DefaultAnalyticsCollector

Artifact: androidx.media3:media3-exoplayer

View Source

---

Kotlin |Java

@UnstableApi
public class DefaultAnalyticsCollector implements AnalyticsCollector

---

Data collector that forwards analytics events to AnalyticsListeners.

Summary

Public constructors
DefaultAnalyticsCollector(Clock clock) Creates an analytics collector.

Public methods
void	@CallSuper addListener(AnalyticsListener listener) Adds a listener for analytics events.
final void	notifySeekStarted() Notifies the analytics collector that a seek operation will start.
final void	onAudioAttributesChanged(AudioAttributes audioAttributes) Called when the value of getAudioAttributes changes.
final void	onAudioCodecError(Exception audioCodecError) Called when an audio decoder encounters an error.
final void	onAudioDecoderInitialized(     String decoderName,     long initializedTimestampMs,     long initializationDurationMs ) Called when a audio decoder is created.
final void	onAudioDecoderReleased(String decoderName) Called when a audio decoder is released.
final void	onAudioDisabled(DecoderCounters counters) Called when the audio renderer is disabled.
final void	onAudioEnabled(DecoderCounters counters) Called when the audio renderer is enabled.
final void	onAudioInputFormatChanged(     Format format,     @Nullable DecoderReuseEvaluation decoderReuseEvaluation ) Called when the format of the media being consumed by the audio renderer changes.
final void	onAudioPositionAdvancing(long playoutStartSystemTimeMs) Called when the audio position has increased for the first time since the last pause or position reset.
final void	onAudioSessionIdChanged(int audioSessionId) Called when the audio session ID changes.
final void	onAudioSinkError(Exception audioSinkError) Called when AudioSink has encountered an error.
void	onAudioTrackInitialized(AudioSink.AudioTrackConfig audioTrackConfig) Called when an AudioTrack has been initialized.
void	onAudioTrackReleased(AudioSink.AudioTrackConfig audioTrackConfig) Called when an AudioTrack has been released.
final void	onAudioUnderrun(     int bufferSize,     long bufferSizeMs,     long elapsedSinceLastFeedMs ) Called when an audio underrun occurs.
void	onAvailableCommandsChanged(Player.Commands availableCommands) Called when the value returned from isCommandAvailable changes for at least one Command.
final void	onBandwidthSample(     int elapsedMs,     long bytesTransferred,     long bitrateEstimate ) Called periodically to indicate that bytes have been transferred or the estimated bitrate has changed.
void	onCues(CueGroup cueGroup) Called when the value of getCurrentCues changes.
void	onCues(List<Cue> cues) This method is deprecated. Use onCues instead.
void	onDeviceInfoChanged(DeviceInfo deviceInfo) Called when the device information changes
void	onDeviceVolumeChanged(int volume, boolean muted) Called when the value of getDeviceVolume or isDeviceMuted changes.
final void	onDownstreamFormatChanged(     int windowIndex,     @Nullable MediaSource.MediaPeriodId mediaPeriodId,     MediaLoadData mediaLoadData ) Called when a downstream format change occurs (i.e. when the format of the media being read from one or more SampleStreams provided by the source changes).
final void	onDrmKeysLoaded(     int windowIndex,     @Nullable MediaSource.MediaPeriodId mediaPeriodId ) Called each time keys are loaded.
final void	onDrmKeysRemoved(     int windowIndex,     @Nullable MediaSource.MediaPeriodId mediaPeriodId ) Called each time offline keys are removed.
final void	onDrmKeysRestored(     int windowIndex,     @Nullable MediaSource.MediaPeriodId mediaPeriodId ) Called each time offline keys are restored.
final void	onDrmSessionAcquired(     int windowIndex,     @Nullable MediaSource.MediaPeriodId mediaPeriodId,     @DrmSession.State int state ) Called each time a drm session is acquired.
final void	onDrmSessionManagerError(     int windowIndex,     @Nullable MediaSource.MediaPeriodId mediaPeriodId,     Exception error ) Called when a drm error occurs.
final void	onDrmSessionReleased(     int windowIndex,     @Nullable MediaSource.MediaPeriodId mediaPeriodId ) Called each time a drm session is released.
final void	onDroppedFrames(int count, long elapsedMs) Called to report the number of frames dropped by the video renderer.
void	onEvents(Player player, Player.Events events) Called when one or more player states changed.
final void	onIsLoadingChanged(boolean isLoading) Called when the player starts or stops loading the source.
void	onIsPlayingChanged(boolean isPlaying) Called when the value of isPlaying changes.
final void	onLoadCanceled(     int windowIndex,     @Nullable MediaSource.MediaPeriodId mediaPeriodId,     LoadEventInfo loadEventInfo,     MediaLoadData mediaLoadData ) Called when a load is canceled.
final void	onLoadCompleted(     int windowIndex,     @Nullable MediaSource.MediaPeriodId mediaPeriodId,     LoadEventInfo loadEventInfo,     MediaLoadData mediaLoadData ) Called when a load ends.
final void	onLoadError(     int windowIndex,     @Nullable MediaSource.MediaPeriodId mediaPeriodId,     LoadEventInfo loadEventInfo,     MediaLoadData mediaLoadData,     IOException error,     boolean wasCanceled ) Called when a load error occurs.
final void	onLoadStarted(     int windowIndex,     @Nullable MediaSource.MediaPeriodId mediaPeriodId,     LoadEventInfo loadEventInfo,     MediaLoadData mediaLoadData ) Called when a load begins.
void	onLoadingChanged(boolean isLoading) This method is deprecated. Use onIsLoadingChanged instead.
void	onMaxSeekToPreviousPositionChanged(long maxSeekToPreviousPositionMs) Called when the value of getMaxSeekToPreviousPosition changes.
final void	onMediaItemTransition(     @Nullable MediaItem mediaItem,     @Player.MediaItemTransitionReason int reason ) Called when playback transitions to a media item or starts repeating a media item according to the current repeat mode.
void	onMediaMetadataChanged(MediaMetadata mediaMetadata) Called when the value of getMediaMetadata changes.
final void	onMetadata(Metadata metadata) Called when there is metadata associated with the current playback time.
final void	onPlayWhenReadyChanged(     boolean playWhenReady,     @Player.PlayWhenReadyChangeReason int reason ) Called when the value returned from getPlayWhenReady changes.
final void	onPlaybackParametersChanged(PlaybackParameters playbackParameters) Called when the value of getPlaybackParameters changes.
final void	onPlaybackStateChanged(@Player.State int playbackState) Called when the value returned from getPlaybackState changes.
final void	onPlaybackSuppressionReasonChanged(     @Player.PlaybackSuppressionReason int playbackSuppressionReason ) Called when the value returned from getPlaybackSuppressionReason changes.
final void	onPlayerError(PlaybackException error) Called when an error occurs.
void	onPlayerErrorChanged(@Nullable PlaybackException error) Called when the PlaybackException returned by getPlayerError changes.
final void	onPlayerStateChanged(     boolean playWhenReady,     @Player.State int playbackState ) This method is deprecated. Use onPlaybackStateChanged and onPlayWhenReadyChanged instead.
void	onPlaylistMetadataChanged(MediaMetadata playlistMetadata) Called when the value of getPlaylistMetadata changes.
void	onPositionDiscontinuity(@Player.DiscontinuityReason int reason) This method is deprecated. Use onPositionDiscontinuity instead.
final void	onPositionDiscontinuity(     Player.PositionInfo oldPosition,     Player.PositionInfo newPosition,     @Player.DiscontinuityReason int reason ) Called when a position discontinuity occurs.
void	onRenderedFirstFrame() Called when a frame is rendered for the first time since setting the surface, or since the renderer was reset, or since the stream being rendered was changed.
final void	onRenderedFirstFrame(Object output, long renderTimeMs) Called when a frame is rendered for the first time since setting the output, or since the renderer was reset, or since the stream being rendered was changed.
void	onRendererReadyChanged(     int rendererIndex,     @C.TrackType int rendererTrackType,     boolean isRendererReady ) Called each time a renderer starts or stops allowing playback to be ready.
final void	onRepeatModeChanged(@Player.RepeatMode int repeatMode) Called when the value of getRepeatMode changes.
void	onSeekBackIncrementChanged(long seekBackIncrementMs) Called when the value of getSeekBackIncrement changes.
void	onSeekForwardIncrementChanged(long seekForwardIncrementMs) Called when the value of getSeekForwardIncrement changes.
final void	onShuffleModeEnabledChanged(boolean shuffleModeEnabled) Called when the value of getShuffleModeEnabled changes.
final void	onSkipSilenceEnabledChanged(boolean skipSilenceEnabled) Called when skipping silences is enabled or disabled in the audio stream.
final void	onSurfaceSizeChanged(int width, int height) Called each time there's a change in the size of the surface onto which the video is being rendered.
final void	onTimelineChanged(     Timeline timeline,     @Player.TimelineChangeReason int reason ) Called when the value of getCurrentTimeline changes.
void	onTrackSelectionParametersChanged(TrackSelectionParameters parameters) Called when the value returned from getTrackSelectionParameters changes.
void	onTracksChanged(Tracks tracks) Called when the value of getCurrentTracks changes.
final void	onUpstreamDiscarded(     int windowIndex,     @Nullable MediaSource.MediaPeriodId mediaPeriodId,     MediaLoadData mediaLoadData ) Called when data is removed from the back of a media buffer, typically so that it can be re-buffered in a different format.
final void	onVideoCodecError(Exception videoCodecError) Called when a video decoder encounters an error.
final void	onVideoDecoderInitialized(     String decoderName,     long initializedTimestampMs,     long initializationDurationMs ) Called when a video decoder is created.
final void	onVideoDecoderReleased(String decoderName) Called when a video decoder is released.
final void	onVideoDisabled(DecoderCounters counters) Called when the video renderer is disabled.
final void	onVideoEnabled(DecoderCounters counters) Called when the video renderer is enabled.
final void	onVideoFrameProcessingOffset(     long totalProcessingOffsetUs,     int frameCount ) Called to report the video processing offset of video frames processed by the video renderer.
final void	onVideoInputFormatChanged(     Format format,     @Nullable DecoderReuseEvaluation decoderReuseEvaluation ) Called when the format of the media being consumed by the video renderer changes.
final void	onVideoSizeChanged(VideoSize videoSize) Called each time when getVideoSize changes.
final void	onVolumeChanged(float volume) Called when the value of getVolume changes.
void	@CallSuper release() Releases the collector.
void	@CallSuper removeListener(AnalyticsListener listener) Removes a previously added analytics event listener.
void	@CallSuper setPlayer(Player player, Looper looper) Sets the player for which data will be collected.
void	setThrowsWhenUsingWrongThread(boolean throwsWhenUsingWrongThread) This method is deprecated. Do not use this method and ensure all calls are made from the correct thread.
final void	updateMediaPeriodQueueInfo(     List<MediaSource.MediaPeriodId> queue,     @Nullable MediaSource.MediaPeriodId readingPeriod ) Updates the playback queue information used for event association.

