MediaPlayer 状态机 API 详解 示例

• There is a subtle but important difference between a newly constructed MediaPlayer object and the MediaPlayer object after reset() is called. It is a programming error to invoke methods such asgetCurrentPosition(), getDuration(), getVideoHeight(), getVideoWidth(), setAudioAttributes(AudioAttributes), setLooping(boolean), setVolume(float, float), pause(), start(), stop(), seekTo(long, int), prepare() or prepareAsync() in the Idle state for both cases. 
  If any of these methods is called right after a MediaPlayer object is constructed, the user supplied callback method OnErrorListener.onError() won‘t be called by the internal player engine and the object state remains unchanged; but if these methods are called right after reset(), the user supplied callback method OnErrorListener.onError() will be invoked by the internal player engine and the object will be transfered to the Error state.
  
• 1.1) 在一个新构建的MediaPlayer对象和一个调用了reset()方法的MediaPlayer对象之间有一个微小的但是十分重要的差别。在处于Idle状态时，调用***方法都是编程错误。
  当一个MediaPlayer对象刚被构建的时候，内部的播放引擎和对象的状态都没有改变，在这个时候调用以上的那些方法，框架将无法回调客户端程序注册的OnErrorListener.onError()方法；但如果那些方法是在调用了reset()方法之后调用的，内部的播放引擎就会回调客户端程序注册的OnErrorListener.onError()方法了，并将错误的状态传入。
  
• It is also recommended that once a MediaPlayer object is no longer being used, call release() immediately so that resources used by the internal player engine associated with the MediaPlayer object can be released immediately. Resource may include singleton resources such as hardware acceleration components and failure to call release() may cause subsequent instances of MediaPlayer objects to fallback to software implementations or fail altogether. Once the MediaPlayer object is in the End state, it can no longer be used and there is no way to bring it back to any other state.
  
• 1.2) 建议，一旦一个MediaPlayer对象不再被使用，应立即调用release()方法来释放在内部的播放引擎中与这个MediaPlayer对象关联的资源。资源可能包括如硬件加速组件的单态组件，若没有调用release()方法可能会导致，之后的MediaPlayer对象实例无法使用这种单态硬件资源，从而退回到软件实现或运行失败。一旦MediaPlayer对象进入了End状态，它不能再被使用，也没有办法再迁移到其它状态。
  
• Furthermore, the MediaPlayer objects created using 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.
  
• 1.3) 此外，使用new操作符创建的MediaPlayer对象处于Idle状态，而那些通过重载的create()便利方法创建的MediaPlayer对象却不是处于Idle状态。事实上，如果成功调用了重载的create()方法，那么这些对象已经是Prepare状态了。 
  

• 2.1) 需要注意的是，一旦发生错误，MediaPlayer对象会进入到Error状态（除了如上所述），即使应用程序尚未注册错误监听器。
  
• 2.2) 为了重用一个处于Error状态的MediaPlayer对象，可以调用reset()方法来把这个对象恢复成Idle状态。
  
• 2.3) 注册一个OnErrorListener来获知内部播放引擎发生的错误是好的编程习惯。
  
• 2.4) 在不合法的状态下调用一些方法，如prepare()，prepareAsync()和setDataSource()方法会抛出IllegalStateException异常，以避免编程错误。 
  

• An IllegalStateException is thrown if setDataSource() is called in any other state.
  
• It is good programming practice to always look out for IllegalArgumentException and IOException that may be thrown from the overloaded setDataSource methods.

• 3.1) 若MediaPlayer处于其它的状态下，调用setDataSource()方法会抛出IllegalStateException异常。
  
• 3.2) 好的编程习惯是不要疏忽了调用setDataSource()方法的时候可能会抛出的IllegalArgumentException异常和IOException异常。 
  

• There are two ways (synchronous vs. asynchronous) that the Prepared state can be reached: either a call to prepare() (synchronous) which transfers the object to the Prepared state once the method call returns, or a call to prepareAsync() (asynchronous) which first transfers the object to the Preparing state after the call returns (which occurs almost right way) while the internal player engine continues working on the rest of preparation work until the preparation work completes. 
  When the preparation completes or when prepare() call returns, the internal player engine then calls a user supplied callback method, onPrepared() of the OnPreparedListener interface, if an OnPreparedListener is registered beforehand via setOnPreparedListener(android.media.MediaPlayer.OnPreparedListener).
  
