Vamos começar

Para casos de uso simples, começar a usar o ExoPlayer consiste em implementar as seguintes etapas:

  1. Adicione o ExoPlayer como uma dependência ao seu projeto.
  2. Crie uma instância ExoPlayer.
  3. Anexe o player a uma visualização (para saída de vídeo e entrada do usuário).
  4. Prepare o player com um MediaItem para tocar.
  5. Libere o player quando terminar.

Essas etapas são descritas com mais detalhes abaixo. Para um exemplo completo, consulte PlayerActivity no app de demonstração principal.

Adicionar o ExoPlayer como uma dependência

Adicionar módulos do ExoPlayer

A maneira mais fácil de começar a usar o AndroidX Media3 é adicionar dependências do Gradle nas bibliotecas necessárias no arquivo build.gradle do módulo do app.

Por exemplo, para depender do ExoPlayer com suporte à reprodução de DASH e componentes de interface você pode adicionar dependências aos módulos assim:

Kotlin

implementation("androidx.media3:media3-exoplayer:1.7.1")
implementation("androidx.media3:media3-exoplayer-dash:1.7.1")
implementation("androidx.media3:media3-ui:1.7.1")
implementation("androidx.media3:media3-ui-compose:1.7.1")

Groovy

implementation "androidx.media3:media3-exoplayer:1.7.1"
implementation "androidx.media3:media3-exoplayer-dash:1.7.1"
implementation "androidx.media3:media3-ui:1.7.1"
implementation("androidx.media3:media3-ui-compose:1.7.1")

em que 1.7.1 é sua versão preferida. Para encontrar a versão mais recente, consulte as notas da versão. Todos os módulos precisam ser da mesma versão.

O AndroidX Media3 tem módulos de biblioteca que dependem de bibliotecas externas para oferecer mais funcionalidades. Alguns estão disponíveis no repositório Maven, enquanto outros precisam ser criados manualmente. Navegue pelo diretório de bibliotecas e confira os arquivos LEIAME individuais para mais detalhes.

Para mais informações sobre os módulos de biblioteca disponíveis, acesse a página do Google Maven AndroidX Media.

Ativar a compatibilidade com o Java 8

Se ainda não estiver ativado, ative pelo menos o suporte ao Java 8 em todos os arquivos build.gradle que dependem do ExoPlayer. Para isso, adicione o seguinte à seção android:

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

Criar o player

É possível criar uma instância ExoPlayer usando ExoPlayer.Builder, que oferece uma variedade de opções de personalização. O código a seguir é o exemplo mais simples de criação de uma instância.

Kotlin

val player = ExoPlayer.Builder(context).build()

Java

ExoPlayer player = new ExoPlayer.Builder(context).build();

Observação sobre linhas de execução

As instâncias do ExoPlayer precisam ser acessadas de uma única linha de execução do aplicativo. Na maioria dos casos, essa é a linha de execução principal do aplicativo. O uso do thread principal do aplicativo é obrigatório ao usar os componentes de interface do ExoPlayer ou a extensão da IMA.

A linha de execução em que uma instância do ExoPlayer precisa ser acessada pode ser especificada explicitamente transmitindo um Looper ao criar o player. Se nenhum Looper for especificado, o Looper da linha de execução em que o player foi criado será usado. Se essa linha de execução não tiver um Looper, o Looper da linha de execução principal do aplicativo será usado. Em todos os casos, o Looper da linha de execução em que o jogador precisa ser acessado pode ser consultado usando Player.getApplicationLooper.

Para mais informações sobre o modelo de linhas de execução do ExoPlayer, consulte a seção "Modelo de linhas de execução" do Javadoc do ExoPlayer.

Anexar o player a uma visualização

A biblioteca ExoPlayer oferece uma variedade de componentes de interface pré-criados para reprodução de mídia. Isso inclui PlayerView, que encapsula um PlayerControlView, um SubtitleView e um Surface em que o vídeo é renderizado. Um PlayerView pode ser incluído no XML de layout do aplicativo. Por exemplo, para vincular o player à visualização:

