@amazon/vinyl 3.0.1 → 3.2.0

package/dist/types/current/playback/PlaybackControllerImpl.js

@@ -2,9 +2,11 @@
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
-import { Abort, AbortError, Browser, clamp, closeTo, createDisposer, createTimeRangesReader, DomEventHost, ErrorLevel, ErrorOrigin, EventHostImpl, getUserAgentInfo, hasBrowser, logDebug, logInfo, logWarn, nextEventAsPromise, onAny, ownKeys, TimeoutSlot, toLowerCase, withAbort, withTimeout, } from '@amazon/vinyl-util';
+import { Abort, AbortError, Browser, clamp, closeTo, createDisposer, createTimeRangesReader, DomEventHost, ErrorLevel, ErrorOrigin, EventHostImpl, hasBrowser, logDebug, logInfo, logWarn, nextEventAsPromise, noop, onAny, ownKeys, TimeoutSlot, toLowerCase, withAbort, withTimeout, } from '@amazon/vinyl-util';
 import { LIVE_DURATION } from './PlaybackController';
 import { PlaybackReadyState, playedReasons, waitedReasons, } from './ReadonlyPlaybackController';
+import { createStallDetector } from './createStallDetector';
+import { createStallMonitor } from './createStallMonitor';
 import { InvalidSeekError } from './error/InvalidSeekError';
 import { playbackStateLoggingHandler } from './logging/playbackStateLoggingHandler';
 import { createChangeEventTrigger } from '../event/ChangeEvent';
