Como começar

Dica: outra maneira de começar é trabalhando no codelab do ExoPlayer (link em inglês).

Para casos de uso simples, começar a usar 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 uma MediaItem para jogar.
5. Solte 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 às 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 da seguinte forma:

Kotlin

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

Groovy

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

A versão 1.3.1 é sua preferência. 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 fornecer outras funcionalidades. Algumas estão disponíveis no repositório Maven, enquanto outras precisam ser criadas manualmente. Procure o diretório de bibliotecas e consulte os READMEs individuais para detalhes.

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

Ativar a compatibilidade com Java 8

Se ainda não estiver ativado, você precisará ativar o suporte para Java 8 em todos os arquivos build.gradle que dependem do ExoPlayer, adicionando o seguinte à seção android:

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

Ativar multidex

Se a minSdkVersion do Gradle for 20 ou anterior, ative o multidex para evitar erros de build.

Criar o player

É possível criar uma instância de ExoPlayer usando ExoPlayer.Builder, que fornece 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 as 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 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 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 é criado vai ser usado ou, se essa linha não tiver um Looper, o Looper da linha de execução principal do aplicativo vai ser usado. Em todos os casos, o Looper da linha de execução em que o player precisa ser acessado pode ser consultado usando Player.getApplicationLooper.

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

Para saber mais sobre o modelo de linha de execução do ExoPlayer, consulte a seção "Modelo de linha de execução" do Javadoc do ExoPlayer (link em inglês).

Anexar o player a uma visualização

A biblioteca do 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);

Você também pode usar PlayerControlView como um componente autônomo, o que é útil para casos de uso somente de áudio.

O uso dos componentes de interface pré-criados do ExoPlayer é 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 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 parte da mídia é representada por um MediaItem. Para abrir uma parte da mídia, é necessário criar uma MediaItem correspondente, adicioná-la 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 a necessidade de preparar o player de novo. 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 recortar e anexar arquivos de legenda, na página Itens de mídia.

Observação: o ExoPlayer da Media3 converte itens de mídia em instâncias de MediaSource necessárias internamente. Leia mais sobre esse processo e como ele pode ser personalizado na página Origens de mídia. Você pode fornecer um MediaSource diretamente ao jogador usando ExoPlayer.setMediaSource(s) e ExoPlayer.addMediaSource(s).

Controlar o player

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

• play e pause iniciam e pausam a reprodução.
• seekTo permite a busca na mídia.
• hasPrevious, hasNext, previous e next permitem navegar pela playlist.
• setRepeatMode controla se e como as mídias são reproduzidas em loop.
• setShuffleModeEnabled controla o embaralhamento de playlists.
• O recurso setPlaybackParameters ajusta a velocidade da 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 fará com que métodos correspondentes no player sejam invocados.

Solte 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 em outros aplicativos. Para fazer isso, chame ExoPlayer.release.