public interface

IBasicMediaPlayer

implements IReleasable
com.h6ah4i.android.media.IBasicMediaPlayer
Known Indirect Subclasses

Summary

Nested Classes
interface IBasicMediaPlayer.OnBufferingUpdateListener Interface definition of a callback to be invoked indicating buffering status of a media resource being streamed over the network. 
interface IBasicMediaPlayer.OnCompletionListener Interface definition for a callback to be invoked when playback of a media source has completed. 
interface IBasicMediaPlayer.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). 
interface IBasicMediaPlayer.OnInfoListener Interface definition of a callback to be invoked to communicate some info and/or warning about the media or its playback. 
interface IBasicMediaPlayer.OnPreparedListener Interface definition for a callback to be invoked when the media source is ready for playback. 
interface IBasicMediaPlayer.OnSeekCompleteListener Interface definition of a callback to be invoked indicating the completion of a seek operation. 
Constants
int MEDIA_ERROR_IO File or network related operation errors.
int MEDIA_ERROR_MALFORMED Bitstream is not conforming to the related coding standard or file spec.
int MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK The video is streamed and its container is not valid for progressive playback i.e the video's index (e.g moov atom) is not at the start of the file.
int MEDIA_ERROR_SERVER_DIED Media server died.
int MEDIA_ERROR_TIMED_OUT Some operation takes too long to complete, usually more than 3-5 seconds.
int MEDIA_ERROR_UNKNOWN Unspecified media player error.
int MEDIA_ERROR_UNSUPPORTED Bitstream is conforming to the related coding standard or file spec, but the media framework does not support the feature.
int MEDIA_INFO_BAD_INTERLEAVING Bad interleaving means that a media has been improperly interleaved or not interleaved at all, e.g has all the video samples first then all the audio ones.
int MEDIA_INFO_BUFFERING_END MediaPlayer is resuming playback after filling buffers.
int MEDIA_INFO_BUFFERING_START MediaPlayer is temporarily pausing playback internally in order to buffer more data.
int MEDIA_INFO_METADATA_UPDATE A new set of metadata is available.
int MEDIA_INFO_NOT_SEEKABLE The media cannot be seeked (e.g live stream)
int MEDIA_INFO_SUBTITLE_TIMED_OUT Reading the subtitle track takes too long.
int MEDIA_INFO_UNKNOWN Unspecified media player info.
int MEDIA_INFO_UNSUPPORTED_SUBTITLE Subtitle track was not supported by the media framework.
int MEDIA_INFO_VIDEO_RENDERING_START The player just pushed the very first video frame for rendering.
int MEDIA_INFO_VIDEO_TRACK_LAGGING The video is too complex for the decoder: it can't decode frames fast enough.
Public Methods
abstract void attachAuxEffect(int effectId)
Attaches an auxiliary effect to the player.
abstract int getAudioSessionId()
Returns the audio session ID.
abstract int getCurrentPosition()
Gets the current playback position.
abstract int getDuration()
Gets the duration of the file.
abstract boolean isLooping()
Checks whether the MediaPlayer is looping or non-looping.
abstract boolean isPlaying()
Checks whether the MediaPlayer is playing.
abstract void pause()
Pauses playback.
abstract void prepare()
Prepares the player for playback, synchronously.
abstract void prepareAsync()
Prepares the player for playback, asynchronously.
abstract void release()
Releases resources associated with this MediaPlayer object.
abstract void reset()
Resets the MediaPlayer to its uninitialized state.
abstract void seekTo(int msec)
Seeks to specified time position.
abstract void setAudioAttributes(AudioAttributes attributes)
Sets the audio attributes for this MediaPlayer.
abstract void setAudioSessionId(int sessionId)
Sets the audio session ID.
abstract void setAudioStreamType(int streamtype)
Sets the audio stream type for this MediaPlayer.
abstract void setAuxEffectSendLevel(float level)
Sets the send level of the player to the attached auxiliary effect.
abstract void setDataSource(FileDescriptor fd)
Sets the data source (FileDescriptor) to use.
abstract void setDataSource(FileDescriptor fd, long offset, long length)
Sets the data source (FileDescriptor) to use.
abstract void setDataSource(String path)
Sets the data source (file-path or http/rtsp URL) to use.
abstract void setDataSource(Context context, Uri uri)
Sets the data source as a content Uri.
abstract void setLooping(boolean looping)
Sets the player to be looping or non-looping.
abstract void setNextMediaPlayer(IBasicMediaPlayer next)
Set the MediaPlayer to start when this MediaPlayer finishes playback (i.e.
abstract void setOnBufferingUpdateListener(IBasicMediaPlayer.OnBufferingUpdateListener listener)
Register a callback to be invoked when the status of a network stream's buffer has changed.
abstract void setOnCompletionListener(IBasicMediaPlayer.OnCompletionListener listener)
Register a callback to be invoked when the end of a media source has been reached during playback.
abstract void setOnErrorListener(IBasicMediaPlayer.OnErrorListener listener)
Register a callback to be invoked when an error has happened during an asynchronous operation.
abstract void setOnInfoListener(IBasicMediaPlayer.OnInfoListener listener)
Register a callback to be invoked when an info/warning is available.
abstract void setOnPreparedListener(IBasicMediaPlayer.OnPreparedListener listener)
Register a callback to be invoked when the media source is ready for playback.
abstract void setOnSeekCompleteListener(IBasicMediaPlayer.OnSeekCompleteListener listener)
Register a callback to be invoked when a seek operation has been completed.
abstract void setVolume(float leftVolume, float rightVolume)
Sets the volume on this player.
abstract void setWakeMode(Context context, int mode)
Set the low-level power management behavior for this MediaPlayer.
abstract void start()
Starts or resumes playback.
abstract void stop()
Stops playback after playback has been stopped or paused.
[Expand]
Inherited Methods
From interface com.h6ah4i.android.media.IReleasable

Constants

public static final int MEDIA_ERROR_IO

File or network related operation errors.

Constant Value: -1004 (0xfffffc14)

public static final int MEDIA_ERROR_MALFORMED

Bitstream is not conforming to the related coding standard or file spec.

Constant Value: -1007 (0xfffffc11)

public static final int MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK

The video is streamed and its container is not valid for progressive playback i.e the video's index (e.g moov atom) is not at the start of the file.

Constant Value: 200 (0x000000c8)

public static final int MEDIA_ERROR_SERVER_DIED

Media server died. In this case, the application must release the MediaPlayer object and instantiate a new one.

Constant Value: 100 (0x00000064)

public static final int MEDIA_ERROR_TIMED_OUT

Some operation takes too long to complete, usually more than 3-5 seconds.

Constant Value: -110 (0xffffff92)

public static final int MEDIA_ERROR_UNKNOWN

Unspecified media player error.

Constant Value: 1 (0x00000001)

public static final int MEDIA_ERROR_UNSUPPORTED

Bitstream is conforming to the related coding standard or file spec, but the media framework does not support the feature.

Constant Value: -1010 (0xfffffc0e)

public static final int MEDIA_INFO_BAD_INTERLEAVING

Bad interleaving means that a media has been improperly interleaved or not interleaved at all, e.g has all the video samples first then all the audio ones. Video is playing but a lot of disk seeks may be happening.

Constant Value: 800 (0x00000320)

public static final int MEDIA_INFO_BUFFERING_END

MediaPlayer is resuming playback after filling buffers.

Constant Value: 702 (0x000002be)

public static final int MEDIA_INFO_BUFFERING_START

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

Constant Value: 701 (0x000002bd)

public static final int MEDIA_INFO_METADATA_UPDATE

A new set of metadata is available.

Constant Value: 802 (0x00000322)

public static final int MEDIA_INFO_NOT_SEEKABLE

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

Constant Value: 801 (0x00000321)

public static final int MEDIA_INFO_SUBTITLE_TIMED_OUT

Reading the subtitle track takes too long.

Constant Value: 902 (0x00000386)

public static final int MEDIA_INFO_UNKNOWN

Unspecified media player info.

Constant Value: 1 (0x00000001)

public static final int MEDIA_INFO_UNSUPPORTED_SUBTITLE

Subtitle track was not supported by the media framework.

Constant Value: 901 (0x00000385)

public static final int MEDIA_INFO_VIDEO_RENDERING_START

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

Constant Value: 3 (0x00000003)

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.

Constant Value: 700 (0x000002bc)

Public Methods

public abstract void attachAuxEffect (int effectId)

Attaches an auxiliary effect to the player. A typical auxiliary effect is a reverberation effect which can be applied on any sound source that directs a certain amount of its energy to this effect. This amount is defined by setAuxEffectSendLevel().

After creating an auxiliary effect (e.g. android.media.audiofx.EnvironmentalReverb), retrieve its ID with getId() and use it when calling this method to attach the player to the effect.

To detach the effect from the player, call this method with a null effect id.

This method must be called after one of the overloaded setDataSource methods.

Parameters
effectId system wide unique id of the effect to attach

public abstract int getAudioSessionId ()

Returns the audio session ID.

Returns
  • the audio session ID. Note that the audio session ID is 0 only if a problem occurred when the MediaPlayer was contructed.

public abstract int getCurrentPosition ()

Gets the current playback position.

Returns
  • the current position in milliseconds

public abstract int getDuration ()

Gets the duration of the file.

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

public abstract boolean isLooping ()

Checks whether the MediaPlayer is looping or non-looping.

Returns
  • true if the MediaPlayer is currently looping, false otherwise

public abstract boolean isPlaying ()

Checks whether the MediaPlayer is playing.

Returns
  • true if currently playing, false otherwise
Throws
IllegalStateException if the internal player engine has not been initialized or has been released.

public abstract void pause ()

Pauses playback. Call start() to resume.

Throws
IllegalStateException if the internal player engine has not been initialized.

public abstract void prepare ()

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
IllegalStateException if it is called in an invalid state
IOException

public abstract void prepareAsync ()

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
IllegalStateException if it is called in an invalid state

public abstract 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.

public abstract 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().

public abstract void seekTo (int msec)

Seeks to specified time position.

Parameters
msec the offset in milliseconds from the start to seek to
Throws
IllegalStateException if the internal player engine has not been initialized

public abstract void setAudioAttributes (AudioAttributes attributes)

Sets the audio attributes for this MediaPlayer. See AudioAttributes for how to build and configure an instance of this class. You must call this method before prepare() or prepareAsync() in order for the audio attributes to become effective thereafter.

Parameters
attributes a non-null set of audio attributes

public abstract void setAudioSessionId (int sessionId)

Sets the audio session ID.

Parameters
sessionId the audio session ID. The audio session ID is a system wide unique identifier for the audio stream played by this MediaPlayer instance. The primary use of the audio session ID is to associate audio effects to a particular instance of MediaPlayer: if an audio session ID is provided when creating an audio effect, this effect will be applied only to the audio content of media players within the same audio session and not to the output mix. When created, a MediaPlayer instance automatically generates its own audio session ID. However, it is possible to force this player to be part of an already existing audio session by calling this method. This method must be called before one of the overloaded setDataSource methods.
Throws
IllegalStateException if it is called in an invalid state
IllegalArgumentException

public abstract void setAudioStreamType (int streamtype)

Sets the audio stream type for this MediaPlayer. See AudioManager for a list of stream types. Must call this method before prepare() or prepareAsync() in order for the target stream type to become effective thereafter.

Parameters
streamtype the audio stream type
See Also
  • android.media.AudioManager

public abstract void setAuxEffectSendLevel (float level)

Sets the send level of the player to the attached auxiliary effect. The level value range is 0 to 1.0.

By default the send level is 0, so even if an effect is attached to the player this method must be called for the effect to be applied.

Note that the passed level value is a raw scalar. UI controls should be scaled logarithmically: the gain applied by audio framework ranges from -72dB to 0dB, so an appropriate conversion from linear UI input x to level is: x == 0 -> level = 0 0 < x <= R -> level = 10^(72*(x-R)/20/R)

Parameters
level send level scalar

public abstract void setDataSource (FileDescriptor fd)

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
IllegalStateException if it is called in an invalid state
IOException
IllegalArgumentException

public abstract void setDataSource (FileDescriptor fd, long offset, long length)

Sets the data source (FileDescriptor) to use. The FileDescriptor must be seekable (N.B. a LocalSocket is not seekable). 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
offset the offset into the file where the data to be played starts, in bytes
length the length in bytes of the data to be played
Throws
IllegalStateException if it is called in an invalid state
IOException
IllegalArgumentException

public abstract void setDataSource (String path)

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

Parameters
path the path of the file, or the http/rtsp URL of the stream you want to play
Throws
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).

