@amazon/vinyl 1.0.0

package/dist/types/current/streaming/abr/QualitySelectorImpl.js

@@ -0,0 +1,147 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { clamp, createDisposer, createLogPrefix, getNetworkMetrics, lerp, } from '@amazon/vinyl-util';
+import { boolean, enumOf, number, object, } from '@amazon/vinyl-validation';
+export var AbrStrategy;
+(function (AbrStrategy) {
+    /**
+     * Selects lowest quality, regardless of bandwidth conditions.
+     */
+    AbrStrategy["LOWEST"] = "lowest";
+    /**
+     * Selects highest quality, regardless of bandwidth conditions.
+     */
+    AbrStrategy["HIGHEST"] = "highest";
+    /**
+     * Selects the best quality based on user bandwidth data.
+     * Uses an EWMA estimation.
+     */
+    AbrStrategy["BEST"] = "best";
+    /**
+     * Selects the initial quality based on bandwidth information, but will not change qualities mid-stream.
+     *
+     * May choose new quality after streaming clear, such as after a seek.
+     */
+    AbrStrategy["FIXED"] = "fixed";
+})(AbrStrategy || (AbrStrategy = {}));
+export const qualitySelectorImplOptionsValidator = object({
+    highBufferThreshold: number().optional(),
+    lowBufferThreshold: number().optional(),
+    strategy: enumOf(AbrStrategy).optional(),
+    bandwidthMultiplierLow: number().optional(),
+    bandwidthMultiplierHigh: number().optional(),
+    restrictDecoderChangeOnAudioAbrUp: boolean().optional(),
+});
+export const defaultQualitySelectorImplOptions = {
+    highBufferThreshold: 15,
+    lowBufferThreshold: 4,
+    strategy: AbrStrategy.BEST,
+    bandwidthMultiplierLow: 0.4,
+    bandwidthMultiplierHigh: 0.9,
+    restrictDecoderChangeOnAudioAbrUp: false,
+};
+export class QualitySelectorImpl {
+    get [Symbol.toStringTag]() {
+        return 'QualitySelectorImpl';
+    }
+    logPrefix = createLogPrefix(this);
+    _options = defaultQualitySelectorImplOptions;
+    disposer = createDisposer();
+    constructor(deps) {
+        const { add } = this.disposer;
+        add(deps.options.onData((v) => {
+            this._options = { ...defaultQualitySelectorImplOptions, ...v };
+        }));
+    }
+    get options() {
+        return this._options;
+    }
+    selectQuality(qualities, prefetchState) {
+        const { strategy, highBufferThreshold, lowBufferThreshold, bandwidthMultiplierLow, bandwidthMultiplierHigh, restrictDecoderChangeOnAudioAbrUp, } = this.options;
+        const previousQuality = prefetchState.previousQuality;
+        // previousIndex will be -1 if the previously playing quality is not within the current qualities list.
+        const previousIndex = previousQuality == null
+            ? -1
+            : qualities.findIndex((quality) => quality.qualityId === previousQuality.qualityId);
+        if (strategy === AbrStrategy.LOWEST) {
+            return qualities.length - 1;
+        }
+        else if (strategy === AbrStrategy.HIGHEST) {
+            return 0;
+        }
+        else if (strategy === AbrStrategy.FIXED) {
+            if (previousIndex >= 0)
+                return previousIndex;
+        }
+        const fetchedTime = prefetchState.fetchedTime;
+        const bandwidthEstimate = getNetworkMetrics().estimatedDownlinkBandwidth;
+        // Interpolate the bandwidth multiplier between the low and high values based on how much
+        // buffer is currently fetched. An empty buffer uses bandwidthMultiplierLow (conservative)
+        // to reduce rebuffer risk; a buffer at or above highBufferThreshold uses
+        // bandwidthMultiplierHigh (optimistic) since buffered data can absorb short-term dips.
+        // The interpolation is linear with respect to the buffer ratio.
+        // If the track is not active (i.e. prefetch), always use the high multiplier.
+        const bufferRatio = highBufferThreshold > 0
+            ? clamp(fetchedTime / highBufferThreshold, 0, 1)
+            : 1;
+        const bandwidthMultiplier = prefetchState.active
+            ? lerp(bandwidthMultiplierLow, bandwidthMultiplierHigh, bufferRatio)
+            : bandwidthMultiplierHigh;
+        // Choose bandwidth based on pessimistic network information.
+        // If the track is active, take the lesser of the latest recorded bandwidth stat and the weighted
+        // average to allow for fast ABR-down in variable conditions.
+        const bandwidth = (prefetchState.active
+            ? Math.min(bandwidthEstimate.ewmaLow, bandwidthEstimate.latest)
+            : bandwidthEstimate.ewmaLow) * bandwidthMultiplier;
+        let restrictDecoderId = null;
+        let restrictSwitchingGroupIds = null;
+        if (previousQuality && previousIndex >= 0) {
+            // Restrict to qualities whose groupId is in the previous quality's switching group.
+            // Null switchingGroupIds means no switching constraint.
+            if (previousQuality.switchingGroupIds != null) {
+                restrictSwitchingGroupIds = previousQuality.switchingGroupIds;
+            }
+            // Intra-track ABR rules
+            if (previousQuality.bandwidthTotal &&
+                bandwidth < previousQuality.bandwidthTotal) {
+                // Measured bandwidth lower than current streaming bandwidth.
+                if (fetchedTime >= highBufferThreshold) {
+                    // Do not ABR-down inter-track when there is ample fetched data.
+                    return previousIndex;
+                }
+            }
+            else {
+                if (fetchedTime < lowBufferThreshold) {
+                    // Do not ABR-up inter-track when there is not enough fetched data.
+                    return previousIndex;
+                }
+                // Measured bandwidth is at least current streaming bandwidth.
+                // Restrict to the previous decoder id for audio to avoid an audible artifact
+                // from decoder re-initialization.
+                if (restrictDecoderChangeOnAudioAbrUp &&
+                    previousQuality.contentType === 'audio') {
+                    restrictDecoderId = previousQuality.decoderId;
+                }
+            }
+        }
+        const index = qualities.findIndex((quality) => {
+            if (restrictSwitchingGroupIds != null &&
+                !restrictSwitchingGroupIds.includes(quality.groupId))
+                return false;
+            if (restrictDecoderId != null &&
+                quality.decoderId !== restrictDecoderId)
+                return false;
+            return (quality.bandwidthTotal == null ||
+                quality.bandwidthTotal <= bandwidth);
+        });
+        return index === -1 ? qualities.length - 1 : index;
+    }
+    get disposed() {
+        return this.disposer.disposed;
+    }
+    dispose() {
+        this.disposer.dispose();
+    }
+}

