@amazon/vinyl 1.1.1 → 1.2.1

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

@@ -0,0 +1,49 @@
+/*
+ * 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 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 function discoverHlsTextTracks(mainPlaylist, baseUrl) {
+    const out = [];
+    let index = 0;
+    const parentDefines = mainPlaylist.defines && Object.keys(mainPlaylist.defines).length > 0
+        ? mainPlaylist.defines
+        : undefined;
+    for (const rendition of mainPlaylist.alternativeRenditions) {
+        if (rendition.type !== 'SUBTITLES')
+            continue;
+        if (!rendition.uri)
+            continue;
+        const resolved = resolveUrl(rendition.uri, baseUrl);
+        out.push({
+            id: `hls-text-${index++}-${rendition.groupId}-${rendition.name}`,
+            kind: 'subtitles',
+            language: rendition.language ?? null,
+            label: rendition.name,
+            default: rendition.default === true,
+            forced: rendition.forced === true,
+            characteristics: rendition.characteristics ?? [],
+            uri: resolved,
+            // HLS subtitle renditions don't carry a MIME type; WebVTT is the
+            // overwhelmingly dominant format for sidecar HLS subtitles.
+            mimeType: 'text/vtt',
+            ...(parentDefines && { variables: parentDefines }),
+        });
+    }
+    return out;
+}

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

@@ -0,0 +1,60 @@
+import type { VttCueStyle } from './VttCueStyle';
+/**
+ * A single WebVTT cue.
+ *
+ * @see https://www.w3.org/TR/webvtt1/
+ */
+export interface WebVttCue {
+    /**
+     * Optional cue identifier, the line that appears before the timing line.
+     */
+    readonly id: string | null;
+    /**
+     * Cue start time in seconds.
+     */
+    readonly startTime: number;
+    /**
+     * Cue end time in seconds.
+     */
+    readonly endTime: number;
+    /**
+     * 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.
+ */
+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 (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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,248 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ErrorOrigin, ValidationError } from '@amazon/vinyl-util';
+const WEBVTT_HEADER = 'WEBVTT';
+// 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 (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 a leading BOM, then normalize line endings.
+    if (text.charCodeAt(0) === 0xfeff)
+        text = text.slice(1);
+    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 — 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 blank lines between blocks.
+        if (lines[i] === '') {
+            i++;
+            continue;
+        }
+        // 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 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: 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;
+        if (!lines[i].includes('-->')) {
+            id = lines[i];
+            i++;
+            if (i >= lines.length)
+                break; // identifier with no timing 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 payloadLines = [];
+        while (i < lines.length && lines[i] !== '') {
+            payloadLines.push(lines[i]);
+            i++;
+        }
+        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, 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))
+        return false;
+    if (line.length === WEBVTT_HEADER.length)
+        return true;
+    const next = line.charCodeAt(WEBVTT_HEADER.length);
+    // Header may be followed by space, tab, or any text after a separator.
+    return next === 0x20 || next === 0x09;
+}
+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

@@ -0,0 +1,15 @@
+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).
+ *
+ * Language dominates: a track is ranked first by which preference it relates to
+ * (earlier entries win) and how closely (see {@link languageRelatedness}).
+ * Within a single language, a full track is preferred over a forced-only track
+ * (a user asking for a caption language wants the full captions, not just the
+ * forced foreign-dialogue cues), and a manifest-default track breaks any
+ * remaining tie.
+ */
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,71 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { languageRelatedness } from '../track/filters/languageFilter';
+/**
+ * Resolves the preferred-text-language option to an ordered list of BCP 47
+ * 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 [];
+}
+/**
+ * Chooses the text track that best matches the preferred language(s), or null
+ * when none relate (or there is no preference / no tracks).
+ *
+ * Language dominates: a track is ranked first by which preference it relates to
+ * (earlier entries win) and how closely (see {@link languageRelatedness}).
+ * Within a single language, a full track is preferred over a forced-only track
+ * (a user asking for a caption language wants the full captions, not just the
+ * forced foreign-dialogue cues), and a manifest-default track breaks any
+ * remaining tie.
+ */
+export function pickPreferredTextTrack(tracks, preferred) {
+    const prefs = resolvePreferredTextLanguages(preferred);
+    if (tracks.length === 0 || prefs.length === 0)
+        return null;
+    let best = null;
+    let bestScore = 0;
+    for (const track of tracks) {
+        const score = scoreTextTrack(track, prefs);
+        if (score > bestScore) {
+            bestScore = score;
+            best = track;
+        }
+    }
+    return best;
+}
+/**
+ * Scores a track against the ordered preference list. 0 means unrelated to
+ * every preference (never selected). Preference position and language
+ * relatedness are weighted so they dominate the full/forced/default tiebreaks.
+ */
+function scoreTextTrack(track, prefs) {
+    if (track.language == null)
+        return 0;
+    let best = 0;
+    for (let i = 0; i < prefs.length; i++) {
+        const rel = languageRelatedness(prefs[i], track.language);
+        if (rel > 0) {
+            best = Math.max(best, (prefs.length - i) * 100 + rel * 10);
+        }
+    }
+    if (best === 0)
+        return 0;
+    // Tiebreaks within the same language: prefer full over forced, then default.
+    if (!track.forced)
+        best += 2;
+    if (track.default)
+        best += 1;
+    return best;
+}

