/*
* 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 androidx.media3.exoplayer.trackselection;
import androidx.annotation.Nullable;
import androidx.media3.common.C;
import androidx.media3.common.Format;
import androidx.media3.common.Timeline;
import androidx.media3.common.TrackGroup;
import androidx.media3.common.TrackSelection;
import androidx.media3.common.util.UnstableApi;
import androidx.media3.exoplayer.source.MediaSource.MediaPeriodId;
import androidx.media3.exoplayer.source.chunk.Chunk;
import androidx.media3.exoplayer.source.chunk.MediaChunk;
import androidx.media3.exoplayer.source.chunk.MediaChunkIterator;
import androidx.media3.exoplayer.upstream.BandwidthMeter;
import java.util.List;
import org.checkerframework.checker.nullness.compatqual.NullableType;
/**
* A {@link TrackSelection} that can change the individually selected track as a result of calling
* {@link #updateSelectedTrack(long, long, long, List, MediaChunkIterator[])} or {@link
* #evaluateQueueSize(long, List)}. This only happens between calls to {@link #enable()} and {@link
* #disable()}.
*/
@UnstableApi
public interface ExoTrackSelection extends TrackSelection {
/** Contains of a subset of selected tracks belonging to a {@link TrackGroup}. */
final class Definition {
/** The {@link TrackGroup} which tracks belong to. */
public final TrackGroup group;
/** The indices of the selected tracks in {@link #group}. */
public final int[] tracks;
/** The type that will be returned from {@link TrackSelection#getType()}. */
public final @Type int type;
/**
* @param group The {@link TrackGroup}. Must not be null.
* @param tracks The indices of the selected tracks within the {@link TrackGroup}. Must not be
* null or empty. May be in any order.
*/
public Definition(TrackGroup group, int... tracks) {
this(group, tracks, TrackSelection.TYPE_UNSET);
}
/**
* @param group The {@link TrackGroup}. Must not be null.
* @param tracks The indices of the selected tracks within the {@link TrackGroup}. Must not be
* null or empty. May be in any order.
* @param type The type that will be returned from {@link TrackSelection#getType()}.
*/
public Definition(TrackGroup group, int[] tracks, @Type int type) {
this.group = group;
this.tracks = tracks;
this.type = type;
}
}
/** Factory for {@link ExoTrackSelection} instances. */
interface Factory {
/**
* Creates track selections for the provided {@link Definition Definitions}.
*
* <p>Implementations that create at most one adaptive track selection may use {@link
* TrackSelectionUtil#createTrackSelectionsForDefinitions}.
*
* @param definitions A {@link Definition} array. May include null values.
* @param bandwidthMeter A {@link BandwidthMeter} which can be used to select tracks.
* @param mediaPeriodId 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 The created selections. Must have the same length as {@code definitions} and may
* include null values.
*/
@NullableType
ExoTrackSelection[] createTrackSelections(
@NullableType Definition[] definitions,
BandwidthMeter bandwidthMeter,
MediaPeriodId mediaPeriodId,
Timeline timeline);
}
/**
* Enables the track selection. Dynamic changes via {@link #updateSelectedTrack(long, long, long,
* List, MediaChunkIterator[])}, {@link #evaluateQueueSize(long, List)} or {@link
* #shouldCancelChunkLoad(long, Chunk, List)} will only happen after this call.
*
* <p>This method may not be called when the track selection is already enabled.
*/
void enable();
/**
* Disables this track selection. No further dynamic changes via {@link #updateSelectedTrack(long,
* long, long, List, MediaChunkIterator[])}, {@link #evaluateQueueSize(long, List)} or {@link
* #shouldCancelChunkLoad(long, Chunk, List)} will happen after this call.
*
* <p>This method may only be called when the track selection is already enabled.
*/
void disable();
// Individual selected track.
/** Returns the {@link Format} of the individual selected track. */
Format getSelectedFormat();
/** Returns the index in the track group of the individual selected track. */
int getSelectedIndexInTrackGroup();
/** Returns the index of the selected track. */
int getSelectedIndex();
/** Returns the reason for the current track selection. */
int getSelectionReason();
/** Returns optional data associated with the current track selection. */
@Nullable
Object getSelectionData();
// Adaptation.
/**
* Called to notify the selection of the current playback speed. The playback speed may affect
* adaptive track selection.
*
* @param playbackSpeed The factor by which playback is sped up.
*/
void onPlaybackSpeed(float playbackSpeed);
/**
* Called to notify the selection of a position discontinuity.
*
* <p>This happens when the playback position jumps, e.g., as a result of a seek being performed.
*/
default void onDiscontinuity() {}
/**
* Called to notify when a rebuffer occurred.
*
* <p>A rebuffer is defined to be caused by buffer depletion rather than a user action. Hence this
* method is not called during initial buffering or when buffering as a result of a seek
* operation.
*/
default void onRebuffer() {}
/**
* Called to notify when the playback is paused or resumed.
*
* @param playWhenReady Whether playback will proceed when ready.
*/
default void onPlayWhenReadyChanged(boolean playWhenReady) {}
/**
* Updates the selected track for sources that load media in discrete {@link MediaChunk}s.
*
* <p>This method will only be called when the selection is enabled.
*
* @param playbackPositionUs The current playback position in microseconds. If playback of the
* period to which this track selection belongs has not yet started, the value will be the
* starting position in the period minus the duration of any media in previous periods still
* to be played.
* @param bufferedDurationUs The duration of media currently buffered from the current playback
* position, in microseconds. Note that the next load position can be calculated as {@code
* (playbackPositionUs + bufferedDurationUs)}.
* @param availableDurationUs The duration of media available for buffering from the current
* playback position, in microseconds, or {@link C#TIME_UNSET} if media can be buffered to the
* end of the current period. Note that if not set to {@link C#TIME_UNSET}, the position up to
* which media is available for buffering can be calculated as {@code (playbackPositionUs +
* availableDurationUs)}.
* @param queue The queue of already buffered {@link MediaChunk}s. Must not be modified.
* @param mediaChunkIterators An array of {@link MediaChunkIterator}s providing information about
* the sequence of upcoming media chunks for each track in the selection. All iterators start
* from the media chunk which will be loaded next if the respective track is selected. Note
* that this information may not be available for all tracks, and so some iterators may be
* empty.
*/
void updateSelectedTrack(
long playbackPositionUs,
long bufferedDurationUs,
long availableDurationUs,
List<? extends MediaChunk> queue,
MediaChunkIterator[] mediaChunkIterators);
/**
* Returns the number of chunks that should be retained in the queue.
*
* <p>May be called by sources that load media in discrete {@link MediaChunk MediaChunks} and
* support discarding of buffered chunks.
*
* <p>To avoid excessive re-buffering, implementations should normally return the size of the
* queue. An example of a case where a smaller value may be returned is if network conditions have
* improved dramatically, allowing chunks to be discarded and re-buffered in a track of
* significantly higher quality. Discarding chunks may allow faster switching to a higher quality
* track in this case.
*
* <p>Note that even if the source supports discarding of buffered chunks, the actual number of
* discarded chunks is not guaranteed. The source will call {@link #updateSelectedTrack(long,
* long, long, List, MediaChunkIterator[])} with the updated queue of chunks before loading a new
* chunk to allow switching to another quality.
*
* <p>This method will only be called when the selection is enabled and none of the {@link
* MediaChunk MediaChunks} in the queue are currently loading.
*
* @param playbackPositionUs The current playback position in microseconds. If playback of the
* period to which this track selection belongs has not yet started, the value will be the
* starting position in the period minus the duration of any media in previous periods still
* to be played.
* @param queue The queue of buffered {@link MediaChunk MediaChunks}. Must not be modified.
* @return The number of chunks to retain in the queue.
*/
int evaluateQueueSize(long playbackPositionUs, List<? extends MediaChunk> queue);
/**
* Returns whether an ongoing load of a chunk should be canceled.
*
* <p>May be called by sources that load media in discrete {@link MediaChunk MediaChunks} and
* support canceling the ongoing chunk load. The ongoing chunk load is either the last {@link
* MediaChunk} in the queue or another type of {@link Chunk}, for example, if the source loads
* initialization or encryption data.
*
* <p>To avoid excessive re-buffering, implementations should normally return {@code false}. An
* example where {@code true} might be returned is if a load of a high quality chunk gets stuck
* and canceling this load in favor of a lower quality alternative may avoid a rebuffer.
*
* <p>The source will call {@link #evaluateQueueSize(long, List)} after the cancelation finishes
* to allow discarding of chunks, and {@link #updateSelectedTrack(long, long, long, List,
* MediaChunkIterator[])} before loading a new chunk to allow switching to another quality.
*
* <p>This method will only be called when the selection is enabled.
*
* @param playbackPositionUs The current playback position in microseconds. If playback of the
* period to which this track selection belongs has not yet started, the value will be the
* starting position in the period minus the duration of any media in previous periods still
* to be played.
* @param loadingChunk The currently loading {@link Chunk} that will be canceled if this method
* returns {@code true}.
* @param queue The queue of buffered {@link MediaChunk MediaChunks}, including the {@code
* loadingChunk} if it's a {@link MediaChunk}. Must not be modified.
* @return Whether the ongoing load of {@code loadingChunk} should be canceled.
*/
default boolean shouldCancelChunkLoad(
long playbackPositionUs, Chunk loadingChunk, List<? extends MediaChunk> queue) {
return false;
}
/**
* Attempts to exclude the track at the specified index in the selection, making it ineligible for
* selection by calls to {@link #updateSelectedTrack(long, long, long, List,
* MediaChunkIterator[])} for the specified period of time.
*
* <p>Exclusion will fail if all other tracks are currently excluded. If excluding the currently
* selected track, note that it will remain selected until the next call to {@link
* #updateSelectedTrack(long, long, long, List, MediaChunkIterator[])}.
*
* <p>This method will only be called when the selection is enabled.
*
* @param index The index of the track in the selection.
* @param exclusionDurationMs The duration of time for which the track should be excluded, in
* milliseconds.
* @return Whether exclusion was successful.
*/
boolean blacklist(int index, long exclusionDurationMs);
/**
* Returns whether the track at the specified index in the selection is excluded.
*
* @param index The index of the track in the selection.
* @param nowMs The current time in the timebase of {@link
* android.os.SystemClock#elapsedRealtime()}.
*/
boolean isBlacklisted(int index, long nowMs);
}