플레이어 이벤트

재생 이벤트 수신 대기

상태 변경 및 재생 오류와 같은 이벤트는 등록된 Player.Listener 인스턴스에 보고됩니다. 이러한 이벤트를 수신하는 리스너를 등록하려면 다음 단계를 따르세요.

Kotlin

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

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)를 구현하여 수신할 수 있습니다.

Kotlin

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 네트워킹 문제로 인해 재생이 실패한 경우를 감지하는 방법을 보여줍니다.

Kotlin

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() 호출 후), 동일한 항목의 반복인지, 재생목록 변경으로 인한 것인지(예: 현재 재생 중인 항목이 삭제된 경우)를 나타냅니다.

Metadata

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 집합을 지정합니다. 이 콜백은 항상 개별 이벤트에 해당하는 콜백 뒤에 호출됩니다.

Kotlin

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에서 함께 사용할 수 있는 경우에만 작동합니다.

AnalyticsListener 사용

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

EventLogger 사용

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

Kotlin

player.addAnalyticsListener(EventLogger())
ListeningToPlayerEvents.kt

자바

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

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

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

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

Kotlin

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

Java

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