@amazon/vinyl 1.1.1 → 2.0.0

package/dist/types/ts3.7/streaming/ContentStream.d.ts

@@ -1,8 +1,8 @@
 import { Disposable, EventHostImpl, Maybe, ReadonlyEventHost, ReadonlyRanges } from '@amazon/vinyl-util';
-import { StreamingEventMap } from '../streaming/StreamingEventMap';
-import { SegmentController } from '../streaming/SegmentController';
-import { BufferingController } from '../streaming/buffering/BufferingController';
-import { ContentType, MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
+import { StreamingEventMap } from './StreamingEventMap';
+import { SegmentController } from './SegmentController';
+import { BufferingController } from './buffering/BufferingController';
+import { ContentType, MediaQualityMetadata } from './MediaQualityMetadata';
 import { Factories } from '@amazon/vinyl-di';
 /**
  * Creates a new ContentStream for the given content type.
@@ -38,6 +38,10 @@ export interface ContentStream extends ReadonlyEventHost<StreamingEventMap>, Dis
      * True if the last segment has been appended.
      */
     readonly bufferingEnded: boolean;
+    /**
+     * True while this stream's buffer holds any data.
+     */
+    readonly hasData: boolean;
     /**
      * Starts prefetching with the given priority and prefetch start time.
      * @param options
@@ -52,7 +56,7 @@ export interface ContentStream extends ReadonlyEventHost<StreamingEventMap>, Dis
     /**
      * Activates the content stream, activating sub-controllers.
      */
-    activate(options: ContentStreamActivateOptions): void;
+    activate(options: Maybe<ContentStreamActivateOptions>): void;
     /**
      * Deactivates the content stream, deactivating sub-controllers.
      */
@@ -81,6 +85,8 @@ export interface ContentStreamImplDeps {
 }
 export declare class ContentStreamImpl extends EventHostImpl<StreamingEventMap> implements ContentStream {
     readonly contentType: ContentType;
+    get [Symbol.toStringTag](): string;
+    readonly logPrefix: string;
     private disposer;
     private readonly segmentController;
     private readonly bufferingController;
@@ -90,6 +96,7 @@ export declare class ContentStreamImpl extends EventHostImpl<StreamingEventMap>
     get streamingQuality(): (MediaQualityMetadata | null);
     get bufferingQuality(): (MediaQualityMetadata | null);
     get playbackQuality(): (MediaQualityMetadata | null);
+    get hasData(): boolean;
     get bufferingEnded(): boolean;
     get error(): (Error | null);
     /**

package/dist/types/ts3.7/streaming/ContentStreamingOptions.d.ts

@@ -1,5 +1,5 @@
-import { SegmentControllerImplOptions } from '../streaming/SegmentControllerImpl';
-import { BufferingControllerImplOptions } from '../streaming/buffering/BufferingController';
+import { SegmentControllerImplOptions } from './SegmentControllerImpl';
+import { BufferingControllerImplOptions } from './buffering/BufferingController';
 export interface ContentStreamingOptions {
     /**
      * Configuration for the segment controller.

package/dist/types/ts3.7/streaming/LoadMetric.d.ts

@@ -0,0 +1,58 @@
+import { Timestamp } from '@amazon/vinyl-util';
+import { TrackUri } from '../track/Track';
+/**
+ * The stage of the track-load journey a {@link LoadSpanMeasurement} describes.
+ *
+ * - `manifest`: fetching and parsing the DASH/HLS manifest.
+ * - `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';
+/**
+ * A timed span for one stage of a track load.
+ *
+ * Dispatched by the controller that owns the stage. Emitters attribute the span
+ * to the track it was measured for at the source (see {@link trackUri}); the
+ * player republishes it as a {@link LoadSpanEvent}. When the emitter cannot know
+ * the owning track, `trackUri` is omitted and the span is dropped rather than
+ * misattributed.
+ */
+export interface LoadSpanMeasurement {
+    readonly kind: LoadSpanKind;
+    /**
+     * When the stage began, as a unix millisecond timestamp.
+     */
+    readonly startTime: Timestamp;
+    /**
+     * When the stage completed, as a unix millisecond timestamp.
+     */
+    readonly endTime: Timestamp;
+    /**
+     * The track this span was measured for, stamped at the source by the
+     * emitter that knows which track initiated the load. Omitted only when the
+     * initiating track is not yet known (e.g. an encrypted event handled before
+     * buffering DRM info is set).
+     */
+    readonly trackUri?: TrackUri;
+}
+/**
+ * A {@link LoadSpanMeasurement} attributed to the track it was measured for.
+ *
+ * Emitted on the player as the `loadSpan` event.
+ */
+export interface LoadSpanEvent extends LoadSpanMeasurement {
+    readonly trackUri: TrackUri;
+}
+/**
+ * Player-level load metric events.
+ */
+export interface LoadMetricEventMap {
+    /**
+     * A stage of a track load completed. Reports the time span of the stage
+     * together with the track it belongs to. Consumers measuring end-to-end
+     * load latency key on the first event per `kind` and `trackUri`.
+     */
+    readonly loadSpan: LoadSpanEvent;
+}
+//# sourceMappingURL=LoadMetric.d.ts.map

package/dist/types/ts3.7/streaming/ManifestController.d.ts

@@ -1,5 +1,16 @@
 import { ObservableValue } from '@amazon/vinyl-observable';
-export interface ManifestController<T> extends ObservableValue<T> {
+import { ReadonlyAbort, ReadonlyEventHost } from '@amazon/vinyl-util';
+import { LoadSpanMeasurement } from './LoadMetric';
+/**
+ * Events a manifest controller dispatches.
+ */
+export interface ManifestControllerEventMap {
+    /**
+     * The initial manifest fetch completed.
+     */
+    readonly loadSpanMeasured: LoadSpanMeasurement;
+}
+export interface ManifestController<T> extends ObservableValue<T>, ReadonlyEventHost<ManifestControllerEventMap> {
     /**
      * Manually triggers a reload of the manifest.
      * A manifest reload will not clear currently fetched or buffered segments.
@@ -10,4 +21,8 @@ export interface ManifestController<T> extends ObservableValue<T> {
      */
     reset(): void;
 }
+/**
+ * Provides a manifest.
+ */
+export type ManifestProvider<T> = (abort?: ReadonlyAbort) => Promise<T>;
 //# sourceMappingURL=ManifestController.d.ts.map

package/dist/types/ts3.7/streaming/ManifestControllerImpl.d.ts

@@ -0,0 +1,40 @@
+import { MutableValue } from '@amazon/vinyl-observable';
+import { EventHandler, SignalOptions, Unsubscribe } from '@amazon/vinyl-util';
+import { ManifestController, ManifestControllerEventMap, ManifestProvider } from './ManifestController';
+export interface ManifestControllerImplDeps<T> {
+    readonly manifestProvider: ManifestProvider<T>;
+}
+export declare class ManifestControllerImpl<T> implements ManifestController<Promise<T>> {
+    private readonly deps;
+    get [Symbol.toStringTag](): string;
+    get logPrefix(): string;
+    private readonly _data;
+    private _error;
+    private readonly abortSlot;
+    private readonly disposer;
+    private readonly events;
+    private manifestSpanArmed;
+    constructor(deps: ManifestControllerImplDeps<T>);
+    on<K extends keyof ManifestControllerEventMap>(type: K, handler: EventHandler<ManifestControllerEventMap[K]>, options?: SignalOptions): Unsubscribe;
+    hasAnyListeners(): boolean;
+    hasListeners(type: keyof ManifestControllerEventMap): boolean;
+    readonly __eventMapType: import("@amazon/vinyl-util").Covariant<ManifestControllerEventMap>;
+    get error(): (Error | null);
+    refresh(): void;
+    private requestManifest;
+    /**
+     * Measures the initial manifest fetch as a load span, re-arming on failure
+     * so a recovered load is still measured.
+     */
+    private measureLoadSpan;
+    reset(): void;
+    get value(): Promise<T>;
+    get changeId(): number;
+    getValue(): Promise<T>;
+    onData(callback: (value: Promise<T>, previous?: Promise<T>) => void): () => void;
+    map<U>(fn: (value: Promise<T>) => U): import("@amazon/vinyl-observable").ObservableValue<U>;
+    pick<K extends keyof NonNullable<Promise<T>>>(key: K): MutableValue<Promise<T>[K]>;
+    get disposed(): boolean;
+    dispose(): void;
+}
+//# sourceMappingURL=ManifestControllerImpl.d.ts.map

package/dist/types/ts3.7/streaming/MediaQualityMetadata.d.ts

@@ -1,7 +1,7 @@
 import { Maybe, MutableDeep } from '@amazon/vinyl-util';
 import { ObjectSchema } from '@amazon/vinyl-validation';
-import { DescriptorRecord } from '../streaming/DescriptorRecord';
-import { DrmInitDataType } from '../streaming/DrmInitDataType';
+import { DescriptorRecord } from './DescriptorRecord';
+import { DrmInitDataType } from './DrmInitDataType';
 import { CencEncryptionScheme } from '../drm/CencEncryptionScheme';
 import { DrmKeySystem } from '../drm/DrmKeySystem';
 import { FrameRate } from '@amazon/vinyl-mpd-parser';
@@ -11,6 +11,17 @@ export declare const ALL_CONTENT_TYPES: [
     "audio",
     "text"
 ];
+/**
+ * The content types that can be restricted via an allow list (see
+ * `VinylOptions.allowedContentTypes`). Text is intentionally excluded: text
+ * tracks (subtitles / closed captions) are governed by caption selection, not
+ * by the content-type allow list, so they always remain available.
+ */
+export type RestrictableContentType = Exclude<ContentType, 'text'>;
+export declare const RESTRICTABLE_CONTENT_TYPES: [
+    "video",
+    "audio"
+];
 /**
  * Contains media formatting and encryption metadata.
  */
@@ -117,6 +128,14 @@ export interface MediaQualityMetadata extends MediaFormatMetadata {
      * Specifies the language of the content, using a code as defined by RFC 5646.
      */
     readonly lang: string | null;
+    /**
+     * Media characteristics / accessibility roles describing this rendition,
+     * e.g. `public.accessibility.describes-video` (HLS CHARACTERISTICS) or a
+     * DASH Role / Accessibility scheme value such as `description`. Used to keep
+     * accessibility renditions (e.g. audio description) from being auto-selected
+     * by default. Empty when none are signaled.
+     */
+    readonly characteristics: readonly string[];
     /**
      * Identifies the group this quality belongs to (e.g. the adaptation set).
      */

package/dist/types/ts3.7/streaming/MediaTimeline.d.ts

@@ -1,6 +1,7 @@
-import { SegmentReference } from '../streaming/SegmentReference';
-import { SegmentDataProvider } from '../streaming/SegmentDataSlot';
-import { MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
+import { SegmentReference } from './SegmentReference';
+import { SegmentDataProvider } from './SegmentDataSlot';
+import { MediaQualityMetadata } from './MediaQualityMetadata';
+import { AdBreakList } from '../ad/AdBreakInfo';
 /**
  * Represents a single quality within a period, providing access to its metadata
  * and segment data.
@@ -32,11 +33,17 @@ export interface MediaTimeline {
      * The minimum duration of the buffer that a client should maintain for uninterrupted playback.
      */
     readonly minBufferTime: number;
+    /**
+     * Ad breaks discovered from the media presentation (e.g. HLS Interstitials,
+     * DASH SCTE-35). Empty when the stream carries no ad signals.
+     */
+    getAdBreaks(): Promise<AdBreakList>;
     /**
      * The total duration of the media, in seconds.
-     * Returns null if duration cannot be determined.
+     * Returns `Infinity` for live streams.
+     * Rejects when there are no segments to derive a duration from.
      */
-    getDuration?(): Promise<number | null>;
+    getDuration(): Promise<number>;
 }
 /**
  * Gets the period spanning the given presentation time.

package/dist/types/ts3.7/streaming/SegmentController.d.ts

@@ -1,7 +1,8 @@
 import { AnyRecord, Disposable, ReadonlyAbort, ReadonlyEventHost, ReadonlyRanges } from '@amazon/vinyl-util';
-import { SegmentReference } from '../streaming/SegmentReference';
+import { SegmentReference } from './SegmentReference';
 import { ChangeEvent } from '../event/ChangeEvent';
-import { MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
+import { MediaQualityMetadata } from './MediaQualityMetadata';
+import { LoadSpanMeasurement } from './LoadMetric';
 /**
  * Forward-snap tolerance, in seconds, applied when looking up a segment by time.
  *
@@ -32,6 +33,10 @@ export interface SegmentControllerEventMap {
      * This is dispatched when a new quality is requested.
      */
     readonly streamingQualityChange: ChangeEvent<MediaQualityMetadata | null>;
+    /**
+     * The first init or media segment fetch of this stream completed.
+     */
+    readonly loadSpanMeasured: LoadSpanMeasurement;
 }
 /**
  * The SegmentController provides segments to buffer for the given time.
@@ -48,11 +53,6 @@ export interface ReadonlySegmentController extends ReadonlyEventHost<SegmentCont
      * The most recently requested quality metadata.
      */
     readonly streamingQuality: MediaQualityMetadata | null;
-    /**
-     * The duration of the media, in seconds.
-     * Returns null if duration cannot be determined.
-     */
-    getDuration(): Promise<number | null>;
     /**
      * Returns a Promise for a segment covering the given time, with quality chosen by
      * the configured `QualitySelector`. Resolves to `null` if no media exists at that

package/dist/types/ts3.7/streaming/SegmentControllerImpl.d.ts

@@ -1,11 +1,11 @@
 import { EventHostImpl, ReadonlyAbort, ReadonlyRanges } from '@amazon/vinyl-util';
 import { ReadonlyPlaybackController } from '../playback/ReadonlyPlaybackController';
-import { PrefetchOptions, SegmentController, SegmentControllerEventMap } from '../streaming/SegmentController';
-import { SegmentReference } from '../streaming/SegmentReference';
-import { ContentType, MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
+import { PrefetchOptions, SegmentController, SegmentControllerEventMap } from './SegmentController';
+import { SegmentReference } from './SegmentReference';
+import { ContentType, MediaQualityMetadata } from './MediaQualityMetadata';
 import { ObservableValue } from '@amazon/vinyl-observable';
-import { MediaTimeline } from '../streaming/MediaTimeline';
-import { QualitySelector } from '../streaming/abr/QualitySelector';
+import { MediaTimeline } from './MediaTimeline';
+import { QualitySelector } from './abr/QualitySelector';
 /**
  * The interval to check if additional segments should be prefetched.
  */
@@ -44,6 +44,7 @@ export declare class SegmentControllerImpl extends EventHostImpl<SegmentControll
     readonly deps: SegmentControllerImplDeps;
     readonly contentType: ContentType;
     get [Symbol.toStringTag](): string;
+    readonly logPrefix: string;
     private _active;
     get active(): boolean;
     private readonly _fetchedRanges;
@@ -64,6 +65,8 @@ export declare class SegmentControllerImpl extends EventHostImpl<SegmentControll
     private ended;
     private prefetching;
     private _error;
+    private initSpanArmed;
+    private firstSegmentSpanArmed;
     private timeUpdateSub;
     private seekingSub;
     private readonly abort;
@@ -73,7 +76,6 @@ export declare class SegmentControllerImpl extends EventHostImpl<SegmentControll
     private _cachedPeriod;
     constructor(deps: SegmentControllerImplDeps, contentType: ContentType, options?: Partial<SegmentControllerImplOptions>);
     get error(): (Error | null);
-    getDuration(): Promise<number | null>;
     /**
      * Gets the period at the given time, using a cache for the last returned period.
      */
@@ -110,6 +112,15 @@ export declare class SegmentControllerImpl extends EventHostImpl<SegmentControll
     private getNextTimeToPrefetch;
     private pollPrefetch;
     private prefetchErrorHandler;
+    /**
+     * Requests init-segment data, measuring the first fetch as a load span.
+     */
+    private requestInitData;
+    /**
+     * Requests media-segment data, measuring the first fetch as a load span.
+     */
+    private requestSegmentData;
+    private measureLoadSpan;
     get fetchedRanges(): ReadonlyRanges;
     get fetchedTime(): number;
     private _streamingQuality;

package/dist/types/ts3.7/streaming/SegmentReference.d.ts

@@ -1,4 +1,4 @@
-import { MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
+import { MediaQualityMetadata } from './MediaQualityMetadata';
 export interface MediaSegmentMetadata {
     /**
      * The timestamp offset of the segment.

package/dist/types/ts3.7/streaming/StreamingEventMap.d.ts

@@ -1,7 +1,9 @@
 import { ChangeEvent } from '../event/ChangeEvent';
-import { ContentType, MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
+import { ContentType, MediaQualityMetadata } from './MediaQualityMetadata';
 import { BasicErrorEvent } from '../event/BasicErrorEvent';
 import { AnyRecord } from '@amazon/vinyl-util';
+import { SeekRange } from '../track/SeekRange';
+import { LoadSpanMeasurement } from './LoadMetric';
 /**
  * Events a track dispatches related to streaming quality and status.
  */
@@ -32,6 +34,10 @@ 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.
      */
@@ -48,6 +54,37 @@ export interface StreamingEventMap {
      * The available unfiltered qualities for the current period have changed.
      */
     readonly qualitiesUnfilteredChange: ChangeEvent<readonly MediaQualityMetadata[]>;
+    /**
+     * A codec the browser reported as supported failed to decode on append and
+     * has been denylisted at runtime. The current media should be reloaded so
+     * quality selection can fall back to a codec that decodes. Recoverable:
+     * this is dispatched instead of an `error`, and the player reloads the
+     * track in response.
+     */
+    readonly codecUnsupported: CodecUnsupportedEvent;
+    /**
+     * The seekable range on the media timeline has changed.
+     */
+    readonly seekRangeChange: ChangeEvent<SeekRange | null>;
+    /**
+     * A stage of the track load completed. Rather than redispatch this raw
+     * measurement, the player attributes it to the current track and
+     * republishes it as the `loadSpan` event.
+     */
+    readonly loadSpanMeasured: LoadSpanMeasurement;
+}
+/**
+ * Payload for {@link StreamingEventMap.codecUnsupported}.
+ */
+export interface CodecUnsupportedEvent {
+    /**
+     * The mimeType (including the failing codec) that was denylisted.
+     */
+    readonly mimeType: string;
+    /**
+     * The content type of the stream whose append failed.
+     */
+    readonly contentType: ContentType;
 }
 /**
  * All streaming-related events a track may emit.
@@ -60,9 +97,13 @@ export declare const ALL_STREAMING_EVENTS: readonly [
     "bufferingQualityChange",
     "playbackQualityChange",
     "bufferingEnded",
+    "hasDataChange",
     "error",
     "reset",
     "qualitiesChange",
-    "qualitiesUnfilteredChange"
+    "qualitiesUnfilteredChange",
+    "codecUnsupported",
+    "seekRangeChange",
+    "loadSpanMeasured"
 ];
 //# sourceMappingURL=StreamingEventMap.d.ts.map

package/dist/types/ts3.7/streaming/abr/QualitySelector.d.ts

@@ -1,4 +1,4 @@
-import { MediaQualityMetadata } from '../../streaming/MediaQualityMetadata';
+import { MediaQualityMetadata } from '../MediaQualityMetadata';
 export interface PrefetchState {
     /**
      * The number of seconds currently prefetched.

package/dist/types/ts3.7/streaming/abr/QualitySelectorImpl.d.ts

@@ -1,7 +1,7 @@
-import { PrefetchState, QualitySelector } from '../../streaming/abr/QualitySelector';
-import { Disposable, LogTarget } from '@amazon/vinyl-util';
+import { PrefetchState, QualitySelector } from './QualitySelector';
+import { Disposable, LogTarget, Maybe } from '@amazon/vinyl-util';
 import { ObjectSchema } from '@amazon/vinyl-validation';
-import { MediaQualityMetadata } from '../../streaming/MediaQualityMetadata';
+import { MediaQualityMetadata } from '../MediaQualityMetadata';
 import { ObservableValue } from '@amazon/vinyl-observable';
 export interface QualitySelectorImplOptions {
     /**
@@ -52,6 +52,46 @@ export interface QualitySelectorImplOptions {
      * Default: false
      */
     readonly restrictDecoderChangeOnAudioAbrUp?: boolean;
+    /**
+     * Maximum bandwidth in bits per second a quality may use to be selectable.
+     *
+     * Soft cap: if no qualities fit within the limit (including when set to 0),
+     * the quality with the lowest bandwidth is selected so playback is still
+     * possible.
+     *
+     * Has no effect when {@link strategy} is {@link AbrStrategy.LOWEST} or
+     * {@link AbrStrategy.HIGHEST}, since those strategies pin the selection
+     * regardless of bandwidth.
+     *
+     * Default: null (no limit).
+     */
+    readonly maxBandwidth?: Maybe<number>;
+    /**
+     * Maximum video height, in pixels, a quality may have to be selectable.
+     * Mirrors Shaka's `restrictions.maxHeight`.
+     *
+     * Only affects video qualities; audio (and other non-video) qualities are
+     * never restricted by resolution. Qualities with an unknown height (null)
+     * are treated as within the cap.
+     *
+     * Soft cap: if no video quality fits within the resolution limit, the
+     * quality with the smallest bandwidth is selected so video still plays.
+     *
+     * Has no effect when {@link strategy} is {@link AbrStrategy.LOWEST} or
+     * {@link AbrStrategy.HIGHEST}, since those strategies pin the selection
+     * regardless of resolution.
+     *
+     * Default: null (no limit).
+     */
+    readonly maxHeight?: Maybe<number>;
+    /**
+     * Maximum video width, in pixels, a quality may have to be selectable.
+     * Mirrors Shaka's `restrictions.maxWidth`. Behaves like {@link maxHeight}
+     * but constrains the width dimension.
+     *
+     * Default: null (no limit).
+     */
+    readonly maxWidth?: Maybe<number>;
 }
 export declare enum AbrStrategy {
     /**
@@ -82,6 +122,9 @@ export declare const defaultQualitySelectorImplOptions: {
     readonly bandwidthMultiplierLow: 0.4;
     readonly bandwidthMultiplierHigh: 0.9;
     readonly restrictDecoderChangeOnAudioAbrUp: false;
+    readonly maxBandwidth: null;
+    readonly maxHeight: null;
+    readonly maxWidth: null;
 };
 export interface QualitySelectorImplDeps {
     readonly options: ObservableValue<QualitySelectorImplOptions>;

package/dist/types/ts3.7/streaming/buffering/BufferingController.d.ts

@@ -1,17 +1,12 @@
 import { AnyRecord, Clearable, Disposable, EventHostImpl, ReadonlyEventHost } from '@amazon/vinyl-util';
 import { ReadonlyPlaybackController } from '../../playback/ReadonlyPlaybackController';
 import { SourceBufferController } from './SourceBufferController';
-import { ReadonlySegmentController } from '../../streaming/SegmentController';
+import { ReadonlySegmentController } from '../SegmentController';
 import { BasicErrorEvent } from '../../event/BasicErrorEvent';
 import { ChangeEvent } from '../../event/ChangeEvent';
-import { ContentType, MediaQualityMetadata } from '../../streaming/MediaQualityMetadata';
-import { MediaSourceController } from '../../streaming/buffering/MediaSourceController';
-/**
- * Chrome 52 has decoding errors when duration is set to the mediaPresentationDuration.
- * Adds a slight padding as a workaround.
- * @private
- */
-export declare const DURATION_PADDING = 0.1;
+import { ContentType, MediaQualityMetadata } from '../MediaQualityMetadata';
+import { CodecUnsupportedEvent } from '../StreamingEventMap';
+import { MediaSourceController } from './MediaSourceController';
 /**
  * The interval to throttle polling the buffer.
  * Reset after a seek.
@@ -49,6 +44,16 @@ 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
+     * reloaded and fall back to a codec that decodes.
+     */
+    readonly codecUnsupported: CodecUnsupportedEvent;
 }
 export interface BufferingController extends ReadonlyEventHost<BufferingControllerEventMap>, Clearable, Disposable {
     /**
@@ -78,6 +83,10 @@ 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.
      */
@@ -130,6 +139,7 @@ export declare class BufferingControllerImpl extends EventHostImpl<BufferingCont
     readonly deps: BufferingControllerImplDeps;
     readonly contentType: ContentType;
     get [Symbol.toStringTag](): string;
+    readonly logPrefix: string;
     readonly options: BufferingControllerImplOptions;
     private readonly mediaSourceController;
     private readonly playbackController;
@@ -153,6 +163,7 @@ export declare class BufferingControllerImpl extends EventHostImpl<BufferingCont
     private reopen;
     private _error;
     private _bufferingEnded;
+    private _hasData;
     private readonly queue;
     private disposer;
     private _active;
@@ -167,10 +178,6 @@ export declare class BufferingControllerImpl extends EventHostImpl<BufferingCont
     deactivate(): void;
     reset(): void;
     get busy(): boolean;
-    /**
-     * Enqueues a duration update.
-     */
-    private refreshDuration;
     /**
      * Resets the throttle and polls the buffer on the next frame.
      */
@@ -217,12 +224,32 @@ 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
+     * codec the browser reported as supported but cannot actually decode.
+     *
+     * Denylists the failing quality's codec so subsequent quality selection
+     * avoids it, then clears and retries. Returns true when a fallback was
+     * initiated (the caller should not enter an error state), false otherwise.
+     *
+     * Guards against loops: recovery only proceeds when the codec was newly
+     * denylisted. A repeat failure for an already-denylisted codec (e.g. a
+     * single-codec stream with no alternative) returns false and falls through
+     * to the normal error path, so playback errors out rather than looping.
+     */
+    private tryCodecFallback;
     /**
      * Returns the amount of time buffered at the current media position.
      * @private
      */
     getBufferedTime(): number;
+    /**
+     * Returns true if the playhead has become disconnected from the continuous buffer.
+     */
+    private needsBufferClear;
     /**
      * Cancels any currently buffering fragments and clears the source buffer.
      */