@amazon/vinyl 3.0.1 → 3.2.0

package/dist/types/ts4.1/streaming/LoadMetric.d.ts

@@ -1,14 +1,17 @@
 import type { Timestamp } from '@amazon/vinyl-util';
 import type { TrackUri } from '../track/Track';
+import type { ContentType } from './MediaQualityMetadata';
 /**
  * The stage of the track-load journey a {@link LoadSpanMeasurement} describes.
  *
  * - `manifest`: fetching and parsing the DASH/HLS manifest.
+ * - `keySetup`: the EME/CDM setup, from session creation to the CDM's first
+ *   license message. Precedes and is contiguous with `license`.
  * - `license`: the DRM license request/response exchange.
  * - `initSegment`: fetching the initialization segment.
  * - `firstSegment`: fetching the first media segment.
  */
-export type LoadSpanKind = 'manifest' | 'license' | 'initSegment' | 'firstSegment';
+export type LoadSpanKind = 'manifest' | 'keySetup' | 'license' | 'initSegment' | 'firstSegment';
 /**
  * A timed span for one stage of a track load.
  *
@@ -35,6 +38,17 @@ export interface LoadSpanMeasurement {
      * buffering DRM info is set).
      */
     readonly trackUri?: TrackUri;
+    /**
+     * The MIME type of the content this span was measured for, when known. Set
+     * for DRM `license` spans so a certificate exchange and the per-content-type
+     * license exchanges are distinguishable.
+     */
+    readonly mimeType?: string;
+    /**
+     * The content type this span was measured for, when known. Set alongside
+     * {@link mimeType} for DRM `license` spans.
+     */
+    readonly contentType?: ContentType;
 }
 /**
  * A {@link LoadSpanMeasurement} attributed to the track it was measured for.

package/dist/types/ts4.1/streaming/StreamingEventMap.d.ts

@@ -34,10 +34,6 @@ export interface StreamingEventMap {
      * The last segment has finished appending.
      */
     readonly bufferingEnded: AnyRecord;
-    /**
-     * The buffer went from empty to holding data, or back to empty.
-     */
-    readonly hasDataChange: ChangeEvent<boolean>;
     /**
      * Dispatched when a streaming error occurs.
      */
