Development Version

vlcj-5 requires VLC 4.0 as a minimum baseline - 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 then switch to the vlcj-4.x branch instead.

vlcj

The vlcj project provides a Java framework to allow an instance of a native VLC media player to be embedded in a Java application.

You get more than just simple bindings, you also get a higher level framework that hides a lot of the complexities of working with LibVLC.

vlcj is primarily developed and therefore extensively tested on Linux - it does also work just fine on Windows and OSX, although there may be some limitations on OSX.

Additionally, whilst not supported as one of the main platforms, this version of vlcj has been tested and shown to be working on contemporary Raspberry Pi builds.

At least JDK 11 is required.

vlcj-4.7.x, which is still current, is the last version of vlcj that was built against JDK 1.6.

vlcj-4.8.x, which is still current, is the first version of vlcj that was built against JDK 11, and is the first to use the Java Module System.

There is an alternative artefact available in the short term to maintain compatibility with Java 1.8, switch to the vlcj-5.x-java8 branch branch, and use the vlcj-java8 artefact name instead of vlcj.

This version of vlcj requires VLC 4.0.0 as a minimum, no earlier version is supported.

This is the open source vlcj project page, see also the 'official' home page where you can find more information as well as some new simple tutorials.

Build Status

Recent News

February 2026 Project status update:

Another year goes by, we're still here, still waiting for VLC 4.x to be released, or waiting for further changes to LibVLC 4.x. Recently not much is changing in the LibVLC API, although some significant changes are expected. It is still unknown when VLC 4.0.0 will be finished and released, this leaves vlcj in a bit of a limbo situation. Right now vlcj 5.x can reliably be used with VLC 4.x nightly builds, but obviously there are risks to using pre-release software.

February 2025 5.0.0-M4 milestone release:

A new development milestone release has been created. You will need an up-to-date nightly build of VLC 4.x to use this.

January 2025 5.0.0-M2 milestone release:

A development milestone release has been created. You will need an up-to-date nightly build of VLC 4.x to use this.

January 2025 Project status update:

We're still here! Small incremental improvements continue to be made, mainly to keep track of the ongoing development of VLC 4.x which even now is still in development and seemingly not close to being completed. We also refreshed the vlcj-examples project, everything (well, almost?) should work with vlcj-5.x now. The JavaFX demo was updated for vlcj-5.x, as was the LWJGL demo along with a new OpenGL video cube demo.

January 2024 Project status update:

This 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.

May 2022 Supporting the project:

If you would like to help support the continued development of vlcj and our other Open Source efforts, you might like to consider sponsoring the project by becoming a GitHub sponsor or buying us a coffee - look for the "Sponsor this project" links on this page.

Alternatively, a good way to support the project is by purchasing a commercial license for vlcj - some more information is included at the end of this README.

May 2022 Project status update:

vlcj is still tracking the development process of VLC/LibVLC 4.0.0 - there are some small changes made recently to LibVLC, but nothing major, no new API. There is still no end in sight to the first VLC 4.x release. Aside from LibVLC there are still some small improvements being made to vlcj, check the project issues for details.

vlcj-5.0.0-SNAPSHOT currently has feature parity with the in-development LibVLC 4.0.0 - we're basically waiting for VLC 4.0 final to be released, or for any new native API to be added to be added to LibVLC.

If you have a stable pre-release build of VLC 4.0.0 you should be fine to use the current vlcj-5.0.0-SNAPSHOT version.

But as of right now, there's nothing much more to be done on vlcj until the next major version of VLC is released - and that is likely yet to be quite some time away.

Future 2022 Next major release

vlcj 5.0.0 release, significant changes for LibVLC 4.0.0, minimum Java version now Java 11 LTS.

All releases are at available at Maven Central.

You can follow @capricasoftware on Twitter for more vlcj news.

Backwards-Incompatible API changes

Changes that break backwards compatibility with prior vlcj versions were avoided if at all possible. However, some such changes are needed in the case where the underlying native LibVLC API changed.

Swing/AWT, JavaFX, OpenGL

Core vlcj embeds native media players in Swing/AWT applications. This has been the foundation of vlcj since the earliest versions. This is still fully supported and still works well, in fact it is still likely the most performant solution.

However, recent versions of JavaFX introduced the PixelBuffer component, providing direct access to a shared native memory buffer that can be used by vlcj/LibVLC as a "callback" video buffer. This performs really well. even when using multiple concurrent video players.

Another factor to consider here is that contemporary macOS does not support AWT at all, so JavaFX is a very good option on that platform.

For more information see the vlcj-javafx and vlcj-javafx-demo projects.

A further possibility with this "callback" approach to video rendering is that with vlcj-5.x and VLC 4.x it becomes very easy to embed a media player in an OpenGL application. This should give very good playback performance, possibly right on a par with the embedded approach, but it would mean foremost developing an OpenGL application.

For more information see the vlcj-lwjgl-demo project.

The beauty of vlcj's design and architecture means adopting any of these approaches is near identical in usage, only a single video surface abstraction is the difference.

vlcj-5

vlcj-5 is primarily an incremental feature-release, preserving the vlcj-4 API as much as possible.

Major New Features

Headline changes:

• requires LibVLC 4.0.0+
• requires Java 11+
• full support for LibVLC native "video engine" rendering, specifically via OpenGL
  • example using LWJGL at vlcj-lwjgl-demo
• fast vs precise native seeking when setting media position/time
• native generation of in-memory thumbnail pictures
• new native track selection API - this makes it possible to reliably make use of video Sample Aspect Ratio (SAR) when rendering video using the "callback" video players and means e.g. DVD video now can render properly with callback players

For a full list of changes in this release, check the release milestones:

• vlcj 5.0.0 release milestone

Examples

All of the examples have been moved to the vlcj-examples project.

Known Issues

• When using the new alternate renderer API, if you attempt to play another media while a media is already being sent to something like Chromecast you may experience problems - even if you stop the current media first. The cause of this is currently unknown, but it may be a native issue.

Tutorials

New tutorials for vlcj-4 are available here.

These tutorials are still valid for vlcj-5.

There are simple tests or demo applications available for pretty much every aspect of vlcj functionality, these are provided in the vlcj-examples project.

There is also a major demo application available at the vlcj-player project page.

Building vlcj - sun.misc.Unsafe

When compiling with Maven it is simply not possible to suppress the warnings about using sun.misc.Unsafe.

Maven Dependency

Add the following Maven dependency to your own project pom.xml:

<dependency>
    <groupId>uk.co.caprica</groupId>
    <artifactId>vlcj</artifactId>
    <version>5.0.0</version>
</dependency>

The core vlcj project now no longer contains the required JNA bindings to LibVLC, these are provided instead by the separate vlcj-natives project. The vlcj core project therefore has a new required dependency on the vlcj-natives project.

If you are using Maven (or similar