AnalyticsCollector

Artifact: androidx.media3:media3-exoplayer

Kotlin |Java

@UnstableApi
interface AnalyticsCollector : Player.Listener, MediaSourceEventListener, BandwidthMeter.EventListener, DrmSessionEventListener

Known direct subclasses

DefaultAnalyticsCollector

DefaultAnalyticsCollector

Data collector that forwards analytics events to AnalyticsListeners.

Interface for data collectors that forward analytics events to AnalyticsListeners.

Summary

Public functions
`Unit`	`addListener(listener: AnalyticsListener!)` Adds a listener for analytics events.
`Unit`	`notifySeekStarted()` Notifies the analytics collector that a seek operation will start.
`Unit`	`onAudioCodecError(audioCodecError: Exception!)` Called when an audio decoder encounters an error.
`Unit`	`onAudioDecoderInitialized( decoderName: String!, initializedTimestampMs: Long, initializationDurationMs: Long )` Called when a audio decoder is created.
`Unit`	`onAudioDecoderReleased(decoderName: String!)` Called when a audio decoder is released.
`Unit`	`onAudioDisabled(counters: DecoderCounters!)` Called when the audio renderer is disabled.
`Unit`	`onAudioEnabled(counters: DecoderCounters!)` Called when the audio renderer is enabled.
`Unit`	`onAudioInputFormatChanged( format: Format!, decoderReuseEvaluation: DecoderReuseEvaluation? )` Called when the format of the media being consumed by the audio renderer changes.
`Unit`	`onAudioPositionAdvancing(playoutStartSystemTimeMs: Long)` Called when the audio position has increased for the first time since the last pause or position reset.
`Unit`	`onAudioSinkError(audioSinkError: Exception!)` Called when `AudioSink` has encountered an error.
`Unit`	`onAudioTrackInitialized(audioTrackConfig: AudioSink.AudioTrackConfig!)` Called when an `AudioTrack` has been initialized.
`Unit`	`onAudioTrackReleased(audioTrackConfig: AudioSink.AudioTrackConfig!)` Called when an `AudioTrack` has been released.
`Unit`	`onAudioUnderrun( bufferSize: Int, bufferSizeMs: Long, elapsedSinceLastFeedMs: Long )` Called when an audio underrun occurs.
`Unit`	`onDroppedFrames(count: Int, elapsedMs: Long)` Called to report the number of frames dropped by the video renderer.
`Unit`	`onRenderedFirstFrame(output: Any!, renderTimeMs: Long)` 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.
`Unit`	`onRendererReadyChanged( rendererIndex: Int, @C.TrackType rendererTrackType: Int, isRendererReady: Boolean )` Called each time a renderer starts or stops allowing playback to be ready.
`Unit`	`onVideoCodecError(videoCodecError: Exception!)` Called when a video decoder encounters an error.
`Unit`	`onVideoDecoderInitialized( decoderName: String!, initializedTimestampMs: Long, initializationDurationMs: Long )` Called when a video decoder is created.
`Unit`	`onVideoDecoderReleased(decoderName: String!)` Called when a video decoder is released.
`Unit`	`onVideoDisabled(counters: DecoderCounters!)` Called when the video renderer is disabled.
`Unit`	`onVideoEnabled(counters: DecoderCounters!)` Called when the video renderer is enabled.
`Unit`	`onVideoFrameProcessingOffset( totalProcessingOffsetUs: Long, frameCount: Int )` Called to report the video processing offset of video frames processed by the video renderer.
`Unit`	`onVideoInputFormatChanged( format: Format!, decoderReuseEvaluation: DecoderReuseEvaluation? )` Called when the format of the media being consumed by the video renderer changes.
`Unit`	`release()` Releases the collector.
`Unit`	`removeListener(listener: AnalyticsListener!)` Removes a previously added analytics event listener.
`Unit`	`setPlayer(player: Player!, looper: Looper!)` Sets the player for which data will be collected.
`Unit`	`updateMediaPeriodQueueInfo( queue: (Mutable)List<MediaSource.MediaPeriodId!>!, readingPeriod: MediaSource.MediaPeriodId? )` Updates the playback queue information used for event association.

Inherited functions

From androidx.media3.exoplayer.upstream.BandwidthMeter.EventListener

Unit

onBandwidthSample(
    elapsedMs: Int,
    bytesTransferred: Long,
    bitrateEstimate: Long
)

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

From androidx.media3.exoplayer.drm.DrmSessionEventListener

