Topics covered here are: *
For more information about how to use MediaPlayer, read the * Media Playback developer guide.
*Playback control of audio/video files and streams is managed as a state * machine. The following diagram shows the life cycle and the states of a * MediaPlayer object driven by the supported playback control operations. * The ovals represent the states a MediaPlayer object may reside * in. The arcs represent the playback control operations that drive the object * state transition. There are two types of arcs. The arcs with a single arrow * head represent synchronous method calls, while those with * a double arrow head represent asynchronous method calls.
* *
From this state diagram, one can see that a MediaPlayer object has the * following states:
*new or
* after {@link #reset()} is called, it is in the Idle state; and after
* {@link #release()} is called, it is in the End state. Between these
* two states is the life cycle of the MediaPlayer object.
* new is in the
* Idle state, while those created with one
* of the overloaded convenient create methods are NOT
* in the Idle state. In fact, the objects are in the Prepared
* state if the creation using create method is successful.
* setDataSource
* methods in an invalid state. IllegalArgumentException
* and IOException that may be thrown from the overloaded
* setDataSource methods.| Method Name | *Valid Sates | *Invalid States | *Comments |
| attachAuxEffect | *{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted} | *{Idle, Error} | *This method must be called after setDataSource. * Calling it does not change the object state. |
| getAudioSessionId | *any | *{} | *This method can be called in any state and calling it does not change * the object state. |
| getCurrentPosition | *{Idle, Initialized, Prepared, Started, Paused, Stopped, * PlaybackCompleted} | *{Error} | *Successful invoke of this method in a valid state does not change the * state. Calling this method in an invalid state transfers the object * to the Error state. |
| getDuration | *{Prepared, Started, Paused, Stopped, PlaybackCompleted} | *{Idle, Initialized, Error} | *Successful invoke of this method in a valid state does not change the * state. Calling this method in an invalid state transfers the object * to the Error state. |
| getVideoHeight | *{Idle, Initialized, Prepared, Started, Paused, Stopped, * PlaybackCompleted} | *{Error} | *Successful invoke of this method in a valid state does not change the * state. Calling this method in an invalid state transfers the object * to the Error state. |
| getVideoWidth | *{Idle, Initialized, Prepared, Started, Paused, Stopped, * PlaybackCompleted} | *{Error} | *Successful invoke of this method in a valid state does not change * the state. Calling this method in an invalid state transfers the * object to the Error state. |
| isPlaying | *{Idle, Initialized, Prepared, Started, Paused, Stopped, * PlaybackCompleted} | *{Error} | *Successful invoke of this method in a valid state does not change * the state. Calling this method in an invalid state transfers the * object to the Error state. |
| pause | *{Started, Paused} | *{Idle, Initialized, Prepared, Stopped, PlaybackCompleted, Error} | *Successful invoke of this method in a valid state transfers the * object to the Paused state. Calling this method in an * invalid state transfers the object to the Error state. |
| prepare | *{Initialized, Stopped} | *{Idle, Prepared, Started, Paused, PlaybackCompleted, Error} | *Successful invoke of this method in a valid state transfers the * object to the Prepared state. Calling this method in an * invalid state throws an IllegalStateException. |
| prepareAsync | *{Initialized, Stopped} | *{Idle, Prepared, Started, Paused, PlaybackCompleted, Error} | *Successful invoke of this method in a valid state transfers the * object to the Preparing state. Calling this method in an * invalid state throws an IllegalStateException. |
| release | *any | *{} | *After {@link #release()}, the object is no longer available. |
| reset | *{Idle, Initialized, Prepared, Started, Paused, Stopped, * PlaybackCompleted, Error} | *{} | *After {@link #reset()}, the object is like being just created. |
| seekTo | *{Prepared, Started, Paused, PlaybackCompleted} | *{Idle, Initialized, Stopped, Error} | *Successful invoke of this method in a valid state does not change * the state. Calling this method in an invalid state transfers the * object to the Error state. |
| setAudioSessionId | *{Idle} | *{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted, * Error} | *This method must be called in idle state as the audio session ID must be known before * calling setDataSource. Calling it does not change the object state. |
| setAudioStreamType | *{Idle, Initialized, Stopped, Prepared, Started, Paused, * PlaybackCompleted} | *{Error} | *Successful invoke of this method does not change the state. In order for the * target audio stream type to become effective, this method must be called before * prepare() or prepareAsync(). |
| setAuxEffectSendLevel | *any | *{} | *Calling this method does not change the object state. |
| setDataSource | *{Idle} | *{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted, * Error} | *Successful invoke of this method in a valid state transfers the * object to the Initialized state. Calling this method in an * invalid state throws an IllegalStateException. |
| setDisplay | *any | *{} | *This method can be called in any state and calling it does not change * the object state. |
| setSurface | *any | *{} | *This method can be called in any state and calling it does not change * the object state. |
| setLooping | *{Idle, Initialized, Stopped, Prepared, Started, Paused, * PlaybackCompleted} | *{Error} | *Successful invoke of this method in a valid state does not change * the state. Calling this method in an * invalid state transfers the object to the Error state. |
| isLooping | *any | *{} | *This method can be called in any state and calling it does not change * the object state. |
| setOnBufferingUpdateListener | *any | *{} | *This method can be called in any state and calling it does not change * the object state. |
| setOnCompletionListener | *any | *{} | *This method can be called in any state and calling it does not change * the object state. |
| setOnErrorListener | *any | *{} | *This method can be called in any state and calling it does not change * the object state. |
| setOnPreparedListener | *any | *{} | *This method can be called in any state and calling it does not change * the object state. |
| setOnSeekCompleteListener | *any | *{} | *This method can be called in any state and calling it does not change * the object state. |
| setScreenOnWhilePlaying | *any | *{} | *This method can be called in any state and calling it does not change * the object state. |
| setVolume | *{Idle, Initialized, Stopped, Prepared, Started, Paused, * PlaybackCompleted} | *{Error} | *Successful invoke of this method does not change the state. * |
| setWakeMode | *any | *{} | *This method can be called in any state and calling it does not change * the object state. |
| start | *{Prepared, Started, Paused, PlaybackCompleted} | *{Idle, Initialized, Stopped, Error} | *Successful invoke of this method in a valid state transfers the * object to the Started state. Calling this method in an * invalid state transfers the object to the Error state. |
| stop | *{Prepared, Started, Stopped, Paused, PlaybackCompleted} | *{Idle, Initialized, Error} | *Successful invoke of this method in a valid state transfers the * object to the Stopped state. Calling this method in an * invalid state transfers the object to the Error state. |
One may need to declare a corresponding WAKE_LOCK permission {@link * android.R.styleable#AndroidManifestUsesPermission <uses-permission>} * element. * *
This class requires the {@link android.Manifest.permission#INTERNET} permission * when used with network-based content. * * *
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 (via calls * to * {@link #setOnPreparedListener(OnPreparedListener)}setOnPreparedListener, * {@link #setOnVideoSizeChangedListener(OnVideoSizeChangedListener)}setOnVideoSizeChangedListener, * {@link #setOnSeekCompleteListener(OnSeekCompleteListener)}setOnSeekCompleteListener, * {@link #setOnCompletionListener(OnCompletionListener)}setOnCompletionListener, * {@link #setOnBufferingUpdateListener(OnBufferingUpdateListener)}setOnBufferingUpdateListener, * {@link #setOnInfoListener(OnInfoListener)}setOnInfoListener, * {@link #setOnErrorListener(OnErrorListener)}setOnErrorListener, etc). * In order to receive the respective callback * associated with these listeners, applications are required to create * MediaPlayer objects on a thread with its own Looper running (main UI * thread by default has a Looper running). * */ public class MediaPlayer { /** Constant to retrieve only the new metadata since the last call. // FIXME: unhide. // FIXME: add link to getMetadata(boolean, boolean) {@hide} */ public static final boolean METADATA_UPDATE_ONLY = true; /** Constant to retrieve all the metadata. // FIXME: unhide. // FIXME: add link to getMetadata(boolean, boolean) {@hide} */ public static final boolean METADATA_ALL = false; /** Constant to enable the metadata filter during retrieval. // FIXME: unhide. // FIXME: add link to getMetadata(boolean, boolean) {@hide} */ public static final boolean APPLY_METADATA_FILTER = true; /** Constant to disable the metadata filter during retrieval. // FIXME: unhide. // FIXME: add link to getMetadata(boolean, boolean) {@hide} */ public static final boolean BYPASS_METADATA_FILTER = false; static { System.loadLibrary("media_jni"); native_init(); } private final static String TAG = "MediaPlayer"; // Name of the remote interface for the media player. Must be kept // in sync with the 2nd parameter of the IMPLEMENT_META_INTERFACE // macro invocation in IMediaPlayer.cpp private final static String IMEDIA_PLAYER = "android.media.IMediaPlayer"; private int mNativeContext; // accessed by native methods private int mNativeSurfaceTexture; // accessed by native methods private int mListenerContext; // accessed by native methods private SurfaceHolder mSurfaceHolder; private EventHandler mEventHandler; private PowerManager.WakeLock mWakeLock = null; private boolean mScreenOnWhilePlaying; private boolean mStayAwake; /** * Default constructor. Consider using one of the create() methods for * synchronously instantiating a MediaPlayer from a Uri or resource. *
When done with the MediaPlayer, you should call {@link #release()}, * to free the resources. If not released, too many MediaPlayer instances may * result in an exception.
*/ public MediaPlayer() { Looper looper; if ((looper = Looper.myLooper()) != null) { mEventHandler = new EventHandler(this, looper); } else if ((looper = Looper.getMainLooper()) != null) { mEventHandler = new EventHandler(this, looper); } else { mEventHandler = null; } /* Native setup requires a weak reference to our object. * It's easier to create it here than in C++. */ native_setup(new WeakReferenceWhen done with the MediaPlayer, you should call {@link #release()}, * to free the resources. If not released, too many MediaPlayer instances will * result in an exception.
* * @param context the Context to use * @param uri the Uri from which to get the datasource * @return a MediaPlayer object, or null if creation failed */ public static MediaPlayer create(Context context, Uri uri) { return create (context, uri, null); } /** * Convenience method to create a MediaPlayer for a given Uri. * On success, {@link #prepare()} will already have been called and must not be called again. *When done with the MediaPlayer, you should call {@link #release()}, * to free the resources. If not released, too many MediaPlayer instances will * result in an exception.
* * @param context the Context to use * @param uri the Uri from which to get the datasource * @param holder the SurfaceHolder to use for displaying the video * @return a MediaPlayer object, or null if creation failed */ public static MediaPlayer create(Context context, Uri uri, SurfaceHolder holder) { try { MediaPlayer mp = new MediaPlayer(); mp.setDataSource(context, uri); if (holder != null) { mp.setDisplay(holder); } mp.prepare(); return mp; } catch (IOException ex) { Log.d(TAG, "create failed:", ex); // fall through } catch (IllegalArgumentException ex) { Log.d(TAG, "create failed:", ex); // fall through } catch (SecurityException ex) { Log.d(TAG, "create failed:", ex); // fall through } return null; } // Note no convenience method to create a MediaPlayer with SurfaceTexture sink. /** * Convenience method to create a MediaPlayer for a given resource id. * On success, {@link #prepare()} will already have been called and must not be called again. *When done with the MediaPlayer, you should call {@link #release()}, * to free the resources. If not released, too many MediaPlayer instances will * result in an exception.
* * @param context the Context to use * @param resid the raw resource id (R.raw.<something>) for * the resource to use as the datasource * @return a MediaPlayer object, or null if creation failed */ public static MediaPlayer create(Context context, int resid) { try { AssetFileDescriptor afd = context.getResources().openRawResourceFd(resid); if (afd == null) return null; MediaPlayer mp = new MediaPlayer(); mp.setDataSource(afd.getFileDescriptor(), afd.getStartOffset(), afd.getLength()); afd.close(); mp.prepare(); return mp; } catch (IOException ex) { Log.d(TAG, "create failed:", ex); // fall through } catch (IllegalArgumentException ex) { Log.d(TAG, "create failed:", ex); // fall through } catch (SecurityException ex) { Log.d(TAG, "create failed:", ex); // fall through } return null; } /** * Sets the data source as a content Uri. * * @param context the Context to use when resolving the Uri * @param uri the Content URI of the data you want to play * @throws IllegalStateException if it is called in an invalid state */ public void setDataSource(Context context, Uri uri) throws IOException, IllegalArgumentException, SecurityException, IllegalStateException { setDataSource(context, uri, null); } /** * Sets the data source as a content Uri. * * @param context the Context to use when resolving the Uri * @param uri the Content URI of the data you want to play * @param headers the headers to be sent together with the request for the data * @throws IllegalStateException if it is called in an invalid state */ public void setDataSource(Context context, Uri uri, MapThis 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 {@link android.os.PowerManager} wake flags.
* Use of this method requires {@link android.Manifest.permission#WAKE_LOCK}
* permission.
* By default, no attempt is made to keep the device awake during playback.
*
* @param context the Context to use
* @param mode the power/wake mode to set
* @see android.os.PowerManager
*/
public void setWakeMode(Context context, int mode) {
boolean washeld = false;
if (mWakeLock != null) {
if (mWakeLock.isHeld()) {
washeld = true;
mWakeLock.release();
}
mWakeLock = null;
}
PowerManager pm = (PowerManager)context.getSystemService(Context.POWER_SERVICE);
mWakeLock = pm.newWakeLock(mode|PowerManager.ON_AFTER_RELEASE, MediaPlayer.class.getName());
mWakeLock.setReferenceCounted(false);
if (washeld) {
mWakeLock.acquire();
}
}
/**
* Control whether we should use the attached SurfaceHolder to keep the
* screen on while video playback is occurring. This is the preferred
* method over {@link #setWakeMode} where possible, since it doesn't
* require that the application have permission for low-level wake lock
* access.
*
* @param screenOn Supply true to keep the screen on, false to allow it
* to turn off.
*/
public void setScreenOnWhilePlaying(boolean screenOn) {
if (mScreenOnWhilePlaying != screenOn) {
if (screenOn && mSurfaceHolder == null) {
Log.w(TAG, "setScreenOnWhilePlaying(true) is ineffective without a SurfaceHolder");
}
mScreenOnWhilePlaying = screenOn;
updateSurfaceScreenOn();
}
}
private void stayAwake(boolean awake) {
if (mWakeLock != null) {
if (awake && !mWakeLock.isHeld()) {
mWakeLock.acquire();
} else if (!awake && mWakeLock.isHeld()) {
mWakeLock.release();
}
}
mStayAwake = awake;
updateSurfaceScreenOn();
}
private void updateSurfaceScreenOn() {
if (mSurfaceHolder != null) {
mSurfaceHolder.setKeepScreenOn(mScreenOnWhilePlaying && mStayAwake);
}
}
/**
* Returns the width of the video.
*
* @return 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
* {@link #setOnVideoSizeChangedListener(OnVideoSizeChangedListener)}
* to provide a notification when the width is available.
*/
public native int getVideoWidth();
/**
* Returns the height of the video.
*
* @return 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
* {@link #setOnVideoSizeChangedListener(OnVideoSizeChangedListener)}
* to provide a notification when the height is available.
*/
public native int getVideoHeight();
/**
* Checks whether the MediaPlayer is playing.
*
* @return true if currently playing, false otherwise
*/
public native boolean isPlaying();
/**
* Seeks to specified time position.
*
* @param msec the offset in milliseconds from the start to seek to
* @throws IllegalStateException if the internal player engine has not been
* initialized
*/
public native void seekTo(int msec) throws IllegalStateException;
/**
* Gets the current playback position.
*
* @return the current position in milliseconds
*/
public native int getCurrentPosition();
/**
* Gets the duration of the file.
*
* @return the duration in milliseconds
*/
public native int getDuration();
/**
* Gets the media metadata.
*
* @param update_only controls whether the full set of available
* metadata is returned or just the set that changed since the
* last call. See {@see #METADATA_UPDATE_ONLY} and {@see
* #METADATA_ALL}.
*
* @param apply_filter if true only metadata that matches the
* filter is returned. See {@see #APPLY_METADATA_FILTER} and {@see
* #BYPASS_METADATA_FILTER}.
*
* @return The metadata, possibly empty. null if an error occured.
// FIXME: unhide.
* {@hide}
*/
public Metadata getMetadata(final boolean update_only,
final boolean apply_filter) {
Parcel reply = Parcel.obtain();
Metadata data = new Metadata();
if (!native_getMetadata(update_only, apply_filter, reply)) {
reply.recycle();
return null;
}
// Metadata takes over the parcel, don't recycle it unless
// there is an error.
if (!data.parse(reply)) {
reply.recycle();
return null;
}
return data;
}
/**
* Set a filter for the metadata update notification and update
* retrieval. The caller provides 2 set of metadata keys, allowed
* and blocked. The blocked set always takes precedence over the
* allowed one.
* Metadata.MATCH_ALL and Metadata.MATCH_NONE are 2 sets available as
* shorthands to allow/block all or no metadata.
*
* By default, there is no filter set.
*
* @param allow Is the set of metadata the client is interested
* in receiving new notifications for.
* @param block Is the set of metadata the client is not interested
* in receiving new notifications for.
* @return The call status code.
*
// FIXME: unhide.
* {@hide}
*/
public int setMetadataFilter(Set After creating an auxiliary effect (e.g.
* {@link android.media.audiofx.EnvironmentalReverb}), retrieve its ID with
* {@link android.media.audiofx.AudioEffect#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 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)
* @param level send level scalar
*/
public native void setAuxEffectSendLevel(float level);
/**
* @param request Parcel destinated to the media player. The
* Interface token must be set to the IMediaPlayer
* one to be routed correctly through the system.
* @param reply[out] Parcel that will contain the reply.
* @return The status code.
*/
private native final int native_invoke(Parcel request, Parcel reply);
/**
* @param update_only If true fetch only the set of metadata that have
* changed since the last invocation of getMetadata.
* The set is built using the unfiltered
* notifications the native player sent to the
* MediaPlayerService during that period of
* time. If false, all the metadatas are considered.
* @param apply_filter If true, once the metadata set has been built based on
* the value update_only, the current filter is applied.
* @param reply[out] On return contains the serialized
* metadata. Valid only if the call was successful.
* @return The status code.
*/
private native final boolean native_getMetadata(boolean update_only,
boolean apply_filter,
Parcel reply);
/**
* @param request Parcel with the 2 serialized lists of allowed
* metadata types followed by the one to be
* dropped. Each list starts with an integer
* indicating the number of metadata type elements.
* @return The status code.
*/
private native final int native_setMetadataFilter(Parcel request);
private static native final void native_init();
private native final void native_setup(Object mediaplayer_this);
private native final void native_finalize();
/**
* @param index The index of the text track to be turned on.
* @return true if the text track is enabled successfully.
* {@hide}
*/
public boolean enableTimedTextTrackIndex(int index) {
if (index < 0) {
return false;
}
return setParameter(KEY_PARAMETER_TIMED_TEXT_TRACK_INDEX, index);
}
/**
* Enables the first timed text track if any.
* @return true if the text track is enabled successfully
* {@hide}
*/
public boolean enableTimedText() {
return enableTimedTextTrackIndex(0);
}
/**
* Disables timed text display.
* @return true if the text track is disabled successfully.
* {@hide}
*/
public boolean disableTimedText() {
return setParameter(KEY_PARAMETER_TIMED_TEXT_TRACK_INDEX, -1);
}
/**
* @param reply Parcel with audio/video duration info for battery
tracking usage
* @return The status code.
* {@hide}
*/
public native static int native_pullBatteryData(Parcel reply);
@Override
protected void finalize() { native_finalize(); }
/* Do not change these values without updating their counterparts
* in include/media/mediaplayer.h!
*/
private static final int MEDIA_NOP = 0; // interface test message
private static final int MEDIA_PREPARED = 1;
private static final int MEDIA_PLAYBACK_COMPLETE = 2;
private static final int MEDIA_BUFFERING_UPDATE = 3;
private static final int MEDIA_SEEK_COMPLETE = 4;
private static final int MEDIA_SET_VIDEO_SIZE = 5;
private static final int MEDIA_TIMED_TEXT = 99;
private static final int MEDIA_ERROR = 100;
private static final int MEDIA_INFO = 200;
private class EventHandler extends Handler
{
private MediaPlayer mMediaPlayer;
public EventHandler(MediaPlayer mp, Looper looper) {
super(looper);
mMediaPlayer = mp;
}
@Override
public void handleMessage(Message msg) {
if (mMediaPlayer.mNativeContext == 0) {
Log.w(TAG, "mediaplayer went away with unhandled events");
return;
}
switch(msg.what) {
case MEDIA_PREPARED:
if (mOnPreparedListener != null)
mOnPreparedListener.onPrepared(mMediaPlayer);
return;
case MEDIA_PLAYBACK_COMPLETE:
if (mOnCompletionListener != null)
mOnCompletionListener.onCompletion(mMediaPlayer);
stayAwake(false);
return;
case MEDIA_BUFFERING_UPDATE:
if (mOnBufferingUpdateListener != null)
mOnBufferingUpdateListener.onBufferingUpdate(mMediaPlayer, msg.arg1);
return;
case MEDIA_SEEK_COMPLETE:
if (mOnSeekCompleteListener != null)
mOnSeekCompleteListener.onSeekComplete(mMediaPlayer);
return;
case MEDIA_SET_VIDEO_SIZE:
if (mOnVideoSizeChangedListener != null)
mOnVideoSizeChangedListener.onVideoSizeChanged(mMediaPlayer, msg.arg1, msg.arg2);
return;
case MEDIA_ERROR:
// For PV specific error values (msg.arg2) look in
// opencore/pvmi/pvmf/include/pvmf_return_codes.h
Log.e(TAG, "Error (" + msg.arg1 + "," + msg.arg2 + ")");
boolean error_was_handled = false;
if (mOnErrorListener != null) {
error_was_handled = mOnErrorListener.onError(mMediaPlayer, msg.arg1, msg.arg2);
}
if (mOnCompletionListener != null && ! error_was_handled) {
mOnCompletionListener.onCompletion(mMediaPlayer);
}
stayAwake(false);
return;
case MEDIA_INFO:
if (msg.arg1 != MEDIA_INFO_VIDEO_TRACK_LAGGING) {
Log.i(TAG, "Info (" + msg.arg1 + "," + msg.arg2 + ")");
}
if (mOnInfoListener != null) {
mOnInfoListener.onInfo(mMediaPlayer, msg.arg1, msg.arg2);
}
// No real default action so far.
return;
case MEDIA_TIMED_TEXT:
if (mOnTimedTextListener != null) {
if (msg.obj == null) {
mOnTimedTextListener.onTimedText(mMediaPlayer, null);
} else {
if (msg.obj instanceof byte[]) {
TimedText text = new TimedText((byte[])(msg.obj));
mOnTimedTextListener.onTimedText(mMediaPlayer, text);
}
}
}
return;
case MEDIA_NOP: // interface test message - ignore
break;
default:
Log.e(TAG, "Unknown message type " + msg.what);
return;
}
}
}
/**
* Called from native code when an interesting event happens. This method
* just uses the EventHandler system to post the event back to the main app thread.
* We use a weak reference to the original MediaPlayer object so that the native
* code is safe from the object disappearing from underneath it. (This is
* the cookie passed to native_setup().)
*/
private static void postEventFromNative(Object mediaplayer_ref,
int what, int arg1, int arg2, Object obj)
{
MediaPlayer mp = (MediaPlayer)((WeakReference)mediaplayer_ref).get();
if (mp == null) {
return;
}
if (mp.mEventHandler != null) {
Message m = mp.mEventHandler.obtainMessage(what, arg1, arg2, obj);
mp.mEventHandler.sendMessage(m);
}
}
/**
* Interface definition for a callback to be invoked when the media
* source is ready for playback.
*/
public interface OnPreparedListener
{
/**
* Called when the media file is ready for playback.
*
* @param mp the MediaPlayer that is ready for playback
*/
void onPrepared(MediaPlayer mp);
}
/**
* Register a callback to be invoked when the media source is ready
* for playback.
*
* @param listener the callback that will be run
*/
public void setOnPreparedListener(OnPreparedListener listener)
{
mOnPreparedListener = listener;
}
private OnPreparedListener mOnPreparedListener;
/**
* Interface definition for a callback to be invoked when playback of
* a media source has completed.
*/
public interface OnCompletionListener
{
/**
* Called when the end of a media source is reached during playback.
*
* @param mp the MediaPlayer that reached the end of the file
*/
void onCompletion(MediaPlayer mp);
}
/**
* Register a callback to be invoked when the end of a media source
* has been reached during playback.
*
* @param listener the callback that will be run
*/
public void setOnCompletionListener(OnCompletionListener listener)
{
mOnCompletionListener = listener;
}
private OnCompletionListener mOnCompletionListener;
/**
* Interface definition of a callback to be invoked indicating buffering
* status of a media resource being streamed over the network.
*/
public interface OnBufferingUpdateListener
{
/**
* Called to update status in buffering a media stream received through
* progressive HTTP download. The received buffering percentage
* indicates how much of the content has been buffered or played.
* For example a buffering update of 80 percent when half the content
* has already been played indicates that the next 30 percent of the
* content to play has been buffered.
*
* @param mp the MediaPlayer the update pertains to
* @param percent the percentage (0-100) of the content
* that has been buffered or played thus far
*/
void onBufferingUpdate(MediaPlayer mp, int percent);
}
/**
* Register a callback to be invoked when the status of a network
* stream's buffer has changed.
*
* @param listener the callback that will be run.
*/
public void setOnBufferingUpdateListener(OnBufferingUpdateListener listener)
{
mOnBufferingUpdateListener = listener;
}
private OnBufferingUpdateListener mOnBufferingUpdateListener;
/**
* Interface definition of a callback to be invoked indicating
* the completion of a seek operation.
*/
public interface OnSeekCompleteListener
{
/**
* Called to indicate the completion of a seek operation.
*
* @param mp the MediaPlayer that issued the seek operation
*/
public void onSeekComplete(MediaPlayer mp);
}
/**
* Register a callback to be invoked when a seek operation has been
* completed.
*
* @param listener the callback that will be run
*/
public void setOnSeekCompleteListener(OnSeekCompleteListener listener)
{
mOnSeekCompleteListener = listener;
}
private OnSeekCompleteListener mOnSeekCompleteListener;
/**
* Interface definition of a callback to be invoked when the
* video size is first known or updated
*/
public interface OnVideoSizeChangedListener
{
/**
* Called to indicate the video size
*
* @param mp the MediaPlayer associated with this callback
* @param width the width of the video
* @param height the height of the video
*/
public void onVideoSizeChanged(MediaPlayer mp, int width, int height);
}
/**
* Register a callback to be invoked when the video size is
* known or updated.
*
* @param listener the callback that will be run
*/
public void setOnVideoSizeChangedListener(OnVideoSizeChangedListener listener)
{
mOnVideoSizeChangedListener = listener;
}
private OnVideoSizeChangedListener mOnVideoSizeChangedListener;
/**
* Interface definition of a callback to be invoked when a
* timed text is available for display.
* {@hide}
*/
public interface OnTimedTextListener
{
/**
* Called to indicate an avaliable timed text
*
* @param mp the MediaPlayer associated with this callback
* @param text the timed text sample which contains the text
* needed to be displayed and the display format.
* {@hide}
*/
public void onTimedText(MediaPlayer mp, TimedText text);
}
/**
* Register a callback to be invoked when a timed text is available
* for display.
*
* @param listener the callback that will be run
* {@hide}
*/
public void setOnTimedTextListener(OnTimedTextListener listener)
{
mOnTimedTextListener = listener;
}
private OnTimedTextListener mOnTimedTextListener;
/* Do not change these values without updating their counterparts
* in include/media/mediaplayer.h!
*/
/** Unspecified media player error.
* @see android.media.MediaPlayer.OnErrorListener
*/
public static final int MEDIA_ERROR_UNKNOWN = 1;
/** Media server died. In this case, the application must release the
* MediaPlayer object and instantiate a new one.
* @see android.media.MediaPlayer.OnErrorListener
*/
public static final int MEDIA_ERROR_SERVER_DIED = 100;
/** 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.
* @see android.media.MediaPlayer.OnErrorListener
*/
public static final int MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK = 200;
/**
* 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).
*/
public interface OnErrorListener
{
/**
* Called to indicate an error.
*
* @param mp the MediaPlayer the error pertains to
* @param what the type of error that has occurred:
* setDataSource methods.
* @throws IllegalStateException if it is called in an invalid state
*/
public native void setAudioSessionId(int sessionId) throws IllegalArgumentException, IllegalStateException;
/**
* Returns the audio session ID.
*
* @return the audio session ID. {@see #setAudioSessionId(int)}
* Note that the audio session ID is 0 only if a problem occured when the MediaPlayer was contructed.
*/
public native int getAudioSessionId();
/**
* 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().
* {@see #setAuxEffectSendLevel(float)}.
* setDataSource
* methods.
* @param effectId system wide unique id of the effect to attach
*/
public native void attachAuxEffect(int effectId);
/* Do not change these values (starting with KEY_PARAMETER) without updating
* their counterparts in include/media/mediaplayer.h!
*/
/*
* Key used in setParameter method.
* Indicates the index of the timed text track to be enabled/disabled.
* The index includes both the in-band and out-of-band timed text.
* The index should start from in-band text if any. Application can retrieve the number
* of in-band text tracks by using MediaMetadataRetriever::extractMetadata().
* Note it might take a few hundred ms to scan an out-of-band text file
* before displaying it.
*/
private static final int KEY_PARAMETER_TIMED_TEXT_TRACK_INDEX = 1000;
/*
* Key used in setParameter method.
* Used to add out-of-band timed text source path.
* Application can add multiple text sources by calling setParameter() with
* KEY_PARAMETER_TIMED_TEXT_ADD_OUT_OF_BAND_SOURCE multiple times.
*/
private static final int KEY_PARAMETER_TIMED_TEXT_ADD_OUT_OF_BAND_SOURCE = 1001;
// There are currently no defined keys usable from Java with get*Parameter.
// But if any keys are defined, the order must be kept in sync with include/media/mediaplayer.h.
// private static final int KEY_PARAMETER_... = ...;
/**
* Sets the parameter indicated by key.
* @param key key indicates the parameter to be set.
* @param value value of the parameter to be set.
* @return true if the parameter is set successfully, false otherwise
* {@hide}
*/
public native boolean setParameter(int key, Parcel value);
/**
* Sets the parameter indicated by key.
* @param key key indicates the parameter to be set.
* @param value value of the parameter to be set.
* @return true if the parameter is set successfully, false otherwise
* {@hide}
*/
public boolean setParameter(int key, String value) {
Parcel p = Parcel.obtain();
p.writeString(value);
boolean ret = setParameter(key, p);
p.recycle();
return ret;
}
/**
* Sets the parameter indicated by key.
* @param key key indicates the parameter to be set.
* @param value value of the parameter to be set.
* @return true if the parameter is set successfully, false otherwise
* {@hide}
*/
public boolean setParameter(int key, int value) {
Parcel p = Parcel.obtain();
p.writeInt(value);
boolean ret = setParameter(key, p);
p.recycle();
return ret;
}
/**
* Gets the value of the parameter indicated by key.
* @param key key indicates the parameter to get.
* @param reply value of the parameter to get.
*/
private native void getParameter(int key, Parcel reply);
/**
* Gets the value of the parameter indicated by key.
* The caller is responsible for recycling the returned parcel.
* @param key key indicates the parameter to get.
* @return value of the parameter.
* {@hide}
*/
public Parcel getParcelParameter(int key) {
Parcel p = Parcel.obtain();
getParameter(key, p);
return p;
}
/**
* Gets the value of the parameter indicated by key.
* @param key key indicates the parameter to get.
* @return value of the parameter.
* {@hide}
*/
public String getStringParameter(int key) {
Parcel p = Parcel.obtain();
getParameter(key, p);
String ret = p.readString();
p.recycle();
return ret;
}
/**
* Gets the value of the parameter indicated by key.
* @param key key indicates the parameter to get.
* @return value of the parameter.
* {@hide}
*/
public int getIntParameter(int key) {
Parcel p = Parcel.obtain();
getParameter(key, p);
int ret = p.readInt();
p.recycle();
return ret;
}
/**
* Sets the send level of the player to the attached auxiliary effect
* {@see #attachAuxEffect(int)}. The level value range is 0 to 1.0.
*
*
* @param extra an extra code, specific to the error. Typically
* implementation dependant.
* @return True if the method handled the error, false if it didn't.
* Returning false, or not having an OnErrorListener at all, will
* cause the OnCompletionListener to be called.
*/
boolean onError(MediaPlayer mp, int what, int extra);
}
/**
* Register a callback to be invoked when an error has happened
* during an asynchronous operation.
*
* @param listener the callback that will be run
*/
public void setOnErrorListener(OnErrorListener listener)
{
mOnErrorListener = listener;
}
private OnErrorListener mOnErrorListener;
/* Do not change these values without updating their counterparts
* in include/media/mediaplayer.h!
*/
/** Unspecified media player info.
* @see android.media.MediaPlayer.OnInfoListener
*/
public static final int MEDIA_INFO_UNKNOWN = 1;
/** 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 android.media.MediaPlayer.OnInfoListener
*/
public static final int MEDIA_INFO_VIDEO_TRACK_LAGGING = 700;
/** MediaPlayer is temporarily pausing playback internally in order to
* buffer more data.
* @see android.media.MediaPlayer.OnInfoListener
*/
public static final int MEDIA_INFO_BUFFERING_START = 701;
/** MediaPlayer is resuming playback after filling buffers.
* @see android.media.MediaPlayer.OnInfoListener
*/
public static final int MEDIA_INFO_BUFFERING_END = 702;
/** 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.
* @see android.media.MediaPlayer.OnInfoListener
*/
public static final int MEDIA_INFO_BAD_INTERLEAVING = 800;
/** The media cannot be seeked (e.g live stream)
* @see android.media.MediaPlayer.OnInfoListener
*/
public static final int MEDIA_INFO_NOT_SEEKABLE = 801;
/** A new set of metadata is available.
* @see android.media.MediaPlayer.OnInfoListener
*/
public static final int MEDIA_INFO_METADATA_UPDATE = 802;
/**
* Interface definition of a callback to be invoked to communicate some
* info and/or warning about the media or its playback.
*/
public interface OnInfoListener
{
/**
* Called to indicate an info or a warning.
*
* @param mp the MediaPlayer the info pertains to.
* @param what the type of info or warning.
*
*
* @param extra an extra code, specific to the info. Typically
* implementation dependant.
* @return True if the method handled the info, false if it didn't.
* Returning false, or not having an OnErrorListener at all, will
* cause the info to be discarded.
*/
boolean onInfo(MediaPlayer mp, int what, int extra);
}
/**
* Register a callback to be invoked when an info/warning is available.
*
* @param listener the callback that will be run
*/
public void setOnInfoListener(OnInfoListener listener)
{
mOnInfoListener = listener;
}
private OnInfoListener mOnInfoListener;
}