재생 이벤트 수신 대기
상태 변경 및 재생 오류와 같은 이벤트는 등록된 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();