io.vov.vitamio
Class MediaPlayer

java.lang.Object
  io.vov.vitamio.MediaPlayer

public class MediaPlayer
extends java.lang.Object

MediaPlayer class can be used to control playback of audio/video files and streams. An example on how to use the methods in this class can be found in VideoView. This class will function the same as android.media.MediaPlayer in most cases. Please see Audio and Video for additional help using MediaPlayer.

Nested Class Summary

static interface	MediaPlayer.OnBufferingUpdateListener
static interface	MediaPlayer.OnCompletionListener
static interface	MediaPlayer.OnErrorListener
static interface	MediaPlayer.OnInfoListener
static interface	MediaPlayer.OnPreparedListener
static interface	MediaPlayer.OnSeekCompleteListener
static interface	MediaPlayer.OnSubtitleUpdateListener
static interface	MediaPlayer.OnVideoSizeChangedListener

Field Summary

static int	MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK
static int	MEDIA_ERROR_UNKNOWN
static int	MEDIA_INFO_BUFFERING_END MediaPlayer is resuming playback after filling buffers.
static int	MEDIA_INFO_BUFFERING_START MediaPlayer is temporarily pausing playback internally in order to buffer more data.
static int	MEDIA_INFO_NOT_SEEKABLE The media cannot be seeked (e.g live stream)
static int	MEDIA_INFO_VIDEO_TRACK_LAGGING The video is too complex for the decoder: it can't decode frames fast enough.
static java.lang.String[]	SUB_TYPES The external subtitle types which Vitamio supports.
static int	SUBTITLE_EXTERNAL The subtitle displayed is an external file
static int	SUBTITLE_INTERNAL The subtitle displayed is embeded in the movie
static int	VIDEOQUALITY_HIGH
static int	VIDEOQUALITY_LOW
static int	VIDEOQUALITY_MEDIUM

Constructor Summary

MediaPlayer(Context ctx)
Default constructor.

Method Summary

