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; 17 18 import com.google.android.exoplayer2.source.TrackGroup; 19 import com.google.android.exoplayer2.source.TrackGroupArray; 20 import com.google.android.exoplayer2.trackselection.TrackSelectionArray; 21 import com.google.android.exoplayer2.upstream.Allocator; 22 23 /** 24 * Controls buffering of media. 25 */ 26 public interface LoadControl { 27 28 /** 29 * Called by the player when prepared with a new source. 30 */ onPrepared()31 void onPrepared(); 32 33 /** 34 * Called by the player when a track selection occurs. 35 * 36 * @param renderers The renderers. 37 * @param trackGroups The {@link TrackGroup}s from which the selection was made. 38 * @param trackSelections The track selections that were made. 39 */ onTracksSelected(Renderer[] renderers, TrackGroupArray trackGroups, TrackSelectionArray trackSelections)40 void onTracksSelected(Renderer[] renderers, TrackGroupArray trackGroups, 41 TrackSelectionArray trackSelections); 42 43 /** 44 * Called by the player when stopped. 45 */ onStopped()46 void onStopped(); 47 48 /** 49 * Called by the player when released. 50 */ onReleased()51 void onReleased(); 52 53 /** 54 * Returns the {@link Allocator} that should be used to obtain media buffer allocations. 55 */ getAllocator()56 Allocator getAllocator(); 57 58 /** 59 * Returns the duration of media to retain in the buffer prior to the current playback position, 60 * for fast backward seeking. 61 * <p> 62 * Note: If {@link #retainBackBufferFromKeyframe()} is false then seeking in the back-buffer will 63 * only be fast if the back-buffer contains a keyframe prior to the seek position. 64 * <p> 65 * Note: Implementations should return a single value. Dynamic changes to the back-buffer are not 66 * currently supported. 67 * 68 * @return The duration of media to retain in the buffer prior to the current playback position, 69 * in microseconds. 70 */ getBackBufferDurationUs()71 long getBackBufferDurationUs(); 72 73 /** 74 * Returns whether media should be retained from the keyframe before the current playback position 75 * minus {@link #getBackBufferDurationUs()}, rather than any sample before or at that position. 76 * <p> 77 * Warning: Returning true will cause the back-buffer size to depend on the spacing of keyframes 78 * in the media being played. Returning true is not recommended unless you control the media and 79 * are comfortable with the back-buffer size exceeding {@link #getBackBufferDurationUs()} by as 80 * much as the maximum duration between adjacent keyframes in the media. 81 * <p> 82 * Note: Implementations should return a single value. Dynamic changes to the back-buffer are not 83 * currently supported. 84 * 85 * @return Whether media should be retained from the keyframe before the current playback position 86 * minus {@link #getBackBufferDurationUs()}, rather than any sample before or at that position. 87 */ retainBackBufferFromKeyframe()88 boolean retainBackBufferFromKeyframe(); 89 90 /** 91 * Called by the player to determine whether it should continue to load the source. 92 * 93 * @param playbackPositionUs The current playback position in microseconds, relative to the start 94 * of the {@link Timeline.Period period} that will continue to be loaded if this method 95 * returns {@code true}. If playback of this period has not yet started, the value will be 96 * negative and equal in magnitude to the duration of any media in previous periods still to 97 * be played. 98 * @param bufferedDurationUs The duration of media that's currently buffered. 99 * @param playbackSpeed The current playback speed. 100 * @return Whether the loading should continue. 101 */ shouldContinueLoading( long playbackPositionUs, long bufferedDurationUs, float playbackSpeed)102 boolean shouldContinueLoading( 103 long playbackPositionUs, long bufferedDurationUs, float playbackSpeed); 104 105 /** 106 * Called repeatedly by the player when it's loading the source, has yet to start playback, and 107 * has the minimum amount of data necessary for playback to be started. The value returned 108 * determines whether playback is actually started. The load control may opt to return {@code 109 * false} until some condition has been met (e.g. a certain amount of media is buffered). 110 * 111 * @param bufferedDurationUs The duration of media that's currently buffered. 112 * @param playbackSpeed The current playback speed. 113 * @param rebuffering Whether the player is rebuffering. A rebuffer is defined to be caused by 114 * buffer depletion rather than a user action. Hence this parameter is false during initial 115 * buffering and when buffering as a result of a seek operation. 116 * @return Whether playback should be allowed to start or resume. 117 */ shouldStartPlayback(long bufferedDurationUs, float playbackSpeed, boolean rebuffering)118 boolean shouldStartPlayback(long bufferedDurationUs, float playbackSpeed, boolean rebuffering); 119 } 120