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