AnalyticsCollector


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

Known direct subclasses
DefaultAnalyticsCollector

Data collector that forwards analytics events to AnalyticsListeners.


Interface for data collectors that forward analytics events to AnalyticsListeners.

Summary

Public methods

abstract void

Adds a listener for analytics events.

abstract void

Notifies the analytics collector that a seek operation will start.

abstract void
onAudioCodecError(Exception audioCodecError)

Called when an audio decoder encounters an error.

abstract void
onAudioDecoderInitialized(
    String decoderName,
    long initializedTimestampMs,
    long initializationDurationMs
)

Called when a audio decoder is created.

abstract void

Called when a audio decoder is released.

abstract void

Called when the audio renderer is disabled.

abstract void

Called when the audio renderer is enabled.

abstract void
onAudioInputFormatChanged(
    Format format,
    @Nullable DecoderReuseEvaluation decoderReuseEvaluation
)

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

abstract void
onAudioPositionAdvancing(long playoutStartSystemTimeMs)

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

abstract void
onAudioSinkError(Exception audioSinkError)

Called when AudioSink has encountered an error.

abstract void

Called when an AudioTrack has been initialized.

abstract void

Called when an AudioTrack has been released.

abstract void
onAudioUnderrun(
    int bufferSize,
    long bufferSizeMs,
    long elapsedSinceLastFeedMs
)

Called when an audio underrun occurs.

abstract void
onDroppedFrames(int count, long elapsedMs)

Called to report the number of frames dropped by the video renderer.

abstract 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.

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

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

abstract void
onVideoCodecError(Exception videoCodecError)

Called when a video decoder encounters an error.

abstract void
onVideoDecoderInitialized(
    String decoderName,
    long initializedTimestampMs,
    long initializationDurationMs
)

Called when a video decoder is created.

abstract void

Called when a video decoder is released.

abstract void

Called when the video renderer is disabled.

abstract void

Called when the video renderer is enabled.

abstract void
onVideoFrameProcessingOffset(
    long totalProcessingOffsetUs,
    int frameCount
)

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

abstract void
onVideoInputFormatChanged(
    Format format,
    @Nullable DecoderReuseEvaluation decoderReuseEvaluation
)

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

abstract void

Releases the collector.

abstract void

Removes a previously added analytics event listener.

abstract void
setPlayer(Player player, Looper looper)

Sets the player for which data will be collected.

abstract void

Updates the playback queue information used for event association.

Inherited methods

From androidx.media3.exoplayer.upstream.BandwidthMeter.EventListener
abstract void
onBandwidthSample(
    int elapsedMs,
    long bytesTransferred,
    long bitrateEstimate
)

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

From androidx.media3.exoplayer.drm.DrmSessionEventListener
default void
onDrmKeysLoaded(
    int windowIndex,
    @Nullable MediaSource.MediaPeriodId mediaPeriodId
)

Called each time keys are loaded.

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

Called each time offline keys are removed.

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

Called each time offline keys are restored.

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

Called each time a drm session is acquired.

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

Called when a drm error occurs.

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

Called each time a drm session is released.

From androidx.media3.exoplayer.source.MediaSourceEventListener
default 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).

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

Called when a load is canceled.

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

Called when a load ends.

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

Called when a load error occurs.

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

Called when a load begins.

