Deprecate decode-only flag.

The flag is no longer used by our components and only set and checked
in a few places to guarantee compatiblity with existing renderers and
decoders that still use it.

The flag will be removed in the future due to its design limitations.

#minor-release

PiperOrigin-RevId: 571291168

libraries/common/src/main/java/androidx/media3/common/C.java

@@ -618,6 +618,7 @@ public final class C {
    * {@link #BUFFER_FLAG_LAST_SAMPLE}, {@link #BUFFER_FLAG_ENCRYPTED} and {@link
    * #BUFFER_FLAG_DECODE_ONLY}.
    */
+  @SuppressWarnings("deprecation") // Includes deprecated BUFFER_FLAG_DECODE_ONLY flag.
   @UnstableApi
   @Documented
   @Retention(RetentionPolicy.SOURCE)
@@ -654,8 +655,12 @@ public final class C {
   /** Indicates that a buffer is (at least partially) encrypted. */
   @UnstableApi public static final int BUFFER_FLAG_ENCRYPTED = 1 << 30; // 0x40000000
 
-  /** Indicates that a buffer should be decoded but not rendered. */
+  /**
-  @UnstableApi public static final int BUFFER_FLAG_DECODE_ONLY = 1 << 31; // 0x80000000
+   * @deprecated Renderers and decoders will check whether the buffer time is greater or equal to
+   *     the desired start time without the need to set this flag. Custom decoders can mark other
+   *     buffers with {@code DecoderOutputBuffer.shouldBeSkipped} if needed.
+   */
+  @UnstableApi @Deprecated public static final int BUFFER_FLAG_DECODE_ONLY = 1 << 31; // 0x80000000
 
   /** A realtime {@linkplain MediaFormat#KEY_PRIORITY codec priority}. */
   @UnstableApi public static final int MEDIA_CODEC_PRIORITY_REALTIME = 0;

libraries/decoder/src/main/java/androidx/media3/decoder/Buffer.java

@@ -31,7 +31,14 @@ public abstract class Buffer {
     flags = 0;
   }
 
-  /** Returns whether the {@link C#BUFFER_FLAG_DECODE_ONLY} flag is set. */
+  /**
+   * @deprecated Check instead whether the buffer time is greater or equal to the desired start
+   *     time. In custom renderers, the start time is {@code BaseRenderer.getLastResetPositionUs()}.
+   *     In custom decoders, the check can be done with {@link
+   *     SimpleDecoder#isAtLeastOutputStartTimeUs}.
+   */
+  @Deprecated
+  @SuppressWarnings("deprecation") // Checking deprecated flag.
   public final boolean isDecodeOnly() {
     return getFlag(C.BUFFER_FLAG_DECODE_ONLY);
   }

libraries/decoder/src/main/java/androidx/media3/decoder/SimpleDecoder.java

@@ -236,6 +236,9 @@ public abstract class SimpleDecoder<
     }
   }
 
+  // Setting and checking deprecated decode-only flag for compatibility with custom decoders that
+  // are still using it.
+  @SuppressWarnings("deprecation")
   private boolean decode() throws InterruptedException {
     I inputBuffer;
     O outputBuffer;

libraries/decoder_midi/src/main/java/androidx/media3/decoder/midi/MidiExtractor.java

@@ -348,9 +348,7 @@ public final class MidiExtractor implements Extractor, SeekMap {
 
       if (nextTimestampUs != C.TIME_UNSET && nextTimestampUs < seekTimeUs) {
         nextChunk.outputFrontSample(
-            trackOutput,
+            trackOutput, C.BUFFER_FLAG_KEY_FRAME, /* skipNoteEvents= */ true);
-            C.BUFFER_FLAG_KEY_FRAME | C.BUFFER_FLAG_DECODE_ONLY,
-            /* skipNoteEvents= */ true);
         nextChunk.populateFrontTrackEvent();
         trackPriorityQueue.add(nextChunk);
       }

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/audio/DecoderAudioRenderer.java

@@ -478,6 +478,8 @@ public abstract class DecoderAudioRenderer<
     }
   }
 
