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