@amazon/vinyl 2.0.0 → 3.0.0

package/dist/types/ts3.7/vinyl/VinylOptions.d.ts

@@ -3,7 +3,8 @@ import { ObjectSchema } from '@amazon/vinyl-validation';
 import { CodecOverrides } from '../util/media/codecOverrides';
 import { RestrictableContentType } from '../streaming/MediaQualityMetadata';
 import { LoudnessNormalizationControllerImplOptions } from '../playback/loudness/LoudnessNormalizationControllerImplOptions';
-import { VttCueStyle } from '../text/VttCueStyle';
+import { TextTrackControllerOptions } from '../text/TextTrack';
+import { AudioOptions } from '../streaming/AudioOptions';
 export interface VinylOptions {
     /**
      * Configuration for the default adaptive bitrate selector.
@@ -11,40 +12,16 @@ export interface VinylOptions {
     readonly abr: QualitySelectorImplOptions;
     readonly loudnessNormalization: LoudnessNormalizationControllerImplOptions;
     /**
-     * Preferred language(s) for audio content, as RFC 5646 codes (e.g. `'en'`,
-     * `'ja'`, `'fr-CA'`). May be a single tag or an ordered list of tags —
-     * earlier entries are preferred, with the best relatedness match kept for
-     * each period (audio without a language tag is always kept). `null` (the
-     * default) is NOT "no preference": it orders by the platform's
-     * `navigator.languages`. To keep every language, this option is not the
-     * mechanism — omit language content or pass a tag matching all.
-     */
-    readonly preferredAudioLanguage: string | readonly string[] | null;
-    /**
-     * Preferred language(s) for text tracks (subtitles / closed captions), as
-     * RFC 5646 codes (e.g. `'en'`, `'ja'`, `'fr-CA'`). May be a single tag or
-     * an ordered list of tags — earlier entries are preferred, with the best
-     * relatedness match chosen among the discovered text tracks. When set, the
-     * matching text track is selected automatically and the choice carries
-     * across track changes (e.g. across an ad break), mirroring how
-     * {@link preferredAudioLanguage} drives audio selection.
+     * Audio (language / audio-description) configuration. See
+     * {@link AudioOptions}.
      *
-     * Unlike audio, `null` (the default) means *no caption preference*: it does
-     * NOT fall back to `navigator.languages` and does NOT force captions on —
-     * forced narrative subtitles still auto-display as usual. Setting it to a
-     * language turns captions on in that language; setting it back to `null`
-     * after a prior selection turns captions off.
-     */
-    readonly preferredTextLanguage: string | readonly string[] | null;
-    /**
-     * Opt in to audio-description (a.k.a. described-video / DVS) audio: audio
-     * renditions carrying an accessibility "describes video" characteristic that
-     * narrate on-screen action. `false` (the default) keeps them out of the
-     * automatic default-audio selection — they are chosen only when this is set.
-     * When `true`, a description rendition is preferred where one exists for the
-     * selected language. Changing this reselects audio immediately.
+     * The default is `{ selection: { language: null, descriptive: false } }`:
+     * audio is ordered by the platform's `navigator.languages` and
+     * audio-description renditions are excluded. Set `selection.language` to
+     * prefer specific language(s) and `selection.descriptive` to `true` to opt
+     * into described audio.
      */
-    readonly preferDescriptiveAudio: boolean;
+    readonly audio: AudioOptions;
     /**
      * Explicit codec allow/deny overrides that bypass browser support
      * detection. Keys are RFC 6381 codec strings or prefixes (e.g. `"hvc1"`),
@@ -68,15 +45,16 @@ export interface VinylOptions {
      */
     readonly allowedContentTypes: readonly RestrictableContentType[] | null;
     /**
-     * Layout style applied to rendered WebVTT cues (the settable `VTTCue`
-     * positioning properties: size, line, position, align, etc.). Applied to
-     * each cue as it is added, on platforms that support `VTTCue`.
+     * Text-track (subtitles / closed captions) configuration: enable/disable
+     * and the selection criteria. See {@link TextTrackControllerOptions}.
      *
-     * Defaults to `{ size: 90 }`, insetting the cue box from the full video
-     * width so long lines don't clip at the screen edges in fullscreen (which
-     * `::cue` CSS cannot fix). Set to `null` to keep the browser defaults.
+     * The default is `{ enabled: 'forced' }`: with no
+     * explicit language, the platform's `navigator.languages` are preferred,
+     * showing only forced (narrative) tracks. Set `enabled` to `'on'` for full
+     * subtitle tracks or `'off'` to render nothing;
+     * `selection.language`/`selection.id` choose a specific rendition.
      */
-    readonly textCueStyle: VttCueStyle | null;
+    readonly text: TextTrackControllerOptions;
 }
 export declare const defaultVinylOptions: VinylOptions;
 export declare const vinylOptionsValidator: ObjectSchema<VinylOptions>;

