@amazon/vinyl 1.1.1 → 1.2.1

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 { 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 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 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 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',
+];

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/VttCueStyle.d.ts

@@ -0,0 +1,41 @@
+import type { ObjectSchema } from '@amazon/vinyl-validation';
+/**
+ * Layout style applied to each rendered WebVTT cue, mirroring the settable
+ * positioning properties of the DOM `VTTCue`. Only the properties that are set
+ * are applied; the rest keep the browser defaults.
+ *
+ * These are the WebVTT cue-box layout controls (not text color/font, which are
+ * only reachable via the non-configurable `::cue` pseudo-element). See
+ * {@link https://developer.mozilla.org/docs/Web/API/VTTCue}.
+ */
+export interface VttCueStyle {
+    /** Text alignment within the cue box. */
+    readonly align?: AlignSetting;
+    /** Line (vertical) position, as a line number/percentage or `'auto'`. */
+    readonly line?: number | AutoKeyword;
+    /** How `line` is anchored. */
+    readonly lineAlign?: LineAlignSetting;
+    /** Inline position of the cue box, as a percentage or `'auto'`. */
+    readonly position?: number | AutoKeyword;
+    /** How `position` is anchored. */
+    readonly positionAlign?: PositionAlignSetting;
+    /** Size of the cue box as a percentage of the video dimension. */
+    readonly size?: number;
+    /** Whether `line` is a line number (true) or a percentage (false). */
+    readonly snapToLines?: boolean;
+    /** Writing direction. */
+    readonly vertical?: DirectionSetting;
+}
+/**
+ * Type guard for a DOM cue that is a `VTTCue` (and so carries the WebVTT layout
+ * properties). On platforms without `VTTCue`, cues are plain `TextTrackCue`s
+ * that cannot be styled.
+ */
+export declare function isVttCue(cue: TextTrackCue): cue is VTTCue;
+/**
+ * Applies the configured layout style to a `VTTCue`, setting only the
+ * properties present in `style`.
+ */
+export declare function applyVttCueStyle(cue: VTTCue, style: VttCueStyle): void;
+export declare const vttCueStyleValidator: ObjectSchema<VttCueStyle>;
+//# sourceMappingURL=VttCueStyle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VttCueStyle.d.ts","sourceRoot":"","sources":["../../../../src/text/VttCueStyle.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAG5D;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IACxB,yCAAyC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAA;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,CAAA;IACpC,8BAA8B;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAA;IACrC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,CAAA;IACxC,kCAAkC;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,oBAAoB,CAAA;IAC7C,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,sEAAsE;IACtE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;IAC9B,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAA;CACvC;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,GAAG,IAAI,MAAM,CAEzD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAUtE;AAED,eAAO,MAAM,oBAAoB,EAAE,YAAY,CAAC,WAAW,CAczD,CAAA"}

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

@@ -0,0 +1,45 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { boolean, isOneOf, number, object } from '@amazon/vinyl-validation';
+/**
+ * Type guard for a DOM cue that is a `VTTCue` (and so carries the WebVTT layout
+ * properties). On platforms without `VTTCue`, cues are plain `TextTrackCue`s
+ * that cannot be styled.
+ */
+export function isVttCue(cue) {
+    return typeof VTTCue !== 'undefined' && cue instanceof VTTCue;
+}
+/**
+ * Applies the configured layout style to a `VTTCue`, setting only the
+ * properties present in `style`.
+ */
+export function applyVttCueStyle(cue, style) {
+    if (style.align !== undefined)
+        cue.align = style.align;
+    if (style.line !== undefined)
+        cue.line = style.line;
+    if (style.lineAlign !== undefined)
+        cue.lineAlign = style.lineAlign;
+    if (style.position !== undefined)
+        cue.position = style.position;
+    if (style.positionAlign !== undefined)
+        cue.positionAlign = style.positionAlign;
+    if (style.size !== undefined)
+        cue.size = style.size;
+    if (style.snapToLines !== undefined)
+        cue.snapToLines = style.snapToLines;
+    if (style.vertical !== undefined)
+        cue.vertical = style.vertical;
+}
+export const vttCueStyleValidator = object({
+    align: isOneOf('start', 'center', 'end', 'left', 'right').optional(),
+    line: number().or(isOneOf('auto')).optional(),
+    lineAlign: isOneOf('start', 'center', 'end').optional(),
+    position: number().or(isOneOf('auto')).optional(),
+    positionAlign: isOneOf('line-left', 'center', 'line-right', 'auto').optional(),
+    size: number().optional(),
+    snapToLines: boolean().optional(),
+    vertical: isOneOf('', 'rl', 'lr').optional(),
+});

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