• 4.1) 有两种方法(同步和异步)可以使MediaPlayer对象进入Prepared状态：要么调用prepare()方法，此方法返回就表示该MediaPlayer对象已经进入了Prepared状态；要么调用prepareAsync()方法，此方法会首先使此MediaPlayer对象进入Preparing状态并返回(这几乎时立即发生的)，而内部的播放引擎会继续未完成的准备工作，直到准备工作完成。
  当准备工作完全完成时，如果之前已经通过调用setOnPreparedListener()方法注册过OnPreparedListener，内部的播放引擎就会调用客户端提供的OnPreparedListener.onPrepared()监听方法。
  
• It is important to note that the Preparing state is a transient state, and the behavior of calling any method with side effect while a MediaPlayer object is in the Preparing state is undefined.
  
• 4.2) 需要注意的是， Preparing是一个中间状态，在此状态下调用任何具有副作用的方法的结果都是未知的！
  
• An IllegalStateException is thrown if prepare() or prepareAsync() is called in any other state.
  
• 4.3) 在除此之外的其他状态下调用prepare()和prepareAsync()方法会抛出IllegalStateException异常。
• While in the Prepared state, properties such as audio/sound volume, screenOnWhilePlaying, looping can be adjusted by invoking the corresponding set methods.
  
• 4.4) 当MediaPlayer对象处于Prepared状态的时候，可以通过调用相应的set方法，调整音频/视频的属性，如音量，播放时是否一直亮屏，循环播放等。 
  

• While in the Started state, the internal player engine calls a user supplied OnBufferingUpdateListener.onBufferingUpdate() callback method if a OnBufferingUpdateListener has been registered beforehand via setOnBufferingUpdateListener(OnBufferingUpdateListener). This callback allows applications to keep track of the buffering status while streaming audio/video.
  
• 5.1) 当处于Started状态时，如果***，内部播放引擎会调用客户端提供的**回调方法。此回调允许应用程序在流式传输音频/视频时跟踪缓冲状态。
  
• Calling start() has not effect on a MediaPlayer object that is already in the Started state.
  
• 5.2) 对一个已经处于Started 状态的MediaPlayer对象，调用start()方法没有影响。
  

• Calling start() to resume playback for a paused MediaPlayer object, and the resumed playback position is the same as where it was paused. When the call to start() returns, the paused MediaPlayer object goes back to the Started state.
  
• 6.1) 调用start()方法会让一个处于Paused状态的MediaPlayer对象从之前暂停时的地方恢复播放。当调用start()方法返回的时候，暂停的MediaPlayer对象会变成Started状态。
  
• Calling pause() has no effect on a MediaPlayer object that is already in the Paused state.
  
• 6.2) 对一个已经处于Paused状态的MediaPlayer对象，调用pause()方法没有影响。
  

• Once in the Stopped state, playback cannot be started until prepare() or prepareAsync() are called to set the MediaPlayer object to the Prepared state again.
  
• 7.1) 一旦处于停止状态，播放将不能开始，直到调用prepare()或prepareAsync()将MediaPlayer对象重新设置为Prepared状态。
  
• Calling stop() has no effect on a MediaPlayer object that is already in the Stopped state.
  
• 7.2) 对一个已经处于Stopped状态的MediaPlayer对象stop()方法没有影响。
  

• Although the asynchronuous seekTo(long, int) call returns right away, the actual seek operation may take a while to finish, especially for audio/video being streamed. When the actual seek operation completes, the internal player engine calls a user supplied OnSeekComplete.onSeekComplete() if an OnSeekCompleteListener has been registered beforehand via setOnSeekCompleteListener(OnSeekCompleteListener).
  
• 8.1) 虽然异步的seekTo(long，int)在调用后立即返回，但实际的定位操作可能需要一段时间才能完成，特别是播放流形式的音频/视频。当实际的定位播放操作完成之后，如果***，内部的播放引擎会调用客户端提供的OnSeekComplete.onSeekComplete()回调方法。
  
• Please note that seekTo(long, int) can also be called in the other states, such as Prepared, Paused and PlaybackCompleted state. When seekTo(long, int) is called in those states, one video frame will be displayed if the stream has video and the requested position is valid.
  
• 8.2) 注意，seekTo()方法也可以在其它状态下调用，比如Prepared、Paused、PlaybackCompleted状态。当在这些状态中调用seekTo()时，如果流具有视频并且请求的位置有效，则将显示一个视频帧。
• Furthermore, the actual current playback position can be retrieved with a call to getCurrentPosition(), which is helpful for applications such as a Music player that need to keep track of the playback progress.
  
