Class MediaPlayerFactory
- java.lang.Object
-
- uk.co.caprica.vlcj.factory.MediaPlayerFactory
-
public class MediaPlayerFactory extends Object
Factory for creating media player instances and associated components.When using VLC options/arguments to initialise the factory, generally any options that enable/disable modules (e.g. video/audio filters) must be set via the factory instance and not when invoking
MediaApi.play(String, String...)
. However, the module-specific options may be able to be passed as media options and be effective via that play call.The factory will attempt to automatically discover the location of the required LibVLC native library, so it should just work by default (at least for the most common/likely environment configurations). If you have other requirements for the native library discovery mechanism, you can pass in your own implementation of
NativeDiscovery
when you create the factory.You should explicitly
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.
You must make sure you keep a hard reference to the components created by this factory to prevent them from going out of scope and being garbage-collected. If you allow one of these components to go out of scope, then unpredictable behaviour will occur (such as events no longer seeming to fire) even though the video playback may continue (since that happens via native code). You will also likely suffer fatal JVM crashes.
It is always a better strategy to reuse media player instances, rather than repeatedly creating and destroying them.
-
-
Constructor Summary
Constructors Constructor Description MediaPlayerFactory()
Create a new media player factory with default native discovery and no initialisation options.MediaPlayerFactory(String... libvlcArgs)
Create a new media player factory with default native discovery.MediaPlayerFactory(Collection<String> libvlcArgs)
Create a new media player factory with default native discovery.MediaPlayerFactory(NativeDiscovery discovery, String... libvlcArgs)
Create a new media player factory.MediaPlayerFactory(NativeDiscovery discovery, Collection<String> libvlcArgs)
Create a new media player factory.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description ApplicationApi
application()
AudioApi
audio()
DialogsApi
dialogs()
EqualizerApi
equalizer()
MediaApi
media()
MediaDiscovererApi
mediaDiscoverers()
MediaPlayerApi
mediaPlayers()
NativeDiscoveryStrategy
nativeDiscoveryStrategy()
Get the native discovery strategy instance that discovered the native library.String
nativeLibraryPath()
Get the discovered native library path.void
release()
Release all native resources associated with this factory.RendererApi
renderers()
void
submit(Runnable r)
Submit a task for asynchronous execution.VideoSurfaceApi
videoSurfaces()
-
-
-
Constructor Detail
-
MediaPlayerFactory
public MediaPlayerFactory(NativeDiscovery discovery, String... libvlcArgs)
Create a new media player factory.- Parameters:
discovery
- native discovery used to locate the native LibVLC library, may benull
libvlcArgs
- array of options/arguments to pass to LibVLC for initialisation of the native library- Throws:
NativeLibraryMappingException
- if one or more of the declared method bindings inLibVlc
could not be found in the native library that was loaded
-
MediaPlayerFactory
public MediaPlayerFactory(String... libvlcArgs)
Create a new media player factory with default native discovery.If you do not want to use native discovery, use the
MediaPlayerFactory(NativeDiscovery, String...)
constructor instead, passingnull
.- Parameters:
libvlcArgs
- array of options/arguments to pass to LibVLC for initialisation of the native library
-
MediaPlayerFactory
public MediaPlayerFactory(NativeDiscovery discovery, Collection<String> libvlcArgs)
Create a new media player factory.If you do not want to use native discovery, pass
null
for thediscovery
parameter.- Parameters:
discovery
- native discovery used to locate the native LibVLC library, may benull
libvlcArgs
- collection of options/arguments to pass to LibVLC for initialisation of the native library
-
MediaPlayerFactory
public MediaPlayerFactory(Collection<String> libvlcArgs)
Create a new media player factory with default native discovery.If you do not want to use native discovery, use the
MediaPlayerFactory(NativeDiscovery, Collection)
constructor instead, passingnull
.- Parameters:
libvlcArgs
- collection of options/arguments to pass to LibVLC for initialisation of the native library
-
MediaPlayerFactory
public MediaPlayerFactory()
Create a new media player factory with default native discovery and no initialisation options.
-
-
Method Detail
-
application
public final ApplicationApi application()
-
audio
public final AudioApi audio()
-
dialogs
public final DialogsApi dialogs()
-
mediaDiscoverers
public final MediaDiscovererApi mediaDiscoverers()
-
equalizer
public final EqualizerApi equalizer()
-
mediaPlayers
public final MediaPlayerApi mediaPlayers()
-
media
public final MediaApi media()
-
renderers
public final RendererApi renderers()
-
videoSurfaces
public final VideoSurfaceApi videoSurfaces()
-
submit
public final void submit(Runnable r)
Submit a task for asynchronous execution.This is useful in particular for event handling code as native events are generated on a native event callback thread and it is not allowed to call back into LibVLC from this callback thread. If you do, either the call will be ineffective, strange behaviour will happen, or a fatal JVM crash may occur.
To mitigate this, those tasks can be offloaded from the native thread, serialised and executed using this method.
- Parameters:
r
- task to execute
-
release
public final void release()
Release all native resources associated with this factory.The factory must not be used again after it has been released.
-
nativeDiscoveryStrategy
public final NativeDiscoveryStrategy nativeDiscoveryStrategy()
Get the native discovery strategy instance that discovered the native library.Used only for diagnostic purposes.
- Returns:
- strategy instance
-
nativeLibraryPath
public final String nativeLibraryPath()
Get the discovered native library path.Used only for diagnostic purposes.
- Returns:
- native library path
-
-