이 페이지는 Cloud Translation API를 통해 번역되었습니다.

플레이어 이벤트

재생 이벤트 수신 대기

상태 변경 및 재생 오류와 같은 이벤트는 등록된 Player.Listener 인스턴스에 보고됩니다. 리스너를 등록하여 이러한 이벤트를 수신하는 방법은 다음과 같습니다.

Kotlin

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

Java

// Add a listener to receive events from the player.
player.addListener(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)를 구현하여 수신할 수 있습니다.

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.
      }
    }
  }
)

Java

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.
        }
      }
    });

재생 오류

재생 실패를 유발하는 오류는 등록된 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.
        }
      }
    }
  }
)

Java

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.
          }
        }
      }
    });

재생목록 전환

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

Metadata

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

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

탐색 중입니다.

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

reason=DISCONTINUITY_REASON_SEEK로 onPositionDiscontinuity 호출 이는 Player.seekTo 호출의 직접적인 결과입니다. 콜백에는 탐색 전후의 위치에 관한 PositionInfo 필드가 있습니다.
탐색과 관련된 즉각적인 상태 변경이 있는 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)
  }
}

Java

@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);
  }
}

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

리스너는 변경 이유에 관심이 있습니다. 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())

Java

player.addAnalyticsListener(new EventLogger());

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

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

일부 사용 사례에서는 지정된 재생 위치에서 이벤트를 실행해야 합니다. 이는 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()

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

플레이어 이벤트

재생 이벤트 수신 대기

Kotlin

Java

재생 상태 변경

Kotlin

Java

재생 오류

Kotlin

Java

재생목록 전환

Metadata

탐색 중입니다.

개별 콜백과 onEvents 비교

Kotlin

Java

AnalyticsListener 사용

EventLogger 사용

Kotlin

Java

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

Kotlin

Java

개별 콜백과 `onEvents` 비교

`AnalyticsListener` 사용

`EventLogger` 사용