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.trackselection; 17 18 import androidx.annotation.Nullable; 19 import com.google.android.exoplayer2.ExoPlaybackException; 20 import com.google.android.exoplayer2.ExoPlayer; 21 import com.google.android.exoplayer2.Renderer; 22 import com.google.android.exoplayer2.RendererCapabilities; 23 import com.google.android.exoplayer2.RendererConfiguration; 24 import com.google.android.exoplayer2.Timeline; 25 import com.google.android.exoplayer2.source.MediaSource.MediaPeriodId; 26 import com.google.android.exoplayer2.source.TrackGroupArray; 27 import com.google.android.exoplayer2.upstream.BandwidthMeter; 28 import com.google.android.exoplayer2.util.Assertions; 29 30 /** 31 * The component of an {@link ExoPlayer} responsible for selecting tracks to be consumed by each of 32 * the player's {@link Renderer}s. The {@link DefaultTrackSelector} implementation should be 33 * suitable for most use cases. 34 * 35 * <h3>Interactions with the player</h3> 36 * 37 * The following interactions occur between the player and its track selector during playback. 38 * 39 * <ul> 40 * <li>When the player is created it will initialize the track selector by calling {@link 41 * #init(InvalidationListener, BandwidthMeter)}. 42 * <li>When the player needs to make a track selection it will call {@link 43 * #selectTracks(RendererCapabilities[], TrackGroupArray, MediaPeriodId, Timeline)}. This 44 * typically occurs at the start of playback, when the player starts to buffer a new period of 45 * the media being played, and when the track selector invalidates its previous selections. 46 * <li>The player may perform a track selection well in advance of the selected tracks becoming 47 * active, where active is defined to mean that the renderers are actually consuming media 48 * corresponding to the selection that was made. For example when playing media containing 49 * multiple periods, the track selection for a period is made when the player starts to buffer 50 * that period. Hence if the player's buffering policy is to maintain a 30 second buffer, the 51 * selection will occur approximately 30 seconds in advance of it becoming active. In fact the 52 * selection may never become active, for example if the user seeks to some other period of 53 * the media during the 30 second gap. The player indicates to the track selector when a 54 * selection it has previously made becomes active by calling {@link 55 * #onSelectionActivated(Object)}. 56 * <li>If the track selector wishes to indicate to the player that selections it has previously 57 * made are invalid, it can do so by calling {@link 58 * InvalidationListener#onTrackSelectionsInvalidated()} on the {@link InvalidationListener} 59 * that was passed to {@link #init(InvalidationListener, BandwidthMeter)}. A track selector 60 * may wish to do this if its configuration has changed, for example if it now wishes to 61 * prefer audio tracks in a particular language. This will trigger the player to make new 62 * track selections. Note that the player will have to re-buffer in the case that the new 63 * track selection for the currently playing period differs from the one that was invalidated. 64 * </ul> 65 * 66 * <h3>Renderer configuration</h3> 67 * 68 * The {@link TrackSelectorResult} returned by {@link #selectTracks(RendererCapabilities[], 69 * TrackGroupArray, MediaPeriodId, Timeline)} contains not only {@link TrackSelection}s for each 70 * renderer, but also {@link RendererConfiguration}s defining configuration parameters that the 71 * renderers should apply when consuming the corresponding media. Whilst it may seem counter- 72 * intuitive for a track selector to also specify renderer configuration information, in practice 73 * the two are tightly bound together. It may only be possible to play a certain combination tracks 74 * if the renderers are configured in a particular way. Equally, it may only be possible to 75 * configure renderers in a particular way if certain tracks are selected. Hence it makes sense to 76 * determine the track selection and corresponding renderer configurations in a single step. 77 * 78 * <h3>Threading model</h3> 79 * 80 * All calls made by the player into the track selector are on the player's internal playback 81 * thread. The track selector may call {@link InvalidationListener#onTrackSelectionsInvalidated()} 82 * from any thread. 83 */ 84 public abstract class TrackSelector { 85 86 /** 87 * Notified when selections previously made by a {@link TrackSelector} are no longer valid. 88 */ 89 public interface InvalidationListener { 90 91 /** 92 * Called by a {@link TrackSelector} to indicate that selections it has previously made are no 93 * longer valid. May be called from any thread. 94 */ onTrackSelectionsInvalidated()95 void onTrackSelectionsInvalidated(); 96 97 } 98 99 @Nullable private InvalidationListener listener; 100 @Nullable private BandwidthMeter bandwidthMeter; 101 102 /** 103 * Called by the player to initialize the selector. 104 * 105 * @param listener An invalidation listener that the selector can call to indicate that selections 106 * it has previously made are no longer valid. 107 * @param bandwidthMeter A bandwidth meter which can be used by track selections to select tracks. 108 */ init(InvalidationListener listener, BandwidthMeter bandwidthMeter)109 public final void init(InvalidationListener listener, BandwidthMeter bandwidthMeter) { 110 this.listener = listener; 111 this.bandwidthMeter = bandwidthMeter; 112 } 113 114 /** 115 * Called by the player to perform a track selection. 116 * 117 * @param rendererCapabilities The {@link RendererCapabilities} of the renderers for which tracks 118 * are to be selected. 119 * @param trackGroups The available track groups. 120 * @param periodId The {@link MediaPeriodId} of the period for which tracks are to be selected. 121 * @param timeline The {@link Timeline} holding the period for which tracks are to be selected. 122 * @return A {@link TrackSelectorResult} describing the track selections. 123 * @throws ExoPlaybackException If an error occurs selecting tracks. 124 */ selectTracks( RendererCapabilities[] rendererCapabilities, TrackGroupArray trackGroups, MediaPeriodId periodId, Timeline timeline)125 public abstract TrackSelectorResult selectTracks( 126 RendererCapabilities[] rendererCapabilities, 127 TrackGroupArray trackGroups, 128 MediaPeriodId periodId, 129 Timeline timeline) 130 throws ExoPlaybackException; 131 132 /** 133 * Called by the player when a {@link TrackSelectorResult} previously generated by {@link 134 * #selectTracks(RendererCapabilities[], TrackGroupArray, MediaPeriodId, Timeline)} is activated. 135 * 136 * @param info The value of {@link TrackSelectorResult#info} in the activated selection. 137 */ onSelectionActivated(Object info)138 public abstract void onSelectionActivated(Object info); 139 140 /** 141 * Calls {@link InvalidationListener#onTrackSelectionsInvalidated()} to invalidate all previously 142 * generated track selections. 143 */ invalidate()144 protected final void invalidate() { 145 if (listener != null) { 146 listener.onTrackSelectionsInvalidated(); 147 } 148 } 149 150 /** 151 * Returns a bandwidth meter which can be used by track selections to select tracks. Must only be 152 * called after {@link #init(InvalidationListener, BandwidthMeter)} has been called. 153 */ getBandwidthMeter()154 protected final BandwidthMeter getBandwidthMeter() { 155 return Assertions.checkNotNull(bandwidthMeter); 156 } 157 } 158