@amazon/vinyl 1.1.1 → 2.0.0

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

@@ -0,0 +1,120 @@
+/*
+ * 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';
+// Trailing cue settings are tolerated but ignored. They are separated from the
+// end timestamp by whitespace, so the tail is matched as an optional group that
+// begins with a whitespace character. Using `(?:\s.*)?$` rather than `\s*(.*)$`
+// avoids the ambiguous overlap between `\s*` and `.*` (both match spaces), which
+// would allow polynomial backtracking on space-heavy input.
+const TIME_RE = /^\s*(?:(\d+):)?([0-5]?\d):([0-5]?\d)\.(\d{3})\s*-->\s*(?:(\d+):)?([0-5]?\d):([0-5]?\d)\.(\d{3})(?:\s.*)?$/;
+/**
+ * Parses a WebVTT document into a list of cues.
+ *
+ * Implements a forgiving subset of the WebVTT 1.0 specification: header
+ * detection, comment blocks (lines starting with `NOTE`), styling/region
+ * blocks (skipped), cue identifiers, and HH:MM:SS.mmm or MM:SS.mmm timestamps.
+ * Cue settings on the timing line are tolerated and ignored.
+ *
+ * @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.
+ */
+export function parseWebVtt(input) {
+    if (typeof input !== 'string') {
+        throw new ValidationError('WebVTT input must be a string', ErrorOrigin.MEDIA);
+    }
+    let text = input;
+    // Strip BOM
+    if (text.charCodeAt(0) === 0xfeff)
+        text = text.slice(1);
+    // Normalize line endings
+    const lines = text.split(/\r\n|\r|\n/);
+    if (lines.length === 0 || !isWebVttHeader(lines[0])) {
+        throw new ValidationError('WebVTT must begin with a WEBVTT header', ErrorOrigin.MEDIA);
+    }
+    const cues = [];
+    // Per the WebVTT spec, everything from the `WEBVTT` signature up to (and
+    // including) the first blank line is the file header — any metadata
+    // header lines (e.g. HLS's `X-TIMESTAMP-MAP=...`) belong in that block
+    // and MUST NOT be interpreted as cue content.
+    let i = 1;
+    while (i < lines.length && lines[i] !== '')
+        i++;
+    while (i < lines.length) {
+        // Skip empty lines between blocks.
+        if (lines[i] === '') {
+            i++;
+            continue;
+        }
+        // NOTE comment block: skip until blank line.
+        if (lines[i] === 'NOTE' || lines[i].startsWith('NOTE ')) {
+            i++;
+            while (i < lines.length && lines[i] !== '')
+                i++;
+            continue;
+        }
+        // STYLE / REGION blocks - skip until blank line.
+        if (lines[i] === 'STYLE' || lines[i] === 'REGION') {
+            i++;
+            while (i < lines.length && lines[i] !== '')
+                i++;
+            continue;
+        }
+        // Cue: optional identifier, then a timing line, then payload.
+        let id = null;
+        let timingLine;
+        const firstLine = lines[i];
+        if (TIME_RE.test(firstLine)) {
+            timingLine = firstLine;
+            i++;
+        }
+        else {
+            id = firstLine;
+            i++;
+            if (i >= lines.length)
+                break;
+            timingLine = lines[i];
+            i++;
+        }
+        const match = TIME_RE.exec(timingLine);
+        if (!match) {
+            // Skip malformed cue: drain to next blank line.
+            while (i < lines.length && lines[i] !== '')
+                i++;
+            continue;
+        }
+        const startTime = toSeconds(match[1], match[2], match[3], match[4]);
+        const endTime = toSeconds(match[5], match[6], match[7], match[8]);
+        const payloadLines = [];
+        while (i < lines.length && lines[i] !== '') {
+            payloadLines.push(lines[i]);
+            i++;
+        }
+        cues.push({
+            id,
+            startTime,
+            endTime,
+            text: payloadLines.join('\n'),
+        });
+    }
+    return { cues };
+}
+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;
+}
+function toSeconds(hours, minutes, seconds, millis) {
+    const h = hours ? Number(hours) : 0;
+    const m = Number(minutes);
+    const s = Number(seconds);
+    const ms = Number(millis);
+    return h * 3600 + m * 60 + s + ms / 1000;
+}

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

