Cómo agregar controles de reproducción a tu app

Una app que reproduce contenido multimedia requiere componentes de interfaz de usuario para mostrar contenido multimedia y controlar la reproducción. La biblioteca Media3 incluye un módulo de IU que contiene una serie de componentes de IU. Para depender del módulo de IU, agrega la siguiente dependencia:

Kotlin

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

Groovy

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

El componente más importante es PlayerView, una vista para la reproducción de contenido multimedia. PlayerView muestra videos, imágenes, subtítulos y la portada del álbum durante la reproducción, así como los controles de reproducción.

PlayerView tiene un método setPlayer para conectar y desconectar (pasando null) instancias de reproductores.

PlayerView

PlayerView se puede usar para la reproducción de video, imagen y audio. Renderiza el video y los subtítulos en el caso de la reproducción de video, los mapas de bits para la reproducción de imágenes y puede mostrar material gráfico incluido como metadatos en archivos de audio. Puedes incluirlo en tus archivos de diseño como cualquier otro componente de la IU. Por ejemplo, se puede incluir un PlayerView con el siguiente 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"/>

En el fragmento anterior, se ilustra que PlayerView proporciona varios atributos. Estos atributos se pueden usar para personalizar el comportamiento de la vista, así como su apariencia. La mayoría de estos atributos tienen métodos setcorrespondientes, que se pueden usar para personalizar la vista durante el tiempo de ejecución. En el Javadoc de PlayerView, se enumeran estos atributos y métodos set en más detalle.

Una vez que se declara la vista en el archivo de diseño, se puede buscar en el método onCreate de la actividad:

Kotlin

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

Java

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

Cuando se inicializa un reproductor, se puede adjuntar a la vista llamando a setPlayer:

Kotlin

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

Java

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

Elige un tipo de plataforma

El atributo surface_type de PlayerView te permite establecer el tipo de superficie que se usa para la reproducción de video. Además de los valores spherical_gl_surface_view (que es un valor especial para la reproducción de videos esféricos) y video_decoder_gl_surface_view (que es para la renderización de videos con renderizadores de extensiones), los valores permitidos son surface_view, texture_view y none. Si la vista es solo para la reproducción de audio, se debe usar none para evitar tener que crear una superficie, ya que hacerlo puede ser costoso.

Si la vista es para la reproducción de video normal, se debe usar surface_view o texture_view. SurfaceView tiene varios beneficios sobre TextureView para la reproducción de video:

• Disminuye significativamente el consumo de energía en muchos dispositivos.
• Tiempos de fotogramas más precisos, lo que brinda una reproducción de video más fluida
• Compatibilidad con una salida de video HDR de mayor calidad en dispositivos compatibles
• Compatibilidad con salidas seguras cuando se reproduce contenido protegido por DRM
• La capacidad de renderizar contenido de video con la resolución completa de la pantalla en dispositivos Android TV que mejoran la capa de la IU

Por lo tanto, se debe preferir SurfaceView en lugar de TextureView siempre que sea posible. TextureView solo debe usarse si SurfaceView no satisface tus necesidades. Un ejemplo es cuando se requieren animaciones fluidas o el desplazamiento de la superficie de video antes de Android 7.0 (nivel de API 24), como se describe en las siguientes notas. En este caso, es preferible usar TextureView solo cuando SDK_INT sea inferior a 24 (Android 7.0) y SurfaceView en caso contrario.

Nota: La renderización de SurfaceView no se sincronizaba correctamente con las animaciones de vista hasta Android 7.0 (nivel de API 24). En versiones anteriores, esto podía generar efectos no deseados cuando se colocaba un SurfaceView en un contenedor de desplazamiento o cuando se sometía a animación. Entre estos efectos, se incluía que el contenido de la vista parecía retrasarse un poco con respecto a dónde debería mostrarse y que la vista se volvía negra cuando se sometía a animación. Para lograr una animación o un desplazamiento de video fluidos antes de Android 7.0, por lo tanto, es necesario usar TextureView en lugar de SurfaceView.

Nota: El ciclo de vida de la superficie de un SurfaceView está vinculado a la visibilidad de la vista, mientras que el ciclo de vida de la superficie de un TextureView está vinculado a la conexión y desconexión de la ventana. Por lo tanto, en las IU de desplazamiento que usan SurfaceView, iniciar la reproducción puede tardar más porque la superficie de salida estará disponible un poco más tarde. A partir de Android 14, PlayerView usa SurfaceView.setSurfaceLifecycle(SURFACE_LIFECYCLE_FOLLOWS_ATTACHMENT) para evitar este comportamiento. Si tu app usa SurfaceView directamente (sin PlayerView), te recomendamos que habilites este modo. Antes de Android 14, es posible evitar que se destruya la superficie transfiriendo vistas fuera de la pantalla cuando se reciclan.

Nota: Algunos dispositivos Android TV ejecutan su capa de IU en una resolución inferior a la resolución completa de la pantalla y la mejoran para presentarla al usuario. Por ejemplo, la capa de la IU se puede ejecutar a 1080p en una Android TV que tenga una pantalla 4K. En esos dispositivos, se debe usar SurfaceView para renderizar contenido en la resolución completa de la pantalla. La resolución completa de la pantalla (en su modo de visualización actual) se puede consultar con Util.getCurrentDisplayModeSize. La resolución de la capa de IU se puede consultar con la API de Display.getSize de Android.

Navegación con el pad direccional en Android TV

El control remoto de Android TV tiene un control de pad direccional que envía comandos que llegan como evento de tecla a dispatchKeyEvent(KeyEvent) de tu Activity. Estos deben delegarse a la vista del reproductor:

Kotlin

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

Java

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

Solicitar el enfoque para la vista del reproductor es importante para navegar por los controles de reproducción y omitir anuncios. Considera solicitar el enfoque en onCreate de Activity:

Kotlin

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

Java

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

Si usas Compose en Android TV, debes hacer que AndroidView sea enfocado y delegar el evento pasando el parámetro de modificador a AndroidView según corresponda:

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

Cómo anular elementos de diseño

Precaución: No garantizamos que las personalizaciones que se describen en la siguiente sección sigan funcionando en versiones futuras de la biblioteca. Es posible que los IDs de los recursos cambien de nombre o que algunos se borren por completo. Esto se indica cuando los IDs de recursos se marcan como "privados".

PlayerView usa PlayerControlView para mostrar los controles de reproducción y la barra de progreso. Los elementos de diseño que usa PlayerControlView se pueden reemplazar por elementos de diseño con los mismos nombres definidos en tu aplicación. Consulta la página de Javadoc de PlayerControlView para obtener una lista de los elementos de diseño de control que se pueden anular.

Más personalización

Cuando se requiera una personalización más allá de la que se describió anteriormente, esperamos que los desarrolladores de apps implementen sus propios componentes de IU en lugar de usar los que proporciona el módulo de IU de Media3.