@amazon/vinyl 1.0.0

package/dist/types/current/playback/PlaybackControllerImpl.js

@@ -0,0 +1,495 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Abort, AbortError, Browser, clamp, closeTo, createDisposer, createTimeRangesReader, DomEventHost, ErrorLevel, ErrorOrigin, EventHostImpl, getUserAgentInfo, hasBrowser, logDebug, logInfo, logWarn, nextEventAsPromise, onAny, ownKeys, TimeoutSlot, toLowerCase, withAbort, withTimeout, } from '@amazon/vinyl-util';
+import { LIVE_DURATION } from './PlaybackController';
+import { PlaybackReadyState, playedReasons, waitedReasons, } from './ReadonlyPlaybackController';
+import { InvalidSeekError } from '../playback/error/InvalidSeekError';
+import { playbackStateLoggingHandler } from '../playback/logging/playbackStateLoggingHandler';
+import { createChangeEventTrigger } from '../event/ChangeEvent';
+import { nextHasMetadata } from '../playback/nextHasMetadata';
+import { ReportableMediaError } from '../playback/error/ReportableMediaError';
+export const defaultPlaybackControllerImplOptions = {
+    loopTimeAffordance: 2,
+    minSeekableBuffer: -1, // Default comes from getMinSeekableBufferDefault()
+    playTimeout: 30,
+    seekTimeout: 30,
+};
+/**
+ * Safari and Edge Legacy cannot reliably seek close to the end of a seekable range.
+ * Firefox can but if the playhead reaches the end of track before the media stream is closed, an 'ended' event
+ * will never fire.
+ */
+export function getMinSeekableBufferDefault() {
+    return !hasBrowser(Browser.CHROMIUM) ? 5 : 2;
+}
+export class PlaybackControllerImpl extends EventHostImpl {
+    loudnessNormalizationController;
+    get [Symbol.toStringTag]() {
+        return 'PlaybackControllerImpl';
+    }
+    _error = null;
+    media;
+    domEvents;
+    disposer = createDisposer();
+    _playing = false;
+    _seeking = false;
+    _waiting = false;
+    // default user volume (0.0 to 1.0 scale)
+    userVolume = 1.0;
+    _pendingPlay = null;
+    playAbort = null;
+    disposeAbort = new Abort();
+    options;
+    constructor(deps, options) {
+        super();
+        this.options = {
+            ...defaultPlaybackControllerImplOptions,
+            minSeekableBuffer: getMinSeekableBufferDefault(),
+            ...options,
+        };
+        this.loudnessNormalizationController =
+            deps.loudnessNormalizationController;
+        logInfo(this, 'constructed', this.options);
+        this.media = deps.media;
+        const { add } = this.disposer;
+        add(() => {
+            this.disposeAbort.abort();
+            this.disposeAbort.dispose();
+        });
+        this.domEvents = add(new DomEventHost(deps.media));
+        // Log media events.
+        add(playbackStateLoggingHandler(this));
+        // Reports media errors
+        this.domEvents.on('error', (_) => {
+            const error = new ReportableMediaError(this.media.error);
+            if (error.level === ErrorLevel.SILENT) {
+                // Not a fatal error, log and ignore
+                logInfo(this, error.message);
+                return;
+            }
+            this._error = error;
+            this.dispatch('error', {
+                target: this,
+                error,
+            });
+        });
+        this.initializeEvents();
+        // Listen for loudness normalization changes
+        add(this.loudnessNormalizationController.on('change', () => {
+            this.refreshVolume();
+        }));
+    }
+    /**
+     * Updates volume with loudness gain, on the mediaElement.
+     * @private
+     */
+    refreshVolume() {
+        const effectiveVolume = this.userVolume * this.loudnessNormalizationController.gain;
+        this.media.volume = Math.min(1.0, effectiveVolume); // valid range (0-1)
+        logDebug(this, 'refreshVolume', {
+            userVolume: this.userVolume,
+            lnGain: this.loudnessNormalizationController.gain,
+            effectiveVolume: this.media.volume,
+        });
+    }
+    /**
+     * Listens to select events on the media element, redispatching as playback state events.
+     * @private
+     */
+    initializeEvents() {
+        this.initializePlainEvents();
+        this.initializeChangeEvents();
+        this.initializeOperationEvents();
+        this.initializeMutedEvent();
+        this.initializeLoopedEvent();
+        this.initializeReadyStateChangeEvent();
+    }
+    /**
+     * Re-dispatches the plain DOM events without extra information.
+     *
+     * @private
+     */
+    initializePlainEvents() {
+        // Re-dispatch html media element events exposed on the playback controller as empty events.
+        for (const key of [
+            'abort',
+            'canPlay',
+            'canPlayThrough',
+            'emptied',
+            'ended',
+            'loadStart',
+            'loadedData',
+            'loadedMetadata',
+            'pause',
+            'play',
+            'playing',
+            'seeking',
+            'waiting',
+            'waitingForKey',
+        ]) {
+            this.domEvents.on(toLowerCase(key), () => this.dispatch(key, {}));
+        }
+        // Keep specific event information for progress events.
+        this.domEvents.on('progress', (e) => {
+            this.dispatch('progress', { loaded: e.loaded, total: e.total });
+        });
+    }
+    /**
+     * Delegates the DOM events with additional information about what the previous and current
+     * values are.
+     * @private
+     */
+    initializeChangeEvents() {
+        const changeEventGetters = {
+            durationChange: () => this.duration,
+            timeUpdate: () => this.currentTime,
+            volumeChange: () => this.volume,
+            rateChange: () => this.playbackRate,
+        };
+        for (const key of ownKeys(changeEventGetters)) {
+            this.domEvents.on(toLowerCase(key), createChangeEventTrigger(changeEventGetters[key], (event) => {
+                this.dispatch(key, event);
+            }));
+        }
+    }
+    /**
+     * Operation events provide an easy way to listen for the terminus of a state.
+     * For example after a 'waiting' event, there are several different events that indicate that
+     * the waiting has finished, and this API provides those events conflated into a single
+     * 'waited' event.
+     * @private
+     */
+    initializeOperationEvents() {
+        // seeking state + seeked event
+        // media element has a seeked event, add operation details and set state.
+        this.operationEvent(this.domEvents, 'seeking', 
+        // A seeked event may not be emitted in certain cases such as changing tracks before the seek can finish.
+        ['seeked', 'emptied'], () => (this._seeking = true), (info) => {
+            this._seeking = false;
+            this.dispatch('seeked', info);
+        });
+        // waiting state + waited event
+        this.operationEvent(this, 'waiting', waitedReasons, () => (this._waiting = true), (info) => {
+            this._waiting = false;
+            this.dispatch('waited', info);
+        });
+        // playing state + played event
+        let startedTime = 0;
+        this.operationEvent(this, 'playing', playedReasons, () => {
+            this._playing = true;
+            startedTime = this.currentTime;
+        }, (info) => {
+            this._playing = false;
+            this.dispatch('played', {
+                ...info,
+                playbackTime: this.currentTime - startedTime,
+            });
+        });
+    }
+    /**
+     * When going into a state from a beginEvent, dispatches endEvent when any of the endEvents
+     * is dispatched.
+     *
+     * This allows consumers of the playback state to listen for the exit of a state without
+     * needing to know every event that ends that state.
+     *
+     * @param host The event host emitting the primary events.
+     * @param beginEvent The event that enters a state.
+     * @param endEvents A list of events that exits the entered state.
+     * @param onBegin Invoked when the operation has begun.
+     * @param onEnd Invoked when the operation has completed.
+     */
+    operationEvent(host, beginEvent, endEvents, onBegin, onEnd) {
+        let startedAt = 0;
+        let started = false;
+        host.on(beginEvent, () => {
+            onBegin();
+            started = true;
+            startedAt = Date.now();
+        });
+        onAny(host, endEvents, (_, event) => {
+            if (started) {
+                started = false;
+                const now = Date.now();
+                onEnd({
+                    started: startedAt,
+                    ended: now,
+                    duration: (now - startedAt) / 1000,
+                    reason: event,
+                });
+            }
+        });
+    }
+    /**
+     * Dispatches a 'mutedChange' event when 'muted' state has changed.
+     *
+     * The DOM element only provides a 'volumeChange' event, which is filtered to watch when
+     * muted has changed.
+     *
+     * @private
+     */
+    initializeMutedEvent() {
+        const { add } = this.disposer;
+        let previousMuted = this.muted;
+        // Dispatches a mutedChange event if the muted property changed since the last check.
+        const maybeDispatchMutedChange = () => {
+            if (this.muted === previousMuted)
+                return;
+            previousMuted = this.muted;
+            this.dispatch('mutedChange', {
+                previous: !this.muted,
+                current: this.muted,
+            });
+        };
+        const mutedTimeoutSlot = add(new TimeoutSlot());
+        this.on('volumeChange', () => {
+            maybeDispatchMutedChange();
+            // The volumechange event may be emitted before the muted property change.
+            // This has been observed on legacy edge and as a rare occurrence for Chrome.
+            mutedTimeoutSlot.set(maybeDispatchMutedChange, 0.2);
+        });
+    }
+    /**
+     * Dispatches a looped event if loop is true and playback wraps back to the start.
+     * Safari emits timeupdate events at duration and then 0 before the seeking event
+     * Other browsers emit the seeking before the timeupdate near zero.
+     * Firefox timeupdate after the loop is near zero, not exactly.
+     *
+     * @private
+     */
+    initializeLoopedEvent() {
+        let lastTime = 0;
+        this.on('timeUpdate', () => {
+            if (this.loop &&
+                !this.paused &&
+                this.currentTime <= this.options.loopTimeAffordance &&
+                lastTime >= this.duration - this.options.loopTimeAffordance) {
+                if (getUserAgentInfo().browserLike?.name === Browser.FIREFOX) {
+                    // Firefox does not emit a 'playing' event after a loop, fabricate one.
+                    logDebug(this, 'fabricating Firefox playing event on loop');
+                    this.dispatch('playing', {});
+                }
+                this.dispatch('looped', {});
+            }
+            lastTime = this.currentTime;
+        });
+    }
+    get buffered() {
+        return createTimeRangesReader(this.media.buffered);
+    }
+    get currentTime() {
+        return this.media.currentTime;
+    }
+    get currentTimePercent() {
+        return this.duration > 0 ? this.currentTime / this.duration : 0;
+    }
+    get defaultPlaybackRate() {
+        return this.media.defaultPlaybackRate;
+    }
+    set defaultPlaybackRate(value) {
+        logDebug(this, `defaultPlaybackRate set to ${value}`);
+        this.media.defaultPlaybackRate = value;
+    }
+    get duration() {
+        if (this.media.duration >= LIVE_DURATION)
+            return Number.POSITIVE_INFINITY;
+        return this.media.duration;
+    }
+    get ended() {
+        return this.media.ended;
+    }
+    get error() {
+        return this._error;
+    }
+    get loop() {
+        return this.media.loop;
+    }
+    set loop(value) {
+        logDebug(this, `loop set to ${value}`);
+        this.media.loop = value;
+    }
+    get muted() {
+        return this.media.muted;
+    }
+    set muted(value) {
+        logDebug(this, `muted set to ${value}`);
+        this.media.muted = value;
+    }
+    get networkState() {
+        return this.media.networkState;
+    }
+    get paused() {
+        return this.media.paused;
+    }
+    get playbackRate() {
+        return this.media.playbackRate;
+    }
+    set playbackRate(value) {
+        logDebug(this, `playbackRate set to ${value}`);
+        this.media.playbackRate = value;
+    }
+    get playing() {
+        return this._playing;
+    }
+    get preservesPitch() {
+        return this.media.preservesPitch;
+    }
+    set preservesPitch(value) {
+        logDebug(this, `preservesPitch set to ${value}`);
+        this.media.preservesPitch = value;
+    }
+    get readyState() {
+        return this.media.readyState;
+    }
+    get seekable() {
+        return createTimeRangesReader(this.media.seekable);
+    }
+    get seeking() {
+        return this._seeking;
+    }
+    get volume() {
+        return this.userVolume;
+    }
+    set volume(value) {
+        logDebug(this, `volume set to ${value}`);
+        this.userVolume = value;
+        this.refreshVolume();
+    }
+    get waiting() {
+        return this._waiting;
+    }
+    pause() {
+        logDebug(this, 'pause');
+        this.playAbort?.abort(new AbortError('The play() request was interrupted by a call to pause().'));
+        this.pendingPlay = null;
+        this.media.pause();
+    }
+    get pendingPlay() {
+        return this._pendingPlay;
+    }
+    set pendingPlay(value) {
+        this._pendingPlay = value;
+        this.dispatch('playIsPendingChange', {
+            previous: value == null,
+            current: value != null,
+        });
+    }
+    play() {
+        logDebug(this, 'play');
+        if (!this.pendingPlay) {
+            const playAbort = new Abort();
+            this.playAbort = playAbort;
+            this.pendingPlay = withAbort((async () => {
+                await nextHasMetadata(this);
+                playAbort.throwIfAborted();
+                await withTimeout(this.media.play(), this.options.playTimeout, 'play() timed out after {time}s', ErrorOrigin.INTERNAL, ErrorLevel.SILENT);
+            })(), playAbort)
+                .catch((reason) => {
+                this.dispatch('playRejected', { reason });
+                throw reason;
+            })
+                .finally(() => {
+                this.pendingPlay = null;
+                this.playAbort = null;
+            });
+        }
+        return this.pendingPlay;
+    }
+    get canPlay() {
+        return this.readyState >= PlaybackReadyState.HAVE_FUTURE_DATA;
+    }
+    get canPlayThrough() {
+        return this.readyState >= PlaybackReadyState.HAVE_ENOUGH_DATA;
+    }
+    get hasMetadata() {
+        return this.readyState >= PlaybackReadyState.HAVE_METADATA;
+    }
+    get playIsPending() {
+        return this.pendingPlay != null;
+    }
+    async seekTo(time, tolerance = 0.5) {
+        logDebug(this, `seekTo: ${time}`);
+        const nextEvent = (type) => {
+            return withAbort(withTimeout(nextEventAsPromise(this, type), this.options.seekTimeout, `seek timed out on ${type} event after {time}s`, ErrorOrigin.INTERNAL, ErrorLevel.WARN), this.disposeAbort);
+        };
+        // Cannot seek until there are seekable ranges.
+        if (!this.hasMetadata) {
+            await nextEvent('loadedMetadata');
+        }
+        const seekable = this.seekable;
+        const range = seekable.getRangeAt(clamp(time, 0, this.duration), tolerance);
+        if (range == null) {
+            logWarn(this, `seekTo: seek outside of seekable ranges, seek ignored`);
+            throw new InvalidSeekError(time, seekable, tolerance);
+        }
+        const clampedTime = Math.max(Math.min(time, range[1] - this.options.minSeekableBuffer), range[0]);
+        // No-op check
+        logDebug(this, `seekTo operation, requested: ${time}, actual: ${clampedTime}`);
+        if (closeTo(clampedTime, this.currentTime, tolerance)) {
+            // Within tolerance of the currentTime, no seek needed.
+            logDebug(this, `seekTo: requested: ${time}, actual: ${clampedTime} no-op`);
+        }
+        else {
+            const seeking = nextEvent('seeking');
+            this.media.currentTime = clampedTime;
+            await seeking;
+            const seekedEvent = await nextEvent('seeked');
+            if (seekedEvent.reason === 'emptied') {
+                // Seek finished due to track unloading. Abort any pending seek.
+                throw new AbortError();
+            }
+        }
+    }
+    /**
+     * Dispatches a readyStateChange event when {@link readyState} changes.
+     * @private
+     */
+    initializeReadyStateChangeEvent() {
+        let previous = this.readyState;
+        onAny(this, [
+            'canPlay',
+            'canPlayThrough',
+            'emptied',
+            'loadedData',
+            'loadedMetadata',
+            'waiting',
+        ], () => {
+            const current = this.readyState;
+            if (previous !== current) {
+                this.dispatch('readyStateChange', {
+                    previous,
+                    current,
+                });
+                previous = this.readyState;
+            }
+        });
+    }
+    reset() {
+        if (this._error == null) {
+            logDebug(this, 'reset no-op');
+            return;
+        }
+        logDebug(this, 'reset');
+        this._error = null;
+        this.dispatch('reset', {});
+    }
+    /**
+     * True if this controller has been disposed.
+     */
+    get disposed() {
+        return this.disposer.disposed;
+    }
+    dispose() {
+        this.disposer.dispose();
+    }
+}
+/**
+ * Returns true if the play rejection reason is a not allowed error. This indicates that play
+ * should be retried within a user interaction stack.
+ * @param reason
+ */
+export function isNotAllowedError(reason) {
+    return reason?.name === 'NotAllowedError';
+}