`Unit`	`onDrmKeysLoaded( windowIndex: Int, mediaPeriodId: MediaSource.MediaPeriodId? )` Called each time keys are loaded.
`Unit`	`onDrmKeysRemoved( windowIndex: Int, mediaPeriodId: MediaSource.MediaPeriodId? )` Called each time offline keys are removed.
`Unit`	`onDrmKeysRestored( windowIndex: Int, mediaPeriodId: MediaSource.MediaPeriodId? )` Called each time offline keys are restored.
`Unit`	`onDrmSessionAcquired( windowIndex: Int, mediaPeriodId: MediaSource.MediaPeriodId?, @DrmSession.State state: Int )` Called each time a drm session is acquired.
`Unit`	`onDrmSessionManagerError( windowIndex: Int, mediaPeriodId: MediaSource.MediaPeriodId?, error: Exception! )` Called when a drm error occurs.
`Unit`	`onDrmSessionReleased( windowIndex: Int, mediaPeriodId: MediaSource.MediaPeriodId? )` Called each time a drm session is released.

From androidx.media3.exoplayer.source.MediaSourceEventListener

`Unit`	`onDownstreamFormatChanged( windowIndex: Int, mediaPeriodId: MediaSource.MediaPeriodId?, mediaLoadData: MediaLoadData! )` Called when a downstream format change occurs (i.e. when the format of the media being read from one or more `SampleStream`s provided by the source changes).
`Unit`	`onLoadCanceled( windowIndex: Int, mediaPeriodId: MediaSource.MediaPeriodId?, loadEventInfo: LoadEventInfo!, mediaLoadData: MediaLoadData! )` Called when a load is canceled.
`Unit`	`onLoadCompleted( windowIndex: Int, mediaPeriodId: MediaSource.MediaPeriodId?, loadEventInfo: LoadEventInfo!, mediaLoadData: MediaLoadData! )` Called when a load ends.
`Unit`	`onLoadError( windowIndex: Int, mediaPeriodId: MediaSource.MediaPeriodId?, loadEventInfo: LoadEventInfo!, mediaLoadData: MediaLoadData!, error: IOException!, wasCanceled: Boolean )` Called when a load error occurs.
`Unit`	`onLoadStarted( windowIndex: Int, mediaPeriodId: MediaSource.MediaPeriodId?, loadEventInfo: LoadEventInfo!, mediaLoadData: MediaLoadData! )` Called when a load begins.
`Unit`	`onUpstreamDiscarded( windowIndex: Int, mediaPeriodId: MediaSource.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.

From androidx.media3.common.Player.Listener

`Unit`	`onAudioAttributesChanged(audioAttributes: AudioAttributes!)` Called when the value of `getAudioAttributes` changes.
`Unit`	`@UnstableApi onAudioSessionIdChanged(audioSessionId: Int)` Called when the audio session ID changes.
`Unit`	`onAvailableCommandsChanged(availableCommands: Player.Commands!)` Called when the value returned from `isCommandAvailable` changes for at least one `Command`.
`Unit`	`onCues(cueGroup: CueGroup!)` Called when the value of `getCurrentCues` changes.
`Unit`	`@UnstableApi onCues(cues: (Mutable)List<Cue!>!)` This function is deprecated. Use `onCues` instead.
`Unit`	`onDeviceInfoChanged(deviceInfo: DeviceInfo!)` Called when the device information changes
`Unit`	`onDeviceVolumeChanged(volume: Int, muted: Boolean)` Called when the value of `getDeviceVolume` or `isDeviceMuted` changes.
`Unit`	`onEvents(player: Player!, events: Player.Events!)` Called when one or more player states changed.
`Unit`	`onIsLoadingChanged(isLoading: Boolean)` Called when the player starts or stops loading the source.
`Unit`	`onIsPlayingChanged(isPlaying: Boolean)` Called when the value of `isPlaying` changes.
`Unit`	`@UnstableApi onLoadingChanged(isLoading: Boolean)` This function is deprecated. Use `onIsLoadingChanged` instead.
`Unit`	`onMaxSeekToPreviousPositionChanged(maxSeekToPreviousPositionMs: Long)` Called when the value of `getMaxSeekToPreviousPosition` changes.
`Unit`	`onMediaItemTransition( mediaItem: MediaItem?, @Player.MediaItemTransitionReason reason: Int )` Called when playback transitions to a media item or starts repeating a media item according to the current `repeat mode`.
`Unit`	`onMediaMetadataChanged(mediaMetadata: MediaMetadata!)` Called when the value of `getMediaMetadata` changes.
`Unit`	`@UnstableApi onMetadata(metadata: Metadata!)` Called when there is metadata associated with the current playback time.
`Unit`	`onPlayWhenReadyChanged( playWhenReady: Boolean, @Player.PlayWhenReadyChangeReason reason: Int )` Called when the value returned from `getPlayWhenReady` changes.
`Unit`	`onPlaybackParametersChanged(playbackParameters: PlaybackParameters!)` Called when the value of `getPlaybackParameters` changes.
`Unit`	`onPlaybackStateChanged(@Player.State playbackState: Int)` Called when the value returned from `getPlaybackState` changes.
`Unit`	`onPlaybackSuppressionReasonChanged( @Player.PlaybackSuppressionReason playbackSuppressionReason: Int )` Called when the value returned from `getPlaybackSuppressionReason` changes.
`Unit`	`onPlayerError(error: PlaybackException!)` Called when an error occurs.
`Unit`	`onPlayerErrorChanged(error: PlaybackException?)` Called when the `PlaybackException` returned by `getPlayerError` changes.
`Unit`	`@UnstableApi onPlayerStateChanged( playWhenReady: Boolean, @Player.State playbackState: Int )` This function is deprecated. Use `onPlaybackStateChanged` and `onPlayWhenReadyChanged` instead.
`Unit`	`onPlaylistMetadataChanged(mediaMetadata: MediaMetadata!)` Called when the value of `getPlaylistMetadata` changes.
`Unit`	`@UnstableApi onPositionDiscontinuity(@Player.DiscontinuityReason reason: Int)` This function is deprecated. Use `onPositionDiscontinuity` instead.
`Unit`	`onPositionDiscontinuity( oldPosition: Player.PositionInfo!, newPosition: Player.PositionInfo!, @Player.DiscontinuityReason reason: Int )` Called when a position discontinuity occurs.
`Unit`	`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.
`Unit`	`onRepeatModeChanged(@Player.RepeatMode repeatMode: Int)` Called when the value of `getRepeatMode` changes.
`Unit`	`onSeekBackIncrementChanged(seekBackIncrementMs: Long)` Called when the value of `getSeekBackIncrement` changes.
`Unit`	`onSeekForwardIncrementChanged(seekForwardIncrementMs: Long)` Called when the value of `getSeekForwardIncrement` changes.
`Unit`	`onShuffleModeEnabledChanged(shuffleModeEnabled: Boolean)` Called when the value of `getShuffleModeEnabled` changes.
`Unit`	`onSkipSilenceEnabledChanged(skipSilenceEnabled: Boolean)` Called when skipping silences is enabled or disabled in the audio stream.
`Unit`	`onSurfaceSizeChanged(width: Int, height: Int)` Called each time there's a change in the size of the surface onto which the video is being rendered.
`Unit`	`onTimelineChanged( timeline: Timeline!, @Player.TimelineChangeReason reason: Int )` Called when the value of `getCurrentTimeline` changes.
`Unit`	`onTrackSelectionParametersChanged(parameters: TrackSelectionParameters!)` Called when the value returned from `getTrackSelectionParameters` changes.
`Unit`	`onTracksChanged(tracks: Tracks!)` Called when the value of `getCurrentTracks` changes.
`Unit`	`onVideoSizeChanged(videoSize: VideoSize!)` Called each time when `getVideoSize` changes.
`Unit`	`onVolumeChanged(volume: Float)` Called when the value of `getVolume` changes.