Protected methods
final AnalyticsListener.EventTime	generateCurrentPlayerMediaPeriodEventTime() Generates an EventTime for the currently playing item in the player.
final AnalyticsListener.EventTime	@RequiresNonNull(value = "player") generateEventTime(     Timeline timeline,     int windowIndex,     @Nullable MediaSource.MediaPeriodId mediaPeriodId ) Returns a new EventTime for the specified timeline, window and media period id.
final void	sendEvent(     AnalyticsListener.EventTime eventTime,     int eventFlag,     ListenerSet.Event<AnalyticsListener> eventInvocation ) Sends an event to registered listeners.

Public constructors

DefaultAnalyticsCollector

public DefaultAnalyticsCollector(Clock clock)

Creates an analytics collector.

Parameters
Clock clock	A Clock used to generate timestamps.

Public methods

addListener

@CallSuper
public void addListener(AnalyticsListener listener)

Adds a listener for analytics events.

Parameters
AnalyticsListener listener	The listener to add.

notifySeekStarted

public final void notifySeekStarted()

Notifies the analytics collector that a seek operation will start. Should be called before the player adjusts its state and position to the seek.

onAudioAttributesChanged

public final void onAudioAttributesChanged(AudioAttributes audioAttributes)

Called when the value of getAudioAttributes changes.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
AudioAttributes audioAttributes	The audio attributes.

