1 /* 2 * Copyright (C) 2016 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 package com.google.android.exoplayer2.source; 17 18 import androidx.annotation.IntDef; 19 import com.google.android.exoplayer2.C; 20 import com.google.android.exoplayer2.FormatHolder; 21 import com.google.android.exoplayer2.decoder.DecoderInputBuffer; 22 import java.io.IOException; 23 import java.lang.annotation.Documented; 24 import java.lang.annotation.Retention; 25 import java.lang.annotation.RetentionPolicy; 26 27 /** 28 * A stream of media samples (and associated format information). 29 */ 30 public interface SampleStream { 31 32 /** Return values of {@link #readData(FormatHolder, DecoderInputBuffer, boolean)}. */ 33 @Documented 34 @Retention(RetentionPolicy.SOURCE) 35 @IntDef({C.RESULT_NOTHING_READ, C.RESULT_FORMAT_READ, C.RESULT_BUFFER_READ}) 36 @interface ReadDataResult {} 37 38 /** 39 * Returns whether data is available to be read. 40 * <p> 41 * Note: If the stream has ended then a buffer with the end of stream flag can always be read from 42 * {@link #readData(FormatHolder, DecoderInputBuffer, boolean)}. Hence an ended stream is always 43 * ready. 44 * 45 * @return Whether data is available to be read. 46 */ isReady()47 boolean isReady(); 48 49 /** 50 * Throws an error that's preventing data from being read. Does nothing if no such error exists. 51 * 52 * @throws IOException The underlying error. 53 */ maybeThrowError()54 void maybeThrowError() throws IOException; 55 56 /** 57 * Attempts to read from the stream. 58 * 59 * <p>If the stream has ended then {@link C#BUFFER_FLAG_END_OF_STREAM} flag is set on {@code 60 * buffer} and {@link C#RESULT_BUFFER_READ} is returned. Else if no data is available then {@link 61 * C#RESULT_NOTHING_READ} is returned. Else if the format of the media is changing or if {@code 62 * formatRequired} is set then {@code formatHolder} is populated and {@link C#RESULT_FORMAT_READ} 63 * is returned. Else {@code buffer} is populated and {@link C#RESULT_BUFFER_READ} is returned. 64 * 65 * @param formatHolder A {@link FormatHolder} to populate in the case of reading a format. 66 * @param buffer A {@link DecoderInputBuffer} to populate in the case of reading a sample or the 67 * end of the stream. If the end of the stream has been reached, the {@link 68 * C#BUFFER_FLAG_END_OF_STREAM} flag will be set on the buffer. If a {@link 69 * DecoderInputBuffer#isFlagsOnly() flags-only} buffer is passed, then no {@link 70 * DecoderInputBuffer#data} will be read and the read position of the stream will not change, 71 * but the flags of the buffer will be populated. 72 * @param formatRequired Whether the caller requires that the format of the stream be read even if 73 * it's not changing. A sample will never be read if set to true, however it is still possible 74 * for the end of stream or nothing to be read. 75 * @return The status of read, one of {@link ReadDataResult}. 76 */ 77 @ReadDataResult readData(FormatHolder formatHolder, DecoderInputBuffer buffer, boolean formatRequired)78 int readData(FormatHolder formatHolder, DecoderInputBuffer buffer, boolean formatRequired); 79 80 /** 81 * Attempts to skip to the keyframe before the specified position, or to the end of the stream if 82 * {@code positionUs} is beyond it. 83 * 84 * @param positionUs The specified time. 85 * @return The number of samples that were skipped. 86 */ skipData(long positionUs)87 int skipData(long positionUs); 88 89 } 90