Document and remove check for C.TIME_UNSET when consuming data in TS

PiperOrigin-RevId: 595647795

libraries/extractor/src/main/java/androidx/media3/extractor/CeaUtil.java

@@ -15,6 +15,8 @@
  */
 package androidx.media3.extractor;
 
+import static androidx.media3.common.util.Assertions.checkState;
+
 import androidx.media3.common.C;
 import androidx.media3.common.util.Log;
 import androidx.media3.common.util.ParsableByteArray;
@@ -104,7 +106,7 @@ public final class CeaUtil {
     for (TrackOutput output : outputs) {
       ccDataBuffer.setPosition(sampleStartPosition);
       output.sampleData(ccDataBuffer, sampleLength);
-      if (presentationTimeUs != C.TIME_UNSET) {
+      checkState(presentationTimeUs != C.TIME_UNSET);
       output.sampleMetadata(
           presentationTimeUs,
           C.BUFFER_FLAG_KEY_FRAME,
@@ -113,7 +115,6 @@ public final class CeaUtil {
           /* cryptoData= */ null);
     }
   }
-  }
 
   /**
    * Reads a value from the provided buffer consisting of zero or more 0xFF bytes followed by a

libraries/extractor/src/main/java/androidx/media3/extractor/ts/Ac3Reader.java

@@ -15,6 +15,7 @@
  */
 package androidx.media3.extractor.ts;
 
+import static androidx.media3.common.util.Assertions.checkState;
 import static java.lang.Math.min;
 import static java.lang.annotation.ElementType.TYPE_USE;
 
@@ -112,10 +113,8 @@ public final class Ac3Reader implements ElementaryStreamReader {
 
   @Override
   public void packetStarted(long pesTimeUs, @TsPayloadReader.Flags int flags) {
-    if (pesTimeUs != C.TIME_UNSET) {
     timeUs = pesTimeUs;
   }
-  }
 
   @Override
   public void consume(ParsableByteArray data) {
@@ -143,10 +142,10 @@ public final class Ac3Reader implements ElementaryStreamReader {
           output.sampleData(data, bytesToRead);
           bytesRead += bytesToRead;
           if (bytesRead == sampleSize) {
-            if (timeUs != C.TIME_UNSET) {
+            // packetStarted method must be called before reading samples.
+            checkState(timeUs != C.TIME_UNSET);
             output.sampleMetadata(timeUs, C.BUFFER_FLAG_KEY_FRAME, sampleSize, 0, null);
             timeUs += sampleDurationUs;
-            }
             state = STATE_FINDING_SYNC;
           }
           break;

libraries/extractor/src/main/java/androidx/media3/extractor/ts/Ac4Reader.java

@@ -15,6 +15,7 @@
  */
 package androidx.media3.extractor.ts;
 
+import static androidx.media3.common.util.Assertions.checkState;
 import static java.lang.Math.min;
 import static java.lang.annotation.ElementType.TYPE_USE;
 
@@ -114,10 +115,8 @@ public final class Ac4Reader implements ElementaryStreamReader {
 
   @Override
   public void packetStarted(long pesTimeUs, @TsPayloadReader.Flags int flags) {
-    if (pesTimeUs != C.TIME_UNSET) {
     timeUs = pesTimeUs;
   }
-  }
 
   @Override
   public void consume(ParsableByteArray data) {
@@ -145,10 +144,10 @@ public final class Ac4Reader implements ElementaryStreamReader {
           output.sampleData(data, bytesToRead);
           bytesRead += bytesToRead;
           if (bytesRead == sampleSize) {
-            if (timeUs != C.TIME_UNSET) {
+            // packetStarted method must be called before reading samples.
+            checkState(timeUs != C.TIME_UNSET);
             output.sampleMetadata(timeUs, C.BUFFER_FLAG_KEY_FRAME, sampleSize, 0, null);
             timeUs += sampleDurationUs;
-            }
             state = STATE_FINDING_SYNC;
           }
           break;

libraries/extractor/src/main/java/androidx/media3/extractor/ts/AdtsReader.java

@@ -15,6 +15,7 @@
  */
 package androidx.media3.extractor.ts;
 
+import static androidx.media3.common.util.Assertions.checkState;
 import static java.lang.Math.min;
 
 import androidx.annotation.Nullable;
@@ -155,10 +156,8 @@ public final class AdtsReader implements ElementaryStreamReader {
 
   @Override
   public void packetStarted(long pesTimeUs, @TsPayloadReader.Flags int flags) {
-    if (pesTimeUs != C.TIME_UNSET) {
     timeUs = pesTimeUs;
   }
-  }
 
   @Override
   public void consume(ParsableByteArray data) throws ParserException {
@@ -537,10 +536,10 @@ public final class AdtsReader implements ElementaryStreamReader {
     currentOutput.sampleData(data, bytesToRead);
     bytesRead += bytesToRead;
     if (bytesRead == sampleSize) {
-      if (timeUs != C.TIME_UNSET) {
+      // packetStarted method must be called before reading samples.
+      checkState(timeUs != C.TIME_UNSET);
       currentOutput.sampleMetadata(timeUs, C.BUFFER_FLAG_KEY_FRAME, sampleSize, 0, null);
       timeUs += currentSampleDuration;
-      }
       setFindingSampleState();
     }
   }

libraries/extractor/src/main/java/androidx/media3/extractor/ts/DtsReader.java

@@ -15,6 +15,7 @@
  */
 package androidx.media3.extractor.ts;
 
+import static androidx.media3.common.util.Assertions.checkState;
 import static java.lang.Math.min;
 
 import androidx.annotation.Nullable;
@@ -89,10 +90,8 @@ public final class DtsReader implements ElementaryStreamReader {
 
   @Override
   public void packetStarted(long pesTimeUs, @TsPayloadReader.Flags int flags) {
-    if (pesTimeUs != C.TIME_UNSET) {
     timeUs = pesTimeUs;
   }
-  }
 
   @Override
   public void consume(ParsableByteArray data) {
@@ -117,10 +116,10 @@ public final class DtsReader implements ElementaryStreamReader {
           output.sampleData(data, bytesToRead);
           bytesRead += bytesToRead;
           if (bytesRead == sampleSize) {
-            if (timeUs != C.TIME_UNSET) {
+            // packetStarted method must be called before consuming samples.
+            checkState(timeUs != C.TIME_UNSET);
             output.sampleMetadata(timeUs, C.BUFFER_FLAG_KEY_FRAME, sampleSize, 0, null);
             timeUs += sampleDurationUs;
-            }
             state = STATE_FINDING_SYNC;
           }
           break;

libraries/extractor/src/main/java/androidx/media3/extractor/ts/DvbSubtitleReader.java

@@ -15,6 +15,7 @@
  */
 package androidx.media3.extractor.ts;
 
+import static androidx.media3.common.util.Assertions.checkState;
 import static androidx.media3.extractor.ts.TsPayloadReader.FLAG_DATA_ALIGNMENT_INDICATOR;
 
 import androidx.media3.common.C;
@@ -79,9 +80,7 @@ public final class DvbSubtitleReader implements ElementaryStreamReader {
       return;
     }
     writingSample = true;
-    if (pesTimeUs != C.TIME_UNSET) {
     sampleTimeUs = pesTimeUs;
-    }
     sampleBytesWritten = 0;
     bytesToCheck = 2;
   }
@@ -89,11 +88,11 @@ public final class DvbSubtitleReader implements ElementaryStreamReader {
   @Override
   public void packetFinished(boolean isEndOfInput) {
     if (writingSample) {
-      if (sampleTimeUs != C.TIME_UNSET) {
+      // packetStarted method must be called before reading sample.
+      checkState(sampleTimeUs != C.TIME_UNSET);
       for (TrackOutput output : outputs) {
         output.sampleMetadata(sampleTimeUs, C.BUFFER_FLAG_KEY_FRAME, sampleBytesWritten, 0, null);
       }
-      }
       writingSample = false;
     }
   }

libraries/extractor/src/main/java/androidx/media3/extractor/ts/ElementaryStreamReader.java

@@ -21,7 +21,20 @@ import androidx.media3.common.util.UnstableApi;
 import androidx.media3.extractor.ExtractorOutput;
 import androidx.media3.extractor.TrackOutput;
 
-/** Extracts individual samples from an elementary media stream, preserving original order. */
+/**
+ * Extracts individual samples from an elementary media stream, preserving original order.
+ *
+ * <p>The expected sequence of method calls is as follows:
+ *
+ * <ol>
+ *   <li>{@link #createTracks(ExtractorOutput, PesReader.TrackIdGenerator)} (once at initialization)
+ *   <li>{@link #seek()} (optional, to reset the state)
+ *   <li>{@link #packetStarted(long, int)} (to signal the start of a new packet)
+ *   <li>{@link #consume(ParsableByteArray)} (zero or more times, to provide packet data)
+ *   <li>{@link #packetFinished(boolean)} (to signal the end of the current packet)
+ *   <li>Repeat steps 3-5 for subsequent packets
+ * </ol>
+ */
 @UnstableApi
 public interface ElementaryStreamReader {
 

libraries/extractor/src/main/java/androidx/media3/extractor/ts/H263Reader.java

@@ -16,6 +16,7 @@
 package androidx.media3.extractor.ts;
 
 import static androidx.media3.common.util.Assertions.checkNotNull;
+import static androidx.media3.common.util.Assertions.checkState;
 import static androidx.media3.common.util.Assertions.checkStateNotNull;
 import static androidx.media3.common.util.Util.castNonNull;
 import static java.lang.annotation.ElementType.TYPE_USE;
@@ -130,10 +131,8 @@ public final class H263Reader implements ElementaryStreamReader {
   @Override
   public void packetStarted(long pesTimeUs, @TsPayloadReader.Flags int flags) {
     // TODO (Internal b/32267012): Consider using random access indicator.
-    if (pesTimeUs != C.TIME_UNSET) {
     this.pesTimeUs = pesTimeUs;
   }
-  }
 
   @Override
   public void consume(ParsableByteArray data) {
@@ -479,10 +478,9 @@ public final class H263Reader implements ElementaryStreamReader {
     }
 
     public void onDataEnd(long position, int bytesWrittenPastPosition, boolean hasOutputFormat) {
-      if (startCodeValue == START_CODE_VALUE_VOP
+      // packetStarted method must be called before reading sample.
-          && hasOutputFormat
+      checkState(sampleTimeUs != C.TIME_UNSET);
-          && readingSample
+      if (startCodeValue == START_CODE_VALUE_VOP && hasOutputFormat && readingSample) {
-          && sampleTimeUs != C.TIME_UNSET) {
         int size = (int) (position - samplePosition);
         @C.BufferFlags int flags = sampleIsKeyframe ? C.BUFFER_FLAG_KEY_FRAME : 0;
         output.sampleMetadata(

libraries/extractor/src/main/java/androidx/media3/extractor/ts/H264Reader.java

@@ -114,9 +114,7 @@ public final class H264Reader implements ElementaryStreamReader {
 
   @Override
   public void packetStarted(long pesTimeUs, @TsPayloadReader.Flags int flags) {
-    if (pesTimeUs != C.TIME_UNSET) {
     this.pesTimeUs = pesTimeUs;
-    }
     randomAccessIndicator |= (flags & FLAG_RANDOM_ACCESS_INDICATOR) != 0;
   }
 

libraries/extractor/src/main/java/androidx/media3/extractor/ts/H265Reader.java

@@ -117,10 +117,8 @@ public final class H265Reader implements ElementaryStreamReader {
   @Override
   public void packetStarted(long pesTimeUs, @TsPayloadReader.Flags int flags) {
     // TODO (Internal b/32267012): Consider using random access indicator.
-    if (pesTimeUs != C.TIME_UNSET) {
     this.pesTimeUs = pesTimeUs;
   }
-  }
 
   @Override
   public void consume(ParsableByteArray data) {

libraries/extractor/src/main/java/androidx/media3/extractor/ts/Id3Reader.java

@@ -15,6 +15,7 @@
  */
 package androidx.media3.extractor.ts;
 
+import static androidx.media3.common.util.Assertions.checkState;
 import static androidx.media3.extractor.metadata.id3.Id3Decoder.ID3_HEADER_LENGTH;
 import static androidx.media3.extractor.ts.TsPayloadReader.FLAG_DATA_ALIGNMENT_INDICATOR;
 import static java.lang.Math.min;
@@ -77,9 +78,7 @@ public final class Id3Reader implements ElementaryStreamReader {
       return;
     }
     writingSample = true;
-    if (pesTimeUs != C.TIME_UNSET) {
     sampleTimeUs = pesTimeUs;
-    }
     sampleSize = 0;
     sampleBytesRead = 0;
   }
@@ -126,9 +125,9 @@ public final class Id3Reader implements ElementaryStreamReader {
     if (!writingSample || sampleSize == 0 || sampleBytesRead != sampleSize) {
       return;
     }
-    if (sampleTimeUs != C.TIME_UNSET) {
+    // packetStarted method must be called before consuming samples.
+    checkState(sampleTimeUs != C.TIME_UNSET);
     output.sampleMetadata(sampleTimeUs, C.BUFFER_FLAG_KEY_FRAME, sampleSize, 0, null);
-    }
     writingSample = false;
   }
 }

libraries/extractor/src/main/java/androidx/media3/extractor/ts/LatmReader.java

@@ -15,6 +15,7 @@
  */
 package androidx.media3.extractor.ts;
 
+import static androidx.media3.common.util.Assertions.checkState;
 import static java.lang.Math.min;
 
 import androidx.annotation.Nullable;
@@ -101,10 +102,8 @@ public final class LatmReader implements ElementaryStreamReader {
 
   @Override
   public void packetStarted(long pesTimeUs, @TsPayloadReader.Flags int flags) {
-    if (pesTimeUs != C.TIME_UNSET) {
     timeUs = pesTimeUs;
   }
-  }
 
   @Override
   public void consume(ParsableByteArray data) throws ParserException {
@@ -314,11 +313,11 @@ public final class LatmReader implements ElementaryStreamReader {
       sampleDataBuffer.setPosition(0);
     }
     output.sampleData(sampleDataBuffer, muxLengthBytes);
-    if (timeUs != C.TIME_UNSET) {
+    // packetStarted method must be called before consuming samples.
+    checkState(timeUs != C.TIME_UNSET);
     output.sampleMetadata(timeUs, C.BUFFER_FLAG_KEY_FRAME, muxLengthBytes, 0, null);
     timeUs += sampleDurationUs;
   }
-  }
 
   private void resetBufferForSize(int newSize) {
     sampleDataBuffer.reset(newSize);

libraries/extractor/src/main/java/androidx/media3/extractor/ts/MpegAudioReader.java

@@ -15,6 +15,7 @@
  */
 package androidx.media3.extractor.ts;
 
+import static androidx.media3.common.util.Assertions.checkState;
 import static java.lang.Math.min;
 
 import androidx.annotation.Nullable;
@@ -92,10 +93,8 @@ public final class MpegAudioReader implements ElementaryStreamReader {
 
   @Override
   public void packetStarted(long pesTimeUs, @TsPayloadReader.Flags int flags) {
-    if (pesTimeUs != C.TIME_UNSET) {
     timeUs = pesTimeUs;
   }
-  }
 
   @Override
   public void consume(ParsableByteArray data) {
@@ -233,10 +232,10 @@ public final class MpegAudioReader implements ElementaryStreamReader {
       return;
     }
 
-    if (timeUs != C.TIME_UNSET) {
+    // packetStarted method must be called before consuming samples.
+    checkState(timeUs != C.TIME_UNSET);
     output.sampleMetadata(timeUs, C.BUFFER_FLAG_KEY_FRAME, frameSize, 0, null);
     timeUs += frameDurationUs;
-    }
     frameBytesRead = 0;
     state = STATE_FINDING_HEADER;
   }