onAudioCodecError

public final void onAudioCodecError(Exception audioCodecError)

Called when an audio decoder encounters an error.

Parameters
Exception audioCodecError	The error. Typically a CodecException if the renderer uses MediaCodec, or a DecoderException if the renderer uses a software decoder.

onAudioDecoderInitialized

public final void onAudioDecoderInitialized(
    String decoderName,
    long initializedTimestampMs,
    long initializationDurationMs
)

Called when a audio decoder is created.

Parameters
String decoderName	The audio decoder that was created.
long initializedTimestampMs	elapsedRealtime when initialization finished.
long initializationDurationMs	The time taken to initialize the decoder in milliseconds.

onAudioDecoderReleased

public final void onAudioDecoderReleased(String decoderName)

Called when a audio decoder is released.

Parameters
String decoderName	The audio decoder that was released.

onAudioDisabled

public final void onAudioDisabled(DecoderCounters counters)

Called when the audio renderer is disabled.

Parameters
DecoderCounters counters	DecoderCounters that were updated by the audio renderer.

onAudioEnabled

public final void onAudioEnabled(DecoderCounters counters)

Called when the audio renderer is enabled.

Parameters
DecoderCounters counters	DecoderCounters that will be updated by the audio renderer for as long as it remains enabled.

onAudioInputFormatChanged

public final void onAudioInputFormatChanged(
    Format format,
    @Nullable DecoderReuseEvaluation decoderReuseEvaluation
)

Called when the format of the media being consumed by the audio renderer changes.

Parameters
Format format	The new format.
@Nullable DecoderReuseEvaluation decoderReuseEvaluation	The result of the evaluation to determine whether an existing decoder instance can be reused for the new format, or null if the renderer did not have a decoder.

onAudioPositionAdvancing

public final void onAudioPositionAdvancing(long playoutStartSystemTimeMs)

Called when the audio position has increased for the first time since the last pause or position reset.

Parameters
long playoutStartSystemTimeMs	The approximate derived currentTimeMillis at which playout started.

onAudioSessionIdChanged

public final void onAudioSessionIdChanged(int audioSessionId)

Called when the audio session ID changes.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
int audioSessionId	The audio session ID.

onAudioSinkError

public final void onAudioSinkError(Exception audioSinkError)

Called when AudioSink has encountered an error.

If the sink writes to a platform AudioTrack, this will be called for all errors.

Parameters
Exception audioSinkError	The error that occurred. Typically an , a AudioSink.WriteException, or an .

onAudioTrackInitialized

public void onAudioTrackInitialized(AudioSink.AudioTrackConfig audioTrackConfig)

Called when an AudioTrack has been initialized.

Parameters
AudioSink.AudioTrackConfig audioTrackConfig	The AudioSink.AudioTrackConfig of the initialized .

onAudioTrackReleased

public void onAudioTrackReleased(AudioSink.AudioTrackConfig audioTrackConfig)

