플레이어 이벤트

플레이어 상태의 변경사항 (예: 재생 시작, 버퍼링, 오류)은 등록된 Player.Listener 인스턴스로 전송되는 이벤트를 트리거합니다. 이러한 이벤트는 정수 상수로 표현되며 Player.Event 및 Player.Events로 정의됩니다.

Player.Listener 등록

플레이어 이벤트는 등록된 Player.Listener 인스턴스에 보고됩니다. 이러한 이벤트를 수신하는 리스너를 등록하려면 다음 단계를 따르세요.

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

Kotlin을 사용하는 경우 media3-common-ktx 모듈에서 제공하는 정지 확장 함수를 사용하여 코루틴을 통해 이벤트를 수신할 수도 있습니다. 이 경우 Player.Listener를 명시적으로 등록하거나 등록 취소할 필요가 없습니다.

Player.Listener를 사용하여 재생 이벤트 수신 대기

Player.Listener에는 빈 기본 메서드가 있으므로 관심 있는 메서드만 구현하면 됩니다. 메서드 및 메서드가 호출되는 시점에 관한 자세한 내용은 Javadoc을 참고하세요. 가장 중요한 메서드 중 일부는 나중에 자세히 설명합니다.

리스너는 개별 이벤트 콜백을 구현하거나 하나 이상의 이벤트가 함께 발생한 후 호출되는 일반 onEvents 콜백을 구현할 수 있습니다. 다양한 사용 사례에 선호되는 항목에 관한 설명은 Individual callbacks vs onEvents를 참조하세요.

재생 상태 변경

등록된 Player.Listener에서 onPlaybackStateChanged(@State int state)를 구현하여 플레이어 상태 변경을 수신할 수 있습니다. 플레이어는 다음 네 가지 재생 상태 중 하나일 수 있습니다.

• Player.STATE_IDLE: 초기 상태, 플레이어가 중지된 상태, 재생이 실패한 상태입니다. 플레이어는 이 상태에서 제한된 리소스만 보유합니다.
• Player.STATE_BUFFERING: 플레이어가 현재 위치에서 즉시 재생할 수 없습니다. 이는 대부분 더 많은 데이터를 로드해야 하기 때문에 발생합니다.
• Player.STATE_READY: 플레이어가 현재 위치에서 즉시 재생할 수 있습니다.
• Player.STATE_ENDED: 플레이어가 모든 미디어 재생을 완료했습니다.

이러한 상태 외에도 플레이어에는 재생하려는 사용자 의도를 나타내는 playWhenReady 플래그가 있습니다. 이 플래그의 변경사항은 onPlayWhenReadyChanged(playWhenReady, @PlayWhenReadyChangeReason int reason)를 구현하여 수신할 수 있습니다.

다음 세 가지 조건이 모두 충족되면 플레이어가 재생 중입니다 (즉, 위치가 진행되고 미디어가 사용자에게 표시됨).

• 플레이어가 Player.STATE_READY 상태입니다.
• playWhenReady은 true입니다.
• Player.getPlaybackSuppressionReason에서 반환한 이유로 인해 재생이 억제되지 않습니다.

이러한 속성을 개별적으로 확인하는 대신 Player.isPlaying를 호출할 수 있습니다. 이 상태의 변경사항은 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

재생 오류

등록된 Player.Listener에서 onPlayerError(PlaybackException error)를 구현하면 재생 실패를 일으키는 오류를 수신할 수 있습니다. 오류가 발생하면 재생 상태가 Player.STATE_IDLE로 전환되기 직전에 이 메서드가 호출됩니다. ExoPlayer.prepare를 호출하여 실패하거나 중지된 재생을 다시 시도할 수 있습니다.

일부 Player 구현은 PlaybackException의 서브클래스 인스턴스를 전달하여 실패에 관한 추가 정보를 제공합니다. 예를 들어 ExoPlayer는 type, rendererIndex, 기타 ExoPlayer 관련 필드가 있는 ExoPlaybackException를 전달합니다.

