@amazon/vinyl 1.2.0 → 1.2.2

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

@@ -0,0 +1,250 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { createAbortSlot, createDisposer, equalDeep, EventHostImpl, logError, } from '@amazon/vinyl-util';
+import { loadWebVttCues } from './SidecarTextTrackLoader';
+import { pickPreferredTextTrack } from './pickPreferredTextTrack';
+import { applyVttCueStyle, isVttCue } from './VttCueStyle';
+/**
+ * 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 function resolveSelectedTrack(tracks, options) {
+    const mode = options.enabled ?? 'forced';
+    if (mode === 'off')
+        return null;
+    const selection = options.selection ?? {};
+    if (selection.id != null) {
+        return tracks.find((t) => t.id === selection.id) ?? null;
+    }
+    let pool = tracks;
+    if (selection.kind != null) {
+        pool = pool.filter((t) => t.kind === selection.kind);
+    }
+    // Explicit forced filter overrides the mode's forced/full split.
+    const forced = selection.forced ?? mode === 'forced';
+    pool = pool.filter((t) => t.forced === forced);
+    // pickPreferredTextTrack falls back to navigator.languages when no language
+    // preference is supplied.
+    return pickPreferredTextTrack(pool, selection.language);
+}
+/**
+ * Manages a sidecar WebVTT-based text track lifecycle:
+ *
+ *  - 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 agnostic of HLS/DASH discovery details; its inputs are the
+ * observables supplied by the manifest layer.
+ */
+export class SidecarTextTrackController extends EventHostImpl {
+    deps;
+    get [Symbol.toStringTag]() {
+        return 'SidecarTextTrackController';
+    }
+    // Whether the owning media track is current (rendering allowed). Toggled by
+    // activate()/deactivate() across suspensions such as ad breaks.
+    _active = false;
+    _tracks = [];
+    _activeTextTrack = null;
+    // The DOM text track currently rendering cues, or null when hidden. Owned by
+    // the provider (never created/removed here).
+    _ref = null;
+    loadAbort = createAbortSlot();
+    disposer = createDisposer();
+    constructor(deps) {
+        super();
+        this.deps = deps;
+        const { add } = this.disposer;
+        // Both fire immediately with the current value, resolving the initial
+        // track list and selection on construction.
+        add(deps.options.onData(() => this.refreshSelection()));
+        add(deps.textTracks.onData((tracksPromise) => {
+            tracksPromise
+                .then((tracks) => this.setTracks(tracks))
+                .catch((error) => {
+                // Manifest errors surface through the manifest
+                // controller; just note and don't double-report.
+                logError(this, 'text tracks promise rejected', error);
+            });
+        }));
+    }
+    get textTracks() {
+        return this._tracks;
+    }
+    get activeTextTrack() {
+        return this._activeTextTrack;
+    }
+    get active() {
+        return this._active;
+    }
+    get disposed() {
+        return this.disposer.disposed;
+    }
+    /**
+     * Replaces the discovered track list, emits `textTracksChange`, then
+     * re-applies the current selection against the new list.
+     */
+    setTracks(tracks) {
+        if (this.disposed)
+            return;
+        const previous = this._tracks;
+        if (equalDeep(previous, tracks))
+            return;
+        this._tracks = tracks;
+        this.dispatch('textTracksChange', { previous, current: tracks });
+        this.refreshSelection();
+    }
+    /**
+     * Recomputes the selection from the current options and track list,
+     * emitting `activeTextTrackChange` on change and (re)rendering when active.
+     */
+    refreshSelection() {
+        const previous = this._activeTextTrack;
+        const target = resolveSelectedTrack(this._tracks, this.deps.options.value);
+        const trackChanged = target?.id !== previous?.id;
+        if (trackChanged) {
+            this._activeTextTrack = target;
+            this.dispatch('activeTextTrackChange', {
+                previous,
+                current: target,
+            });
+        }
+        if (!this._active)
+            return;
+        // Cues carry their own authored styling, so only a track change (not a
+        // same-track options change) needs a (re)load.
+        if (!target)
+            this.hideCurrent();
+        else if (trackChanged || !this._ref)
+            this.startLoad(target);
+    }
+    deactivate() {
+        this._active = false;
+        this.hideCurrent();
+    }
+    activate() {
+        this._active = true;
+        // Rebuild only when a selection exists and it isn't already rendering.
+        if (!this._activeTextTrack || this._ref)
+            return;
+        this.startLoad(this._activeTextTrack);
+    }
+    startLoad(track) {
+        // Hide the previously-rendering track (a different rendition) so its
+        // cues don't linger alongside the new one; this also aborts any prior
+        // in-flight load and arms a fresh abort for this one.
+        this.hideCurrent();
+        const abort = this.loadAbort.value;
+        const ref = this.deps.textTrackProvider.getOrCreate(track.kind, track.label, track.language ?? undefined);
+        // With an injected renderer the browser must not paint (the renderer
+        // does), but the track still needs to be active for cue timing — hence
+        // 'hidden'. Without one, 'showing' uses native rendering. Set the mode
+        // before clearing: `cues` reads null while disabled.
+        const renderer = this.deps.textTrackRenderer;
+        ref.track.mode = renderer ? 'hidden' : 'showing';
+        ref.clear();
+        this._ref = ref;
+        renderer?.setTextTrack(ref.track);
+        const CueCtor = getVttCueConstructor();
+        // Adjacent HLS caption segments commonly repeat the boundary cue in both
+        // segments (so a client that only fetches one still renders the overlap).
+        // Track seen keys per active load so we don't push the same cue twice.
+        const seen = new Set();
+        // Accumulate authored STYLE-block CSS and forward it to the renderer as
+        // it arrives — only wired when the renderer can actually consume styles.
+        const styles = new Set();
+        const setStyles = renderer?.setStyles?.bind(renderer);
+        loadWebVttCues(track.uri, {
+            abort,
+            requestInit: this.deps.requestInit,
+            variables: track.variables,
+            getCurrentTime: () => this.deps.playbackController.currentTime,
+            onCues: (cues) => {
+                if (abort.aborted())
+                    return;
+                if (CueCtor)
+                    this.appendCues(ref.track, CueCtor, cues, seen);
+            },
+            onStyles: setStyles
+                ? (blocks) => {
+                    if (abort.aborted())
+                        return;
+                    for (const block of blocks)
+                        styles.add(block);
+                    setStyles([...styles]);
+                }
+                : undefined,
+        }).catch((error) => {
+            if (abort.aborted())
+                return;
+            this.dispatch('textTrackError', {
+                track,
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        });
+    }
+    appendCues(dom, CueCtor, cues, seen) {
+        for (const cue of cues) {
+            const key = `${cue.startTime}|${cue.endTime}|${cue.text}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const domCue = new CueCtor(cue.startTime, cue.endTime, cue.text);
+            if (cue.id != null)
+                domCue.id = cue.id;
+            // Preserve the cue's own authored WebVTT settings (position, line,
+            // size, align, …). Only VTTCues carry these properties.
+            if (cue.settings && isVttCue(domCue)) {
+                applyVttCueStyle(domCue, cue.settings);
+            }
+            dom.addCue(domCue);
+        }
+    }
+    /**
+     * Clears cues from the current DOM track and hides it, keeping the track for
+     * later reuse via the provider.
+     */
+    hideCurrent() {
+        // Cancel any in-flight load: its cues are no longer wanted, and a late
+        // rejection must not surface as a textTrackError.
+        this.loadAbort.abort();
+        const ref = this._ref;
+        if (!ref)
+            return;
+        this.deps.textTrackRenderer?.setTextTrack(null);
+        ref.clear();
+        ref.track.mode = 'disabled';
+        this._ref = null;
+    }
+    /**
+     * Cancels any in-flight load, hides the DOM text track, and resets state.
+     * Called by the host when the underlying media is unloaded.
+     */
+    dispose() {
+        if (this.disposed)
+            return;
+        super.dispose();
+        this.loadAbort.abort();
+        this.hideCurrent();
+        this.disposer.dispose();
+        this._tracks = [];
+        this._activeTextTrack = null;
+    }
+}
+function getVttCueConstructor() {
+    const g = globalThis;
+    return g.VTTCue ?? g.TextTrackCue ?? null;
+}

package/dist/types/current/text/SidecarTextTrackLoader.d.ts

@@ -0,0 +1,65 @@
+import type { Maybe, ReadonlyAbort, RequestInitOptions } from '@amazon/vinyl-util';
+import { type WebVttCue } from './parseWebVtt';
+/**
+ * Seconds ahead of the playhead to keep cues buffered. Mirrors the media
+ * pipeline's default HLS `minBufferTime` so captions stay in step with the
+ * audio/video buffer.
+ */
+export declare const DEFAULT_TEXT_LOOK_AHEAD = 10;
+/**
+ * Seconds behind the playhead to keep cues buffered. Small window so that a
+ * short rewind (e.g. accidental skip-back) doesn't force a refetch.
+ */
+export declare const DEFAULT_TEXT_LOOK_BEHIND = 2;
+export interface LoadWebVttCuesOptions {
+    readonly abort?: Maybe<ReadonlyAbort>;
+    readonly requestInit?: Maybe<RequestInitOptions>;
+    /**
+     * HLS EXT-X-DEFINE variables to make available for `IMPORT` and for
+     * substitution of segment URIs when loading from an HLS media playlist.
+     */
+    readonly variables?: Maybe<Readonly<Record<string, string>>>;
+    /**
+     * Invoked with each batch of cues as soon as they are parsed. Called once
+     * 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
+     * playhead rather than draining the entire playlist up front.
+     */
+    readonly getCurrentTime: () => number;
+    /**
+     * Seconds ahead of the playhead to keep buffered. Default 10s.
+     */
+    readonly lookAhead?: Maybe<number>;
+    /**
+     * Seconds behind the playhead to keep buffered. Default 2s.
+     */
+    readonly lookBehind?: Maybe<number>;
+}
+/**
+ * Loads WebVTT cues from a URI, streaming them by playhead position.
+ *
+ * Two URI shapes are accepted:
+ *  - Direct `.vtt` document: fetched once and delivered via `onCues`.
+ *  - HLS media playlist (`.m3u8`): the playlist is parsed, then segments
+ *    whose time range overlaps the buffer window around `getCurrentTime()`
+ *    are fetched (closest to the playhead first), one at a time. Each
+ *    segment's cues are delivered via `onCues` as it is parsed.
+ *
+ * Cue start/end times are expected to already be on the presentation
+ * timeline (Shaka packager's default WebVTT output), so segments are joined
+ * without offset.
+ *
+ * The returned promise resolves once every segment has been fetched, or the
+ * abort signal fires. Fetch failures reject the promise.
+ */
+export declare function loadWebVttCues(uri: string, options: LoadWebVttCuesOptions): Promise<void>;
+//# sourceMappingURL=SidecarTextTrackLoader.d.ts.map

package/dist/types/current/text/SidecarTextTrackLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SidecarTextTrackLoader.d.ts","sourceRoot":"","sources":["../../../../src/text/SidecarTextTrackLoader.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACR,KAAK,EACL,aAAa,EACb,kBAAkB,EACrB,MAAM,oBAAoB,CAAA;AAQ3B,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,eAAe,CAAA;AAE3D;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAA;AAEzC;;;GAGG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAA;AAQzC,MAAM,WAAW,qBAAqB;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,CAAA;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAA;IAEhD;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;IAE5D;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,KAAK,IAAI,CAAA;IAErD;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC,CAAA;IAE9D;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,MAAM,CAAA;IAErC;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;IAElC;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;CACtC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,cAAc,CAChC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,qBAAqB,GAC/B,OAAO,CAAC,IAAI,CAAC,CA0Cf"}

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

@@ -0,0 +1,150 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { readResponseBody, requestWithRetry, resolveUrl, sleep, } from '@amazon/vinyl-util';
+import { parseMediaPlaylist } from '@amazon/vinyl-hls-parser';
+import { parseWebVtt } from './parseWebVtt';
+/**
+ * Seconds ahead of the playhead to keep cues buffered. Mirrors the media
+ * pipeline's default HLS `minBufferTime` so captions stay in step with the
+ * audio/video buffer.
+ */
+export const DEFAULT_TEXT_LOOK_AHEAD = 10;
+/**
+ * Seconds behind the playhead to keep cues buffered. Small window so that a
+ * short rewind (e.g. accidental skip-back) doesn't force a refetch.
+ */
+export const DEFAULT_TEXT_LOOK_BEHIND = 2;
+/**
+ * Polling interval, in seconds, when no segment is currently in the buffer
+ * window. Short enough to feel responsive after a seek without spinning.
+ */
+const IDLE_POLL_SECONDS = 0.25;
+/**
+ * Loads WebVTT cues from a URI, streaming them by playhead position.
+ *
+ * Two URI shapes are accepted:
+ *  - Direct `.vtt` document: fetched once and delivered via `onCues`.
+ *  - HLS media playlist (`.m3u8`): the playlist is parsed, then segments
+ *    whose time range overlaps the buffer window around `getCurrentTime()`
+ *    are fetched (closest to the playhead first), one at a time. Each
+ *    segment's cues are delivered via `onCues` as it is parsed.
+ *
+ * Cue start/end times are expected to already be on the presentation
+ * timeline (Shaka packager's default WebVTT output), so segments are joined
+ * without offset.
+ *
+ * The returned promise resolves once every segment has been fetched, or the
+ * abort signal fires. Fetch failures reject the promise.
+ */
+export async function loadWebVttCues(uri, options) {
+    const { abort, requestInit, variables, onCues, onStyles, getCurrentTime } = options;
+    const lookAhead = options.lookAhead ?? DEFAULT_TEXT_LOOK_AHEAD;
+    const lookBehind = options.lookBehind ?? DEFAULT_TEXT_LOOK_BEHIND;
+    const init = requestInit ?? undefined;
+    if (looksLikeMediaPlaylist(uri)) {
+        return streamMediaPlaylist({
+            uri,
+            init,
+            abort,
+            variables: variables ?? undefined,
+            onCues,
+            onStyles,
+            getCurrentTime,
+            lookAhead,
+            lookBehind,
+        });
+    }
+    const response = await requestWithRetry(uri, init, { abort });
+    const contentType = (response.headers.get('content-type') ?? '').toLowerCase();
+    const body = await readResponseBody(response, 'text');
+    if (contentType.includes('mpegurl') || body.startsWith('#EXTM3U')) {
+        return streamMediaPlaylistText({
+            text: body,
+            baseUrl: response.url || uri,
+            init,
+            abort,
+            variables: variables ?? undefined,
+            onCues,
+            onStyles,
+            getCurrentTime,
+            lookAhead,
+            lookBehind,
+        });
+    }
+    const doc = parseWebVtt(body);
+    if (doc.cues.length > 0)
+        onCues(doc.cues);
+    if (onStyles && doc.styles.length > 0)
+        onStyles(doc.styles);
+}
+function looksLikeMediaPlaylist(uri) {
+    const path = uri.split(/[?#]/)[0];
+    return path.toLowerCase().endsWith('.m3u8');
+}
+async function streamMediaPlaylist(ctx) {
+    const response = await requestWithRetry(ctx.uri, ctx.init, {
+        abort: ctx.abort,
+    });
+    const text = await readResponseBody(response, 'text');
+    return streamMediaPlaylistText({
+        ...ctx,
+        text,
+        baseUrl: response.url || ctx.uri,
+    });
+}
+async function streamMediaPlaylistText(ctx) {
+    const playlist = parseMediaPlaylist(ctx.text, ctx.variables);
+    const segments = playlist.segments;
+    // Precompute each segment's [start, end] on the presentation timeline.
+    const ranges = [];
+    let cursor = 0;
+    for (const seg of segments) {
+        ranges.push({ start: cursor, end: cursor + seg.duration });
+        cursor += seg.duration;
+    }
+    const pending = new Set(segments.map((_, i) => i));
+    while (pending.size > 0 && !ctx.abort?.aborted()) {
+        const idx = pickInWindow(pending, ranges, ctx);
+        if (idx < 0) {
+            await sleep(IDLE_POLL_SECONDS, ctx.abort).catch(() => { });
+            continue;
+        }
+        pending.delete(idx);
+        const segUri = resolveUrl(segments[idx].uri, ctx.baseUrl);
+        const res = await requestWithRetry(segUri, ctx.init, {
+            abort: ctx.abort,
+        });
+        const body = await readResponseBody(res, 'text');
+        const doc = parseWebVtt(body);
+        if (doc.cues.length > 0)
+            ctx.onCues(doc.cues);
+        if (ctx.onStyles && doc.styles.length > 0)
+            ctx.onStyles(doc.styles);
+    }
+}
+/**
+ * Selects the pending segment closest to the playhead whose time range
+ * overlaps [now - lookBehind, now + lookAhead]. Returns -1 when no pending
+ * segment intersects the window — the caller should sleep and re-check.
+ */
+function pickInWindow(pending, ranges, ctx) {
+    const now = ctx.getCurrentTime();
+    const windowStart = now - ctx.lookBehind;
+    const windowEnd = now + ctx.lookAhead;
+    let best = -1;
+    let bestDist = Number.POSITIVE_INFINITY;
+    for (const idx of pending) {
+        const r = ranges[idx];
+        if (r.end < windowStart || r.start > windowEnd)
+            continue;
+        const mid = (r.start + r.end) / 2;
+        const dist = Math.abs(mid - now);
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = idx;
+        }
+    }
+    return best;
+}

package/dist/types/current/text/TextTrack.d.ts

@@ -0,0 +1,179 @@
+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.
+ */
+export type TextTrackKind = 'subtitles' | 'captions' | 'descriptions' | 'chapters' | 'metadata';
+/**
+ * Identifies and describes an available text track.
+ * One TextTrackInfo is produced per discovered subtitle rendition.
+ */
+export interface TextTrackInfo {
+    /**
+     * A stable, unique identifier within the current media presentation.
+     */
+    readonly id: string;
+    /**
+     * The text track kind. Defaults to 'subtitles' when not otherwise specified.
+     */
+    readonly kind: TextTrackKind;
+    /**
+     * The BCP 47 language tag for the cues in this track, or null if unknown.
+     */
+    readonly language: string | null;
+    /**
+     * A human-readable label for the track.
+     */
+    readonly label: string;
+    /**
+     * Set when the source manifest signals this track as the default selection.
+     */
+    readonly default: boolean;
+    /**
+     * Whether this is a forced track: it carries essential text (e.g.
+     * translations of foreign-language dialogue) meant to be shown even when
+     * the user has not enabled subtitles. Two tracks may share a language and
+     * differ only by this flag, so selection must distinguish them.
+     */
+    readonly forced: boolean;
+    /**
+     * Media characteristics / accessibility roles describing the track, e.g.
+     * `public.accessibility.transcribes-spoken-dialog` (HLS CHARACTERISTICS) or
+     * a DASH role/accessibility scheme value. Empty when none are signaled.
+     */
+    readonly characteristics: readonly string[];
+    /**
+     * The full URL of the underlying text resource (typically a WebVTT file).
+     */
+    readonly uri: string;
+    /**
+     * The MIME type signaled by the source manifest, when known.
+     */
+    readonly mimeType: string | null;
+    /**
+     * HLS EXT-X-DEFINE variables inherited from the parent multivariant
+     * playlist. Sidecar text-track media playlists commonly `IMPORT` these
+     * names and reference them in segment URIs. Present only for HLS-sourced
+     * tracks whose parent playlist declared any variables.
+     */
+    readonly variables?: Readonly<Record<string, string>>;
+}
+/**
+ * Events dispatched by a {@link TextTrackController}.
+ */
+export interface TextTrackEventMap {
+    /**
+     * Emitted when the available text tracks change.
+     */
+    readonly textTracksChange: ChangeEvent<readonly TextTrackInfo[]>;
+    /**
+     * Emitted when the active text track changes.
+     */
+    readonly activeTextTrackChange: ChangeEvent<TextTrackInfo | null>;
+    /**
+     * Emitted when an error occurs while loading or activating a text track.
+     */
+    readonly textTrackError: TextTrackErrorEvent;
+}
+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", "textTrackError"];
+/**
+ * Read-only view of available text tracks and the active selection.
+ */
+export interface ReadonlyTextTrackController extends ReadonlyEventHost<TextTrackEventMap> {
+    /**
+     * The list of currently discovered text tracks.
+     */
+    readonly textTracks: readonly TextTrackInfo[];
+    /**
+     * 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;
+}
+/**
+ * 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 {
+    /**
+     * Suspends cue rendering without changing the active selection: cancels any
+     * 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.
+     */
+    deactivate(): void;
+    /**
+     * 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.
+     */
+    activate(): void;
+}
+//# sourceMappingURL=TextTrack.d.ts.map

package/dist/types/current/text/TextTrack.d.ts.map

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

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

@@ -0,0 +1,29 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { array, boolean, isOneOf, object, string, } from '@amazon/vinyl-validation';
+const TEXT_TRACK_KINDS = [
+    'subtitles',
+    'captions',
+    'descriptions',
+    'chapters',
+    'metadata',
+];
+const textTrackSelectionValidator = object({
+    id: string().orNull().optional(),
+    kind: isOneOf(...TEXT_TRACK_KINDS)
+        .orNull()
+        .optional(),
+    language: string().or(array(string()).readonly()).orNull().optional(),
+    forced: boolean().orNull().optional(),
+});
+export const textTrackControllerOptionsValidator = object({
+    enabled: isOneOf('on', 'off', 'forced').orNull().optional(),
+    selection: textTrackSelectionValidator.orNull().optional(),
+});
+export const ALL_TEXT_TRACK_EVENTS = [
+    'textTracksChange',
+    'activeTextTrackChange',
+    'textTrackError',
+];