@amazon/vinyl 2.0.4 → 3.0.0

package/dist/types/ts4.1/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.
+    */
+    readonly 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.1/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.1/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.1/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.1/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.1/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.1/track/dash/createDashFactories.d.ts

@@ -21,6 +21,8 @@ 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 type { ManifestControllerImplDeps } from '../../streaming/ManifestControllerImpl';
 import { ManifestControllerImpl } from '../../streaming/ManifestControllerImpl';
@@ -28,7 +30,7 @@ import { ManifestControllerImpl } 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;
@@ -40,6 +42,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.
@@ -78,15 +88,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>;
@@ -96,11 +103,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>;
@@ -108,6 +117,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

package/dist/types/ts4.1/track/hls/createHlsFactories.d.ts

@@ -21,10 +21,12 @@ import type { BuildHlsMediaTimelineDeps } from './buildHlsMediaTimeline';
 import { createDefaultMediaTimelineTransformer } from '../../streaming/createDefaultMediaTimelineTransformer';
 import type { HlsManifestData } from './HlsManifestData';
 import { SidecarTextTrackController } from '../../text/SidecarTextTrackController';
+import type { MediaTextTrackProvider } from '../../text/mediaTextTrackProvider';
+import type { TextTrackRenderer } from '../../text/TextTrackRenderer';
 import type { ManifestControllerImplDeps } from '../../streaming/ManifestControllerImpl';
 import { ManifestControllerImpl } from '../../streaming/ManifestControllerImpl';
 export interface HlsFactoryDeps {
-    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;
@@ -36,6 +38,14 @@ export interface HlsFactoryDeps {
      * `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.
@@ -68,15 +78,12 @@ export declare function createHlsFactories(options: Maybe<HlsInitOptions>): (dep
     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>;
@@ -85,11 +92,13 @@ export declare function createHlsFactories(options: Maybe<HlsInitOptions>): (dep
     }) => 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<HlsManifestData>>;
-        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>;
@@ -97,6 +106,8 @@ export declare function createHlsFactories(options: Maybe<HlsInitOptions>): (dep
     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=createHlsFactories.d.ts.map

package/dist/types/ts4.1/track/mse/MseTrack.d.ts

@@ -43,9 +43,8 @@ export type MseTrackDeps = TrackBaseDeps & {
      * the initial value) is applied to this track immediately so it takes
      * effect without waiting for the buffered media to drain.
      */
-    readonly preferredAudioLanguage: ObservableValue<VinylOptions['preferredAudioLanguage']>;
+    readonly audio: ObservableValue<VinylOptions['audio']>;
     readonly allowedContentTypes: ObservableValue<VinylOptions['allowedContentTypes']>;
-    readonly preferDescriptiveAudio: ObservableValue<VinylOptions['preferDescriptiveAudio']>;
     readonly abr: ObservableValue<VinylOptions['abr']>;
 };
 /**

package/dist/types/ts4.1/vinyl/VinylOptions.d.ts

@@ -3,7 +3,8 @@ import type { ObjectSchema } from '@amazon/vinyl-validation';
 import type { CodecOverrides } from '../util/media/codecOverrides';
 import type { RestrictableContentType } from '../streaming/MediaQualityMetadata';
 import type { LoudnessNormalizationControllerImplOptions } from '../playback/loudness/LoudnessNormalizationControllerImplOptions';
-import type { VttCueStyle } from '../text/VttCueStyle';
+import type { TextTrackControllerOptions } from '../text/TextTrack';
+import type { 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/ts4.1/vinyl/VinylPlayer.d.ts

@@ -157,12 +157,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/ts4.1/vinyl/createVinylFactories.d.ts

@@ -13,6 +13,8 @@ import type { VinylPatchOptions } from './VinylPatchOptions';
 import type { QualitySelectorImplOptions } from '../streaming/abr/QualitySelectorImpl';
 import type { AdControllerImplDeps, AdControllerImplOptions } from '../ad/AdControllerImpl';
 import { AdControllerImpl } from '../ad/AdControllerImpl';
+import type { MediaTextTrackProvider } from '../text/mediaTextTrackProvider';
+import type { TextTrackRenderer } from '../text/TextTrackRenderer';
 import type { DrmOptions } from '../drm/DrmOptions';
 import { commonEmeFactory } from '../drm/commonEme/CommonEmeFactory';
 import type { DrmControllerImplDeps } from '../drm/DrmControllerImpl';
@@ -36,6 +38,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.
@@ -83,6 +91,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: {
@@ -123,15 +135,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>;
@@ -141,11 +150,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>;
@@ -153,6 +164,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) => {
@@ -178,15 +191,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>;
@@ -195,11 +205,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>;
@@ -207,6 +219,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>;
     };
 };