API enhancements for audio (and subtitle) track selection

[robwalch]

Is your feature request related to a problem? Please describe.

Select audio track by language and/or features such as number of channels or description

Describe the solution you'd like

• Provide fields such as language, channels, and characteristics
• Provide audio and subtitle rendition groups which can each contain a set of tracks, groups and corresponding levels
• Limit level selection based on active renditions
• Provide rendition selection API that can handle complex level and track selection HLS Manifest with multi audio is not supported by player #5302

Additional context

#5704 Added hls.allAudioTracks and hls.allSubtitleTracks getters. These are not directly selectable, but list all MVP media options. The rendition groups will be a list of options that share the same attributes with the exception of those described in HLS Spec section 4.4.6.1.1 Rendition Groups.

Proposed solution

Two new new config options and methods will allow (pre) selection of audio and subtitles, implicitly by providing one ore more attributes for which a match must be found, or explicitly, using the methods, by passing in a MediaPlaylist instance (one of hls.allAudioTracks or hls.allSubtitleTracks).

export type AudioSelectionOption = {
  lang?: string;
  characteristics?: string;
  channels?: string;
  name?: string;
  audioCodec?: string;
  groupId?: string;
};

export type SubtitleSelectionOption = {
  lang?: string;
  characteristics?: string;
  name?: string;
  groupId?: string;
};

/**
 * Find and select the best matching audio track, making a level switch when a Group change is necessary.
 * Returns the selected track, or null when no matching track could be found.
 */
setAudioOption(audioOption: MediaPlaylist | AudioSelectionOption): MediaPlaylist | null {}
/**
 * Find and select the best matching subtitle track, making a level switch when a Group change is necessary.
 * Returns the selected track, or null when no matching track could be found.
 */
setSubtitleOption(audioOption: MediaPlaylist | SubtitleSelectionOption): MediaPlaylist | null {}

// New config options
export type SelectionPreferences = {
  audioPreference: AudioSelectionOption,
  subtitlePreference: SubtitleSelectionOption
};

Already added in dev (v1.5.0):

  /**
   * Get the complete list of audio tracks across all media groups
   */
  get allAudioTracks(): Array<MediaPlaylist> {}

  /**
   * get the complete list of subtitle tracks across all media groups
   */
  get allSubtitleTracks(): Array<MediaPlaylist> {}

Matching options:

First look for a matching option in the active group. If one is found, select the track and return it.

Otherwise, look for a matching option across all options and groups. As a level change is required, select the match and level that best matches the current codec set, bitrate, and channel count for audio.

If no match is found, log a warning including the provided input, and return null.

For the config options, matching will be performed on start, overriding the default AUTOSELECT/FORCED behavior, and potentially overriding the initial selection criterial for audioCodec and channels in abr-controller.

TBD: calling the setter methods successfully may update corresponding config option values. Either this, or another player instance specific value may be needed to coordinate changes on level switch.

Switching:
Generally, tracks a flushed on manual selection. Taking special care to smooth switch on changes of the same language and characteristics is a point for further enhancement.