Eventos del jugador

Los cambios en el estado del reproductor (como el inicio de la reproducción, el almacenamiento en búfer o los errores) activan eventos que se envían a las instancias Player.Listener registradas. Estos eventos se representan mediante constantes enteras y se definen con Player.Event y Player.Events.

Cómo registrar un Player.Listener

Los eventos del reproductor se informan a las instancias Player.Listener registradas. Para registrar un objeto de escucha que reciba esos eventos, haz lo siguiente:

// Add a listener to receive events from the player.
player.addListener(listener)
ListeningToPlayerEvents.kt

// Add a listener to receive events from the player.
player.addListener(listener);
ListeningToPlayerEvents.java

Si usas Kotlin, también puedes usar las funciones de extensión de suspensión que proporciona el módulo media3-common-ktx para escuchar eventos con corrutinas. En ese caso, no necesitarás registrar ni anular el registro de un Player.Listener de forma explícita.

Cómo escuchar eventos de reproducción con Player.Listener

Player.Listener tiene métodos predeterminados vacíos, por lo que solo debes implementar los métodos que te interesen. Consulta Javadoc para obtener una descripción completa de los métodos y cuándo se llaman. A continuación, se describen con más detalle algunos de los métodos más importantes.

Los objetos de escucha pueden elegir entre implementar devoluciones de llamada de eventos individuales o una devolución de llamada onEvents genérica que se llama después de que ocurren uno o más eventos juntos. Consulta Individual callbacks vs onEvents para obtener una explicación de cuál se debe preferir para diferentes casos de uso.

Cambios en el estado de reproducción

Para recibir los cambios en el estado del reproductor, implementa onPlaybackStateChanged(@State int state) en un Player.Listener registrado. El reproductor puede estar en uno de los cuatro estados de reproducción:

• Player.STATE_IDLE: Es el estado inicial, el estado cuando se detiene el reproductor y cuando falla la reproducción. En este estado, el reproductor solo tendrá recursos limitados.
• Player.STATE_BUFFERING: El reproductor no puede reproducir de inmediato desde su posición actual. Esto sucede principalmente porque se deben cargar más datos.
• Player.STATE_READY: El reproductor puede reproducir de inmediato desde su posición actual.
• Player.STATE_ENDED: El reproductor terminó de reproducir todo el contenido multimedia.

Además de estos estados, el reproductor tiene una marca playWhenReady para indicar la intención del usuario de reproducir contenido. Para recibir los cambios en esta marca, implementa onPlayWhenReadyChanged(playWhenReady, @PlayWhenReadyChangeReason int reason).

Un reproductor está reproduciendo contenido (es decir, su posición avanza y se presenta contenido multimedia al usuario) cuando se cumplen las siguientes tres condiciones:

• El reproductor está en el estado Player.STATE_READY.
• playWhenReady es true.
• La reproducción no se suprime por un motivo que muestra Player.getPlaybackSuppressionReason.

En lugar de tener que verificar estas propiedades de forma individual, se puede llamar a Player.isPlaying. Para recibir los cambios en este estado, implementa onIsPlayingChanged(boolean isPlaying):

player.addListener(
  object : Player.Listener {
    override fun onIsPlayingChanged(isPlaying: Boolean) {
      if (isPlaying) {
        // Active playback.
      } else {
        // Not playing because playback is paused, ended, suppressed, or the player
        // is buffering, stopped or failed. Check player.playWhenReady,
        // player.playbackState, player.playbackSuppressionReason and
        // player.playerError for details.
      }
    }
  }
)
ListeningToPlayerEvents.kt

player.addListener(
    new Player.Listener() {
      @Override
      public void onIsPlayingChanged(boolean isPlaying) {
        if (isPlaying) {
          // Active playback.
        } else {
          // Not playing because playback is paused, ended, suppressed, or the player
          // is buffering, stopped or failed. Check player.getPlayWhenReady,
          // player.getPlaybackState, player.getPlaybackSuppressionReason and
          // player.getPlaybackError for details.
        }
      }
    });
ListeningToPlayerEvents.java

Errores de reproducción