@@ -97,7 +93,6 @@ export declare const ALL_STREAMING_EVENTS: readonly [
     "bufferingQualityChange",
     "playbackQualityChange",
     "bufferingEnded",
-    "hasDataChange",
     "error",
     "reset",
     "qualitiesChange",

package/dist/types/ts4.1/streaming/buffering/BufferingController.d.ts

@@ -45,10 +45,6 @@ export interface BufferingControllerEventMap {
      * The last segment has finished appending.
      */
     readonly bufferingEnded: AnyRecord;
-    /**
-     * The buffer went from empty to holding data, or back to empty.
-     */
-    readonly hasDataChange: ChangeEvent<boolean>;
     /**
      * A codec the browser reported as supported failed to decode on append and
      * has been denylisted. Dispatched instead of `error` so the media can be
@@ -84,10 +80,6 @@ export interface BufferingController extends ReadonlyEventHost<BufferingControll
      * True if the stream has buffered the last segment.
      */
     readonly bufferingEnded: boolean;
-    /**
-     * True while the buffer holds any data (false when empty or cleared).
-     */
-    readonly hasData: boolean;
     /**
      * Begins buffering.
      */
@@ -164,7 +156,6 @@ export declare class BufferingControllerImpl extends EventHostImpl<BufferingCont
     private reopen;
     private _error;
     private _bufferingEnded;
-    private _hasData;
     private readonly queue;
     private disposer;
     private _active;
@@ -225,8 +216,6 @@ export declare class BufferingControllerImpl extends EventHostImpl<BufferingCont
      */
     private get mediaSourceClosed();
     get bufferingEnded(): boolean;
-    get hasData(): boolean;
-    private setHasData;
     private readonly handleError;
     /**
      * Attempts to recover from a SourceBuffer decode/append failure caused by a

package/dist/types/ts4.1/streaming/mediaTimelineFilter.d.ts

@@ -3,12 +3,14 @@ import type { MediaQualityMetadata } from './MediaQualityMetadata';
 import type { FilterPredicate, FilterPredicateAsync, Maybe } from '@amazon/vinyl-util';
 /**
  * Filters qualities in a MediaTimeline using a synchronous predicate.
- * If filtering would remove all qualities from any period, throws via `throwError`.
+ * If filtering drops an audio or video stream to zero in any period, throws via
+ * `throwError`.
  */
 export declare function filterTimelineQualities(filter: Maybe<FilterPredicate<MediaQualityMetadata>>, throwError: () => never, timeline: MediaTimeline): MediaTimeline;
 /**
  * Filters qualities in a MediaTimeline using an asynchronous predicate.
- * If filtering would remove all qualities from any period, throws via `throwError`.
+ * If filtering drops an audio or video stream to zero in any period, throws via
+ * `throwError`.
  */
 export declare function filterTimelineQualitiesAsync(filter: FilterPredicateAsync<MediaQualityMetadata>, throwError: () => never, timeline: MediaTimeline): Promise<MediaTimeline>;
 /**

package/dist/types/ts4.1/track/dash/DashMediaQualityMetadataResolver.d.ts

@@ -20,13 +20,17 @@ export interface DashMediaQualityMetadataResolverDeps {
 }
 export declare function createMediaQualityMetadataFromDashRepresentation(representation: RepresentationType, deps: DashMediaQualityMetadataResolverDeps): MediaQualityMetadata;
 /**
- * Estimates the total bandwidth a representation would use when paired with
- * proportionally matched qualities from sibling content types.
+ * Estimates the total bandwidth a representation uses alongside sibling content
+ * types, pairing it with the cheapest sibling rendition in its proportional
+ * bucket.
  *
- * For each sibling content type, the representation's relative position within its own
- * content type's sorted bandwidth list is mapped to the corresponding position in the
- * sibling's list. This produces realistic pairings — e.g. with video [v1,v2,v3,v4] and
- * audio [a1,a2], v1 pairs with a1, v2 with a1, v3 with a2, v4 with a2.
+ * Each content type's sorted list is split into as many buckets as this
+ * representation's own list has tiers; the representation is paired with the
+ * cheapest sibling rendition in the matching bucket. A stream with few tiers
+ * therefore stays selected across the span of a finer sibling's tiers (e.g. the
+ * top audio across the top half of video tiers) rather than being pinned to a
+ * single endpoint — with video [v1..v4] and audio [a1,a2], a1's bucket is
+ * v1..v2 so a1 pairs with v2, and a2's bucket is v3..v4 so a2 pairs with v4.
  */
 export declare function estimatePeakBandwidth(representation: RepresentationType, contentType: ContentType): number;
 /**

package/dist/types/ts4.1/track/dash/createDashFactories.d.ts

@@ -109,7 +109,7 @@ export declare function createDashFactories(options: Maybe<DashInitOptions>): (d
         readonly manifestTransformed: ObservableValue<Promise<DashManifestData>>;
         readonly options: ObservableValue<Pick<VinylOptions, "text">>;
     }) => SidecarTextTrackController;
-    options: import("@amazon/vinyl-di").Factory<ObservableValue<Pick<VinylOptions, "audio" | "text" | "abr" | "allowedContentTypes">>>;
+    options: import("@amazon/vinyl-di").Factory<ObservableValue<Pick<VinylOptions, "text" | "audio" | "abr" | "allowedContentTypes">>>;
     playbackController: import("@amazon/vinyl-di").Factory<PlaybackController>;
     playbackSource: import("@amazon/vinyl-di").Factory<PlaybackSource>;
     drmKeySystemResolver: import("@amazon/vinyl-di").Factory<DrmKeySystemResolver>;

package/dist/types/ts4.1/track/dash/util/mpd.d.ts

@@ -36,6 +36,12 @@ export declare function calculatePeriodTimeRange(period: PeriodType): PeriodRang
  *
  * In a static presentation, the first period SHALL start at the zero point of the MPD timeline (with a
  * Period@start value of 0 seconds).
+ *
+ * When `Period@start` is absent, the start is derived from the sum of the
+ * preceding periods' `Period@duration` values, per the PeriodStart derivation
+ * in ISO/IEC 23009-1 §5.3.2.1. This is common in on-demand manifests that
+ * declare only per-period durations (no explicit `@start`, no
+ * `MPD@mediaPresentationDuration`).
  */
 export declare function calculatePeriodStart(period: PeriodType): number;
 /**

package/dist/types/ts4.1/track/filters/resourceTypeFilter.d.ts

@@ -3,6 +3,10 @@ import type { MediaFormatMetadata } from '../../streaming/MediaQualityMetadata';
 export declare function throwMimeTypesUnsupported(): never;
 /**
  * Returns true when the media's codec and container is supported.
+ *
+ * Both ISO-BMFF (MP4/fMP4) and WebM containers are supported: the DASH
+ * `SegmentBase` indexer reads ISO-BMFF `sidx` boxes or WebM EBML `Cues` as
+ * appropriate, and MSE appends each to a matching SourceBuffer.
  */
 export declare function canPlayMimeType(deps: {
     readonly capabilities: Capabilities;

package/dist/types/ts4.1/track/filters/sampleRateFilter.d.ts

@@ -1,13 +1,31 @@
 import type { MediaQualityMetadata } from '../../streaming/MediaQualityMetadata';
 import type { Capabilities } from '../../client/Capabilities';
 export declare function throwSamplingRatesUnsupported(): never;
+export interface AudioSampleRateRangeOptions {
+    readonly capabilities: Capabilities;
+    /**
+     * An explicit maximum sampling rate that takes precedence over the
+     * platform's `AudioContext`-reported output rate when set.
+     */
+    readonly maxSampleRate?: number | null;
+    /** An optional minimum sampling-rate floor. */
+    readonly minSampleRate?: number | null;
+}
 /**
- * Returns true when the media's sampling rate is supported.
- * If Firefox (which does not support >48kHz), filter out all sampling rates above the supported sampling rate.
- * All other browsers filter out all sampling rates above the supported sampling rate unless this will filter all
- * and then do not filter the lowest sampling rate.
+ * Returns true when the media's sampling rate is within the supported range.
+ * Only audio content types are gated; every other content type passes through.
+ *
+ * The upper bound is `maxSampleRate` when set, otherwise the platform's
+ * `AudioContext`-reported output rate (Firefox is hard-capped at 48kHz, which it
+ * cannot decode beyond via MSE). The optional lower bound is `minSampleRate`.
+ * Both bounds are soft, and soft *together*: when no audio rendition sits in the
+ * acceptable `[minSampleRate, maxSampleRate]` band, a single fallback is kept so
+ * playback is never stranded — the highest rate the ceiling can decode, or, when
+ * every rate is above the ceiling, the lowest. This holds even when renditions
+ * straddle an empty band (some below the floor, some above the ceiling). Only
+ * audio renditions count toward the fallback — a co-present video quality (no
+ * audio rate) never influences it. Firefox is the exception: its 48kHz cap is
+ * hard, with no fallback.
  */
-export declare function supportsAudioSamplingRate(deps: {
-    readonly capabilities: Capabilities;
-}, metadata: MediaQualityMetadata, _index: number, array: ArrayLike<MediaQualityMetadata>): boolean;
+export declare function withinAudioSampleRateRange(options: AudioSampleRateRangeOptions, metadata: MediaQualityMetadata, _index: number, array: ArrayLike<MediaQualityMetadata>): boolean;
 //# sourceMappingURL=sampleRateFilter.d.ts.map

package/dist/types/ts4.1/track/hls/createHlsFactories.d.ts

@@ -98,7 +98,7 @@ export declare function createHlsFactories(options: Maybe<HlsInitOptions>): (dep
         readonly manifestTransformed: ObservableValue<Promise<HlsManifestData>>;
         readonly options: ObservableValue<Pick<VinylOptions, "text">>;
     }) => SidecarTextTrackController;
-    options: import("@amazon/vinyl-di").Factory<ObservableValue<Pick<VinylOptions, "audio" | "text" | "abr" | "allowedContentTypes">>>;
+    options: import("@amazon/vinyl-di").Factory<ObservableValue<Pick<VinylOptions, "text" | "audio" | "abr" | "allowedContentTypes">>>;
     playbackController: import("@amazon/vinyl-di").Factory<PlaybackController>;
     playbackSource: import("@amazon/vinyl-di").Factory<PlaybackSource>;
     drmKeySystemResolver: import("@amazon/vinyl-di").Factory<DrmKeySystemResolver>;

package/dist/types/ts4.1/track/mse/MseTrack.d.ts

@@ -15,15 +15,6 @@ import type { TextTrackController } from '../../text/TextTrack';
 import type { TrackConfigOptions } from '../TrackFactory';
 import type { TrackAds } from '../../ad/AdBreakInfo';
 import type { VinylOptions } from '../../vinyl/VinylOptions';
-/**
- * How long to wait after all streams have data before checking whether a seek
- * is still stuck, in seconds.
- */
-export declare const SEEKING_STALL_TIME_CHECK = 0.1;
-/**
- * How far to nudge the playhead, in seconds, to recover a stuck seek.
- */
-export declare const PLAYHEAD_NUDGE = 0.05;
 export type MseTrackDeps = TrackBaseDeps & {
     readonly contentTypesValue: ContentTypesValue;
     readonly contentStreamFactory: (contentType: ContentType) => ContentStream;
@@ -55,7 +46,6 @@ export declare class MseTrack extends TrackBase {
     protected readonly deps: MseTrackDeps;
     get textTrackController(): (TextTrackController | null);
     private readonly streams;
-    private stallNudgeTimer;
     private readonly disposeAbort;
     private lastPreloadOptions;
     private readonly allFetchedRanges;
@@ -130,13 +120,6 @@ export declare class MseTrack extends TrackBase {
     private getStream;
     private clearStreams;
     get bufferingEnded(): boolean;
-    /**
-     * A seek only completes once every stream has data at the target, but on
-     * some platforms the element can stay stuck `seeking` even after that. Once
-     * all streams hold data, if we're still seeking a moment later, nudge the
-     * playhead to prod the element into completing the seek.
-     */
-    private checkStalledSeek;
     private setContentTypes;
     dispose(): void;
 }

package/dist/types/ts4.1/util/media/mimeType.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Extracts the container subtype from a MIME type, lowercased — the portion
+ * after the `/`, ignoring any parameters. For example
+ * `video/webm; codecs="vp9"` → `webm` and `audio/mp4` → `mp4`. Returns an empty
+ * string when the MIME type has no subtype.
+ */
+export declare function mimeSubtype(mimeType: string): string;
+//# sourceMappingURL=mimeType.d.ts.map

package/dist/types/ts4.1/vinyl/VinylPlayer.d.ts

@@ -67,6 +67,11 @@ export declare class VinylPlayer<TrackLoadOptionsType extends TrackLoadOptions =
      * @see createVinylPlayer
      */
     protected constructor(factories: Factories<VinylDeps<TrackLoadOptionsType, OptionsType>>);
+    /**
+     * Logs each republished load span once at the verbose level, formatting its
+     * bounds as ISO date strings and its duration in milliseconds.
+     */
+    protected initializeLoadSpanLogging(): void;
     protected redispatchSubControllerEvents(): void;
     /**
      * Certain track events are redispatched on the player for the current track.

package/dist/types/ts4.1/vinyl/createVinylFactories.d.ts

@@ -1,6 +1,6 @@
 import type { CapabilitiesImplDeps } from '../client/CapabilitiesImpl';
 import { CapabilitiesImpl } from '../client/CapabilitiesImpl';
-import type { Merge, PartialDeep, PatchedRef } from '@amazon/vinyl-util';
+import type { Merge, PartialDeep } from '@amazon/vinyl-util';
 import { noop } from '@amazon/vinyl-util';
 import type { PlaybackControllerImplDeps, PlaybackControllerImplOptions } from '../playback/PlaybackControllerImpl';
 import { PlaybackControllerImpl } from '../playback/PlaybackControllerImpl';
@@ -9,7 +9,6 @@ import { PlaybackSourceImpl } from '../playback/PlaybackSourceImpl';
 import type { VinylTrackFactoryDeps } from '../track/createVinylTrackFactories';
 import type { TrackControllerImplDeps, TrackControllerImplOptions } from '../track/TrackController';
 import { TrackControllerImpl } from '../track/TrackController';
-import type { VinylPatchOptions } from './VinylPatchOptions';
 import type { QualitySelectorImplOptions } from '../streaming/abr/QualitySelectorImpl';
 import type { AdControllerImplDeps, AdControllerImplOptions } from '../ad/AdControllerImpl';
 import { AdControllerImpl } from '../ad/AdControllerImpl';
@@ -44,11 +43,6 @@ export interface VinylDependencyOptions {
      * `'hidden'`; without one they render natively. See `TextTrackRenderer`.
      */
     readonly textTrackRenderer?: TextTrackRenderer;
-    /**
-     * Flags for patches that should be applied browser-specifically.
-     * These will be defaulted based on the user-agent.
-     */
-    readonly patches?: PartialDeep<VinylPatchOptions>;
     /**
      * Configuration for the track controller.
      */
@@ -85,12 +79,7 @@ export interface VinylDependencyOptions {
  */
 export declare function createVinylFactories(options: VinylDependencyOptions): {
     options: (_deps: import("@amazon/vinyl-util").AnyRecord, add: import("@amazon/vinyl-util").AddDisposable) => import("@amazon/vinyl-observable").MutableValue<VinylOptions>;
-    patchedMedia: () => PatchedRef<HTMLMediaElement>;
-    media: (deps: {
-        readonly patchedMedia: {
-            readonly patched: HTMLMediaElement;
-        };
-    }) => HTMLMediaElement;
+    media: () => HTMLMediaElement;
     textTrackProvider: (deps: {
         readonly media: HTMLMediaElement;
     }) => MediaTextTrackProvider;
@@ -156,7 +145,7 @@ export declare function createVinylFactories(options: VinylDependencyOptions): {
             readonly manifestTransformed: ObservableValue<Promise<import("..").DashManifestData>>;
             readonly options: ObservableValue<Pick<VinylOptions, "text">>;
         }) => import("..").SidecarTextTrackController;
-        options: import("@amazon/vinyl-di").Factory<ObservableValue<Pick<VinylOptions, "audio" | "text" | "abr" | "allowedContentTypes">>>;
+        options: import("@amazon/vinyl-di").Factory<ObservableValue<Pick<VinylOptions, "text" | "audio" | "abr" | "allowedContentTypes">>>;
         playbackController: import("@amazon/vinyl-di").Factory<import("..").PlaybackController>;
         playbackSource: import("@amazon/vinyl-di").Factory<import("..").PlaybackSource>;
         drmKeySystemResolver: import("@amazon/vinyl-di").Factory<import("..").DrmKeySystemResolver>;
@@ -168,7 +157,9 @@ export declare function createVinylFactories(options: VinylDependencyOptions): {
         textTrackRenderer: import("@amazon/vinyl-di").Factory<TextTrackRenderer | null>;
         adController: import("@amazon/vinyl-di").Factory<import("..").AdController>;
     };
-    createHlsFactories: (deps: import("..").HlsFactoryDeps) => (loadOptions: import("..").HlsTrackLoadOptions) => {
+    createHlsFactories: (deps: import("..").HlsFactoryDeps) => (loadOptions: import("..").HlsTrackLoadOptions /**
+     * Configuration for adaptive bitrate switching.
+     */) => {
         baseContentTypesValue: typeof import("..").createHlsContentTypesValue;
         contentTypesValue: typeof import("..").createAllowedContentTypesValue;
         manifestProvider: () => import("..").HlsManifestProvider;
@@ -211,7 +202,7 @@ export declare function createVinylFactories(options: VinylDependencyOptions): {
             readonly manifestTransformed: ObservableValue<Promise<import("..").HlsManifestData>>;
             readonly options: ObservableValue<Pick<VinylOptions, "text">>;
         }) => import("..").SidecarTextTrackController;
-        options: import("@amazon/vinyl-di").Factory<ObservableValue<Pick<VinylOptions, "audio" | "text" | "abr" | "allowedContentTypes">>>;
+        options: import("@amazon/vinyl-di").Factory<ObservableValue<Pick<VinylOptions, "text" | "audio" | "abr" | "allowedContentTypes">>>;
         playbackController: import("@amazon/vinyl-di").Factory<import("..").PlaybackController>;
         playbackSource: import("@amazon/vinyl-di").Factory<import("..").PlaybackSource>;
         drmKeySystemResolver: import("@amazon/vinyl-di").Factory<import("..").DrmKeySystemResolver>;

package/dist/types/ts4.7/drm/DrmControllerImpl.d.ts

@@ -2,7 +2,7 @@ import { EventHostImpl, type Maybe } from '@amazon/vinyl-util';
 import { type DrmOptions } from './DrmOptions';
 import type { DrmController, DrmControllerEventMap, DrmKeySystemSupport, DrmPlaybackOptions } from './DrmController';
 import type { CommonEme, CommonMediaKeyMessageEvent, CommonMediaKeys, CommonMediaKeySession } from './commonEme/CommonEme';
-import type { MediaFormatMetadata } from '../streaming/MediaQualityMetadata';
+import type { ContentType, MediaFormatMetadata } from '../streaming/MediaQualityMetadata';
 import type { TrackUri } from '../track/Track';
 /**
  * The number of seconds a license request will be allowed before timing out.
@@ -30,6 +30,13 @@ export interface DrmControllerMessageProps {
      * to their own track.
      */
     readonly trackUri: TrackUri | null;
+    /**
+     * The MIME and content type of the session's content, captured at creation
+     * so the license span can distinguish the certificate exchange from the
+     * per-content-type license exchanges.
+     */
+    readonly mimeType: string;
+    readonly contentType: ContentType | null;
 }
 export declare class DrmControllerImpl extends EventHostImpl<DrmControllerEventMap> implements DrmController {
     private readonly deps;
@@ -44,6 +51,8 @@ export declare class DrmControllerImpl extends EventHostImpl<DrmControllerEventM
     private bufferingTrackUri;
     private sessionAbort;
     private pendingMessageProps;
+    private keySetupSpanArmed;
+    private keySetupSpanStart;
     private readonly disposer;
     constructor(deps: DrmControllerImplDeps, options?: Maybe<Partial<DrmOptions>>);
     configure(options: Maybe<Partial<DrmOptions>>): void;
@@ -64,7 +73,16 @@ export declare class DrmControllerImpl extends EventHostImpl<DrmControllerEventM
      * The new session will be added to the current sessions list.
      */
     private maybeCreateSession;
+    /**
+     * Captures the key-setup span start at the top of the session-creation path
+     * (before media keys are attached), latching so only the first session of
+     * the current track load is measured.
+     */
+    private markKeySetupStart;
+    private dispatchLoadSpan;
     initializeForPlayback(drmInfo: MediaFormatMetadata | null, options?: DrmPlaybackOptions): void;
+    /** True when the manifest carried pssh (sessions come from it, not events). */
+    private manifestProvidesInitData;
     setBufferingDrmInfo(drmInfo: MediaFormatMetadata | null, options?: DrmPlaybackOptions): void;
     /**
      * If the drm metadata contains initialization data for the current key system, create a new session.

package/dist/types/ts4.7/index.d.ts

@@ -38,11 +38,8 @@ export * from './global/environment';
 export * from './global/globalRef';
 export * from './global/initializeVinylGlobal';
 export * from './global/PlayerRegistry';
-export * from './patch/media/HtmlMediaElementPatch';
-export * from './patch/media/MediaElementPatchOptions';
-export * from './patch/media/patches/createPreventStallsPatch';
-export * from './patch/media/patches/createUnreliablePlaybackEventsPatch';
-export * from './patch/media/patchMediaElement';
+export * from './playback/createStallDetector';
+export * from './playback/createStallMonitor';
 export * from './playback/error/InvalidSeekError';
 export * from './playback/error/ReportableMediaError';
 export * from './playback/logging/mediaErrorToJson';
@@ -150,12 +147,12 @@ export * from './util/media/codecOverrides';
 export * from './util/media/codecSupport';
 export * from './util/media/getAudioContext';
 export * from './util/media/mediaSource';
+export * from './util/media/mimeType';
 export * from './util/media/sourceBuffer';
 export * from './vinyl/createVinylFactories';
 export * from './vinyl/playerConfigFactory';
 export * from './vinyl/ReadonlyPlaybackStreamingState';
 export * from './vinyl/VinylDeps';
 export * from './vinyl/VinylOptions';
-export * from './vinyl/VinylPatchOptions';
 export * from './vinyl/VinylPlayer';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/ts4.7/playback/PlaybackControllerImpl.d.ts

@@ -29,12 +29,19 @@ export interface PlaybackControllerImplOptions {
      * Default: 30
      */
     readonly seekTimeout: number;
+    /**
+     * The number of seconds the play head must be frozen while playing before a stall is reported
+     * via the `stallEntered`/`stallEnded` events.
+     * Default: 1
+     */
+    readonly stallThreshold: number;
 }
 export declare const defaultPlaybackControllerImplOptions: {
     readonly loopTimeAffordance: 2;
     readonly minSeekableBuffer: -1;
     readonly playTimeout: 30;
     readonly seekTimeout: 30;
+    readonly stallThreshold: 1;
 };
 /**
  * Safari and Edge Legacy cannot reliably seek close to the end of a seekable range.
@@ -57,6 +64,7 @@ export declare class PlaybackControllerImpl extends EventHostImpl<PlaybackContro
     private _seeking;
     private _waiting;
     private _seekId;
+    private stopStallDetection;
     private userVolume;
     private _pendingPlay;
     private playAbort;
@@ -153,6 +161,13 @@ export declare class PlaybackControllerImpl extends EventHostImpl<PlaybackContro
     pause(): void;
     private get pendingPlay();
     private set pendingPlay(value);
+    /**
+     * 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
+     */
+    private startStallDetection;
     play(): Promise<void>;
     get canPlay(): boolean;
     get canPlayThrough(): boolean;

package/dist/types/ts4.7/playback/ReadonlyPlaybackController.d.ts

@@ -194,6 +194,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.
      */
@@ -241,6 +254,19 @@ export declare const waitedReasons: readonly [
     WaitedReason.EMPTIED,
     WaitedReason.SEEKING
 ];
+/**
+ * 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",
@@ -267,6 +293,8 @@ export declare const ALL_PLAYBACK_STATE_EVENTS: readonly [
     "resize",
     "seeked",
     "seeking",
+    "stallEntered",
+    "stallEnded",
     "timeUpdate",
     "volumeChange",
     "waited",

package/dist/types/ts4.7/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/ts4.7/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