@amazon/vinyl 1.2.0 → 2.0.4

package/dist/types/current/streaming/mediaTimelineLanguageFilter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mediaTimelineLanguageFilter.d.ts","sourceRoot":"","sources":["../../../../src/streaming/mediaTimelineLanguageFilter.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAOzD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAChC,iBAAiB,EAAE,MAAM,GAAG,IAAI,EAChC,WAAW,EAAE,MAAM,GACpB,eAAe,CAAC,oBAAoB,CAAC,GAAG,IAAI,CAyB9C"}
+{"version":3,"file":"mediaTimelineLanguageFilter.d.ts","sourceRoot":"","sources":["../../../../src/streaming/mediaTimelineLanguageFilter.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAIzD;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACrC,SAAS,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,IAAI,GAC7C,SAAS,MAAM,EAAE,CAKnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAChC,iBAAiB,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,IAAI,EACpD,WAAW,EAAE,MAAM,GACpB,eAAe,CAAC,oBAAoB,CAAC,GAAG,IAAI,CAyC9C"}

package/dist/types/current/streaming/mediaTimelineLanguageFilter.js

@@ -3,34 +3,79 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { memoize } from '@amazon/vinyl-util';
-import { findBestLanguageMatch, languageRelatedness, } from '../track/filters/languageFilter';
+import { languageRelatedness } from '../track/filters/languageFilter';
 /**
- * Creates a filter predicate that keeps qualities matching the preferred language.
- * The best language match is computed per period (per unique array reference),
- * so periods with different available languages are handled independently.
+ * Resolves the preferred-language option to an ordered list of BCP 47 tags,
+ * most-preferred first.
  *
- * Qualities not matching the content type or without a language tag are always kept.
+ * - a string becomes a single-element list
+ * - an array is used as-is (already ordered)
+ * - `null` falls back to the platform's `navigator.languages` order — `null`
+ *   means "use the platform preference", not "no preference"
+ * - an empty list (empty array, or `navigator.languages` unavailable) means no
+ *   preference: keep all languages
+ */
+export function resolvePreferredLanguages(preferred) {
+    if (typeof preferred === 'string')
+        return [preferred];
+    if (preferred)
+        return preferred;
+    if (typeof navigator !== 'undefined')
+        return [...navigator.languages];
+    return [];
+}
+/**
+ * Creates a filter predicate that keeps the qualities best matching the
+ * preferred language(s). The preference is an ordered list (see
+ * {@link resolvePreferredLanguages}): earlier entries win, and relatedness
+ * (exact > parent > sibling > child) breaks ties within a single preference.
  *
- * @param preferredLanguage BCP 47 language tag, or null to keep all.
+ * The best match is computed per period (per unique array reference), so
+ * periods with different available languages are handled independently. When no
+ * available language relates to any preference, all are kept (playback is never
+ * stranded). Qualities not matching the content type, or without a language
+ * tag, are always kept.
+ *
+ * @param preferredLanguage BCP 47 tag, ordered list of tags, or null (which
+ *   falls back to `navigator.languages`).
  * @param contentType Only filter qualities matching this content type (e.g. 'audio').
  */
 export function createLanguageFilter(preferredLanguage, contentType) {
-    if (!preferredLanguage)
+    const preferences = resolvePreferredLanguages(preferredLanguage);
+    if (preferences.length === 0)
         return null;
-    // Finds the best language for the period by relevance.
-    // If no languages are related, the first language will be chosen.
-    const bestRelevanceForPeriod = memoize((array) => {
-        const langs = Array.from(array)
-            .filter((q) => q.contentType === contentType && q.lang)
-            .map((q) => q.lang);
-        return languageRelatedness(preferredLanguage, findBestLanguageMatch(preferredLanguage, langs));
+    // Ranks a language against the ordered preference list. Earlier preferences
+    // dominate (weighted by list position); relatedness breaks ties within one.
+    // 0 means the language is unrelated to every preference.
+    const scoreLang = (lang) => {
+        let best = 0;
+        for (let i = 0; i < preferences.length; i++) {
+            const rel = languageRelatedness(preferences[i], lang);
+            if (rel > 0) {
+                best = Math.max(best, (preferences.length - i) * 10 + rel);
+            }
+        }
+        return best;
+    };
+    // The best score among the period's languages, memoized per unique array.
+    const bestScoreForPeriod = memoize((array) => {
+        let best = 0;
+        for (const quality of Array.from(array)) {
+            if (quality.contentType === contentType && quality.lang) {
+                best = Math.max(best, scoreLang(quality.lang));
+            }
+        }
+        return best;
     }, (array) => array, 1);
     return (quality, _index, array) => {
         if (quality.contentType !== contentType)
             return true;
         if (!quality.lang)
             return true;
-        const bestScore = bestRelevanceForPeriod(array);
-        return languageRelatedness(preferredLanguage, quality.lang) >= bestScore;
+        const best = bestScoreForPeriod(array);
+        // Nothing matched any preference; keep all rather than strand playback.
+        if (best === 0)
+            return true;
+        return scoreLang(quality.lang) === best;
     };
 }

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

@@ -0,0 +1,91 @@
+import { EventHostImpl, type Maybe, type RequestInitOptions } from '@amazon/vinyl-util';
+import type { TextTrackController, TextTrackEventMap, TextTrackInfo } from './TextTrack';
+import type { ObservableValue } from '@amazon/vinyl-observable';
+import { type VttCueStyle } from './VttCueStyle';
+export interface SidecarTextTrackControllerDeps {
+    /**
+     * The HTML media element on which to attach the in-band TextTrack
+     * representation. Cues for the active text track are added to a TextTrack
+     * created via `media.addTextTrack`. Setting this to null disables DOM
+     * integration; cues are still loaded and surfaced via events.
+     */
+    readonly media: HTMLMediaElement | null;
+    /**
+     * Optional request init options forwarded with each VTT fetch (e.g. CORS).
+     */
+    readonly requestInit?: Maybe<RequestInitOptions>;
+    /**
+     * Preferred caption language(s), most-preferred first. A non-null
+     * preference auto-selects the best-matching track, re-applied as the track
+     * list changes. Changing the preference to null clears the selection
+     * (captions off). An initial null (or an absent observable) is "no
+     * preference": forced tracks still auto-select until the app makes an
+     * explicit choice — it does not force captions off.
+     */
+    readonly preferredTextLanguage?: ObservableValue<string | readonly string[] | null>;
+    /**
+     * Layout style applied to each rendered VTTCue (see
+     * {@link VttCueStyle}). Read per cue as it is appended, so a change affects
+     * subsequently-rendered cues. Absent means no styling (browser defaults).
+     */
+    readonly cueStyle?: ObservableValue<VttCueStyle | null>;
+}
+/**
+ * Manages a sidecar WebVTT-based text track lifecycle:
+ *
+ *  - holds a discovered list of {@link TextTrackInfo}
+ *  - on activation, fetches the chosen track's WebVTT and pushes cues to a
+ *    `TextTrack` created on the `HTMLMediaElement`
+ *  - clears any previously activated cues when switching tracks
+ *
+ * The controller is intentionally agnostic of HLS/DASH discovery details. Its
+ * input is whatever list of {@link TextTrackInfo} entries the manifest layer
+ * decides to surface.
+ */
+export declare class SidecarTextTrackController extends EventHostImpl<TextTrackEventMap> implements TextTrackController {
+    private readonly deps;
+    get [Symbol.toStringTag](): string;
+    private _tracks;
+    private _active;
+    private _domTrack;
+    private loadAbort;
+    private _userSelected;
+    private readonly preferredLanguageSub;
+    constructor(deps: SidecarTextTrackControllerDeps);
+    get textTracks(): readonly TextTrackInfo[];
+    get activeTextTrack(): TextTrackInfo | null;
+    /**
+     * Replaces the discovered text track list. Emits `textTracksChange`. If
+     * the previously active track is no longer present, clears the active
+     * selection and emits `activeTextTrackChange`.
+     */
+    setTextTracks(tracks: readonly TextTrackInfo[]): void;
+    setActiveTextTrack(id: string | null): void;
+    /**
+     * Selects the track best matching the preferred language(s), or clears the
+     * selection when the preference is null or nothing matches.
+     */
+    private applyPreferredLanguage;
+    /**
+     * Applies a selection by id (null clears it) without marking it as an
+     * explicit user choice. Shared by setActiveTextTrack and forced auto-select.
+     */
+    private selectById;
+    /**
+     * The forced track to auto-select, or null. Prefers the default track's
+     * language, else the first forced track.
+     */
+    private pickForcedTrack;
+    suspend(): void;
+    resume(): void;
+    /**
+     * Cancels any in-flight load, clears the DOM TextTrack, and resets state.
+     * Called by the host when the underlying media is unloaded.
+     */
+    dispose(): void;
+    private startLoad;
+    private ensureDomTrack;
+    private appendCues;
+    private clearDomTrack;
+}
+//# sourceMappingURL=SidecarTextTrackController.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SidecarTextTrackController.d.ts","sourceRoot":"","sources":["../../../../src/text/SidecarTextTrackController.ts"],"names":[],"mappings":"AAKA,OAAO,EAGH,aAAa,EACb,KAAK,KAAK,EACV,KAAK,kBAAkB,EAE1B,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EACR,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EAChB,MAAM,aAAa,CAAA;AAGpB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAE/D,OAAO,EAA8B,KAAK,WAAW,EAAE,MAAM,eAAe,CAAA;AAE5E,MAAM,WAAW,8BAA8B;IAC3C;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAA;IAEvC;;OAEG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAA;IAEhD;;;;;;;OAOG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,eAAe,CAC5C,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,IAAI,CACpC,CAAA;IAED;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;CAC1D;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,0BACT,SAAQ,aAAa,CAAC,iBAAiB,CACvC,YAAW,mBAAmB;IAelB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAbjC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,MAAM,CAEjC;IAED,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,SAAS,CAAqB;IAGtC,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAoB;gBAE5B,IAAI,EAAE,8BAA8B;IAQjE,IAAI,UAAU,IAAI,SAAS,aAAa,EAAE,CAEzC;IAED,IAAI,eAAe,IAAI,aAAa,GAAG,IAAI,CAE1C;IAED;;;;OAIG;IACH,aAAa,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,GAAG,IAAI;IAuBrD,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAM3C;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAO9B;;;OAGG;IACH,OAAO,CAAC,UAAU;IAiBlB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAavB,OAAO,IAAI,IAAI;IAMf,MAAM,IAAI,IAAI;IAQd;;;OAGG;IACH,OAAO,IAAI,IAAI;IAUf,OAAO,CAAC,SAAS;IAoCjB,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,UAAU;IAuBlB,OAAO,CAAC,aAAa;CAexB"}

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

@@ -0,0 +1,237 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Abort, equalDeep, EventHostImpl, } from '@amazon/vinyl-util';
+import { loadWebVttCues } from './SidecarTextTrackLoader';
+import { pickPreferredTextTrack } from './pickPreferredTextTrack';
+import { applyVttCueStyle, isVttCue } from './VttCueStyle';
+/**
+ * Manages a sidecar WebVTT-based text track lifecycle:
+ *
+ *  - holds a discovered list of {@link TextTrackInfo}
+ *  - on activation, fetches the chosen track's WebVTT and pushes cues to a
+ *    `TextTrack` created on the `HTMLMediaElement`
+ *  - clears any previously activated cues when switching tracks
+ *
+ * The controller is intentionally agnostic of HLS/DASH discovery details. Its
+ * input is whatever list of {@link TextTrackInfo} entries the manifest layer
+ * decides to surface.
+ */
+export class SidecarTextTrackController extends EventHostImpl {
+    deps;
+    get [Symbol.toStringTag]() {
+        return 'SidecarTextTrackController';
+    }
+    _tracks = [];
+    _active = null;
+    _domTrack = null;
+    loadAbort = null;
+    // True once the app has made an explicit selection (including null). Until
+    // then, forced tracks auto-select on discovery.
+    _userSelected = false;
+    preferredLanguageSub;
+    constructor(deps) {
+        super();
+        this.deps = deps;
+        this.preferredLanguageSub =
+            deps.preferredTextLanguage?.onData((value, previous) => {
+                if (previous !== undefined)
+                    this.applyPreferredLanguage(value);
+            }) ?? null;
+    }
+    get textTracks() {
+        return this._tracks;
+    }
+    get activeTextTrack() {
+        return this._active;
+    }
+    /**
+     * Replaces the discovered text track list. Emits `textTracksChange`. If
+     * the previously active track is no longer present, clears the active
+     * selection and emits `activeTextTrackChange`.
+     */
+    setTextTracks(tracks) {
+        if (equalDeep(this._tracks, tracks))
+            return;
+        const previous = this._tracks;
+        this._tracks = tracks;
+        this.dispatch('textTracksChange', { previous, current: tracks });
+        if (this._active && !tracks.some((t) => t.id === this._active.id)) {
+            // Clear a now-absent selection, but keep _userSelected intact.
+            this.selectById(null);
+        }
+        // A preferred language re-selects the best match as the list changes;
+        // otherwise auto-show forced captions until the app makes an explicit
+        // choice.
+        const preferred = this.deps.preferredTextLanguage?.value;
+        if (preferred != null) {
+            this.applyPreferredLanguage(preferred);
+        }
+        else if (!this._userSelected && !this._active) {
+            const forced = this.pickForcedTrack(tracks);
+            if (forced)
+                this.selectById(forced.id);
+        }
+    }
+    setActiveTextTrack(id) {
+        // An explicit app choice; stop auto-selecting forced tracks.
+        this._userSelected = true;
+        this.selectById(id);
+    }
+    /**
+     * Selects the track best matching the preferred language(s), or clears the
+     * selection when the preference is null or nothing matches.
+     */
+    applyPreferredLanguage(preferred) {
+        const target = pickPreferredTextTrack(this._tracks, preferred);
+        this.setActiveTextTrack(target?.id ?? null);
+    }
+    /**
+     * Applies a selection by id (null clears it) without marking it as an
+     * explicit user choice. Shared by setActiveTextTrack and forced auto-select.
+     */
+    selectById(id) {
+        const next = id == null ? null : this._tracks.find((t) => t.id === id);
+        if (id != null && !next)
+            return; // unknown id is a no-op
+        const target = next ?? null;
+        if (target?.id === this._active?.id)
+            return;
+        const previous = this._active;
+        this.clearDomTrack();
+        this.loadAbort?.abort();
+        this.loadAbort = null;
+        this._active = target;
+        this.dispatch('activeTextTrackChange', {
+            previous,
+            current: target,
+        });
+        if (target)
+            this.startLoad(target);
+    }
+    /**
+     * The forced track to auto-select, or null. Prefers the default track's
+     * language, else the first forced track.
+     */
+    pickForcedTrack(tracks) {
+        const forced = tracks.filter((t) => t.forced);
+        if (forced.length === 0)
+            return null;
+        const defaultLang = tracks.find((t) => t.default)?.language;
+        if (defaultLang != null) {
+            const match = forced.find((t) => t.language === defaultLang);
+            if (match)
+                return match;
+        }
+        return forced[0];
+    }
+    suspend() {
+        this.loadAbort?.abort();
+        this.loadAbort = null;
+        this.clearDomTrack();
+    }
+    resume() {
+        // Rebuild only when an active selection exists and it isn't already
+        // rendering (clearDomTrack/suspend nulls _domTrack; setActiveTextTrack
+        // sets it).
+        if (!this._active || this._domTrack)
+            return;
+        this.startLoad(this._active);
+    }
+    /**
+     * Cancels any in-flight load, clears the DOM TextTrack, and resets state.
+     * Called by the host when the underlying media is unloaded.
+     */
+    dispose() {
+        super.dispose();
+        this.preferredLanguageSub?.();
+        this.loadAbort?.abort();
+        this.loadAbort = null;
+        this.clearDomTrack();
+        this._tracks = [];
+        this._active = null;
+    }
+    startLoad(track) {
+        const media = this.deps.media;
+        // Without a media element there's nowhere to render cues and no
+        // playhead to drive segment selection, so skip fetching entirely.
+        // The active-selection state still surfaces via events.
+        if (!media)
+            return;
+        const abort = new Abort();
+        this.loadAbort = abort;
+        // Create the DOM TextTrack up front so cues render incrementally as
+        // segments arrive rather than after the whole playlist loads.
+        const dom = this.ensureDomTrack(media, track);
+        const CueCtor = getVttCueConstructor();
+        // Adjacent HLS caption segments commonly repeat the boundary cue in
+        // both segments (packagers do this so a client that only fetches one
+        // segment still renders the overlapping cue). Track seen keys per
+        // active load so we don't push the same cue twice.
+        const seen = new Set();
+        loadWebVttCues(track.uri, {
+            abort,
+            requestInit: this.deps.requestInit,
+            variables: track.variables,
+            getCurrentTime: () => media.currentTime,
+            onCues: (cues) => {
+                if (abort.aborted())
+                    return;
+                if (CueCtor)
+                    this.appendCues(dom, CueCtor, cues, seen);
+            },
+        }).catch((error) => {
+            if (abort.aborted())
+                return;
+            this.dispatch('textTrackError', {
+                track,
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        });
+    }
+    ensureDomTrack(media, track) {
+        const dom = media.addTextTrack(track.kind, track.label, track.language ?? undefined);
+        dom.mode = 'showing';
+        this._domTrack = dom;
+        return dom;
+    }
+    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;
+            // Apply the configured cue layout style (e.g. the default `size: 90`
+            // inset so long lines don't clip in fullscreen, which `::cue` CSS
+            // cannot fix). Only VTTCues carry these properties.
+            const cueStyle = this.deps.cueStyle?.value;
+            if (cueStyle && isVttCue(domCue)) {
+                applyVttCueStyle(domCue, cueStyle);
+            }
+            dom.addCue(domCue);
+        }
+    }
+    clearDomTrack() {
+        const dom = this._domTrack;
+        if (!dom)
+            return;
+        dom.mode = 'disabled';
+        // Best-effort: remove any cues we added so a future activation starts
+        // from a clean slate. Some platforms recreate the underlying TextTrack
+        // when the source changes; this is defensive.
+        if (dom.cues) {
+            const all = Array.from(dom.cues);
+            for (const cue of all)
+                dom.removeCue(cue);
+        }
+        this._domTrack = null;
+    }
+}
+function getVttCueConstructor() {
+    const g = globalThis;
+    return g.VTTCue ?? g.TextTrackCue ?? null;
+}

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

@@ -0,0 +1,60 @@
+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;
+    /**
+     * 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;AAG3B,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;;;;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,CAsCf"}

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

@@ -0,0 +1,144 @@
+/*
+ * 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, 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,
+            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,
+            getCurrentTime,
+            lookAhead,
+            lookBehind,
+        });
+    }
+    const cues = parseWebVtt(body).cues;
+    if (cues.length > 0)
+        onCues(cues);
+}
+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 cues = parseWebVtt(body).cues;
+        if (cues.length > 0)
+            ctx.onCues(cues);
+    }
+}
+/**
+ * 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;
+}