Kotlin

// Bind the player to the view.
playerView.player = player

Java

// Bind the player to the view.
playerView.setPlayer(player);

O uso dos componentes de interface pré-criados do ExoPlayer é opcional. Para apps de vídeo que implementam a própria interface, o SurfaceView, TextureView, SurfaceHolder ou Surface de destino podem ser definidos usando os métodos setVideoSurfaceView, setVideoTextureView, setVideoSurfaceHolder e setVideoSurface do ExoPlayer respectivamente. O callback Listener.onCues pode ser usado para receber legendas que devem ser renderizadas durante a reprodução, e o setImageOutput pode ser usado para receber imagens decodificadas.

Para uma experiência do usuário mais confortável, considere adicionar o atributo keepScreenOn ou definir o bloqueio de despertar no ExoPlayer. Você pode investigar outras ações que mantêm o dispositivo ativo nas páginas de trabalho em segundo plano.

android:keepScreenOn="true"

Leia mais sobre como usar os componentes de interface do Media3 e a personalização deles na página de interface.

Preencher a playlist e preparar o player

No ExoPlayer, cada mídia é representada por um MediaItem. Para tocar uma mídia, é preciso criar um MediaItem correspondente, adicioná-lo ao player, preparar o player e chamar play para iniciar a reprodução:

Kotlin

// Build the media item.
val mediaItem = MediaItem.fromUri(videoUri)
// Set the media item to be played.
player.setMediaItem(mediaItem)
// Prepare the player.
player.prepare()
// Start the playback.
player.play()

Java

// Build the media item.
MediaItem mediaItem = MediaItem.fromUri(videoUri);
// Set the media item to be played.
player.setMediaItem(mediaItem);
// Prepare the player.
player.prepare();
// Start the playback.
player.play();

O ExoPlayer oferece suporte direto a playlists. Portanto, é possível preparar o player com vários itens de mídia para serem reproduzidos um após o outro:

Kotlin

// Build the media items.
val firstItem = MediaItem.fromUri(firstVideoUri)
val secondItem = MediaItem.fromUri(secondVideoUri)
// Add the media items to be played.
player.addMediaItem(firstItem)
player.addMediaItem(secondItem)
// Prepare the player.
player.prepare()
// Start the playback.
player.play()

Java

// Build the media items.
MediaItem firstItem = MediaItem.fromUri(firstVideoUri);
MediaItem secondItem = MediaItem.fromUri(secondVideoUri);
// Add the media items to be played.
player.addMediaItem(firstItem);
player.addMediaItem(secondItem);
// Prepare the player.
player.prepare();
// Start the playback.
player.play();

A playlist pode ser atualizada durante a reprodução sem precisar preparar o player novamente. Leia mais sobre como preencher e manipular a playlist na página "Playlists". Saiba mais sobre as diferentes opções disponíveis ao criar itens de mídia, como corte e anexação de arquivos de legenda, na página "Itens de mídia".

Controlar o player

Depois que o player for preparado, a reprodução poderá ser controlada chamando métodos no player. Confira alguns dos métodos mais usados:

  • play e pause iniciam e pausam a reprodução.
  • O seekTo permite buscar na mídia.
  • hasPrevious, hasNext, previous e next permitem navegar pela playlist.
  • setRepeatMode controla se e como a mídia é reproduzida em loop.
  • setShuffleModeEnabled controla a ordem aleatória da playlist.
  • O setPlaybackParameters ajusta a velocidade de reprodução e o tom do áudio.

Se o player estiver vinculado a um PlayerView ou PlayerControlView, a interação do usuário com esses componentes vai invocar os métodos correspondentes no player.

Soltar o player

É importante liberar o player quando ele não for mais necessário para liberar recursos limitados, como decodificadores de vídeo, para uso por outros aplicativos. Para isso, chame ExoPlayer.release.