@@ -0,0 +1,14 @@
+import type { TextTrackInfo } from './TextTrack';
+/**
+ * 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: string | readonly string[] | null): 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;AAgBhD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAClC,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,SAAS,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,IAAI,GAC7C,aAAa,GAAG,IAAI,CActB"}

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

@@ -0,0 +1,68 @@
+/*
+ * 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. Unlike the audio equivalent, `null` resolves to
+ * an empty list (no preference) rather than falling back to
+ * `navigator.languages` — captions default to off.
+ */
+function resolvePreferredTextLanguages(preferred) {
+    if (typeof preferred === 'string')
+        return [preferred];
+    if (preferred)
+        return preferred;
+    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"}

package/dist/types/current/track/AutoResetController.js

@@ -2,7 +2,7 @@
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
-import { createDisposer, ErrorOrigin, EventHostImpl, getNetworkState, logDebug, onAny, ReportableError, } from '@amazon/vinyl-util';
+import { createDisposer, EventHostImpl, getNetworkState, logDebug, onAny, RequestError, } from '@amazon/vinyl-util';
 export const defaultResetControllerOptions = {
     enabled: true,
     maxRetries: 30,
@@ -36,38 +36,48 @@ export class AutoResetControllerImpl extends EventHostImpl {
     setError(error) {
         if (!this.options.enabled || this._error)
             return;
-        if (error instanceof ReportableError &&
-            error.origin === ErrorOrigin.SERVICE_INTERNAL) {
+        if (error instanceof RequestError && error.response == null) {
             this._error = error;
-            this.setWatching(true);
+            this.setResetPending(true);
         }
     }
-    setWatching(value) {
-        logDebug(this, 'setWatching', value);
+    get resetPending() {
+        return this.watchSub != null;
+    }
+    setResetPending(value) {
+        if (this.resetPending === value) {
+            logDebug(this, 'setResetPending', value, 'no-op');
+            return;
+        }
+        logDebug(this, 'setResetPending', value);
         this.watchSub?.();
         this.watchSub = null;
-        if (!value)
-            return;
-        const networkState = getNetworkState();
-        const { add, dispose: watchSub } = createDisposer();
-        this.watchSub = watchSub;
-        add(networkState.on('online', () => {
-            logDebug(this, 'online, emitting reset');
-            this.reset();
-        }));
-        const intervalId = setTimeout(() => {
-            if (this.currentRetry++ < this.options.maxRetries) {
-                if (networkState.onLine) {
-                    logDebug(this, 'interval, emitting reset');
-                    this.reset();
+        if (value) {
+            const networkState = getNetworkState();
+            const { add, dispose: watchSub } = createDisposer();
+            this.watchSub = watchSub;
+            add(networkState.on('online', () => {
+                logDebug(this, 'online, emitting reset');
+                this.reset();
+            }));
+            const intervalId = setTimeout(() => {
+                if (this.currentRetry++ < this.options.maxRetries) {
+                    if (networkState.onLine) {
+                        logDebug(this, 'interval, emitting reset');
+                        this.reset();
+                    }
                 }
-            }
-            else {
-                logDebug(this, 'max retries exhausted, pausing playback');
-                this.setWatching(false);
-            }
-        }, this.options.retryInterval * 1000);
-        add(() => clearTimeout(intervalId));
+                else {
+                    logDebug(this, 'max retries exhausted, pausing playback');
+                    this.setResetPending(false);
+                }
+            }, this.options.retryInterval * 1000);
+            add(() => clearTimeout(intervalId));
+        }
+        this.dispatch('resetPendingChange', {
+            previous: !value,
+            current: value,
+        });
     }
     reset() {
         if (!this._error)
@@ -79,7 +89,7 @@ export class AutoResetControllerImpl extends EventHostImpl {
         if (!this._error)
             return;
         this._error = null;
-        this.setWatching(false);
+        this.setResetPending(false);
     }
     get disposed() {
         return this.disposer.disposed;

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

@@ -0,0 +1,9 @@
+/**
+ * The seekable time range on the media timeline, in seconds.
+ * `end` will be `Infinity` when a live stream.
+ */
+export type SeekRange = {
+    readonly start: number;
+    readonly end: number;
+};
+//# sourceMappingURL=SeekRange.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SeekRange.d.ts","sourceRoot":"","sources":["../../../../src/track/SeekRange.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAA"}

package/dist/types/current/track/SeekRange.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/track/Track.d.ts

@@ -1,11 +1,18 @@
-import type { AnyRecord, Disposable, LogTarget, ReadonlyEventHost, ReadonlyRanges, ReadonlySet } from '@amazon/vinyl-util';
+import type { AnyRecord, Covariant, Disposable, EventHandler, LogTarget, Maybe, ReadonlyEventHost, ReadonlyRanges, ReadonlySet, SignalOptions, Unsubscribe } from '@amazon/vinyl-util';
 import type { ContentType, MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
 import type { StreamingEventMap } from '../streaming/StreamingEventMap';
+import type { ReadonlyTextTrackController, TextTrackController } from '../text/TextTrack';
+import type { SeekRange } from './SeekRange';
+import type { TrackAds } from '../ad/AdBreakInfo';
+import type { TrackConfigOptions } from './TrackFactory';
+export type { SeekRange } from './SeekRange';
 /**
  * All events a track may emit.
  * Streaming-related events are separated as they will be bubbled by the player.
  */
-export type TrackEventMap = StreamingEventMap;
+export type TrackEventMap = StreamingEventMap & {
+    readonly adsChange: AnyRecord;
+};
 /**
  * An identifier for a Track, used for referencing a track.
  */
@@ -93,10 +100,13 @@ export interface StreamingState extends ReadonlyStreamingState {
     /**
      * Resets the track to recover from error states.
      * This will reset failed segments and clear error conditions to allow streaming to resume.
+     *
+     * @param hard If true, the track will reset the playback state and
+     * recreate media sources.
      */
-    reset(): void;
+    reset(hard?: boolean): void;
 }
-export interface ReadonlyTrack extends ReadonlyStreamingState, LogTarget {
+export interface ReadonlyTrack extends ReadonlyEventHost<TrackEventMap>, ReadonlyStreamingState, LogTarget {
     /**
      * The track identifier.
      */
@@ -122,18 +132,44 @@ export interface ReadonlyTrack extends ReadonlyStreamingState, LogTarget {
      * The last error that occurred in this track, or null if no error.
      */
     readonly error: Error | null;
+    /**
+     * Controller for sidecar text tracks discovered for this track, or null
+     * if the track type does not surface text tracks.
+     */
+    readonly textTrackController: ReadonlyTextTrackController | null;
+    /**
+     * The seekable range on the media timeline, or null when not yet known
+     * (e.g. before the manifest is loaded). Based on the media timeline, not
+     * the element's native seekable ranges.
+     */
+    readonly seekRange: SeekRange | null;
+    /**
+     * Resolves to the ads for this track.
+     * The track's ads may change if the media timeline changes.
+     *
+     * @see {@link TrackEventMap} — the `adsChange` event.
+     */
+    getAds(): Promise<TrackAds>;
+    readonly __eventMapType: Covariant<TrackEventMap>;
+    hasListeners(type: keyof TrackEventMap): boolean;
+    on<K extends keyof TrackEventMap>(type: K, handler: EventHandler<TrackEventMap[K]>, options?: SignalOptions): Unsubscribe;
 }
 /**
  * One track is active on the track controller at a time.
  */
-export interface Track<LoadOptionsType extends AnyRecord = AnyRecord> extends ReadonlyTrack, StreamingState, Disposable {
+export interface Track<ConfigType extends TrackConfigOptions = TrackConfigOptions> extends ReadonlyTrack, StreamingState, Disposable {
+    /**
+     * Mutable view of {@link ReadonlyTrack.textTrackController} that allows
+     * selecting the active text track.
+     */
+    readonly textTrackController: TextTrackController | null;
     /**
      * Provides configuration to the track and begins preloading (if applicable).
      *
      * @param trackOptions Configuration provided by the TrackController.
      * @param loadOptions Configuration from `TrackLoadOptions.config`, provided by the Application.
      */
-    preload(trackOptions: TrackPreloadOptions, loadOptions: LoadOptionsType): void;
+    preload(trackOptions: TrackPreloadOptions, loadOptions: Maybe<ConfigType>): void;
     /**
      * Sets this track as active, deactivating any currently active track.
      * This should set sources on the playback source and add any listeners needed for shared
@@ -141,7 +177,7 @@ export interface Track<LoadOptionsType extends AnyRecord = AnyRecord> extends Re
      *
      * @param loadOptions Configuration from `TrackLoadOptions.config`, provided by the Application.
      */
-    activate(loadOptions: LoadOptionsType): void;
+    activate(loadOptions: Maybe<ConfigType>): void;
     /**
      * Sets this track as inactive.
      * This should unset sources, and remove any listeners. Tracks do not implement disposable,
@@ -149,5 +185,12 @@ export interface Track<LoadOptionsType extends AnyRecord = AnyRecord> extends Re
      * are no longer references to the track.
      */
     deactivate(): void;
+    /**
+     * True if this track is disposed.
+     */
+    readonly disposed: boolean;
+    readonly __eventMapType: Covariant<TrackEventMap>;
+    hasListeners(type: keyof TrackEventMap): boolean;
+    on<K extends keyof TrackEventMap>(type: K, handler: EventHandler<TrackEventMap[K]>, options?: SignalOptions): Unsubscribe;
 }
 //# sourceMappingURL=Track.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Track.d.ts","sourceRoot":"","sources":["../../../../src/track/Track.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACR,SAAS,EACT,UAAU,EACV,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,WAAW,EACd,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EACR,WAAW,EACX,oBAAoB,EACvB,MAAM,kCAAkC,CAAA;AACzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAA;AAEtE;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,iBAAiB,CAAA;AAE7C;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAA;AAE7B;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAA;AAEhC;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;CACpC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,sBAAuB,SAAQ,iBAAiB,CAAC,iBAAiB,CAAC;IAChF;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,cAAc,CAAA;IAEtC;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,WAAW,CAAC,CAAA;IAE/C;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,oBAAoB,EAAE,GAAG,IAAI,CAAA;IAE1D;;;OAGG;IACH,QAAQ,CAAC,mBAAmB,EAAE,SAAS,oBAAoB,EAAE,GAAG,IAAI,CAAA;IAEpE;;;;;;;;;OASG;IACH,mBAAmB,CAAC,WAAW,EAAE,WAAW,GAAG,oBAAoB,GAAG,IAAI,CAAA;IAE1E;;;;;;OAMG;IACH,mBAAmB,CAAC,WAAW,EAAE,WAAW,GAAG,oBAAoB,GAAG,IAAI,CAAA;IAE1E;;;;;;OAMG;IACH,kBAAkB,CAAC,WAAW,EAAE,WAAW,GAAG,oBAAoB,GAAG,IAAI,CAAA;CAC5E;AAED,MAAM,WAAW,cAAe,SAAQ,sBAAsB;IAC1D;;OAEG;IACH,aAAa,IAAI,IAAI,CAAA;IAErB;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAA;CAChB;AAED,MAAM,WAAW,aAAc,SAAQ,sBAAsB,EAAE,SAAS;IACpE;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAA;IAEtB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAE1B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IAExB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAE1B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAA;IAEnB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,KAAK,CAAC,eAAe,SAAS,SAAS,GAAG,SAAS,CAChE,SAAQ,aAAa,EAAE,cAAc,EAAE,UAAU;IACjD;;;;;OAKG;IACH,OAAO,CACH,YAAY,EAAE,mBAAmB,EACjC,WAAW,EAAE,eAAe,GAC7B,IAAI,CAAA;IAEP;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,EAAE,eAAe,GAAG,IAAI,CAAA;IAE5C;;;;;OAKG;IACH,UAAU,IAAI,IAAI,CAAA;CACrB"}
+{"version":3,"file":"Track.d.ts","sourceRoot":"","sources":["../../../../src/track/Track.ts"],"names":[],"mappings":"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"}

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

@@ -1,10 +1,12 @@
-import type { ObjectSchema } from '@amazon/vinyl-validation';
 import { EventHostImpl, type Maybe, type ReadonlyRanges, type ReadonlySet } from '@amazon/vinyl-util';
 import type { PlaybackController } from '../playback/PlaybackController';
 import type { Track, TrackEventMap, TrackPreloadOptions, TrackTypeId, TrackUri } from './Track';
+import type { SeekRange } from './SeekRange';
 import { type DrmController } from '../drm/DrmController';
 import type { ContentType, MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
-import { type DrmOptions } from '../drm/DrmOptions';
+import type { TextTrackController } from '../text/TextTrack';
+import type { TrackAds } from '../ad/AdBreakInfo';
+import type { TrackConfigOptions } from './TrackFactory';
 /**
  * Dependencies for TrackBase.
  */
@@ -18,29 +20,10 @@ export interface TrackBaseDeps {
      */
     readonly drmController: DrmController;
 }
-/**
- * General configuration for tracks set in track load options.
- */
-export interface TrackBaseOptions {
-    /**
-     * The time to seek to when the track has been activated.
-     * For MSE tracks this will affect pre-fetching.
-     */
-    readonly startTime?: Maybe<number>;
-    /**
-     * Extra application data to associate with the track.
-     */
-    readonly extra?: any;
-    /**
-     * DRM Configuration overrides for this track.
-     */
-    readonly drm?: Partial<DrmOptions>;
-}
-export declare const trackBaseOptionsValidator: ObjectSchema<TrackBaseOptions>;
 /**
  * A base class for all tracks.
  */
-export declare abstract class TrackBase<EventMap extends TrackEventMap = TrackEventMap, LoadOptionsType extends TrackBaseOptions = TrackBaseOptions> extends EventHostImpl<EventMap> implements Track<LoadOptionsType> {
+export declare abstract class TrackBase<EventMap extends TrackEventMap = TrackEventMap, ConfigType extends TrackConfigOptions = TrackConfigOptions> extends EventHostImpl<EventMap> implements Track<ConfigType> {
     /**
      * The identifier of this track, used as the key in the track cache.
      */
@@ -54,11 +37,22 @@ export declare abstract class TrackBase<EventMap extends TrackEventMap = TrackEv
     /**
      * The current load options, if this is an active track.
      */
-    protected loadOptions: LoadOptionsType | null;
+    protected loadOptions: Maybe<ConfigType>;
     protected readonly errorHandler: (error: any) => void;
     protected readonly disposer: import("@amazon/vinyl-util").Disposer;
     protected drmSessionAbort: import("@amazon/vinyl-util").AbortSlot;
     get fetchedRanges(): ReadonlyRanges;
+    /**
+     * Default text track controller is null. Tracks that surface text tracks
+     * (e.g. {@link MseTrack}) override this getter.
+     */
+    get textTrackController(): TextTrackController | null;
+    /**
+     * The presentation seek range of the media.
+     * Most often {start=0, end=duration} but may be different depending on the
+     * media timeline.
+     */
+    get seekRange(): SeekRange | null;
     abstract get contentTypes(): ReadonlySet<ContentType>;
     abstract get qualities(): readonly MediaQualityMetadata[] | null;
     abstract get qualitiesUnfiltered(): readonly MediaQualityMetadata[] | null;
@@ -70,6 +64,7 @@ export declare abstract class TrackBase<EventMap extends TrackEventMap = TrackEv
      */
     protected _error: Error | null;
     private _active;
+    private _seekRange;
     protected constructor(
     /**
      * The identifier of this track, used as the key in the track cache.
@@ -79,31 +74,37 @@ export declare abstract class TrackBase<EventMap extends TrackEventMap = TrackEv
      * The track type.
      */
     type: TrackTypeId, deps: TrackBaseDeps);
+    toString(): string;
     get error(): Error | null;
-    preload(_trackOptions: TrackPreloadOptions, _loadOptions: LoadOptionsType): void;
+    preload(_trackOptions: TrackPreloadOptions, _loadOptions: Maybe<ConfigType>): void;
     get extra(): any;
     get active(): boolean;
     get disposed(): boolean;
-    activate(loadOptions: LoadOptionsType): void;
+    activate(loadOptions: Maybe<ConfigType>): void;
     /**
      * The track has been activated.
      * Operations on shared resources such as the playback controller may only be done while the
      * track is currently active. For example if there is a loading operation before the
      * playback source is set, isActive must be checked before the property is changed.
      */
-    abstract onActivated(loadOptions: LoadOptionsType): void;
+    abstract onActivated(loadOptions: Maybe<ConfigType>): void;
     deactivate(): void;
     abstract onDeactivated(): void;
-    toString(): string;
-    protected closeDrmSessions(): void;
     abstract clearPrefetch(): void;
+    protected closeDrmSessions(): void;
+    /**
+     * Resolves to this track's ads.
+     * Implementations may override to provide ad breaks.
+     */
+    getAds(): Promise<TrackAds>;
+    protected setSeekRange(value: SeekRange): void;
     /**
      * Resets the track to recover from error states.
      * Base implementation does nothing.
      *
      * Overrides should dispatch 'reset' after resetting error state.
      */
-    reset(): void;
+    reset(hard?: boolean): void;
     dispose(): void;
 }
 //# sourceMappingURL=TrackBase.d.ts.map