default void
onUpstreamDiscarded(
    int windowIndex,
    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.

From androidx.media3.common.Player.Listener
default void

Called when the value of getAudioAttributes changes.

default void

Called when the audio session ID changes.

default void

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

default void
onCues(CueGroup cueGroup)

Called when the value of getCurrentCues changes.

default void

This method is deprecated.

Use onCues instead.

default void

Called when the device information changes

default void
onDeviceVolumeChanged(int volume, boolean muted)

Called when the value of getDeviceVolume or isDeviceMuted changes.

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

Called when one or more player states changed.

default void
onIsLoadingChanged(boolean isLoading)

Called when the player starts or stops loading the source.

default void
onIsPlayingChanged(boolean isPlaying)

Called when the value of isPlaying changes.

default void
@UnstableApi
onLoadingChanged(boolean isLoading)

This method is deprecated.

Use onIsLoadingChanged instead.

default void
onMaxSeekToPreviousPositionChanged(long maxSeekToPreviousPositionMs)

Called when the value of getMaxSeekToPreviousPosition changes.

default void

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

default void

Called when the value of getMediaMetadata changes.

default void

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

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

Called when the value returned from getPlayWhenReady changes.

default void

Called when the value of getPlaybackParameters changes.

default void

Called when the value returned from getPlaybackState changes.

default void

Called when the value returned from getPlaybackSuppressionReason changes.

default void

Called when an error occurs.

default void

Called when the PlaybackException returned by getPlayerError changes.

default void
@UnstableApi
onPlayerStateChanged(
    boolean playWhenReady,
    @Player.State int playbackState
)

This method is deprecated.

Use onPlaybackStateChanged and onPlayWhenReadyChanged instead.

default void

Called when the value of getPlaylistMetadata changes.

default void

This method is deprecated.

Use onPositionDiscontinuity instead.

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

Called when a position discontinuity occurs.

default void

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.

default void

Called when the value of getRepeatMode changes.

default void
onSeekBackIncrementChanged(long seekBackIncrementMs)

Called when the value of getSeekBackIncrement changes.

default void
onSeekForwardIncrementChanged(long seekForwardIncrementMs)

Called when the value of getSeekForwardIncrement changes.

default void
onShuffleModeEnabledChanged(boolean shuffleModeEnabled)

Called when the value of getShuffleModeEnabled changes.

default void
onSkipSilenceEnabledChanged(boolean skipSilenceEnabled)

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

default 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.

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

Called when the value of getCurrentTimeline changes.

default void

Called when the value returned from getTrackSelectionParameters changes.

default void

Called when the value of getCurrentTracks changes.

default void

Called each time when getVideoSize changes.

default void
onVolumeChanged(float volume)

Called when the value of getVolume changes.

Public methods

addListener

abstract void addListener(AnalyticsListener listener)

Adds a listener for analytics events.

Parameters
AnalyticsListener listener

The listener to add.

notifySeekStarted

abstract 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.

onAudioCodecError

abstract 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

abstract 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

abstract void onAudioDecoderReleased(String decoderName)

Called when a audio decoder is released.

Parameters
String decoderName

The audio decoder that was released.

onAudioDisabled

abstract void onAudioDisabled(DecoderCounters counters)

Called when the audio renderer is disabled.

Parameters
DecoderCounters counters

DecoderCounters that were updated by the audio renderer.

onAudioEnabled

abstract 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

abstract 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

abstract 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.

onAudioSinkError

abstract 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

abstract void onAudioTrackInitialized(AudioSink.AudioTrackConfig audioTrackConfig)

Called when an AudioTrack has been initialized.

Parameters
AudioSink.AudioTrackConfig audioTrackConfig

The AudioSink.AudioTrackConfig of the initialized .

onAudioTrackReleased

abstract void onAudioTrackReleased(AudioSink.AudioTrackConfig audioTrackConfig)

Called when an AudioTrack has been released.

Parameters
AudioSink.AudioTrackConfig audioTrackConfig

The AudioSink.AudioTrackConfig of the released .

onAudioUnderrun

abstract 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.

onDroppedFrames

abstract 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.

onRenderedFirstFrame

abstract 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

abstract 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.

onVideoCodecError

abstract 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

abstract 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

abstract void onVideoDecoderReleased(String decoderName)

Called when a video decoder is released.

Parameters
String decoderName

The video decoder that was released.

onVideoDisabled

abstract void onVideoDisabled(DecoderCounters counters)

Called when the video renderer is disabled.

Parameters
DecoderCounters counters

DecoderCounters that were updated by the video renderer.

onVideoEnabled

abstract 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

abstract 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

abstract 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.

release

abstract void release()

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

removeListener

abstract void removeListener(AnalyticsListener listener)

Removes a previously added analytics event listener.

Parameters
AnalyticsListener listener

The listener to remove.

setPlayer

abstract 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.

updateMediaPeriodQueueInfo

abstract 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.