@amazon/vinyl 1.1.1 → 2.0.0

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

@@ -1,7 +1,8 @@
 import type { AnyRecord, Disposable, ReadonlyAbort, ReadonlyEventHost, ReadonlyRanges } from '@amazon/vinyl-util';
-import type { SegmentReference } from '../streaming/SegmentReference';
+import type { SegmentReference } from './SegmentReference';
 import type { ChangeEvent } from '../event/ChangeEvent';
-import type { MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
+import type { MediaQualityMetadata } from './MediaQualityMetadata';
+import type { 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/ts4.1/streaming/SegmentControllerImpl.d.ts

@@ -1,12 +1,12 @@
 import type { ReadonlyAbort, ReadonlyRanges } from '@amazon/vinyl-util';
 import { EventHostImpl } from '@amazon/vinyl-util';
 import type { ReadonlyPlaybackController } from '../playback/ReadonlyPlaybackController';
-import type { PrefetchOptions, SegmentController, SegmentControllerEventMap } from '../streaming/SegmentController';
-import type { SegmentReference } from '../streaming/SegmentReference';
-import type { ContentType, MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
+import type { PrefetchOptions, SegmentController, SegmentControllerEventMap } from './SegmentController';
+import type { SegmentReference } from './SegmentReference';
+import type { ContentType, MediaQualityMetadata } from './MediaQualityMetadata';
 import type { ObservableValue } from '@amazon/vinyl-observable';
-import type { MediaTimeline } from '../streaming/MediaTimeline';
-import type { QualitySelector } from '../streaming/abr/QualitySelector';
+import type { MediaTimeline } from './MediaTimeline';
+import type { QualitySelector } from './abr/QualitySelector';
 /**
  * The interval to check if additional segments should be prefetched.
  */
@@ -45,6 +45,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;
@@ -65,6 +66,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;
@@ -74,7 +77,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.
      */
@@ -111,6 +113,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/ts4.1/streaming/SegmentReference.d.ts

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

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

@@ -1,7 +1,9 @@
 import type { ChangeEvent } from '../event/ChangeEvent';
-import type { ContentType, MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
+import type { ContentType, MediaQualityMetadata } from './MediaQualityMetadata';
 import type { BasicErrorEvent } from '../event/BasicErrorEvent';
 import type { AnyRecord } from '@amazon/vinyl-util';
+import type { SeekRange } from '../track/SeekRange';
+import type { 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/ts4.1/streaming/abr/QualitySelector.d.ts

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

package/dist/types/ts4.1/streaming/abr/QualitySelectorImpl.d.ts

@@ -1,7 +1,7 @@
-import type { PrefetchState, QualitySelector } from '../../streaming/abr/QualitySelector';
-import type { Disposable, LogTarget } from '@amazon/vinyl-util';
+import type { PrefetchState, QualitySelector } from './QualitySelector';
+import type { Disposable, LogTarget, Maybe } from '@amazon/vinyl-util';
 import type { ObjectSchema } from '@amazon/vinyl-validation';
-import type { MediaQualityMetadata } from '../../streaming/MediaQualityMetadata';
+import type { MediaQualityMetadata } from '../MediaQualityMetadata';
 import type { 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/ts4.1/streaming/buffering/BufferingController.d.ts

@@ -2,17 +2,12 @@ import type { AnyRecord, Clearable, Disposable, ReadonlyEventHost } from '@amazo
 import { EventHostImpl } from '@amazon/vinyl-util';
 import type { ReadonlyPlaybackController } from '../../playback/ReadonlyPlaybackController';
 import type { SourceBufferController } from './SourceBufferController';
-import type { ReadonlySegmentController } from '../../streaming/SegmentController';
+import type { ReadonlySegmentController } from '../SegmentController';
 import type { BasicErrorEvent } from '../../event/BasicErrorEvent';
 import type { ChangeEvent } from '../../event/ChangeEvent';
-import type { ContentType, MediaQualityMetadata } from '../../streaming/MediaQualityMetadata';
-import type { 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 type { ContentType, MediaQualityMetadata } from '../MediaQualityMetadata';
+import type { CodecUnsupportedEvent } from '../StreamingEventMap';
+import type { MediaSourceController } from './MediaSourceController';
 /**
  * The interval to throttle polling the buffer.
  * Reset after a seek.
@@ -50,6 +45,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 {
     /**
@@ -79,6 +84,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.
      */
@@ -131,6 +140,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;
@@ -154,6 +164,7 @@ export declare class BufferingControllerImpl extends EventHostImpl<BufferingCont
     private reopen;
     private _error;
     private _bufferingEnded;
+    private _hasData;
     private readonly queue;
     private disposer;
     private _active;
@@ -168,10 +179,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.
      */
@@ -218,12 +225,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.
      */

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

@@ -1,8 +1,16 @@
 import type { AnyRecord, Disposable, Json, LogTarget, ReadonlyEventHost } from '@amazon/vinyl-util';
 import { EventHostImpl, ReportableError } from '@amazon/vinyl-util';
-import type { ContentTypesValue } from '../../streaming/ContentTypesValue';
+import type { ObservableValue } from '@amazon/vinyl-observable';
+import type { ContentTypesValue } from '../ContentTypesValue';
 import type { BasicErrorEvent } from '../../event/BasicErrorEvent';
-import type { ContentType } from '../../streaming/MediaQualityMetadata';
+import type { ContentType } from '../MediaQualityMetadata';
+import type { MediaTimeline } from '../MediaTimeline';
+/**
+ * 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;
 export interface SourceBufferRef extends Disposable {
     /**
      * The source buffer.
@@ -23,7 +31,8 @@ export interface MediaSourceControllerEventMap {
      */
     readonly sourceOpen: AnyRecord;
     /**
-     * All source buffers have been created and data may be appended.
+     * All source buffers have been created, the media source duration has been set, and data
+     * may be appended.
      */
     readonly readyToAppend: AnyRecord;
     /**
@@ -36,20 +45,12 @@ export interface ReadonlyMediaSourceController extends ReadonlyEventHost<MediaSo
      * Returns the parent media source ready state.
      */
     readonly readyState: ReadyState;
-    /**
-     * Gets the media source's duration.
-     */
-    readonly duration: number;
     /**
      * True if all source buffers have been created and data may be appended.
      */
     readonly readyToAppend: boolean;
 }
 export interface MediaSourceController extends ReadonlyMediaSourceController {
-    /**
-     * Sets/gets the media source's duration.
-     */
-    duration: number;
     /**
      * Constructs a new SourceBuffer with the given content type and mime type.
      */
@@ -60,9 +61,17 @@ export interface MediaSourceController extends ReadonlyMediaSourceController {
      */
     endOfStream(error?: EndOfStreamError): void;
     /**
-     * Creates an Object URL to use as the source for this stream.
+     * Creates the internal media source.
+     * Returns an Object URL to use as the source for this stream.
+     *
+     * Implementation note:
+     * Only the first
+     */
+    activate(): string;
+    /**
+     * Deactivates the controller, disposing underlying resources.
      */
-    createUrl(): string;
+    deactivate(): void;
 }
 export interface MediaSourceControllerImplDeps {
     /**
@@ -73,25 +82,47 @@ export interface MediaSourceControllerImplDeps {
      * Provides the streams that must be created before appending.
      */
     readonly contentTypesValue: ContentTypesValue;
+    /**
+     * The media timeline used to determine duration.
+     */
+    readonly mediaTimelineTransformed: ObservableValue<Promise<MediaTimeline>>;
 }
 export declare class MediaSourceControllerImpl extends EventHostImpl<MediaSourceControllerEventMap> implements MediaSourceController, LogTarget {
+    private readonly deps;
     get [Symbol.toStringTag](): string;
-    private sourceBufferCount;
-    private readonly mediaSource;
-    private readonly disposer;
+    private readonly sourceBuffers;
+    private mediaSource;
+    private objectUrl;
+    private activateDisposer;
     private contentTypes;
+    private durationSet;
+    /**
+     * Token for the in-flight duration update; used to discard stale results when
+     * the timeline changes or the source closes mid-fetch.
+     */
+    private durationToken;
     constructor(deps: MediaSourceControllerImplDeps);
-    private initializeEvents;
-    get duration(): number;
-    set duration(value: number);
+    get active(): boolean;
+    activate(): string;
+    deactivate(): void;
+    private get sourceBufferCount();
+    private readonly errorHandler;
+    /**
+     * Sets the duration on the media source from the current media timeline.
+     * Live streams use LIVE_DURATION since not all browsers support +Infinity duration.
+     *
+     * MSE throws InvalidStateError if duration is set while any source buffer is updating,
+     * so we wait for all tracked source buffers to be idle first.
+     */
+    private refreshDuration;
     get readyState(): ReadyState;
     createSourceBuffer(contentType: ContentType, mimeType: string): SourceBufferRef;
     /**
-     * Emits a 'readyToAppend' event if all source buffers have been created.
+     * Emits a 'readyToAppend' event if all source buffers have been created and the duration
+     * has been applied to the media source.
      */
     private readonly checkReady;
     endOfStream(error?: EndOfStreamError): void;
-    createUrl(): string;
     get readyToAppend(): boolean;
     dispose(): void;
 }

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

@@ -1,6 +1,6 @@
 import type { Disposable, LogTarget, ReadonlyRanges, Task } from '@amazon/vinyl-util';
 import type { MediaSourceController } from './MediaSourceController';
-import type { ContentType } from '../../streaming/MediaQualityMetadata';
+import type { ContentType } from '../MediaQualityMetadata';
 export declare const APPEND_WINDOW_START_OFFSET = 0.05;
 export declare const APPEND_WINDOW_END_OFFSET = 0.01;
 export declare const READY_TO_APPEND_TIMEOUT = 30;

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

@@ -0,0 +1,23 @@
+/**
+ * Records every codec in the given mimeType as denylisted. Returns true if any
+ * codec was newly added (i.e. was not already denylisted), false if all codecs
+ * were already present. The return value lets callers bound retry loops: a
+ * repeat failure for an already-denylisted codec should not trigger another
+ * fallback attempt.
+ */
+export declare function denylistCodecsFromMimeType(mimeType: string): boolean;
+/**
+ * Returns true when any codec in the given mimeType has been denylisted.
+ */
+export declare function isMimeTypeDenylisted(mimeType: string): boolean;
+/**
+ * Returns the currently denylisted codec strings (lowercased). Primarily for
+ * diagnostics and testing.
+ */
+export declare function getDenylistedCodecs(): readonly string[];
+/**
+ * Clears the runtime codec denylist. Intended for tests and for re-detecting
+ * support (e.g. after an environment change).
+ */
+export declare function clearCodecDenylist(): void;
+//# sourceMappingURL=codecDenylist.d.ts.map

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

@@ -0,0 +1,30 @@
+import type { RestrictableContentType } from './MediaQualityMetadata';
+import type { ContentTypesValue } from './ContentTypesValue';
+import type { ObservableValue } from '@amazon/vinyl-observable';
+export interface AllowedContentTypesValueDeps {
+    /**
+     * The unfiltered content types present in the manifest.
+     */
+    readonly baseContentTypesValue: ContentTypesValue;
+    /**
+     * The player options. The `allowedContentTypes` allow list restricts which
+     * media content types are streamed; `null` means no restriction.
+     */
+    readonly options: ObservableValue<{
+        readonly allowedContentTypes: readonly RestrictableContentType[] | null;
+    }>;
+}
+/**
+ * Wraps a {@link ContentTypesValue} with the `allowedContentTypes` allow list
+ * from the player options. When the allow list is set, only media content
+ * types (`'audio'`, `'video'`) in the list are emitted; other media streams
+ * are ignored. When it is `null`, the underlying content types pass through
+ * unchanged. Text is never restricted by the allow list and always passes
+ * through (captions are governed by caption selection).
+ *
+ * Because the result is derived from the `allowedContentTypes` option via
+ * {@link combineData}, changing the option re-emits a newly filtered set, which
+ * reloads the track using only the allowed content types.
+ */
+export declare function createAllowedContentTypesValue(deps: AllowedContentTypesValueDeps): ContentTypesValue;
+//# sourceMappingURL=createAllowedContentTypesValue.d.ts.map

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

@@ -1,13 +1,16 @@
 import type { ObservableValue } from '@amazon/vinyl-observable';
 import type { Capabilities } from '../client/Capabilities';
 import type { DrmController } from '../drm/DrmController';
-import type { MediaTimeline } from '../streaming/MediaTimeline';
+import type { MediaTimeline } from './MediaTimeline';
+import type { CodecOverrides } from '../util/media/codecOverrides';
 export interface DefaultMediaTimelineTransformerDeps {
     readonly capabilities: Capabilities;
     readonly drmController: DrmController;
     readonly mediaTimeline: ObservableValue<Promise<MediaTimeline>>;
     readonly options: ObservableValue<{
-        readonly preferredAudioLanguage: string | null;
+        readonly preferredAudioLanguage: string | readonly string[] | null;
+        readonly preferDescriptiveAudio?: boolean;
+        readonly codecOverrides?: CodecOverrides;
     }>;
 }
 /**

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

@@ -0,0 +1,35 @@
+import type { MediaQualityMetadata } from './MediaQualityMetadata';
+import type { FilterPredicate } from '@amazon/vinyl-util';
+/**
+ * Thrown if the audio-description filter ever emptied a period's audio. The
+ * filter keeps at least one audio rendition per period by design, so this is a
+ * defensive guard rather than an expected path.
+ */
+export declare function throwNoPlayableAudio(): never;
+/**
+ * Characteristics that mark an audio rendition as an audio description (a.k.a.
+ * described video / DVS) — narration of on-screen action for viewers who cannot
+ * see it. HLS signals this with the `public.accessibility.describes-video`
+ * CHARACTERISTIC; DASH with a `description` Role. Such renditions must not be
+ * chosen as the default audio; they are an accessibility opt-in.
+ */
+export declare const AUDIO_DESCRIPTION_CHARACTERISTICS: readonly string[];
+/**
+ * Whether an audio quality is an audio-description rendition.
+ */
+export declare function isAudioDescription(quality: MediaQualityMetadata): boolean;
+/**
+ * Creates a filter that keeps audio-description renditions out of (or, when
+ * opted in, restricts audio to) the audio selection.
+ *
+ * - `preferDescription: false` (default): drop audio-description renditions
+ *   from each period *when a non-description audio alternative exists*, so the
+ *   main audio is chosen by default instead of the description track. If a
+ *   period has only description audio, it is kept (playback is never stranded).
+ * - `preferDescription: true`: keep only description renditions when the period
+ *   has any; otherwise keep all (again, never strand playback).
+ *
+ * Non-audio qualities are always kept.
+ */
+export declare function createAudioDescriptionFilter(preferDescription: boolean): FilterPredicate<MediaQualityMetadata>;
+//# sourceMappingURL=mediaTimelineAccessibilityFilter.d.ts.map

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

@@ -1,5 +1,5 @@
-import type { MediaTimeline } from '../streaming/MediaTimeline';
-import type { MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
+import type { MediaTimeline } from './MediaTimeline';
+import type { MediaQualityMetadata } from './MediaQualityMetadata';
 import type { FilterPredicate, FilterPredicateAsync, Maybe } from '@amazon/vinyl-util';
 /**
  * Filters qualities in a MediaTimeline using a synchronous predicate.
@@ -14,5 +14,5 @@ export declare function filterTimelineQualitiesAsync(filter: FilterPredicateAsyn
 /**
  * Creates a language filter predicate for use with filterTimelineQualities.
  */
-export { createLanguageFilter } from '../streaming/mediaTimelineLanguageFilter';
+export { createLanguageFilter } from './mediaTimelineLanguageFilter';
 //# sourceMappingURL=mediaTimelineFilter.d.ts.map

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

@@ -1,14 +1,32 @@
-import type { MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
+import type { MediaQualityMetadata } from './MediaQualityMetadata';
 import type { FilterPredicate } from '@amazon/vinyl-util';
 /**
- * Creates a filter predicate that keeps qualities matching the preferred language.
- * The best language match is computed per period (per unique array reference),
- * so periods with different available languages are handled independently.
+ * Resolves the preferred-language option to an ordered list of BCP 47 tags,
+ * most-preferred first.
  *
- * Qualities not matching the content type or without a language tag are always kept.
+ * - a string becomes a single-element list
+ * - an array is used as-is (already ordered)
+ * - `null` falls back to the platform's `navigator.languages` order — `null`
+ *   means "use the platform preference", not "no preference"
+ * - an empty list (empty array, or `navigator.languages` unavailable) means no
+ *   preference: keep all languages
+ */
+export declare function resolvePreferredLanguages(preferred: string | readonly string[] | null): readonly string[];
+/**
+ * Creates a filter predicate that keeps the qualities best matching the
+ * preferred language(s). The preference is an ordered list (see
+ * {@link resolvePreferredLanguages}): earlier entries win, and relatedness
+ * (exact > parent > sibling > child) breaks ties within a single preference.
+ *
+ * The best match is computed per period (per unique array reference), so
+ * periods with different available languages are handled independently. When no
+ * available language relates to any preference, all are kept (playback is never
+ * stranded). Qualities not matching the content type, or without a language
+ * tag, are always kept.
  *
- * @param preferredLanguage BCP 47 language tag, or null to keep all.
+ * @param preferredLanguage BCP 47 tag, ordered list of tags, or null (which
+ *   falls back to `navigator.languages`).
  * @param contentType Only filter qualities matching this content type (e.g. 'audio').
  */
-export declare function createLanguageFilter(preferredLanguage: string | null, contentType: string): FilterPredicate<MediaQualityMetadata> | null;
+export declare function createLanguageFilter(preferredLanguage: string | readonly string[] | null, contentType: string): FilterPredicate<MediaQualityMetadata> | null;
 //# sourceMappingURL=mediaTimelineLanguageFilter.d.ts.map