MediaPlayer Classe

Definição

[Android.Runtime.Register("android/media/MediaPlayer", DoNotGenerateAcw=true)]
public class MediaPlayer : Java.Lang.Object, Android.Media.IAudioRouting, Android.Media.IVolumeAutomation, IDisposable

[<Android.Runtime.Register("android/media/MediaPlayer", DoNotGenerateAcw=true)>]
type MediaPlayer = class
    inherit Object
    interface IAudioRouting
    interface IJavaObject
    interface IDisposable
    interface IJavaPeerable
    interface IVolumeAutomation

Herança

Object

JavaObject

Object

MediaPlayer

Atributos

RegisterAttribute

Implementações

IAudioRouting IVolumeAutomation IJavaObject IJavaPeerable IDisposable

Comentários

A classe MediaPlayer pode ser usada para controlar a reprodução de arquivos e fluxos de áudio/vídeo.

O MediaPlayer não é thread-safe. A criação e todo o acesso a instâncias de player devem estar no mesmo thread. Se estiver registrando retornos de chamada, o thread deverá ter um Looper.

Os tópicos abordados aqui são: <ol><li>State Diagram<li>Valid and Invalid States<li>Permissions<li>Register informational and error callbacks</ol>

<div class="special reference"><h3>Developer Guides</h3>

Para obter mais informações sobre como usar o MediaPlayer, leia o guia do desenvolvedor de Reprodução de Mídia .

</div>

"StateDiagram"><h3>State Diagram</h3>

O controle de reprodução de arquivos e fluxos de áudio/vídeo é gerenciado como um computador de estado. O diagrama a seguir mostra o ciclo de vida e os estados de um objeto MediaPlayer controlado pelas operações de controle de reprodução com suporte. As ovais representam os estados em que um objeto MediaPlayer pode residir. Os arcos representam as operações de controle de reprodução que conduzem a transição de estado do objeto. Há dois tipos de arcos. Os arcos com uma única seta representam chamadas de método síncrono, enquanto aqueles com uma seta dupla representam chamadas de método assíncrono.

<img src=".. /.. /.. /images/mediaplayer_state_diagram.gif" alt="Diagrama de Estado do MediaPlayer" border="0" />

Neste diagrama de estado, é possível ver que um objeto MediaPlayer tem os seguintes estados:

<ul>li Quando um objeto MediaPlayer é criado usando < ou depois > é chamado, ele está no newestado em#reset()Idle</em>; e depois < é chamado, ele está no >estado em End#release()</em>.<> Entre esses dois estados está o ciclo de vida do objeto MediaPlayer. <ul><li>Há uma diferença sutil, mas importante, entre um objeto MediaPlayer recém-construído e o objeto MediaPlayer depois #reset() é chamado. É um erro de programação invocar métodos como #getCurrentPosition(), , #getDuration(), #getVideoHeight(), #getVideoWidth(), #setAudioAttributes(AudioAttributes), #setLooping(boolean), #setVolume(float, float), , #pause(), , #start(), #stop(), #seekTo(long, int), #prepare() ou #prepareAsync() no <estado em>Idle</em> para ambos os casos. Se qualquer um desses métodos for chamado logo após a construção de um objeto MediaPlayer, o método de retorno de chamada fornecido pelo usuário OnErrorListener.onError() não será chamado pelo mecanismo de player interno e o estado do objeto permanecerá inalterado; mas se esses métodos forem chamados logo depois #reset(), o método de retorno de chamada fornecido pelo usuário OnErrorListener.onError() será invocado pelo mecanismo de player interno e o objeto será transferido para o <estado em>Error</em> . </li li><>Você deve manter uma referência a uma instância do MediaPlayer para impedir que ela seja coletada de lixo. Se uma instância do MediaPlayer for coletada de lixo, #release será chamada, fazendo com que qualquer reprodução contínua pare. <li>Você deve ligar #release() depois de terminar de usar uma instância para liberar recursos adquiridos, como memória e codecs. Depois de ligar #release, você não deve mais interagir com a instância liberada. <os objetos li>MediaPlayer criados usando new estão no <estado em>Idle</em> , enquanto aqueles criados com um dos métodos convenientes create sobrecarregados são <em>NOT</em> no <estado em>Idle</em> . Na verdade, os objetos estarão no <estado em>Prepared</em> se a criação usando create o método for bem-sucedida. </li></ul></li li><>Em geral, alguma operação de controle de reprodução pode falhar devido a vários motivos, como formato de áudio/vídeo sem suporte, áudio/vídeo mal intercalado, resolução muito alta, tempo limite de streaming e similares. Portanto, o relatório de erros e a recuperação são uma preocupação importante nessas circunstâncias. Às vezes, devido a erros de programação, a invocação de uma operação de controle de reprodução em um estado inválido também pode ocorrer. Em todas essas condições de erro, o mecanismo de player interno invocará um método OnErrorListener.onError() fornecido pelo usuário se um OnErrorListener tiver sido registrado de antemão via #setOnErrorListener(android.media.MediaPlayer.OnErrorListener). <ul><li>É importante observar que, uma vez que ocorre um erro, o objeto MediaPlayer insere o <estado em>Error</em> (exceto conforme observado acima), mesmo que um ouvinte de erro não tenha sido registrado pelo aplicativo.</li>li Para reutilizar um objeto MediaPlayer que está no <estado em> Error</em> e recuperar do erro, < pode ser chamado para restaurar o objeto para >seu estado em#reset()Idle</em>.<></li><li>É uma boa prática de programação fazer com que seu aplicativo registre um OnErrorListener para ficar atento às notificações de erro do mecanismo de player interno.</li li><>IllegalStateException é gerado para evitar erros de programação, como chamada#prepare(), #prepareAsync()ou um dos métodos sobrecarregados setDataSource em um estado inválido. </li>/ul<>/li li<><Chamando >, ou #setDataSource(FileDescriptor), ou #setDataSource(String), ou #setDataSource(Context, Uri), ou #setDataSource(FileDescriptor, long, long) transfere um objeto MediaPlayer no estado em#setDataSource(MediaDataSource)< Idle>/em< para o >estado em<Inicializado>/em<.> <ul><li>An IllegalStateException será lançado se setDataSource() for chamado em qualquer outro estado.</li><li>É uma boa prática de programação sempre ficar atento IllegalArgumentException e IOException que pode ser gerada dos métodos sobrecarregadossetDataSource.</li></ul></li li><>Um objeto MediaPlayer deve primeiro inserir o <estado em>Prepared</em> antes que a reprodução possa ser iniciada. <ul><li>Há duas maneiras (síncronas vs. assíncronas) que o <estado em>Prepared</em> pode ser atingido: uma chamada para #prepare() (síncrona) que transfere o objeto para o <estado em>Prepared</em> quando a chamada do método retorna ou uma chamada para #prepareAsync() (assíncrona) que primeiro transfere o objeto para o <em>Prepare/em Prepare</em> estado após o retorno da chamada (que ocorre quase imediatamente) enquanto o mecanismo de player interno continua trabalhando no restante do trabalho de preparação até que o trabalho de preparação seja concluído. Quando a preparação for concluída ou quando #prepare() a chamada for retornada, o mecanismo de player interno chamará um método de retorno de chamada fornecido pelo usuário, onPrepared() da interface OnPreparedListener, se um OnPreparedListener for registrado com antecedência via #setOnPreparedListener(android.media.MediaPlayer.OnPreparedListener).</li><li>É importante observar que o <estado em>Preparação</em> é um estado transitório e o comportamento de chamar qualquer método com efeito colateral enquanto um objeto MediaPlayer está no <estado em>Preparação</em> é indefinido.</li li><>An IllegalStateException é gerado se #prepare() ou #prepareAsync() é chamado em qualquer outro estado.</li li><>Enquanto estiver no <estado em>Prepared</em>, propriedades como volume de áudio/som, screenOnWhilePlaying, o looping pode ser ajustado invocando os métodos de conjunto correspondentes.</li></ul></li li><>Para iniciar a reprodução, #start() deve ser chamado. Depois #start() de retornar com êxito, o objeto MediaPlayer está no <estado em>Started</em> . #isPlaying() pode ser chamado para testar se o objeto MediaPlayer está no <estado em>Started</em> . <ul>li Enquanto estiver no <estado em>Started</em>, o mecanismo de player interno chamará um usuário fornecido pelo método de retorno de chamada OnBufferingUpdateListener.onBufferingUpdate() se um OnBufferingUpdateListener tiver sido registrado com antecedência via <.>#setOnBufferingUpdateListener(OnBufferingUpdateListener) Esse retorno de chamada permite que os aplicativos acompanhem o status do buffer durante o streaming de áudio/vídeo.</li><li>Calling #start() não tem nenhum efeito em um objeto MediaPlayer que já está no <estado em>Started</em>.</li></ul></li li><>Playback pode ser pausado e interrompido, e a posição de reprodução atual pode ser ajustada. A reprodução pode ser pausada por meio de #pause(). Quando a chamada a ser #pause() retornada, o objeto MediaPlayer insere o <estado em>Pausa/<em> . Observe que a transição do <estado em>Started</em> para o <estado em>Pausa/<em> e vice-versa ocorre de forma assíncrona no mecanismo do player. Pode levar algum tempo até que o estado seja atualizado em chamadas para #isPlaying(), e pode ser um número de segundos no caso de conteúdo transmitido. <ul><li>Calling #start() para retomar a reprodução de um objeto MediaPlayer pausado, e a posição de reprodução retomada é a mesma de onde foi pausada. Quando a chamada a ser #start() retornada, o objeto MediaPlayer pausado volta para o <estado em Iniciado></em.></li><li>Calling #pause() não tem nenhum efeito em um objeto MediaPlayer que já está no <estado em>Pausado</em>.</li>/ul<>/li li<><Chamada > interrompe a reprodução e faz com que um MediaPlayer in the #stop()em<Started>/em<, >em<Paused>/em<, >em<Prepared >/em< ou >em<PlaybackCompleted>/em< state insira o >estado em Em<Stopped>/em<.> <ul><li>Uma vez no <estado em>Parado</em>, a reprodução não pode ser iniciada até #prepare() ou #prepareAsync() é chamada para definir o objeto MediaPlayer para o <estado em>Prepared</em> novamente.</li><li>Calling #stop() não tem nenhum efeito em um objeto MediaPlayer que já está no <estado em>Stopped</em>.</li>/ul<>/li li<><A posição de reprodução pode ser ajustada com uma chamada para >.#seekTo(long, int) <ul><li>Embora a chamada assíncrona #seekTo(long, int) retorne imediatamente, a operação de busca real pode levar um tempo para ser concluída, especialmente para áudio/vídeo sendo transmitido. Quando a operação de busca real for concluída, o mecanismo de player interno chamará um usuário fornecido por OnSeekComplete.onSeekComplete() se um OnSeekCompleteListener tiver sido registrado com antecedência via #setOnSeekCompleteListener(OnSeekCompleteListener).</li li><>Observe que #seekTo(long, int) também pode ser chamado nos outros estados, como <em>Prepared</em>, <em>Paused</em> e <em>PlaybackCompleted </em> state. Quando #seekTo(long, int) for chamado nesses estados, um quadro de vídeo será exibido se o fluxo tiver vídeo e a posição solicitada for válida. </li li><>Além disso, a posição de reprodução atual real pode ser recuperada com uma chamada para#getCurrentPosition(), o que é útil para aplicativos como um player de música que precisa acompanhar o progresso da reprodução.</li></ul></li li><>Quando a reprodução atinge o final do fluxo, a reprodução é concluída. <ul>li Se o modo de looping estava sendo definido como <var>true</var> com<, o objeto MediaPlayer permanecerá no >estado em#setLooping(boolean)Started</em>.<></li li><>Se o modo de looping foi definido como <var>false </var>, o mecanismo de player chamará um método de retorno de chamada fornecido pelo usuário, OnCompletion.onCompletion(), se um OnCompletionListener for registrado de antemão via .#setOnCompletionListener(OnCompletionListener) A invocação dos sinais de retorno de chamada de que o objeto está agora no <estado em> PlaybackCompleted</em> .</li><li>Enquanto estiver no <estado em>PlaybackCompleted</em> , a chamada #start() pode reiniciar a reprodução desde o início da fonte de áudio/vídeo.</li></ul>