Called when an AudioTrack has been released.

Parameters
AudioSink.AudioTrackConfig audioTrackConfig	The AudioSink.AudioTrackConfig of the released .

onAudioUnderrun

public final void onAudioUnderrun(
    int bufferSize,
    long bufferSizeMs,
    long elapsedSinceLastFeedMs
)

Called when an audio underrun occurs.

Parameters
int bufferSize	The size of the audio output buffer, in bytes.
long bufferSizeMs	The size of the audio output buffer, in milliseconds, if it contains PCM encoded audio. TIME_UNSET if the output buffer contains non-PCM encoded audio.
long elapsedSinceLastFeedMs	The time since audio was last written to the output buffer.

onAvailableCommandsChanged

public void onAvailableCommandsChanged(Player.Commands availableCommands)

Called when the value returned from isCommandAvailable changes for at least one Command.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
Player.Commands availableCommands	The available Commands.

onBandwidthSample

public final void onBandwidthSample(
    int elapsedMs,
    long bytesTransferred,
    long bitrateEstimate
)

Called periodically to indicate that bytes have been transferred or the estimated bitrate has changed.

Note: The estimated bitrate is typically derived from more information than just bytesTransferred and elapsedMs.

Parameters
int elapsedMs	The time taken to transfer bytesTransferred, in milliseconds. This is at most the elapsed time since the last callback, but may be less if there were periods during which data was not being transferred.
long bytesTransferred	The number of bytes transferred since the last callback.
long bitrateEstimate	The estimated bitrate in bits/sec.

onCues

public void onCues(CueGroup cueGroup)

Called when the value of getCurrentCues changes.

Both this method and onCues are called when there is a change in the cues. You should only implement one or the other.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

onCues

public void onCues(List<Cue> cues)

This method is deprecated.

Use onCues instead.

Called when the value of getCurrentCues changes.

Both this method and onCues are called when there is a change in the cues. You should only implement one or the other.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

onDeviceInfoChanged

public void onDeviceInfoChanged(DeviceInfo deviceInfo)

Called when the device information changes

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
DeviceInfo deviceInfo	The new DeviceInfo.

onDeviceVolumeChanged

public void onDeviceVolumeChanged(int volume, boolean muted)

Called when the value of getDeviceVolume or isDeviceMuted changes.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
int volume	The new device volume, with 0 being silence and 1 being unity gain.
boolean muted	Whether the device is muted.

onDownstreamFormatChanged

public final void onDownstreamFormatChanged(
    int windowIndex,
    @Nullable MediaSource.MediaPeriodId mediaPeriodId,
    MediaLoadData mediaLoadData
)

Called when a downstream format change occurs (i.e. when the format of the media being read from one or more SampleStreams provided by the source changes).

Parameters
int windowIndex	The window index in the timeline of the media source this load belongs to.
@Nullable MediaSource.MediaPeriodId mediaPeriodId	The MediaPeriodId the media belongs to.
MediaLoadData mediaLoadData	The MediaLoadData defining the newly selected downstream data.

onDrmKeysLoaded

public final void onDrmKeysLoaded(
    int windowIndex,
    @Nullable MediaSource.MediaPeriodId mediaPeriodId
)

Called each time keys are loaded.

Parameters
int windowIndex	The window index in the timeline this media period belongs to.
@Nullable MediaSource.MediaPeriodId mediaPeriodId	The MediaPeriodId associated with the drm session.

onDrmKeysRemoved

public final void onDrmKeysRemoved(
    int windowIndex,
    @Nullable MediaSource.MediaPeriodId mediaPeriodId
)

Called each time offline keys are removed.

Parameters
int windowIndex	The window index in the timeline this media period belongs to.
@Nullable MediaSource.MediaPeriodId mediaPeriodId	The MediaPeriodId associated with the drm session.

onDrmKeysRestored

public final void onDrmKeysRestored(
    int windowIndex,
    @Nullable MediaSource.MediaPeriodId mediaPeriodId
)

Called each time offline keys are restored.

Parameters
int windowIndex	The window index in the timeline this media period belongs to.
@Nullable MediaSource.MediaPeriodId mediaPeriodId	The MediaPeriodId associated with the drm session.

onDrmSessionAcquired

public final void onDrmSessionAcquired(
    int windowIndex,
    @Nullable MediaSource.MediaPeriodId mediaPeriodId,
    @DrmSession.State int state
)

Called each time a drm session is acquired.

Parameters
int windowIndex	The window index in the timeline this media period belongs to.
@Nullable MediaSource.MediaPeriodId mediaPeriodId	The MediaPeriodId associated with the drm session.
@DrmSession.State int state	The DrmSession.State of the session when the acquisition completed.

onDrmSessionManagerError

public final void onDrmSessionManagerError(
    int windowIndex,
    @Nullable MediaSource.MediaPeriodId mediaPeriodId,
    Exception error
)

Called when a drm error occurs.

This method being called does not indicate that playback has failed, or that it will fail. The player may be able to recover from the error and continue. Hence applications should not implement this method to display a user visible error or initiate an application level retry (onPlayerError is the appropriate place to implement such behavior). This method is called to provide the application with an opportunity to log the error if it wishes to do so.

