Documentation
Bitmovin PlatformPlaybackEncodingBitmovin Dashboard

Selection Modes

Introduction

Input files commonly include multiple tracks, such as one or more video tracks, several audio languages, and subtitles. For each stream you add to an encoding, specify which track from the input file should be used.

Track selection is configured using three properties on the input stream:

PropertyDescription
selectionModeDefines the strategy used to select the track. The available modes are described below.
positionA zero-based index. What the index applies to depends on the selected mode.
conditionsOptional rules, such as language == "eng", used to filter or validate tracks depending on the selected mode.

Selection modes at a glance

ModeTrack scopeSelection behaviorRecommended when
AUTOTracks matching the stream typeApplies conditions, then selects by positionSelect the N-th track that matches specific criteria
AUDIO_RELATIVEAudio tracksSelects by position, then validates conditionsSelect the N-th audio track
VIDEO_RELATIVEVideo tracksSelects by position, then validates conditionsSelect the N-th video track
SUBTITLE_RELATIVESubtitle tracksSelects by position, then validates conditionsSelect the N-th subtitle track
POSITION_ABSOLUTEAll tracks in the fileSelects by position, then validates conditionsSelect a track by its exact position in the file

Choosing the right mode

Selection requirementUse
Select the second English audio track. Filter by language, then count matching tracks.AUTO
Select the second audio track in the file, regardless of language or other metadata.AUDIO_RELATIVE
Select the second video track in the file.VIDEO_RELATIVE
Select the second subtitle track in the file.SUBTITLE_RELATIVE
Select a specific track by its exact position in the file, for example track 4.POSITION_ABSOLUTE

AUTO is the best choice for most track selection use cases. It provides condition-based filtering and the most flexible behavior across audio, video, and subtitle streams.

AUTO

AUTO selects tracks in a predictable order:

  1. First, it considers only tracks that match the stream type: audio streams use audio tracks, subtitle streams use subtitle tracks, and video streams use video tracks.
  2. Next, it filters those tracks using the configured conditions.
  3. Finally, it selects the track at the configured position from the filtered list.

When position is omitted, it defaults to 0, selecting the first matching track.

When conditions are omitted, AUTO selects the first track of the matching stream type. In this case, position is ignored.

Example

Assume the input contains the following audio tracks, in order:

Audio indexLanguage
0German
1English
2English
3French

With AUTO, track selection works as follows:

positionconditionsSelected track
0language == "eng"The first English track
1language == "eng"The second English track
omittedlanguage == "eng"The first English track, because position defaults to 0
2omittedGerman, because without conditions, position defaults to 0
omittedomittedGerman, because position defaults to 0

AUDIO_RELATIVE, VIDEO_RELATIVE, SUBTITLE_RELATIVE

These modes select the track at the configured position among tracks of the corresponding type, in the order they appear in the input file.

If conditions are configured, they are used to validate the selected track. If the selected track does not satisfy the conditions, the encoding fails. The conditions do not change which track is selected.

Example

Using the same audio tracks as above: German, English, English, French.

ModepositionconditionsSelected track
AUDIO_RELATIVE0—German
AUDIO_RELATIVE1—The first English track
AUDIO_RELATIVE1language == "deu"Fails because track 1 is English, not German

In the last row, position determines the selected track, and conditions only validate that selection. To select the German track, use position = 0 or use AUTO.

VIDEO_RELATIVEandSUBTITLE_RELATIVE follow the same behavior for video and subtitle tracks.

POSITION_ABSOLUTE

This mode selects tracks by their absolute position in the input file, counting all track types in container order. Use it when the exact track position is known.

Example

Assume the input contains the following tracks, in order:

Absolute indexTrack
0Video
1Audio (English)
2Audio (German)
3Subtitle
positionconditionsSelected track
2—The German audio track
2language == "eng"Fails because track 2 is German

As with the relative modes, conditions validate the selected track. They do not change which track is selected.

Key difference: AUTO vs. AUDIO_RELATIVE

AUTO and AUDIO_RELATIVE use different track selection logic: AUTO applies conditions before position, while AUDIO_RELATIVE applies position before validating conditions.

Using the same audio tracks as above — German, English, English, French — with position = 1 and language == "eng":

ModeResult
AUDIO_RELATIVESelects the first English track. position = 1 selects the second audio track in the file, and conditions validate that it is English.
AUTOSelects the second English track. conditions are applied first, and position = 1 then selects the second matching track.

Guideline:

  • Use a relative mode when selecting a track by position and using conditions only to validate that selection.
  • Use AUTO when selecting the N-th track that matches specific conditions.

When track selection fails

The encoding is rejected if track selection fails. The error identifies the affected stream and the selection mode used.

Track selection fails when:

  • position is outside the available range, for example AUDIO_RELATIVE with position = 3 on an input file with only two audio tracks
  • position is negative
  • No tracks are available for the required stream type, for example an audio stream on a video-only input file
  • For relative modes and POSITION_ABSOLUTE, the selected track does not satisfy the configured conditions

In AUTO, non-matching tracks are skipped rather than causing the selection to fail.

To resolve a selection failure, adjust position, loosen or remove conditions, or use AUTO where filtering by conditions is required.

Updated about 6 hours ago