"Valid_and_Invalid_States"><h3>Estados< válidos e inválidos/h3>

<table border="0" cellspacing="0" cellpadding="0">tr td<Method Name ></p>/td td<><>Valid States </p>/td td<><>Invalid States </p>/td td<><>Comments </p>/td</tr><><tr>td<attachAuxEffect ></p>/td<><td>{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted}</p>/td td<><>{Idle, Error}</p/><>< td><td>Esse método deve ser chamado após setDataSource. Chamá-lo não altera o estado do objeto. </p></td></tr><tr><td>getAudioSessionId </p></td td><>any </p></td><td>{}</p></td><td>Esse método pode ser chamado em qualquer estado e chamá-lo não altera o estado do objeto. </p></td></tr><tr><td>getCurrentPosition </p></td td><>{Idle, Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted}</p></td td><>{Error}</p></td td><>Invocação bem-sucedida desse método em um estado válido não altera o estado. Chamar esse método em um estado inválido transfere o objeto para o <estado em>Error</em> . </p></td></tr><tr><td>getDuration </p></td td><>{Prepared, Started, Paused, Stopped, PlaybackCompleted}</p></td td><>{Idle, Initialized, Error}</p></td td><>Invocação bem-sucedida desse método em um estado válido não altera o estado. Chamar esse método em um estado inválido transfere o objeto para o <estado em>Error</em> . </p></td></tr><tr><td>getVideoHeight </p></td td><>{Idle, Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted}</p></td td><>{Error}</p></td td><>Invocação bem-sucedida desse método em um estado válido não altera o estado. Chamar esse método em um estado inválido transfere o objeto para o <estado em>Error</em> . </p></td></tr><tr><td>getVideoWidth </p></td td><>{Idle, Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted}</p></td td><>{Error}</p></td td><>Invocação bem-sucedida desse método em um estado válido não altera o estado. Chamar esse método em um estado inválido transfere o objeto para o <estado em>Error</em> . </p></td></tr><tr><td>isPlaying </p></td td><>{Idle, Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted}</p></td td><>{Error}</p></td td><>Invocação bem-sucedida desse método em um estado válido não altera o estado. Chamar esse método em um estado inválido transfere o objeto para o <estado em>Error</em> . </p></td></tr><tr><td>pause </p></td td><>{Started, Paused, PlaybackCompleted}</p></td td><>{Idle, Initialized, Prepared, Stopped, Error}</p></td td><>invoke of this method in a valid state transfers the object to the <em>Paused</em> state. Chamar esse método em um estado inválido transfere o objeto para o <estado em>Error</em>.</p></td></tr><tr><td>prepare </p></td td><>{Initialized, Stopped}</p></td td><>{Idle, Prepared, Started, Paused, PlaybackCompleted, Error}</p></td td><td>Successful invoke of this method in a valid state transfers the object to the <em>Prepared</em> state. Chamar esse método em um estado inválido lança uma IllegalStateException.</p></td></tr><tr><td>prepareAsync </p></td td><>{Initialized, Stopped}</p></td td><>{Idle, Prepared, Started, Paused, PlaybackCompleted, Error}</p></td td><>Invocação bem-sucedida desse método em um estado válido transfere o objeto para o <estado em>Preparação</em.> Chamar esse método em um estado inválido lança uma IllegalStateException.</p></td></tr><tr><td>release </p></td td><>any </p></td td><>{}</p></td td><>After#release(), you must not interact with the object. </p></td></tr><tr><td>reset </p></td td><>{Idle, Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted, Error}</p></td td><>{}</p></td td><>After#reset(), o objeto é como sendo criado.</p></td></tr><tr><td>seekTo </p></td td><>{Prepared, Started, Paused, PlaybackCompleted}</p></td td><>{Idle, Initialized, Stopped, Error}</p></td td><>Invocação bem-sucedida desse método em um estado válido não altera o estado. Chamar esse método em um estado inválido transfere o objeto para o <estado em>Error</em> . </p></td></tr><tr><td>setAudioAttributes </p></td td><>{Idle, Initialized, Stopped, Prepared, Started, Paused, PlaybackCompleted}</p></td td><>{Error}</p></td td><>Invocação bem-sucedida desse método não altera o estado. Para que o tipo de atributos de áudio de destino se torne eficaz, esse método deve ser chamado antes de prepare() ou prepareAsync().</p></td></tr><td><>setAudioSessionId </p></td td><>{Idle}</p></td td><>{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted, Error}</p></td><td>esse método deve ser chamado em estado ocioso, pois a ID da sessão de áudio deve ser conhecida antes de chamar setDataSource. Chamá-lo não altera o estado do objeto. </p></td></tr><tr><td>setAudioStreamType (preterido)</p></td td><>{Idle, Initialized, Stopped, Prepared, Started, Paused, PlaybackCompleted}</p></td td><>{Error}</p></td td><>Invocação bem-sucedida desse método não altera o estado. Para que o tipo de fluxo de áudio de destino se torne eficaz, esse método deve ser chamado antes de preparar() ou prepararAsync().</p></td></tr><tr><td>setAuxEffectSendLevel </p></td td><>any</p></td td><>{}</p></td td><>Chamando esse método não altera o estado do objeto. </p></td></tr><tr><td>setDataSource </p></td td><>{Idle}</p></td td><>{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted, Error}</p></td td><>Invocação bem-sucedida desse método em um estado válido transfere o objeto para o <estado inicializado></em.> Chamar esse método em um estado inválido lança uma IllegalStateException.</p></td></tr><tr><td>setDisplay </p></td td><>any </p></td td><>{}</p></td td><>Esse método pode ser chamado em qualquer estado e chamá-lo não altera o estado do objeto. </p></td></tr><tr><td>setSurface </p></td td><>any </p></td td><>{}</p></td td><>Esse método pode ser chamado em qualquer estado e chamá-lo não altera o estado do objeto. </p></td></tr><tr><td>setVideoScalingMode </p></td td><>{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted}</p></td td><>{Idle, Error}</p></td td><>Invocação bem-sucedida desse método não altera o estado.</p></td></tr><tr><td>setLooping </p></td td><>{Idle, Initialized, Stopped, Prepared, Started, Paused, PlaybackCompleted}</p></td td><>{Error}</p></td td><>Invocação bem-sucedida desse método em um estado válido não altera o estado. Chamar esse método em um estado inválido transfere o objeto para o <estado em>Error</em>.</p></td></tr><tr><td>isLooping </p></td td><>any </p></td td><>{}</p></td td><>Esse método pode ser chamado em qualquer estado e chamá-lo não altera o estado do objeto. </p></td></tr><td><>setOnBufferingUpdateListener </p></td td><>any </p></td td><>{}</p></td><td>Esse método pode ser chamado em qualquer estado e chamá-lo não altera o estado do objeto. </p></td></tr><td><>setOnCompletionListener </p></td td><>any </p></td td><>{}</p></td><td>Esse método pode ser chamado em qualquer estado e chamá-lo não altera o estado do objeto. </p></td></tr><td><>setOnErrorListener </p></td td><>any </p></td td><>{}</p></td><td>Esse método pode ser chamado em qualquer estado e chamá-lo não altera o estado do objeto. </p></td></tr><td><>setOnPreparedListener </p></td td><>any </p></td td><>{}</p></td><td>Esse método pode ser chamado em qualquer estado e chamá-lo não altera o estado do objeto. </p></td></tr><td><>setOnSeekCompleteListener </p></td><td>any </p></td td><>{}</p></td><td>Esse método pode ser chamado em qualquer estado e chamá-lo não altera o estado do objeto. </p></td></tr><tr><td>setPlaybackParams</p></td td><>{Initialized, Prepared, Started, Paused, PlaybackCompleted, Error}</p></td td><>{Idle, Stopped}</p></td><td>Esse método alterará o estado em alguns casos, dependendo de quando for chamado. </p></td></tr><tr><td>setScreenOnWhilePlaying</></td td><>any </p></td td><>{}</p></td><td>Esse método pode ser chamado em qualquer estado e chamá-lo não altera o estado do objeto. </p></td></tr><tr><td>setVolume </p></td td><>{Idle, Initialized, Stopped, Prepared, Started, Paused, PlaybackCompleted}</p></td td><>{Error}</p></td td><>Invocação bem-sucedida desse método não altera o estado. <tr><td>setWakeMode </p></td td><>any </p></td td><>{}</p></td><td>Esse método pode ser chamado em qualquer estado e chamá-lo não altera o estado do objeto.</p></td></tr><tr><td>start </p></td td><>{Prepared, Started, Paused, PlaybackCompleted}</p></td><td>{Idle, Initialized, Stopped, Error}</p></td td><>Successful invoke of this method in a valid state transfers the object to the <em>Started</em> state. Chamar esse método em um estado inválido transfere o objeto para o <estado em>Error</em>.</p></td></tr><tr td><>stop </p></td td><>{Prepared, Started, Stopped, Paused, PlaybackCompleted}</p></td td><>{Idle, Initialized, Error}</p></td td><>invoke of this method in a valid state transfers the object to the <em>Stopped</em> state. Chamar esse método em um estado inválido transfere o objeto para o <estado em>Error</em>.</p></td></tr><tr><td>getTrackInfo </p></td td><>{Prepared, Started, Stopped, Paused, PlaybackCompleted}</p></td td><>{Idle, Initialized, Error}</p></td td><>Invocação bem-sucedida desse método não altera o estado.</p></td></tr><tr><td>addTimedTextSource </p></td td><>{Prepared, Started, Stopped, Paused, PlaybackCompleted}</p></td td><>{Idle, Initialized, Error}</p></td td><>Invocação bem-sucedida desse método não altera o estado.</p></td></tr><tr><td>selectTrack </p></td td><>{Prepared, Started, Stopped, Paused, PlaybackCompleted}</p></td td><>{Idle, Initialized, Error}</p></td td><>Invocação bem-sucedida desse método não altera o estado.</p></td></tr><tr><td>deselectTrack </p></td td><>{Prepared, Started, Stopped, Paused, PlaybackCompleted}</p></td td><>{Idle, Initialized, Error}</p></td td><>Invocação bem-sucedida desse método não altera o estado.</p></td></tr>

