public interface

SampleStream

 androidx.media3.exoplayer.source.SampleStream

Subclasses:

EmptySampleStream, ChunkSampleStream<T>, ChunkSampleStream.EmbeddedSampleStream, FakeSampleStream

Gradle dependencies

compile group: 'androidx.media3', name: 'media3-exoplayer', version: '1.5.0-alpha01'

  • groupId: androidx.media3
  • artifactId: media3-exoplayer
  • version: 1.5.0-alpha01

Artifact androidx.media3:media3-exoplayer:1.5.0-alpha01 it located at Google repository (https://maven.google.com/)

Overview

A stream of media samples (and associated format information).

Summary

Fields
public static final intFLAG_OMIT_SAMPLE_DATA

Specifies that DecoderInputBuffer.data, DecoderInputBuffer.supplementalData and DecoderInputBuffer.cryptoInfo should not be populated when reading a sample buffer.

public static final intFLAG_PEEK

Specifies that the read position should not be advanced if a sample buffer is read.

public static final intFLAG_REQUIRE_FORMAT

Specifies that if a sample buffer would normally be read next, the format of the stream should be read instead.

Methods
public booleanisReady()

Returns whether data is available to be read.

public voidmaybeThrowError()

Throws an error that's preventing data from being read.

public intreadData(FormatHolder formatHolder, DecoderInputBuffer buffer, int readFlags)

Attempts to read from the stream.

public intskipData(long positionUs)

Attempts to skip to the keyframe before the specified position, or to the end of the stream if positionUs is beyond it.

Fields

public static final int FLAG_PEEK

Specifies that the read position should not be advanced if a sample buffer is read.

public static final int FLAG_REQUIRE_FORMAT

Specifies that if a sample buffer would normally be read next, the format of the stream should be read instead. In detail, the effect of this flag is as follows:

  • If a sample buffer would be read were the flag not set, then the stream format will be read instead.
  • If nothing would be read were the flag not set, then the stream format will be read if it's known. If the stream format is not known then behavior is unchanged.
  • If an end of stream buffer would be read were the flag not set, then behavior is unchanged.

public static final int FLAG_OMIT_SAMPLE_DATA

Specifies that DecoderInputBuffer.data, DecoderInputBuffer.supplementalData and DecoderInputBuffer.cryptoInfo should not be populated when reading a sample buffer.

This flag is useful for efficiently reading or (when combined with SampleStream.FLAG_PEEK) peeking sample metadata. It can also be used for efficiency by a caller wishing to skip a sample buffer.

Methods

public boolean isReady()

Returns whether data is available to be read.

Note: If the stream has ended then a buffer with the end of stream flag can always be read from SampleStream.readData(FormatHolder, DecoderInputBuffer, int). Hence an ended stream is always ready.

Returns:

Whether data is available to be read.

public void maybeThrowError()

Throws an error that's preventing data from being read. Does nothing if no such error exists.

public int readData(FormatHolder formatHolder, DecoderInputBuffer buffer, int readFlags)

Attempts to read from the stream.

If the stream has ended then C.BUFFER_FLAG_END_OF_STREAM flag is set on buffer and C.RESULT_BUFFER_READ is returned. Else if no data is available then C.RESULT_NOTHING_READ is returned. Else if the format of the media is changing or if formatRequired is set then formatHolder is populated and C.RESULT_FORMAT_READ is returned. Else buffer is populated and C.RESULT_BUFFER_READ is returned.

Parameters:

formatHolder: A FormatHolder to populate in the case of reading a format.
buffer: A DecoderInputBuffer to populate in the case of reading a sample or the end of the stream. If the end of the stream has been reached, the C.BUFFER_FLAG_END_OF_STREAM flag will be set on the buffer.
readFlags: Flags controlling the behavior of this read operation.

Returns:

The result of the read operation.

public int skipData(long positionUs)

Attempts to skip to the keyframe before the specified position, or to the end of the stream if positionUs is beyond it.

Parameters:

positionUs: The specified time.

Returns:

The number of samples that were skipped.

Source

/*
 * Copyright (C) 2016 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package androidx.media3.exoplayer.source;

import static java.lang.annotation.ElementType.TYPE_USE;

import androidx.annotation.IntDef;
import androidx.media3.common.C;
import androidx.media3.common.util.UnstableApi;
import androidx.media3.decoder.DecoderInputBuffer;
import androidx.media3.decoder.DecoderInputBuffer.InsufficientCapacityException;
import androidx.media3.exoplayer.FormatHolder;
import java.io.IOException;
import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/** A stream of media samples (and associated format information). */
@UnstableApi
public interface SampleStream {

  /**
   * Flags that can be specified when calling {@link #readData}. Possible flag values are {@link
   * #FLAG_PEEK}, {@link #FLAG_REQUIRE_FORMAT} and {@link #FLAG_OMIT_SAMPLE_DATA}.
   */
  @Documented
  @Retention(RetentionPolicy.SOURCE)
  @Target(TYPE_USE)
  @IntDef(
      flag = true,
      value = {FLAG_PEEK, FLAG_REQUIRE_FORMAT, FLAG_OMIT_SAMPLE_DATA})
  @interface ReadFlags {}

  /** Specifies that the read position should not be advanced if a sample buffer is read. */
  int FLAG_PEEK = 1;

  /**
   * Specifies that if a sample buffer would normally be read next, the format of the stream should
   * be read instead. In detail, the effect of this flag is as follows:
   *
   * <ul>
   *   <li>If a sample buffer would be read were the flag not set, then the stream format will be
   *       read instead.
   *   <li>If nothing would be read were the flag not set, then the stream format will be read if
   *       it's known. If the stream format is not known then behavior is unchanged.
   *   <li>If an end of stream buffer would be read were the flag not set, then behavior is
   *       unchanged.
   * </ul>
   */
  int FLAG_REQUIRE_FORMAT = 1 << 1;

  /**
   * Specifies that {@link DecoderInputBuffer#data}, {@link DecoderInputBuffer#supplementalData} and
   * {@link DecoderInputBuffer#cryptoInfo} should not be populated when reading a sample buffer.
   *
   * <p>This flag is useful for efficiently reading or (when combined with {@link #FLAG_PEEK})
   * peeking sample metadata. It can also be used for efficiency by a caller wishing to skip a
   * sample buffer.
   */
  int FLAG_OMIT_SAMPLE_DATA = 1 << 2;

  /** Return values of {@link #readData}. */
  @Documented
  @Retention(RetentionPolicy.SOURCE)
  @Target(TYPE_USE)
  @IntDef({C.RESULT_NOTHING_READ, C.RESULT_FORMAT_READ, C.RESULT_BUFFER_READ})
  @interface ReadDataResult {}

  /**
   * Returns whether data is available to be read.
   *
   * <p>Note: If the stream has ended then a buffer with the end of stream flag can always be read
   * from {@link #readData}. Hence an ended stream is always ready.
   *
   * @return Whether data is available to be read.
   */
  boolean isReady();

  /**
   * Throws an error that's preventing data from being read. Does nothing if no such error exists.
   *
   * @throws IOException The underlying error.
   */
  void maybeThrowError() throws IOException;

  /**
   * Attempts to read from the stream.
   *
   * <p>If the stream has ended then {@link C#BUFFER_FLAG_END_OF_STREAM} flag is set on {@code
   * buffer} and {@link C#RESULT_BUFFER_READ} is returned. Else if no data is available then {@link
   * C#RESULT_NOTHING_READ} is returned. Else if the format of the media is changing or if {@code
   * formatRequired} is set then {@code formatHolder} is populated and {@link C#RESULT_FORMAT_READ}
   * is returned. Else {@code buffer} is populated and {@link C#RESULT_BUFFER_READ} is returned.
   *
   * @param formatHolder A {@link FormatHolder} to populate in the case of reading a format.
   * @param buffer A {@link DecoderInputBuffer} to populate in the case of reading a sample or the
   *     end of the stream. If the end of the stream has been reached, the {@link
   *     C#BUFFER_FLAG_END_OF_STREAM} flag will be set on the buffer.
   * @param readFlags Flags controlling the behavior of this read operation.
   * @return The {@link ReadDataResult result} of the read operation.
   * @throws InsufficientCapacityException If the {@code buffer} has insufficient capacity to hold
   *     the data of a sample being read. The buffer {@link DecoderInputBuffer#timeUs timestamp} and
   *     flags are populated if this exception is thrown, but the read position is not advanced.
   */
  @ReadDataResult
  int readData(FormatHolder formatHolder, DecoderInputBuffer buffer, @ReadFlags int readFlags);

  /**
   * Attempts to skip to the keyframe before the specified position, or to the end of the stream if
   * {@code positionUs} is beyond it.
   *
   * @param positionUs The specified time.
   * @return The number of samples that were skipped.
   */
  int skipData(long positionUs);
}