vlcj embeds native VLC in Java, but version 5 waits on an unreleased VLC 4.0

A Java layer over a native player, not a set of thin bindings

vlcj exists to put a native VLC media player inside a Java application. The project description says it plainly: it provides a Java framework to allow an instance of a native VLC media player to be embedded in a Java application. The native part is LibVLC, the C library that ships inside VLC itself, and the framing is important, because the value is not in calling into C from Java, it is in not having to.

The README draws the line between the two things you get. More than simple bindings, it also provides a higher level framework that hides a lot of the complexities of working with LibVLC. In practice that means the event model, the media and player lifecycles, and the type conversions between native handles and Java objects are handled for you, rather than left as a raw callback-and-handle exercise for every application team.

The platform story is uneven by design. vlcj is primarily developed and therefore extensively tested on Linux. It also works on Windows and macOS, although there may be some limitations on macOS, and the project states plainly which platform it prefers rather than claiming parity. Separately, and explicitly not as one of the main platforms, this version has been tested and shown to be working on contemporary Raspberry Pi builds. For a reader choosing a platform, that ordering is the most useful sentence in the README: Linux is where the testing effort is.

The repository is a conventional Maven project with a pom.xml at the root and sources under src/, plus doc/ and etc/ directories.

Version 5 needs VLC 4.0, which VideoLAN has not released

This is the central fact about the project right now, and it decides which branch you use. The development version, vlcj-5, requires VLC 4.0 as a minimum baseline, and the README is explicit that VLC 4.0 is currently in development and it may be some time before it is released. If you are looking for a stable combination of vlcj and VLC, the instruction is to switch to the vlcj-4.x branch instead.

The news section shows how long that has been true. The September 2026 status update says another year goes by, they are still there, still waiting for VLC 4.x to be released or for further changes to LibVLC 4.x, and that recently significant changes to LibVLC 4.x have been made which are backwardly incompatible. Work was under way to integrate these new native library changes, but with significant upheaval.

The January 2024 update is more candid about the effect on the project itself. It says the project is still actively maintained and supported, but activity has been less recently, because the main driver for the next release and the blocker for releasing something new is the ongoing development of VLC 4.x, which is still seemingly not close to being completed. The January 2025 update says much the same, with small incremental improvements mainly to keep track of the ongoing development of VLC 4.x.

So the pattern is consistent across three years of status notes. The work is not stalled, but the release of a new major version is gated on an upstream native library that has not shipped. That is a dependency risk, not a project risk, and it is worth understanding before you plan around the 5.x API.

5.0.0-M6 rewrote the event model and switched the clock to microseconds

The October 2026 milestone release is the clearest picture of what a LibVLC 4.x upgrade costs you, and the description is unsparing. To use it you need an up-to-date nightly build of VLC 4.x. The release notes list unavoidable breaking API changes, and the cause is upstream: LibVLC has had its own major breaking changes, a complete replacement of the event model, a refactoring of media list players, new media parsing, a new media discoverer and a new renderer discoverer.

Two consequences land directly in your code. The first is the player type. If you previously relied on MediaPlayer subitems, you now work with MediaListPlayer instead, and the same substitution applies to the embedded variants. The second is time. Times, offsets and durations are all microseconds now, a change from milliseconds before. Any code that treated those values as milliseconds, or formatted a timestamp on that assumption, is now wrong by a factor of a thousand, and the failure is silent because the number still looks plausible.

Listener events have also changed or been removed, which is the hardest category of breakage to absorb, because the removal is a compile error at best and a listener that never fires at worst. The release notes are blunt about the consequence: this is likely not going to be a drop-in update, you will probably need to make some changes to your own code, and all vlcj API is still subject to change.

The stable line avoids all of this. vlcj-4.8.x, which the README calls still current, is the first version built against JDK 11 and the first to use the Java Module System, and it is the branch to pick if you want a released combination rather than a moving target.

Picking a branch and pulling the artifacts from Maven Central

There is no GitHub release for this project, so Maven Central is where the artifacts live. The README states that all releases are available at Maven Central, and the Maven Central badge points at the group id uk.co.caprica and the artifact id vlcj, which is what a build tool needs to resolve. For a production project you would resolve the 4.x artifact instead, since the README directs stable users to the vlcj-4.x branch.