Para recibir los errores que provocan que falle la reproducción, implementa onPlayerError(PlaybackException error) en un Player.Listener registrado. Cuando se produzca una falla, se llamará a este método inmediatamente antes de que el estado de reproducción pase a Player.STATE_IDLE. Para volver a intentar las reproducciones fallidas o detenidas, llama a ExoPlayer.prepare.

Ten en cuenta que algunas Player implementaciones pasan instancias de subclases de PlaybackException para proporcionar información adicional sobre la falla. Por ejemplo, ExoPlayer pasa ExoPlaybackException, que tiene type, rendererIndex, y otros campos específicos de ExoPlayer.

En el siguiente ejemplo, se muestra cómo detectar cuándo falló una reproducción debido a un problema de red HTTP:

player.addListener(
  object : Player.Listener {
    override fun onPlayerError(error: PlaybackException) {
      val cause = error.cause
      if (cause is HttpDataSourceException) {
        // An HTTP error occurred.
        val httpError = cause
        // It's possible to find out more about the error both by casting and by querying
        // the cause.
        if (httpError is InvalidResponseCodeException) {
          // Cast to InvalidResponseCodeException and retrieve the response code, message
          // and headers.
        } else {
          // Try calling httpError.getCause() to retrieve the underlying cause, although
          // note that it may be null.
        }
      }
    }
  }
)
ListeningToPlayerEvents.kt

player.addListener(
    new Player.Listener() {
      @Override
      public void onPlayerError(PlaybackException error) {
        @Nullable Throwable cause = error.getCause();
        if (cause instanceof HttpDataSourceException) {
          // An HTTP error occurred.
          HttpDataSourceException httpError = (HttpDataSourceException) cause;
          // It's possible to find out more about the error both by casting and by querying
          // the cause.
          if (httpError instanceof HttpDataSource.InvalidResponseCodeException) {
            // Cast to InvalidResponseCodeException and retrieve the response code, message
            // and headers.
          } else {
            // Try calling httpError.getCause() to retrieve the underlying cause, although
            // note that it may be null.
          }
        }
      }
    });
ListeningToPlayerEvents.java

Transiciones de playlist

Cada vez que el reproductor cambia a un elemento multimedia nuevo en la playlist onMediaItemTransition(MediaItem mediaItem, @MediaItemTransitionReason int reason) se llama a Player.Listener objetos registrados. El motivo indica si se trató de una transición automática, una búsqueda (por ejemplo, después de llamar a player.next()), una repetición del mismo elemento o si se produjo debido a un cambio en la playlist (por ejemplo, si se quita el elemento que se está reproduciendo).

Metadatos

Los metadatos que se muestran desde player.getCurrentMediaMetadata() pueden cambiar por muchos motivos: transiciones de playlist, actualizaciones de metadatos en el flujo o actualización del MediaItem actual durante la reproducción.

Si te interesan los cambios en los metadatos, por ejemplo, para actualizar una IU que muestra el título actual, puedes escuchar onMediaMetadataChanged.

Buscando

Llamar a los métodos Player.seekTo genera una serie de devoluciones de llamada a las instancias Player.Listener registradas:

1. onPositionDiscontinuity con reason=DISCONTINUITY_REASON_SEEK. Este es el resultado directo de llamar a Player.seekTo. La devolución de llamada tiene campos PositionInfo para la posición antes y después de la búsqueda.
2. onPlaybackStateChanged con cualquier cambio de estado inmediato relacionado con la búsqueda. Ten en cuenta que es posible que no haya ningún cambio.

Devoluciones de llamada individuales en comparación con onEvents

Los objetos de escucha pueden elegir entre implementar devoluciones de llamada individuales como onIsPlayingChanged(boolean isPlaying) y la devolución de llamada genérica onEvents(Player player, Events events). La devolución de llamada genérica proporciona acceso al objeto Player y especifica el conjunto de events que ocurrieron juntos. Siempre se llama a esta devolución de llamada después de las devoluciones de llamada que corresponden a los eventos individuales.

override fun onEvents(player: Player, events: Player.Events) {
  if (
    events.contains(Player.EVENT_PLAYBACK_STATE_CHANGED) ||
      events.contains(Player.EVENT_PLAY_WHEN_READY_CHANGED)
  ) {
    uiModule.updateUi(player)
  }
}
ListeningToPlayerEvents.kt

