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. Anexar 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.

Esses arquivos são descritos 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 à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, adicione dependências aos módulos desta forma:

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

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

em que 1.11.1 é sua versão preferida (a versão mais recente pode ser encontrada nas 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 consulte os READMEs individuais para mais detalhes.

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

Ativar o suporte ao 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, adicionando o seguinte à seção android:

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

Criar o player

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

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

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

Observação sobre as linhas de execução

As instâncias do ExoPlayer precisam ser acessadas em uma única linha de execução do aplicativo. Na maioria dos casos, essa precisa ser a linha de execução principal do aplicativo. O uso da linha de execução principal do aplicativo é um requisito ao usar os componentes de IU do ExoPlayer ou a extensão do IMA.

A linha de execução em que uma instância do ExoPlayer precisa ser acessada pode ser explicitamente especificada transmitindo um Looper ao criar o player. Se nenhum Looper for especificado, o Looper da linha de execução em que o player é 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 de onde o player precisa ser acessado pode ser consultado usando Player.getApplicationLooper.

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 media3-ui 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:

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

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

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

Para uma experiência do usuário mais confortável, adicione o atributo keepScreenOn. É possível investigar outras ações que mantêm o dispositivo ativo nas páginas de trabalho em segundo plano.

android:keepScreenOn="true"

Se o app usa o Jetpack Compose para a interface, use o elemento combinável Player da biblioteca media3-ui-compose-material3. O Player exibe o vídeo e inclui valores pré-preenchidos para os slots de controles de mídia. Para anexar um objeto androidx.media3.common.Player a um elemento combinável androidx.media3.ui.compose.material3.Player, basta transmiti-lo como um argumento:

// Bind the player to the composable.
Player(player = player)
HelloWorld.kt

Leia mais sobre o uso de 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 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:

// 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()
HelloWorld.kt

// 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();
HelloWorld.java

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:

// 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()
HelloWorld.kt

// 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();
HelloWorld.java

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 cortar e anexar arquivos de legenda, na página de itens de mídia.

Controlar o player

Depois que o player estiver preparado, a reprodução poderá ser controlada chamando métodos nele. Confira alguns dos métodos usados com frequência:

• play e pause iniciam e pausam a reprodução.
• seekTo permite buscar na mídia.
• hasPrevious, hasNext, previous e next permitem navegar pela playlist.
• setRepeatMode controla se e como a mídia é repetida.
• setShuffleModeEnabled controla o embaralhamento da playlist.
• setPlaybackParameters ajusta a velocidade do vídeo 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 isso, chame ExoPlayer.release.