• 8.3) 此外，目前的播放位置，实际可以调用getCurrentPosition()方法得到，它可以帮助如音乐播放器的应用程序不断更新播放进度
  

• If the looping mode was being set to true with setLooping(boolean), the MediaPlayer object shall(应) remain in the Started state.
  
• 9.1) 如果通过调用setLooping(true)方法设置为循环模式，这个MediaPlayer对象会保持在Started状态。
  
• If the looping mode was set to false , the player engine calls a user supplied callback method, OnCompletion.onCompletion(), if a OnCompletionListener is registered beforehand via setOnCompletionListener(OnCompletionListener). The invoke of the callback signals(表面) that the object is now in the PlaybackCompleted state.
  
• 9.2) 如果循环模式设置为false，如果***，那么内部的播放引擎会调用客户端提供的OnCompletion.onCompletion()回调方法。调用回调后说明这个MediaPlayer对象进入了PlaybackCompleted状态。
  
• While in the PlaybackCompleted state, calling start() can restart the playback from the beginning of the audio/video source.
  
• 9.3) 当处于PlaybackCompleted状态的时候，可以再调用start()方法来让这个MediaPlayer对象再进入Started状态。

• void setDataSource(FileDescriptor fd)    Sets the data source (FileDescriptor) to use.
• 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).

• void setDataSource(AssetFileDescriptor afd)    Sets the data source (AssetFileDescriptor) 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.

public void setDataSource(FileDescriptor fd) throws IOException, IllegalArgumentException, IllegalStateException {
	setDataSource(fd, 0, 0x7ffffffffffffffL);// intentionally故意地 less than LONG_MAX
}
public void setDataSource(FileDescriptor fd, long offset, long length) throws IOException, IllegalArgumentException, IllegalStateException {
	_setDataSource(fd, offset, length);
}
public void setDataSource(@NonNull AssetFileDescriptor afd)  throws IOException, IllegalArgumentException, IllegalStateException {
	Preconditions.checkNotNull(afd);
	// Note: using getDeclaredLength so that our behavior is the same as previous versions when the content provider is returning a full file.
	if (afd.getDeclaredLength() < 0) setDataSource(afd.getFileDescriptor());
	else setDataSource(afd.getFileDescriptor(), afd.getStartOffset(), afd.getDeclaredLength());
}
private native void _setDataSource(FileDescriptor fd, long offset, long length) throws IOException, IllegalArgumentException, IllegalStateException;

public void setDataSource(MediaDataSource dataSource) throws IllegalArgumentException, IllegalStateException {
	_setDataSource(dataSource);
}
private native void _setDataSource(MediaDataSource dataSource) throws IllegalArgumentException, IllegalStateException;

【prepare、start、pause、stop、reset、seekTo】等方法源码分析

public void prepare() throws IOException, IllegalStateException {
    _prepare();
    scanInternalSubtitleTracks();
}
private native void _prepare() throws IOException, IllegalStateException;
public native void prepareAsync() throws IllegalStateException;

 public void start() throws IllegalStateException {
     baseStart();
     stayAwake(true);
     _start();
 }
 private native void _start() throws IllegalStateException;

public void pause() throws IllegalStateException {
    stayAwake(false);
    _pause();
}
private native void _pause() throws IllegalStateException;

public void stop() throws IllegalStateException {
    stayAwake(false);
    _stop();
}
private native void _stop() throws IllegalStateException;

public void reset() {
    mSelectedSubtitleTrackIndex = -1;
    synchronized(mOpenSubtitleSources) {
        for (final InputStream is: mOpenSubtitleSources) {
            try {
                is.close();
            } catch (IOException e) {
            }
        }
        mOpenSubtitleSources.clear();
    }
    if (mSubtitleController != null)  mSubtitleController.reset();
    if (mTimeProvider != null) {
        mTimeProvider.close();
        mTimeProvider = null;
    }
    stayAwake(false);
    _reset();
    // make sure none of the listeners get called anymore
    if (mEventHandler != null) mEventHandler.removeCallbacksAndMessages(null);
    synchronized (mIndexTrackPairs) {
        mIndexTrackPairs.clear();
        mInbandTrackIndices.clear();
    };
}
private native void _reset();

public native void seekTo(int msec) throws IllegalStateException;

【release】方法源码分析