com.pili.pldroid.player

Class PLMediaPlayer

java.lang.Object

com.pili.pldroid.player.PLMediaPlayer

public class PLMediaPlayer
extends java.lang.Object

PLMediaPlayer class can be used to control playback of audio/video files and streams.

This class will function the same as android.media.MediaPlayer in most cases. Please see Audio and Video for additional help using PLMediaPlayer.

Permissions

One may need to declare a corresponding WAKE_LOCK permission

This class requires the Manifest.permission.INTERNET permission when used with network-based content.

Callbacks

Applications may want to register for informational and error events in order to be informed of some internal state update and possible runtime errors during playback or streaming. Registration for these events is done by properly setting the appropriate listeners.

1. setOnPreparedListener(OnPreparedListener),
2. setOnVideoSizeChangedListener(OnVideoSizeChangedListener),
3. setOnSeekCompleteListener(OnSeekCompleteListener),
4. setOnCompletionListener(OnCompletionListener),
5. setOnBufferingUpdateListener(OnBufferingUpdateListener),
6. setOnInfoListener(OnInfoListener),
7. setOnErrorListener(OnErrorListener)
8. .etc

Usage

The calling sequence of the class should be:

1. Construct PLMediaPlayer() or PLMediaPlayer(AVOptions)
2. setDataSource(String) or setDataSource(Context, Uri) etc.
3. setDisplay(SurfaceHolder) or setSurface(Surface)
4. setOnPreparedListener(com.pili.pldroid.player.PLMediaPlayer.OnPreparedListener)
5. prepareAsync()
6. start()/seekTo(long)/pause()/stop()/etc.
7. release()

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	PLMediaPlayer.OnBufferingUpdateListener Interface definition of a callback to be invoked indicating buffering status of a media resource being streamed over the network.
static interface	PLMediaPlayer.OnCompletionListener Interface definition for a callback to be invoked when playback of a media source has completed.
static interface	PLMediaPlayer.OnErrorListener Interface definition of a callback to be invoked when there has been an error during an asynchronous operation (other errors will throw exceptions at method call time).
static interface	PLMediaPlayer.OnInfoListener Interface definition of a callback to be invoked to communicate some info and/or warning about the media or its playback.
static interface	PLMediaPlayer.OnPreparedListener Interface definition for a callback to be invoked when the media source is ready for playback.
static interface	PLMediaPlayer.OnSeekCompleteListener Interface definition of a callback to be invoked indicating the completion of a seek operation.
static interface	PLMediaPlayer.OnVideoSizeChangedListener Interface definition of a callback to be invoked when the video size is first known or updated

Field Summary

Fields

Modifier and Type	Field and Description
static int	ERROR_CODE_404_NOT_FOUND 404 resource not found
static int	ERROR_CODE_CONNECTION_REFUSED Connection refused
static int	ERROR_CODE_CONNECTION_TIMEOUT Connection timeout
static int	ERROR_CODE_EMPTY_PLAYLIST Playlist is empty
static int	ERROR_CODE_INVALID_URI Invalid URL.
static int	ERROR_CODE_IO_ERROR Network error
static int	ERROR_CODE_STREAM_DISCONNECTED Disconnected with the server
static int	MEDIA_ERROR_UNKNOWN Unspecified media player error.
static int	MEDIA_INFO_AUDIO_RENDERING_START The player just output the very first audio frame.
static int	MEDIA_INFO_BUFFERING_BYTES_UPDATE Buffered bytes are updated now.
static int	MEDIA_INFO_BUFFERING_END The player is resuming playback after filling buffers.
static int	MEDIA_INFO_BUFFERING_START The player is temporarily pausing playback internally in order to buffer more data.
static int	MEDIA_INFO_NOT_SEEKABLE The media cannot be seek (e.g live stream)
static int	MEDIA_INFO_UNKNOWN Unspecified media player info.
static int	MEDIA_INFO_VIDEO_RENDERING_START The player just pushed the very first video frame for rendering.
static int	MEDIA_INFO_VIDEO_ROTATION_CHANGED The video rotation is changed

