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, Java.Interop.IJavaPeerable

[<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

Object

MediaPlayer

Atributos

RegisterAttribute

Implementações

IAudioRouting IVolumeAutomation IJavaObject IJavaPeerable IDisposable

Comentários

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

O MediaPlayer não é thread-safe. A criação e todo o acesso às instâncias do jogador devem estar no mesmo thread. Se estiver registrando retornos de chamada, o thread deve 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="referência especial"><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>Diagrama de Estado</h3>

O controle de reprodução de arquivos e fluxos de áudio/vídeo é gerenciado como uma máquina 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. Os 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 do estado do objeto. Existem dois tipos de arcos. Os arcos com uma única cabeça de seta representam chamadas de método síncronas, enquanto aqueles com uma ponta de seta dupla representam chamadas de método assíncronas.

<img src=".. /.. /.. /images/mediaplayer_state_diagram.gif" alt="MediaPlayer State diagram" border="0" />

A partir deste diagrama de estado, pode-se ver que um objeto MediaPlayer tem os seguintes estados:

<ul li>Quando um objeto MediaPlayer é criado usando new ou depois #reset() é chamado, ele está no <estado em>Idle</em>, e depois #release() é chamado, ele está no <estado em>End</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() que é chamado. É um erro de programação invocar métodos como #getCurrentPosition(), #getDuration(), , #getVideoHeight(), #getVideoWidth()#setAudioAttributes(AudioAttributes), #setLooping(boolean), #setVolume(float, float), #prepare()#start()#stop()#pause()#seekTo(long, int)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 interno do player e o estado do objeto permanecerá inalterado; mas se esses métodos forem chamados logo após #reset(), o método de retorno de chamada fornecido pelo usuário OnErrorListener.onError() será chamado pelo mecanismo interno do player 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 evitar que ela seja coletada como lixo. Se uma instância do MediaPlayer for coletada, #release será chamada, fazendo com que qualquer reprodução em andamento seja interrompida. <li>Você deve ligar #release() depois de terminar de usar uma instância para liberar recursos adquiridos, como memória e codecs. Depois de chamar #releaseo , você não deve mais interagir com a instância liberada. <li>MediaPlayer objetos criados usando new está no <estado em>Idle</em> , enquanto aqueles criados com um dos métodos convenientes create sobrecarregados estão <em>NOT</em> no <estado em>Idle</em> . Na verdade, os objetos estão no estado em>Prepared</em> se a criação usando create o <método for bem-sucedida. </li></ul></li><li>Em geral, algumas operações de controle de reprodução podem falhar devido a vários motivos, como formato de áudio/vídeo não suportado, áudio/vídeo mal intercalado, resolução muito alta, tempo limite de streaming e afins. Assim, a comunicação e a recuperação de erros 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 invoca um método OnErrorListener.onError() fornecido pelo usuário se um OnErrorListener tiver sido registrado previamente via #setOnErrorListener(android.media.MediaPlayer.OnErrorListener). <><ul li>É importante observar que, uma vez que ocorre um erro, o objeto MediaPlayer entra <no 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 se recuperar do erro, #reset() pode ser chamado para restaurar o objeto ao seu <estado em>Idle</em>.<></li><li>É uma boa prática de programação fazer com que seu aplicativo registre um OnErrorListener para ficar atento a notificações de erro do mecanismo interno do player.</li><li>IllegalStateException é lançado para evitar erros de programação, como chamar #prepare(), #prepareAsync()ou um dos métodos sobrecarregados setDataSource em um estado inválido. </li></ul></li><li>Chamando #setDataSource(FileDescriptor), ou #setDataSource(String), ou #setDataSource(Context, Uri), ou , ou #setDataSource(FileDescriptor, long, long)transfere #setDataSource(MediaDataSource) um objeto MediaPlayer no <estado em>Idle</em> para o <estado em>Initialized</em> . <><ul li>Um IllegalStateException é lançado se setDataSource() é chamado em qualquer outro estado.</li><li>É uma boa prática de programação estar sempre atento IllegalArgumentException e IOException isso pode ser jogado a partir dos métodos sobrecarregadossetDataSource.</li></ul></li><li>Um objeto MediaPlayer deve primeiro entrar no estado em>Prepared/em> antes que a <reprodução possa ser iniciada<. <><ul li>Há duas maneiras (síncrona vs. assíncrona) que o <estado em>Prepared</em> pode ser alcançado: ou uma chamada para #prepare() (síncrona) que transfere o objeto para o <estado em>Prepared</em> uma vez que a chamada de método retorna, ou uma chamada para #prepareAsync() (assíncrona) que primeiro transfere o objeto para o <em>Preparing</em> após o retorno da chamada (que ocorre quase imediatamente) enquanto o mecanismo interno do jogador 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 retornar, o mecanismo interno do player chamará um método de retorno de chamada fornecido pelo usuário, onPrepared() da interface OnPreparedListener, se um OnPreparedListener for registrado previamente via #setOnPreparedListener(android.media.MediaPlayer.OnPreparedListener).</li><li>É importante observar que o <estado em>Preparing</em> é um estado transitório, e o comportamento de chamar qualquer método com efeito colateral enquanto um objeto MediaPlayer está no <estado em>Preparing</em> é indefinido.</li><li>Um IllegalStateException é lançado se #prepare() ou #prepareAsync() for chamado em qualquer outro estado.</li><li>Enquanto estiver no <estado em>Prepared</em> , propriedades como volume de áudio/som, screenOnWhilePlaying, looping podem ser ajustadas invocando os métodos de conjunto correspondentes.</li></ul></li><li>Para iniciar a reprodução, #start() deve ser chamado. Após #start() o retorno bem-sucedido, 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 chama um usuário fornecido pelo método de retorno de chamada OnBufferingUpdateListener.onBufferingUpdate() se um OnBufferingUpdateListener tiver sido registrado previamente via #setOnBufferingUpdateListener(OnBufferingUpdateListener).>< Esse retorno de chamada permite que os aplicativos acompanhem o status do buffer durante a transmissão de áudio/vídeo.</li>li A chamada #start() não tem efeito em um objeto MediaPlayer que já está no <estado em>Started</em>.<></li></ul></li><li>A reprodução pode ser pausada e interrompida, e a posição de reprodução atual pode ser ajustada. A reprodução pode ser pausada via #pause(). Quando a chamada para #pause() retorna, o objeto MediaPlayer entra <no estado em>Paused</em> . Observe que a <transição do estado em>Started</em> para o <estado em>Paused</em> e vice-versa acontece 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>Chamando #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 para #start() retorna, o objeto MediaPlayer pausado volta para o <estado em>Started</em>.</li>li A chamada #pause() não tem efeito sobre um objeto MediaPlayer que já está no <estado em>Paused</em>.<></li></ul></li><li A>chamada #stop() interrompe a <reprodução e faz com que um MediaPlayer no estado em>Started</em>, <em>Paused</em>, <em>Prepared </em> ou <em>PlaybackCompleted</em> entre no <estado em>Stopped</em>. <ul li>Uma vez no estado em>Stopped</em>, a <reprodução não pode ser iniciada até #prepare() ou #prepareAsync() são chamados para definir o objeto MediaPlayer para o <estado em>Prepared</em> novamente.<></li>li A chamada #stop() não tem 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 demorar um pouco para ser concluída, especialmente para áudio/vídeo sendo transmitido. Quando a operação de busca real é concluída, o mecanismo interno do player chama um usuário fornecido OnSeekComplete.onSeekComplete() se um OnSeekCompleteListener tiver sido registrado previamente 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 precisam 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 #setLooping(boolean), o objeto MediaPlayer deve permanecer no <estado em>Started</em>.</li><li>Se o modo de looping foi definido como <var>false </var>, o mecanismo do player chama um método de retorno de chamada fornecido pelo usuário, OnCompletion.onCompletion(), se um OnCompletionListener for registrado previamente via #setOnCompletionListener(OnCompletionListener). A chamada do retorno de chamada sinaliza que o objeto agora está no <estado em> PlaybackCompleted</em>.</li><li>Enquanto estiver no estado em>PlaybackCompleted</em>, a <chamada #start() pode reiniciar a reprodução a partir do 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>Nome <do Método /p></td><td>Estados válidos </p></td><td>Estados <inválidos /p></td><td>Comentários </p></td></tr<>tr td><>attachAuxEffect </p></td<>td>{Inicializado, Preparado, Iniciado, Pausado, Parado, ReproduçãoConcluída}</p></td><td>{Inativo, Erro}</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>qualquer </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>A 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>A 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>A 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>A 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>A 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>A invocação bem-sucedida desse método em um estado válido transfere o objeto para o <estado em>Paused</em.> 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>A invocação bem-sucedida desse método em um estado válido transfere o objeto para o <estado em>Prepared</em.> Chamar esse método em um estado inválido lança um IllegalStateException.</p></td></tr><tr><td>prepareAsync </p></td><td>{Initialized, Stopped}</p></td<>td>{Idle, Prepared, Started, Paused, PlaybackCompleted, Error}</p></td><td>A invocação bem-sucedida desse método em um estado válido transfere o objeto para o <estado em>Preparing</em.> Chamar esse método em um estado inválido lança um IllegalStateException.</p></td></tr<>tr><td>release </p></td><td>qualquer </p></td><td>{}</p></td<>td>Depois , #release()você não deve interagir com o objeto. </p></td></tr><tr><td>reset </p></td<>td>{Idle, Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted, Error}</p></td><td>{}</p></td><td>Depois #reset(), o objeto é como se estivesse apenas 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>A 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>A invocação bem-sucedida desse método não altera o estado. Para que o tipo de atributos de áudio de destino se torne efetivo, esse método deve ser chamado antes de prepare() ou prepareAsync().</p></td></tr><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 no estado ocioso, pois o ID da sessão de áudio deve ser conhecido 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>A invocação bem-sucedida desse método não altera o estado. Para que o tipo de fluxo de áudio de destino se torne efetivo, esse método deve ser chamado antes de prepare() ou prepareAsync().</p></td></tr><tr><td>setAuxEffectSendLevel </p></td><td>any</p></td><td>{}</p></td><td>Chamar 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>A invocação bem-sucedida desse método em um estado válido transfere o objeto para o <estado em>Initialized</em.> Chamar esse método em um estado inválido lança um IllegalStateException.</p></td></tr><tr><td>setDisplay </p></td><td>qualquer </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>qualquer </p></td><td>{}</p></td><td>Este 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>A 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>A 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>qualquer </p></td><td>{}</p></td><td>Este método pode ser chamado em qualquer estado e chamá-lo não altera o estado do objeto. </p></td></tr><tr><td>setOnBufferingUpdateListener </p></td><td>qualquer </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>setOnCompletionListener </p></td><td>qualquer </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>setOnErrorListener </p></td><td>qualquer </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>setOnPreparedListener </p></td><td>qualquer </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>setOnSeekCompleteListener </p></td><td>qualquer </p></td><td>{}</p></td><td>Este 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>Este método mudará de estado em alguns casos, dependendo de quando for chamado. </p></td></tr<>tr><td>setScreenOnWhilePlaying</></td><td>qualquer </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>A invocação bem-sucedida desse método não altera o estado. <tr td setWakeMode </p></td><td>qualquer </p></td><td>{}</p></td><td>Este 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>A invocação bem-sucedida desse método em um estado válido transfere o objeto para o <estado em>Started</em.> 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>A invocação bem-sucedida desse método em um estado válido transfere o objeto para o <estado em>Stopped</em.> 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>A 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>A 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>A invocação bem-sucedida deste 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>A invocação bem-sucedida deste método não altera o estado.</p></td></tr>

</mesa>

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

Pode ser necessário declarar um elemento de permissão android.R.styleable#AndroidManifestUsesPermission <uses-permission> 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 interno e possíveis erros de tempo de execução durante a reprodução ou streaming. O registro para esses eventos é feito definindo corretamente os ouvintes apropriados (através de chamadas para #setOnPreparedListener(OnPreparedListener) setOnPreparedListener, #setOnVideoSizeChangedListener(OnVideoSizeChangedListener) setOnVideoSizeChangedListener, #setOnSeekCompleteListener(OnSeekCompleteListener) setOnSeekCompleteListener, #setOnCompletionListener(OnCompletionListener) setOnCompletionListener, #setOnBufferingUpdateListener(OnBufferingUpdateListener) setOnBufferingUpdateListener, #setOnInfoListener(OnInfoListener) setOnInfoListener, #setOnErrorListener(OnErrorListener) setOnErrorListener, etc). Para receber o respectivo retorno de chamada associado a esses ouvintes, os aplicativos são obrigados a criar objetos MediaPlayer em um thread com seu próprio Looper em execução (thread principal da interface do usuário por padrão tem um Looper em execução).

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

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

Construtores

Campos

Propriedades

Métodos

Eventos

Implantações explícitas de interface

Métodos de Extensão

Aplica-se a