@@ -0,0 +1,24 @@
+import type { DashManifest } from '@amazon/vinyl-mpd-parser';
+import type { TextTrackInfo } from './TextTrack';
+/**
+ * Discovers sidecar text tracks from a DASH manifest.
+ *
+ * Considers an `<AdaptationSet>` to carry text when one of:
+ *  - `contentType="text"`
+ *  - `mimeType` starts with `text/` (e.g. `text/vtt`)
+ *  - `mimeType` is `application/mp4` *and* the codec/role indicates text
+ *
+ * Within a text adaptation set, each `<Representation>` becomes one
+ * {@link TextTrackInfo}. The `BaseURL` chain (MPD → Period → AdaptationSet →
+ * Representation) is resolved against the supplied `baseUrl`.
+ *
+ * Only sidecar (single-file) WebVTT renditions are surfaced. Segmented text
+ * tracks (`stpp`/`wvtt` codecs) are ignored - they would require streaming
+ * through MSE which the sidecar pipeline does not support.
+ *
+ * @param manifest The parsed DASH manifest.
+ * @param baseUrl The URL of the manifest, used as the root for `BaseURL`
+ * resolution.
+ */
+export declare function discoverDashTextTracks(manifest: DashManifest, baseUrl: string): readonly TextTrackInfo[];
+//# sourceMappingURL=discoverDashTextTracks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"discoverDashTextTracks.d.ts","sourceRoot":"","sources":["../../../../src/text/discoverDashTextTracks.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAE5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CAClC,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,MAAM,GAChB,SAAS,aAAa,EAAE,CAwD1B"}

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

