@amazon/vinyl 2.0.4 → 3.0.0

package/dist/types/current/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/current/text/TextTrackRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TextTrackRenderer.d.ts","sourceRoot":"","sources":["../../../../src/text/TextTrackRenderer.ts"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAC9B;;;OAGG;IACH,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,GAAG,IAAI,CAAA;IAE3C;;;;OAIG;IACH,SAAS,CAAC,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAA;CAC9C"}

package/dist/types/current/text/TextTrackRenderer.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/types/current/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/current/text/mediaTextTrackProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediaTextTrackProvider.d.ts","sourceRoot":"","sources":["../../../../src/text/mediaTextTrackProvider.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD;;;GAGG;AACH,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IAEzB;;;;OAIG;IACH,KAAK,IAAI,IAAI,CAAA;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAsB;IACnC,WAAW,CACP,IAAI,EAAE,aAAa,EACnB,KAAK,CAAC,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,MAAM,GAClB,YAAY,CAAA;CAClB;AAED,wBAAgB,4BAA4B,CAAC,IAAI,EAAE;IAC/C;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAA;CACnC,GAAG,sBAAsB,CAwCzB"}

package/dist/types/current/text/mediaTextTrackProvider.js

@@ -0,0 +1,42 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export function createMediaTextTrackProvider(deps) {
+    const { media } = deps;
+    const cache = new Map();
+    const isAttached = (track) => {
+        for (let i = 0; i < media.textTracks.length; i++) {
+            if (media.textTracks[i] === track)
+                return true;
+        }
+        return false;
+    };
+    const create = (kind, label, language) => {
+        const track = media.addTextTrack(kind, label, language);
+        return {
+            track,
+            clear() {
+                if (!track.cues)
+                    return;
+                // Snapshot first — removeCue mutates the live list.
+                const all = Array.from(track.cues);
+                for (const cue of all)
+                    track.removeCue(cue);
+            },
+        };
+    };
+    return {
+        getOrCreate(kind, label, language) {
+            const key = `${kind}-${label}-${language}`;
+            const cached = cache.get(key);
+            // Resetting the media source (MSE `src = null; load()`) drops added
+            // tracks, so a cached track can become detached; recreate when so.
+            if (cached && isAttached(cached.track))
+                return cached;
+            const ref = create(kind, label, language);
+            cache.set(key, ref);
+            return ref;
+        },
+    };
+}

