1 /* 2 * Copyright (C) 2015 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.android.tv.tuner.exoplayer; 17 18 import android.os.Handler; 19 import com.google.android.exoplayer.MediaFormat; 20 import com.google.android.exoplayer.MediaFormatHolder; 21 import com.google.android.exoplayer.SampleHolder; 22 import com.google.android.exoplayer.SampleSource; 23 import com.google.android.exoplayer.TrackRenderer; 24 import java.io.IOException; 25 import java.util.List; 26 27 /** 28 * Extractor for reading track metadata and samples stored in tracks. 29 * 30 * <p>Call {@link #prepare} until it returns {@code true}, then access track metadata via {@link 31 * #getTrackFormats} and {@link #getTrackMediaFormat}. 32 * 33 * <p>Pass indices of tracks to read from to {@link #selectTrack}. A track can later be deselected 34 * by calling {@link #deselectTrack}. It is safe to select/deselect tracks after reading sample data 35 * or seeking. Initially, all tracks are deselected. 36 * 37 * <p>Call {@link #release()} when the extractor is no longer needed to free resources. 38 */ 39 public interface SampleExtractor { 40 41 /** 42 * If the extractor is currently having difficulty preparing or loading samples, then this 43 * method throws the underlying error. Otherwise does nothing. 44 * 45 * @throws IOException The underlying error. 46 */ maybeThrowError()47 void maybeThrowError() throws IOException; 48 49 /** 50 * Prepares the extractor for reading track metadata and samples. 51 * 52 * @return whether the source is ready; if {@code false}, this method must be called again. 53 * @throws IOException thrown if the source can't be read 54 */ prepare()55 boolean prepare() throws IOException; 56 57 /** Returns track information about all tracks that can be selected. */ getTrackFormats()58 List<MediaFormat> getTrackFormats(); 59 60 /** Selects the track at {@code index} for reading sample data. */ selectTrack(int index)61 void selectTrack(int index); 62 63 /** Deselects the track at {@code index}, so no more samples will be read from that track. */ deselectTrack(int index)64 void deselectTrack(int index); 65 66 /** 67 * Returns an estimate of the position up to which data is buffered. 68 * 69 * <p>This method should not be called until after the extractor has been successfully prepared. 70 * 71 * @return an estimate of the absolute position in microseconds up to which data is buffered, or 72 * {@link TrackRenderer#END_OF_TRACK_US} if data is buffered to the end of the stream, or 73 * {@link TrackRenderer#UNKNOWN_TIME_US} if no estimate is available. 74 */ getBufferedPositionUs()75 long getBufferedPositionUs(); 76 77 /** 78 * Seeks to the specified time in microseconds. 79 * 80 * <p>This method should not be called until after the extractor has been successfully prepared. 81 * 82 * @param positionUs the seek position in microseconds 83 */ seekTo(long positionUs)84 void seekTo(long positionUs); 85 86 /** Stores the {@link MediaFormat} of {@code track}. */ getTrackMediaFormat(int track, MediaFormatHolder outMediaFormatHolder)87 void getTrackMediaFormat(int track, MediaFormatHolder outMediaFormatHolder); 88 89 /** 90 * Reads the next sample in the track at index {@code track} into {@code sampleHolder}, 91 * returning {@link SampleSource#SAMPLE_READ} if it is available. 92 * 93 * <p>Advances to the next sample if a sample was read. 94 * 95 * @param track the index of the track from which to read a sample 96 * @param sampleHolder the holder for read sample data, if {@link SampleSource#SAMPLE_READ} is 97 * returned 98 * @return {@link SampleSource#SAMPLE_READ} if a sample was read into {@code sampleHolder}, or 99 * {@link SampleSource#END_OF_STREAM} if the last samples in all tracks have been read, or 100 * {@link SampleSource#NOTHING_READ} if the sample cannot be read immediately as it is not 101 * loaded. 102 */ readSample(int track, SampleHolder sampleHolder)103 int readSample(int track, SampleHolder sampleHolder); 104 105 /** Releases resources associated with this extractor. */ release()106 void release(); 107 108 /** Indicates to the source that it should still be buffering data. */ continueBuffering(long positionUs)109 boolean continueBuffering(long positionUs); 110 111 /** 112 * Sets OnCompletionListener for notifying the completion of SampleExtractor. 113 * 114 * @param listener the OnCompletionListener 115 * @param handler the {@link Handler} for {@link Handler#post(Runnable)} of OnCompletionListener 116 */ setOnCompletionListener(OnCompletionListener listener, Handler handler)117 void setOnCompletionListener(OnCompletionListener listener, Handler handler); 118 119 /** The listener for SampleExtractor being completed. */ 120 interface OnCompletionListener { 121 122 /** 123 * Called when sample extraction is completed. 124 * 125 * @param result {@code true} when the extractor is finished without an error, {@code false} 126 * otherwise (storage error, weak signal, being reached at EoS prematurely, etc.) 127 * @param lastExtractedPositionUs the last extracted position when extractor is completed 128 */ onCompletion(boolean result, long lastExtractedPositionUs)129 void onCompletion(boolean result, long lastExtractedPositionUs); 130 } 131 } 132