io.vov.vitamio
Class MediaPlayer

java.lang.Object
  extended by 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 -

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:

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