Primeiros passos

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

1. Adicione o ExoPlayer como uma dependência do projeto.
2. Crie uma instância ExoPlayer.
3. Conecte 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 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 a reprodução DASH e componentes de interface, você pode adicionar dependências aos módulos como este:

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")

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"

em que 1.3.1 é sua versão preferida. A versão mais recente pode ser encontrada consultando as notas da versão. Todos os módulos precisam ter a mesma versão.

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

Saiba mais sobre os módulos de biblioteca disponíveis na página Google Maven AndroidX Media.

Ativar a compatibilidade com Java 8

Se ainda não estiver ativado, será necessário ativar a compatibilidade com o 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

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.

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

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. O uso da linha de execução principal do aplicativo é um requisito ao usar os componentes de interface 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 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 em que o player precisa ser acessado pode ser consultado usando Player.getApplicationLooper.

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

Anexar o player a uma visualização

A biblioteca do ExoPlayer oferece vários 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. Uma PlayerView pode ser incluída no XML de layout do aplicativo. Por exemplo, para vincular o jogador à visualização:

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

// 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, 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 uma MediaItem. Para abrir uma mídia, você precisa 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()

// 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:

// 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()

// 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 recortar e anexar arquivos de legendas, na página Itens de mídia.

Controlar o player

Quando o player estiver preparado, a reprodução poderá 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 é repetida.
• setShuffleModeEnabled controla o embaralhamento de playlists.
• O setPlaybackParameters ajusta a velocidade do vídeo e o tom do áudio.

Se o player estiver vinculado a uma PlayerView ou PlayerControlView, a interação do usuário com esses componentes fará 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.