package/dist/types/current/streaming/buffering/BufferingController.d.ts

@@ -0,0 +1,253 @@
+import { type AnyRecord, type Clearable, type Disposable, EventHostImpl, type ReadonlyEventHost } from '@amazon/vinyl-util';
+import type { ReadonlyPlaybackController } from '../../playback/ReadonlyPlaybackController';
+import type { SourceBufferController } from './SourceBufferController';
+import type { ReadonlySegmentController } from '../../streaming/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;
+/**
+ * The interval to throttle polling the buffer.
+ * Reset after a seek.
+ * @private
+ */
+export declare const POLL_BUFFER_THROTTLE = 0.1;
+/**
+ * If segments are too large to append, reduces the max append size.
+ */
+export declare const QUOTA_REACHED_SCALE = 0.8;
+/**
+ * If quota exceeded errors are hit, the max append size will not be reduced below this value and the buffering
+ * controller will be set to an erred state.
+ */
+export declare const MIN_APPEND_SIZE = 524288;
+/**
+ * If the content type does not match a config setting.
+ */
+export declare const DEFAULT_MAX_APPEND_SIZE = 10485760;
+export interface BufferingControllerEventMap {
+    /**
+     * Dispatched when an error of severity warning or fatal occurred while buffering.
+     */
+    readonly error: BasicErrorEvent;
+    /**
+     * Dispatched when the currently playing media encoding has changed.
+     */
+    readonly playbackQualityChange: ChangeEvent<MediaQualityMetadata | null>;
+    /**
+     * Dispatched when the currently buffering quality changes.
+     * This is dispatched before the segment is appended.
+     */
+    readonly bufferingQualityChange: ChangeEvent<MediaQualityMetadata | null>;
+    /**
+     * The last segment has finished appending.
+     */
+    readonly bufferingEnded: AnyRecord;
+}
+export interface BufferingController extends ReadonlyEventHost<BufferingControllerEventMap>, Clearable, Disposable {
+    /**
+     * The last error emitted.
+     * Buffering will halt if this controller is in an error state.
+     * Deactivating this controller will reset the error state.
+     */
+    readonly error: Error | null;
+    /**
+     * The currently buffering media quality.
+     * This is set immediately before a segment of a new quality is appended.
+     *
+     * Listen to {@link BufferingControllerEventMap.bufferingQualityChange} events for changes.
+     */
+    readonly bufferingQuality: MediaQualityMetadata | null;
+    /**
+     * The currently playing media quality.
+     *
+     * Listen to {@link BufferingControllerEventMap.playbackQualityChange} events for changes.
+     */
+    readonly playbackQuality: MediaQualityMetadata | null;
+    /**
+     * True if this buffering controller is active.
+     */
+    readonly active: boolean;
+    /**
+     * True if the stream has buffered the last segment.
+     */
+    readonly bufferingEnded: boolean;
+    /**
+     * Begins buffering.
+     */
+    activate(): void;
+    /**
+     * Stops buffering.
+     */
+    deactivate(): void;
+    /**
+     * If this controller is in an error state, resets and tries again.
+     */
+    reset(): void;
+}
+/**
+ * Clears the current estimated source buffer quota.
+ * @private
+ */
+export declare function clearSourceBufferQuota(): void;
+/**
+ * Returns the measured source buffer quota for the given content type.
+ * Will return null if the quota was never reached.
+ *
+ * @param contentType
+ */
+export declare function getSourceBufferQuota(contentType: ContentType): number | null;
+export interface BufferingControllerImplDeps {
+    readonly mediaSourceController: MediaSourceController;
+    readonly segmentController: ReadonlySegmentController;
+    readonly playbackController: ReadonlyPlaybackController;
+    readonly sourceBufferControllerFactory: () => SourceBufferController;
+}
+export interface BufferingControllerImplOptions {
+    /**
+     * When the buffer falls below this time threshold, the next segment will be requested from the
+     * segment controller and appended.
+     * Default: 4s
+     */
+    readonly minBuffer: number;
+    /**
+     * The maximum number of bytes to append at a time per content type.
+     * Default: { audio: 1MiB, video: 15MiB }
+     */
+    readonly maxAppendSize: Partial<Record<ContentType, number>>;
+}
+/**
+ * The buffering controller is responsible for requesting and appending segments to the source
+ * buffer controller.
+ */
+export declare class BufferingControllerImpl extends EventHostImpl<BufferingControllerEventMap> implements BufferingController, Disposable {
+    readonly deps: BufferingControllerImplDeps;
+    readonly contentType: ContentType;
+    get [Symbol.toStringTag](): string;
+    readonly options: BufferingControllerImplOptions;
+    private readonly mediaSourceController;
+    private readonly playbackController;
+    private readonly segmentController;
+    private sourceBufferController;
+    private decoderId;
+    /**
+     * The currently buffered segments.
+     */
+    private buffered;
+    private appendOffset;
+    /**
+     * The currently buffering quality.
+     */
+    private _bufferingQuality;
+    /**
+     * If true and in a bufferingEnded state, the segment provider will be queried again.
+     * This will be set to true after the segment controller reports a change event, indicating that there may be new
+     * segments to append.
+     */
+    private reopen;
+    private _error;
+    private _bufferingEnded;
+    private readonly queue;
+    private disposer;
+    private _active;
+    private activateDisposer;
+    private readonly segmentAbort;
+    constructor(deps: BufferingControllerImplDeps, contentType: ContentType, options?: Partial<BufferingControllerImplOptions>);
+    get active(): boolean;
+    /**
+     * Activates the buffering controller, watching the playhead and segment controller.
+     */
+    activate(): void;
+    deactivate(): void;
+    reset(): void;
+    /**
+     * Returns true if there are active operations.
+     */
+    get busy(): boolean;
+    /**
+     * Enqueues a duration update.
+     */
+    private refreshDuration;
+    /**
+     * Resets the throttle and polls the buffer on the next frame.
+     */
+    private pollBufferImmediate;
+    /**
+     * If buffered time reaches below minBuffer, request the segment for the next unbuffered
+     * time and append.
+     * @private
+     */
+    private readonly pollBuffer;
+    private shouldAppend;
+    /**
+     * The buffered segment at the playhead.
+     */
+    private get head();
+    /**
+     * The most recently buffered segment.
+     */
+    private get tail();
+    protected appendNext(): Promise<void>;
+    private abortCurrentSegment;
+    /**
+     * Checks if the playhead has progressed past the current head segment and shifts the linked list.
+     * Updates the playback quality if changed.
+     */
+    private refreshHead;
+    private getMaxAppendSize;
+    private _playbackQuality;
+    get playbackQuality(): MediaQualityMetadata | null;
+    /**
+     * Returns the quality currently buffering.
+     */
+    get bufferingQuality(): MediaQualityMetadata | null;
+    private set bufferingQuality(value);
+    /**
+     * Sets the current playback quality and emits a playbackQualityChange event.
+     * No-ops if quality id has not changed.
+     */
+    private set playbackQuality(value);
+    /**
+     * The last error emitted.
+     * Buffering will halt if this controller is in an error state.
+     * Deactivating this controller will reset the error state.
+     */
+    get error(): Error | null;
+    /**
+     * Returns true if the media source's ready state is 'open'
+     */
+    private get mediaSourceOpen();
+    /**
+     * Returns true if the media source's ready state is 'closed'
+     */
+    private get mediaSourceClosed();
+    /**
+     * Returns true if the last segment has been appended.
+     */
+    get bufferingEnded(): boolean;
+    private readonly handleError;
+    /**
+     * Returns the amount of time buffered at the current media position.
+     * @private
+     */
+    getBufferedTime(): number;
+    /**
+     * Cancels any currently buffering fragments and clears the source buffer.
+     */
+    clear(): void;
+    private endBuffering;
+    private resetBufferedState;
+    /**
+     * Finish any partial appends and clear the source buffer.
+     */
+    private finishAndClearBuffers;
+    get disposed(): boolean;
+    dispose(): void;
+}
+//# sourceMappingURL=BufferingController.d.ts.map

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

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