@amazon/vinyl 1.2.0 → 1.2.1

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

@@ -0,0 +1,104 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { data } from '@amazon/vinyl-observable';
+import { createAbortSlot, createDisposer, EventHostImpl, logDebug, } from '@amazon/vinyl-util';
+export class ManifestControllerImpl {
+    deps;
+    get [Symbol.toStringTag]() {
+        return 'ManifestControllerImpl';
+    }
+    get logPrefix() {
+        return 'ManifestControllerImpl';
+    }
+    _data;
+    _error = null;
+    abortSlot = createAbortSlot();
+    disposer = createDisposer();
+    events = new EventHostImpl();
+    manifestSpanArmed = true;
+    constructor(deps) {
+        this.deps = deps;
+        // Kick off the initial manifest request. requestManifest() attaches its
+        // own rejection handler, so the stored promise never rejects unhandled.
+        this._data = data(this.requestManifest());
+    }
+    on(type, handler, options) {
+        return this.events.on(type, handler, options);
+    }
+    hasAnyListeners() {
+        return this.events.hasAnyListeners();
+    }
+    hasListeners(type) {
+        return this.events.hasListeners(type);
+    }
+    __eventMapType = this.events.__eventMapType;
+    /**
+     * The most recent error from the manifest provider, or null.
+     */
+    get error() {
+        return this._error;
+    }
+    refresh() {
+        logDebug(this, 'refresh');
+        this._data.value = this.requestManifest();
+    }
+    requestManifest() {
+        this.abortSlot.abort();
+        this._error = null;
+        const promise = this.deps.manifestProvider(this.abortSlot.value);
+        this.measureLoadSpan(promise);
+        promise.catch((error) => {
+            this._error = error;
+        });
+        return promise;
+    }
+    /**
+     * Measures the initial manifest fetch as a load span, re-arming on failure
+     * so a recovered load is still measured.
+     */
+    measureLoadSpan(promise) {
+        if (!this.manifestSpanArmed)
+            return;
+        this.manifestSpanArmed = false;
+        const startTime = Date.now();
+        promise.then(() => this.events.dispatch('loadSpanMeasured', {
+            kind: 'manifest',
+            startTime,
+            endTime: Date.now(),
+        }), () => (this.manifestSpanArmed = true));
+    }
+    reset() {
+        logDebug(this, 'reset');
+        if (this._error) {
+            this.refresh();
+        }
+    }
+    get value() {
+        return this._data.value;
+    }
+    get changeId() {
+        return this._data.changeId;
+    }
+    getValue() {
+        return this._data.getValue();
+    }
+    onData(callback) {
+        return this._data.onData(callback);
+    }
+    map(fn) {
+        return this._data.map(fn);
+    }
+    pick(key) {
+        return this._data.pick(key);
+    }
+    get disposed() {
+        return this.disposer.disposed;
+    }
+    dispose() {
+        this.abortSlot.abort();
+        this.disposer.dispose();
+        this.events.dispose();
+    }
+}

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/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/text/HtmlTextTrackRenderer.d.ts

@@ -0,0 +1,60 @@
+import type { Disposable } from '@amazon/vinyl-util';
+import type { TextTrackRenderer } from './TextTrackRenderer';
+/**
+ * The subset of a `VTTCue`'s positioning properties {@link computeCueLayout}
+ * reads. A native `VTTCue` satisfies this; a plain `TextTrackCue` (platforms
+ * without `VTTCue`) leaves them undefined and falls back to defaults.
+ */
+export interface CueGeometry {
+    readonly align?: string | null;
+    readonly line?: number | AutoKeyword;
+    readonly lineAlign?: LineAlignSetting;
+    readonly position?: number | AutoKeyword;
+    readonly positionAlign?: PositionAlignSetting;
+    readonly size?: number;
+    readonly snapToLines?: boolean;
+    readonly vertical?: DirectionSetting;
+}
+/** Inline styles (camelCase CSS properties) to apply to a rendered cue box. */
+export type CueLayout = Record<string, string>;
+/**
+ * Maps a cue's WebVTT positioning settings to inline CSS. Pure and DOM-free so
+ * the (branchy) placement logic is unit-testable in isolation.
+ *
+ * A cue with neither `line` nor `position` set flows in the renderer's
+ * bottom-anchored, centered container (the common subtitle case). Otherwise it
+ * is absolutely positioned: `size` → width, `position`/`positionAlign` →
+ * horizontal, `line`/`lineAlign`/`snapToLines` → vertical (percentage lines, or
+ * whole rows counted from the bottom for negative integers), `align` → text
+ * alignment, `vertical` → writing mode.
+ */
+export declare function computeCueLayout(cue: CueGeometry): CueLayout;
+/**
+ * Renders a cue's text payload as safe HTML. Text is escaped (so it can't
+ * inject nodes); newlines become `<br>`; and WebVTT cue tags are converted:
+ * `<c.foo>`→`<span class="foo">`, `<i>/<b>/<u>/<ruby>/<rt>` pass through,
+ * `<v Name>`→`<span title>`, `<lang xx>`→`<span lang>`, timestamp tags are
+ * dropped. Class-based styling requires matching app CSS (STYLE blocks in the
+ * VTT are not applied).
+ */
+export declare function renderCueText(text: string): string;
+/**
+ * A {@link TextTrackRenderer} that paints cues as HTML into {@link element}.
+ * Mount `element` over the video; it stacks cues at the bottom, centered, and
+ * positions any cue that carries explicit WebVTT settings. The DOM track is
+ * expected to be `'hidden'` so only this renderer paints.
+ */
+export declare class HtmlTextTrackRenderer implements TextTrackRenderer, Disposable {
+    /** The overlay container to mount over the video. */
+    readonly element: HTMLElement;
+    private track;
+    private readonly styleElement;
+    private readonly onCueChange;
+    constructor();
+    setTextTrack(track: TextTrack | null): void;
+    setStyles(styles: readonly string[]): void;
+    dispose(): void;
+    private renderActiveCues;
+    private createCueBox;
+}
+//# sourceMappingURL=HtmlTextTrackRenderer.d.ts.map

package/dist/types/current/text/HtmlTextTrackRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HtmlTextTrackRenderer.d.ts","sourceRoot":"","sources":["../../../../src/text/HtmlTextTrackRenderer.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D;;;;GAIG;AACH,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,CAAA;IACpC,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAA;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,CAAA;IACxC,QAAQ,CAAC,aAAa,CAAC,EAAE,oBAAoB,CAAA;IAC7C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAA;CACvC;AAED,+EAA+E;AAC/E,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAK9C;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,WAAW,GAAG,SAAS,CAmD5D;AAmDD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoBlD;AAeD;;;;;GAKG;AACH,qBAAa,qBAAsB,YAAW,iBAAiB,EAAE,UAAU;IACvE,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;IAE7B,OAAO,CAAC,KAAK,CAAyB;IAGtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkB;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgC;;IAgB5D,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,GAAG,IAAI;IAe3C,SAAS,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAI1C,OAAO,IAAI,IAAI;IAIf,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,YAAY;CAOvB"}