Constructor Summary

Constructors

Constructor and Description
PLMediaPlayer() Default constructor.
PLMediaPlayer(AVOptions options) Constructor with AVOptions.

Method Summary

Modifier and Type	Method and Description
long	getCurrentPosition() Gets the current playback position.
java.lang.String	getDataSource() Gets data source.
long	getDuration() Gets the duration of the file or stream.
int	getVideoHeight() Returns the height of the video.
int	getVideoWidth() Returns the width of the video.
boolean	isLooping() Checks whether the PLMediaPlayer is looping or non-looping.
boolean	isPlaying() Checks whether the MediaPlayer is playing.
void	pause() Pauses playback.
void	prepareAsync() Prepares the player for playback, asynchronously.
void	release() Releases resources associated with this MediaPlayer object.
void	reset() Resets the PLMediaPlayer to its uninitialized state.
void	seekTo(long msec) Seeks to specified time position.
void	setDataSource(android.content.Context context, android.net.Uri uri) Sets the data source as a content Uri.
void	setDataSource(android.content.Context context, android.net.Uri uri, java.util.Map<java.lang.String,java.lang.String> headers) 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/rtmp URL) to use.
void	setDisplay(android.view.SurfaceHolder sh) Sets the SurfaceHolder to use for displaying the video portion of the media.
void	setLooping(boolean looping) Sets the player to be looping or non-looping.
void	setOnBufferingUpdateListener(PLMediaPlayer.OnBufferingUpdateListener listener) Register a callback to be invoked when the status of a network stream's buffer has changed.
void	setOnCompletionListener(PLMediaPlayer.OnCompletionListener listener) Register a callback to be invoked when the end of a media source has been reached during playback.
void	setOnErrorListener(PLMediaPlayer.OnErrorListener listener) Register a callback to be invoked when an error has happened during an asynchronous operation.
void	setOnInfoListener(PLMediaPlayer.OnInfoListener listener) Register a callback to be invoked when an info/warning is available.
void	setOnPreparedListener(PLMediaPlayer.OnPreparedListener listener) Register a callback to be invoked when the media source is ready for playback.
void	setOnSeekCompleteListener(PLMediaPlayer.OnSeekCompleteListener listener) Register a callback to be invoked when a seek operation has been completed.
void	setOnVideoSizeChangedListener(PLMediaPlayer.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	setSurface(android.view.Surface surface) Sets the Surface to be used as the sink for the video portion of the media.
void	setVolume(float leftVolume, float rightVolume) Sets the volume on this player.
void	setWakeMode(android.content.Context context, int mode) Set the low-level power management behavior for this MediaPlayer.
void	start() Starts or resumes playback.
void	stop() Stops playback.

Methods inherited from class java.lang.Object

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

Field Detail

MEDIA_INFO_UNKNOWN

public static final int MEDIA_INFO_UNKNOWN

Unspecified media player info.

See Also:

PLMediaPlayer.OnInfoListener, Constant Field Values

MEDIA_INFO_VIDEO_RENDERING_START

public static final int MEDIA_INFO_VIDEO_RENDERING_START

The player just pushed the very first video frame for rendering.

See Also:

PLMediaPlayer.OnInfoListener, Constant Field Values

MEDIA_INFO_BUFFERING_BYTES_UPDATE

public static final int MEDIA_INFO_BUFFERING_BYTES_UPDATE

Buffered bytes are updated now.

See Also:

PLMediaPlayer.OnInfoListener, Constant Field Values

MEDIA_INFO_BUFFERING_START

public static final int MEDIA_INFO_BUFFERING_START

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

See Also:

PLMediaPlayer.OnInfoListener, Constant Field Values

MEDIA_INFO_BUFFERING_END

public static final int MEDIA_INFO_BUFFERING_END

The player is resuming playback after filling buffers.

See Also:

PLMediaPlayer.OnInfoListener, Constant Field Values

MEDIA_INFO_NOT_SEEKABLE

public static final int MEDIA_INFO_NOT_SEEKABLE

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

See Also:

PLMediaPlayer.OnInfoListener, Constant Field Values

MEDIA_INFO_VIDEO_ROTATION_CHANGED

public static final int MEDIA_INFO_VIDEO_ROTATION_CHANGED

The video rotation is changed

See Also:

PLMediaPlayer.OnInfoListener, Constant Field Values

MEDIA_INFO_AUDIO_RENDERING_START

public static final int MEDIA_INFO_AUDIO_RENDERING_START

The player just output the very first audio frame.

See Also:

PLMediaPlayer.OnInfoListener, Constant Field Values

MEDIA_ERROR_UNKNOWN

public static final int MEDIA_ERROR_UNKNOWN

Unspecified media player error.

See Also:

PLMediaPlayer.OnErrorListener, Constant Field Values

ERROR_CODE_INVALID_URI

public static final int ERROR_CODE_INVALID_URI

Invalid URL.

See Also:

PLMediaPlayer.OnErrorListener, Constant Field Values

ERROR_CODE_IO_ERROR

public static final int ERROR_CODE_IO_ERROR

Network error

See Also:

PLMediaPlayer.OnErrorListener, Constant Field Values

ERROR_CODE_STREAM_DISCONNECTED

public static final int ERROR_CODE_STREAM_DISCONNECTED

Disconnected with the server

See Also:

PLMediaPlayer.OnErrorListener, Constant Field Values

ERROR_CODE_EMPTY_PLAYLIST

public static final int ERROR_CODE_EMPTY_PLAYLIST

Playlist is empty

See Also:

PLMediaPlayer.OnErrorListener, Constant Field Values

ERROR_CODE_404_NOT_FOUND

public static final int ERROR_CODE_404_NOT_FOUND

404 resource not found

See Also:

PLMediaPlayer.OnErrorListener, Constant Field Values

ERROR_CODE_CONNECTION_REFUSED

public static final int ERROR_CODE_CONNECTION_REFUSED

Connection refused

See Also:

PLMediaPlayer.OnErrorListener, Constant Field Values

ERROR_CODE_CONNECTION_TIMEOUT

public static final int ERROR_CODE_CONNECTION_TIMEOUT

Connection timeout

See Also:

PLMediaPlayer.OnErrorListener, Constant Field Values

Constructor Detail

PLMediaPlayer

public PLMediaPlayer()

Default constructor.

When done with the PLMediaPlayer, you should call release(), to free the resources.

PLMediaPlayer

public PLMediaPlayer(AVOptions options)

Constructor with AVOptions.

When done with the PLMediaPlayer, you should call release(), to free the resources.

Parameters:

options - the options

Method Detail

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. In particular, whenever an Activity of an application is paused (its onPause() method is called), or stopped (its onStop() method is called), this method should be invoked to release the MediaPlayer object, unless the application has a special need to keep the object around. In addition to unnecessary resources (such as memory and instances of codecs) being held, failure to call this method immediately if a MediaPlayer object is no longer needed may also lead to continuous battery consumption for mobile devices, and playback failure for other applications if no multiple instances of the same codec are supported on a device. Even if multiple instances of the same codec are supported, some performance degradation may be expected when unnecessary multiple instances are used at the same time.

setDisplay

public void setDisplay(android.view.SurfaceHolder sh)

Sets the SurfaceHolder to use for displaying the video portion of the media.

Either a surface holder or surface must be set if a display or video sink is needed. Not calling this method or setSurface(Surface) when playing back a video will result in only the audio track being played. A null surface holder or surface will result in only the audio track being played.

Parameters:

sh - the SurfaceHolder to use for video display

setSurface

public void setSurface(android.view.Surface surface)

Sets the Surface to be used as the sink for the video portion of the media. This is similar to setDisplay(SurfaceHolder). Setting a Surface will un-set any Surface or SurfaceHolder that was previously set. A null surface will result in only the audio track being played.

If the Surface sends frames to a SurfaceTexture, the timestamps returned from SurfaceTexture.getTimestamp() will have an unspecified zero point. These timestamps cannot be directly compared between different media sources, different instances of the same media source, or multiple runs of the same program. The timestamp is normally monotonically increasing and is unaffected by time-of-day adjustments, but it is reset when the position is set.

Parameters:

surface - The Surface to be used for the video portion of the media.

setWakeMode

public void setWakeMode(android.content.Context context,
                        int mode)

Set the low-level power management behavior for this MediaPlayer.

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 PowerManager wake flags. Use of this method requires 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:

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(android.content.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.

setDataSource

public void setDataSource(android.content.Context context,
                          android.net.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.io.IOException - the io exception

java.lang.IllegalArgumentException - the illegal argument exception

java.lang.SecurityException - the security exception

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

setDataSource

public void setDataSource(android.content.Context context,
                          android.net.Uri uri,
                          java.util.Map<java.lang.String,java.lang.String> headers)
                   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

headers - the headers to be sent together with the request for the data Note that the cross domain redirection is allowed by default, but that can be changed with key/value pairs through the headers parameter with "android-allow-cross-domain-redirect" as the key and "0" or "1" as the value to disallow or allow cross domain redirection.

Throws:

java.io.IOException - the io exception

java.lang.IllegalArgumentException - the illegal argument exception

java.lang.SecurityException - the security exception

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

setDataSource

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

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

Parameters:

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

Throws:

java.io.IOException - the io exception

java.lang.IllegalArgumentException - the illegal argument exception

java.lang.SecurityException - the security exception

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

When path refers to a local file, the file may actually be opened by a process other than the calling application. This implies that the pathname should be an absolute path (as any other process runs with unspecified current working directory), and that the pathname should reference a world-readable file. As an alternative, the application could first open the file for reading, and then use the file descriptor form setDataSource(FileDescriptor).

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.io.IOException - the io exception

java.lang.IllegalArgumentException - the illegal argument exception

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

getDataSource

public java.lang.String getDataSource()

Gets data source.

Returns:

the data source

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 call prepareAsync(). This method starts preparing the media in the background and returns immediately. When the media is done preparing, the onPrepared() method of the MediaPlayer.OnPreparedListener is called, which is configured through setOnPreparedListener(OnPreparedListener)

Throws:

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

setVolume

public void setVolume(float leftVolume,
                      float rightVolume)

Sets the volume on this player. This API is recommended for balancing the output of audio streams within an application. Unless you are writing an application to control user settings, this API should be used in preference to AudioManager.setStreamVolume(int, int, int) which sets the volume of ALL streams of a particular type. Note that the passed volume values are raw scalars in range 0.0 to 1.0. UI controls should be scaled logarithmically.

Parameters:

leftVolume - left volume scalar

rightVolume - right volume scalar

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

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.

stop

public void stop()
          throws java.lang.IllegalStateException

Stops playback.

Throws:

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

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

reset

public void reset()

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

getVideoWidth

public int getVideoWidth()

Returns the width of the video.

Returns:

the width of the video, or 0 if there is no video, no display surface was set, 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, no display surface was set, 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

Throws:

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

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 or stream.

Returns:

the duration in milliseconds, if no duration is available for example, if streaming live content, -1 is returned.

setLooping

public void setLooping(boolean looping)

Sets the player to be looping or non-looping.

Parameters:

looping - whether to loop or not

isLooping

public boolean isLooping()

Checks whether the PLMediaPlayer is looping or non-looping.

Returns:

true if the PLMediaPlayer is currently looping, false otherwise

setOnInfoListener

public void setOnInfoListener(PLMediaPlayer.OnInfoListener listener)

Register a callback to be invoked when an info/warning is available.

Parameters:

listener - the callback that will be run

setOnPreparedListener

public void setOnPreparedListener(PLMediaPlayer.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(PLMediaPlayer.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(PLMediaPlayer.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(PLMediaPlayer.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(PLMediaPlayer.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(PLMediaPlayer.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