个人级别,低水平翻译.存以备查
public class
MediaPlayer
extends Object
可以用来控制A/V文件和流回放.
播放A/V文件和流控制的管理作为一个状态机. 下图显示了生命周期和所支持的播放控制操作驾驶的MediaPlayer的对象状态.椭圆代表MediaPlaer对象会进入的状态.弧代表播放控制操作驱动对象状态过滤.有两种类型的弧线,单箭头的表示同步方法调用,双箭头的表示异步方法调用.
从状态图解中,可以分析出MediaPlayer对象有以下状态:
当一个MediaPlayer对象刚被创建或者在调用reset()之后,他进入idle状态,然后在release()被调用之后,进入End状态.在这两种状态之间是MediaPlayer对象的生命周期.
l 这是一个微妙的但是重要的不同在一个新构造了的MediaPlaer对象和调用了reset()方法之后的MediaPlayer对象.这是一个编程错误在idle状态中两种不同情况下去调用诸如getCurrentPosition()
, getDuration()
, getVideoHeight()
, getVideoWidth()
, setAudioStreamType(int)
, setLooping(boolean)
, setVolume(float, float)
, pause()
, start()
, stop()
, seekTo(int)
, prepare()
or prepareAsync()
方法.如果这些方法中任何一个方法被成功调用在MediaPlayer对象构造后,用户提供的回调方法OnErrorListener.onError()将不会被内部的player引擎调用而且这对象的状态不会发生改变.但是如果该方法被正确调用在reset()之后,用户提供的OnErrorListener.onError()将会被内部的player引擎调用而且这对象将会过滤到Error状态
l 这是经常被推荐的当一个MediaPlayer对象不在被使用,调用release()马上因此那些被内部player引擎所使用的资源将会被立刻释放.资源可能包含单例资源例如一个硬件加速组件而且调用release()失败将引发随后的MediaPlaer对象实例退回到软件实现或者完全失败.当MediaPlayer对象处于End状态,它将不能被使用且没有任何办法把它放回到其他任何状态.
l 此外,MediaPlaer对象被使用new创建会处于idle状态,当那些被创建了的却重载了create方法的将不会进入idle状态.事实上,这些对象处于Prepared()状态如果是通过create方法成功创建的
通常情况下,一些回放控制操作由于种种原因可能会失败,例如不支持的AV格式,劣质的AV.分辨率过高,流超时,等等.因此,错误报告和收集机制在这种情况下是很重要的.有时,由于编程错误,在一个无效的状态下调用一个播放控制操作也可能发生. 在所有这些错误的条件下,内部Player引擎调用用户提供OnErrorListener.onError()方法如果OnErrorListener已注册通过事先 setOnErrorListener(android.media.MediaPlayer.OnErrorListener)
l 重要的是要注意,一旦发生错误,MediaPlayer对象进入Error状态(除了上面提到的),即使有错误监听还没有被应用程序注册.
l 为了重复使用一个处于Error状态的MediaPlayer对象并且从error中恢复,reset()可以调用对象恢复到它的空闲状态.
l 这是很好的编程习惯去为你的APP注册一个OnErrorListenner以用来从内部的Player引擎中查找错误通知
l IIIegalStateException被抛出以防止编程错误比如调用prepara(),prepareAsync(),或者被重载了的一个setDataSource()方法在无效的状态.
调用setDataSource(FileDescriptor)或setDataSource(String)或setDataSource(Context,Uri)或者setDataSource(FileDescriptor,long,long)会转变MediaPlayer对象从idle状态改变到initialized状态
l IIIegalStateException将会被抛出如果setDataSource()在其他状态被调用
l 这是很好的编程习惯总是从重载了的setDataSource()方法中寻找出IllegalArgumentException异常 和IOException异常
一个MediaPlayer对象必须先进入Prepared状态然后才可以播放
l 有两种方法(同步和异步)可以达到Prepared状态.调用prepare()(同步)会转变该对象到Prepared状态当该方法返回时,或者调用prepareAsync()(异步)将会先转变对象到Preparing状态然后方法才返回而内部的Player引擎继续工作在”剩下的准备工作”直到”准备工作完成”.当准备完成或者当prepared调用返回,内部Player引擎将会调用用户提供的回调方法onPrepared(),前提是OnPreparedListener是通过事先注册setOnPreparedListener(android.media.MediaPlayer.OnPreparedListener)
l 重要的是要注意Preparing状态是短暂的状态,而且在MediaPlayer对象在Preparing状态时调用任何副作用的方法的行为是不支持的.-----在Preparing状态时不要调用任何”副作用方法”
l 如果prepare()或prepareAsync()在其他状态被调用将会抛出IIIegalStateException
l 在Prepared状态,那些属性比如A/V的音量,播放时是否亮屏,循环这些可以被自适应通过调用相应的方法进行调整
要开始播放,Start()方法必须被调用.在Start()成功返回后,MediaPlayer对象进入Sarted状态.isPlaying()可以被调用以测试MediaPlayer对象是否处于Started状态.
l 在开始的状态,内部Player引擎调用用户提供的OnBufferingUpdateListenner.onBufferingUpdate()回调方法,如果OnBufferingUpdateListenner已经注册在事先通过setOnBufferingUpdateListenner(OnBufferingUpdateListenner).此回调允许APP允许缓冲状态跟踪.
l 调用start()不会产生效果当MediaPlayer已经处于Started状态
回放可以暂停和停止,而且当前播放进度可以调整.回放可以通过pause()达到暂停.当调用pause()返回时MediaPlayer对象进入Paused状态.请注意它是从Started状态过渡到Paused状态而且在Player引擎中这是异步的.这可能需要一点时间如果在状态更新完成前调用isPlaying(),而且在这种情况下将会需要几秒钟流媒体内容.
l 调用Start()恢复一个处于Paused状态的MediaPlayer对象,而且恢复了的播放进度和暂停时播放位置是一样的
l 调用pause()不会产生效果当MediaPlayer已经处于Paused状态.
调用stop()将停止播放并让MediaPlayer无论是在Started,Paused,Prepared或者PlaybackCompleted状态都进入到Stopped状态
l 一旦处于Stopped状态,回放不能被开启直到prepare()或者prepareAsync()被调用以用来设置MediaPlayer对象进入Prepared状态
l 调用stop()不会产生效果当MediaPlayer已经处于Stopped状态.
播放的位置可以通过调用seekTo(int)进行调整
l 虽然调用asynchronous seekTo(int)返回正确的方式,但是实际的seek操作可能需要一点点时间去完成,尤其是A/V的流式传输.当实际的seek操作完成,内部的Player引擎调用用户提供的OnSeekComplete.onSeekComplete()如果这个OnSeekCompleteListener已经被实现通过setOnSeekCompleteListener(OnSeekCompleteListener)注册
l 请注意seekTo(int)可以在其他状态被调用,例如Prepared,Paused和PlaybackCompleted状态.
l 此外,实际当前播放位置可以被调用getCurrentPosition()方法获取到,这是非常又帮助的对与一个APP例如音乐播放器,这方法可以 跟踪播放进度.
当播放到流的末尾播放完成
l 如果循环模式被通过setLooping(boolean)设置为真,MediaPlayer对象将会保持在Started状态.
l 如果循环模式被设置成假,Player引擎调用用户提供的回调函数OnCompletion.onCompletion(),如果这个onCompletionListener()事先通过set onCompletionListener(OnCompletionListener)注册.调用这个回调标识这对象现在处于PlaybackCompleted状态
l 当处于PlaybackCompleted状态,调用start()可以重新让播放回到A/V的开始部分
有效和无效状态
l attachAuxEffect 必须在setDataSource之后调用
l getAudioSessionId 可以再任何状态调用,而且调用之后不会改变对象当前状态.
l getCurrentPosition 在有效状态下成功调用不会引起状态的改变,否则进入Error状态
l getDuration 在有效状态下成功调用不会引起状态的改变,否则进入Error状态
l getVideoHeight 在有效状态下成功调用不会引起状态的改变,否则进入Error状态
l getVideoWidth 在有效状态下成功调用不会引起状态的改变,否则进入Error状态
l isPlaying 在有效状态下成功调用不会引起状态的改变,否则进入Error状态
l pause 在有效状态下成功调用会改变对象进入Paused状态,在无效状态下调用会改变对象进入Error状态.
l Prepare 在有效状态下调用会转变对象进入Prepared状态
l prepareAsync 在有效状态下成功调用会转变对象进入Preparing状态,否则抛出IIIegalStateException
l rease 调用之后该对象将不能被使用
l reset 调用之后该对象犹如刚创建一样
l seekTo 在有效状态下成功调用会改变对象进入Paused状态,在无效状态下调用会改变对象进入Error状态.
l setAudioSessionId 必须在idle状态调用因为音频会话ID必须在setDataSource之前被识别
l setAudioStreamType 成功调用该方法不改变状态,为了让大音频流类型变得有序,该方法必须在prepare()或prepareAsync()之前调用
l setAuxEffectSendLevel 调用此方法不改变对象状态
l setDataSource 在有效状态下调用成功将转变对象进入Initialized状态,否则抛出IIIegalStateException
l setDisplay调用此方法不改变对象状态
l setTexture调用此方法不改变对象状态
l setLooping 在有效的状态下成功调用将不会改变对象状态,否则转变到Error状态
l isLooping调用此方法不改变对象状态
l setOnBufferingUpdateListener调用此方法不改变对象状态
l setOnCompletionListener 调用此方法不改变对象状态
l setOnErrorListener 调用此方法不改变对象状态
l setOnPreparedListener 调用此方法不改变对象状态
l setOnSeekCompleteListener调用此方法不改变对象状态
l setScreenOnWhilePlaying 调用此方法不改变对象状态
l setVolume 成功调用将不会改变状态
l setWakeMode调用此方法不改变对象状态
l start 在有效状态下调用将转变对象状态到Started状态,否则进入Error状态.
l stop在有效状态下调用将转变对象状态到Stop状态,否则进入Error状态.
接口:
MediaPlayer.OnBufferingUpdateListener:表明媒体资源缓冲状态变成streamed
MediaPlayer.OnCompletionListener:播放一个媒体资源完成
MediaPlayer.OnErrorListener:异步操作过程中引发的error
MediaPlayer.OnInfoListener:表达一些关于媒体的或者回放的信息或者警告.
MediaPlayer.OnPreparedListener:媒体资源已经准备好进入播放状态的回调.
MediaPlayer.OnSeekCompleteListener:标示seek操作完成的回调
MediaPlayer.OnVideoSizeChangedListener:第一次获得到或者更新了视频大小.
常量:
MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK:视频是流式的,但是他的控制信息对于渐进流不是有效的.
MEDIA_ERROR_SERVER_DIED:多媒体服务器崩溃.
MEDIA_ERROR_UNKNOWN:未指定的媒体播放器错误
MEDIA_INFO_BAD_INTERLEAVING:坏的交错媒体(不正确的交叉方式或者根本没有交叉)
MEDIA_INFO_BUFFERING_END:MediaPlayer在缓冲满后恢复播放
MEDIA_INFO_BUFFERING_START:MediaPlayer为了缓冲更多数据,内部停止播放
MEDIA_INFO_METADATA_UPDATE:一个新的元素集可用
MEDIA_INFO_NOT_SEEKABLE:媒体不能被seek
MEDIA_INFO_UNKNOWN:未指定的媒体播放器信息
MEDIA_INFO_VIDEO_TRACK_LAGGING:对于解码器该视频太复杂,解码帧数不够快。
attachAuxEffect(INT effectId):附加一个辅助的效果到播放器
create(Context context, Uri uri, SurfaceHolder holder):通过给定的Uri创建一个MediaPlayer
create(Context context, int resid):通过给定的resid创建MediaPlayer
create(Context context, Uri uri): 通过给定的Uri创建一个MediaPlayer
getAudioSessionId:返回音频会话ID
getCurrentPosition:返回当前播放位置
getDuration:获取文件持续时间
getVideoHeight:获得视频高度
getVideoWidth:获得视频宽度
isLooping():返回MediaPlayer是否循环
isPlaying():返回但却是否在播放
pause:暂停
prepare():准备播放器,同步
prepareAsync():准备播放器.异步
release():释放
reset():复位MediaPlayer到它的未初始化状态
seekTo:定位到指定播放进度
setAudioSessionId:设置会话Id
setAudioStreamType:设置MediaPlayer音频流类型
setAuxEffectSendLevel:设置附加辅助影响发送等级
setDataSource(String path):设置数据源,(文件路径或者http/rtsp url)
setDataSource(FileDescriptor fd,long offset,long length):设置数据源
setDataSource(FileDescriptor fd):设置数据源
setDataSource(Context context,Uri uri):设置数据源
setDisplay(SurfaxceHold sh):设置SurfaceHolder用来显示媒体视频
setLooping:设置播放器是否循环
setOnBufferingUpdateListener(MediaPlayer.OnBufferingUpdateListener监听器):注册一个回调当网络流缓冲状态发生改变的时候回调
setOnCompletionListener(MediaPlayer.OnCompletionListener监听器):注册一个回调当播放过程中媒体资源被播放完成时回调
setOnErrorListener(MediaPlayer.OnErrorListener监听器):注册一个回调当在异步操作过程中一个error发生的时候被调用
setOnInfoListener(MediaPlayer.OnInfoListener监听器):注册一个回调当一个信息/警告发生时调用.
setOnPreparedListener(MediaPlayer.OnPreparedListener监听器):注册一个回调当媒体数据准备好可以播放了.
setOnSeekCompleteListener(MediaPlayer.OnSeekCompleteListener监听器):注册一个回调当seek操作完成时调用
setOnVideoSizeChangedListener(MediaPlayer.OnVideoSizeChangedListener监听器):注册一个回调当视频大小被获得或者更新时调用
setScreenOnWhilePlaying(布尔screenOn):控制在视频播放期间是否使用附加的SurfaceHolder来保持屏幕亮着
setVolume(leftVolume浮动,浮动rightVolume):设置播放器的音量
setWakeMode(上下文的背景下,INT模式):设置MediaPlayer的底层电源管理器操作
start():开始或继续播放
stop():停止播放