[DRAFT] API enhancements for audio and subtitle track selection

Resolves #5532

api-extractor/report/hls.js.api.md

@@ -1625,6 +1625,10 @@ class Hls implements HlsEventEmitter {
     // (undocumented)
     removeLevel(levelIndex: any, urlId?: number): void;
     resumeBuffering(): void;
+    // Warning: (ae-forgotten-export) The symbol "AudioSelectionOption" needs to be exported by the entry point hls.d.ts
+    setAudioOption(audioOption: MediaPlaylist | AudioSelectionOption): MediaPlaylist | null;
+    // Warning: (ae-forgotten-export) The symbol "SubtitleSelectionOption" needs to be exported by the entry point hls.d.ts
+    setSubtitleOption(audioOption: MediaPlaylist | SubtitleSelectionOption): MediaPlaylist | null;
     get startLevel(): number;
     // Warning: (ae-setter-with-docs) The doc comment for the property "startLevel" must appear on the getter, not the setter.
     set startLevel(newLevel: number);
@@ -1657,6 +1661,7 @@ export interface HlsChunkPerformanceTiming extends HlsPerformanceTiming {
     executeStart: number;
 }
 
+// Warning: (ae-forgotten-export) The symbol "SelectionPreferences" needs to be exported by the entry point hls.d.ts
 // Warning: (ae-missing-release-tag) "HlsConfig" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
@@ -1692,7 +1697,7 @@ export type HlsConfig = {
     fpsController: typeof FPSController;
     progressive: boolean;
     lowLatencyMode: boolean;
-} & ABRControllerConfig & BufferControllerConfig & CapLevelControllerConfig & EMEControllerConfig & FPSControllerConfig & LevelControllerConfig & MP4RemuxerConfig & StreamControllerConfig & LatencyControllerConfig & MetadataControllerConfig & TimelineControllerConfig & TSDemuxerConfig & HlsLoadPolicies & FragmentLoaderConfig & PlaylistLoaderConfig;
+} & ABRControllerConfig & BufferControllerConfig & CapLevelControllerConfig & EMEControllerConfig & FPSControllerConfig & LevelControllerConfig & MP4RemuxerConfig & StreamControllerConfig & SelectionPreferences & LatencyControllerConfig & MetadataControllerConfig & TimelineControllerConfig & TSDemuxerConfig & HlsLoadPolicies & FragmentLoaderConfig & PlaylistLoaderConfig;
 
 // Warning: (ae-missing-release-tag) "HlsEventEmitter" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //

src/config.ts

@@ -29,6 +29,10 @@ import type {
   LoaderResponse,
   PlaylistLoaderContext,
 } from './types/loader';
+import type {
+  AudioSelectionOption,
+  SubtitleSelectionOption,
+} from './types/media-playlist';
 
 export type ABRControllerConfig = {
   abrEwmaFastLive: number;
@@ -217,6 +221,11 @@ export type StreamControllerConfig = {
   testBandwidth: boolean;
 };
 
+export type SelectionPreferences = {
+  audioPreference?: AudioSelectionOption;
+  subtitlePreference?: SubtitleSelectionOption;
+};
+
 export type LatencyControllerConfig = {
   liveSyncDurationCount: number;
   liveMaxLatencyDurationCount: number;
@@ -298,6 +307,7 @@ export type HlsConfig = {
   LevelControllerConfig &
   MP4RemuxerConfig &
   StreamControllerConfig &
+  SelectionPreferences &
   LatencyControllerConfig &
   MetadataControllerConfig &
   TimelineControllerConfig &

src/hls.ts

@@ -22,7 +22,11 @@ import type CMCDController from './controller/cmcd-controller';
 import type EMEController from './controller/eme-controller';
 import type SubtitleTrackController from './controller/subtitle-track-controller';
 import type { ComponentAPI, NetworkComponentAPI } from './types/component-api';
-import type { MediaPlaylist } from './types/media-playlist';
+import type {
+  AudioSelectionOption,
+  MediaPlaylist,
+  SubtitleSelectionOption,
+} from './types/media-playlist';
 import type { HlsConfig } from './config';
 import type { BufferInfo } from './utils/buffer-helper';
 import type AudioStreamController from './controller/audio-stream-controller';
@@ -771,6 +775,25 @@ export default class Hls implements HlsEventEmitter {
     return this.streamController.getMainFwdBufferInfo();
   }
 
+  /**
+   * 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.
+   */
+  public setAudioOption(
+    audioOption: MediaPlaylist | AudioSelectionOption,
+  ): MediaPlaylist | null {
+    return 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.
+   */
+  public setSubtitleOption(
+    audioOption: MediaPlaylist | SubtitleSelectionOption,
+  ): MediaPlaylist | null {
+    return null;
+  }
+
   /**
    * Get the complete list of audio tracks across all media groups
    */

src/types/media-playlist.ts

@@ -13,6 +13,22 @@ export type SubtitlePlaylistType = 'SUBTITLES' | 'CLOSED-CAPTIONS';
 
 export type MediaPlaylistType = MainPlaylistType | SubtitlePlaylistType;
 
+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;
+};
+
 // audioTracks, captions and subtitles returned by `M3U8Parser.parseMasterPlaylistMedia`
 export interface MediaPlaylist extends Omit<LevelParsed, 'attrs'> {
   attrs: MediaAttributes;