MediaPlayer 中文

个人级别,低水平翻译.存以备查

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        虽然调用asynchronousseekTo(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(Stringpath):设置数据源,(文件路径或者http/rtsp url)

setDataSource(FileDescriptorfd,long offset,long length):设置数据源

setDataSource(FileDescriptorfd):设置数据源

setDataSource(Contextcontext,Uri uri):设置数据源

setDisplay(SurfaxceHoldsh):设置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():停止播放