</table>

"Permissões"><h3>Permissões</h3>

Talvez seja necessário declarar um elemento de permissão android.R.styleable#AndroidManifestUsesPermission <uses-permission> de WAKE_LOCK correspondente.

Essa classe requer a android.Manifest.permission#INTERNET permissão quando usada com conteúdo baseado em rede.

"Retornos de chamada"><h3>Retornos de< chamada/h3>

Os aplicativos podem querer se registrar para eventos informativos e de erro para serem informados de alguma atualização de estado interna e possíveis erros de runtime durante a reprodução ou streaming. O registro desses eventos é feito definindo corretamente os ouvintes apropriados (por meio de chamadas para#setOnPreparedListener(OnPreparedListener) setOnPreparedListener, #setOnVideoSizeChangedListener(OnVideoSizeChangedListener) setOnVideoSizeChangedListener, #setOnSeekCompleteListener(OnSeekCompleteListener) setOnSeekCompleteListener, , #setOnCompletionListener(OnCompletionListener) setOnCompletionListener#setOnBufferingUpdateListener(OnBufferingUpdateListener) setOnBufferingUpdateListener, #setOnInfoListener(OnInfoListener) setOnInfoListener, , #setOnErrorListener(OnErrorListener) setOnErrorListeneretc. Para receber o respectivo retorno de chamada associado a esses ouvintes, os aplicativos são necessários para criar objetos MediaPlayer em um thread com seu próprio Looper em execução (o thread de interface do usuário principal por padrão tem um Looper em execução).

Java documentação para android.media.MediaPlayer.

Partes desta página são modificações baseadas no trabalho criado e compartilhado pelo Project Open Source do Open Source e usadas de acordo com os termos descritos na Creative Commons 2.5.