Parameters
int windowIndex	The window index in the timeline this media period belongs to.
@Nullable MediaSource.MediaPeriodId mediaPeriodId	The MediaPeriodId associated with the drm session.
Exception error	The corresponding exception.

onDrmSessionReleased

public final void onDrmSessionReleased(
    int windowIndex,
    @Nullable MediaSource.MediaPeriodId mediaPeriodId
)

Called each time a drm session is released.

Parameters
int windowIndex	The window index in the timeline this media period belongs to.
@Nullable MediaSource.MediaPeriodId mediaPeriodId	The MediaPeriodId associated with the drm session.

onDroppedFrames

public final void onDroppedFrames(int count, long elapsedMs)

Called to report the number of frames dropped by the video renderer. Dropped frames are reported whenever the renderer is stopped having dropped frames, and optionally, whenever the count reaches a specified threshold whilst the renderer is started.

Parameters
int count	The number of dropped frames.
long elapsedMs	The duration in milliseconds over which the frames were dropped. This duration is timed from when the renderer was started or from when dropped frames were last reported (whichever was more recent), and not from when the first of the reported drops occurred.

onEvents

public void onEvents(Player player, Player.Events events)

Called when one or more player states changed.

State changes and events that happen within one Looper message queue iteration are reported together and only after all individual callbacks were triggered.

Listeners should prefer this method over individual callbacks in the following cases:

• They intend to trigger the same logic for multiple events (e.g. when updating a UI for both onPlaybackStateChanged and onPlayWhenReadyChanged).
• They need access to the Player object to trigger further events (e.g. to call seekTo after a onMediaItemTransition).
• They intend to use multiple state values together or in combination with Player getter methods. For example using getCurrentMediaItemIndex with the timeline provided in onTimelineChanged is only safe from within this method.
• They are interested in events that logically happened together (e.g onPlaybackStateChanged to STATE_BUFFERING because of onMediaItemTransition).

Parameters
Player player	The Player whose state changed. Use the getters to obtain the latest states.
Player.Events events	The Events that happened in this iteration, indicating which player states changed.

onIsLoadingChanged

public final void onIsLoadingChanged(boolean isLoading)

Called when the player starts or stops loading the source.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
boolean isLoading	Whether the source is currently being loaded.

onIsPlayingChanged

public void onIsPlayingChanged(boolean isPlaying)

Called when the value of isPlaying changes.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
boolean isPlaying	Whether the player is playing.

onLoadCanceled

public final void onLoadCanceled(
    int windowIndex,
    @Nullable MediaSource.MediaPeriodId mediaPeriodId,
    LoadEventInfo loadEventInfo,
    MediaLoadData mediaLoadData
)

Called when a load is canceled.

Parameters
int windowIndex	The window index in the timeline of the media source this load belongs to.
@Nullable MediaSource.MediaPeriodId mediaPeriodId	The MediaPeriodId this load belongs to. Null if the load does not belong to a specific media period.
LoadEventInfo loadEventInfo	The LoadEventInfo corresponding to the event. The values of elapsedRealtimeMs and bytesLoaded are relative to the corresponding onLoadStarted event.
MediaLoadData mediaLoadData	The MediaLoadData defining the data being loaded.

onLoadCompleted

public final void onLoadCompleted(
    int windowIndex,
    @Nullable MediaSource.MediaPeriodId mediaPeriodId,
    LoadEventInfo loadEventInfo,
    MediaLoadData mediaLoadData
)

Called when a load ends.

Parameters
int windowIndex	The window index in the timeline of the media source this load belongs to.
@Nullable MediaSource.MediaPeriodId mediaPeriodId	The MediaPeriodId this load belongs to. Null if the load does not belong to a specific media period.
LoadEventInfo loadEventInfo	The LoadEventInfo corresponding to the event. The values of elapsedRealtimeMs and bytesLoaded are relative to the corresponding onLoadStarted event.
MediaLoadData mediaLoadData	The MediaLoadData defining the data being loaded.

onLoadError

public final void onLoadError(
    int windowIndex,
    @Nullable MediaSource.MediaPeriodId mediaPeriodId,
    LoadEventInfo loadEventInfo,
    MediaLoadData mediaLoadData,
    IOException error,
    boolean wasCanceled
)

Called when a load error occurs.

The error may or may not have resulted in the load being canceled, as indicated by the wasCanceled parameter. If the load was canceled, onLoadCanceled will not be called in addition to this method.

This method being called does not indicate that playback has failed, or that it will fail. The player may be able to recover from the error. Hence applications should not implement this method to display a user visible error or initiate an application level retry. onPlayerError is the appropriate place to implement such behavior. This method is called to provide the application with an opportunity to log the error if it wishes to do so.

Parameters
int windowIndex	The window index in the timeline of the media source this load belongs to.
@Nullable MediaSource.MediaPeriodId mediaPeriodId	The MediaPeriodId this load belongs to. Null if the load does not belong to a specific media period.
LoadEventInfo loadEventInfo	The LoadEventInfo corresponding to the event. The values of elapsedRealtimeMs and bytesLoaded are relative to the corresponding onLoadStarted event.
MediaLoadData mediaLoadData	The MediaLoadData defining the data being loaded.
IOException error	The load error.
boolean wasCanceled	Whether the load was canceled as a result of the error.