다음 예는 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

재생목록 전환

플레이어가 재생목록의 새 미디어 항목으로 변경될 때마다 등록된 Player.Listener 객체에서 onMediaItemTransition(MediaItem mediaItem, @MediaItemTransitionReason int reason)가 호출됩니다. 이유는 자동 전환인지, 탐색 (예: player.next() 호출 후)인지, 동일한 항목의 반복인지, 재생목록 변경(예: 현재 재생 중인 항목이 삭제된 경우)으로 인한 것인지 나타냅니다.

메타데이터

player.getCurrentMediaMetadata()에서 반환된 메타데이터는 재생목록 전환, 인스트림 메타데이터 업데이트, 재생 중 현재 MediaItem 업데이트 등 여러 가지 이유로 변경될 수 있습니다.

현재 제목을 표시하는 UI를 업데이트하는 등 메타데이터 변경사항에 관심이 있다면 onMediaMetadataChanged를 수신 대기하면 됩니다.

탐색 중입니다.

Player.seekTo 메서드를 호출하면 등록된 Player.Listener 인스턴스에 대한 일련의 콜백이 발생합니다.

1. reason=DISCONTINUITY_REASON_SEEK로 onPositionDiscontinuity 호출 이는 Player.seekTo를 호출한 직접적인 결과입니다. 콜백에는 탐색 전후의 위치를 나타내는 PositionInfo 필드가 있습니다.
2. 탐색과 관련된 즉각적인 상태 변경이 있는 onPlaybackStateChanged입니다. 이러한 변경사항이 없을 수도 있습니다.

개별 콜백과 onEvents 비교

리스너는 onIsPlayingChanged(boolean isPlaying)와 같은 개별 콜백과 일반 onEvents(Player player, Events events) 콜백 중에서 선택할 수 있습니다. 일반 콜백은 Player 객체에 대한 액세스를 제공하고 함께 발생한 events 집합을 지정합니다. 이 콜백은 항상 개별 이벤트에 해당하는 콜백 다음에 호출됩니다.

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

다음과 같은 경우에는 개별 이벤트를 사용하는 것이 좋습니다.

• 청취자는 변경 이유에 관심이 있습니다. 예를 들어 onPlayWhenReadyChanged 또는 onMediaItemTransition에 제공된 이유입니다.
• 리스너는 콜백 매개변수를 통해 제공된 새 값에만 작동하거나 콜백 매개변수에 종속되지 않는 다른 항목을 트리거합니다.
• 리스너 구현은 메서드 이름에서 이벤트가 트리거된 원인을 명확하게 읽을 수 있는 표시를 선호합니다.
• 리스너는 모든 개별 이벤트 및 상태 변경사항을 알아야 하는 분석 시스템에 보고합니다.

다음과 같은 경우에는 일반 onEvents(Player player, Events events)를 사용하는 것이 좋습니다.

• 리스너가 여러 이벤트에 대해 동일한 로직을 트리거하려고 합니다. 예를 들어 onPlaybackStateChanged 및 onPlayWhenReadyChanged 모두에 대해 UI를 업데이트합니다.
• 리스너는 미디어 항목 전환 후 탐색과 같은 추가 이벤트를 트리거하기 위해 Player 객체에 액세스해야 합니다.
• 리스너는 별도의 콜백을 통해 보고된 여러 상태 값을 함께 사용하거나 Player getter 메서드와 함께 사용하려고 합니다. 예를 들어 onTimelineChanged에 제공된 Timeline와 함께 Player.getCurrentWindowIndex()를 사용하는 것은 onEvents 콜백 내에서만 안전합니다.
• 리스너는 이벤트가 논리적으로 함께 발생했는지에 관심이 있습니다. 예를 들어 미디어 항목 전환으로 인해 onPlaybackStateChanged에서 STATE_BUFFERING로 변경됩니다.

