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.chunk; 17 18 import com.google.android.exoplayer2.C; 19 import com.google.android.exoplayer2.SeekParameters; 20 import java.io.IOException; 21 import java.util.List; 22 23 /** 24 * A provider of {@link Chunk}s for a {@link ChunkSampleStream} to load. 25 */ 26 public interface ChunkSource { 27 28 /** 29 * Adjusts a seek position given the specified {@link SeekParameters}. Chunk boundaries are used 30 * as sync points. 31 * 32 * @param positionUs The seek position in microseconds. 33 * @param seekParameters Parameters that control how the seek is performed. 34 * @return The adjusted seek position, in microseconds. 35 */ getAdjustedSeekPositionUs(long positionUs, SeekParameters seekParameters)36 long getAdjustedSeekPositionUs(long positionUs, SeekParameters seekParameters); 37 38 /** 39 * If the source is currently having difficulty providing chunks, then this method throws the 40 * underlying error. Otherwise does nothing. 41 * <p> 42 * This method should only be called after the source has been prepared. 43 * 44 * @throws IOException The underlying error. 45 */ maybeThrowError()46 void maybeThrowError() throws IOException; 47 48 /** 49 * Evaluates whether {@link MediaChunk}s should be removed from the back of the queue. 50 * <p> 51 * Removing {@link MediaChunk}s from the back of the queue can be useful if they could be replaced 52 * with chunks of a significantly higher quality (e.g. because the available bandwidth has 53 * substantially increased). 54 * 55 * @param playbackPositionUs The current playback position. 56 * @param queue The queue of buffered {@link MediaChunk}s. 57 * @return The preferred queue size. 58 */ getPreferredQueueSize(long playbackPositionUs, List<? extends MediaChunk> queue)59 int getPreferredQueueSize(long playbackPositionUs, List<? extends MediaChunk> queue); 60 61 /** 62 * Returns the next chunk to load. 63 * 64 * <p>If a chunk is available then {@link ChunkHolder#chunk} is set. If the end of the stream has 65 * been reached then {@link ChunkHolder#endOfStream} is set. If a chunk is not available but the 66 * end of the stream has not been reached, the {@link ChunkHolder} is not modified. 67 * 68 * @param playbackPositionUs The current playback position in microseconds. If playback of the 69 * period to which this chunk source belongs has not yet started, the value will be the 70 * starting position in the period minus the duration of any media in previous periods still 71 * to be played. 72 * @param loadPositionUs The current load position in microseconds. If {@code queue} is empty, 73 * this is the starting position from which chunks should be provided. Else it's equal to 74 * {@link MediaChunk#endTimeUs} of the last chunk in the {@code queue}. 75 * @param queue The queue of buffered {@link MediaChunk}s. 76 * @param out A holder to populate. 77 */ getNextChunk( long playbackPositionUs, long loadPositionUs, List<? extends MediaChunk> queue, ChunkHolder out)78 void getNextChunk( 79 long playbackPositionUs, 80 long loadPositionUs, 81 List<? extends MediaChunk> queue, 82 ChunkHolder out); 83 84 /** 85 * Called when the {@link ChunkSampleStream} has finished loading a chunk obtained from this 86 * source. 87 * 88 * <p>This method should only be called when the source is enabled. 89 * 90 * @param chunk The chunk whose load has been completed. 91 */ onChunkLoadCompleted(Chunk chunk)92 void onChunkLoadCompleted(Chunk chunk); 93 94 /** 95 * Called when the {@link ChunkSampleStream} encounters an error loading a chunk obtained from 96 * this source. 97 * 98 * <p>This method should only be called when the source is enabled. 99 * 100 * @param chunk The chunk whose load encountered the error. 101 * @param cancelable Whether the load can be canceled. 102 * @param e The error. 103 * @param blacklistDurationMs The duration for which the associated track may be blacklisted, or 104 * {@link C#TIME_UNSET} if the track may not be blacklisted. 105 * @return Whether the load should be canceled so that a replacement chunk can be loaded instead. 106 * Must be {@code false} if {@code cancelable} is {@code false}. If {@code true}, {@link 107 * #getNextChunk(long, long, List, ChunkHolder)} will be called to obtain the replacement 108 * chunk. 109 */ onChunkLoadError(Chunk chunk, boolean cancelable, Exception e, long blacklistDurationMs)110 boolean onChunkLoadError(Chunk chunk, boolean cancelable, Exception e, long blacklistDurationMs); 111 } 112