int	getAudioTrack() Get the audio track number in playback
java.util.HashMap<java.lang.String,java.lang.Integer>	getAudioTrackMap(java.lang.String encoding) Get the audio tracks embeded in the movie (e.g.
int	getBufferProgress()
long	getCurrentPosition() Gets the current playback position.
long	getDuration() Gets the duration of the file.
java.lang.String	getMetaEncoding() Get the encoding if haven't set with setMetaEncoding(String)
int	getSubLocation()
java.lang.String	getSubPath() You can get the file-path of the external subtitle in use.
int	getSubTrack() Get the subtitle track number in playback
java.util.HashMap<java.lang.String,java.lang.Integer>	getSubTrackMap(java.lang.String encoding) Get the subtitles embeded in the movie (e.g.
float	getVideoAspectRatio() Returns the aspect ratio of the video.
int	getVideoHeight() Returns the height of the video.
int	getVideoWidth() Returns the width of the video.
boolean	isBuffering() Checks whether the buffer is filled
boolean	isPlaying() Checks whether the MediaPlayer is playing.
void	pause() Pauses playback.
void	prepare() Prepares the player for playback, synchronously.
void	prepareAsync() Prepares the player for playback, asynchronously.
void	release() Releases resources associated with this MediaPlayer object.
void	releaseDisplay() Calling this result in only the audio track being played.
void	reset() Resets the MediaPlayer to its uninitialized state.
void	seekTo(long msec) Seeks to specified time position.
void	setAudioTrack(int audioIndex) Set the audio track to play, must be in the result of getAudioTrackMap(String)
void	setBufferSize(int bufSize) The buffer to fill before playback, default is 1024KB
void	setDataSource(Context context, Uri uri) Sets the data source as a content Uri.
void	setDataSource(java.io.FileDescriptor fd) Sets the data source (FileDescriptor) to use.
void	setDataSource(java.lang.String path) Sets the data source (file-path or http/rtsp/mms URL) to use.
void	setDisplay(SurfaceHolder sh) Sets the SurfaceHolder to use for displaying the video portion of the media.
void	setMetaEncoding(java.lang.String encoding) Set the encoding MediaPlayer will use to determine the metadata
void	setOnBufferingUpdateListener(MediaPlayer.OnBufferingUpdateListener listener) Register a callback to be invoked when the status of a network stream's buffer has changed.
void	setOnCompletionListener(MediaPlayer.OnCompletionListener listener) Register a callback to be invoked when the end of a media source has been reached during playback.
void	setOnErrorListener(MediaPlayer.OnErrorListener listener) Register a callback to be invoked when an error has happened during an asynchronous operation.
void	setOnInfoListener(MediaPlayer.OnInfoListener listener)
void	setOnPreparedListener(MediaPlayer.OnPreparedListener listener) Register a callback to be invoked when the media source is ready for playback.
void	setOnSeekCompleteListener(MediaPlayer.OnSeekCompleteListener listener) Register a callback to be invoked when a seek operation has been completed.
void	setOnSubtitleUpdateListener(MediaPlayer.OnSubtitleUpdateListener listener) Register a callback to be invoked when a subtitle need to display.
void	setOnVideoSizeChangedListener(MediaPlayer.OnVideoSizeChangedListener listener) Register a callback to be invoked when the video size is known or updated.
void	setScreenOnWhilePlaying(boolean screenOn) Control whether we should use the attached SurfaceHolder to keep the screen on while video playback is occurring.
void	setSubEncoding(java.lang.String encoding) Set the encoding to display text subtitle.
void	setSubPath(java.lang.String subPath) Set the file-path of an external subtitle.
void	setSubShown(boolean shown) Tell the MediaPlayer whether to show subtitle
void	setSubTrack(int trackId) Set the subtitle track to display, must be in the result of getSubTrackMap(String)
void	setVideoQuality(int quality) Set the quality when play video, if the video is too lag, you may try VIDEOQUALITY_LOW, default is VIDEOQUALITY_LOW.
void	setVolume(float leftVolume, float rightVolume)
void	setWakeMode(Context context, int mode) Set the low-level power management behavior for this MediaPlayer.
void	start() Starts or resumes playback.
void	stop() The same as pause()

Methods inherited from class java.lang.Object

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

Field Detail

MEDIA_ERROR_UNKNOWN

public static final int MEDIA_ERROR_UNKNOWN

See Also:

Constant Field Values

MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK

public static final int MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK

See Also:

Constant Field Values

MEDIA_INFO_VIDEO_TRACK_LAGGING

public static final int MEDIA_INFO_VIDEO_TRACK_LAGGING

The video is too complex for the decoder: it can't decode frames fast enough. Possibly only the audio plays fine at this stage.

See Also:

MediaPlayer.OnInfoListener, Constant Field Values

MEDIA_INFO_BUFFERING_START

public static final int MEDIA_INFO_BUFFERING_START

MediaPlayer is temporarily pausing playback internally in order to buffer more data.

See Also:

Constant Field Values

MEDIA_INFO_BUFFERING_END

public static final int MEDIA_INFO_BUFFERING_END

MediaPlayer is resuming playback after filling buffers.

See Also:

Constant Field Values

MEDIA_INFO_NOT_SEEKABLE

public static final int MEDIA_INFO_NOT_SEEKABLE

The media cannot be seeked (e.g live stream)

See Also:

MediaPlayer.OnInfoListener, Constant Field Values

VIDEOQUALITY_LOW

public static final int VIDEOQUALITY_LOW

See Also:

Constant Field Values

VIDEOQUALITY_MEDIUM

public static final int VIDEOQUALITY_MEDIUM

See Also:

Constant Field Values

VIDEOQUALITY_HIGH

public static final int VIDEOQUALITY_HIGH

See Also:

Constant Field Values

SUBTITLE_INTERNAL

public static final int SUBTITLE_INTERNAL

The subtitle displayed is embeded in the movie

See Also:

Constant Field Values

SUBTITLE_EXTERNAL

public static final int SUBTITLE_EXTERNAL

The subtitle displayed is an external file

See Also:

Constant Field Values

SUB_TYPES

public static final java.lang.String[] SUB_TYPES

The external subtitle types which Vitamio supports.

Constructor Detail

MediaPlayer

public MediaPlayer(Context ctx)
            throws VitamioInstaller.VitamioNotCompatibleException,
                   VitamioInstaller.VitamioNotFoundException

Default constructor. The same as Android's, except that it will throw VitamioInstaller.VitamioNotCompatibleException if Vitamio not compatible with user's device, VitamioInstaller.VitamioNotFoundException if Vitamio not installed in the device.

When done with the MediaPlayer, you should call release(), to free the resources. If not released, too many MediaPlayer instances may result in an exception.

Throws:

VitamioInstaller.VitamioNotCompatibleException

VitamioInstaller.VitamioNotFoundException

Method Detail

setDisplay

public void setDisplay(SurfaceHolder sh)

Sets the SurfaceHolder to use for displaying the video portion of the media. This call is optional. Not calling it when playing back a video will result in only the audio track being played.

Parameters:

sh - the SurfaceHolder to use for video display

setDataSource

public void setDataSource(Context context,
                          Uri uri)
                   throws java.io.IOException,
                          java.lang.IllegalArgumentException,
                          java.lang.SecurityException,
                          java.lang.IllegalStateException

Sets the data source as a content Uri.

Parameters:

context - the Context to use when resolving the Uri

uri - the Content URI of the data you want to play

Throws:

java.lang.IllegalStateException - if it is called in an invalid state

java.io.IOException

java.lang.IllegalArgumentException

java.lang.SecurityException

setDataSource

public void setDataSource(java.lang.String path)
                   throws java.io.IOException,
                          java.lang.IllegalArgumentException,
                          java.lang.IllegalStateException

Sets the data source (file-path or http/rtsp/mms URL) to use.

Parameters:

path - the path of the file, or the http/rtsp/mms URL of the stream you want to play

Throws:

java.lang.IllegalStateException - if it is called in an invalid state

java.io.IOException

java.lang.IllegalArgumentException

setDataSource

public void setDataSource(java.io.FileDescriptor fd)
                   throws java.io.IOException,
                          java.lang.IllegalArgumentException,
                          java.lang.IllegalStateException

Sets the data source (FileDescriptor) to use. It is the caller's responsibility to close the file descriptor. It is safe to do so as soon as this call returns.

Parameters:

fd - the FileDescriptor for the file you want to play

Throws:

java.lang.IllegalStateException - if it is called in an invalid state

java.io.IOException

java.lang.IllegalArgumentException

prepare

public void prepare()
             throws java.io.IOException,
                    java.lang.IllegalStateException

Prepares the player for playback, synchronously. After setting the datasource and the display surface, you need to either call prepare() or prepareAsync(). For files, it is OK to call prepare(), which blocks until MediaPlayer is ready for playback.

Throws:

java.lang.IllegalStateException - if it is called in an invalid state

java.io.IOException

prepareAsync

public void prepareAsync()
                  throws java.lang.IllegalStateException

Prepares the player for playback, asynchronously. After setting the datasource and the display surface, you need to either call prepare() or prepareAsync(). For streams, you should call prepareAsync(), which returns immediately, rather than blocking until enough data has been buffered.

Throws:

java.lang.IllegalStateException - if it is called in an invalid state

start

public void start()
           throws java.lang.IllegalStateException

Starts or resumes playback. If playback had previously been paused, playback will continue from where it was paused. If playback had been stopped, or never started before, playback will start at the beginning.

Throws:

java.lang.IllegalStateException - if it is called in an invalid state

stop

public void stop()
          throws java.lang.IllegalStateException

The same as pause()

Throws:

java.lang.IllegalStateException - if the internal player engine has not been initialized.

pause

public void pause()
           throws java.lang.IllegalStateException

Pauses playback. Call start() to resume.

Throws:

java.lang.IllegalStateException - if the internal player engine has not been initialized.

setWakeMode

public void setWakeMode(Context context,
                        int mode)

Set the low-level power management behavior for this MediaPlayer. This can be used when the MediaPlayer is not playing through a SurfaceHolder set with setDisplay(SurfaceHolder) and thus can use the high-level setScreenOnWhilePlaying(boolean) feature. This function has the MediaPlayer access the low-level power manager service to control the device's power usage while playing is occurring. The parameter is a combination of android.os.PowerManager wake flags. Use of this method requires android.Manifest.permission#WAKE_LOCK permission. By default, no attempt is made to keep the device awake during playback.

Parameters:

context - the Context to use

mode - the power/wake mode to set

See Also:

android.os.PowerManager

setScreenOnWhilePlaying

public void setScreenOnWhilePlaying(boolean screenOn)

Control whether we should use the attached SurfaceHolder to keep the screen on while video playback is occurring. This is the preferred method over setWakeMode(Context, int) where possible, since it doesn't require that the application have permission for low-level wake lock access.

Parameters:

screenOn - Supply true to keep the screen on, false to allow it to turn off.

getVideoWidth

public int getVideoWidth()

Returns the width of the video.

Returns:

the width of the video, or 0 if there is no video, or the width has not been determined yet. The OnVideoSizeChangedListener can be registered via setOnVideoSizeChangedListener(OnVideoSizeChangedListener) to provide a notification when the width is available.

getVideoHeight

public int getVideoHeight()

Returns the height of the video.

Returns:

the height of the video, or 0 if there is no video, or the height has not been determined yet. The OnVideoSizeChangedListener can be registered via setOnVideoSizeChangedListener(OnVideoSizeChangedListener) to provide a notification when the height is available.

isPlaying

public boolean isPlaying()

Checks whether the MediaPlayer is playing.

Returns:

true if currently playing, false otherwise

seekTo

public void seekTo(long msec)
            throws java.lang.IllegalStateException

Seeks to specified time position.

Parameters:

msec - the offset in milliseconds from the start to seek to

Throws:

java.lang.IllegalStateException - if the internal player engine has not been initialized

getCurrentPosition

public long getCurrentPosition()

Gets the current playback position.

Returns:

the current position in milliseconds

getDuration

public long getDuration()

Gets the duration of the file.

Returns:

the duration in milliseconds

release

public void release()

Releases resources associated with this MediaPlayer object. It is considered good practice to call this method when you're done using the MediaPlayer.

reset

public void reset()

Resets the MediaPlayer to its uninitialized state. After calling this method, you will have to initialize it again by setting the data source and calling prepare().

setVolume

public void setVolume(float leftVolume,
                      float rightVolume)

setOnPreparedListener

public void setOnPreparedListener(MediaPlayer.OnPreparedListener listener)

Register a callback to be invoked when the media source is ready for playback.

Parameters:

listener - the callback that will be run

setOnCompletionListener

public void setOnCompletionListener(MediaPlayer.OnCompletionListener listener)

Register a callback to be invoked when the end of a media source has been reached during playback.

Parameters:

listener - the callback that will be run

setOnBufferingUpdateListener

public void setOnBufferingUpdateListener(MediaPlayer.OnBufferingUpdateListener listener)

Register a callback to be invoked when the status of a network stream's buffer has changed.

Parameters:

listener - the callback that will be run.

setOnSeekCompleteListener

public void setOnSeekCompleteListener(MediaPlayer.OnSeekCompleteListener listener)

Register a callback to be invoked when a seek operation has been completed.

Parameters:

listener - the callback that will be run

setOnVideoSizeChangedListener

public void setOnVideoSizeChangedListener(MediaPlayer.OnVideoSizeChangedListener listener)

Register a callback to be invoked when the video size is known or updated.

Parameters:

listener - the callback that will be run

setOnErrorListener

public void setOnErrorListener(MediaPlayer.OnErrorListener listener)

Register a callback to be invoked when an error has happened during an asynchronous operation.

Parameters:

listener - the callback that will be run

setOnInfoListener

public void setOnInfoListener(MediaPlayer.OnInfoListener listener)

setOnSubtitleUpdateListener

public void setOnSubtitleUpdateListener(MediaPlayer.OnSubtitleUpdateListener listener)

Register a callback to be invoked when a subtitle need to display.

Parameters:

listener - the callback that will be run

releaseDisplay

public void releaseDisplay()

Calling this result in only the audio track being played.

getVideoAspectRatio

public float getVideoAspectRatio()

Returns the aspect ratio of the video.

Returns:

the aspect ratio of the video, or 0 if there is no video, or the width and height is not available. io.vov.vitamio.VideoView#setVideoLayout(int, float)

setVideoQuality

public void setVideoQuality(int quality)

Set the quality when play video, if the video is too lag, you may try VIDEOQUALITY_LOW, default is VIDEOQUALITY_LOW.

Parameters:

quality -

• VIDEOQUALITY_HIGH
• VIDEOQUALITY_MEDIUM
• VIDEOQUALITY_LOW

setBufferSize

public void setBufferSize(int bufSize)

The buffer to fill before playback, default is 1024KB

Parameters:

bufSize - buffer size in Byte

isBuffering

public boolean isBuffering()

Checks whether the buffer is filled

Returns:

false if buffer is filled

getBufferProgress

public int getBufferProgress()

Returns:

the percent

See Also:

MediaPlayer.OnBufferingUpdateListener

setMetaEncoding

public void setMetaEncoding(java.lang.String encoding)

Set the encoding MediaPlayer will use to determine the metadata

Parameters:

encoding - e.g. "UTF-8"

getMetaEncoding

public java.lang.String getMetaEncoding()

Get the encoding if haven't set with setMetaEncoding(String)

Returns:

the encoding

getAudioTrackMap

public java.util.HashMap<java.lang.String,java.lang.Integer> getAudioTrackMap(java.lang.String encoding)

Get the audio tracks embeded in the movie (e.g. "English", 3).

Parameters:

encoding - the encoding to format String, will detect it if null

Returns:

Map of track name and track number

getAudioTrack

public int getAudioTrack()

Get the audio track number in playback

Returns:

track number

setAudioTrack

public void setAudioTrack(int audioIndex)

Set the audio track to play, must be in the result of getAudioTrackMap(String)

Parameters:

audioIndex - the track number

setSubShown

public void setSubShown(boolean shown)

Tell the MediaPlayer whether to show subtitle

Parameters:

shown - true if wanna show

setSubEncoding

public void setSubEncoding(java.lang.String encoding)

Set the encoding to display text subtitle.

Parameters:

encoding - MediaPlayer will detet it if null

getSubLocation

public int getSubLocation()

Returns:

• SUBTITLE_EXTERNAL
• SUBTITLE_INTERNAL

setSubPath

public void setSubPath(java.lang.String subPath)

Set the file-path of an external subtitle.

Parameters:

subPath - must be a local file

getSubPath

public java.lang.String getSubPath()

You can get the file-path of the external subtitle in use.

Returns:

null if no external subtitle

setSubTrack

public void setSubTrack(int trackId)

Set the subtitle track to display, must be in the result of getSubTrackMap(String)

Parameters:

audioIndex - the track number

getSubTrack

public int getSubTrack()

Get the subtitle track number in playback

Returns:

track number

getSubTrackMap

public java.util.HashMap<java.lang.String,java.lang.Integer> getSubTrackMap(java.lang.String encoding)

Get the subtitles embeded in the movie (e.g. "English", 3).

Parameters:

encoding - the encoding to format String, will detect it if null

Returns:

Map of track name and track number