@Override
public void onEvents(Player player, Events events) {
  if (events.contains(Player.EVENT_PLAYBACK_STATE_CHANGED)
      || events.contains(Player.EVENT_PLAY_WHEN_READY_CHANGED)) {
    uiModule.updateUi(player);
  }
}
ListeningToPlayerEvents.java

Se deben preferir los eventos individuales en los siguientes casos:

• El objeto de escucha está interesado en los motivos de los cambios. Por ejemplo, los motivos proporcionados para onPlayWhenReadyChanged o onMediaItemTransition.
• El objeto de escucha solo actúa sobre los valores nuevos proporcionados a través de los parámetros de devolución de llamada o activa otra acción que no depende de los parámetros de devolución de llamada.
• La implementación del objeto de escucha prefiere una indicación clara y legible de lo que activó el evento en el nombre del método.
• El objeto de escucha informa a un sistema de estadísticas que necesita conocer todos los eventos individuales y los cambios de estado.

Se debe preferir el onEvents(Player player, Events events) genérico en los siguientes casos:

• El objeto de escucha quiere activar la misma lógica para varios eventos. Por ejemplo, actualizar una IU para onPlaybackStateChanged y onPlayWhenReadyChanged.
• El objeto de escucha necesita acceder al objeto Player para activar más eventos, por ejemplo, buscar después de una transición de elemento multimedia.
• El objeto de escucha pretende usar varios valores de estado que se informan a través de devoluciones de llamada separadas, o en combinación con métodos de obtención de Player. Por ejemplo, usar Player.getCurrentWindowIndex() con el Timeline proporcionado en onTimelineChanged solo es seguro desde la onEvents devolución de llamada.
• El objeto de escucha está interesado en si los eventos ocurrieron juntos de forma lógica. Por ejemplo, onPlaybackStateChanged a STATE_BUFFERING debido a una transición de elemento multimedia.

En algunos casos, es posible que los objetos de escucha deban combinar las devoluciones de llamada individuales con la devolución de llamada genérica onEvents, por ejemplo, para registrar los motivos de cambio de elementos multimedia con onMediaItemTransition, pero solo actuar una vez que todos los cambios de estado se puedan usar juntos en onEvents.

Cómo escuchar eventos de reproducción con corrutinas

Como alternativa, puedes iniciar una corrutina de Kotlin con Player.listenTo y especificar el Player.Event pertinente:

Ten en cuenta que se puede llamar a Player.listen y Player.listenTo desde cualquier subproceso, mientras que la lambda de devolución de llamada siempre se invoca en el subproceso asociado con Player.getApplicationLooper. Por lo tanto, es seguro acceder a los métodos Player y a las propiedades de estado dentro de la lambda de devolución de llamada, incluso si la corrutina se inició en un subproceso diferente.

Cambios en el estado de reproducción

coroutineScope.launch {
  player.listenTo(Player.EVENT_IS_PLAYING_CHANGED) {
    // `Player` is a receiver scope for this trailing lambda
    if (isPlaying) {
      // Active playback.
    } else {
      // Not playing.
    }
  }
}
ListeningToPlayerEvents.kt

Errores de reproducción

coroutineScope.launch {
  player.listenTo(Player.EVENT_PLAYER_ERROR) {
    val error = playerError ?: return@listenTo
    val cause = error.cause
    if (cause is HttpDataSourceException) {
      // An HTTP error occurred.
      if (cause is InvalidResponseCodeException) {
        // Retrieve the response code, message and headers
      } else {
        // Try calling cause.cause to retrieve the underlying cause
      }
    }
  }
}
ListeningToPlayerEvents.kt

Devoluciones de llamada individuales en comparación con onEvents

Cuando escuches eventos del reproductor dentro de una corrutina, siempre proporcionarás la implementación para la devolución de llamada onEvents, en lugar de una devolución de llamada individual. Puedes elegir entre Player.listen y Player.listenTo, según los eventos que deban activar una invocación de tu lambda. De lo contrario, las funciones son equivalentes:

