uk.co.caprica.vlcj.player

Class MediaPlayerFactory

java.lang.Object

uk.co.caprica.vlcj.player.MediaPlayerFactory

public class MediaPlayerFactory
extends Object

Factory for media player instances.

The factory initialises a single libvlc instance and uses that to create media player instances.

If required, you can create multiple factory instances each with their own libvlc options.

You should release the factory when your application terminates to properly clean up native resources.

The factory also provides access to the native libvlc Logger and other resources such as the list of audio outputs, and the list of available audio and video filters.

Usage:

   // Set some options for libvlc
   String[] libvlcArgs = {...add options here...};

   // Create a factory instance (once), you can keep a reference to this
   MediaPlayerFactory mediaPlayerFactory = new MediaPlayerFactory(libvlcArgs);

   // Create a full-screen strategy
   FullScreenStrategy fullScreenStrategy = new DefaultFullScreenStrategy(mainFrame);

   // Create a media player instance
   EmbeddedMediaPlayer mediaPlayer = mediaPlayerFactory.newEmbeddedMediaPlayer(fullScreenStrategy);

   // Do some interesting things with the media player, like setting a video surface...

   ...

   // Release the media player
   mediaPlayer.release();

   // Release the factory
   factory.release();
 

You must make sure you keep a hard reference to the media player (and possibly other) objects created by this factory. If you allow a media player object to go out of scope, then unpredictable behaviour will occur (such as events no longer seeming to fire) even though the video playback continues (since that happens via native code). You may also likely suffer fatal JVM crashes.

It is always a better strategy to reuse media player instances, rather than repeatedly creating and destroying instances.

Constructor Summary

Constructors

Constructor and Description
MediaPlayerFactory() Create a new media player factory.
MediaPlayerFactory(LibVlc libvlc) Create a new media player factory.
MediaPlayerFactory(LibVlc libvlc, List<String> libvlcArgs) Create a new media player factory.
MediaPlayerFactory(LibVlc libvlc, String... libvlcArgs) Create a new media player factory.
MediaPlayerFactory(List<String> libvlcArgs) Create a new media player factory.
MediaPlayerFactory(String... libvlcArgs) Create a new media player factory.

Method Summary

Methods

Modifier and Type	Method and Description
String	changeset() Get the source code change-set id used to build libvlc.
long	clock() Get the time as defined by LibVLC.
String	compiler() Get the compiler used to build libvlc.
List<ModuleDescription>	getAudioFilters() Get the available audio filters.
List<AudioOutput>	getAudioOutputs() Get the available audio outputs.
MediaMeta	getMediaMeta(String mediaPath, boolean parse) Get local media meta data.
List<ModuleDescription>	getVideoFilters() Get the available video filters.
MediaDiscoverer	newAudioMediaDiscoverer() Create a new native audio media service discoverer.
DirectMediaPlayer	newDirectMediaPlayer(BufferFormatCallback bufferFormatCallback, RenderCallback renderCallback) Create a new direct video rendering media player.
DirectMediaPlayer	newDirectMediaPlayer(int width, int height, RenderCallback renderCallback) Deprecated. use newDirectMediaPlayer(BufferFormatCallback, RenderCallback) instead
DirectMediaPlayer	newDirectMediaPlayer(String format, int width, int height, int pitch, RenderCallback renderCallback) Deprecated. use newDirectMediaPlayer(BufferFormatCallback, RenderCallback) instead
EmbeddedMediaPlayer	newEmbeddedMediaPlayer() Create a new embedded media player.
EmbeddedMediaPlayer	newEmbeddedMediaPlayer(FullScreenStrategy fullScreenStrategy) Create a new embedded media player.
HeadlessMediaPlayer	newHeadlessMediaPlayer() Create a new headless media player.
NativeLog	newLog() Create a new native log component.
MediaDiscoverer	newMediaDiscoverer(String name) Create a new native media service discoverer.
MediaList	newMediaList() Create a new media list for a play-list media player.
MediaListPlayer	newMediaListPlayer() Create a new play-list media player.
MediaManager	newMediaManager() Create a new media manager.
MediaDiscoverer	newVideoMediaDiscoverer() Create a new native video media service discoverer.
CanvasVideoSurface	newVideoSurface(Canvas canvas) Create a new video surface for a Canvas.
ComponentIdVideoSurface	newVideoSurface(long componentId) Create a new video surface for a native component id.
void	release() Release the native resources associated with this factory.
void	setUserAgent(String userAgent) Set the application name.
void	setUserAgent(String userAgent, String httpUserAgent) Set the application name.
String	version() Get the libvlc version.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MediaPlayerFactory

