Module uk.co.caprica.vlcj
Package uk.co.caprica.vlcj.factory

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 Details

    • 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 be null
      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 in LibVlc 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, passing null.

      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 the discovery parameter.

      Parameters:
      discovery - native discovery used to locate the native LibVLC library, may be null
      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, passing null.

      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 Details

    • 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