Package uk.co.caprica.vlcj.player

Interface MediaPlayer

  • All Known Subinterfaces:
    DirectAudioPlayer, DirectMediaPlayer, EmbeddedMediaPlayer, HeadlessMediaPlayer
    All Known Implementing Classes:
    DefaultDirectAudioPlayer, DefaultDirectMediaPlayer, DefaultEmbeddedMediaPlayer, DefaultHeadlessMediaPlayer, DefaultMediaPlayer
    public interface MediaPlayer
    Specification for a media player component.

    A media player provides the following functions:

    • Status controls - e.g. length, time
    • Play-back controls - play, pause, stop, skip, back
    • Volume controls - volume level, mute
    • Chapter controls - next/previous/set chapter, chapter count
    • Sub-picture/sub-title controls - get/set, count
    • Snapshot controls
    • Logo controls - enable/disable, set opacity, file
    • Marquee controls - enable/disable, set colour, size, opacity, timeout
    • Video adjustment controls - contrast, brightness, hue, saturation, gamma
    • Audio adjustment controls - delay

    The basic life-cycle is: 

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

   // Create a factory
   MediaPlayerFactory mediaPlayerFactory = new MediaPlayerFactory(libvlcArgs);

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

   // Create a media player instance (in this example an embedded media player)
   EmbeddedMediaPlayer mediaPlayer = mediaPlayerFactory.newEmbeddedMediaPlayer(fullScreenStrategy);

   // Set standard options as needed to be applied to all subsequently played media items
   String[] standardMediaOptions = {"video-filter=logo", "logo-file=vlcj-logo.png", "logo-opacity=25"};
   mediaPlayer.setStandardMediaOptions(standardMediaOptions);

   // Add a component to be notified of player events
   mediaPlayer.addMediaPlayerEventListener(new MediaPlayerEventAdapter() {...add implementation here...});

   // Create and set a new component to display the rendered video (not shown: add the Canvas to a Frame)
   Canvas canvas = new Canvas();
   CanvasVideoSurface videoSurface = mediaPlayerFactory.newVideoSurface(canvas);
   mediaPlayer.setVideoSurface(videoSurface);

   // Play a particular item, with options if necessary
   String mediaPath = "/path/to/some/movie.mpg";
   String[] mediaOptions = {...add options here...};
   mediaPlayer.playMedia(mediaPath, mediaOptions);

   // Do some interesting things in the application
   ...

   // Cleanly dispose of the media player instance and any associated native resources
   mediaPlayer.release();

   // Cleanly dispose of the media player factory and any associated native resources
   mediaPlayerFactory.release();
    With regard to overlaying logos there are three approaches.

    The first way is to specify standard options for the media player - this will set the logo for any subsequently played media item, for example: 

     String[] standardMediaOptions = {"video-filter=logo", "logo-file=vlcj-logo.png", "logo-opacity=25"};
 mediaPlayer.setStandardMediaOptions(standardMediaOptions);
    The second way is to specify options when playing the media item, for example: 
     String[] mediaOptions = {"video-filter=logo", "logo-file=vlcj-logo.png", "logo-opacity=25"};
 mediaPlayer.playMedia(mediaPath, mediaOptions);
    The final way is to use the methods of this class to set various logo properties, for example: 
     mediaPlayer.setLogoFile("vlcj-logo.png");
 mediaPlayer.setLogoOpacity(25);
 mediaPlayer.setLogoLocation(10, 10);
 mediaPlayer.enableLogo(true);
    For this latter method, it is not possible to enable the logo until after the video has started playing. There is also a noticeable stutter in video play-back when enabling the logo filter in this way.

    With regard to overlaying marquees, again there are three approaches (similar to those for logos).

    In this instance only the final way showing the usage of the API is used, for example: 

     mediaPlayer.setMarqueeText("VLCJ is quite good");
 mediaPlayer.setMarqueeSize(60);
 mediaPlayer.setMarqueeOpacity(70);
 mediaPlayer.setMarqueeColour(Color.green);
 mediaPlayer.setMarqueeTimeout(3000);
 mediaPlayer.setMarqueeLocation(300, 400);
 mediaPlayer.enableMarquee(true);
    With regard to video adjustment controls, after the video has started playing: 
     mediaPlayer.setAdjustVideo(true);
 mediaPlayer.setGamma(0.9f);
 mediaPlayer.setHue(10);
    Some media when played may cause one or more media sub-items to created. These sub-items subsequently need to be played. The media player can be set to automatically play these sub-items via setPlaySubItems(boolean), otherwise playNextSubItem(String...) can be invoked in response to a MediaPlayerEventListener.finished(MediaPlayer) event.

    When using options, generally any options that enable/disable modules (e.g. video/audio filters) must be set via the factory instance and not when invoking playMedia(String, String...). However, the filter-specific options may be able to be passed and be effective via a playMedia call.

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

    Note that media player implementations will guarantee that native media player events are delivered in a single-threaded sequential manner.

    See Also:
    EmbeddedMediaPlayerComponent

    • Method Detail

      • addMediaPlayerEventListener

        void addMediaPlayerEventListener​(MediaPlayerEventListener listener)
        Add a component to be notified of media player events.
        Parameters:
        listener - component to notify

      • removeMediaPlayerEventListener

        void removeMediaPlayerEventListener​(MediaPlayerEventListener listener)
        Remove a component that was previously interested in notifications of media player events.
        Parameters:
        listener - component to stop notifying

      • enableEvents

        void enableEvents​(long eventMask)
        Restrict the set of media player events that generate event notifications to listeners.

        If a set of events is not explicitly enabled, then it is expected that all events be enabled.

        See MediaPlayerEventType.

        This setting applies to all registered event listeners - it is not (currently) possible to set a different event mask for each listener.

        Parameters:
        eventMask - bit mask of events to enable

      • setStandardMediaOptions

        void setStandardMediaOptions​(String... mediaOptions)
        Set standard media options for all media items subsequently played.

        This will not affect any currently playing media item.

        Parameters:
        mediaOptions - options to apply to all subsequently played media items

      • playMedia

        boolean playMedia​(String mrl,
                  String... mediaOptions)
        Play a new media item, with options.

        The new media will begin play-back asynchronously. This means that some media player functions will likely not work if you invoke them immediately after invoking this method - you will in some circumstances need to wait for an appropriate event to be fired before some API functions will have an effect.

        When playing files, depending on the run-time Operating System it may be necessary to pass a URL here (beginning with "file://") rather than a local file path. This should actually not be required.

        Parameters:
        mrl - media resource locator
        mediaOptions - zero or more media item options
        Returns:
        true if the media item was created; false otherwise

      • playMedia

        boolean playMedia​(Media media)
        Play a new media item.

        The new media will begin play-back asynchronously. This means that some media player functions will likely not work if you invoke them immediately after invoking this method - you will in some circumstances need to wait for an appropriate event to be fired before some API functions will have an effect.

        When playing files, depending on the run-time Operating System it may be necessary to pass a URL here (beginning with "file://") rather than a local file path. This should actually not be required.

        Parameters:
        media - media, with options
        Returns:
        true if the media item was created; false otherwise

      • prepareMedia

        boolean prepareMedia​(String mrl,
                     String... mediaOptions)
        Prepare a new media item for play-back, but do not begin playing.

        When playing files, depending on the run-time Operating System it may be necessary to pass a URL here (beginning with "file://") rather than a local file path.

        Parameters:
        mrl - media resource locator
        mediaOptions - zero or more media item options
        Returns:
        true if the media item was created; false otherwise

      • prepareMedia

        boolean prepareMedia​(Media media)
        Prepare a new media item for play-back, but do not begin playing.

        When playing files, depending on the run-time Operating System it may be necessary to pass a URL here (beginning with "file://") rather than a local file path.

        Parameters:
        media - media, with options
        Returns:
        true if the media item was created; false otherwise

      • startMedia

        boolean startMedia​(String mrl,
                   String... mediaOptions)
        Play a new media item, with options, and wait for it to start playing or error.

        This call will block until the media starts or errors.

        Parameters:
        mrl - media resource locator
        mediaOptions - zero or more media item options
        Returns:
        true if the media started playing, false if the media failed to start because of an error

      • startMedia

        boolean startMedia​(Media media)
        Play a new media item, with options, and wait for it to start playing or error.

        This call will block until the media starts or errors.

        Parameters:
        media - media, with options
        Returns:
        true if the media started playing, false if the media failed to start because of an error

      • parseMedia

        void parseMedia()
        Parse local meta data from the current media.

        This method is synchronous.

        Parsing media may cause an HTTP request to be made to search for cover- art.

        Invoking this method on a stream or DVB channel may cause a hang.

      • requestParseMedia

        void requestParseMedia()
        Parse local meta data from the current media.

        This method is asynchronous and a media player event will be raised when the parsed status changes.

        Parsing media may cause an HTTP request to be made to search for cover-art.

        If the media has already been parsed when this function is called then no event will be raised.

        Invoking this method on a stream or DVB channel may cause a hang.

      • requestParseMediaWithOptions

        boolean requestParseMediaWithOptions​(libvlc_media_parse_flag_t... options)
        Parse meta data from the current media, with options.

        This method is asynchronous and a media player event will be raised when the parsed status changes.

        Parsing media may cause an HTTP request to be made to search for cover-art.

        If the media has already been parsed when this function is called, or this function returns an error, then no event will be raised.

        If no options are specified, then the file is parsed if it is a local file.

        This method, while always asynchronous, will cause the media parsing to wait indefinitely, in contrast with requestParseMediaWithOptions(int, libvlc_media_parse_flag_t...)

        Parameters:
        options - optional options
        Returns:
        true if successful; false on error (or e.g. requires LibVLC 3.0.0)

      • requestParseMediaWithOptions

        boolean requestParseMediaWithOptions​(int timeout,
                                     libvlc_media_parse_flag_t... options)
        Parse meta data from the current media, with options and a timeout.

        This method is asynchronous and a media player event will be raised when the parsed status changes.

        Parsing media may cause an HTTP request to be made to search for cover-art.

        If the media has already been parsed when this function is called, or this function returns an error, then no event will be raised.

        If no options are specified, then the file is parsed if it is a local file.

        Parameters:
        timeout - -1 to use the default preparse timeout, 0 to wait indefinitely, otherwise number of milliseconds
        options - optional options
        Returns:
        true if successful; false on error (or e.g. requires LibVLC 3.0.0)

      • isMediaParsed

        boolean isMediaParsed()
        Test whether or not the current media has been parsed.
        Returns:
        true if the current media has been parsed, otherwise false

      • getMediaMeta

        MediaMeta getMediaMeta()
        Get local meta data for the current media.

        Some media types require that the media be parsed before accessing meta data - it is the responsibility of the client application to parse the media if required, see parseMedia().

        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.

        Returns:
        meta data

      • getMediaMeta

        MediaMeta getMediaMeta​(libvlc_media_t mediaInstance)
        Get local meta data for a media instance.

        See getMediaMeta(), the same notes with regard to parsing hold here.

        Parameters:
        mediaInstance - media instance, may be a sub-item
        Returns:
        meta data, never null

      • getSubItemMediaMeta

        List<MediaMeta> getSubItemMediaMeta()
        Get local meta data for all of the current media sub-items (if there are any).

        See getMediaMeta(), the same notes with regard to parsing hold here.

        Returns:
        collection of meta data for the media sub-items, may be empty but never null

      • getMediaMetaData

        MediaMetaData getMediaMetaData()
        Get local meta data for the current media.

        See getMediaMeta(), the same notes with regard to parsing hold here.

        This function returns the meta data in a "detached" value object, i.e. there is no link to the native media handle (so the meta data can not be updated using this function.

        Returns:
        meta data, never null

      • getSubItemMediaMetaData

        List<MediaMetaData> getSubItemMediaMetaData()
        Get local meta data for all of the current media sub-items (if there are any).

        See getMediaMeta(), the same notes with regard to parsing hold here.

        This function returns the meta data in a "detached" value object, i.e. there is no link to the native media handle (so the meta data can not be updated using this function.

        Returns:
        collection of meta data for the media sub-items, may be empty but never null

      • addMediaOptions

        void addMediaOptions​(String... mediaOptions)
        Add options to the current media.
        Parameters:
        mediaOptions - media options

      • setRepeat

        void setRepeat​(boolean repeat)
        Set whether or not the media player should automatically repeat playing the media when it has finished playing.

        There is no guarantee of seamless play-back when using this method - see instead MediaListPlayer.

        If the media has sub-items, then it is the sub-items that are repeated.

        Parameters:
        repeat - true to automatically replay the media, otherwise false

      • getRepeat

        boolean getRepeat()
        Test whether or not the media player will automatically repeat playing the media when it has finished playing.
        Returns:
        true if the media will be automatically replayed, otherwise false

      • setPlaySubItems

        void setPlaySubItems​(boolean playSubItems)
        Set whether or not the media player should automatically play media sub-items.
        Parameters:
        playSubItems - true to automatically play sub-items, otherwise false

      • subItemCount

        int subItemCount()
        Get the number of sub-items (if any).
        Returns:
        sub-item count, or -1 if there is no current media

      • subItemIndex

        int subItemIndex()
        Get the index of the current sub-item.
        Returns:
        sub-item index, or -1 if no sub-items or no current sub-item

      • subItems

        List<String> subItems()
        Get the list of sub-items (if any).

        The MRL of each sub-item is returned in the list.

        Returns:
        sub-item list, or null if there is no current media

      • subItemsMedia

        List<libvlc_media_t> subItemsMedia()
        Get the list of sub-item media instances (if any).

        The native media instance of each sub-item is returned in the list.

        Returns:
        sub-item list, or null if there is no current media

      • subItemsMediaList

        MediaList subItemsMediaList()
        Get the sub-items as a MediaList.
        Returns:
        sub-item media list, or null if there is no current media

      • playNextSubItem

        boolean playNextSubItem​(String... mediaOptions)
        Play the next sub-item (if there is one).

        If any standard media options have been set via setStandardMediaOptions(String...) then those options will be applied to the sub-item.

        If the media player has been set to automatically repeat, then the sub- items will be repeated once the last one has been played.

        Parameters:
        mediaOptions - zero or more media options for the sub-item
        Returns:
        true if there is a sub-item, otherwise false

      • playSubItem

        boolean playSubItem​(int index,
                    String... mediaOptions)
        Play a particular sub-item (if there is one).

        If any standard media options have been set via setStandardMediaOptions(String...) then those options will be applied to the sub-item.

        If the media player has been set to automatically repeat, then the sub- items will be repeated once the last one has been played, or if the requested sub-item index exceeds the currently available sub-items.

        Parameters:
        index - sub-item index
        mediaOptions - zero or more media options for the sub-item
        Returns:
        true if there is a sub-item, otherwise false

      • isPlayable

        boolean isPlayable()
        Is the current media playable?
        Returns:
        true if the current media is playable, otherwise false

      • isPlaying

        boolean isPlaying()
        Is the media player playing?
        Returns:
        true if the media player is playing, otherwise false

      • isSeekable

        boolean isSeekable()
        Is the current media seekable?
        Returns:
        true if the current media is seekable, otherwise false

      • canPause

        boolean canPause()
        Can the current media be paused?
        Returns:
        true if the current media can be paused, otherwise false

      • programScrambled

        boolean programScrambled()
        Is the current program scrambled?

        Requires vlc 2.2.0 or later.

        Returns:
        true if the current program is scrambled, otherwise false

      • getLength

        long getLength()
        Get the length of the current media item.
        Returns:
        length, in milliseconds

      • getTime

        long getTime()
        Get the current play-back time.
        Returns:
        current time, expressed as a number of milliseconds

      • getPosition

        float getPosition()
        Get the current play-back position.
        Returns:
        current position, expressed as a percentage (e.g. 0.15 is returned for 15% complete)

      • getFps

        float getFps()
        Get the current play-back frames-per-second.
        Returns:
        number of frames-per-second

      • getRate

        float getRate()
        Get the current video play rate.
        Returns:
        rate, where 1.0 is normal speed, 0.5 is half speed, 2.0 is double speed and so on

      • getVideoOutputs

        int getVideoOutputs()
        Get the number of video outputs for the media player.
        Returns:
        number of video outputs, may be zero

      • getVideoDimension

        Dimension getVideoDimension()
        Get the video size.

        The video dimensions are not available until after the video has started playing and a video output has been created.

        Returns:
        video size if available, or null

      • getMediaDetails

        MediaDetails getMediaDetails()
        Get the media details.

        The details are available after the video has started playing, regardless of whether nor not a video output has been created.

        Returns:
        video meta data, or null if the media meta data is not available

      • getAspectRatio

        String getAspectRatio()
        Get the video aspect ratio.
        Returns:
        aspect ratio

      • getScale

        float getScale()
        Get the current video scale (zoom).
        Returns:
        scale

      • getCropGeometry

        String getCropGeometry()
        Get the current video crop geometry.
        Returns:
        crop geometry

      • getMediaStatistics

        libvlc_media_stats_t getMediaStatistics()
        Get the current media statistics.

        Statistics are only updated if the video is playing.

        Returns:
        media statistics

      • getMediaStatistics

        libvlc_media_stats_t getMediaStatistics​(libvlc_media_t media)
        Get the current media statistics for a media item (e.g. a sub-item).

        Statistics are only updated if the video is playing.

        Parameters:
        media - media item
        Returns:
        media statistics, never null

      • getMediaState

        libvlc_state_t getMediaState()
        Get the current media state.
        Returns:
        state

      • getMediaPlayerState

        libvlc_state_t getMediaPlayerState()
        Get the media player current state.
        Returns:
        state

      • getTitleCount

        int getTitleCount()
        Get the number of titles.
        Returns:
        number of titles, or -1 if none

      • getTitle

        int getTitle()
        Get the current title.
        Returns:
        title number

      • setTitle

        void setTitle​(int title)
        Set a new title to play.
        Parameters:
        title - title number

      • getVideoTrackCount

        int getVideoTrackCount()
        Get the number of available video tracks.
        Returns:
        number of tracks

      • getVideoTrack

        int getVideoTrack()
        Get the current video track.
        Returns:
        track identifier, see getVideoDescriptions()

      • setVideoTrack

        int setVideoTrack​(int track)
        Set a new video track to play.

        The track identifier must be one of those returned by getVideoDescriptions().

        Video can be disabled by passing here the identifier of the track with a description of "Disable".

        There is no guarantee that the available track identifiers go in sequence from zero up to getVideoTrackCount()-1. The getVideoDescriptions() method should always be used to ascertain the available track identifiers.

        Parameters:
        track - track identifier
        Returns:
        current video track identifier

      • getAudioTrackCount

        int getAudioTrackCount()
        Get the number of available audio tracks.
        Returns:
        track count

      • getAudioTrack

        int getAudioTrack()
        Get the current audio track.
        Returns:
        track identifier, see getAudioDescriptions()

      • setAudioTrack

        int setAudioTrack​(int track)
        Set a new audio track to play.

        The track identifier must be one of those returned by getAudioDescriptions().

        Audio can be disabled by passing here the identifier of the track with a description of "Disable".

        There is no guarantee that the available track identifiers go in sequence from zero up to getAudioTrackCount()-1. The getAudioDescriptions() method should always be used to ascertain the available track identifiers.

        The implementation of the corresponding native method in libvlc is bugged before vlc 2.0.5, therefore vlc 2.0.5 or later is required for correct behaviour when using this method.

        Parameters:
        track - track identifier
        Returns:
        current audio track identifier

      • play

        void play()
        Begin play-back.

        If called when the play-back is paused, the play-back will resume from the current position.

      • start

        boolean start()
        Begin play-back and wait for the media to start playing or for an error to occur.

        If called when the play-back is paused, the play-back will resume from the current position.

        This call will block until the media starts or errors.

        Returns:
        true if the media started playing, false if the media failed to start because of an error

      • stop

        void stop()
        Stop play-back.

        A subsequent play will play-back from the start.

      • setPause

        void setPause​(boolean pause)
        Pause/resume.

        Requires vlc 1.1.1 or later.

        Parameters:
        pause - true to pause, false to play/resume

      • pause

        void pause()
        Pause play-back.

        If the play-back is currently paused it will begin playing.

      • nextFrame

        void nextFrame()
        Advance one frame.

      • skip

        void skip​(long delta)
        Skip forward or backward by a period of time.

        To skip backwards specify a negative delta.

        Parameters:
        delta - time period, in milliseconds

      • skipPosition

        void skipPosition​(float delta)
        Skip forward or backward by a change in position.

        To skip backwards specify a negative delta.

        Parameters:
        delta - amount to skip

      • setTime

        void setTime​(long time)
        Jump to a specific moment.

        If the requested time is less than zero, it is normalised to zero.

        Parameters:
        time - time since the beginning, in milliseconds

      • setPosition

        void setPosition​(float position)
        Jump to a specific position.

        If the requested position is less than zero, it is normalised to zero.

        Parameters:
        position - position value, a percentage (e.g. 0.15 is 15%)

      • setRate

        int setRate​(float rate)
        Set the video play rate.

        Some media protocols are not able to change the rate.

        Parameters:
        rate - rate, where 1.0 is normal speed, 0.5 is half speed, 2.0 is double speed and so on
        Returns:
        -1 on error, 0 on success

      • setAspectRatio

        void setAspectRatio​(String aspectRatio)
        Set the video aspect ratio
        Parameters:
        aspectRatio - aspect ratio, e.g. "16:9", "4:3", "185:100" for 1:85.1 and so on

      • setScale

        void setScale​(float factor)
        Set the video scaling factor.
        Parameters:
        factor - scaling factor, or zero to scale the video the size of the container

      • setCropGeometry

        void setCropGeometry​(String cropGeometry)
        Set the crop geometry.

        The format for the crop geometry is one of:

        • numerator:denominator
        • widthxheight+x+y
        • left:top:right:bottom
        For example: 
         mediaPlayer.setCropGeometry("4:3");         // W:H
 mediaPlayer.setCropGeometry("719x575+0+0"); // WxH+L+T
 mediaPlayer.setCropGeometry("6+10+6+10");   // L+T+R+B
        Parameters:
        cropGeometry - formatted string describing the desired crop geometry

      • setAudioOutput

        boolean setAudioOutput​(String output)
        Set the desired audio output.

        The change will not be applied until the media player has been stopped and then played again.

        The output name comes from MediaPlayerFactory.getAudioOutputs().

        Parameters:
        output - name of the desired audio output
        Returns:
        true if the output was successfully set, otherwise false

      • getAudioOutputDevice

        String getAudioOutputDevice()
        Get the identifier of the current audio output device, if available.

        To return a useful value, an audio output must be active (i.e. the media must be playing).

        Returns:
        identifier of the current audio output device, or null if not available (e.g. requires LibVLC 3.0.0)

      • getAudioOutputDevices

        List<AudioDevice> getAudioOutputDevices()
        Get the available audio devices for the media player audio output.
        Returns:
        list of audio devices, or null if not available (e.g. requires LibVLC 2.2.0)

      • mute

        boolean mute()
        Toggle volume mute.
        Returns:
        mute true if the volume is muted, false if the volume is not muted

      • mute

        void mute​(boolean mute)
        Mute or un-mute the volume.
        Parameters:
        mute - true to mute the volume, false to un-mute it

      • isMute

        boolean isMute()
        Test whether or not the volume is currently muted.
        Returns:
        mute true if the volume is muted, false if the volume is not muted

      • getVolume

        int getVolume()
        Get the current volume.
        Returns:
        volume, a percentage of full volume in the range 0 to 200

      • setVolume

        void setVolume​(int volume)
        Set the volume.

        The volume is actually a percentage of full volume, setting a volume over 100 may cause audible distortion.

        Parameters:
        volume - volume, a percentage of full volume in the range 0 to 200

      • getAudioChannel

        int getAudioChannel()
        Get the current audio channel. For channel values see libvlc_audio_output_channel_t. Warning this API is subject to change.
        Returns:
        audio channel

      • setAudioChannel

        void setAudioChannel​(int channel)
        Set the audio channel. For channel values see libvlc_audio_output_channel_t. Warning this API is subject to change.
        Parameters:
        channel - channel

      • getAudioDelay

        long getAudioDelay()
        Get the audio delay.
        Returns:
        audio delay, in microseconds

      • setAudioDelay

        void setAudioDelay​(long delay)
        Set the audio delay.

        The audio delay is set for the current item only and will be reset to zero each time the media changes.

        Parameters:
        delay - desired audio delay, in microseconds

      • getChapterCount

        int getChapterCount()
        Get the chapter count.
        Returns:
        number of chapters, or -1 if no chapters

      • getChapter

        int getChapter()
        Get the current chapter.
        Returns:
        chapter number, where zero is the first chatper, or -1 if no media

      • setChapter

        void setChapter​(int chapterNumber)
        Set the chapter.
        Parameters:
        chapterNumber - chapter number, where zero is the first chapter

      • nextChapter

        void nextChapter()
        Jump to the next chapter.

        If the play-back is already at the last chapter, this will have no effect.

      • previousChapter

        void previousChapter()
        Jump to the previous chapter.

        If the play-back is already at the first chapter, this will have no effect.

      • menuActivate

        void menuActivate()
        Activate a DVD menu. Requires vlc 2.0.0 or later.

      • menuUp

        void menuUp()
        Navigate up a DVD menu. Requires vlc 2.0.0 or later.

      • menuDown

        void menuDown()
        Navigate down a DVD menu. Requires vlc 2.0.0 or later.

      • menuLeft

        void menuLeft()
        Navigate left a DVD menu. Requires vlc 2.0.0 or later.

      • menuRight

        void menuRight()
        Navigate right a DVD menu. Requires vlc 2.0.0 or later.

      • getSpuCount

        int getSpuCount()
        Get the number of sub-pictures/sub-titles.
        Returns:
        number of sub-titles

      • getSpu

        int getSpu()
        Get the current sub-title track.
        Returns:
        sub-title number, or -1 if none

      • setSpu

        int setSpu​(int spu)
        Set the current sub-title track.

        The track identifier must be one of those returned by getSpuDescriptions().

        Subtitles can be disabled by passing here the identifier of the track with a description of "Disable".

        There is no guarantee that the available subtitle identifiers go in sequence from zero up to getSpuCount()-1. The getSpuDescriptions() method should always be used to ascertain the available subtitle identifiers.

        The implementation of the corresponding native method in libvlc is bugged before vlc 2.0.6, therefore vlc 2.0.6 or later is required for correct behaviour when using this method.

        Parameters:
        spu - sub-title identifier, or -1 for none
        Returns:
        current sub-title identifier

      • getSpuDelay

        long getSpuDelay()
        Get the sub-title delay.
        Returns:
        sub-title delay, in microseconds

      • setSpuDelay

        void setSpuDelay​(long delay)
        Set the sub-title delay.

        The sub-title delay is set for the current item only and will be reset to zero each time the media changes.

        Parameters:
        delay - desired sub-title delay, in microseconds

      • setSubTitleFile

        void setSubTitleFile​(String subTitleFileName)
        Set the sub-title file to use.
        Parameters:
        subTitleFileName - name of the file containing the sub-titles

      • setSubTitleFile

        void setSubTitleFile​(File subTitleFile)
        Set the sub-title file to use.
        Parameters:
        subTitleFile - file containing the sub-titles

      • getTeletextPage

        int getTeletextPage()
        Get the current teletext page.
        Returns:
        page number

      • setTeletextPage

        void setTeletextPage​(int pageNumber)
        Set the new teletext page to retrieve.
        Parameters:
        pageNumber - page number

      • setTeletextKey

        void setTeletextKey​(libvlc_teletext_key_e key)
        Set ("press") a teletext key.

        Requires LibVLC 3.0.0 or later.

        Parameters:
        key - teletext key

      • toggleTeletext

        void toggleTeletext()
        Toggle teletext status.

      • getTitleDescriptions

        List<TrackDescription> getTitleDescriptions()
        Get the title descriptions.

        The media must be playing before this information is available.

        Returns:
        list of descriptions, may be empty but will never be null

      • getVideoDescriptions

        List<TrackDescription> getVideoDescriptions()
        Get the video (i.e. "title") track descriptions.

        The media must be playing before this information is available.

        Returns:
        list of descriptions, may be empty but will never be null

      • getAudioDescriptions

        List<TrackDescription> getAudioDescriptions()
        Get the audio track descriptions.

        The media must be playing before this information is available.

        Returns:
        list of descriptions, may be empty but will never be null

      • getSpuDescriptions

        List<TrackDescription> getSpuDescriptions()
        Get the sub-title track descriptions.

        The media must be playing before this information is available.

        Returns:
        list of descriptions, may be empty but will never be null

      • getChapterDescriptions

        List<String> getChapterDescriptions​(int title)
        Get the chapter descriptions for a title.

        The media must be playing before this information is available.

        Parameters:
        title - title number
        Returns:
        list of descriptions (which may be empty), or null if there is no such title

      • getChapterDescriptions

        List<String> getChapterDescriptions()
        Get the chapter descriptions for the current title.

        The media must be playing before this information is available.

        Returns:
        list of descriptions (which may be empty), or null if there is no current title

      • getAllChapterDescriptions

        List<List<String>> getAllChapterDescriptions()
        Get all of the chapter descriptions for all available titles.

        The media must be playing before this information is available.

        Returns:
        a collection of chapter description lists, one list for each title (may be empty, but never null)

      • getExtendedTitleDescriptions

        List<TitleDescription> getExtendedTitleDescriptions()
        Get the extended (or "full") title descriptions for the current title.
        Returns:
        collection of title descriptions, may be empty (but not null)

      • getExtendedChapterDescriptions

        List<ChapterDescription> getExtendedChapterDescriptions()
        Get the extended (or "full") chapter descriptions for the current title.
        Returns:
        collection of chapter descriptions, may be empty (but not null)

      • getExtendedChapterDescriptions

        List<ChapterDescription> getExtendedChapterDescriptions​(int title)
        Get the extended (or "full") chapter descriptions for a particular title.
        Parameters:
        title - title id (this is not an index from zero, it must be a valid title identifier)
        Returns:
        collection of chapter descriptions, may be empty (but not null)

      • getTrackInfo

        List<TrackInfo> getTrackInfo​(TrackType... types)
        Get the track (i.e. "elementary streams") information for the current media.

        The media (if local) should first be parsed, see parseMedia(), or be already playing.

        In the case of DVD media (for example ".iso" files) and streams the media must be played and video output must be available before valid track information becomes available, and even then it is not always available immediately (or it is only partially available) so polling may be required.

        If you invoke this method "too soon", you may only receive partial track information.

        Parameters:
        types - zero or more types of track to get, or all tracks if omitted
        Returns:
        collection of track information, or null if there is no current media

      • getTrackInfo

        List<TrackInfo> getTrackInfo​(libvlc_media_t media,
                             TrackType... types)
        Get track (i.e. "elementary streams") information for a media item.

        See getTrackInfo(TrackType...).

        Parameters:
        media - media item
        types - zero or more types of track to get, or all tracks if omitted
        Returns:
        collection of track information, or null if there is no current media

      • getMediaType

        libvlc_media_type_e getMediaType()
        Get the media type for the current media.

        This is a medium type rather than e.g. a specific file type.

        Requires LibVLC 3.0.0 or later.

        Returns:
        media type, or null if the current media is null

      • getMediaType

        libvlc_media_type_e getMediaType​(libvlc_media_t media)
        Get the media type for a specific media.

        This is a medium type rather than e.g. a specific file type.

        Requires LibVLC 3.0.0 or later.

        Parameters:
        media - media
        Returns:
        media type, or null if media is null

      • getCodecDescription

        String getCodecDescription​(libvlc_track_type_t type,
                           int codec)
        Get a description for a FourCC codec value.

        Requires LibVLC 3.0.0 or later.

        Parameters:
        type - type of track
        codec - codec value
        Returns:
        description, or the empty string if the description is not available

      • getSubItemTrackInfo

        List<List<TrackInfo>> getSubItemTrackInfo​(TrackType... types)
        Get the track (i.e. "elementary streams") information for all sub-items if there are any.

        See getTrackInfo(TrackType...).

        Parameters:
        types - zero or more types of track to get, or all tracks if omitted
        Returns:
        collection of track information for each sub-item, or null if there is no current media

      • setSnapshotDirectory

        void setSnapshotDirectory​(String snapshotDirectoryName)
        Set the directory into which snapshots of the video are saved.

        If the specified directory path does not yet exist, it will be created.

        Parameters:
        snapshotDirectoryName - name of the directory to save snapshots to

      • saveSnapshot

        boolean saveSnapshot()
        Save a snapshot of the currently playing video.

        The size of the image will be that produced by the libvlc native snapshot function, i.e. the size of the media itself.

        The snapshot will be created in the directory set via setSnapshotDirectory(String), unless that directory has not been set in which case the snapshot will be created in the user's home directory, obtained via the "user.home" system property.

        The snapshot will be assigned a filename based on the current time.

        The size of the image will be that produced by the libvlc native snapshot function.

        Taking a snapshot is an asynchronous function, the snapshot is not available until after the MediaPlayerEventListener.snapshotTaken(MediaPlayer, String) event is received.

        Returns:
        true if the snapshot was saved, otherwise false

      • saveSnapshot

        boolean saveSnapshot​(int width,
                     int height)
        Save a snapshot of the currently playing video.

        The snapshot will be created in the directory set via setSnapshotDirectory(String), unless that directory has not been set in which case the snapshot will be created in the user's home directory, obtained via the "user.home" system property.

        The snapshot will be assigned a filename based on the current time.

        If one of width or height is zero the original image aspect ratio will be preserved.

        If both width and height are zero, the original image size will be used, see saveSnapshot().

        Taking a snapshot is an asynchronous function, the snapshot is not available until after the MediaPlayerEventListener.snapshotTaken(MediaPlayer, String) event is received.

        Parameters:
        width - desired image width
        height - desired image height
        Returns:
        true if the snapshot was saved, otherwise false

      • saveSnapshot

        boolean saveSnapshot​(File file)
        Save a snapshot of the currently playing video.

        The size of the image will be that produced by the libvlc native snapshot function, i.e. the size of the media itself.

        Any missing directory path will be created if it does not exist.

        Taking a snapshot is an asynchronous function, the snapshot is not available until after the MediaPlayerEventListener.snapshotTaken(MediaPlayer, String) event is received.

        Parameters:
        file - file to contain the snapshot
        Returns:
        true if the snapshot was saved, otherwise false

      • saveSnapshot

        boolean saveSnapshot​(File file,
                     int width,
                     int height)
        Save a snapshot of the currently playing video.

        Any missing directory path will be created if it does not exist.

        If one of width or height is zero the original image aspect ratio will be preserved.

        If both width and height are zero, the original image size will be used, see saveSnapshot(File).

        Taking a snapshot is an asynchronous function, the snapshot is not available until after the MediaPlayerEventListener.snapshotTaken(MediaPlayer, String) event is received.

        Parameters:
        file - file to contain the snapshot
        width - desired image width
        height - desired image height
        Returns:
        true if the snapshot was saved, otherwise false

      • getSnapshot

        BufferedImage getSnapshot()
        Get a snapshot of the currently playing video.

        The size of the image will be that produced by the libvlc native snapshot function, i.e. the size of the media itself.

        This implementation uses the native libvlc method to save a snapshot of the currently playing video. This snapshot is saved to a temporary file and then the resultant image is loaded from the file.

        Taking a snapshot is an asynchronous function, the snapshot is not available until after the MediaPlayerEventListener.snapshotTaken(MediaPlayer, String) event is received.

        Returns:
        snapshot image, or null if a snapshot could not be taken

      • getSnapshot

        BufferedImage getSnapshot​(int width,
                          int height)
        Get a snapshot of the currently playing video.

        This implementation uses the native libvlc method to save a snapshot of the currently playing video. This snapshot is saved to a temporary file and then the resultant image is loaded from the file.

        If one of width or height is zero the original image aspect ratio will be preserved.

        If both width and height are zero, the original image size will be used, see getSnapshot()

        Taking a snapshot is an asynchronous function, the snapshot is not available until after the MediaPlayerEventListener.snapshotTaken(MediaPlayer, String) event is received.

        Parameters:
        width - desired image width
        height - desired image height
        Returns:
        snapshot image, or null if a snapshot could not be taken

      • enableLogo

        void enableLogo​(boolean enable)
        Enable/disable the logo.

        The logo will not be enabled if there is currently no video being played.

        Parameters:
        enable - true to show the logo, false to hide it

      • setLogoOpacity

        void setLogoOpacity​(int opacity)
        Set the logo opacity.
        Parameters:
        opacity - opacity in the range 0 to 255 where 255 is fully opaque

      • setLogoOpacity

        void setLogoOpacity​(float opacity)
        Set the logo opacity.
        Parameters:
        opacity - opacity percentage in the range 0.0 to 1.0 where 1.0 is fully opaque

      • setLogoLocation

        void setLogoLocation​(int x,
                     int y)
        Set the logo location.
        Parameters:
        x - x co-ordinate for the top left of the logo
        y - y co-ordinate for the top left of the logo

      • setLogoPosition

        void setLogoPosition​(libvlc_logo_position_e position)
        Set the logo position.
        Parameters:
        position - position

      • setLogoFile

        void setLogoFile​(String logoFile)
        Set the logo file.
        Parameters:
        logoFile - logo file name

      • setLogoImage

        void setLogoImage​(RenderedImage logoImage)
        Set the logo image.

        The image will first be written to a temporary file, before invoking setLogoFile(String). This is not optimal, but creating a temporary file for the logo in this way is unavoidable.

        The temporary file will persist until the JVM exits. The file can not be deleted immediately due to the asynchronous nature of the native API call that sets the logo from the file.

        There are circumstances under which this temporary file may fail to be deleted, as per File.deleteOnExit() - i.e. "Deletion will be attempted only for normal termination of the virtual machine".

        Parameters:
        logoImage - logo image

      • setLogo

        void setLogo​(Logo logo)
        Set a logo.
        Parameters:
        logo - logo

      • enableMarquee

        void enableMarquee​(boolean enable)
        Enable/disable the marquee.

        The marquee will not be enabled if there is currently no video being played.

        Parameters:
        enable - true to show the marquee, false to hide it

      • setMarqueeText

        void setMarqueeText​(String text)
        Set the marquee text.

        Format variables are available: 

         Time related:
  %Y = year
  %d = day
  %H = hour
  %M = minute
  %S = second
        See http://wiki.videolan.org/index.php?title=Documentation:Modules/marq.

        If you want to use new-lines in the marquee text make sure you use the "\r\n" escape sequence - "\n" on its own will not work.

        Parameters:
        text - text

      • setMarqueeColour

        void setMarqueeColour​(Color colour)
        Set the marquee colour.
        Parameters:
        colour - colour, any alpha component will be masked off

      • setMarqueeColour

        void setMarqueeColour​(int colour)
        Set the marquee colour.
        Parameters:
        colour - RGB colour value

      • setMarqueeOpacity

        void setMarqueeOpacity​(int opacity)
        Set the marquee opacity.
        Parameters:
        opacity - opacity in the range 0 to 100 where 255 is fully opaque

      • setMarqueeOpacity

        void setMarqueeOpacity​(float opacity)
        Set the marquee opacity.
        Parameters:
        opacity - opacity percentage in the range 0.0 to 1.0 where 1.0 is fully opaque

      • setMarqueeSize

        void setMarqueeSize​(int size)
        Set the marquee size.
        Parameters:
        size - size, height of the marquee text in pixels

      • setMarqueeTimeout

        void setMarqueeTimeout​(int timeout)
        Set the marquee timeout.
        Parameters:
        timeout - timeout, in milliseconds

      • setMarqueeLocation

        void setMarqueeLocation​(int x,
                        int y)
        Set the marquee location.
        Parameters:
        x - x co-ordinate for the top left of the marquee
        y - y co-ordinate for the top left of the marquee

      • setMarqueePosition

        void setMarqueePosition​(libvlc_marquee_position_e position)
        Set the marquee position.
        Parameters:
        position - position

      • setMarquee

        void setMarquee​(Marquee marquee)
        Set a marquee.
        Parameters:
        marquee - marquee

      • setDeinterlace

        void setDeinterlace​(DeinterlaceMode deinterlaceMode)
        Set the de-interlace filter to use.
        Parameters:
        deinterlaceMode - mode, or null to disable the de-interlace filter

      • setAdjustVideo

        void setAdjustVideo​(boolean adjustVideo)
        Enable/disable the video adjustments.

        The video adjustment controls must be enabled after the video has started playing.

        Requires vlc 1.1.1 or later.

        Parameters:
        adjustVideo - true if the video adjustments are enabled, otherwise false

      • isAdjustVideo

        boolean isAdjustVideo()
        Test whether or not the video adjustments are enabled.

        Requires vlc 1.1.1 or later.

        Returns:
        true if the video adjustments are enabled, otherwise false

      • getContrast

        float getContrast()
        Get the current video contrast.

        Requires vlc 1.1.1 or later.

        Returns:
        contrast, in the range from 0.0 to 2.0

      • setContrast

        void setContrast​(float contrast)
        Set the video contrast.

        Video adjustments must be enabled for this to have any effect. Requires vlc 1.1.1 or later.

        Parameters:
        contrast - contrast value, in the range from 0.0 to 2.0

      • getBrightness

        float getBrightness()
        Get the current video brightness.

        Requires vlc 1.1.1 or later.

        Returns:
        brightness, in the range from 0.0 to 2.0

      • setBrightness

        void setBrightness​(float brightness)
        Set the video brightness.

        Video adjustments must be enabled for this to have any effect.

        Requires vlc 1.1.1 or later.

        Parameters:
        brightness - brightness value, in the range from 0.0 to 2.0

      • getHue

        int getHue()
        Get the current video hue.

        Requires vlc 1.1.1 or later.

        Returns:
        hue, in the range from 0 to 360

      • setHue

        void setHue​(int hue)
        Set the video hue.

        Video adjustments must be enabled for this to have any effect.

        Requires vlc 1.1.1 or later.

        Parameters:
        hue - hue value, in the range from 0 to 360

      • getSaturation

        float getSaturation()
        Get the current video saturation.

        Requires vlc 1.1.1 or later.

        Returns:
        saturation, in the range from 0.0 to 3.0

      • setSaturation

        void setSaturation​(float saturation)
        Set the video saturation.

        Video adjustments must be enabled for this to have any effect.

        Requires vlc 1.1.1 or later.

        Parameters:
        saturation - saturation value, in the range from 0.0 to 3.0

      • getGamma

        float getGamma()
        Get the current video gamma.

        Requires vlc 1.1.1 or later.

        Returns:
        gamma value, in the range from 0.01 to 10.0

      • setGamma

        void setGamma​(float gamma)
        Set the video gamma.

        Video adjustments must be enabled for this to have any effect.

        Requires vlc 1.1.1 or later.

        Parameters:
        gamma - gamma, in the range from 0.01 to 10.0

      • setVideoTitleDisplay

        void setVideoTitleDisplay​(libvlc_position_e position,
                          int timeout)
        Set if, and how, the video title will be shown when playing media.
        Parameters:
        position - position, libvlc_position_e.disable to prevent the title from appearing
        timeout - time to display the title in milliseconds (ignored when the title is disabled)

      • getEqualizer

        Equalizer getEqualizer()
        Get the current audio equalizer.

        Requires vlc 2.2.0 or later.

        Returns:
        equalizer, or null if there is no active equalizer

      • setEqualizer

        void setEqualizer​(Equalizer equalizer)
        Set the audio equalizer.

        Requires vlc 2.2.0 or later.

        Parameters:
        equalizer - equalizer, or null to disable the audio equalizer

      • getRole

        libvlc_media_player_role_e getRole()
        Get the media player role.

        Requires vlc 3.0.0 or later.

        Returns:
        media player role

      • setRole

        void setRole​(libvlc_media_player_role_e role)
        Set the media player role.

        Requires vlc 3.0.0 or later.

        Parameters:
        role - media player role

      • mrl

        String mrl()
        Get the media resource locator for the current media instance.

        The native media instance may be an automatically/scripted added sub-item.

        Returns:
        URL-encoded media resource locator, or null if there is no current media

      • mrl

        String mrl​(libvlc_media_t mediaInstance)
        Get the media resource locator for a media instance.

        The native media instance may be an automatically/scripted added sub-item.

        Parameters:
        mediaInstance - native media instance
        Returns:
        URL-encoded media resource locator

      • userData

        Object userData()
        Get the user data associated with the media player.
        Returns:
        user data

      • userData

        void userData​(Object userData)
        Set user data to associate with the media player.
        Parameters:
        userData - user data

      • release

        void release()
        Release the media player, freeing all associated (including native) resources.

      • mediaPlayerInstance

        libvlc_media_player_t mediaPlayerInstance()
        Provide access to the native media player instance.

        This is exposed on the interface as an implementation side-effect, ordinary applications are not expected to use this.

        Returns:
        media player instance