package/dist/types/current/track/AutoResetController.d.ts

@@ -1,35 +1,59 @@
 import { type AnyRecord, type Clearable, type Disposable, EventHostImpl, type ReadonlyEventHost } from '@amazon/vinyl-util';
 import type { PlaybackController } from '../playback/PlaybackController';
+import type { ChangeEvent } from '../event/ChangeEvent';
 export interface AutoResetControllerEventMap {
     /**
      * Notifies that playback errors should be reset and retried.
      */
     readonly reset: AnyRecord;
+    /**
+     * Dispatched when {@link AutoResetController.resetPending} changes.
+     */
+    readonly resetPendingChange: ChangeEvent<boolean>;
 }
 /**
- * Notifies when playback should be reset and retried.
+ * Notifies when playback should be reset and retried after a transient,
+ * potentially-recoverable error.
  *
- * The controller monitors for retry opportunities after an error is set:
- * - Immediately on network 'online' events
- * - After a timeout interval if online
+ * Once an eligible error is set, the controller watches for opportunities
+ * to emit a `reset` event:
+ * - Immediately when the network transitions back to online
+ * - After a timeout interval, if online and retries are not exhausted
  * - Immediately on user playback actions (play, pause, seeking, playing)
  *
- * Each error triggers a single timeout. If another error occurs after a reset,
- * setError() should be called again to schedule the next retry attempt.
+ * Each error triggers a single retry timeout. If another error occurs
+ * after a reset, {@link AutoResetController.setError} should be called again
+ * to schedule the next retry attempt.
  */
 export interface AutoResetController extends ReadonlyEventHost<AutoResetControllerEventMap>, Clearable {
     /**
-     * Sets the current playback error and begins monitoring for retry opportunities.
+     * Sets the current playback error and, if eligible, begins watching for
+     * retry opportunities.
+     *
+     * An error is eligible when it is a {@link RequestError} that did not
+     * receive an HTTP response (i.e. `response == null`), indicating a
+     * transient network failure such as connection loss or DNS failure.
+     * All other errors — including HTTP failures with a response (4xx/5xx),
+     * and non-RequestError errors — are ignored, since those are unlikely
+     * to recover on their own.
      *
-     * Only SERVICE_INTERNAL ReportableErrors are monitored. Subsequent calls while
-     * an error is already set are ignored until the error is cleared via reset or clear().
+     * Subsequent calls while an error is already set are ignored until the
+     * error is cleared via a reset emission or {@link Clearable.clear}.
      *
-     * After a reset, if another error occurs, this method should be called again
-     * to schedule the next retry attempt.
+     * After a reset, if another eligible error occurs, this method should
+     * be called again to schedule the next retry attempt.
      *
      * @param error The error to monitor for retry opportunities
      */
     setError(error: Error): void;
+    /**
+     * True while an eligible error is being watched and a `reset` event
+     * may still be emitted. Becomes false once the error is cleared, a
+     * reset is emitted, or all retries are exhausted.
+     *
+     * Listen to `resetPendingChange` events for changes.
+     */
+    readonly resetPending: boolean;
 }
 export interface AutoResetControllerImplDeps {
     readonly playbackController: PlaybackController;
@@ -74,7 +98,8 @@ export declare class AutoResetControllerImpl extends EventHostImpl<AutoResetCont
     private disposer;
     constructor(deps: AutoResetControllerImplDeps, options?: Partial<AutoResetControllerImplOptions>);
     setError(error: Error): void;
-    private setWatching;
+    get resetPending(): boolean;
+    private setResetPending;
     private reset;
     clear(): void;
     get disposed(): boolean;

package/dist/types/current/track/AutoResetController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AutoResetController.d.ts","sourceRoot":"","sources":["../../../../src/track/AutoResetController.ts"],"names":[],"mappings":"AAKA,OAAO,EACH,KAAK,SAAS,EACd,KAAK,SAAS,EAEd,KAAK,UAAU,EAEf,aAAa,EAIb,KAAK,iBAAiB,EAGzB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAA;AAEvE,MAAM,WAAW,2BAA2B;IACxC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;CAC5B;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBACb,SAAQ,iBAAiB,CAAC,2BAA2B,CAAC,EAAE,SAAS;IACjE;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CAC/B;AAED,MAAM,WAAW,2BAA2B;IACxC,QAAQ,CAAC,kBAAkB,EAAE,kBAAkB,CAAA;CAClD;AAED,MAAM,WAAW,8BAA8B;IAC3C;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IAEzB;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAE3B;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CACjC;AAED,eAAO,MAAM,6BAA6B;;;;CAIS,CAAA;AAEnD,qBAAa,uBACT,SAAQ,aAAa,CAAC,2BAA2B,CACjD,YAAW,mBAAmB,EAAE,UAAU;IAatC,QAAQ,CAAC,IAAI,EAAE,2BAA2B;IAX9C,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,MAAM,CAEjC;IAED,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,QAAQ,CAA2B;IAC3C,OAAO,CAAC,YAAY,CAAI;IACxB,OAAO,CAAC,QAAQ,CAAmB;gBAGtB,IAAI,EAAE,2BAA2B,EAC1C,OAAO,CAAC,EAAE,OAAO,CAAC,8BAA8B,CAAC;IAuBrD,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAW5B,OAAO,CAAC,WAAW;IA6BnB,OAAO,CAAC,KAAK;IAMb,KAAK;IAML,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,OAAO,IAAI,IAAI;CAIlB"}
+{"version":3,"file":"AutoResetController.d.ts","sourceRoot":"","sources":["../../../../src/track/AutoResetController.ts"],"names":[],"mappings":"AAKA,OAAO,EACH,KAAK,SAAS,EACd,KAAK,SAAS,EAEd,KAAK,UAAU,EACf,aAAa,EAIb,KAAK,iBAAiB,EAGzB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAEvD,MAAM,WAAW,2BAA2B;IACxC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IAEzB;;OAEG;IACH,QAAQ,CAAC,kBAAkB,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA;CACpD;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,mBACb,SAAQ,iBAAiB,CAAC,2BAA2B,CAAC,EAAE,SAAS;IACjE;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IAE5B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;CACjC;AAED,MAAM,WAAW,2BAA2B;IACxC,QAAQ,CAAC,kBAAkB,EAAE,kBAAkB,CAAA;CAClD;AAED,MAAM,WAAW,8BAA8B;IAC3C;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IAEzB;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAE3B;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CACjC;AAED,eAAO,MAAM,6BAA6B;;;;CAIS,CAAA;AAEnD,qBAAa,uBACT,SAAQ,aAAa,CAAC,2BAA2B,CACjD,YAAW,mBAAmB,EAAE,UAAU;IAatC,QAAQ,CAAC,IAAI,EAAE,2BAA2B;IAX9C,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,MAAM,CAEjC;IAED,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,QAAQ,CAA2B;IAC3C,OAAO,CAAC,YAAY,CAAI;IACxB,OAAO,CAAC,QAAQ,CAAmB;gBAGtB,IAAI,EAAE,2BAA2B,EAC1C,OAAO,CAAC,EAAE,OAAO,CAAC,8BAA8B,CAAC;IAuBrD,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAQ5B,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,OAAO,CAAC,eAAe;IAsCvB,OAAO,CAAC,KAAK;IAMb,KAAK;IAML,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,OAAO,IAAI,IAAI;CAIlB"}