If you would rather read or build the sources, the repository is on GitHub with a vlcj-4.x branch alongside the default master branch, which is where the 5.x development line lives. The project links the stable branch directly.

https://github.com/caprica/vlcj/tree/vlcj-4.x

To get to that state you clone the repository, change into it and check out the vlcj-4.x branch, which gives you the last stable combination of the framework and a released VLC. To follow the 5.x development line instead you stay on the master branch, and to move between the two you switch branches in the clone you already have. The build itself is a standard Maven project, and the CI badge shows a Java CI with Maven workflow running against the repository, so the same Maven build the workflow runs is what you would run locally.

On the Java side, the development version requires at least JDK 21, and the README's future notes for the 5.0.0 release state that the minimum Java version is Java 21 LTS. The 4.8.x line is the one built against JDK 11, and it is also the first to use the Java Module System, which matters if you are assembling a modular application and do not want the framework on the classpath.

Swing and AWT are the base, JavaFX and OpenGL are the extras

The rendering side of the project has a clear hierarchy. Core vlcj embeds native media players in Swing and AWT applications, and the README calls this the foundation of vlcj since the earliest versions, adding that it is still fully supported. The section covering Swing and AWT, JavaFX and OpenGL is presented as three supported paths rather than one default.

JavaFX and OpenGL matter for different reasons. The JavaFX route gives you a scene-graph-based surface rather than an AWT component, and the OpenGL route renders the video through a texture pipeline. The examples project shows both, and the January 2025 status note says the examples were refreshed so that almost everything should work with vlcj-5.x, that the JavaFX demo was updated for vlcj-5.x, as was the LWJGL demo, along with a new OpenGL video cube demo. The OpenGL video cube is the interesting one, since it implies you can place the video surface in a 3D scene rather than only in a flat panel.

The examples are also where you should look before writing code. A separate vlcj-examples project exists to demonstrate the techniques, and the README points to the official home page for additional tutorials, including some new simple ones.

The trade-off with a native-backed approach is worth naming explicitly. Every one of these surfaces renders native video into a Java toolkit, which means the usual Java deployment concerns apply to video playback, such as headless environments, and it means the application ships a dependency on the native VLC libraries for the target platform.

GPL-3.0, plus a commercial licence that now runs through Stripe

The repository is licensed GPL-3.0. That is the licence of the open source project itself, and it carries the usual copyleft obligations if you redistribute modified versions, including the requirement to keep the licence text and to publish the source of derivatives. That is a licensing fact rather than legal advice, and for an application that embeds a GPL library it is a decision that belongs with your legal team.

Alongside it there is a commercial licensing path, and it changed in October 2026. The announcement says the commercial licence purchase process has been simplified and streamlined, that it is now entirely self-service and hosted by Stripe, and that purchasing a commercial licence is described as the best way to support the ongoing development and maintenance of the project. There is also an offer with large discounts and without subscription for freelancers and small businesses. The commercial licences are sold from the Caprica Software site, and the project also accepts GitHub sponsorship.

The licensing choice is not the only decision. The other one is which branch you take, and the README's warning on that point deserves to be quoted in substance: no promises are made on backwards compatibility with earlier versions of vlcj. The vast majority of the API is unchanged, but there are unavoidable breakages needed to adapt to changes in the native LibVLC library. In other words, the compatibility surface you can rely on is the one your chosen VLC version offers, not the one vlcj happened to publish last year.

Editorial conclusion

vlcj fits a Java team that needs real video playback with hardware decoding inside an existing application and is prepared to track a native library whose API is still moving, and it fits them best today on the vlcj-4.x branch against a released VLC. It does not fit a team that needs a frozen API, since the README makes no promises about backwards compatibility and the 5.0.0-M6 milestone changes the event model, the player types and the time units at once. Before committing, decide which branch you will pin, confirm the VLC version on your target machines matches the LibVLC baseline that branch expects, and read the microsecond change before you start interpreting any timing value from a listener callback.

Frequently asked questions

Official sources

1. caprica/vlcj on GitHub
2. Issues
3. License: GPL-3.0
4. Project website
5. README