onLoadStarted

public final void onLoadStarted(
    int windowIndex,
    @Nullable MediaSource.MediaPeriodId mediaPeriodId,
    LoadEventInfo loadEventInfo,
    MediaLoadData mediaLoadData
)

Called when a load begins.

Parameters
int windowIndex	The window index in the timeline of the media source this load belongs to.
@Nullable MediaSource.MediaPeriodId mediaPeriodId	The MediaPeriodId this load belongs to. Null if the load does not belong to a specific media period.
LoadEventInfo loadEventInfo	The LoadEventInfo corresponding to the event. The value of uri won't reflect potential redirection yet and responseHeaders will be empty.
MediaLoadData mediaLoadData	The MediaLoadData defining the data being loaded.

onLoadingChanged

public void onLoadingChanged(boolean isLoading)

This method is deprecated.

Use onIsLoadingChanged instead.

onMaxSeekToPreviousPositionChanged

public void onMaxSeekToPreviousPositionChanged(long maxSeekToPreviousPositionMs)

Called when the value of getMaxSeekToPreviousPosition changes.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
long maxSeekToPreviousPositionMs	The maximum position for which seekToPrevious seeks to the previous position, in milliseconds.

onMediaItemTransition

public final void onMediaItemTransition(
    @Nullable MediaItem mediaItem,
    @Player.MediaItemTransitionReason int reason
)

Called when playback transitions to a media item or starts repeating a media item according to the current repeat mode.

Note that this callback is also called when the value of getCurrentTimeline becomes non-empty or empty.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
@Nullable MediaItem mediaItem	The MediaItem. May be null if the playlist becomes empty.
@Player.MediaItemTransitionReason int reason	The reason for the transition.

onMediaMetadataChanged

public void onMediaMetadataChanged(MediaMetadata mediaMetadata)

Called when the value of getMediaMetadata changes.

This method may be called multiple times in quick succession.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
MediaMetadata mediaMetadata	The combined MediaMetadata.

onMetadata

public final void onMetadata(Metadata metadata)

Called when there is metadata associated with the current playback time.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
Metadata metadata	The metadata.

onPlayWhenReadyChanged

public final void onPlayWhenReadyChanged(
    boolean playWhenReady,
    @Player.PlayWhenReadyChangeReason int reason
)

Called when the value returned from getPlayWhenReady changes.

The current playWhenReady value may be re-reported if the reason for this value changes.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
boolean playWhenReady	Whether playback will proceed when ready.
@Player.PlayWhenReadyChangeReason int reason	The PlayWhenReadyChangeReason for the change.

onPlaybackParametersChanged

public final void onPlaybackParametersChanged(PlaybackParameters playbackParameters)

Called when the value of getPlaybackParameters changes. The playback parameters may change due to a call to setPlaybackParameters, or the player itself may change them (for example, if audio playback switches to passthrough or offload mode, where speed adjustment is no longer possible).

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
PlaybackParameters playbackParameters	The playback parameters.

onPlaybackStateChanged

public final void onPlaybackStateChanged(@Player.State int playbackState)

Called when the value returned from getPlaybackState changes.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
@Player.State int playbackState	The new playback State.

onPlaybackSuppressionReasonChanged

public final void onPlaybackSuppressionReasonChanged(
    @Player.PlaybackSuppressionReason int playbackSuppressionReason
)

Called when the value returned from getPlaybackSuppressionReason changes.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
@Player.PlaybackSuppressionReason int playbackSuppressionReason	The current PlaybackSuppressionReason.

onPlayerError

public final void onPlayerError(PlaybackException error)

Called when an error occurs. The playback state will transition to STATE_IDLE immediately after this method is called. The player instance can still be used, and release must still be called on the player should it no longer be required.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Implementations of Player may pass an instance of a subclass of PlaybackException to this method in order to include more information about the error.

Parameters
PlaybackException error	The error.

onPlayerErrorChanged

public void onPlayerErrorChanged(@Nullable PlaybackException error)

Called when the PlaybackException returned by getPlayerError changes.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Implementations of Player may pass an instance of a subclass of PlaybackException to this method in order to include more information about the error.

Parameters
@Nullable PlaybackException error	The new error, or null if the error is being cleared.

onPlayerStateChanged

public final void onPlayerStateChanged(
    boolean playWhenReady,
    @Player.State int playbackState
)

This method is deprecated.

Use onPlaybackStateChanged and onPlayWhenReadyChanged instead.

onPlaylistMetadataChanged

public void onPlaylistMetadataChanged(MediaMetadata playlistMetadata)

Called when the value of getPlaylistMetadata changes.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

onPositionDiscontinuity

public void onPositionDiscontinuity(@Player.DiscontinuityReason int reason)

This method is deprecated.

Use onPositionDiscontinuity instead.

onPositionDiscontinuity

public final void onPositionDiscontinuity(
    Player.PositionInfo oldPosition,
    Player.PositionInfo newPosition,
    @Player.DiscontinuityReason int reason
)

Called when a position discontinuity occurs.