public MediaPlayerFactory()

Create a new media player factory.

If you want to enable logging or synchronisation of the native library interface you must use MediaPlayerFactory(LibVlc) and LibVlcFactory.

This factory constructor will enforce a minimum required native library version check - if a suitable native library version is not found a RuntimeException will be thrown.

If you do not want to enforce this version check, use one of the other constructors that accepts a LibVlc instance that you obtain from the LibVlcFactory.

MediaPlayerFactory

public MediaPlayerFactory(String... libvlcArgs)

Create a new media player factory.

If you want to enable logging or synchronisation of the native library interface you must use MediaPlayerFactory(LibVlc) and LibVlcFactory.

This factory constructor will enforce a minimum required native library version check - if a suitable native library version is not found, a RuntimeException will be thrown.

If you do not want to enforce this version check, use one of the other constructors that accepts a LibVlc instance that you obtain from the LibVlcFactory.

Most initialisation arguments may be gleaned by invoking "vlc -H".

Parameters:

libvlcArgs - initialisation arguments to pass to libvlc

MediaPlayerFactory

public MediaPlayerFactory(LibVlc libvlc)

Create a new media player factory.

Use LibVlcFactory to get a reference to the native library.

Parameters:

libvlc - interface to the native library

MediaPlayerFactory

public MediaPlayerFactory(LibVlc libvlc,
                  String... libvlcArgs)

Create a new media player factory.

Use LibVlcFactory to get a reference to the native library.

Parameters:

libvlc - interface to the native library

libvlcArgs - initialisation arguments to pass to libvlc

MediaPlayerFactory

public MediaPlayerFactory(List<String> libvlcArgs)

Create a new media player factory.

This is simply an alternate constructor for convenience, see MediaPlayerFactory(String...).

Parameters:

libvlcArgs - initialisation arguments to pass to libvlc, may be empty but must not be null

MediaPlayerFactory

public MediaPlayerFactory(LibVlc libvlc,
                  List<String> libvlcArgs)

Create a new media player factory.

Use LibVlcFactory to get a reference to the native library.

This is simply an alternate constructor for convenience, see MediaPlayerFactory(LibVlc, String...).

Parameters:

libvlc - interface to the native library

libvlcArgs - initialisation arguments to pass to libvlc, may be empty but must not be null

Method Detail

release

public void release()

Release the native resources associated with this factory.

setUserAgent

public void setUserAgent(String userAgent)

Set the application name.

Parameters:

userAgent - application name

setUserAgent

public void setUserAgent(String userAgent,
                String httpUserAgent)

Set the application name.

Parameters:

userAgent - application name

httpUserAgent - application name for HTTP

getAudioOutputs

public List<AudioOutput> getAudioOutputs()

Get the available audio outputs.

Each audio output has zero or more audio devices, each device having it's own unique identifier that can be used on a media player to set the select the required output device.

Returns:

collection of audio outputs

getAudioFilters

public List<ModuleDescription> getAudioFilters()

Get the available audio filters.

Returns:

collection of audio filter descriptions

Since:

libvlc 2.0.0

getVideoFilters

public List<ModuleDescription> getVideoFilters()

Get the available video filters.

Returns:

collection of video filter descriptions

Since:

libvlc 2.0.0

newEmbeddedMediaPlayer

public EmbeddedMediaPlayer newEmbeddedMediaPlayer()

Create a new embedded media player.

Full-screen will not be available, to enable full-screen support see newEmbeddedMediaPlayer(FullScreenStrategy), or use an alternate mechanism to manually set full-screen if needed.

Returns:

media player instance

newEmbeddedMediaPlayer

public EmbeddedMediaPlayer newEmbeddedMediaPlayer(FullScreenStrategy fullScreenStrategy)

Create a new embedded media player.

Parameters:

fullScreenStrategy - full screen implementation, may be null

Returns:

media player instance

newDirectMediaPlayer

@Deprecated
public DirectMediaPlayer newDirectMediaPlayer(int width,
                                                int height,
                                                RenderCallback renderCallback)

