Adicionar controles de mídia ao app

Um app que reproduz mídia requer componentes de interface do usuário para exibir mídia e controlar a reprodução. A biblioteca Media3 inclui um módulo de interface que contém vários componentes de interface. Para depender do módulo da interface, adicione a seguinte dependência:

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

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

O componente mais importante é PlayerView, uma visualização para reproduções de mídia. O PlayerView exibe o vídeo, as legendas e a capa do álbum durante a reprodução, além dos controles de reprodução.

PlayerView tem um método setPlayer para anexar e desanexar (transmitindo null) instâncias do jogador.

PlayerView

PlayerView pode ser usado para reproduções de vídeo e áudio. Ele renderiza vídeo e legendas no caso de reprodução de vídeo e pode exibir artes incluídas como metadados nos arquivos de áudio. Ela pode ser incluída nos arquivos de layout como qualquer outro componente de IU. Por exemplo, um PlayerView pode ser incluído no seguinte XML:

<androidx.media3.ui.PlayerView
    android:id="@+id/player_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:show_buffering="when_playing"
    app:show_shuffle_button="true"/>

O snippet acima ilustra que PlayerView fornece vários atributos. Esses atributos podem ser usados para personalizar o comportamento da visualização, bem como a aparência dela. A maioria desses atributos tem métodos setter correspondentes, que podem ser usados para personalizar a visualização no momento da execução. O Javadoc PlayerView lista esses atributos e métodos setter em mais detalhes.

Depois que a visualização é declarada no arquivo de layout, ela pode ser pesquisada no método onCreate da atividade:

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  // ...
  playerView = findViewById(R.id.player_view)
}

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  // ...
  playerView = findViewById(R.id.player_view);
}

Quando um player é inicializado, ele pode ser anexado à visualização chamando setPlayer:

// Instantiate the player.
val player = ExoPlayer.Builder(context).build()
// Attach player to the view.
playerView.player = player
// Set the media item to be played.
player.setMediaItem(mediaItem)
// Prepare the player.
player.prepare()

// Instantiate the player.
player = new ExoPlayer.Builder(context).build();
// Attach player to the view.
playerView.setPlayer(player);
// Set the media item to be played.
player.setMediaItem(mediaItem);
// Prepare the player.
player.prepare();

Escolha um tipo de plataforma

O atributo surface_type de PlayerView permite definir o tipo de plataforma usada para reprodução de vídeo. Além dos valores spherical_gl_surface_view (que é um valor especial para reprodução de vídeos esféricos) e video_decoder_gl_surface_view (que é para renderização de vídeo usando renderizadores de extensão), os valores permitidos são surface_view, texture_view e none. Se a visualização for apenas para reprodução de áudio, use none para evitar a necessidade de criar uma superfície, porque isso pode sair caro.

Se a visualização for para reprodução de vídeo normal, surface_view ou texture_view precisam ser usados. O SurfaceView tem uma série de benefícios em relação ao TextureView para reprodução de vídeo:

• Consumo de energia significativamente menor em muitos dispositivos.
• Tempo de renderização de frames mais preciso, resultando em uma reprodução de vídeo mais suave.
• Suporte a saída de vídeo HDR com maior qualidade em dispositivos compatíveis.
• Suporte para saída segura ao reproduzir conteúdo protegido por DRM.
• A capacidade de renderizar conteúdo de vídeo na resolução máxima da tela em dispositivos Android TV que aprimoram a camada da interface.

Portanto, dê preferência a SurfaceView em vez de TextureView sempre que possível. TextureView só será usado se SurfaceView não atender às suas necessidades. Um exemplo é quando animações ou rolagem suaves da superfície do vídeo são necessárias antes do Android 7.0 (nível 24 da API), conforme descrito nas notas a seguir. Para esse caso, é preferível usar TextureView somente quando SDK_INT for menor que 24 (Android 7.0) e SurfaceView de outra forma.

Navegação com botão direcional no Android TV

O controle remoto do Android TV tem um botão direcional que envia comandos que chegam como um evento de tecla em dispatchKeyEvent(KeyEvent) das Activity. Eles precisam ser delegados à visualização do jogador:

override fun dispatchKeyEvent(event: KeyEvent?): Boolean{
  return playerView.dispatchKeyEvent(event!!) || super.dispatchKeyEvent(event)
}

@Override
public boolean dispatchKeyEvent(KeyEvent event) {
  return playerView.dispatchKeyEvent(event) || super.dispatchKeyEvent(event);
}

Solicitar o foco para a visualização do player é importante para navegar pelos controles de reprodução e pular anúncios. Solicite o foco em onCreate do Activity:

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  // ...
  playerView.requestFocus()
  // ...
}

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // ...
    playerView.requestFocus();
    // ...
}

Se você estiver usando o Compose no Android TV, será necessário tornar o AndroidView focalizável e delegar o evento transmitindo o parâmetro modificador para o AndroidView corretamente:

AndroidView(
  modifier = modifier
    .focusable()
    .onKeyEvent { playerView.dispatchKeyEvent(it.nativeKeyEvent) },
  factory = { playerView }
)

Substituir drawables

O PlayerView usa PlayerControlView para mostrar os controles de reprodução e a barra de progresso. Os drawables usados por PlayerControlView podem ser substituídos por drawables com os mesmos nomes definidos no aplicativo. Consulte o Javadoc PlayerControlView para uma lista de drawables de controle que podem ser modificados.

Mais personalização

Quando a personalização além da descrita acima for necessária, esperamos que os desenvolvedores de apps implementem os próprios componentes de interface em vez de usar os fornecidos pelo módulo de interface do Media3.