package/dist/types/ts3.7/vinyl/VinylPlayer.d.ts

@@ -156,12 +156,6 @@ export declare class VinylPlayer<TrackLoadOptionsType extends TrackLoadOptions =
     getPlaybackQuality(contentType: ContentType): MediaQualityMetadata | null;
     get textTracks(): readonly TextTrackInfo[];
     get activeTextTrack(): (TextTrackInfo | null);
-    /**
-     * Selects the text track with the given id, or clears the active text
-     * track when called with null. No-op when the current track does not
-     * surface text tracks or the id is unknown.
-     */
-    setActiveTextTrack(id: string | null): void;
     private emitTextTrackChangeEventsFor;
     get currentTrackAds(): (TrackAds | null);
     get currentAdBreak(): (AdBreakInfo | null);

package/dist/types/ts3.7/vinyl/createVinylFactories.d.ts

@@ -12,6 +12,8 @@ import { TrackControllerImpl } from '../track/TrackController';
 import { VinylPatchOptions } from './VinylPatchOptions';
 import { QualitySelectorImplOptions } from '../streaming/abr/QualitySelectorImpl';
 import { AdControllerImpl, AdControllerImplDeps, AdControllerImplOptions } from '../ad/AdControllerImpl';
+import { MediaTextTrackProvider } from '../text/mediaTextTrackProvider';
+import { TextTrackRenderer } from '../text/TextTrackRenderer';
 import { DrmOptions } from '../drm/DrmOptions';
 import { commonEmeFactory } from '../drm/commonEme/CommonEmeFactory';
 import { DrmControllerImpl, DrmControllerImplDeps } from '../drm/DrmControllerImpl';