Public functions

addListener

fun addListener(listener: AnalyticsListener!): Unit

Adds a listener for analytics events.

Parameters
`listener: AnalyticsListener!`	The listener to add.

notifySeekStarted

fun notifySeekStarted(): Unit

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

onAudioCodecError

fun onAudioCodecError(audioCodecError: Exception!): Unit

Called when an audio decoder encounters an error.

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

onAudioDecoderInitialized

fun onAudioDecoderInitialized(
    decoderName: String!,
    initializedTimestampMs: Long,
    initializationDurationMs: Long
): Unit

Called when a audio decoder is created.

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

onAudioDecoderReleased

fun onAudioDecoderReleased(decoderName: String!): Unit

Called when a audio decoder is released.

Parameters
`decoderName: String!`	The audio decoder that was released.

onAudioDisabled

fun onAudioDisabled(counters: DecoderCounters!): Unit

Called when the audio renderer is disabled.

Parameters
`counters: DecoderCounters!`	`DecoderCounters` that were updated by the audio renderer.

onAudioEnabled

fun onAudioEnabled(counters: DecoderCounters!): Unit

Called when the audio renderer is enabled.

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

onAudioInputFormatChanged

fun onAudioInputFormatChanged(
    format: Format!,
    decoderReuseEvaluation: DecoderReuseEvaluation?
): Unit

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

