Options & Arguments

VLC provides many modules and filters that can be used to enable advanced media player functionality - this includes things like selecting specific audio and video outputs, rotating the video and so on.

LibVLC, and consequently vlcj, does not have a public API for all of these modules but you can still use them with vlcj by using a combination of: arguments when you create a MediaPlayerFactory, and; media options when you invoke playMedia on a MediaPlayer.

Media Player Factory Arguments

In general, anything that enables/disables VLC modules and filters must be set via the MediaPlayerFactory.

Pretty much every other VLC option can be set via the factory, but it is not always desirable to do so and so you can consider using media options when you play your media.

There are a number of ways you can configure the factory to your liking, but in all cases the arguments supplied are the same - one or more String values.

If you create your own factory, you can pass an array of strings (using an array or a variable length argument) or a list of strings, for example:

String[] options = {option1, option2, option3};
MediaPlayerFactory factory = new MediaPlayerFactory(options);

If you use the media player component framework provided by vlcj, rather than creating the factory directly yourself, you have several ways to configure the factory.

You can provide your own factory implementation by overriding a template method in the component:

EmbeddedMediaPlayerComponent mediaPlayer = new EmbeddedMediaPlayerComponent() {
    @Override
    protected MediaPlayerFactory onGetMediaPlayerFactory() {
        String[] options = {option1, option2, option3};
        MediaPlayerFactory factory = new MediaPlayerFactory(options);
    }
};

You can use the default factory provided by the component, but provide your own factory arguments (this will replace any default configuration arguments set by the component):

EmbeddedMediaPlayerComponent mediaPlayer = new EmbeddedMediaPlayerComponent() {
    @Override
    protected String[] onGetMediaPlayerFactoryArgs() {
        String[] options = {option1, option2, option3};
        return options;
    }
};

You can use the default factory provided by the component, but provide your own additional factory arguments (preserving any default configuration arguments set by the component):

EmbeddedMediaPlayerComponent mediaPlayer = new EmbeddedMediaPlayerComponent() {
    @Override
    protected String[] onGetMediaPlayerFactoryExtraArgs() {
        String[] options = {option1, option2, option3};
        return options;
    }
};

Media Options

The playMedia method on a MediaPlayer takes an optional options parameter.

There are other additional methods, like startMedia, that can be used with options in the same manner. It is also possible to use setStandardMediaOptions to set options that will be applied each time to any media that is played by your media player.

These options can be generally used to provide configuration values to one or more of VLC's modules/filters.

Any options specified here that deal with enabling/disabling of VLC modules/filters will generally by ineffective here and must instead be set by the factory.

When playing media:

String[] options = {option1, option2, option3};
mediaPlayer.playMedia(mrl, options);

Setting standard options to use for all media:

String[] options = {option1, option2, option3};
mediaPlayer.setStandardMediaOptions(options);
// ... some time later...
mediaPlayer.playMedia(mrl);

Option/Argument Values

The available settings for factory arguments and media options can be found by invoking VLC from the comamnd-line:

vlc -H

Using the rotate filter as an example VLC tells us:

Rotate video filter (rotate)
--rotate-angle <float [-340282346638528859811704183484516925440 .. 340282346638528859811704183484516925440]>
                           Angle in degrees

Leaving aside the strange parameter value range, to use this module with vlcj you would start by enabling the rotate module via the factory:

MediaPlayerFactory factory = new MediaPlayerFactory("--video-filter", "rotate");
EmbeddedMediaPlayer mediaPlayer = factory.newEmbeddedMediaPlayer();

Then when you play media, set the desired rotation angle:

mediaPlayer.playMedia(mrl, "--rotate-angle", "30");

Note that with this particular example, you could have also set the rotation angle via the factory - but doing it instead via a media option gives you the choice to set a different angle each time you play media.

Alternate Syntax

Previously we described the syntax for options and arguments as:

mediaPlayer.playMedia(mrl, "--rotate-angle", "30");

If you like you can use an alternate syntax, the equivalent of the above being:

mediaPlayer.playMedia(mrl, "--rotate-angle=30");

Yet Another Alternate Syntax

If neither of the previous syntaxes works, and especially for media options when playing media, there is another syntax with a colon prefix:

mediaPlayer.media().play(mrl, ":start-time=30.5", ":run-time=10");

This example will play the media starting at 30.5 seconds, and run for 10 seconds before stopping.

When to use Options vs Arguments

It is not always straightforward to know which of VLC's many options can be set via the factory or by the media options when playing media.

We have already mentioned the general case of arguments that are used to enable/disable modules/filters and how these must be set via the factory.

Usually, setting arguments by the factory will always have an effect so you may never have a need to use anything else.

However, you may like to enable a particular video filter once via the factory (for example the "rotate" filter) but have each video you play rotated with different parameters. In this case it makes sense to pass the rotation value itself when you play the media - if you had set this rotation value via the factory you would be stuck with one value for all media.

The other general rule is that if you try and use media options when you play the media and it does not work, try via the factory instead.

Caprica Software