coroutineScope.launch {
  player.listen { events ->
    // `Player` is a receiver scope for this trailing lambda
    if (events.contains(Player.EVENT_PLAYBACK_STATE_CHANGED)) {
      // Access the player state directly from the receiver
      updateUi(playbackState)
    }

    if (events.contains(Player.EVENT_PLAYER_ERROR)) {
      // Access the error directly from the player
      handleError(playerError)
    }
  }
}
ListeningToPlayerEvents.kt

coroutineScope.launch {
  player.listenTo(Player.EVENT_PLAYBACK_STATE_CHANGED, Player.EVENT_PLAYER_ERROR) { events ->
    // `Player` is a receiver scope for this trailing lambda
    if (events.contains(Player.EVENT_PLAYBACK_STATE_CHANGED)) {
      // Access the player state directly from the receiver
      updateUi(playbackState)
    }

    if (events.contains(Player.EVENT_PLAYER_ERROR)) {
      // Access the error directly from the player
      handleError(playerError)
    }
  }
}
ListeningToPlayerEvents.kt

Si te interesan varios tipos de eventos, puedes pasar una lista de eventos a Player.listenTo. Se invocará tu lambda cada vez que ocurra alguno de esos eventos, y podrás inspeccionar el parámetro Events para verificar qué eventos se activaron:

coroutineScope.launch {
  player.listenTo(Player.EVENT_PLAYBACK_STATE_CHANGED, Player.EVENT_PLAYER_ERROR) { events ->
    // Unclear which event got triggered without querying `events` parameter
    // The following function will fire whenever either one is caught
    updateUiAndHandleError(playbackState, playerError)
  }
}
ListeningToPlayerEvents.kt

Debido a que estas funciones operan en onEvents, no proporcionan acceso a los argumentos transitorios que se pasan a las devoluciones de llamada individuales, como el motivo en onMediaItemTransition(..., int reason) o el oldPosition en onPositionDiscontinuity(...). Si tu lógica depende de estos argumentos específicos (y no están disponibles como propiedades de estado en el Player), debes usar la interfaz Player.Listener estándar.

Usar AnalyticsListener

Cuando se usa ExoPlayer, se puede registrar un AnalyticsListener con el reproductor llamando a addAnalyticsListener. Las implementaciones de AnalyticsListener pueden escuchar eventos detallados que pueden ser útiles para fines de estadísticas y registro. Consulta la página de estadísticas para obtener más detalles.

Usar EventLogger

EventLogger es un AnalyticsListener que proporciona directamente la biblioteca para fines de registro. Agrega EventLogger a un ExoPlayer para habilitar registros adicionales útiles con una sola línea:

player.addAnalyticsListener(EventLogger())
ListeningToPlayerEvents.kt

player.addAnalyticsListener(new EventLogger());
ListeningToPlayerEvents.java

Consulta la página de registro de depuración para obtener más detalles.

Cómo activar eventos en posiciones de reproducción especificadas

Algunos casos de uso requieren activar eventos en posiciones de reproducción especificadas. Esto se admite con PlayerMessage. Se puede crear un PlayerMessage con ExoPlayer.createMessage. La posición de reproducción en la que se debe ejecutar se puede configurar con PlayerMessage.setPosition. Los mensajes se ejecutan en el subproceso de reproducción de forma predeterminada, pero esto se puede personalizar con PlayerMessage.setLooper. Se puede usar PlayerMessage.setDeleteAfterDelivery para controlar si el mensaje se ejecutará cada vez que se encuentre la posición de reproducción especificada (esto puede suceder varias veces debido a los modos de búsqueda y repetición) o solo la primera vez. Una vez que se configura el PlayerMessage, se puede programar con PlayerMessage.send.

player
  .createMessage { messageType: Int, payload: Any? -> }
  .setLooper(Looper.getMainLooper())
  .setPosition(/* mediaItemIndex= */ 0, /* positionMs= */ 120000)
  .setPayload(customPayloadData)
  .setDeleteAfterDelivery(false)
  .send()
ListeningToPlayerEvents.kt

player
    .createMessage(
        (messageType, payload) -> {
          // Do something at the specified playback position.
        })
    .setLooper(Looper.getMainLooper())
    .setPosition(/* mediaItemIndex= */ 0, /* positionMs= */ 120_000)
    .setPayload(customPayloadData)
    .setDeleteAfterDelivery(false)
    .send();
ListeningToPlayerEvents.java