@@ -15,6 +17,7 @@ export const defaultPlaybackControllerImplOptions = {
     minSeekableBuffer: -1, // Default comes from getMinSeekableBufferDefault()
     playTimeout: 30,
     seekTimeout: 30,
+    stallThreshold: 1,
 };
 /**
  * Safari and Edge Legacy cannot reliably seek close to the end of a seekable range.
@@ -24,6 +27,19 @@ export const defaultPlaybackControllerImplOptions = {
 export function getMinSeekableBufferDefault() {
     return !hasBrowser(Browser.CHROMIUM) ? 5 : 2;
 }
+/**
+ * Re-issue a seek up to this many times when it lands outside tolerance of the target (some WebKit
+ * versions report `seeked` at the pre-seek position) or when it never completes (see
+ * {@link SEEK_ATTEMPT_TIMEOUT}).
+ */
+const SEEK_RETRY_LIMIT = 2;
+/**
+ * Seconds to wait for `seeked` before treating a seek attempt as stuck. WebKit can leave a seek on
+ * a freshly-attached, never-decoded source pending forever (observed on iOS Safari); on a stuck
+ * attempt the decoder is warmed with play() and the seek re-issued. Comfortably above a normal
+ * seek's completion time so a slow-but-valid seek isn't cut short.
+ */
+const SEEK_ATTEMPT_TIMEOUT = 4;
 export class PlaybackControllerImpl extends EventHostImpl {
     loudnessNormalizationController;
     get [Symbol.toStringTag]() {
@@ -38,6 +54,8 @@ export class PlaybackControllerImpl extends EventHostImpl {
     _waiting = false;
     // Monotonic counter identifying the most recent seekTo call.
     _seekId = 0;
+    // Stops the stall detector started after the last seek, if any.
+    stopStallDetection = null;
     // default user volume (0.0 to 1.0 scale)
     userVolume = 1.0;
     _pendingPlay = null;
@@ -59,6 +77,7 @@ export class PlaybackControllerImpl extends EventHostImpl {
         add(() => {
             this.disposeAbort.abort();
             this.disposeAbort.dispose();
+            this.stopStallDetection?.();
         });
         this.domEvents = add(new DomEventHost(deps.media));
         // Log media events.
@@ -78,6 +97,12 @@ export class PlaybackControllerImpl extends EventHostImpl {
             });
         });
         this.initializeEvents();
+        // Detect and report play-head stalls (frozen while playing) via
+        // stallEntered/stallEnded, independent of the recovery stall detector.
+        add(createStallMonitor(this, {
+            onStallEntered: () => this.dispatch('stallEntered', {}),
+            onStallEnded: (info) => this.dispatch('stallEnded', info),
+        }, { stallThreshold: this.options.stallThreshold }));
         // Listen for loudness normalization changes
         add(this.loudnessNormalizationController.on('change', () => {
             this.refreshVolume();
@@ -278,7 +303,7 @@ export class PlaybackControllerImpl extends EventHostImpl {
                 !this.paused &&
                 this.currentTime <= this.options.loopTimeAffordance &&
                 lastTime >= this.duration - this.options.loopTimeAffordance) {
-                if (getUserAgentInfo().browserLike?.name === Browser.FIREFOX) {
+                if (hasBrowser(Browser.FIREFOX)) {
                     // Firefox does not emit a 'playing' event after a loop, fabricate one.
                     logDebug(this, 'fabricating Firefox playing event on loop');
                     this.dispatch('playing', {});
@@ -388,8 +413,27 @@ export class PlaybackControllerImpl extends EventHostImpl {
             current: value != null,
         });
     }
+    /**
+     * Starts (or restarts) the stall detector: recovers a play head that stays frozen when it
+     * should be advancing — some WebKit versions never resume after a seek or a play, e.g. after a
+     * buffer-flushing seek. Superseded by the next seek/play and stopped on dispose.
+     * @private
+     */
+    startStallDetection() {
+        this.stopStallDetection?.();
+        this.stopStallDetection = createStallDetector(this.media, {
+            fabricatePlaying: () => this.dispatch('playing', {}),
+            // Safari/iOS can leave a seek on a freshly-attached source pending
+            // with a stale empty `buffered`; re-issue the seek to un-stick it.
+            nudgeUnbuffered: hasBrowser(Browser.WEBKIT),
+        });
+    }
     play() {
         logDebug(this, 'play');
+        // Recover a play that never starts progressing (stuck WebKit) — start
+        // even when a prior play() is still pending, e.g. a resume that stalled
+        // after a buffer-flushing seek, whose play() promise this call returns.
+        this.startStallDetection();
         if (!this.pendingPlay) {
             const playAbort = new Abort();
             this.playAbort = playAbort;
@@ -430,15 +474,18 @@ export class PlaybackControllerImpl extends EventHostImpl {
         // Claim this seek as the newest. A seek that parks on an await (e.g. waiting for loadedMetadata) can resume
         // AFTER a later-issued seek has already applied its target.
         const seekId = ++this._seekId;
+        // A new seek supersedes any stall watch from the previous one.
+        this.stopStallDetection?.();
+        this.stopStallDetection = null;
         const superseded = () => {
             if (this._seekId === seekId)
                 return false;
             logDebug(this, `seekTo: ${time} superseded by a newer seek`);
             return true;
         };
-        const nextEvent = (type) => {
+        const nextEvent = (type, options) => {
             return nextEventAsPromise(this, type, {
-                timeout: this.options.seekTimeout,
+                timeout: options?.timeout ?? this.options.seekTimeout,
                 timeoutMessage: `seek timed out on ${type} event after {time}s`,
                 timeoutOrigin: ErrorOrigin.INTERNAL,
                 timeoutLevel: ErrorLevel.WARN,
@@ -471,14 +518,58 @@ export class PlaybackControllerImpl extends EventHostImpl {
             logDebug(this, `seekTo: requested: ${time}, actual: ${clampedTime} no-op`);
         }
         else {
-            const seeking = nextEvent('seeking');
-            this.media.currentTime = clampedTime;
-            await seeking;
-            const seekedEvent = await nextEvent('seeked');
-            if (seekedEvent.reason === 'emptied') {
+            // A dispose rejects the seek; a timeout means the attempt is stuck.
+            const nullIfStuck = (error) => {
+                if (this.disposeAbort.aborted())
+                    throw error;
+                return null;
+            };
+            // Issues one seek attempt. Returns the seeked event, or null if it
+            // didn't complete within SEEK_ATTEMPT_TIMEOUT. Observed on WebKit/iOS
+            // Safari: seeking a freshly-attached source that has never decoded a
+            // frame hangs — the seek never completes and playback stalls in
+            // `waiting`. The initial attempt keeps the full seekTimeout on
+            // `seeking` (a media that never starts seeking is a real timeout); a
+            // re-seek to the current position emits no fresh `seeking` on WebKit,
+            // so bound that wait and fall through to the stall detector.
+            const seekOnce = async (reSeeking) => {
+                const seeking = reSeeking
+                    ? nextEvent('seeking', {
+                        timeout: SEEK_ATTEMPT_TIMEOUT,
+                    }).catch(nullIfStuck)
+                    : nextEvent('seeking');
+                this.media.currentTime = clampedTime;
+                if ((await seeking) === null)
+                    return null;
+                return nextEvent('seeked', {
+                    timeout: SEEK_ATTEMPT_TIMEOUT,
+                }).catch(nullIfStuck);
+            };
+            let seekedEvent = await seekOnce(false);
+            // Re-issue the seek when it never completed (kick the decoder with
+            // play() first — decoding a frame unsticks WebKit) or when it landed
+            // outside tolerance of the target. Bounded, and not fighting a newer
+            // seek. The play() kick is fire-and-forget: a wedged seek can leave
+            // its promise unsettled forever, which would stall the retry loop.
+            for (let attempt = 0; !superseded() &&
+                attempt < SEEK_RETRY_LIMIT &&
+                (seekedEvent === null ||
+                    (seekedEvent.reason === 'seeked' &&
+                        !closeTo(clampedTime, this.currentTime, tolerance))); attempt++) {
+                if (seekedEvent === null)
+                    void this.media.play().catch(noop);
+                logDebug(this, `seekTo: re-seeking to ${clampedTime}`);
+                seekedEvent = await seekOnce(true);
+            }
+            if (seekedEvent?.reason === 'emptied') {
                 // Seek finished due to track unloading. Abort any pending seek.
                 throw new AbortError();
             }
+            // Some WebKit versions don't resume after seeking. Watch for that:
+            // nudge/kick playback back to life, and fabricate a playing event
+            // if it resumes without emitting one.
+            if (!this.paused)
+                this.startStallDetection();
         }
     }
     /**

package/dist/types/current/playback/ReadonlyPlaybackController.d.ts

@@ -188,6 +188,19 @@ export interface PlaybackControllerEventMap {
      * true and the media is seeking a new position.
      */
     readonly seeking: AnyRecord;
+    /**
+     * Fired when the play head has been detected as frozen while playing — i.e. no `timeUpdate`
+     * was observed for longer than the stall threshold. Only emitted once playback has actually
+     * been observed (a `playing` event), so it is not emitted during initial loading or while
+     * awaiting a seek. Each stall is bracketed by a `stallEntered`/{@link stallEnded} pair.
+     */
+    readonly stallEntered: AnyRecord;
+    /**
+     * Fired when a stall (see {@link stallEntered}) has ended, for any reason. `started` is the
+     * time of the last `timeUpdate` observed before the play head froze, and `duration` is the
+     * total number of seconds the play head was frozen.
+     */
+    readonly stallEnded: OperationCompletedEvent<StallEndedReason>;
     /**
      * Fired when the time indicated by the currentTime attribute has been updated.
      */
@@ -230,7 +243,20 @@ export declare enum WaitedReason {
  * A list of all events that cause the 2nd-order 'waited' event.
  */
 export declare const waitedReasons: readonly [WaitedReason.PLAYING, WaitedReason.PAUSE, WaitedReason.EMPTIED, WaitedReason.SEEKING];
-export declare const ALL_PLAYBACK_STATE_EVENTS: readonly ["abort", "canPlay", "canPlayThrough", "durationChange", "emptied", "ended", "error", "playIsPendingChange", "loadedData", "loadedMetadata", "loadStart", "looped", "mutedChange", "pause", "play", "playRejected", "played", "playing", "progress", "rateChange", "readyStateChange", "reset", "resize", "seeked", "seeking", "timeUpdate", "volumeChange", "waited", "waiting", "waitingForKey"];
+/**
+ * Reasons a stall (see {@link PlaybackControllerEventMap.stallEntered}) has ended.
+ */
+export declare enum StallEndedReason {
+    /** The play head advanced again — playback resumed. */
+    PLAYING = "playing",
+    /** Playback was paused. */
+    PAUSE = "pause",
+    /** A seek started. */
+    SEEKING = "seeking",
+    /** The media was emptied (e.g. unloaded/reloaded). */
+    EMPTIED = "emptied"
+}
+export declare const ALL_PLAYBACK_STATE_EVENTS: readonly ["abort", "canPlay", "canPlayThrough", "durationChange", "emptied", "ended", "error", "playIsPendingChange", "loadedData", "loadedMetadata", "loadStart", "looped", "mutedChange", "pause", "play", "playRejected", "played", "playing", "progress", "rateChange", "readyStateChange", "reset", "resize", "seeked", "seeking", "stallEntered", "stallEnded", "timeUpdate", "volumeChange", "waited", "waiting", "waitingForKey"];
 export declare enum PlaybackReadyState {
     /**
      * No information is available about the media resource.

package/dist/types/current/playback/ReadonlyPlaybackController.d.ts.map

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

package/dist/types/current/playback/ReadonlyPlaybackController.js

@@ -48,6 +48,20 @@ export const waitedReasons = [
     WaitedReason.EMPTIED,
     WaitedReason.SEEKING,
 ];
+/**
+ * Reasons a stall (see {@link PlaybackControllerEventMap.stallEntered}) has ended.
+ */
+export var StallEndedReason;
+(function (StallEndedReason) {
+    /** The play head advanced again — playback resumed. */
+    StallEndedReason["PLAYING"] = "playing";
+    /** Playback was paused. */
+    StallEndedReason["PAUSE"] = "pause";
+    /** A seek started. */
+    StallEndedReason["SEEKING"] = "seeking";
+    /** The media was emptied (e.g. unloaded/reloaded). */
+    StallEndedReason["EMPTIED"] = "emptied";
+})(StallEndedReason || (StallEndedReason = {}));
 export const ALL_PLAYBACK_STATE_EVENTS = [
     'abort',
     'canPlay',
@@ -74,6 +88,8 @@ export const ALL_PLAYBACK_STATE_EVENTS = [
     'resize',
     'seeked',
     'seeking',
+    'stallEntered',
+    'stallEnded',
     'timeUpdate',
     'volumeChange',
     'waited',

package/dist/types/current/playback/createStallDetector.d.ts

@@ -0,0 +1,43 @@
+export interface StallDetectorOptions {
+    /**
+     * Called when playback resumes without emitting a `playing` event (or after the detector
+     * revived it), so the caller can announce playback.
+     */
+    readonly fabricatePlaying: () => void;
+    /** Poll interval in seconds. Default: 0.25 */
+    readonly pollInterval?: number;
+    /** Seconds the play head must be frozen before recovering. Default: 0.75 */
+    readonly stallThreshold?: number;
+    /**
+     * Don't nudge this close to the end of buffered data; a freeze there is a
+     * legitimate wait for more data. Seconds. Default: 0.5
+     */
+    readonly bufferEndMargin?: number;
+    /** Seconds to nudge the play head forward to prod a resume. Default: 0.1 */
+    readonly stallSkip?: number;
+    /** Max recovery attempts before giving up. Default: 3 */
+    readonly maxAttempts?: number;
+    /**
+     * Nudge even when the playhead isn't inside a buffered range. Some WebKit versions leave a
+     * seek perpetually pending (no `seeked`) with a stale empty `buffered` even though data is
+     * appended; re-issuing the seek via a nudge can complete it. Off by default (only nudge over
+     * genuinely buffered data). Default: false
+     */
+    readonly nudgeUnbuffered?: boolean;
+}
+/**
+ * Watches a media element after a seek/play and drives it back into a playing state. Some WebKit
+ * versions stall: the play head freezes inside buffered data and playback never resumes (often with
+ * a stale low readyState). This polls the play head and, while the element should be advancing:
+ *
+ * - if it's frozen inside buffered data, nudges currentTime forward to prod a resume;
+ * - if there's no data at the playhead, waits (it's legitimately buffering, or between sources).
+ *
+ * When the play head progresses it calls {@link StallDetectorOptions.fabricatePlaying} if playback
+ * resumed without a `playing` event (or after the detector revived it), then stops. It also stops
+ * on pause/ended/emptied or after {@link StallDetectorOptions.maxAttempts}.
+ *
+ * Start it after a seek or play only when playback is intended — a paused element won't advance.
+ */
+export declare function createStallDetector(media: HTMLMediaElement, options: StallDetectorOptions): () => void;
+//# sourceMappingURL=createStallDetector.d.ts.map

package/dist/types/current/playback/createStallDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createStallDetector.d.ts","sourceRoot":"","sources":["../../../../src/playback/createStallDetector.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,oBAAoB;IACjC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,IAAI,CAAA;IACrC,8CAA8C;IAC9C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,4EAA4E;IAC5E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAA;CACrC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAC/B,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,oBAAoB,GAC9B,MAAM,IAAI,CAgEZ"}

package/dist/types/current/playback/createStallDetector.js

@@ -0,0 +1,101 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Watches a media element after a seek/play and drives it back into a playing state. Some WebKit
+ * versions stall: the play head freezes inside buffered data and playback never resumes (often with
+ * a stale low readyState). This polls the play head and, while the element should be advancing:
+ *
+ * - if it's frozen inside buffered data, nudges currentTime forward to prod a resume;
+ * - if there's no data at the playhead, waits (it's legitimately buffering, or between sources).
+ *
+ * When the play head progresses it calls {@link StallDetectorOptions.fabricatePlaying} if playback
+ * resumed without a `playing` event (or after the detector revived it), then stops. It also stops
+ * on pause/ended/emptied or after {@link StallDetectorOptions.maxAttempts}.
+ *
+ * Start it after a seek or play only when playback is intended — a paused element won't advance.
+ */
+export function createStallDetector(media, options) {
+    const { fabricatePlaying } = options;
+    const pollInterval = options.pollInterval ?? 0.25;
+    const stallThreshold = options.stallThreshold ?? 0.75;
+    const bufferEndMargin = options.bufferEndMargin ?? 0.5;
+    const stallSkip = options.stallSkip ?? 0.1;
+    const maxAttempts = options.maxAttempts ?? 3;
+    const nudgeUnbuffered = options.nudgeUnbuffered ?? false;
+    let lastTime = media.currentTime;
+    let stalledFor = 0;
+    let attempts = 0;
+    let sawPlaying = false;
+    let recovered = false;
+    const onPlaying = () => {
+        sawPlaying = true;
+    };
+    // A cleared source (track unload) means there's nothing to recover.
+    const onEmptied = () => stop();
+    media.addEventListener('playing', onPlaying);
+    media.addEventListener('emptied', onEmptied);
+    const stop = () => {
+        clearInterval(id);
+        media.removeEventListener('playing', onPlaying);
+        media.removeEventListener('emptied', onEmptied);
+    };
+    const id = setInterval(() => {
+        // Only a playing element is expected to advance.
+        if (media.paused || media.ended)
+            return stop();
+        if (media.currentTime !== lastTime) {
+            lastTime = media.currentTime;
+            // Progressing. Announce playback if it resumed without a `playing`
+            // event, or if the detector had to revive it (a prior `playing` was
+            // cleared by the intervening stall).
+            if (!sawPlaying || recovered)
+                fabricatePlaying();
+            return stop();
+        }
+        // Frozen. Recover only over buffered data; otherwise it's legitimately
+        // waiting to buffer (or between sources) and nudging can disrupt
+        // loading — except on platforms whose `buffered` is unreliable here
+        // ({@link nudgeUnbuffered}), where re-issuing the seek is the recovery.
+        if (!nudgeUnbuffered && !withinBufferedData(media, bufferEndMargin)) {
+            stalledFor = 0;
+            return;
+        }
+        stalledFor += pollInterval;
+        if (stalledFor < stallThreshold)
+            return;
+        stalledFor = 0;
+        if (attempts++ >= maxAttempts)
+            return stop();
+        recovered = true;
+        // Data is buffered at the playhead — a small nudge prods a resume.
+        // (iOS can sit here reporting a stale low readyState even though the
+        // range around the playhead is buffered.)
+        media.currentTime += stallSkip;
+        lastTime = media.currentTime;
+    }, pollInterval * 1000);
+    return stop;
+}
+/**
+ * True when the play head sits inside a buffered range, clear of its end by
+ * {@link endMargin} — i.e. there is data to keep playing.
+ *
+ * A range that ends at the end of the media is treated as nudgeable up to its
+ * end: no more data is coming, so a freeze there is a stuck end-of-track (seen
+ * on progressive `src` tracks), and a nudge pushes the element to `ended`.
+ */
+function withinBufferedData(media, endMargin) {
+    const t = media.currentTime;
+    const duration = media.duration;
+    const buffered = media.buffered;
+    for (let i = 0; i < buffered.length; i++) {
+        const end = buffered.end(i);
+        const isEndOfMedia = Number.isFinite(duration) &&
+            duration > 0 &&
+            end >= duration - endMargin;
+        if (t >= buffered.start(i) && (t < end - endMargin || isEndOfMedia))
+            return true;
+    }
+    return false;
+}

package/dist/types/current/playback/createStallMonitor.d.ts

@@ -0,0 +1,45 @@
+import { type Timestamp } from '@amazon/vinyl-util';
+import type { ReadonlyPlaybackController } from './ReadonlyPlaybackController';
+import { StallEndedReason } from './ReadonlyPlaybackController';
+export interface StallMonitorOptions {
+    /**
+     * Seconds the play head must be frozen (no `timeUpdate`) while playing before a stall is
+     * reported. Default: 1
+     */
+    readonly stallThreshold?: number;
+    /**
+     * How often (seconds) the play head freeze is checked. Default: 0.25
+     */
+    readonly pollInterval?: number;
+}
+export interface StallEndedInfo {
+    /** Time of the last `timeUpdate` observed before the play head froze. */
+    readonly started: Timestamp;
+    /** Time the stall ended. */
+    readonly ended: Timestamp;
+    /** Total seconds the play head was frozen. */
+    readonly duration: number;
+    /** Why the stall ended. */
+    readonly reason: StallEndedReason;
+}
+export interface StallMonitorCallbacks {
+    /** Called when a stall is first detected. */
+    readonly onStallEntered: () => void;
+    /** Called when a detected stall ends. */
+    readonly onStallEnded: (info: StallEndedInfo) => void;
+}
+/**
+ * Watches a {@link ReadonlyPlaybackController} for stalls while playing: the play head freezing
+ * (no `timeUpdate`) for longer than {@link StallMonitorOptions.stallThreshold} seconds.
+ *
+ * Detection only runs once playback has actually been observed (a `playing` event) and is
+ * suspended on `pause`/`seeking`/`emptied` until playback is observed again — so a stall is never
+ * reported during initial loading or while awaiting a seek. A detected stall ends when the play
+ * head advances again (`playing`) or playback stops for another reason (`pause`/`seeking`/
+ * `emptied`); {@link StallEndedInfo.duration} is measured from the last `timeUpdate` before the
+ * freeze, so it reflects the full frozen time rather than only the time past the threshold.
+ *
+ * Returns a function that stops the monitor.
+ */
+export declare function createStallMonitor(controller: ReadonlyPlaybackController, callbacks: StallMonitorCallbacks, options?: StallMonitorOptions): () => void;
+//# sourceMappingURL=createStallMonitor.d.ts.map

package/dist/types/current/playback/createStallMonitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createStallMonitor.d.ts","sourceRoot":"","sources":["../../../../src/playback/createStallMonitor.ts"],"names":[],"mappings":"AAKA,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAA;AACnE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAA;AAC9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AAE/D,MAAM,WAAW,mBAAmB;IAChC;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAEhC;;OAEG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CACjC;AAED,MAAM,WAAW,cAAc;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAA;IAC3B,4BAA4B;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;CACpC;AAED,MAAM,WAAW,qBAAqB;IAClC,6CAA6C;IAC7C,QAAQ,CAAC,cAAc,EAAE,MAAM,IAAI,CAAA;IACnC,yCAAyC;IACzC,QAAQ,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAA;CACxD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAC9B,UAAU,EAAE,0BAA0B,EACtC,SAAS,EAAE,qBAAqB,EAChC,OAAO,GAAE,mBAAwB,GAClC,MAAM,IAAI,CA8EZ"}

package/dist/types/current/playback/createStallMonitor.js

@@ -0,0 +1,94 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { createDisposer } from '@amazon/vinyl-util';
+import { StallEndedReason } from './ReadonlyPlaybackController';
+/**
+ * Watches a {@link ReadonlyPlaybackController} for stalls while playing: the play head freezing
+ * (no `timeUpdate`) for longer than {@link StallMonitorOptions.stallThreshold} seconds.
+ *
+ * Detection only runs once playback has actually been observed (a `playing` event) and is
+ * suspended on `pause`/`seeking`/`emptied` until playback is observed again — so a stall is never
+ * reported during initial loading or while awaiting a seek. A detected stall ends when the play
+ * head advances again (`playing`) or playback stops for another reason (`pause`/`seeking`/
+ * `emptied`); {@link StallEndedInfo.duration} is measured from the last `timeUpdate` before the
+ * freeze, so it reflects the full frozen time rather than only the time past the threshold.
+ *
+ * Returns a function that stops the monitor.
+ */
+export function createStallMonitor(controller, callbacks, options = {}) {
+    const stallThresholdMs = (options.stallThreshold ?? 1) * 1000;
+    const pollIntervalMs = (options.pollInterval ?? 0.25) * 1000;
+    // Only detect once playback has been observed; gates out initial load and post-seek buffering.
+    let observedPlaying = false;
+    // Wall-clock time of the last `timeUpdate` — the reference start of any freeze.
+    let lastProgressAt = Date.now();
+    let inStall = false;
+    let pollId = null;
+    const endStall = (reason) => {
+        if (!inStall)
+            return;
+        inStall = false;
+        const ended = Date.now();
+        callbacks.onStallEnded({
+            started: lastProgressAt,
+            ended,
+            duration: (ended - lastProgressAt) / 1000,
+            reason,
+        });
+    };
+    const stopPoll = () => {
+        if (pollId == null)
+            return;
+        clearInterval(pollId);
+        pollId = null;
+    };
+    const startPoll = () => {
+        if (pollId != null)
+            return;
+        pollId = setInterval(() => {
+            if (inStall || !observedPlaying)
+                return;
+            if (Date.now() - lastProgressAt >= stallThresholdMs) {
+                inStall = true;
+                callbacks.onStallEntered();
+            }
+        }, pollIntervalMs);
+    };
+    // Playback stopped for a non-resume reason: close any open stall and suspend detection until
+    // playback is observed again.
+    const suspend = (reason) => {
+        endStall(reason);
+        observedPlaying = false;
+        stopPoll();
+    };
+    const { add, dispose } = createDisposer();
+    add(controller.on('playing', () => {
+        // Resuming from a stall closes it; otherwise this is a fresh start of playback, so
+        // begin the freeze clock now (no `timeUpdate` has necessarily arrived yet).
+        if (inStall)
+            endStall(StallEndedReason.PLAYING);
+        else
+            lastProgressAt = Date.now();
+        observedPlaying = true;
+        startPoll();
+    }));
+    add(controller.on('timeUpdate', () => {
+        // The play head advanced: close any open stall, then reset the freeze clock.
+        if (inStall)
+            endStall(StallEndedReason.PLAYING);
+        lastProgressAt = Date.now();
+    }));
+    add(controller.on('pause', () => suspend(StallEndedReason.PAUSE)));
+    add(controller.on('seeking', () => suspend(StallEndedReason.SEEKING)));
+    add(controller.on('emptied', () => suspend(StallEndedReason.EMPTIED)));
+    let stopped = false;
+    return () => {
+        if (stopped)
+            return;
+        stopped = true;
+        stopPoll();
+        dispose();
+    };
+}

package/dist/types/current/streaming/AudioOptions.d.ts

@@ -1,4 +1,5 @@
 import type { ObjectSchema } from '@amazon/vinyl-validation';
+import type { Maybe } from '@amazon/vinyl-util';
 /**
  * Criteria used to pick which audio rendition to play.
  */
@@ -33,6 +34,32 @@ export interface AudioOptions {
      * The audio selection criteria (language / descriptive).
      */
     readonly selection?: AudioSelection;
+    /**
+     * When `true`, disables the audio sampling-rate support filter, so audio
+     * renditions whose sampling rate exceeds what the platform reports (via the
+     * `AudioContext` output rate) are kept and offered to playback anyway.
+     * `false` (the default) applies the filter. Changing this re-filters the
+     * timeline immediately.
+     */
+    readonly disableSampleRateFilter?: boolean;
+    /**
+     * The maximum audio sampling rate (Hz) the sampling-rate filter treats as
+     * supported. When set, it takes precedence over the platform's
+     * `AudioContext`-reported output rate. Ignored when
+     * {@link disableSampleRateFilter} is `true`. Changing this re-filters the
+     * timeline immediately. `null`/`undefined` falls back to the reported rate.
+     */
+    readonly maxSampleRate?: Maybe<number>;
+    /**
+     * The minimum audio sampling rate (Hz) the sampling-rate filter treats as
+     * supported. When set, renditions below it are filtered out as a soft floor
+     * (if every audio rendition is below it, the highest is kept so playback is
+     * never stranded). Applied alongside the max cap whenever the filter runs,
+     * regardless of how the max was determined; ignored when
+     * {@link disableSampleRateFilter} is `true`. Changing this re-filters the
+     * timeline immediately.
+     */
+    readonly minSampleRate?: Maybe<number>;
 }
 export declare const defaultAudioOptions: AudioOptions;
 export declare const audioOptionsValidator: ObjectSchema<AudioOptions>;

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

@@ -1 +1 @@
-{"version":3,"file":"AudioOptions.d.ts","sourceRoot":"","sources":["../../../../src/streaming/AudioOptions.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAG5D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,IAAI,CAAA;IAErD;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IACzB;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAA;CACtC;AAED,eAAO,MAAM,mBAAmB,EAAE,YAEjC,CAAA;AAOD,eAAO,MAAM,qBAAqB,EAAE,YAAY,CAAC,YAAY,CAE3D,CAAA"}
+{"version":3,"file":"AudioOptions.d.ts","sourceRoot":"","sources":["../../../../src/streaming/AudioOptions.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAQ5D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAE/C;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,IAAI,CAAA;IAErD;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IACzB;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAA;IAEnC;;;;;;OAMG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAA;IAE1C;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;IAEtC;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;CACzC;AAED,eAAO,MAAM,mBAAmB,EAAE,YAGjC,CAAA;AAOD,eAAO,MAAM,qBAAqB,EAAE,YAAY,CAAC,YAAY,CAK3D,CAAA"}

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

@@ -2,9 +2,10 @@
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
-import { array, boolean, object, string } from '@amazon/vinyl-validation';
+import { array, boolean, number, object, string, } from '@amazon/vinyl-validation';
 export const defaultAudioOptions = {
     selection: { language: null, descriptive: false },
+    disableSampleRateFilter: false,
 };
 const audioSelectionValidator = object({
     language: string().or(array(string()).readonly()).orNull().optional(),
@@ -12,4 +13,7 @@ const audioSelectionValidator = object({
 });
 export const audioOptionsValidator = object({
     selection: audioSelectionValidator.optional(),
+    disableSampleRateFilter: boolean().optional(),
+    maxSampleRate: number().maybe().optional(),
+    minSampleRate: number().maybe().optional(),
 });