Vamos começar

Dica: outra maneira de começar é trabalhar com o codelab do ExoPlayer.

Para casos de uso simples, a inicialização com 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 jogador com um MediaItem para jogar.
5. Solte o player quando terminar.

Essas etapas são descritas com mais detalhes abaixo. Para conferir 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 às bibliotecas necessárias no arquivo build.gradle do módulo do app.

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

Kotlin

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

Groovy

implementation "androidx.media3:media3-exoplayer:1.5.0"
implementation "androidx.media3:media3-exoplayer-dash:1.5.0"
implementation "androidx.media3:media3-ui:1.5.0"

em que 1.5.0 é a versão de sua preferência. A versão mais recente pode ser encontrada consultando 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 do Maven, enquanto outros precisam ser criados manualmente. Navegue pelo diretório de bibliotecas e consulte os READMEs individuais para mais detalhes.

Mais informações sobre os módulos de biblioteca disponíveis podem ser encontradas na página do Google Maven AndroidX Media.

Ativar o suporte a Java 8

Se ainda não estiver ativado, ative o suporte ao Java 8 em todos os arquivos build.gradle que dependem do ExoPlayer adicionando 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 várias 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 em uma única linha de execução do aplicativo. Na grande maioria dos casos, essa é a linha de execução principal do aplicativo. Usar a linha de execução principal do aplicativo é um requisito ao usar os componentes de interface do ExoPlayer ou a extensão 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 nenhuma Looper for especificada, a Looper da linha de execução em que o player foi criado será usada. Se essa linha de execução não tiver uma Looper, a Looper da linha de execução principal do aplicativo será usada. Em todos os casos, o Looper da linha de execução de onde o jogador precisa ser acessado pode ser consultado usando Player.getApplicationLooper.

Observação: se você notar que IllegalStateException está sendo gerado com a mensagem "O jogador está sendo acessado na linha de execução errada", algum código no app está acessando uma instância ExoPlayer na linha de execução errada (o stack trace da exceção mostra onde).

Para mais informações sobre o modelo de linha de execução do ExoPlayer, consulte a seção "Modelo de linha 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 layout XML 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);

Também é possível usar PlayerControlView como um componente autônomo, o que é útil para casos de uso de áudio.

O uso de componentes de interface pré-criados do ExoPlayer é opcional. Para apps de vídeo que implementam a própria interface, o alvo SurfaceView, TextureView, SurfaceHolder ou Surface pode ser definido usando os métodos setVideoSurfaceView, setVideoTextureView, setVideoSurfaceHolder e setVideoSurface do ExoPlayer, respectivamente. O método addTextOutput do ExoPlayer pode ser usado para receber legendas que precisam ser renderizadas durante a reprodução.

Preencher a playlist e preparar o player

No ExoPlayer, cada mídia é representada por um MediaItem. Para reproduzir uma mídia, é necessário 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, então é 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 a necessidade de preparar o player novamente. Leia mais sobre como preencher e manipular a playlist na página Playlists. Leia mais sobre as diferentes opções disponíveis ao criar itens de mídia, como recorte e anexação de arquivos de legenda, na página de itens de mídia.

Observação: o Media3 ExoPlayer converte itens de mídia em instâncias de MediaSource que ele precisa internamente. Leia mais sobre esse processo e como ele pode ser personalizado na página Origens de mídia. É possível fornecer um MediaSource diretamente ao player usando ExoPlayer.setMediaSource(s) e ExoPlayer.addMediaSource(s).

Controlar o player

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

• play e pause iniciam e pausam a reprodução.
• seekTo permite a busca dentro da 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.
• 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 fazer com que os métodos correspondentes no player sejam invocados.

Liberar 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 fazer isso, chame ExoPlayer.release.