@amazon/vinyl 2.0.0 → 3.0.0

package/dist/types/ts4.7/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.7/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.7/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.7/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.7/text/SidecarTextTrackController.d.ts

@@ -1,91 +1,103 @@
 import { EventHostImpl, type Maybe, type RequestInitOptions } 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.7/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

package/dist/types/ts4.7/text/TextTrack.d.ts

@@ -1,5 +1,6 @@
 import type { ChangeEvent } from '../event/ChangeEvent';
 import type { ReadonlyEventHost } from '@amazon/vinyl-util';
+import type { ObjectSchema } from '@amazon/vinyl-validation';
 /**
  * Categorizes the role of a text track. Mirrors HTMLMediaElement.TextTrackKind.
  */
@@ -79,6 +80,64 @@ export interface TextTrackErrorEvent {
     readonly track: TextTrackInfo;
     readonly error: Error;
 }
+/**
+ * Which captions render:
+ * - `'off'` — nothing renders (not even forced narrative captions).
+ * - `'forced'` — only forced (narrative) tracks, so nothing shows unless the
+ *   content carries a forced track for the preferred language.
+ * - `'on'` — the full (non-forced) subtitle track for the preferred language.
+ */
+export type CaptionMode = 'on' | 'off' | 'forced';
+/**
+ * Criteria used to pick which text track to render. Applied in priority order:
+ * an explicit {@link id} wins; otherwise the best {@link language} match is
+ * chosen among tracks filtered by {@link kind} and by forced-ness (from
+ * {@link forced} when set, else from the controller's
+ * {@link TextTrackControllerOptions.enabled} mode).
+ */
+export interface TextTrackSelection {
+    /**
+     * Selects the text track with this exact identifier, ignoring the other
+     * criteria (but still gated by the `'off'` mode). If no track has this id,
+     * nothing is selected.
+     */
+    readonly id?: string | null;
+    /**
+     * Restricts selection to tracks of this kind (e.g. `'captions'`). Unset
+     * considers all kinds.
+     */
+    readonly kind?: TextTrackKind | null;
+    /**
+     * Preferred caption language(s), most-preferred first, as RFC 5646 tags.
+     * When unset (or empty) selection falls back to the platform's
+     * `navigator.languages`.
+     */
+    readonly language?: string | readonly string[] | null;
+    /**
+     * Explicit forced-ness filter. When set, only tracks whose `forced` flag
+     * equals this value are considered, overriding the forced/full split
+     * implied by the `enabled` mode. Unset means the mode decides.
+     */
+    readonly forced?: boolean | null;
+}
+/**
+ * Declarative configuration for a {@link TextTrackController}. Rendering is
+ * driven entirely by this value (via `VinylOptions.text`); there is no
+ * imperative track-select call.
+ */
+export interface TextTrackControllerOptions {
+    /**
+     * Which captions render (see {@link CaptionMode}). Unset defaults to
+     * `'forced'`.
+     */
+    readonly enabled?: CaptionMode | null;
+    /**
+     * The selection criteria (language / id / kind). When unset, the preferred
+     * languages fall back to the platform's `navigator.languages`.
+     */
+    readonly selection?: TextTrackSelection | null;
+}
+export declare const textTrackControllerOptionsValidator: ObjectSchema<TextTrackControllerOptions>;
 export declare const ALL_TEXT_TRACK_EVENTS: readonly [
     "textTracksChange",
     "activeTextTrackChange",
@@ -96,34 +155,29 @@ export interface ReadonlyTextTrackController extends ReadonlyEventHost<TextTrack
      * The currently active text track, or null if none is active.
      */
     readonly activeTextTrack: TextTrackInfo | null;
+    /**
+     * Returns true if this text track controller is active.
+     */
+    get active(): boolean;
 }
 /**
- * Provides access to the text tracks of the current media and allows
- * selecting one for playback.
- *
- * Selection is persisted across track changes only when applications choose
- * to call {@link setActiveTextTrack} again on the new track. This matches
- * how audio tracks are typically driven.
+ * Full controller for the current media's text tracks. Selection is driven
+ * declaratively through the controller's options (`VinylOptions.text`); this
+ * interface only adds the render lifecycle used by the owning media track.
  */
 export interface TextTrackController extends ReadonlyTextTrackController {
-    /**
-     * Selects the text track with the given id, or clears the active text
-     * track when called with null. No-op if the id does not match a known
-     * text track.
-     */
-    setActiveTextTrack(id: string | null): void;
     /**
      * Suspends cue rendering without changing the active selection: cancels any
-     * in-flight load and tears down the DOM text track (so its cues stop
-     * showing). Called when the owning media track is deactivated — e.g. while
-     * an ad plays over the suspended content. {@link resume} rebuilds it.
+     * in-flight load and hides the DOM text track (so its cues stop showing).
+     * Called when the owning media track is deactivated — e.g. while an ad
+     * plays over the suspended content. {@link activate} rebuilds it.
      */
-    suspend(): void;
+    deactivate(): void;
     /**
-     * Rebuilds the DOM text track for the active selection after a
-     * {@link suspend}, reloading its cues. No-op when nothing is active or when
-     * already rendering. Called when the owning media track is reactivated.
+     * Resumes rendering the active selection after a {@link deactivate},
+     * reloading its cues. No-op when nothing is selected or already rendering.
+     * Called when the owning media track is reactivated.
      */
-    resume(): void;
+    activate(): void;
 }
 //# sourceMappingURL=TextTrack.d.ts.map