A position discontinuity occurs when the playing period changes, the playback position jumps within the period currently being played, or when the playing period has been skipped or removed.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
Player.PositionInfo oldPosition	The position before the discontinuity.
Player.PositionInfo newPosition	The position after the discontinuity.
@Player.DiscontinuityReason int reason	The DiscontinuityReason responsible for the discontinuity.

onRenderedFirstFrame

public void onRenderedFirstFrame()

Called when a frame is rendered for the first time since setting the surface, or since the renderer was reset, or since the stream being rendered was changed.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

onRenderedFirstFrame

public final void onRenderedFirstFrame(Object output, long renderTimeMs)

Called when a frame is rendered for the first time since setting the output, or since the renderer was reset, or since the stream being rendered was changed.

Parameters
Object output	The output of the video renderer. Normally a Surface, however some video renderers may have other output types (e.g., a VideoDecoderOutputBufferRenderer).
long renderTimeMs	The elapsedRealtime when the frame was rendered.

onRendererReadyChanged

public void onRendererReadyChanged(
    int rendererIndex,
    @C.TrackType int rendererTrackType,
    boolean isRendererReady
)

Called each time a renderer starts or stops allowing playback to be ready.

Parameters
int rendererIndex	The index of the renderer in the instance.
@C.TrackType int rendererTrackType	The C.TrackType of the renderer.
boolean isRendererReady	Whether the renderer allows playback to be ready.

onRepeatModeChanged

public final void onRepeatModeChanged(@Player.RepeatMode int repeatMode)

Called when the value of getRepeatMode changes.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
@Player.RepeatMode int repeatMode	The RepeatMode used for playback.

onSeekBackIncrementChanged

public void onSeekBackIncrementChanged(long seekBackIncrementMs)

Called when the value of getSeekBackIncrement changes.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
long seekBackIncrementMs	The seekBack increment, in milliseconds.

onSeekForwardIncrementChanged

public void onSeekForwardIncrementChanged(long seekForwardIncrementMs)

Called when the value of getSeekForwardIncrement changes.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
long seekForwardIncrementMs	The seekForward increment, in milliseconds.

onShuffleModeEnabledChanged

public final void onShuffleModeEnabledChanged(boolean shuffleModeEnabled)

Called when the value of getShuffleModeEnabled changes.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
boolean shuffleModeEnabled	Whether shuffling of media items is enabled.

onSkipSilenceEnabledChanged

public final void onSkipSilenceEnabledChanged(boolean skipSilenceEnabled)

Called when skipping silences is enabled or disabled in the audio stream.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
boolean skipSilenceEnabled	Whether skipping silences in the audio stream is enabled.

onSurfaceSizeChanged

public final void onSurfaceSizeChanged(int width, int height)

Called each time there's a change in the size of the surface onto which the video is being rendered.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
int width	The surface width in pixels. May be LENGTH_UNSET if unknown, or 0 if the video is not rendered onto a surface.
int height	The surface height in pixels. May be LENGTH_UNSET if unknown, or 0 if the video is not rendered onto a surface.

onTimelineChanged

public final void onTimelineChanged(
    Timeline timeline,
    @Player.TimelineChangeReason int reason
)

Called when the value of getCurrentTimeline changes.

Note that the current MediaItem or playback position may change as a result of a timeline change. If playback can't continue smoothly because of this timeline change, a separate onPositionDiscontinuity callback will be triggered.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
Timeline timeline	The latest timeline. Never null, but may be empty.
@Player.TimelineChangeReason int reason	The TimelineChangeReason responsible for this timeline change.

onTrackSelectionParametersChanged

public void onTrackSelectionParametersChanged(TrackSelectionParameters parameters)

Called when the value returned from getTrackSelectionParameters changes.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
TrackSelectionParameters parameters	The new TrackSelectionParameters.

onTracksChanged

public void onTracksChanged(Tracks tracks)

Called when the value of getCurrentTracks changes.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
Tracks tracks	The available tracks information. Never null, but may be of length zero.

onUpstreamDiscarded

public final void onUpstreamDiscarded(
    int windowIndex,
    @Nullable MediaSource.MediaPeriodId mediaPeriodId,
    MediaLoadData mediaLoadData
)

Called when data is removed from the back of a media buffer, typically so that it can be re-buffered in a different format.

Parameters
int windowIndex	The window index in the timeline of the media source this load belongs to.
@Nullable MediaSource.MediaPeriodId mediaPeriodId	The MediaPeriodId the media belongs to.
MediaLoadData mediaLoadData	The MediaLoadData defining the media being discarded.

onVideoCodecError

public final void onVideoCodecError(Exception videoCodecError)

Called when a video decoder encounters an error.

This method being called does not indicate that playback has failed, or that it will fail. The player may be able to recover from the error. Hence applications should not implement this method to display a user visible error or initiate an application level retry. onPlayerError is the appropriate place to implement such behavior. This method is called to provide the application with an opportunity to log the error if it wishes to do so.

Parameters
Exception videoCodecError	The error. Typically a CodecException if the renderer uses MediaCodec, or a DecoderException if the renderer uses a software decoder.

onVideoDecoderInitialized