package/dist/types/current/playback/PlaybackSource.d.ts

@@ -0,0 +1,34 @@
+export type CrossOrigin = 'use-credentials' | 'anonymous' | null;
+export interface PlaybackSource {
+    /**
+     * The CORS setting for the media element.
+     */
+    crossOrigin: CrossOrigin;
+    /**
+     * Contains the absolute URL of the chosen media resource
+     * The value is an empty string if the networkState property is EMPTY.
+     */
+    readonly currentSrc: string;
+    /**
+     * The media element's src.
+     */
+    src: string | null;
+    /**
+     * The media element's srcObject.
+     *
+     * Note: while the specification is that srcObject may be MediaStream | MediaSource | Blob,
+     * only Safari supports this. Most browsers only support MediaStream.
+     */
+    srcObject: MediaStream | null;
+    /**
+     * Resets the media element to its initial state and begins the process of selecting a
+     * media source and loading the media in preparation for playback to begin at the beginning.
+     */
+    load(): void;
+    /**
+     * Determines whether the media element is allowed to have a remote playback UI.
+     * (Note: AirPlay does not support remote playback for Dash)
+     */
+    disableRemotePlayback: boolean;
+}
+//# sourceMappingURL=PlaybackSource.d.ts.map

package/dist/types/current/playback/PlaybackSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlaybackSource.d.ts","sourceRoot":"","sources":["../../../../src/playback/PlaybackSource.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,WAAW,GAAG,iBAAiB,GAAG,WAAW,GAAG,IAAI,CAAA;AAEhE,MAAM,WAAW,cAAc;IAC3B;;OAEG;IACH,WAAW,EAAE,WAAW,CAAA;IAExB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAE3B;;OAEG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAElB;;;;;OAKG;IACH,SAAS,EAAE,WAAW,GAAG,IAAI,CAAA;IAE7B;;;OAGG;IACH,IAAI,IAAI,IAAI,CAAA;IAEZ;;;OAGG;IACH,qBAAqB,EAAE,OAAO,CAAA;CACjC"}

