From f768fedaee81792d1c2b4c27fbefa981ff959844 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 (cherry picked from commit b324b8aa72db8853cf28429fa6462acdbf769f21) --- .../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 5147bc9e96..a26a40d573 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();