IOException
IllegalArgumentException

public abstract void setDataSource (Context context, Uri uri)

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
IllegalStateException if it is called in an invalid state
IOException
IllegalArgumentException
SecurityException

public abstract void setLooping (boolean looping)

Sets the player to be looping or non-looping.

Parameters
looping whether to loop or not

public abstract void setNextMediaPlayer (IBasicMediaPlayer next)

Set the MediaPlayer to start when this MediaPlayer finishes playback (i.e. reaches the end of the stream). The media framework will attempt to transition from this player to the next as seamlessly as possible. The next player can be set at any time before completion. The next player must be prepared by the app, and the application should not call start() on it. The next MediaPlayer must be different from 'this'. An exception will be thrown if next == this. The application may call setNextMediaPlayer(null) to indicate no next player should be started at the end of playback. If the current player is looping, it will keep looping and the next player will not be started.

Parameters
next the player to start after this one completes playback.

public abstract void setOnBufferingUpdateListener (IBasicMediaPlayer.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.

public abstract void setOnCompletionListener (IBasicMediaPlayer.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

public abstract void setOnErrorListener (IBasicMediaPlayer.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

public abstract void setOnInfoListener (IBasicMediaPlayer.OnInfoListener listener)

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

Parameters
listener the callback that will be run

public abstract void setOnPreparedListener (IBasicMediaPlayer.OnPreparedListener listener)

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

Parameters
listener the callback that will be run

public abstract void setOnSeekCompleteListener (IBasicMediaPlayer.OnSeekCompleteListener listener)

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

Parameters
listener the callback that will be run

public abstract 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 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

public abstract void setWakeMode (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 android.os.PowerManager wake flags. Use of this method requires 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

public abstract void start ()

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
IllegalStateException if it is called in an invalid state

public abstract void stop ()

Stops playback after playback has been stopped or paused.

Throws
IllegalStateException if the internal player engine has not been initialized.