Deprecated. use newDirectMediaPlayer(BufferFormatCallback, RenderCallback) instead

Create a new direct video rendering media player with a pixel format suitable for, amongst other things, rendering into a BufferedImage.

The pixel format used is "RV32" (a raw RGB format with padded alpha) and the pitch is width*4.

Parameters:

width - width for the video

height - height for the video

renderCallback - callback to receive the video frame data

Returns:

direct media player implementation

newDirectMediaPlayer

@Deprecated
public DirectMediaPlayer newDirectMediaPlayer(String format,
                                                int width,
                                                int height,
                                                int pitch,
                                                RenderCallback renderCallback)

Deprecated. use newDirectMediaPlayer(BufferFormatCallback, RenderCallback) instead

Create a new direct video rendering media player.

Parameters:

width - width for the video

height - height for the video

format - pixel format (e.g. RV15, RV16, RV24, RV32, RGBA, YUYV)

pitch - pitch, also known as stride

renderCallback - callback to receive the video frame data

Returns:

media player instance

newDirectMediaPlayer

public DirectMediaPlayer newDirectMediaPlayer(BufferFormatCallback bufferFormatCallback,
                                     RenderCallback renderCallback)

Create a new direct video rendering media player.

Parameters:

bufferFormatCallback - callback to set the desired buffer format

renderCallback - callback to receive the video frame data

Returns:

media player instance

newHeadlessMediaPlayer

public HeadlessMediaPlayer newHeadlessMediaPlayer()

Create a new headless media player.

The head-less player is intended for audio media players or streaming server media players and may spawn a native video player window unless you set proper media options when playing media.

Returns:

media player instance

newMediaListPlayer

public MediaListPlayer newMediaListPlayer()

Create a new play-list media player.

Returns:

media player instance

newVideoSurface

public CanvasVideoSurface newVideoSurface(Canvas canvas)

Create a new video surface for a Canvas.

Parameters:

canvas - canvas

Returns:

video surface

newVideoSurface

public ComponentIdVideoSurface newVideoSurface(long componentId)

Create a new video surface for a native component id.

Parameters:

componentId - native component id

Returns:

video surface

newMediaList

public MediaList newMediaList()

Create a new media list for a play-list media player.

Returns:

media list instance

getMediaMeta

public MediaMeta getMediaMeta(String mediaPath,
                     boolean parse)

Get local media meta data.

Note that requesting meta data may cause one or more HTTP connections to be made to external web-sites to attempt download of album art.

This method should not be invoked for non-local MRL's like streaming network addresses.

Parameters:

mediaPath - path to the local media

parse - true if the media should be parsed immediately; otherwise false

Returns:

media meta data, or null if the media could not be located

newLog

public NativeLog newLog()

Create a new native log component.

The native log requires vlc 2.1.0 or later.

Returns:

native log component, or null if the native log is not available

newMediaDiscoverer

public MediaDiscoverer newMediaDiscoverer(String name)

Create a new native media service discoverer.

Not all media discoveres are supported on all platforms.

Parameters:

name - name of the required service discoverer, e.g. "audio", "video".

Returns:

native media discoverer component

newAudioMediaDiscoverer

public MediaDiscoverer newAudioMediaDiscoverer()

Create a new native audio media service discoverer.

This method is simply a convenient wrapper around newMediaDiscoverer(String).

Returns:

native media discoverer component

newVideoMediaDiscoverer

public MediaDiscoverer newVideoMediaDiscoverer()

Create a new native video media service discoverer.

This should return for example video capture devices currently attached to the system.

This method is simply a convenient wrapper around newMediaDiscoverer(String).

The video discoverer may not be available on all platforms.

Returns:

native media discoverer component

clock

public long clock()

Get the time as defined by LibVLC.

The time is not meaningful in the sense of what time is it, rather it is a monotonic clock with an arbitrary starting value.

Returns:

current clock time value, in microseconds

newMediaManager

public MediaManager newMediaManager()

Create a new media manager.

Returns:

media manager instance

version

public String version()

Get the libvlc version.

Returns:

native library version

compiler

public String compiler()

Get the compiler used to build libvlc.

Returns:

compiler

changeset

public String changeset()

Get the source code change-set id used to build libvlc.

Returns:

change-set