@@ -33,6 +35,12 @@ export interface VinylDependencyOptions {
      * The media element.
      */
     readonly media: HTMLMediaElement;
+    /**
+     * Optional renderer for text-track cues (an HTML overlay). When provided,
+     * captions are painted by the renderer and the DOM text track is kept
+     * `'hidden'`; without one they render natively. See `TextTrackRenderer`.
+     */
+    readonly textTrackRenderer?: TextTrackRenderer;
     /**
      * Flags for patches that should be applied browser-specifically.
      * These will be defaulted based on the user-agent.
@@ -80,6 +88,10 @@ export declare function createVinylFactories(options: VinylDependencyOptions): {
             readonly patched: HTMLMediaElement;
         };
     }) => HTMLMediaElement;
+    textTrackProvider: (deps: {
+        readonly media: HTMLMediaElement;
+    }) => MediaTextTrackProvider;
+    textTrackRenderer: () => TextTrackRenderer | null;
     playbackController: (deps: PlaybackControllerImplDeps) => PlaybackControllerImpl;
     playbackSource: (deps: PlaybackSourceImplDeps) => PlaybackSourceImpl;
     loudnessNormalizationController: (deps: {
@@ -120,15 +132,12 @@ export declare function createVinylFactories(options: VinylDependencyOptions): {
         qualitySelector: (deps: {
             options: ObservableValue<Pick<VinylOptions, "abr">>;
         }) => import("..").QualitySelectorImpl;
-        preferredAudioLanguage: (deps: {
-            options: ObservableValue<Pick<VinylOptions, "preferredAudioLanguage">>;
-        }) => ObservableValue<string | readonly string[] | null>;
+        audio: (deps: {
+            options: ObservableValue<Pick<VinylOptions, "audio">>;
+        }) => ObservableValue<import("..").AudioOptions>;
         allowedContentTypes: (deps: {
             options: ObservableValue<Pick<VinylOptions, "allowedContentTypes">>;
         }) => ObservableValue<readonly import("..").RestrictableContentType[] | null>;
-        preferDescriptiveAudio: (deps: {
-            options: ObservableValue<Pick<VinylOptions, "preferDescriptiveAudio">>;
-        }) => ObservableValue<boolean>;
         abr: (deps: {
             options: ObservableValue<Pick<VinylOptions, "abr">>;
         }) => ObservableValue<QualitySelectorImplOptions>;
@@ -138,11 +147,13 @@ export declare function createVinylFactories(options: VinylDependencyOptions): {
         }) => ObservableValue<Promise<import("..").MediaTimeline>>;
         mediaTimelineTransformed: typeof import("..").createDefaultMediaTimelineTransformer;
         textTrackController: (deps: {
-            readonly media: HTMLMediaElement;
+            readonly textTrackProvider: MediaTextTrackProvider;
+            readonly textTrackRenderer: TextTrackRenderer | null;
+            readonly playbackController: import("..").PlaybackController;
             readonly manifestTransformed: ObservableValue<Promise<import("..").DashManifestData>>;
-            readonly options: ObservableValue<Pick<VinylOptions, "preferredTextLanguage" | "textCueStyle">>;
+            readonly options: ObservableValue<Pick<VinylOptions, "text">>;
         }) => import("..").SidecarTextTrackController;
-        options: import("@amazon/vinyl-di").Factory<ObservableValue<Pick<VinylOptions, "abr" | "preferredAudioLanguage" | "preferredTextLanguage" | "preferDescriptiveAudio" | "allowedContentTypes" | "textCueStyle">>>;
+        options: import("@amazon/vinyl-di").Factory<ObservableValue<Pick<VinylOptions, "audio" | "text" | "abr" | "allowedContentTypes">>>;
         playbackController: import("@amazon/vinyl-di").Factory<import("..").PlaybackController>;
         playbackSource: import("@amazon/vinyl-di").Factory<import("..").PlaybackSource>;
         drmKeySystemResolver: import("@amazon/vinyl-di").Factory<import("..").DrmKeySystemResolver>;
@@ -150,6 +161,8 @@ export declare function createVinylFactories(options: VinylDependencyOptions): {
         drmController: import("@amazon/vinyl-di").Factory<import("..").DrmController>;
         capabilities: import("@amazon/vinyl-di").Factory<import("..").Capabilities>;
         media: import("@amazon/vinyl-di").Factory<HTMLMediaElement>;
+        textTrackProvider: import("@amazon/vinyl-di").Factory<MediaTextTrackProvider>;
+        textTrackRenderer: import("@amazon/vinyl-di").Factory<TextTrackRenderer | null>;
         adController: import("@amazon/vinyl-di").Factory<import("..").AdController>;
     };
     createHlsFactories: (deps: import("..").HlsFactoryDeps) => (loadOptions: import("..").HlsTrackLoadOptions) => {
@@ -175,15 +188,12 @@ export declare function createVinylFactories(options: VinylDependencyOptions): {
         qualitySelector: (deps: {
             options: ObservableValue<Pick<VinylOptions, "abr">>;
         }) => import("..").QualitySelectorImpl;
-        preferredAudioLanguage: (deps: {
-            options: ObservableValue<Pick<VinylOptions, "preferredAudioLanguage">>;
-        }) => ObservableValue<string | readonly string[] | null>;
+        audio: (deps: {
+            options: ObservableValue<Pick<VinylOptions, "audio">>;
+        }) => ObservableValue<import("..").AudioOptions>;
         allowedContentTypes: (deps: {
             options: ObservableValue<Pick<VinylOptions, "allowedContentTypes">>;
         }) => ObservableValue<readonly import("..").RestrictableContentType[] | null>;
-        preferDescriptiveAudio: (deps: {
-            options: ObservableValue<Pick<VinylOptions, "preferDescriptiveAudio">>;
-        }) => ObservableValue<boolean>;
         abr: (deps: {
             options: ObservableValue<Pick<VinylOptions, "abr">>;
         }) => ObservableValue<QualitySelectorImplOptions>;
@@ -192,11 +202,13 @@ export declare function createVinylFactories(options: VinylDependencyOptions): {
         }) => ObservableValue<Promise<import("..").MediaTimeline>>;
         mediaTimelineTransformed: typeof import("..").createDefaultMediaTimelineTransformer;
         textTrackController: (deps: {
-            readonly media: HTMLMediaElement;
+            readonly textTrackProvider: MediaTextTrackProvider;
+            readonly textTrackRenderer: TextTrackRenderer | null;
+            readonly playbackController: import("..").PlaybackController;
             readonly manifestTransformed: ObservableValue<Promise<import("..").HlsManifestData>>;
-            readonly options: ObservableValue<Pick<VinylOptions, "preferredTextLanguage" | "textCueStyle">>;
+            readonly options: ObservableValue<Pick<VinylOptions, "text">>;
         }) => import("..").SidecarTextTrackController;
-        options: import("@amazon/vinyl-di").Factory<ObservableValue<Pick<VinylOptions, "abr" | "preferredAudioLanguage" | "preferredTextLanguage" | "preferDescriptiveAudio" | "allowedContentTypes" | "textCueStyle">>>;
+        options: import("@amazon/vinyl-di").Factory<ObservableValue<Pick<VinylOptions, "audio" | "text" | "abr" | "allowedContentTypes">>>;
         playbackController: import("@amazon/vinyl-di").Factory<import("..").PlaybackController>;
         playbackSource: import("@amazon/vinyl-di").Factory<import("..").PlaybackSource>;
         drmKeySystemResolver: import("@amazon/vinyl-di").Factory<import("..").DrmKeySystemResolver>;
@@ -204,6 +216,8 @@ export declare function createVinylFactories(options: VinylDependencyOptions): {
         drmController: import("@amazon/vinyl-di").Factory<import("..").DrmController>;
         capabilities: import("@amazon/vinyl-di").Factory<import("..").Capabilities>;
         media: import("@amazon/vinyl-di").Factory<HTMLMediaElement>;
+        textTrackProvider: import("@amazon/vinyl-di").Factory<MediaTextTrackProvider>;
+        textTrackRenderer: import("@amazon/vinyl-di").Factory<TextTrackRenderer | null>;
         adController: import("@amazon/vinyl-di").Factory<import("..").AdController>;
     };
 };

package/dist/types/ts4.1/index.d.ts

@@ -58,6 +58,7 @@ export * from './playback/PlaybackSourceImpl';
 export * from './playback/ReadonlyPlaybackController';
 export * from './streaming/abr/QualitySelector';
 export * from './streaming/abr/QualitySelectorImpl';
+export * from './streaming/AudioOptions';
 export * from './streaming/buffering/BufferingController';
 export * from './streaming/buffering/codecDenylist';
 export * from './streaming/buffering/error/SourceBufferError';
@@ -87,11 +88,14 @@ export * from './streaming/StreamingEventMap';
 export * from './streaming/util/segment';
 export * from './text/discoverDashTextTracks';
 export * from './text/discoverHlsTextTracks';
+export * from './text/HtmlTextTrackRenderer';
+export * from './text/mediaTextTrackProvider';
 export * from './text/parseWebVtt';
 export * from './text/pickPreferredTextTrack';
 export * from './text/SidecarTextTrackController';
 export * from './text/SidecarTextTrackLoader';
 export * from './text/TextTrack';
+export * from './text/TextTrackRenderer';
 export * from './text/VttCueStyle';
 export * from './track/AutoResetController';
 export * from './track/createSegmentDataProvider';

package/dist/types/ts4.1/streaming/AudioOptions.d.ts

@@ -0,0 +1,39 @@
+import type { ObjectSchema } from '@amazon/vinyl-validation';
+/**
+ * Criteria used to pick which audio rendition to play.
+ */
+export interface AudioSelection {
+    /**
+     * Preferred language(s) for audio content, as RFC 5646 codes (e.g. `'en'`,
+     * `'ja'`, `'fr-CA'`). May be a single tag or an ordered list of tags —
+     * earlier entries are preferred, with the best relatedness match kept for
+     * each period (audio without a language tag is always kept). `null` (the
+     * default) is NOT "no preference": it orders by the platform's
+     * `navigator.languages`. To keep every language, this option is not the
+     * mechanism — omit language content or pass a tag matching all.
+     */
+    readonly language?: string | readonly string[] | null;
+    /**
+     * Opt in to audio-description (a.k.a. described-video / DVS) audio: audio
+     * renditions carrying an accessibility "describes video" characteristic that
+     * narrate on-screen action. `false` (the default) keeps them out of the
+     * automatic default-audio selection — they are chosen only when this is set.
+     * When `true`, a description rendition is preferred where one exists for the
+     * selected language. Changing this reselects audio immediately.
+     */
+    readonly descriptive?: boolean;
+}
+/**
+ * Declarative audio configuration. Mirrors `VinylOptions.text`: the audio
+ * rendition is chosen from {@link selection}; changing it reselects audio
+ * immediately.
+ */
+export interface AudioOptions {
+    /**
+     * The audio selection criteria (language / descriptive).
+     */
+    readonly selection?: AudioSelection;
+}
+export declare const defaultAudioOptions: AudioOptions;
+export declare const audioOptionsValidator: ObjectSchema<AudioOptions>;
+//# sourceMappingURL=AudioOptions.d.ts.map

package/dist/types/ts4.1/streaming/createDefaultMediaTimelineTransformer.d.ts

@@ -3,13 +3,13 @@ import type { Capabilities } from '../client/Capabilities';
 import type { DrmController } from '../drm/DrmController';
 import type { MediaTimeline } from './MediaTimeline';
 import type { CodecOverrides } from '../util/media/codecOverrides';
+import type { AudioOptions } from './AudioOptions';
 export interface DefaultMediaTimelineTransformerDeps {
     readonly capabilities: Capabilities;
     readonly drmController: DrmController;
     readonly mediaTimeline: ObservableValue<Promise<MediaTimeline>>;
     readonly options: ObservableValue<{
-        readonly preferredAudioLanguage: string | readonly string[] | null;
-        readonly preferDescriptiveAudio?: boolean;
+        readonly audio: AudioOptions;
         readonly codecOverrides?: CodecOverrides;
     }>;
 }

package/dist/types/ts4.1/text/HtmlTextTrackRenderer.d.ts

@@ -0,0 +1,60 @@
+import type { Disposable } from '@amazon/vinyl-util';
+import type { TextTrackRenderer } from './TextTrackRenderer';
+/**
+ * The subset of a `VTTCue`'s positioning properties {@link computeCueLayout}
+ * reads. A native `VTTCue` satisfies this; a plain `TextTrackCue` (platforms
+ * without `VTTCue`) leaves them undefined and falls back to defaults.
+ */
+export interface CueGeometry {
+    readonly align?: string | null;
+    readonly line?: number | AutoKeyword;
+    readonly lineAlign?: LineAlignSetting;
+    readonly position?: number | AutoKeyword;
+    readonly positionAlign?: PositionAlignSetting;
+    readonly size?: number;
+    readonly snapToLines?: boolean;
+    readonly vertical?: DirectionSetting;
+}
+/** Inline styles (camelCase CSS properties) to apply to a rendered cue box. */
+export type CueLayout = Record<string, string>;
+/**
+ * Maps a cue's WebVTT positioning settings to inline CSS. Pure and DOM-free so
+ * the (branchy) placement logic is unit-testable in isolation.
+ *
+ * A cue with neither `line` nor `position` set flows in the renderer's
+ * bottom-anchored, centered container (the common subtitle case). Otherwise it
+ * is absolutely positioned: `size` → width, `position`/`positionAlign` →
+ * horizontal, `line`/`lineAlign`/`snapToLines` → vertical (percentage lines, or
+ * whole rows counted from the bottom for negative integers), `align` → text
+ * alignment, `vertical` → writing mode.
+ */
+export declare function computeCueLayout(cue: CueGeometry): CueLayout;
+/**
+ * Renders a cue's text payload as safe HTML. Text is escaped (so it can't
+ * inject nodes); newlines become `<br>`; and WebVTT cue tags are converted:
+ * `<c.foo>`→`<span class="foo">`, `<i>/<b>/<u>/<ruby>/<rt>` pass through,
+ * `<v Name>`→`<span title>`, `<lang xx>`→`<span lang>`, timestamp tags are
+ * dropped. Class-based styling requires matching app CSS (STYLE blocks in the
+ * VTT are not applied).
+ */
+export declare function renderCueText(text: string): string;
+/**
+ * A {@link TextTrackRenderer} that paints cues as HTML into {@link element}.
+ * Mount `element` over the video; it stacks cues at the bottom, centered, and
+ * positions any cue that carries explicit WebVTT settings. The DOM track is
+ * expected to be `'hidden'` so only this renderer paints.
+ */
+export declare class HtmlTextTrackRenderer implements TextTrackRenderer, Disposable {
+    /** The overlay container to mount over the video. */
+    readonly element: HTMLElement;
+    private track;
+    private readonly styleElement;
+    private readonly onCueChange;
+    constructor();
+    setTextTrack(track: TextTrack | null): void;
+    setStyles(styles: readonly string[]): void;
+    dispose(): void;
+    private renderActiveCues;
+    private createCueBox;
+}
+//# sourceMappingURL=HtmlTextTrackRenderer.d.ts.map

package/dist/types/ts4.1/text/SidecarTextTrackController.d.ts

@@ -1,92 +1,104 @@
 import type { Maybe, RequestInitOptions } from '@amazon/vinyl-util';
 import { EventHostImpl } from '@amazon/vinyl-util';
-import type { TextTrackController, TextTrackEventMap, TextTrackInfo } from './TextTrack';
+import type { TextTrackController, TextTrackControllerOptions, TextTrackEventMap, TextTrackInfo } from './TextTrack';
 import type { ObservableValue } from '@amazon/vinyl-observable';
-import type { VttCueStyle } from './VttCueStyle';
+import type { MediaTextTrackProvider } from './mediaTextTrackProvider';
+import type { ReadonlyPlaybackController } from '../playback/ReadonlyPlaybackController';
+import type { TextTrackRenderer } from './TextTrackRenderer';
 export interface SidecarTextTrackControllerDeps {
     /**
-     * The HTML media element on which to attach the in-band TextTrack
-     * representation. Cues for the active text track are added to a TextTrack
-     * created via `media.addTextTrack`. Setting this to null disables DOM
-     * integration; cues are still loaded and surfaced via events.
+     * Hands out (memoized) DOM text tracks. Text tracks can only be created on a
+     * media element and never removed, so the provider reuses one track per
+     * rendition rather than accumulating them.
      */
-    readonly media: HTMLMediaElement | null;
+    readonly textTrackProvider: MediaTextTrackProvider;
     /**
      * Optional request init options forwarded with each VTT fetch (e.g. CORS).
      */
     readonly requestInit?: Maybe<RequestInitOptions>;
     /**
-     * Preferred caption language(s), most-preferred first. A non-null
-     * preference auto-selects the best-matching track, re-applied as the track
-     * list changes. Changing the preference to null clears the selection
-     * (captions off). An initial null (or an absent observable) is "no
-     * preference": forced tracks still auto-select until the app makes an
-     * explicit choice — it does not force captions off.
+     * The discovered text tracks, re-emitted whenever the manifest changes.
      */
-    readonly preferredTextLanguage?: ObservableValue<string | readonly string[] | null>;
+    readonly textTracks: ObservableValue<Promise<readonly TextTrackInfo[]>>;
     /**
-     * Layout style applied to each rendered VTTCue (see
-     * {@link VttCueStyle}). Read per cue as it is appended, so a change affects
-     * subsequently-rendered cues. Absent means no styling (browser defaults).
+     * Declarative selection / rendering configuration. Re-applied on change.
      */
-    readonly cueStyle?: ObservableValue<VttCueStyle | null>;
+    readonly options: ObservableValue<TextTrackControllerOptions>;
+    /**
+     * Supplies the current playhead used to fetch caption segments in a window
+     * around it.
+     */
+    readonly playbackController: ReadonlyPlaybackController;
+    /**
+     * Optional renderer that paints cues itself (HTML overlay). When provided,
+     * the DOM text track is kept `'hidden'` (timing only) and the renderer is
+     * handed the active track; without one, the track renders natively
+     * (`'showing'`).
+     */
+    readonly textTrackRenderer?: Maybe<TextTrackRenderer>;
 }
+/**
+ * Selects the text track that matches the given options, or null for none.
+ *
+ * The `enabled` mode gates everything: `'off'` renders nothing (default is
+ * `'forced'`). Otherwise an explicit {@link TextTrackSelection.id} wins; else
+ * the best language match is chosen among tracks filtered by kind and
+ * forced-ness. Forced-ness comes from {@link TextTrackSelection.forced} when
+ * set, otherwise from the mode (`'forced'` keeps only forced tracks, `'on'`
+ * only full tracks).
+ *
+ * @private
+ */
+export declare function resolveSelectedTrack(tracks: readonly TextTrackInfo[], options: TextTrackControllerOptions): TextTrackInfo | null;
 /**
  * Manages a sidecar WebVTT-based text track lifecycle:
  *
- *  - holds a discovered list of {@link TextTrackInfo}
- *  - on activation, fetches the chosen track's WebVTT and pushes cues to a
- *    `TextTrack` created on the `HTMLMediaElement`
- *  - clears any previously activated cues when switching tracks
+ *  - tracks the discovered {@link TextTrackInfo} list (from the `textTracks`
+ *    observable) and the current selection (from the `options` observable)
+ *  - on selection, fetches the chosen track's WebVTT and pushes cues to a DOM
+ *    `TextTrack` obtained from the {@link MediaTextTrackProvider}
+ *  - clears cues and hides the DOM track when the selection changes or clears
  *
- * The controller is intentionally agnostic of HLS/DASH discovery details. Its
- * input is whatever list of {@link TextTrackInfo} entries the manifest layer
- * decides to surface.
+ * The controller is agnostic of HLS/DASH discovery details; its inputs are the
+ * observables supplied by the manifest layer.
  */
 export declare class SidecarTextTrackController extends EventHostImpl<TextTrackEventMap> implements TextTrackController {
     private readonly deps;
     get [Symbol.toStringTag](): string;
-    private _tracks;
     private _active;
-    private _domTrack;
-    private loadAbort;
-    private _userSelected;
-    private readonly preferredLanguageSub;
+    private _tracks;
+    private _activeTextTrack;
+    private _ref;
+    private readonly loadAbort;
+    private readonly disposer;
     constructor(deps: SidecarTextTrackControllerDeps);
     get textTracks(): readonly TextTrackInfo[];
     get activeTextTrack(): (TextTrackInfo | null);
+    get active(): boolean;
+    get disposed(): boolean;
     /**
-     * Replaces the discovered text track list. Emits `textTracksChange`. If
-     * the previously active track is no longer present, clears the active
-     * selection and emits `activeTextTrackChange`.
-     */
-    setTextTracks(tracks: readonly TextTrackInfo[]): void;
-    setActiveTextTrack(id: string | null): void;
-    /**
-     * Selects the track best matching the preferred language(s), or clears the
-     * selection when the preference is null or nothing matches.
+     * Replaces the discovered track list, emits `textTracksChange`, then
+     * re-applies the current selection against the new list.
      */
-    private applyPreferredLanguage;
+    private setTracks;
     /**
-     * Applies a selection by id (null clears it) without marking it as an
-     * explicit user choice. Shared by setActiveTextTrack and forced auto-select.
+     * Recomputes the selection from the current options and track list,
+     * emitting `activeTextTrackChange` on change and (re)rendering when active.
      */
-    private selectById;
+    private refreshSelection;
+    deactivate(): void;
+    activate(): void;
+    private startLoad;
+    private appendCues;
     /**
-     * The forced track to auto-select, or null. Prefers the default track's
-     * language, else the first forced track.
+     * Clears cues from the current DOM track and hides it, keeping the track for
+     * later reuse via the provider.
      */
-    private pickForcedTrack;
-    suspend(): void;
-    resume(): void;
+    private hideCurrent;
     /**
-     * Cancels any in-flight load, clears the DOM TextTrack, and resets state.
+     * Cancels any in-flight load, hides the DOM text track, and resets state.
      * Called by the host when the underlying media is unloaded.
      */
     dispose(): void;
-    private startLoad;
-    private ensureDomTrack;
-    private appendCues;
-    private clearDomTrack;
 }
 //# sourceMappingURL=SidecarTextTrackController.d.ts.map

package/dist/types/ts4.1/text/SidecarTextTrackLoader.d.ts

@@ -24,6 +24,11 @@ export interface LoadWebVttCuesOptions {
      * per HLS segment, or once for a direct `.vtt` document.
      */
     readonly onCues: (cues: readonly WebVttCue[]) => void;
+    /**
+     * Invoked with the CSS body of any `STYLE` blocks parsed from a document.
+     * Only called when a document actually declares styles.
+     */
+    readonly onStyles?: Maybe<(styles: readonly string[]) => void>;
     /**
      * Returns the current playback time (seconds on the presentation
      * timeline). Used to fetch caption segments in a window around the