Skip to content
Projekte

caprica/vlcj has 1,244 GitHub stars and 262 forks. GitHot measured 0 stars in 24 hours, 0 in 7 days, and 0 in 15 days. Last checked 2026-11-21 00:32 UTC. Last push 2026-10-14.

So werden diese Zahlen gemessen

What you can do

  • requires LibVLC 4.0.0+
  • requires Java 21+
  • example using LWJGL at vlcj-lwjgl-demo
  • fast vs precise native seeking when setting media position/time

Gemessener Sternzuwachs

in 24h
0
in 7 days
0
in 15 days
0
in 1 month
Verlauf wird gesammelt

Nettoänderungen in überlappenden Zeiträumen, keine Tagessummen. Fehlende Messwerte bleiben leer. Sterne zeigen Interesse, nicht Qualität.

Über uns

Java framework for the vlc media player

Entwicklerwerkzeuge

README.md

Original

vlcj

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 21 is required.

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.

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

Continuous Integration

Maven Central

Recent News

October 2026 new commercial licensing:

We have simplified and streamlined our commercial license purchase process, it is now entirely self-service and hosted by Stripe. Purchasing a commercial license is the best way to support the ongoing development and maintenance of the project.

We have a very favourable offer with huge discounts and without subsription for freelancers and small businesses.

See Commercial Licenses

October 2026 5.0.0-M6 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. With this release, there are unavoidable breaking API changes. This is because LibVLC has had its own major breaking changes, a complete replacement of the event model, a refactoring of media list players, new media parsing, new media discoverer, new renderer discoverer, the list goes on.

This is likely NOT going to be a drop-in update, you will probably need to make some changes to your own code to use this update, and if you relied previously on (Embedded)MediaPlayer subitems you will instead need to work with an (Embedded)MediaListPlayer.

Some listener events have changed or been removed.

Times, offsets, durations etc, are all microseconds now, a change from milliseconds before.

All vlcj API is still subject to change.

Septemeber 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 significant changes to LibVLC 4.x have been made, and these changes are backwardly incompatible. Work is underway currently to integrate these new native library changes, but there is significant upheaval.

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 21 LTS.

All releases are at available at Maven Central.

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

Backwards-Incompatible API changes

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.

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 major development update, incorporating new features and native library changes.

Major New Features

Headline changes:

  • requires LibVLC 4.0.0+
  • requires Java 21+
  • full support for LibVLC native "video engine" rendering, specifically via OpenGL
  • 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
  • new smooth time/position update events using interpolation and jitter correction, see TimeApi on MediaPlayer and WatchTimeListener
  • new media parser
  • changes to media discoverers and renderer discoverers

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

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

Tutorials for vlcj-4 are available here.

These tutorials are mostly still valid for vlcj-5, but some things now may be obsolete.

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) to manage your dependencies, the vlcj-natives dependency will be handled automatically for you (you only need to explicitly add vlcj to your project, not vlcj-natives).

If you are installing vlcj manually, then you will need to include the new vlcj-natives jar file along with the existing vlcj jar file.

Threading Model

This section is very important.

With vlcj-4 and later, every native event coming from LibVLC is processed on the native callback thread. This should give some small performance gains when compared with vlcj-3.

The critical issue is that it is generally not permitted to call back into LibVLC from the event callback thread. Doing so may cause subtle failures or outright hard JVM crashes.

A prime example of the sort of trap waiting for you is the very common case of handling a media player "finished" event so that you can then play the next item in a play-list:

mediaPlayer.events().addMediaPlayerEventListener(new MediaPlayerEventAdapter() {
    @Override
    public void finished(MediaPlayer mediaPlayer) {
        mediaPlayer.media().play(nextMrl); // <-- This is VERY BAD INDEED
    }
});

In this example, the finished method is being invoked on a native callback thread owned by LibVLC. The implementation of this method is calling back into LibVLC when it invokes play. This is very likely to cause a JVM crash and kill your application.

In cases such as this, you should make use of an asynchronous task-executor queue conveniently provided by the MediaPlayer object passed to the listener method:

mediaPlayer.events().addMediaPlayerEventListener(new MediaPlayerEventAdapter() {
    @Override
    public void finished(final MediaPlayer mediaPlayer) {
        mediaPlayer.submit(new Runnable() {
            @Override
            public void run() {
                mediaPlayer.media().play(nextMrl);
            }
        });
    }
});

You should not use this mechanism for all of your event handlers, only those that will call back into LibVLC.

Other high-level vlcj components may also provide their own asynchronous task executor, it is not limited to the media player.

An added caveat for vlcj-4 and later is that when you implement event handling you must be sure to execute quickly, and to not block the native thread with any long-running operation.

