selectTrack

suspend fun selectTrack(kind: TrackKind, track: TrackId?): TrackChange

Selects a track, or deselects the kind entirely with a null track, and says what happened.

An audio or subtitle track switches in place, from the packets the player already keeps for every track of those kinds, on any source. So do no video while a sound plays, a VIDEO track that appeared after the open, and one turned off before, because the player keeps the packets of those too. Any other VIDEO track reopens the container and seeks back to where playback was, so that path needs a seekable source. An EXTERNAL subtitle track (a negative TrackId from MediaItem.externalSubtitles) is a cue table and switches in place.

A subtitle the open chose by itself follows the audio. After an audio change it is chosen again by the same rules against the new audio, so a viewer who switches an anime from Japanese to the English dub gets the English signs track made for the dub instead of every line they now hear, and the full track again on switching back. A subtitle selected here, or a file added or flagged to show, is the caller's and stays through every audio change.

Selections of DIFFERENT kinds made close together apply together, and a video change takes the audio or subtitle change waiting beside it into its one reopen. Two requests for the SAME kind cannot both be honoured, and the earlier one returns TrackChange.Superseded rather than the success it used to report. Read the result when it matters; ignore it when your application only ever selects from one place.

Return

TrackChange.Applied when this request is the live selection, TrackChange.Superseded when a later request for the same kind replaced it, and TrackChange.Discarded when a stop, a close or a new open ended it first.

Throws

when the reopen itself failed: the media or the device broke.

when nothing is open.

when track is not a track of kind in the current media.

for a video track switch that reopens, on a source that cannot seek, for turning off the picture or the sound when it is the only one that plays, and for a container subtitle track when the backend decodes no subtitle format.