package/dist/types/current/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/current/text/parseWebVtt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parseWebVtt.d.ts","sourceRoot":"","sources":["../../../../src/text/parseWebVtt.ts"],"names":[],"mappings":"AAOA;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACtB;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IAE1B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAE1B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IAExB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,CAAA;CACtC;AAYD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAuFzD"}
+{"version":3,"file":"parseWebVtt.d.ts","sourceRoot":"","sources":["../../../../src/text/parseWebVtt.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEhD;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACtB;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IAE1B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAE1B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IAExB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,CAAA;IAEnC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC;AAeD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAoGzD"}

package/dist/types/current/text/parseWebVtt.js

@@ -4,103 +4,153 @@
  */
 import { ErrorOrigin, ValidationError } from '@amazon/vinyl-util';
 const WEBVTT_HEADER = 'WEBVTT';
-// Trailing cue settings are tolerated but ignored. They are separated from the
-// end timestamp by whitespace, so the tail is matched as an optional group that
-// begins with a whitespace character. Using `(?:\s.*)?$` rather than `\s*(.*)$`
-// avoids the ambiguous overlap between `\s*` and `.*` (both match spaces), which
-// would allow polynomial backtracking on space-heavy input.
-const TIME_RE = /^\s*(?:(\d+):)?([0-5]?\d):([0-5]?\d)\.(\d{3})\s*-->\s*(?:(\d+):)?([0-5]?\d):([0-5]?\d)\.(\d{3})(?:\s.*)?$/;
+// A single WebVTT timestamp anchored at the start: `[ hours ":" ] minutes ":"
+// seconds "." ms`, with hours two-or-more digits (optional), minutes/seconds
+// two digits in 0-59, and milliseconds three digits (per the spec's "collect a
+// WebVTT timestamp"). Timestamp collection stops after the milliseconds — it is
+// NOT anchored at the end — so the start match must be checked to consume its
+// whole (pre-`-->`) token, while for the end match any remainder is cue
+// settings. The only unbounded quantifier is `\d+`, followed by a literal `:`
+// (no nested/overlapping quantifiers), so it matches in linear time, and it
+// only ever runs against a single short token — backtracking is a non-issue.
+const TIMESTAMP_RE = /^(?:(\d+):)?([0-5]\d):([0-5]\d)\.(\d{3})/;
 /**
  * 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 function parseWebVtt(input) {
     if (typeof input !== 'string') {
         throw new ValidationError('WebVTT input must be a string', ErrorOrigin.MEDIA);
     }
     let text = input;
-    // Strip BOM
+    // Strip a leading BOM, then normalize line endings.
     if (text.charCodeAt(0) === 0xfeff)
         text = text.slice(1);
-    // Normalize line endings
     const lines = text.split(/\r\n|\r|\n/);
     if (lines.length === 0 || !isWebVttHeader(lines[0])) {
         throw new ValidationError('WebVTT must begin with a WEBVTT header', ErrorOrigin.MEDIA);
     }
     const cues = [];
+    const styles = [];
     // Per the WebVTT spec, everything from the `WEBVTT` signature up to (and
-    // including) the first blank line is the file header — any metadata
-    // header lines (e.g. HLS's `X-TIMESTAMP-MAP=...`) belong in that block
-    // and MUST NOT be interpreted as cue content.
+    // including) the first blank line is the file header — metadata lines (e.g.
+    // HLS's `X-TIMESTAMP-MAP=...`) belong in that block and MUST NOT be
+    // interpreted as cue content.
     let i = 1;
     while (i < lines.length && lines[i] !== '')
         i++;
     while (i < lines.length) {
-        // Skip empty lines between blocks.
+        // Skip blank lines between blocks.
         if (lines[i] === '') {
             i++;
             continue;
         }
-        // NOTE comment block: skip until blank line.
-        if (lines[i] === 'NOTE' || lines[i].startsWith('NOTE ')) {
+        // NOTE comment / REGION blocks: skip until the blank line. A NOTE line
+        // is `NOTE` alone or `NOTE` followed by whitespace (space or tab).
+        if (lines[i] === 'NOTE' ||
+            lines[i].startsWith('NOTE ') ||
+            lines[i].startsWith('NOTE\t') ||
+            lines[i] === 'REGION') {
             i++;
             while (i < lines.length && lines[i] !== '')
                 i++;
             continue;
         }
-        // STYLE / REGION blocks - skip until blank line.
-        if (lines[i] === 'STYLE' || lines[i] === 'REGION') {
+        // STYLE block: capture its CSS body (up to the blank line).
+        if (lines[i] === 'STYLE') {
             i++;
+            const start = i;
             while (i < lines.length && lines[i] !== '')
                 i++;
+            const css = lines.slice(start, i).join('\n').trim();
+            if (css)
+                styles.push(css);
             continue;
         }
-        // Cue: optional identifier, then a timing line, then payload.
+        // Cue: an optional identifier line, then a timing line, then payload.
+        // A cue identifier never contains `-->`, so a line without it is the
+        // identifier and the timing line follows (spec: "collect a WebVTT
+        // block").
         let id = null;
-        let timingLine;
-        const firstLine = lines[i];
-        if (TIME_RE.test(firstLine)) {
-            timingLine = firstLine;
-            i++;
-        }
-        else {
-            id = firstLine;
+        if (!lines[i].includes('-->')) {
+            id = lines[i];
             i++;
             if (i >= lines.length)
-                break;
-            timingLine = lines[i];
-            i++;
+                break; // identifier with no timing line
         }
-        const match = TIME_RE.exec(timingLine);
-        if (!match) {
-            // Skip malformed cue: drain to next blank line.
+        const timing = parseTiming(lines[i]);
+        i++;
+        if (!timing) {
+            // Malformed timing line: drain to the next blank line.
             while (i < lines.length && lines[i] !== '')
                 i++;
             continue;
         }
-        const startTime = toSeconds(match[1], match[2], match[3], match[4]);
-        const endTime = toSeconds(match[5], match[6], match[7], match[8]);
         const payloadLines = [];
         while (i < lines.length && lines[i] !== '') {
             payloadLines.push(lines[i]);
             i++;
         }
-        cues.push({
-            id,
-            startTime,
-            endTime,
-            text: payloadLines.join('\n'),
-        });
+        const text = payloadLines.join('\n');
+        // Omit the optional `settings` key entirely when there are none.
+        cues.push(timing.settings === undefined
+            ? {
+                id,
+                startTime: timing.startTime,
+                endTime: timing.endTime,
+                text,
+            }
+            : {
+                id,
+                startTime: timing.startTime,
+                endTime: timing.endTime,
+                text,
+                settings: timing.settings,
+            });
     }
-    return { cues };
+    return { cues, styles };
+}
+/**
+ * Parses a WebVTT timing line ("start --> end settings"), returning the two
+ * times (in seconds) and any parsed cue settings, or null if it is not a valid
+ * timing line. Splitting on the literal `-->` (and on the whitespace before the
+ * settings) keeps each timestamp match a fixed, anchored token.
+ */
+function parseTiming(line) {
+    const arrow = line.indexOf('-->');
+    if (arrow < 0)
+        return null;
+    // Before the arrow: only the start timestamp (whitespace-trimmed), so the
+    // match must consume the whole token.
+    const before = line.slice(0, arrow).trim();
+    const start = TIMESTAMP_RE.exec(before);
+    if (!start || start[0].length !== before.length)
+        return null;
+    // After the arrow: the end timestamp, then whatever follows is cue settings.
+    const rest = line.slice(arrow + 3).trim();
+    const end = TIMESTAMP_RE.exec(rest);
+    if (!end)
+        return null;
+    return {
+        startTime: toSeconds(start[1], start[2], start[3], start[4]),
+        endTime: toSeconds(end[1], end[2], end[3], end[4]),
+        settings: parseCueSettings(rest.slice(end[0].length)),
+    };
+}
+function toSeconds(hours, minutes, seconds, millis) {
+    return ((hours ? Number(hours) * 3600 : 0) +
+        Number(minutes) * 60 +
+        Number(seconds) +
+        Number(millis) / 1000);
 }
 function isWebVttHeader(line) {
     if (!line.startsWith(WEBVTT_HEADER))
@@ -111,10 +161,88 @@ function isWebVttHeader(line) {
     // Header may be followed by space, tab, or any text after a separator.
     return next === 0x20 || next === 0x09;
 }
-function toSeconds(hours, minutes, seconds, millis) {
-    const h = hours ? Number(hours) : 0;
-    const m = Number(minutes);
-    const s = Number(seconds);
-    const ms = Number(millis);
-    return h * 3600 + m * 60 + s + ms / 1000;
+const ALIGN = new Set(['start', 'center', 'end', 'left', 'right']);
+const LINE_ALIGN = new Set(['start', 'center', 'end']);
+const POSITION_ALIGN = new Set(['line-left', 'center', 'line-right', 'auto']);
+const VERTICAL = new Set(['rl', 'lr']);
+/**
+ * Parses the cue-settings tail of a timing line (e.g.
+ * `align:center line:80% position:50%,center size:90% vertical:rl`) into a
+ * {@link VttCueStyle}. Unknown keys and malformed values are skipped; returns
+ * undefined when nothing valid was found.
+ */
+function parseCueSettings(text) {
+    if (!text)
+        return undefined;
+    const settings = {};
+    for (const token of text.trim().split(/\s+/)) {
+        const colon = token.indexOf(':');
+        if (colon <= 0)
+            continue;
+        const key = token.slice(0, colon);
+        const value = token.slice(colon + 1);
+        switch (key) {
+            case 'align': {
+                // 'middle' is the legacy spelling of 'center'.
+                const align = value === 'middle' ? 'center' : value;
+                if (ALIGN.has(align))
+                    settings.align = align;
+                break;
+            }
+            case 'vertical':
+                if (VERTICAL.has(value))
+                    settings.vertical = value;
+                break;
+            case 'size': {
+                const size = parsePercent(value);
+                if (size != null)
+                    settings.size = size;
+                break;
+            }
+            case 'line':
+                parseLine(value, settings);
+                break;
+            case 'position':
+                parsePosition(value, settings);
+                break;
+        }
+    }
+    return Object.keys(settings).length > 0 ? settings : undefined;
+}
+function parseLine(value, settings) {
+    const [pos, align] = value.split(',');
+    if (pos.endsWith('%')) {
+        const percent = parsePercent(pos);
+        if (percent == null)
+            return;
+        settings.line = percent;
+        settings.snapToLines = false;
+    }
+    else {
+        const n = Number(pos);
+        if (!Number.isInteger(n))
+            return;
+        settings.line = n;
+        settings.snapToLines = true;
+    }
+    const lineAlign = align === 'middle' ? 'center' : align;
+    if (lineAlign && LINE_ALIGN.has(lineAlign))
+        settings.lineAlign = lineAlign;
+}
+function parsePosition(value, settings) {
+    const [pos, align] = value.split(',');
+    const percent = parsePercent(pos);
+    if (percent == null)
+        return;
+    settings.position = percent;
+    const positionAlign = align === 'middle' ? 'center' : align;
+    if (positionAlign && POSITION_ALIGN.has(positionAlign))
+        settings.positionAlign = positionAlign;
+}
+/** Parses an `N%` token to its numeric percentage, or null when malformed. */
+function parsePercent(value) {
+    if (!value.endsWith('%'))
+        return null;
+    const n = Number(value.slice(0, -1));
+    return Number.isFinite(n) ? n : null;
 }

package/dist/types/current/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/current/text/pickPreferredTextTrack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pickPreferredTextTrack.d.ts","sourceRoot":"","sources":["../../../../src/text/pickPreferredTextTrack.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAgBhD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAClC,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,SAAS,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,IAAI,GAC7C,aAAa,GAAG,IAAI,CActB"}
+{"version":3,"file":"pickPreferredTextTrack.d.ts","sourceRoot":"","sources":["../../../../src/text/pickPreferredTextTrack.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAkB/C;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAClC,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,SAAS,EAAE,KAAK,CAAC,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC,GAC7C,aAAa,GAAG,IAAI,CActB"}

package/dist/types/current/text/pickPreferredTextTrack.js

@@ -5,15 +5,18 @@
 import { languageRelatedness } from '../track/filters/languageFilter';
 /**
  * Resolves the preferred-text-language option to an ordered list of BCP 47
- * tags, most-preferred first. Unlike the audio equivalent, `null` resolves to
- * an empty list (no preference) rather than falling back to
- * `navigator.languages` — captions default to off.
+ * tags, most-preferred first. A string becomes a single-element list; an array
+ * is used as-is; unset (null/undefined) falls back to the platform's
+ * `navigator.languages`. Returns an empty list only when there is no preference
+ * and no `navigator.languages` — in which case nothing is selected.
  */
 function resolvePreferredTextLanguages(preferred) {
     if (typeof preferred === 'string')
         return [preferred];
     if (preferred)
         return preferred;
+    if (typeof navigator !== 'undefined')
+        return [...navigator.languages];
     return [];
 }
 /**

package/dist/types/current/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/current/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

package/dist/types/current/track/dash/createDashFactories.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createDashFactories.d.ts","sourceRoot":"","sources":["../../../../../src/track/dash/createDashFactories.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"createDashFactories.d.ts","sourceRoot":"","sources":["../../../../../src/track/dash/createDashFactories.ts"],"names":[],"mappings":"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"}