package/dist/types/ts4.7/text/TextTrackRenderer.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Renders a text track's cues. Injected into the player so an application can
+ * paint captions itself (as HTML) instead of relying on the browser's native
+ * `TextTrack` rendering — giving full control over styling and placement.
+ *
+ * The controller hands the renderer the DOM `TextTrack` (set to `'hidden'`, so
+ * the browser tracks cue timing but does not paint); the renderer listens for
+ * the track's active cues and draws them. See {@link HtmlTextTrackRenderer} for
+ * the built-in HTML implementation.
+ */
+export interface TextTrackRenderer {
+    /**
+     * Renders the active cues of `track`, listening for cue changes. Passing
+     * `null` clears anything rendered and detaches from the previous track.
+     */
+    setTextTrack(track: TextTrack | null): void;
+    /**
+     * Supplies the CSS bodies of the track's WebVTT `STYLE` blocks (which carry
+     * `::cue` rules), so the renderer can style cue classes. Optional — a
+     * renderer may ignore authored styles.
+     */
+    setStyles?(styles: readonly string[]): void;
+}
+//# sourceMappingURL=TextTrackRenderer.d.ts.map

package/dist/types/ts4.7/text/mediaTextTrackProvider.d.ts

@@ -0,0 +1,34 @@
+import type { TextTrackKind } from './TextTrack';
+/**
+ * A handle to a DOM {@link TextTrack} created on the media element, plus a way
+ * to clear its cues.
+ */
+export interface TextTrackRef {
+    readonly track: TextTrack;
+    /**
+     * Removes all cues from the track. Must be called while the track is not
+     * `disabled` — `TextTrack.cues` reads null in the disabled state, so
+     * clearing a disabled track silently leaves its cues attached.
+     */
+    clear(): void;
+}
+/**
+ * Creates and hands out DOM text tracks for a media element, memoized per
+ * `(kind, label, language)`.
+ *
+ * `HTMLMediaElement.addTextTrack` tracks can never be removed, so creating a
+ * fresh one per activation would accumulate tracks — and any left in `showing`
+ * mode renders alongside the active one (captions "bleed through"). Reusing one
+ * track per key keeps exactly one track per distinct rendition.
+ */
+export interface MediaTextTrackProvider {
+    getOrCreate(kind: TextTrackKind, label?: string, language?: string): TextTrackRef;
+}
+export declare function createMediaTextTrackProvider(deps: {
+    /**
+     * The HTML media element on which to attach the in-band TextTrack
+     * representation.
+     */
+    readonly media: HTMLMediaElement;
+}): MediaTextTrackProvider;
+//# sourceMappingURL=mediaTextTrackProvider.d.ts.map

