From b4860fada0cbc8a30c23a14eb8ca8f2b81742139 Mon Sep 17 00:00:00 2001
From: tonihei <tonihei@google.com>
Date: Thu, 20 Jul 2023 12:12:26 +0100
Subject: [PATCH] Document MediaCodecRenderer's stream and codec behavior
 assumptions

The class tries to be flexible to support as many different input
and codec behavior combinations as possible. But so far it didn't
spell out its remaining assumptions and explicit non-assumptions,
making it hard to know which behavior to rely on.

PiperOrigin-RevId: 549589347
---
 .../mediacodec/MediaCodecRenderer.java        | 23 +++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/mediacodec/MediaCodecRenderer.java b/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/mediacodec/MediaCodecRenderer.java
index 2128c584bf..cfecc4b4f9 100644
--- a/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/mediacodec/MediaCodecRenderer.java
+++ b/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/mediacodec/MediaCodecRenderer.java
@@ -87,6 +87,29 @@ import java.util.ArrayDeque;
 import java.util.List;
 
 /** An abstract renderer that uses {@link MediaCodec} to decode samples for rendering. */
+//
+// The input media in the SampleStreams and the behavior of MediaCodec are outside of the control of
+// this class and we try to make as few assumptions as possible.
+//
+// Assumptions about the input streams:
+// - The first stream may pre-roll samples from a keyframe preceding the start time. Subsequent
+//   streams added via replaceSampleStream are always fully rendered.
+//
+// Assumptions about the codec output:
+// - Output timestamps from one stream are monotonically increasing.
+// - Output samples from the first stream with less than the declared start time are pre-rolled
+//   samples that are meant to be dropped. Output samples from subsequent streams are always fully
+//   rendered.
+// - There is exactly one last output sample with a timestamp greater or equal to the largest input
+//   sample timestamp of this stream.
+//
+// Explicit non-assumptions this class accepts as valid behavior:
+// - Input sample timestamps may not be monotonically increasing (e.g. for B-frames).
+// - Input and output sample timestamps may be less than the declared stream start time.
+// - Input and output sample timestamps may exceed the stream start time of the next stream.
+//   (The points above imply that output sample timestamps may jump backwards at stream transitions)
+// - Input and output sample timestamps may not be the same.
+// - The number of output samples may be different from the number of input samples.
 @UnstableApi
 public abstract class MediaCodecRenderer extends BaseRenderer {