From b324b8aa72db8853cf28429fa6462acdbf769f21 Mon Sep 17 00:00:00 2001 From: tonihei Date: Wed, 28 Jun 2023 08:55:56 +0000 Subject: [PATCH] Clarify MediaPeriod.readDiscontinuity Javadoc It currently wrongly documents that it is only called before reading streams (that has never been the case and all MediaPeriods already need to handle calls after reading samples from the streams). It was also a bit unclear what a discontinuity implies and the new Javadoc calls out the main use case for discontinuties and the intended meaning of returning a discontinuity. #minor-release PiperOrigin-RevId: 543989124 --- .../media3/exoplayer/source/MediaPeriod.java | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/source/MediaPeriod.java b/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/source/MediaPeriod.java index 01fe9d34e3..62b4e2ccc7 100644 --- a/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/source/MediaPeriod.java +++ b/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/source/MediaPeriod.java @@ -158,14 +158,18 @@ public interface MediaPeriod extends SequenceableLoader { /** * Attempts to read a discontinuity. * + *

A discontinuity implies that the provided {@link SampleStream SampleStreams} will start from + * a new playback position and any output pipelines need to be reset. This happens for example if + * the streams provide decode-only samples before the intended playback start position that need + * to be dropped. + * *

After this method has returned a value other than {@link C#TIME_UNSET}, all {@link - * SampleStream}s provided by the period are guaranteed to start from a key frame. + * SampleStream SampleStreams} provided by the period are guaranteed to start from a key frame. * - *

This method is only called after the period has been prepared and before reading from any - * {@link SampleStream}s provided by the period. + *

This method is only called after the period has been prepared. * - * @return If a discontinuity was read then the playback position in microseconds after the - * discontinuity. Else {@link C#TIME_UNSET}. + * @return The playback position after the discontinuity, in microseconds, or {@link C#TIME_UNSET} + * if there is no discontinuity. */ long readDiscontinuity();