package/dist/types/ts4.7/text/parseWebVtt.d.ts

@@ -1,3 +1,4 @@
+import type { VttCueStyle } from './VttCueStyle';
 /**
  * A single WebVTT cue.
  *
@@ -20,6 +21,12 @@ export interface WebVttCue {
      * The cue text payload, with line breaks preserved as `\n`.
      */
     readonly text: string;
+    /**
+     * The authored cue settings from the timing line (position/line/size/
+     * align/vertical), when any were present. Preserved so a renderer can
+     * position the cue faithfully. Absent when the cue declared no settings.
+     */
+    readonly settings?: VttCueStyle;
 }
 /**
  * The result of parsing a WebVTT document.
@@ -29,18 +36,25 @@ export interface WebVttDocument {
      * Parsed cues in document order.
      */
     readonly cues: readonly WebVttCue[];
+    /**
+     * The raw CSS body of each `STYLE` block, in document order. These carry
+     * `::cue` rules (e.g. `::cue(.loud) { font-weight: bold }`) an HTML renderer
+     * can apply. Empty when the document declared no styles.
+     */
+    readonly styles: readonly string[];
 }
 /**
  * Parses a WebVTT document into a list of cues.
  *
  * Implements a forgiving subset of the WebVTT 1.0 specification: header
  * detection, comment blocks (lines starting with `NOTE`), styling/region
- * blocks (skipped), cue identifiers, and HH:MM:SS.mmm or MM:SS.mmm timestamps.
- * Cue settings on the timing line are tolerated and ignored.
+ * blocks (STYLE bodies are captured, REGION skipped), cue identifiers, and
+ * HH:MM:SS.mmm or MM:SS.mmm timestamps with optional cue settings.
  *
  * @param input The raw WebVTT document text. Both LF and CRLF line endings
  * are supported, and a leading BOM is stripped if present.
  * @throws ValidationError if the input is missing the WEBVTT header.
+ * @see https://www.w3.org/TR/webvtt1/#webvtt-timestamp
  */
 export declare function parseWebVtt(input: string): WebVttDocument;
 //# sourceMappingURL=parseWebVtt.d.ts.map

package/dist/types/ts4.7/text/pickPreferredTextTrack.d.ts

@@ -1,4 +1,5 @@
 import type { TextTrackInfo } from './TextTrack';
+import type { Maybe } from '@amazon/vinyl-util';
 /**
  * Chooses the text track that best matches the preferred language(s), or null
  * when none relate (or there is no preference / no tracks).
@@ -10,5 +11,5 @@ import type { TextTrackInfo } from './TextTrack';
  * forced foreign-dialogue cues), and a manifest-default track breaks any
  * remaining tie.
  */
-export declare function pickPreferredTextTrack(tracks: readonly TextTrackInfo[], preferred: string | readonly string[] | null): TextTrackInfo | null;
+export declare function pickPreferredTextTrack(tracks: readonly TextTrackInfo[], preferred: Maybe<string | readonly string[]>): TextTrackInfo | null;
 //# sourceMappingURL=pickPreferredTextTrack.d.ts.map

package/dist/types/ts4.7/track/Track.d.ts

@@ -133,7 +133,7 @@ export interface ReadonlyTrack extends ReadonlyEventHost<TrackEventMap>, Readonl
      */
     readonly error: Error | null;
     /**
-     * Controller for sidecar text tracks discovered for this track, or null
+     * Controller for text tracks discovered for this track, or null
      * if the track type does not surface text tracks.
      */
     readonly textTrackController: ReadonlyTextTrackController | null;