Parameters
`format: Format!`	The new format.
`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

fun onAudioPositionAdvancing(playoutStartSystemTimeMs: Long): Unit

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

Parameters
`playoutStartSystemTimeMs: Long`	The approximate derived `currentTimeMillis` at which playout started.

onAudioSinkError

fun onAudioSinkError(audioSinkError: Exception!): Unit

Called when AudioSink has encountered an error.

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

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

onAudioTrackInitialized

fun onAudioTrackInitialized(audioTrackConfig: AudioSink.AudioTrackConfig!): Unit

Called when an AudioTrack has been initialized.

Parameters
`audioTrackConfig: AudioSink.AudioTrackConfig!`	The `AudioSink.AudioTrackConfig` of the initialized .

onAudioTrackReleased

fun onAudioTrackReleased(audioTrackConfig: AudioSink.AudioTrackConfig!): Unit

Called when an AudioTrack has been released.

Parameters
`audioTrackConfig: AudioSink.AudioTrackConfig!`	The `AudioSink.AudioTrackConfig` of the released .

onAudioUnderrun

fun onAudioUnderrun(
    bufferSize: Int,
    bufferSizeMs: Long,
    elapsedSinceLastFeedMs: Long
): Unit

Called when an audio underrun occurs.

Parameters
`bufferSize: Int`	The size of the audio output buffer, in bytes.
`bufferSizeMs: Long`	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.
`elapsedSinceLastFeedMs: Long`	The time since audio was last written to the output buffer.

onDroppedFrames

fun onDroppedFrames(count: Int, elapsedMs: Long): Unit

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
`count: Int`	The number of dropped frames.
`elapsedMs: Long`	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.

onRenderedFirstFrame

fun onRenderedFirstFrame(output: Any!, renderTimeMs: Long): Unit

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
`output: Any!`	The output of the video renderer. Normally a `Surface`, however some video renderers may have other output types (e.g., a `VideoDecoderOutputBufferRenderer`).
`renderTimeMs: Long`	The `elapsedRealtime` when the frame was rendered.

onRendererReadyChanged

fun onRendererReadyChanged(
    rendererIndex: Int,
    @C.TrackType rendererTrackType: Int,
    isRendererReady: Boolean
): Unit

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

Parameters
`rendererIndex: Int`	The index of the renderer in the instance.
`@C.TrackType rendererTrackType: Int`	The `C.TrackType` of the renderer.
`isRendererReady: Boolean`	Whether the renderer allows playback to be ready.

onVideoCodecError

fun onVideoCodecError(videoCodecError: Exception!): Unit

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
`videoCodecError: Exception!`	The error. Typically a `CodecException` if the renderer uses `MediaCodec`, or a `DecoderException` if the renderer uses a software decoder.

onVideoDecoderInitialized

fun onVideoDecoderInitialized(
    decoderName: String!,
    initializedTimestampMs: Long,
    initializationDurationMs: Long
): Unit

Called when a video decoder is created.

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

onVideoDecoderReleased

fun onVideoDecoderReleased(decoderName: String!): Unit

Called when a video decoder is released.

Parameters
`decoderName: String!`	The video decoder that was released.

onVideoDisabled

fun onVideoDisabled(counters: DecoderCounters!): Unit

Called when the video renderer is disabled.

Parameters
`counters: DecoderCounters!`	`DecoderCounters` that were updated by the video renderer.

onVideoEnabled

fun onVideoEnabled(counters: DecoderCounters!): Unit

Called when the video renderer is enabled.

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

onVideoFrameProcessingOffset

fun onVideoFrameProcessingOffset(
    totalProcessingOffsetUs: Long,
    frameCount: Int
): Unit

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
`totalProcessingOffsetUs: Long`	The sum of all video frame processing offset samples for the video frames processed by the renderer in microseconds.
`frameCount: Int`	The number of samples included in the `totalProcessingOffsetUs`.

onVideoInputFormatChanged

fun onVideoInputFormatChanged(
    format: Format!,
    decoderReuseEvaluation: DecoderReuseEvaluation?
): Unit

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

Parameters
`format: Format!`	The new format.
`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.

release

fun release(): Unit

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

removeListener

fun removeListener(listener: AnalyticsListener!): Unit

Removes a previously added analytics event listener.

Parameters
`listener: AnalyticsListener!`	The listener to remove.

setPlayer

fun setPlayer(player: Player!, looper: Looper!): Unit

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.

updateMediaPeriodQueueInfo

fun updateMediaPeriodQueueInfo(
    queue: (Mutable)List<MediaSource.MediaPeriodId!>!,
    readingPeriod: MediaSource.MediaPeriodId?
): Unit

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
`queue: (Mutable)List<MediaSource.MediaPeriodId!>!`	The playback queue of media periods identified by their `MediaPeriodId`.
`readingPeriod: MediaSource.MediaPeriodId?`	The media period in the queue that is currently being read by renderers, or null if the queue is empty.