Caprica Software

vlcj 4.x Tutorial

My First Media Player

This tutorial will show you how to build a media player application using very few lines of vlcj code...

Let's Get Started

Start by creating a completely standard Swing application:

Tutorial.java
import javax.swing.JFrame;
import javax.swing.SwingUtilities;

public class Tutorial {

    private final Tutorial thisApp;

    private final JFrame frame;

    public static void main(String[] args) {
        thisApp = new Tutorial();
    }

    public Tutorial() {
        frame = new JFrame("My First Media Player");
        frame.setBounds(100, 100, 600, 400);
        frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
        frame.setVisible(true);
    }
}

There is nothing particularly special about this code so far, it is all pretty much standard.

If you run this application now you will see an empty frame, and that's about it.

Add a Media Player Component

vlcj provides a different ways to create a media player, the simplest is to use an instance of an EmbeddedMediaPlayerComponent.

Tutorial.java
import javax.swing.JFrame;
import javax.swing.SwingUtilities;

import uk.co.caprica.vlcj.component.EmbeddedMediaPlayerComponent;

public class Tutorial {

    private final Tutorial thisApp;

    private final JFrame frame;

    private final EmbeddedMediaPlayerComponent mediaPlayerComponent;

    public static void main(String[] args) {
        thisApp = new Tutorial();
    }

    public Tutorial() {
        frame = new JFrame("My First Media Player");
        frame.setBounds(100, 100, 600, 400);
        frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
        mediaPlayerComponent = new EmbeddedMediaPlayerComponent(); 
        frame.setContentPane(mediaPlayerComponent); 
        frame.setVisible(true);
    }
}

With the few lines of new code we have added here we get a media player component fully ready to use. The EmbeddedMediaPlayerComponent is a visual component that can be added directly to a user interface. In this tutorial we set the media player component directly as the content pane of the application frame, we could instead add it to a JPanel or include it as part of a more elaborate layout.

If you run this application now you should no longer see an empty grey frame - you'll see that the frame now contains a media player component (well, all you'll see is that the background changed from grey to black, but the black background is the video surface of the media player component you just added).

Play Something

We'll now assume that your application accepts the name of a media file to play via a command-line argument:

Tutorial.java
import javax.swing.JFrame;
import javax.swing.SwingUtilities;

import uk.co.caprica.vlcj.component.EmbeddedMediaPlayerComponent;

public class Tutorial {

    private final Tutorial thisApp;

    private final JFrame frame;

    private final EmbeddedMediaPlayerComponent mediaPlayerComponent;

    public static void main(String[] args) {
        thisApp = new Tutorial(args); 
    }

    public Tutorial(String[] args) { 
        frame = new JFrame("My First Media Player");
        frame.setBounds(100, 100, 600, 400);
        frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
        mediaPlayerComponent = new EmbeddedMediaPlayerComponent();
        frame.setContentPane(mediaPlayerComponent);
        frame.setVisible(true);
        mediaPlayerComponent.mediaPlayer().media().play(args[0]); 
    }
}

We've taken some liberties by leaving out argument checking and error handling, but by adding only one more line of vlcj code, we have a working media player.

Pretty impressive!

Cleaning Up

This simple application works just fine, but to help prevent native resource leaks it is a good idea to explicitly release the media player component when your application exits. To do this, we don't let the application exit directly when the close button on the frame is pressed. Instead, we use a WindowListener to intercept the close event and perform our clean-up:

Tutorial.java
import javax.swing.JFrame;
import javax.swing.SwingUtilities;

import uk.co.caprica.vlcj.component.EmbeddedMediaPlayerComponent;

public class Tutorial {

    private final Tutorial thisApp;

    private final JFrame frame;

    private final EmbeddedMediaPlayerComponent mediaPlayerComponent;

    public static void main(String[] args) {
        thisApp = new Tutorial(args);
    }

    public Tutorial(String[] args) {
        frame = new JFrame("My First Media Player");
        frame.setBounds(100, 100, 600, 400);
        frame.setDefaultCloseOperation(JFrame.DO_NOTHING_ON_CLOSE); // FIXME this is wrong in current tutorials also need to actually run this code to make sure // mark
        frame.addWindowListener(new WindowAdapter() {
            @Override
            public void windowClosing(WindowEvent e) {
                mediaPlayerComponent.release(); 
                System.exit(0);
            }
        });
        mediaPlayerComponent = new EmbeddedMediaPlayerComponent();
        frame.setContentPane(mediaPlayerComponent);
        frame.setVisible(true);
        mediaPlayerComponent.mediaPlayer().media().play(args[0]);
    }
}

We changed two things here. The first is we use DO_NOTHING_ON_CLOSE instead of EXIT_ON_CLOSE; the second is to add a new window listener that invokes mediaPlayerComponent.release() to release the media player component and associated native resources, before exiting the application.

Summary

This tutorial has shown how to embed a native media player in a Java application with very few lines of code. This is now the basic template for all vlcj applications.

What's left really is to hook up user interface controls like buttons, menus or keyboard short-cuts to invoke various media player operations, and to listen for and handle media player events.

How you do this is up to you, it depends on the type of application you're building.

The next tutorial shows you the basics of adding controls.