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 play 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 you can provide your own factory implementation when constructing the component:

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

Media Options

The play method on a MediaPlayer (via MediaApi) takes an optional options parameter.

There are other additional methods, prepare or start, that can be used with options in the same manner.

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.media().play(mrl, options);

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.media().play(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.

If you try this example with the rotate filter, the code fragment and arguments shown are correct, but VLC may not rotate your video if it is mp4 as this seems to be currently unsupported.

Alternate Syntax

Previously we described the syntax for options and arguments as:

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

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

mediaPlayer.media().play(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.

Alternate Simple Syntax

This simple syntax without any prefix can also work:

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

Why so many different syntaxes? Documentation is sparse and conflicting, some options only seem to work in certain circumstances, what actually works only is known with empirical testing.

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.