public final void onVideoDecoderInitialized(
    String decoderName,
    long initializedTimestampMs,
    long initializationDurationMs
)

Called when a video decoder is created.

Parameters
String decoderName	The decoder that was created.
long initializedTimestampMs	elapsedRealtime when initialization finished.
long initializationDurationMs	The time taken to initialize the decoder in milliseconds.

onVideoDecoderReleased

public final void onVideoDecoderReleased(String decoderName)

Called when a video decoder is released.

Parameters
String decoderName	The video decoder that was released.

onVideoDisabled

public final void onVideoDisabled(DecoderCounters counters)

Called when the video renderer is disabled.

Parameters
DecoderCounters counters	DecoderCounters that were updated by the video renderer.

onVideoEnabled

public final void onVideoEnabled(DecoderCounters counters)

Called when the video renderer is enabled.

Parameters
DecoderCounters counters	DecoderCounters that will be updated by the video renderer for as long as it remains enabled.

onVideoFrameProcessingOffset

public final void onVideoFrameProcessingOffset(
    long totalProcessingOffsetUs,
    int frameCount
)

Called to report the video processing offset of video frames processed by the video renderer.

Video processing offset represents how early a video frame is processed compared to the player's current position. For each video frame, the offset is calculated as Pvf - Ppl where Pvf is the presentation timestamp of the video frame and Ppl is the current position of the player. Positive values indicate the frame was processed early enough whereas negative values indicate that the player's position had progressed beyond the frame's timestamp when the frame was processed (and the frame was probably dropped).

The renderer reports the sum of video processing offset samples (one sample per processed video frame: dropped, skipped or rendered) and the total number of samples.

Parameters
long totalProcessingOffsetUs	The sum of all video frame processing offset samples for the video frames processed by the renderer in microseconds.
int frameCount	The number of samples included in the totalProcessingOffsetUs.

onVideoInputFormatChanged

public final void onVideoInputFormatChanged(
    Format format,
    @Nullable DecoderReuseEvaluation decoderReuseEvaluation
)

Called when the format of the media being consumed by the video renderer changes.

Parameters
Format format	The new format.
@Nullable DecoderReuseEvaluation decoderReuseEvaluation	The result of the evaluation to determine whether an existing decoder instance can be reused for the new format, or null if the renderer did not have a decoder.

onVideoSizeChanged

public final void onVideoSizeChanged(VideoSize videoSize)

Called each time when getVideoSize changes.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
VideoSize videoSize	The new size of the video.

onVolumeChanged

public final void onVolumeChanged(float volume)

Called when the value of getVolume changes.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
float volume	The new volume, with 0 being silence and 1 being unity gain.

release

@CallSuper
public void release()

Releases the collector. Must be called after the player for which data is collected has been released.

removeListener

@CallSuper
public void removeListener(AnalyticsListener listener)

Removes a previously added analytics event listener.

Parameters
AnalyticsListener listener	The listener to remove.

setPlayer

@CallSuper
public void setPlayer(Player player, Looper looper)

Sets the player for which data will be collected. Must only be called if no player has been set yet or the current player is idle.

Parameters
Player player	The Player for which data will be collected.
Looper looper	The Looper used for listener callbacks.

setThrowsWhenUsingWrongThread

public void setThrowsWhenUsingWrongThread(boolean throwsWhenUsingWrongThread)

This method is deprecated.

Do not use this method and ensure all calls are made from the correct thread.

Sets whether methods throw when using the wrong thread.

Do not use this method unless to support legacy use cases.

Parameters
boolean throwsWhenUsingWrongThread	Whether to throw when using the wrong thread.

updateMediaPeriodQueueInfo

public final void updateMediaPeriodQueueInfo(
    List<MediaSource.MediaPeriodId> queue,
    @Nullable MediaSource.MediaPeriodId readingPeriod
)

Updates the playback queue information used for event association.

Should only be called by the player controlling the queue and not from app code.

Parameters
List<MediaSource.MediaPeriodId> queue	The playback queue of media periods identified by their MediaPeriodId.
@Nullable MediaSource.MediaPeriodId readingPeriod	The media period in the queue that is currently being read by renderers, or null if the queue is empty.

Protected methods

generateCurrentPlayerMediaPeriodEventTime

protected final AnalyticsListener.EventTime generateCurrentPlayerMediaPeriodEventTime()

Generates an EventTime for the currently playing item in the player.

generateEventTime

@RequiresNonNull(value = "player")
protected final AnalyticsListener.EventTime generateEventTime(
    Timeline timeline,
    int windowIndex,
    @Nullable MediaSource.MediaPeriodId mediaPeriodId
)

Returns a new EventTime for the specified timeline, window and media period id.

sendEvent

protected final void sendEvent(
    AnalyticsListener.EventTime eventTime,
    int eventFlag,
    ListenerSet.Event<AnalyticsListener> eventInvocation
)

Sends an event to registered listeners.

Parameters
AnalyticsListener.EventTime eventTime	The EventTime to report.
int eventFlag	An integer flag indicating the type of the event, or INDEX_UNSET to report this event without flag.
ListenerSet.Event<AnalyticsListener> eventInvocation	The event.