@amazon/vinyl 1.2.0 → 2.0.0

package/dist/types/current/streaming/buffering/MediaSourceController.js

@@ -2,7 +2,7 @@
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
-import { closeTo, createDisposer, DomEventHost, ErrorLevel, ErrorOrigin, EventHostImpl, isSilentError, logDebug, ReportableError, toJson, toLowerCase, } from '@amazon/vinyl-util';
+import { closeTo, createDisposer, DomEventHost, ErrorLevel, ErrorOrigin, EventHostImpl, IllegalStateError, isSilentError, logDebug, logWarn, ReportableError, toJson, toLowerCase, } from '@amazon/vinyl-util';
 import { LIVE_DURATION } from '../../playback/PlaybackController';
 import { nextSourceBufferIdle } from '../../util/media/sourceBuffer';
 /**
@@ -17,8 +17,9 @@ export class MediaSourceControllerImpl extends EventHostImpl {
         return 'MediaSourceControllerImpl';
     }
     sourceBuffers = new Set();
-    mediaSource;
-    disposer = createDisposer();
+    mediaSource = null;
+    objectUrl = null;
+    activateDisposer = null;
     contentTypes = null;
     durationSet = false;
     /**
@@ -29,17 +30,68 @@ export class MediaSourceControllerImpl extends EventHostImpl {
     constructor(deps) {
         super();
         this.deps = deps;
-        this.mediaSource = deps.mediaSourceFactory();
-        this.initializeEvents();
-        this.disposer.add(deps.contentTypesValue.onData((value) => {
+    }
+    get active() {
+        return this.activateDisposer != null;
+    }
+    activate() {
+        this.activateDisposer = createDisposer();
+        const add = this.activateDisposer.add;
+        const mediaSource = this.deps.mediaSourceFactory();
+        this.mediaSource = mediaSource;
+        const domEvents = add(new DomEventHost(mediaSource));
+        domEvents.on('sourceopen', () => {
+            this.refreshDuration().catch(this.errorHandler);
+        });
+        domEvents.on('sourceclose', () => {
+            this.durationSet = false;
+            ++this.durationToken;
+        });
+        // Redispatch events from the media source:
+        for (const key of [
+            'sourceClose',
+            'sourceOpen',
+            'sourceEnded',
+        ]) {
+            domEvents.on(toLowerCase(key), () => this.dispatch(key, {}));
+        }
+        add(this.deps.mediaTimelineTransformed.onData(() => {
+            this.refreshDuration().catch(this.errorHandler);
+        }));
+        // React to content type changes (fires immediately with the current
+        // value and again whenever the timeline reveals new content types).
+        add(this.deps.contentTypesValue.onData((contentTypesPromise) => {
+            // The pending content types are unknown until the new promise
+            // resolves, so the controller is not ready to append until then.
             this.contentTypes = null;
-            value
+            contentTypesPromise
                 .then((contentTypes) => {
+                if (this.deps.contentTypesValue.value !==
+                    contentTypesPromise)
+                    return; // Stale
                 this.contentTypes = contentTypes;
                 this.checkReady();
             })
                 .catch(this.errorHandler);
         }));
+        this.objectUrl = URL.createObjectURL(mediaSource);
+        return this.objectUrl;
+    }
+    deactivate() {
+        if (!this.active)
+            return;
+        this.activateDisposer.dispose();
+        this.activateDisposer = null;
+        // Invalidate any in-flight refreshDuration so its continuation returns
+        // at the token check rather than setting duration (and logging) after
+        // deactivation.
+        ++this.durationToken;
+        try {
+            URL.revokeObjectURL(this.objectUrl);
+        }
+        catch (error) {
+            logWarn(this, 'error revoking object url', error);
+        }
     }
     get sourceBufferCount() {
         return this.sourceBuffers.size;
@@ -52,31 +104,6 @@ export class MediaSourceControllerImpl extends EventHostImpl {
             error,
         });
     };
-    /**
-     * Subscription to mediaTimelineTransformed; only attached while the media source is open
-     * so the timeline pipeline isn't forced to evaluate before the source has opened.
-     */
-    timelineSub = null;
-    initializeEvents() {
-        const domEvents = new DomEventHost(this.mediaSource);
-        for (const key of [
-            'sourceClose',
-            'sourceOpen',
-            'sourceEnded',
-        ]) {
-            domEvents.on(toLowerCase(key), () => this.dispatch(key, {}));
-        }
-        this.timelineSub = this.deps.mediaTimelineTransformed.onData(() => {
-            this.refreshDuration().catch(this.errorHandler);
-        });
-        this.on('sourceOpen', () => {
-            this.refreshDuration().catch(this.errorHandler);
-        });
-        this.on('sourceClose', () => {
-            this.durationSet = false;
-            ++this.durationToken;
-        });
-    }
     /**
      * Sets the duration on the media source from the current media timeline.
      * Live streams use LIVE_DURATION since not all browsers support +Infinity duration.
@@ -85,6 +112,7 @@ export class MediaSourceControllerImpl extends EventHostImpl {
      * so we wait for all tracked source buffers to be idle first.
      */
     async refreshDuration() {
+        const mediaSource = this.mediaSource;
         const timelinePromise = this.deps.mediaTimelineTransformed.value;
         const token = ++this.durationToken;
         const timeline = await timelinePromise;
@@ -92,18 +120,21 @@ export class MediaSourceControllerImpl extends EventHostImpl {
         const value = duration === Infinity ? LIVE_DURATION : duration + DURATION_PADDING;
         await Promise.all(Array.from(this.sourceBuffers, nextSourceBufferIdle));
         if (token !== this.durationToken ||
-            this.mediaSource.readyState !== 'open' ||
-            closeTo(this.mediaSource.duration, value, 0.1))
+            mediaSource.readyState !== 'open' ||
+            closeTo(mediaSource.duration, value, 0.1))
             return;
         logDebug(this, `setting duration: ${value}`);
-        this.mediaSource.duration = value;
+        mediaSource.duration = value;
         this.durationSet = true;
         this.checkReady();
     }
     get readyState() {
-        return this.mediaSource.readyState;
+        return this.mediaSource?.readyState ?? 'closed';
     }
     createSourceBuffer(contentType, mimeType) {
+        if (!this.active) {
+            throw new IllegalStateError('cannot create a source buffer when not active');
+        }
         const mediaSource = this.mediaSource;
         logDebug(this, 'create source buffer', contentType, mimeType, mediaSource.readyState, 'sourceBufferCount:', this.sourceBufferCount);
         let sourceBuffer;
@@ -116,16 +147,15 @@ export class MediaSourceControllerImpl extends EventHostImpl {
         sourceBuffer.mode = 'sequence';
         this.sourceBuffers.add(sourceBuffer);
         this.checkReady();
-        const dispose = () => {
-            logDebug(this, 'removing source buffer from media source', mediaSource.readyState);
-            if (mediaSource.readyState !== 'closed') {
-                mediaSource.removeSourceBuffer(sourceBuffer);
-            }
-            this.sourceBuffers.delete(sourceBuffer);
-        };
         return {
             value: sourceBuffer,
-            dispose,
+            dispose: () => {
+                logDebug(this, 'removing source buffer from media source', mediaSource.readyState);
+                if (mediaSource.readyState !== 'closed') {
+                    mediaSource.removeSourceBuffer(sourceBuffer);
+                }
+                this.sourceBuffers.delete(sourceBuffer);
+            },
         };
     }
     /**
@@ -138,10 +168,7 @@ export class MediaSourceControllerImpl extends EventHostImpl {
     };
     endOfStream(error) {
         logDebug(this, 'endOfStream, error:', error);
-        this.mediaSource.endOfStream(error);
-    }
-    createUrl() {
-        return URL.createObjectURL(this.mediaSource);
+        this.mediaSource?.endOfStream(error);
     }
     get readyToAppend() {
         return (this.durationSet &&
@@ -149,9 +176,7 @@ export class MediaSourceControllerImpl extends EventHostImpl {
     }
     dispose() {
         super.dispose();
-        this.timelineSub?.();
-        this.timelineSub = null;
-        this.disposer.dispose();
+        this.deactivate();
     }
 }
 export class MediaSourceError extends ReportableError {

package/dist/types/current/streaming/buffering/SourceBufferController.d.ts.map

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

package/dist/types/current/streaming/buffering/SourceBufferController.js

@@ -17,15 +17,18 @@ export const READY_TO_APPEND_TIMEOUT = 30;
 export class SourceBufferControllerImpl {
     contentType;
     get [Symbol.toStringTag]() {
-        return 'SourceBufferController';
+        return `SourceBuffer_${this.contentType}`;
     }
     sourceBufferRef = null;
     mimeType = null;
     queue = createTaskQueue();
-    logPrefix = createLogPrefix(this);
+    // Assigned in the constructor body: a field initializer runs before the
+    // contentType param-property, so it would capture `undefined`.
+    logPrefix;
     mediaSourceController;
     constructor(deps, contentType) {
         this.contentType = contentType;
+        this.logPrefix = createLogPrefix(`SourceBuffer_${contentType}`);
         logDebug(this, 'constructed, contentType:', contentType);
         this.mediaSourceController = deps.mediaSourceController;
     }

package/dist/types/current/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/current/streaming/buffering/codecDenylist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codecDenylist.d.ts","sourceRoot":"","sources":["../../../../../src/streaming/buffering/codecDenylist.ts"],"names":[],"mappings":"AAyBA;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAWpE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAG9D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,MAAM,EAAE,CAEvD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/types/current/streaming/buffering/codecDenylist.js

@@ -0,0 +1,62 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { extractCodecs } from '../../util/media/codecSupport';
+/**
+ * A runtime denylist of media codecs that failed to decode after a SourceBuffer
+ * append, despite the browser reporting them as supported.
+ *
+ * Some browsers report a codec as supported via `MediaSource.isTypeSupported`
+ * yet fail to decode it (e.g. HEVC on Chromium without a platform decoder),
+ * surfacing as an append/decode error only once media is fed to the
+ * SourceBuffer. When that happens, the failing codec is recorded here so that
+ * quality selection avoids it and playback can fall back to a codec that does
+ * decode.
+ *
+ * This mirrors the runtime {@link getSourceBufferQuota} learning: it is a
+ * process-wide singleton learned from real append failures, with a reset hook
+ * for tests and re-detection. Entries are the individual RFC 6381 codec
+ * strings (e.g. `hvc1.2.20000000.L123.B0`), stored lowercased.
+ */
+const denylistedCodecs = new Set();
+/**
+ * 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 function denylistCodecsFromMimeType(mimeType) {
+    const codecs = extractCodecs(mimeType);
+    let added = false;
+    for (const codec of codecs) {
+        const lower = codec.toLowerCase();
+        if (!denylistedCodecs.has(lower)) {
+            denylistedCodecs.add(lower);
+            added = true;
+        }
+    }
+    return added;
+}
+/**
+ * Returns true when any codec in the given mimeType has been denylisted.
+ */
+export function isMimeTypeDenylisted(mimeType) {
+    const codecs = extractCodecs(mimeType);
+    return codecs.some((c) => denylistedCodecs.has(c.toLowerCase()));
+}
+/**
+ * Returns the currently denylisted codec strings (lowercased). Primarily for
+ * diagnostics and testing.
+ */
+export function getDenylistedCodecs() {
+    return [...denylistedCodecs];
+}
+/**
+ * Clears the runtime codec denylist. Intended for tests and for re-detecting
+ * support (e.g. after an environment change).
+ */
+export function clearCodecDenylist() {
+    denylistedCodecs.clear();
+}

package/dist/types/current/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/current/streaming/createAllowedContentTypesValue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createAllowedContentTypesValue.d.ts","sourceRoot":"","sources":["../../../../src/streaming/createAllowedContentTypesValue.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAER,uBAAuB,EAC1B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAI/D,MAAM,WAAW,4BAA4B;IACzC;;OAEG;IACH,QAAQ,CAAC,qBAAqB,EAAE,iBAAiB,CAAA;IAEjD;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;QAC9B,QAAQ,CAAC,mBAAmB,EAAE,SAAS,uBAAuB,EAAE,GAAG,IAAI,CAAA;KAC1E,CAAC,CAAA;CACL;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAC1C,IAAI,EAAE,4BAA4B,GACnC,iBAAiB,CAOnB"}

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

@@ -0,0 +1,43 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { combineData } from '@amazon/vinyl-observable';
+/**
+ * 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 function createAllowedContentTypesValue(deps) {
+    return combineData({
+        contentTypes: deps.baseContentTypesValue,
+        allowedContentTypes: deps.options.pick('allowedContentTypes'),
+    }).map(async ({ contentTypes, allowedContentTypes }) => {
+        return filterContentTypes(await contentTypes, allowedContentTypes);
+    });
+}
+/**
+ * Returns the subset of `contentTypes` permitted by the `allowedContentTypes`
+ * allow list. A `null` allow list permits everything. Text always passes
+ * through regardless of the allow list.
+ */
+function filterContentTypes(contentTypes, allowedContentTypes) {
+    if (allowedContentTypes == null)
+        return contentTypes;
+    const allowed = new Set(allowedContentTypes);
+    const filtered = new Set();
+    for (const contentType of contentTypes) {
+        // Text is not subject to the allow list; keep it regardless.
+        if (contentType === 'text' || allowed.has(contentType)) {
+            filtered.add(contentType);
+        }
+    }
+    return filtered;
+}

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

@@ -2,12 +2,15 @@ import type { ObservableValue } from '@amazon/vinyl-observable';
 import type { Capabilities } from '../client/Capabilities';
 import type { DrmController } from '../drm/DrmController';
 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/current/streaming/createDefaultMediaTimelineTransformer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createDefaultMediaTimelineTransformer.d.ts","sourceRoot":"","sources":["../../../../src/streaming/createDefaultMediaTimelineTransformer.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAE/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAoBpD,MAAM,WAAW,mCAAmC;IAChD,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAA;IACnC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAA;IACrC,QAAQ,CAAC,aAAa,EAAE,eAAe,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAA;IAC/D,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;QAC9B,QAAQ,CAAC,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAA;KACjD,CAAC,CAAA;CACL;AAED;;;GAGG;AACH,wBAAgB,qCAAqC,CACjD,IAAI,EAAE,mCAAmC,GAC1C,eAAe,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAqCzC"}
+{"version":3,"file":"createDefaultMediaTimelineTransformer.d.ts","sourceRoot":"","sources":["../../../../src/streaming/createDefaultMediaTimelineTransformer.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAE/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAuBpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAGlE,MAAM,WAAW,mCAAmC;IAChD,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAA;IACnC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAA;IACrC,QAAQ,CAAC,aAAa,EAAE,eAAe,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAA;IAC/D,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;QAC9B,QAAQ,CAAC,sBAAsB,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,IAAI,CAAA;QAClE,QAAQ,CAAC,sBAAsB,CAAC,EAAE,OAAO,CAAA;QACzC,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAA;KAC3C,CAAC,CAAA;CACL;AAED;;;GAGG;AACH,wBAAgB,qCAAqC,CACjD,IAAI,EAAE,mCAAmC,GAC1C,eAAe,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CA6EzC"}

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

@@ -5,25 +5,56 @@
 import { combineData } from '@amazon/vinyl-observable';
 import { filterTimelineQualities, filterTimelineQualitiesAsync, } from './mediaTimelineFilter';
 import { createLanguageFilter } from './mediaTimelineLanguageFilter';
+import { createAudioDescriptionFilter, throwNoPlayableAudio, } from './mediaTimelineAccessibilityFilter';
 import { canPlayMimeType, throwMimeTypesUnsupported, } from '../track/filters/resourceTypeFilter';
 import { canPlayKeySystem, throwKeySystemsUnsupported, } from '../track/filters/keySystemFilter';
 import { supportsAudioSamplingRate, throwSamplingRatesUnsupported, } from '../track/filters/sampleRateFilter';
 import { throwLanguagesUnsupported } from '../track/filters/languageFilter';
+import { resolveCodecOverride } from '../util/media/codecOverrides';
 /**
  * The default media timeline transformer filters out unplayable qualities
  * and applies language preferences. Shared by Dash and HLS.
  */
 export function createDefaultMediaTimelineTransformer(deps) {
+    /**
+     * Applies explicit codec overrides on top of browser support detection.
+     * An `'allow'`/`'deny'` override for a quality's codec supersedes
+     * {@link canPlayMimeType}; otherwise the browser's support check is used.
+     */
+    function canPlayWithOverrides(quality, codecOverrides) {
+        if (quality.mimeType) {
+            const override = resolveCodecOverride(quality.mimeType, codecOverrides);
+            if (override === 'allow')
+                return true;
+            if (override === 'deny')
+                return false;
+        }
+        return canPlayMimeType(deps, quality);
+    }
     async function transformTimeline(timeline) {
-        let t = filterTimelineQualities((quality) => canPlayMimeType(deps, quality), throwMimeTypesUnsupported, timeline);
+        const codecOverrides = deps.options.value.codecOverrides;
+        let t = filterTimelineQualities((quality) => canPlayWithOverrides(quality, codecOverrides), throwMimeTypesUnsupported, timeline);
         t = await filterTimelineQualitiesAsync((quality) => canPlayKeySystem(deps, quality), throwKeySystemsUnsupported, t);
         t = filterTimelineQualities((quality, index, array) => supportsAudioSamplingRate(deps, quality, index, array), throwSamplingRatesUnsupported, t);
+        // Resolve audio-description eligibility BEFORE the language filter.
+        // Description renditions are an accessibility opt-in, not general audio,
+        // so they must be gated out (unless opted in via preferDescriptiveAudio)
+        // before language selection runs. Otherwise a description rendition
+        // whose language tag happens to score higher than the main audio's
+        // (e.g. a described 'en' beating a main 'en-US') could win language
+        // selection and evict the main audio, stranding the listener on
+        // described audio they never opted into. With this gate first, the
+        // language filter only ever picks among eligible (main, or opted-in
+        // description) renditions.
+        t = filterTimelineQualities(createAudioDescriptionFilter(deps.options.value.preferDescriptiveAudio ?? false), throwNoPlayableAudio, t);
         t = filterTimelineQualities(createLanguageFilter(deps.options.value.preferredAudioLanguage, 'audio'), throwLanguagesUnsupported, t);
         return t;
     }
     return combineData({
         timeline: deps.mediaTimeline,
         preferredAudioLanguage: deps.options.pick('preferredAudioLanguage'),
+        preferDescriptiveAudio: deps.options.pick('preferDescriptiveAudio'),
+        codecOverrides: deps.options.pick('codecOverrides'),
     }).map(async ({ timeline }) => {
         return transformTimeline(await timeline);
     });

package/dist/types/current/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/current/streaming/mediaTimelineAccessibilityFilter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediaTimelineAccessibilityFilter.d.ts","sourceRoot":"","sources":["../../../../src/streaming/mediaTimelineAccessibilityFilter.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAGzD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,KAAK,CAE5C;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,SAAS,MAAM,EAG9D,CAAA;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAIzE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CACxC,iBAAiB,EAAE,OAAO,GAC3B,eAAe,CAAC,oBAAoB,CAAC,CA8BvC"}

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

@@ -0,0 +1,75 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { MediaUnsupportedError, memoize } 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 function throwNoPlayableAudio() {
+    throw new MediaUnsupportedError('No playable audio rendition', 'audio');
+}
+/**
+ * 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 const AUDIO_DESCRIPTION_CHARACTERISTICS = [
+    'public.accessibility.describes-video',
+    'description',
+];
+/**
+ * Whether an audio quality is an audio-description rendition.
+ */
+export function isAudioDescription(quality) {
+    return quality.characteristics.some((c) => AUDIO_DESCRIPTION_CHARACTERISTICS.includes(c));
+}
+/**
+ * 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 function createAudioDescriptionFilter(preferDescription) {
+    // Per period (per unique array reference): does it have description audio,
+    // and does it have non-description ("main") audio?
+    const periodFlags = memoize((array) => {
+        let hasDescription = false;
+        let hasMain = false;
+        for (const quality of Array.from(array)) {
+            if (quality.contentType !== 'audio')
+                continue;
+            if (isAudioDescription(quality))
+                hasDescription = true;
+            else
+                hasMain = true;
+        }
+        return { hasDescription, hasMain };
+    }, (array) => array, 1);
+    return (quality, _index, array) => {
+        if (quality.contentType !== 'audio')
+            return true;
+        const { hasDescription, hasMain } = periodFlags(array);
+        if (preferDescription) {
+            // Nothing to prefer; keep all rather than strand playback.
+            if (!hasDescription)
+                return true;
+            return isAudioDescription(quality);
+        }
+        // No main alternative; keep all rather than strand playback.
+        if (!hasMain)
+            return true;
+        return !isAudioDescription(quality);
+    };
+}

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

@@ -1,14 +1,32 @@
 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