package/dist/types/current/playback/PlaybackSource.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/types/current/playback/PlaybackSourceImpl.d.ts

@@ -0,0 +1,19 @@
+import type { CrossOrigin, PlaybackSource } from './PlaybackSource';
+export interface PlaybackSourceImplDeps {
+    readonly media: HTMLMediaElement;
+}
+export declare class PlaybackSourceImpl implements PlaybackSource {
+    protected readonly media: HTMLMediaElement;
+    constructor(deps: PlaybackSourceImplDeps);
+    get crossOrigin(): CrossOrigin;
+    set crossOrigin(value: CrossOrigin);
+    get currentSrc(): string;
+    load(): void;
+    get src(): string;
+    set src(value: string | null);
+    get srcObject(): MediaStream | null;
+    set srcObject(value: MediaStream | null);
+    get disableRemotePlayback(): boolean;
+    set disableRemotePlayback(value: boolean);
+}
+//# sourceMappingURL=PlaybackSourceImpl.d.ts.map

package/dist/types/current/playback/PlaybackSourceImpl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlaybackSourceImpl.d.ts","sourceRoot":"","sources":["../../../../src/playback/PlaybackSourceImpl.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEnE,MAAM,WAAW,sBAAsB;IACnC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAA;CACnC;AAED,qBAAa,kBAAmB,YAAW,cAAc;IACrD,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAA;gBAE9B,IAAI,EAAE,sBAAsB;IAIxC,IAAI,WAAW,IAAI,WAAW,CAE7B;IAED,IAAI,WAAW,CAAC,KAAK,EAAE,WAAW,EAEjC;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,IAAI,IAAI;IAIZ,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED,IAAI,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAG3B;IAED,IAAI,SAAS,IAAI,WAAW,GAAG,IAAI,CAElC;IAED,IAAI,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,EAEtC;IAED,IAAI,qBAAqB,IAAI,OAAO,CAEnC;IAED,IAAI,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAEvC;CACJ"}

package/dist/types/current/playback/PlaybackSourceImpl.js

@@ -0,0 +1,43 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export class PlaybackSourceImpl {
+    media;
+    constructor(deps) {
+        this.media = deps.media;
+    }
+    get crossOrigin() {
+        return this.media.crossOrigin;
+    }
+    set crossOrigin(value) {
+        this.media.crossOrigin = value;
+    }
+    get currentSrc() {
+        return this.media.currentSrc;
+    }
+    load() {
+        this.media.load();
+    }
+    get src() {
+        return this.media.src;
+    }
+    set src(value) {
+        if (!value)
+            this.media.removeAttribute('src');
+        else
+            this.media.src = value;
+    }
+    get srcObject() {
+        return this.media.srcObject;
+    }
+    set srcObject(value) {
+        this.media.srcObject = value;
+    }
+    get disableRemotePlayback() {
+        return this.media.disableRemotePlayback;
+    }
+    set disableRemotePlayback(value) {
+        this.media.disableRemotePlayback = value;
+    }
+}