Your event handler implementations must not throw an Exception, failure of your event handlers to catch and handle any thrown exception may prevent other listeners from being notified of the event.

If you are attempting to use multiple media players in your application, or using media players from multiple threads, you may need to take some extra care so that you do not have multiple threads calling into LibVLC concurrently. You may encounter subtle bugs and races that are very difficult to diagnose.

In addition, you must take care not to update Swing UI components from the native thread - all Swing UI updates are supposed to go via the Swing Event Dispatch Thread (EDT).

You can achieve this in the usual way by using SwingUtilities#invokeLater in your event handler:

mediaPlayer.events().addMediaPlayerEventListener(new MediaPlayerEventAdapter() {
    @Override
    public void finished(MediaPlayer mediaPlayer) {
        SwingUtilities.invokeLater(new Runnable() {
            @Override
            public void run() {
                // ...change UI state here...
            }
        });
    }
});

Garbage Collection

This section is also very important.

Ordinarily when developing with Java you will be used to not thinking about the scope and life-cycle of the objects that you create, instead you will rely on the garbage collector in the Java Virtual Machine to just take care of things for you.

With vlcj's MediaPlayerFactory, MediaPlayer, and associated classes, you must take care to prevent those objects from being garbage collected - if you do not, at best your media player will simply unexpectedly stop working and at worst you may see a fatal JVM crash.

Those vlcj objects wrap a native resource (e.g. a native media player). Those media player resources know nothing about any JVM. So just because a native media player is still "alive" it will not prevent your object instance from being garbage collected. If your object instance does get garbage collected, the native resource still has no idea, and will will keeping sending native events back to the JVM via a callback. If your object is gone, that native callback has nowhere to go and will most likely crash your JVM.

A very common mistake is to declare vlcj objects on the local heap in some sort of initialisation method:

    private void setup() {
        MediaPlayerFactory factory = new MediaPlayerFactory();
        EmbeddedMediaPlayer mediaPlayer = factory.mediaPlayers().newEmbeddedMediaPlayer();
        // ... other initialisation ...
    }

When this method returns, the factory and mediaPlayer objects go out of scope and become eligible for garbage collection. The garbage collection may happen immediately, or some time later.

The most common solution is to change those local heap declarations to class fields:

    private MediaPlayerFactory factory;

    private EmbeddedMediaPlayer mediaPlayer;

    private void setup() {
        factory = new MediaPlayerFactory();
        mediaPlayer = factory.mediaPlayers().newEmbeddedMediaPlayer();
        // ... other initialisation ...
    }

This is fine and will work in most cases, but you must still make sure that the enclosing class does not itself get garbage collected!

See this vlcj garbage collection tutorial for more information.

Privacy Considerations

When parsing media, depending on configuration, it may be possible that a remote network access is made for meta data and album/cover art. This may unintentionally expose sensitive data regarding the media being parsed.

To affirmatively prevent all network access for meta data, consider using the --no-metadata-network-access argument when creating a MediaPlayerFactory.

It should also be possible to prevent such network accesses by using appropriate MediaParseFlags values when requesting to parse media.

Even with network access disabled, some media cover art may still appear locally (e.g. ~/.cache/vlc) - this does not necessarily mean that a remote network request was made for the cover art, rather the art that was already embedded in the media file was extracted to this temporary cache directory.

In any case, you need to be aware of this issue and inform users of your application about it.

Documentation

The vlcj project page is at github.

Online Javadoc is available at javadoc.io.

Examples

There are many examples in the vlcj-examples project showing how to use vlcj.

For a more complete example of a feature-rich media player built with vlcj, see vlcj-player.

Related Projects

Support

Free support for Open Source and non-commercial projects is generally provided - you can use github issues for this purpose.

Commercial services for vlcj are provided by Caprica Software.

Support for commercial projects is provided exclusively on commercial terms - send an email to the following address for more information:

mark [dot] lee [at] capricasoftware [dot] co [dot] uk

LibVLC Discord

Join the chat at https://discord.gg/3h3K3JF

vlcj is part of the LibVLC Discord Community server. Feel free to come say hi!

License

The vlcj framework is provided under the GPL, version 3 or later.

New for October 2026, we have simplified and streamlined our commercial licensing approach.

The best way to support the project is to purchase a commercial license subscription.

We now accept commercial license purchases via Stripe, it is completely self-service and accepts any method of payment that Stripe accepts.

See Commercial Licenses

Contributors

Contributions are welcome and will always be licensed according to the Open Source license terms of the project (currently GPL).

However, for a contribution to be accepted you must agree to transfer any copyright so that your contribution does not impede our ability to provide commercial licenses for vlcj.