package/dist/types/ts4.7/track/dash/createDashFactories.d.ts

@@ -20,13 +20,15 @@ import { type BuildDashMediaTimelineDeps } from './buildDashMediaTimeline';
 import { createDefaultMediaTimelineTransformer } from '../../streaming/createDefaultMediaTimelineTransformer';
 import type { DashManifestData } from './DashManifestProvider';
 import { SidecarTextTrackController } from '../../text/SidecarTextTrackController';
+import type { MediaTextTrackProvider } from '../../text/mediaTextTrackProvider';
+import type { TextTrackRenderer } from '../../text/TextTrackRenderer';
 import type { AdController } from '../../ad/AdController';
 import { ManifestControllerImpl, type ManifestControllerImplDeps } from '../../streaming/ManifestControllerImpl';
 /**
  * Player-level dependencies needed for the Dash-specific factories.
  */
 export interface DashFactoryDeps {
-    readonly options: ObservableValue<Pick<VinylOptions, 'abr' | 'preferredAudioLanguage' | 'allowedContentTypes' | 'preferDescriptiveAudio' | 'preferredTextLanguage' | 'textCueStyle'>>;
+    readonly options: ObservableValue<Pick<VinylOptions, 'abr' | 'audio' | 'allowedContentTypes' | 'text'>>;
     readonly playbackController: PlaybackController;
     readonly playbackSource: PlaybackSource;
     readonly drmKeySystemResolver: DrmKeySystemResolver;
@@ -38,6 +40,14 @@ export interface DashFactoryDeps {
      * `media.addTextTrack`.
      */
     readonly media: HTMLMediaElement;
+    /**
+     * Creates and reuses the DOM text tracks for sidecar captions.
+     */
+    readonly textTrackProvider: MediaTextTrackProvider;
+    /**
+     * Optional HTML cue renderer; null for native rendering.
+     */
+    readonly textTrackRenderer: TextTrackRenderer | null;
     /**
      * The player-level ad controller. MseTrack sets discovered ad breaks on it
      * when the media timeline resolves.
@@ -76,15 +86,12 @@ export declare function createDashFactories(options: Maybe<DashInitOptions>): (d
     qualitySelector: (deps: {
         options: ObservableValue<Pick<VinylOptions, "abr">>;
     }) => 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<import("../..").QualitySelectorImplOptions>;
@@ -94,11 +101,13 @@ export declare function createDashFactories(options: Maybe<DashInitOptions>): (d
     }) => ObservableValue<Promise<import("../..").MediaTimeline>>;
     mediaTimelineTransformed: typeof createDefaultMediaTimelineTransformer;
     textTrackController: (deps: {
-        readonly media: HTMLMediaElement;
+        readonly textTrackProvider: MediaTextTrackProvider;
+        readonly textTrackRenderer: TextTrackRenderer | null;
+        readonly playbackController: PlaybackController;
         readonly manifestTransformed: ObservableValue<Promise<DashManifestData>>;
-        readonly options: ObservableValue<Pick<VinylOptions, "preferredTextLanguage" | "textCueStyle">>;
+        readonly options: ObservableValue<Pick<VinylOptions, "text">>;
     }) => 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<PlaybackController>;
     playbackSource: import("@amazon/vinyl-di").Factory<PlaybackSource>;
     drmKeySystemResolver: import("@amazon/vinyl-di").Factory<DrmKeySystemResolver>;
@@ -106,6 +115,8 @@ export declare function createDashFactories(options: Maybe<DashInitOptions>): (d
     drmController: import("@amazon/vinyl-di").Factory<DrmController>;
     capabilities: import("@amazon/vinyl-di").Factory<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<AdController>;
 };
 //# sourceMappingURL=createDashFactories.d.ts.map