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 player com uma 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 a reprodução DASH e componentes de interface, você pode adicionar dependências aos módulos como este:

Kotlin

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

Groovy

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

em que 1.4.1 é a versão de sua preferência. 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.

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
}

Ativar multidex

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

Criar o player

Você pode 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 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. 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 nenhum Looper for especificado, o Looper da linha de execução em que o player foi criado será usado. Se essa linha 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 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);

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

O uso de componentes de interface pré-criados do ExoPlayer é opcional. Para apps de vídeo que implementam a própria interface, os destinos SurfaceView, TextureView, SurfaceHolder ou Surface podem ser definidos 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 a playlists diretamente. Por isso, é 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 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. É 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. Aqui estã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 a mídia é reproduzida em loop.
• setShuffleModeEnabled controla a ordem aleatória da playlist.
• O 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.

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 o uso por outros aplicativos. Para fazer isso, chame ExoPlayer.release.