@@ -0,0 +1,109 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { resolveUrl } from '@amazon/vinyl-util';
+/**
+ * Discovers sidecar text tracks from a DASH manifest.
+ *
+ * Considers an `<AdaptationSet>` to carry text when one of:
+ *  - `contentType="text"`
+ *  - `mimeType` starts with `text/` (e.g. `text/vtt`)
+ *  - `mimeType` is `application/mp4` *and* the codec/role indicates text
+ *
+ * Within a text adaptation set, each `<Representation>` becomes one
+ * {@link TextTrackInfo}. The `BaseURL` chain (MPD → Period → AdaptationSet →
+ * Representation) is resolved against the supplied `baseUrl`.
+ *
+ * Only sidecar (single-file) WebVTT renditions are surfaced. Segmented text
+ * tracks (`stpp`/`wvtt` codecs) are ignored - they would require streaming
+ * through MSE which the sidecar pipeline does not support.
+ *
+ * @param manifest The parsed DASH manifest.
+ * @param baseUrl The URL of the manifest, used as the root for `BaseURL`
+ * resolution.
+ */
+export function discoverDashTextTracks(manifest, baseUrl) {
+    const out = [];
+    const periods = manifest.MPD.Period;
+    const mpdBase = chainBase(baseUrl, manifest.MPD.BaseURL);
+    for (let p = 0; p < periods.length; p++) {
+        const period = periods[p];
+        const periodBase = chainBase(mpdBase, period.BaseURL);
+        const adaptationSets = period.AdaptationSet ?? [];
+        for (const adaptationSet of adaptationSets) {
+            if (!isTextAdaptationSet(adaptationSet))
+                continue;
+            const asBase = chainBase(periodBase, adaptationSet.BaseURL);
+            const representations = adaptationSet.Representation ?? [];
+            for (const representation of representations) {
+                const repBase = chainBase(asBase, representation.BaseURL);
+                const uri = pickRepresentationUri(repBase, representation.id);
+                const mimeType = representation.mimeType ?? adaptationSet.mimeType ?? null;
+                // Only surface sidecar formats. Segmented text (stpp/wvtt) is
+                // intentionally skipped.
+                if (!isSidecarTextMime(mimeType))
+                    continue;
+                const language = adaptationSet.lang ?? null;
+                const roleValues = (adaptationSet.Role ?? [])
+                    .filter((d) => d.schemeIdUri === 'urn:mpeg:dash:role:2011')
+                    .map((d) => d.value)
+                    .filter((v) => v != null);
+                // Accessibility descriptors (e.g. SDH / hard-of-hearing) also
+                // describe the track's role; surface them as characteristics.
+                const accessibility = (adaptationSet.Accessibility ?? [])
+                    .map((d) => d.value)
+                    .filter((v) => v != null);
+                const characteristics = [...roleValues, ...accessibility];
+                const isCaption = roleValues.includes('caption');
+                const isDefault = roleValues.includes('main');
+                // DASH signals forced text via the `forced_subtitle` /
+                // `forced-subtitle` role value.
+                const forced = roleValues.includes('forced_subtitle') ||
+                    roleValues.includes('forced-subtitle');
+                out.push({
+                    id: `dash-text-${p}-${representation.id}`,
+                    kind: isCaption ? 'captions' : 'subtitles',
+                    language,
+                    label: language ?? representation.id,
+                    default: isDefault,
+                    forced,
+                    characteristics,
+                    uri,
+                    mimeType,
+                });
+            }
+        }
+    }
+    return out;
+}
+function isTextAdaptationSet(adaptationSet) {
+    if (adaptationSet.contentType === 'text')
+        return true;
+    const mt = adaptationSet.mimeType;
+    if (mt && mt.startsWith('text/'))
+        return true;
+    return false;
+}
+function isSidecarTextMime(mimeType) {
+    // Permissive when manifest omits the MIME type, otherwise require a
+    // text/* MIME type. Segmented codec-only types like application/mp4
+    // (used with stpp/wvtt codecs) are excluded.
+    if (mimeType == null)
+        return true;
+    return mimeType.startsWith('text/');
+}
+function chainBase(parent, bases) {
+    if (!bases || bases.length === 0)
+        return parent;
+    return resolveUrl(bases[0]._content, parent);
+}
+function pickRepresentationUri(base, id) {
+    // For a sidecar text representation, the BaseURL is expected to point at
+    // the file. When the chain ends in a directory (trailing `/`), append a
+    // conventional `<id>.vtt` filename so the loader can fetch the resource.
+    if (base.endsWith('/')) {
+        return resolveUrl(`${id}.vtt`, base);
+    }
+    return base;
+}

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

@@ -0,0 +1,19 @@
+import type { HlsMainPlaylist } from '@amazon/vinyl-hls-parser';
+import type { TextTrackInfo } from './TextTrack';
+/**
+ * Discovers sidecar text tracks from an HLS multivariant playlist.
+ *
+ * Per RFC 8216 §4.3.4.2, subtitle renditions are signaled with
+ * `EXT-X-MEDIA:TYPE=SUBTITLES` and (when usable as sidecar) carry a `URI`
+ * attribute pointing at a media playlist or, in the simplified single-file
+ * case, a `.vtt` file directly.
+ *
+ * Closed captions (`TYPE=CLOSED-CAPTIONS`) are intentionally excluded - they
+ * are delivered in-band with the video stream and are surfaced by the browser
+ * automatically, not through a sidecar fetch.
+ *
+ * @param mainPlaylist The parsed HLS main playlist.
+ * @param baseUrl The URL of the main playlist, used to resolve relative URIs.
+ */
+export declare function discoverHlsTextTracks(mainPlaylist: HlsMainPlaylist, baseUrl: string): readonly TextTrackInfo[];
+//# sourceMappingURL=discoverHlsTextTracks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"discoverHlsTextTracks.d.ts","sourceRoot":"","sources":["../../../../src/text/discoverHlsTextTracks.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAE/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACjC,YAAY,EAAE,eAAe,EAC7B,OAAO,EAAE,MAAM,GAChB,SAAS,aAAa,EAAE,CA2B1B"}