First Steps

The first step when developing a vlcj application is to make sure vlcj can find the LibVLC native libraries. These native libraries provide the public API to LibVLC and is what enables you to embed VLC media players in your own applications.

In most cases, vlcj will be able to find the installed native libraries without you needing to do anything in your own code. This will likely be the case when you have VLC installed into the default location on your computer. If so, vlcj will be able to find the native libraries just by using your computer's normal search path.

Nevertheless, the most common problem for new developers when using vlcj is how to properly locate these libraries, and this tutorial will show you how to do just that.

Let's Get Started

Start with a standard Java application:

public class Tutorial {
    public static void main(String[] args) {
    }
}

These is nothing special here.

Option 1 - Automatic Native Discovery

vlcj provides a class that you can use to try and automatically discover the location of the native libraries by searching well-known locations on your computer:

import uk.co.caprica.vlcj.binding.LibVlc;
import uk.co.caprica.vlcj.discovery.NativeDiscovery;

public class Tutorial {

    public static void main(String[] args) {
        boolean found = new NativeDiscovery().discover();
        System.out.println(found);
        System.out.println(LibVlc.INSTANCE.libvlc_get_version());
    }
}

This class instantiates an instance of the NativeDiscovery class and invokes discover() to return a result to show whether or not the native libraries were indeed found.

To check the native libraries, the next line of code writes out the version of LibVLC that was found or alternatively if the native libraries weren't found an exception will be thrown.

For most applications this will just work and you won't have to do anything else.

The NativeDiscovery class can be sub-classed in your application to add more locations to be searched for the native libraries if you want.

If it does not work, you have another option...

Option 2 - Explicit Library Path

If the native discovery does not work, you can explicitly set the library path:

import uk.co.caprica.vlcj.binding.LibVlc;
import uk.co.caprica.vlcj.runtime.RuntimeUtil;

import com.sun.jna.NativeLibrary;

public class Tutorial {

    private static final String NATIVE_LIBRARY_SEARCH_PATH = "/home/vlc";

    public static void main(String[] args) {
        NativeLibrary.addSearchPath(RuntimeUtil.getLibVlcLibraryName(), NATIVE_LIBRARY_SEARCH_PATH);
        System.out.println(LibVlc.INSTANCE.libvlc_get_version());
    }
}

This class uses a hard-coded constant to hold the native library search path, you could of course pass this in to your application as a command-line argument, a Java system property, read it from a properties file or whatever you want.

The RuntimeUtil.getLibVlcLibraryName() code is required because the native libraries are named differenty depending on your operating system.

The directory that you use for the search path must be the directory that contains the libvlc and libvlccore shared objects (shared objects being e.g. the files whose name ends .so on Linux and .dll on Windows).

Summary

This tutorial has shown the two main, and most reliable, ways to help vlcj discover the locations of the LibVLC native libraries.

You may ask why does vlcj not do this automatically? Well, different users will have different ways of configuring their environment and automatically doing native library discovery for every user might not be appropriate, for example it may be the case that multiple different versions of VLC are installed so how would automatic discovery know which one to pick. This is why it is left up to the application developer to choose.

Until you get this working, there is no point trying to do anything else with vlcj!

The rest of these tutorials will assume the automatic native discovery works.