경우에 따라 리스너는 개별 콜백을 일반 onEvents 콜백과 결합해야 할 수 있습니다. 예를 들어 onMediaItemTransition를 사용하여 미디어 항목 변경 이유를 기록하지만 모든 상태 변경을 onEvents에서 함께 사용할 수 있는 경우에만 작동합니다.

코루틴을 사용하여 재생 이벤트 수신 대기

또는 Player.listenTo를 사용하여 Kotlin 코루틴을 실행하고 관련 Player.Event를 지정할 수 있습니다.

Player.listen 및 Player.listenTo는 모든 스레드에서 호출할 수 있지만 콜백 람다는 항상 Player.getApplicationLooper와 연결된 스레드에서 호출됩니다. 따라서 코루틴이 다른 스레드에서 실행되더라도 콜백 람다 내에서 Player 메서드 및 상태 속성에 안전하게 액세스할 수 있습니다.

재생 상태 변경

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

재생 오류

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

개별 콜백과 onEvents 비교

코루틴 내에서 플레이어 이벤트를 수신 대기할 때는 개별 콜백이 아닌 onEvents 콜백의 구현을 항상 제공해야 합니다. 람다 호출을 트리거할 이벤트에 따라 Player.listen와 Player.listenTo 중에서 선택할 수 있습니다. 하지만 그 외에는 함수가 동일합니다.

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

여러 이벤트 유형에 관심이 있는 경우 이벤트 목록을 Player.listenTo에 전달할 수 있습니다. 이러한 이벤트가 발생할 때마다 람다가 호출되며 Events 매개변수를 검사하여 실제로 실행된 이벤트를 확인할 수 있습니다.

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

이러한 함수는 onEvents에서 작동하므로 onMediaItemTransition(..., int reason)의 이유 또는 onPositionDiscontinuity(...)의 oldPosition와 같이 개별 콜백에 전달된 일시적인 인수에 대한 액세스 권한을 제공하지 않습니다. 로직이 이러한 특정 인수에 의존하는 경우(Player에서 상태 속성으로 사용할 수 없음) 표준 Player.Listener 인터페이스를 대신 사용해야 합니다.

AnalyticsListener 사용

ExoPlayer를 사용할 때 addAnalyticsListener를 호출하여 플레이어에 AnalyticsListener를 등록할 수 있습니다. AnalyticsListener 구현은 분석 및 로깅 목적으로 유용할 수 있는 상세 이벤트를 수신 대기할 수 있습니다. 자세한 내용은 분석 페이지를 참고하세요.

EventLogger 사용

EventLogger는 로깅 목적으로 라이브러리에서 직접 제공하는 AnalyticsListener입니다. EventLogger를 ExoPlayer에 추가하여 한 줄로 유용한 추가 로깅을 사용 설정합니다.

player.addAnalyticsListener(EventLogger())
ListeningToPlayerEvents.kt

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

자세한 내용은 디버그 로깅 페이지를 참고하세요.

지정된 재생 위치에서 이벤트 실행

일부 사용 사례에서는 지정된 재생 위치에서 이벤트를 실행해야 합니다. 이는 PlayerMessage를 사용하여 지원됩니다. ExoPlayer.createMessage를 사용하여 PlayerMessage를 만들 수 있습니다. PlayerMessage.setPosition를 사용하여 실행해야 하는 재생 위치를 설정할 수 있습니다. 메시지는 기본적으로 재생 스레드에서 실행되지만 PlayerMessage.setLooper를 사용하여 맞춤설정할 수 있습니다. PlayerMessage.setDeleteAfterDelivery를 사용하면 지정된 재생 위치가 발생할 때마다 메시지가 실행될지 (탐색 및 반복 모드로 인해 여러 번 발생할 수 있음) 아니면 처음 한 번만 실행될지 제어할 수 있습니다. PlayerMessage가 구성되면 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