Introduction

The vlcj project is an Open Source project that provides Java bindings and an application framework for the excellent VLC media player from VideoLAN.

The bindings can be used to build media player client and server software using Java - everything from simply playing local media files to a full-blown video-on-demand streaming server is possible.

vlcj is being used in diverse applications, helping to provide video capabilities to software in use on oceanographic research vessels and bespoke IPTV and home cinema solutions.

vlcj is also being used to create software for an Open Source video camera at Elphel and video mapping for the Open Street Map project.

Why?

Support for playing media, especially video media, is generally poor on the Java platform. The Java Media Framework can be used to play some media, but it seems to be a neglected framework and has not been updated to play media encoded with modern codecs. JavaFX also provides the ability to play some media, but not all.

In addition to playing media it is often desirable to be able to publish and consume streams of media across the network or the Internet and this too is not well supported by existing Java frameworks.

For these reasons, the usual solution is to use a native media framework and bind to it using native libraries by using the Java Native Interface (JNI), or the Java Native API (JNA) to simplify JNI.

There are a number of different native media players that could be used in this way, two such widely used media players are VLC and mplayer. The vlcj project was created to integrate VLC into Java applications.

VLC

The VLC media player is an extremely popular cross-platform media player available for Linux, macOS and Windows. It differs from most other media players in that it comes bundled with codecs to play almost any type of media and does not make use of external Operating System codecs. In addition to playing just about any type of media, extensive support is provided by VLC to facilitate streaming of media across networks and transcoding of media.

The VLC media player can play (and publish) local media files, local network streams, streams across the Internet, DVD, BluRay, web-cams, digital video and so on. In short VLC can play and stream just about anything.

Whilst VLC is a cross-platform media player, it is compiled to native code for each platform and is not directly usable by Java. A native application programming interface (API) is provided by VLC. The native API is called "LibVLC" and is included with the VLC media player. A layer of Java code is required to interact with the native code and this is precisely what vlcj does.

What does vlcj provide?

The vlcj project first gives you Java bindings to just about all of the native functionality provided through LibVLC, but you also get much more than that...

The vlcj project also gives you a framework that provides a simpler higher-level programming model for LibVLC - encapsulating as much as possible of the access to the native library, and encapsulating any platform-specific behaviours.

The vlcj framework also protects you as much as possible from incorrect usage of the native library which might lead to dead-locks or fatal application crashes.

For example vlcj completely encapsulates handling of asynchronous native media player events by transparently registering callbacks for them and dispatching them in a serial manner via the more familiar Java standard listener pattern. Incorrect handling of events can also cause deadlocks, vlcj knows about this, handles this, and provides a programming model such that your own application can not suffer from such problems.

The vlcj project is now mature, and provides access to most of the features provided by LibVLC. It is now possible with vlcj to build advanced Java multi-media applications that can play almost any type of media, can consume media streams across a local network or the Internet, can publish media in server applications such as a web-radio station or video-on-demand.

What can vlcj be used for?

It is possible to use vlcj to build applications using various user-interface toolkits, including Swing, AWT, SWT, JavaFX and OpenGL.

Just about any type of media player application can be created by using vlcj:

Rich-client video/audio player (like the VLC application) seamlessly embedded inside a Java application (e.g. a home cinema application);
Embed video in Swing, SWT, JavaFX, OpenGL, JMonkeyEngine applications;
Embed video in Eclipse/Netbeans Rich Client Platform applications;
Internet radio player;
YouTube player;
Transcoder;
Network streaming server (e.g. a network radio station or a video on demand server);
Network streaming client;
Video/audio applet (or JNLP application) embedded inside a web page;
Webcam or other camera monitor (e.g. CCTV application);
...and so on...

Since vlcj is embedding VLC, then vlcj can play anything that VLC can play.

What is the license?

vlcj is distributed according to the terms of the GPL license.

If you want to distribute vlcj with your own product without the conditions of the GPL license, then you may like to consider purchasing a commercial license - please use the contact details below (at the bottom of this page) for more information.

vlcj-4 vs vlcj-3

There are two major versions of vlcj.

vlcj-3 is designed for use with VLC 2.2.x and is mostly compatible with VLC 3.x.

vlcj-4 has a new API and supports VLC 3.x and later only. vlcj-4 is not a drop-in replacement for vlcj-3, if you want to use vlcj-4 with your existing projects, some rework will be required due to the API changes.

Where do I get vlcj?

The vlcj project is available at GitHub.

vlcj is available from Maven Central, for vlcj-4 use:

pom.xml

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

For vlcj-3 use:

pom.xml

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

You can also get everything you need, including sources and Javadoc, by downloading a vlcj distribution package, for vlcj-4:

For vlcj-3:

Using vlcj?

If you are using vlcj in your own project or product we would love to hear about it.

Please feel free to tell us via email at the "contact us" link.

More Information

Some new vlcj-4 tutorials and vlcj-3 tutorials are available.

vlcj-player

The vlcj-player project at GitHub is a feature-rich application built using vlcj. It is intended be a comprehensive reference application to demonstrate how to properly build media player applications using vlcj. As such, full source code is available for you to study.

Javadoc

Full Javadoc is also available:

Support / Forum

Please post issues at the GitHub project page.

You can also post questions at Stackoverflow with the vlcj tag.

JavaFX

vlcj works really nicely with the new PixelBuffer that was included with JavaFX 13.

See vlcj-javafx, and vlcj-javafx-demo at GitHub.

Also a short video clip showing a JavaFX concept application built with the upcoming vlcj-5 and LibVLC 4.0 (both of which are still currently in development):

Even multiple concurrent video players is possible, depending on available CPU/GPU resources:

A basic picture-in-picture concept:

Two Minute Demo Challenge

A quick demo video showing the creation of a media player application in Java using vlcj.

It would have been quicker but sometimes you have to fight unhelpful code-completion and poups, and Eclipse.