+  // Setting deprecated decode-only flag for compatibility with decoders that are still using it.
+  @SuppressWarnings("deprecation")
   private boolean feedInputBuffer() throws DecoderException, ExoPlaybackException {
     if (decoder == null
         || decoderReinitializationState == REINITIALIZATION_STATE_WAIT_END_OF_STREAM

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/source/SampleQueue.java

@@ -228,8 +228,9 @@ public class SampleQueue implements TrackOutput {
   }
 
   /**
-   * Sets the start time for the queue. Samples with earlier timestamps will be discarded or have
+   * Sets the start time for the queue. Samples with earlier timestamps will be discarded if
-   * the {@link C#BUFFER_FLAG_DECODE_ONLY} flag set when read.
+   * {@linkplain MimeTypes#allSamplesAreSyncSamples all samples are sync samples} in the given input
+   * format.
    *
    * @param startTimeUs The start time, in microseconds.
    */
@@ -692,7 +693,9 @@ public class SampleQueue implements TrackOutput {
     sampleDataQueue.rewind();
   }
 
-  @SuppressWarnings("ReferenceEquality") // See comments in setUpstreamFormat
+  // Setting deprecated decode-only flag for compatibility with renderers that are still using it.
+  // See comments in setUpstreamFormat for reference equality warning.
+  @SuppressWarnings({"ReferenceEquality", "deprecation"})
   private synchronized int peekSampleMetadata(
       FormatHolder formatHolder,
       DecoderInputBuffer buffer,

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/text/TextRenderer.java

@@ -239,6 +239,8 @@ public final class TextRenderer extends BaseRenderer implements Callback {
     }
   }
 
+  // Setting deprecated decode-only flag for compatibility with decoders that are still using it.
+  @SuppressWarnings("deprecation")
   @Override
   public void render(long positionUs, long elapsedRealtimeUs) {
     if (isCurrentStreamFinal()

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/video/DecoderVideoRenderer.java

@@ -739,6 +739,8 @@ public abstract class DecoderVideoRenderer extends BaseRenderer {
     }
   }
 
+  // Setting deprecated decode-only flag for compatibility with decoders that are still using it.
+  @SuppressWarnings("deprecation")
   private boolean feedInputBuffer() throws DecoderException, ExoPlaybackException {
     if (decoder == null
         || decoderReinitializationState == REINITIALIZATION_STATE_WAIT_END_OF_STREAM

libraries/extractor/src/main/java/androidx/media3/extractor/text/SimpleSubtitleDecoder.java

@@ -70,7 +70,8 @@ public abstract class SimpleSubtitleDecoder
     return new SubtitleDecoderException("Unexpected decode error", error);
   }
 
-  @SuppressWarnings("ByteBufferBackingArray")
+  // Clearing deprecated decode-only flag for compatibility with decoders that are still using it.
+  @SuppressWarnings({"ByteBufferBackingArray", "deprecation"})
   @Override
   @Nullable
   protected final SubtitleDecoderException decode(

libraries/extractor/src/main/java/androidx/media3/extractor/text/SubtitleTranscodingTrackOutput.java

@@ -156,6 +156,8 @@ import org.checkerframework.checker.nullness.qual.MonotonicNonNull;
     sampleDataStart = sampleStart + size;
   }
 
+  // Clearing deprecated decode-only flag for compatibility with decoders that are still using it.
+  @SuppressWarnings("deprecation")
   private void outputSample(CuesWithTiming cuesWithTiming, long timeUs, int flags) {
     checkStateNotNull(currentFormat); // format() must be called before sampleMetadata()
     byte[] cuesWithDurationBytes =

libraries/extractor/src/main/java/androidx/media3/extractor/text/cea/CeaDecoder.java

@@ -79,6 +79,8 @@ import java.util.PriorityQueue;
     return dequeuedInputBuffer;
   }
 
+  // Still using deprecated decoder-only flag until this decoder is replaced by a SubtitleParser.
+  @SuppressWarnings("deprecation")
   @Override
   public void queueInputBuffer(SubtitleInputBuffer inputBuffer) throws SubtitleDecoderException {
     Assertions.checkArgument(inputBuffer == dequeuedInputBuffer);

libraries/test_data/src/test/assets/extractordumps/midi/seek_test_with_non_note_events.mid.dump

@@ -12,27 +12,27 @@ track 0:
     codecs = audio/midi
   sample 0:
     time = 0
-    flags = -2147483647
+    flags = 1
     data = length 3, hash 70FB
   sample 1:
     time = 0
-    flags = -2147483647
+    flags = 1
     data = length 3, hash FFFF56B6
   sample 2:
     time = 0
-    flags = -2147483647
+    flags = 1
     data = length 7, hash C95FA238
   sample 3:
     time = 0
-    flags = -2147483647
+    flags = 1
     data = length 3, hash FFFF494C
   sample 4:
     time = 0
-    flags = -2147483647
+    flags = 1
     data = length 6, hash 37A83E76
   sample 5:
     time = 4999999
-    flags = -2147483647
+    flags = 1
     data = length 3, hash 8DE
   sample 6:
     time = 5500000