@amazon/vinyl 1.0.0

package/dist/types/ts4.7/streaming/SegmentDataSlot.d.ts

@@ -0,0 +1,58 @@
+import type { Disposable, Maybe } from '@amazon/vinyl-util';
+import { type ReadonlyAbort } from '@amazon/vinyl-util';
+export declare enum SegmentStatus {
+    /**
+     * This segment has not been requested.
+     */
+    INACTIVE = "inactive",
+    /**
+     * The segment has been requested but not yet completed.
+     */
+    PENDING = "pending",
+    /**
+     * The segment has finished requesting.
+     */
+    RESOLVED = "resolved",
+    /**
+     * The segment failed to load.
+     */
+    ERRED = "erred"
+}
+/**
+ * A function that returns a promise to segment data.
+ */
+export type SegmentDataProvider = (abort?: Maybe<ReadonlyAbort>) => Promise<ArrayBuffer>;
+/**
+ * A SegmentSlot is a holder for a segment buffer. It may be requested, cleared, and its status observed.
+ */
+export declare class SegmentDataSlot implements Disposable {
+    private readonly requestSegmentData;
+    /**
+     * Called when the status has changed.
+     */
+    onStatusChange: (() => void) | null;
+    private _status;
+    private readonly abortSlot;
+    private bufferPromise;
+    constructor(requestSegmentData: SegmentDataProvider);
+    /**
+     * This segment's request status.
+     */
+    get status(): SegmentStatus;
+    private set status(value);
+    /**
+     * Aborts the request if the status is currently {@link SegmentStatus.PENDING}, and clears the cached buffer.
+     * The status will go back to {@link SegmentStatus.INACTIVE} and the segment may be requested again in the future.
+     */
+    clear(): void;
+    /**
+     * Begins the segment request now if it has not already been requested.
+     * The promise returned will settle after this slot's status has updated and onStatusChange callback invoked.
+     */
+    request(): Promise<ArrayBuffer>;
+    /**
+     * Clears this segment and removes its handler.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=SegmentDataSlot.d.ts.map

package/dist/types/ts4.7/streaming/SegmentPrefetch.d.ts

@@ -0,0 +1,62 @@
+import type { Task, TaskQueue } from '@amazon/vinyl-util';
+import { type Comparator } from '@amazon/vinyl-util';
+import type { ContentType } from './MediaQualityMetadata';
+/**
+ * Properties affecting segment prefetch priority.
+ * Each track when prefetching will only add one segment to the prefetch queue at a time.
+ */
+export interface SegmentPrefetchPriority {
+    /**
+     * The track's prefetch priority.
+     */
+    readonly trackPriority: number;
+    /**
+     * The starting time of the segment.
+     */
+    readonly segmentStartTime: number;
+    /**
+     * The time position prefetching starts for this segment's track.
+     */
+    readonly prefetchStartTime: number;
+}
+export declare const defaultTrackPriority: {
+    readonly trackPriority: 0;
+    readonly segmentStartTime: 9007199254740991;
+    readonly prefetchStartTime: 0;
+};
+/**
+ * Highest priority; used to block prefetching while an actively-needed operation is enqueued.
+ */
+export declare const immediatePrefetchPriority: {
+    trackPriority: number;
+    segmentStartTime: number;
+    prefetchStartTime: number;
+};
+/**
+ * A comparator for segment prefetching.
+ * Given tracks A, B, and C with track priorities 1, 2, and 3 respectively:
+ * The expected prefetch order will be:
+ *
+ * A0
+ * B0 // "lean forward" case
+ * C0 // "lean forward" case
+ * A1 ... An
+ * B1 ... Bn
+ * C1 ... Cn
+ *
+ * Note that background prefetching is in parallel to prefetching for the active track.
+ */
+export declare const segmentPriorityComparatorRef: import("@amazon/vinyl-util").GlobalRef<Comparator<SegmentPrefetchPriority>>;
+export declare const prefetchPriorityQueuesRef: import("@amazon/vinyl-util").GlobalRef<Record<ContentType, TaskQueue<SegmentPrefetchPriority>>>;
+/**
+ * Enqueues a task to request a streaming segment for a specific content type.
+ * This should only be used for low priority background requests. Active tracks should request without
+ * prioritization for the immediately needed segment.
+ * Tracks are expected to prefetch one segment at a time, in order.
+ *
+ * @param requestTask
+ * @param contentType
+ * @param priority
+ */
+export declare function enqueueSegmentPrefetch(requestTask: Task<any>, contentType: ContentType, priority: SegmentPrefetchPriority): Promise<void>;
+//# sourceMappingURL=SegmentPrefetch.d.ts.map

package/dist/types/ts4.7/streaming/SegmentReference.d.ts

@@ -0,0 +1,48 @@
+import type { MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
+export interface MediaSegmentMetadata {
+    /**
+     * The timestamp offset of the segment.
+     * Should be used as the append timestamp offset.
+     * This is in seconds, relative to the MPD timeline.
+     * For example if the first segment has a timestampOffset of -2 and startTime of 0, playback will begin 2s into the
+     * start of that segment.
+     */
+    readonly timestampOffset: number;
+    /**
+     * The start time of the segment, in seconds.
+     * Relative to the MPD timeline.
+     * Should be used as the append window start.
+     */
+    readonly startTime: number;
+    /**
+     * The end time of the segment, in seconds.
+     * Relative to the MPD timeline.
+     * Should be used as the append window end.
+     */
+    readonly endTime: number;
+}
+export interface InitSegmentReference<T> {
+    /**
+     * Metadata describing the media encoding.
+     */
+    readonly quality: MediaQualityMetadata;
+    /**
+     * References initialization data for this segment.
+     * Must be appended before `data` if the decoderId has changed from the last buffered
+     * segment.
+     * This is a shared reference between other streaming segments of the same quality/representation.
+     */
+    readonly initData: T;
+}
+export interface MediaSegmentReference<T> extends MediaSegmentMetadata {
+    /**
+     * Provides the media data.
+     */
+    readonly data: T;
+}
+/**
+ * A reference, with metadata, to streaming and initialization data.
+ */
+export interface SegmentReference<T> extends InitSegmentReference<T>, MediaSegmentReference<T> {
+}
+//# sourceMappingURL=SegmentReference.d.ts.map

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

@@ -0,0 +1,68 @@
+import type { ChangeEvent } from '../event/ChangeEvent';
+import type { ContentType, MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
+import type { BasicErrorEvent } from '../event/BasicErrorEvent';
+import type { AnyRecord } from '@amazon/vinyl-util';
+/**
+ * Events a track dispatches related to streaming quality and status.
+ */
+export interface StreamingEventMap {
+    /**
+     * The actively streamed content types have changed.
+     */
+    readonly contentTypesChange: ChangeEvent<ReadonlySet<ContentType>>;
+    /**
+     * fetchedRanges have been updated.
+     */
+    readonly fetchedRangesChange: AnyRecord;
+    /**
+     * Dispatched when the currently streaming quality changes.
+     * This is dispatched when a new streaming quality has been requested.
+     */
+    readonly streamingQualityChange: ChangeEvent<MediaQualityMetadata | null>;
+    /**
+     * Dispatched when the currently buffering quality changes.
+     * This is dispatched before the segment is appended.
+     */
+    readonly bufferingQualityChange: ChangeEvent<MediaQualityMetadata | null>;
+    /**
+     * The currently playing quality has changed.
+     */
+    readonly playbackQualityChange: ChangeEvent<MediaQualityMetadata | null>;
+    /**
+     * The last segment has finished appending.
+     */
+    readonly bufferingEnded: AnyRecord;
+    /**
+     * Dispatched when a streaming error occurs.
+     */
+    readonly error: BasicErrorEvent;
+    /**
+     * Emitted when the error state has been reset.
+     */
+    readonly reset: AnyRecord;
+    /**
+     * The available qualities for the current period have changed.
+     */
+    readonly qualitiesChange: ChangeEvent<readonly MediaQualityMetadata[]>;
+    /**
+     * The available unfiltered qualities for the current period have changed.
+     */
+    readonly qualitiesUnfilteredChange: ChangeEvent<readonly MediaQualityMetadata[]>;
+}
+/**
+ * All streaming-related events a track may emit.
+ * These will be bubbled by the player.
+ */
+export declare const ALL_STREAMING_EVENTS: readonly [
+    "contentTypesChange",
+    "fetchedRangesChange",
+    "streamingQualityChange",
+    "bufferingQualityChange",
+    "playbackQualityChange",
+    "bufferingEnded",
+    "error",
+    "reset",
+    "qualitiesChange",
+    "qualitiesUnfilteredChange"
+];
+//# sourceMappingURL=StreamingEventMap.d.ts.map

package/dist/types/ts4.7/streaming/abr/QualitySelector.d.ts

@@ -0,0 +1,33 @@
+import type { MediaQualityMetadata } from '../../streaming/MediaQualityMetadata';
+export interface PrefetchState {
+    /**
+     * The number of seconds currently prefetched.
+     */
+    readonly fetchedTime: number;
+    /**
+     * The quality metadata of the previous segment. Quality selection may have a bias to prefer avoiding
+     * decoder re-initialization.
+     */
+    readonly previousQuality: MediaQualityMetadata | null;
+    /**
+     * True when prefetching for the active track.
+     */
+    readonly active: boolean;
+}
+export interface QualitySelector {
+    /**
+     * Returns the quality that should currently be streamed.
+     *
+     * @param qualities A sorted list of qualities for the currently streaming media.
+     * All qualities are expected to be playable.
+     *
+     * Higher bandwidth values are expected to also mean higher quality.
+     * That is, if there are multiple playable qualities where one has a higher quality ranking and lower bandwidth,
+     * the less efficient representation should be filtered out before the request.
+     * @param prefetchState The current prefetch state.
+     *
+     * @return Returns the index of the quality to stream.
+     */
+    selectQuality(qualities: readonly MediaQualityMetadata[], prefetchState: PrefetchState): number;
+}
+//# sourceMappingURL=QualitySelector.d.ts.map

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

@@ -0,0 +1,100 @@
+import type { PrefetchState, QualitySelector } from '../../streaming/abr/QualitySelector';
+import { type Disposable, type LogTarget } from '@amazon/vinyl-util';
+import { type ObjectSchema } from '@amazon/vinyl-validation';
+import type { MediaQualityMetadata } from '../../streaming/MediaQualityMetadata';
+import type { ObservableValue } from '@amazon/vinyl-observable';
+export interface QualitySelectorImplOptions {
+    /**
+     * If at least this amount of time (in seconds) is currently fetched, don't consider an ABR-down.
+     * Also used as the upper bound for interpolating between {@link bandwidthMultiplierLow} and
+     * {@link bandwidthMultiplierHigh} based on the current fetched time.
+     * Default: 15
+     */
+    readonly highBufferThreshold?: number;
+    /**
+     * If less than this amount of time (in seconds) is currently fetched, don't consider an ABR-up.
+     * Default: 4
+     */
+    readonly lowBufferThreshold?: number;
+    /**
+     * Defines the strategy used for quality selection.
+     *
+     * Default: BEST (ABR will be enabled)
+     */
+    readonly strategy?: AbrStrategy;
+    /**
+     * A multiplier applied to the estimated bandwidth when the fetched buffer is empty (0 seconds).
+     * Lower values are more conservative (reduce the bandwidth used for quality selection) and help
+     * avoid rebuffers when the buffer is low.
+     *
+     * As the fetched buffer fills toward {@link highBufferThreshold}, the effective multiplier
+     * linearly interpolates between this value and {@link bandwidthMultiplierHigh}.
+     *
+     * Default: 0.4
+     */
+    readonly bandwidthMultiplierLow?: number;
+    /**
+     * A multiplier applied to the estimated bandwidth when the fetched buffer is at or above
+     * {@link highBufferThreshold}. Higher values are more optimistic and allow selection of higher
+     * qualities once enough data is buffered to absorb short-term bandwidth dips.
+     *
+     * As the fetched buffer fills from 0 toward {@link highBufferThreshold}, the effective multiplier
+     * linearly interpolates between {@link bandwidthMultiplierLow} and this value.
+     *
+     * Default: 0.9
+     */
+    readonly bandwidthMultiplierHigh?: number;
+    /**
+     * When true, avoids changing codecs when considering choosing a higher audio bitrate
+     * than what is currently playing. A decoder re-initialization is often an audible change,
+     * so consumers that prefer to avoid audible artifacts may enable this. ABR-down is still
+     * allowed across decoders because the subtle audio artifact is more desirable than a rebuffer.
+     * Default: false
+     */
+    readonly restrictDecoderChangeOnAudioAbrUp?: boolean;
+}
+export declare enum AbrStrategy {
+    /**
+     * Selects lowest quality, regardless of bandwidth conditions.
+     */
+    LOWEST = "lowest",
+    /**
+     * Selects highest quality, regardless of bandwidth conditions.
+     */
+    HIGHEST = "highest",
+    /**
+     * Selects the best quality based on user bandwidth data.
+     * Uses an EWMA estimation.
+     */
+    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.
+     */
+    FIXED = "fixed"
+}
+export declare const qualitySelectorImplOptionsValidator: ObjectSchema<QualitySelectorImplOptions>;
+export declare const defaultQualitySelectorImplOptions: {
+    readonly highBufferThreshold: 15;
+    readonly lowBufferThreshold: 4;
+    readonly strategy: AbrStrategy.BEST;
+    readonly bandwidthMultiplierLow: 0.4;
+    readonly bandwidthMultiplierHigh: 0.9;
+    readonly restrictDecoderChangeOnAudioAbrUp: false;
+};
+export interface QualitySelectorImplDeps {
+    readonly options: ObservableValue<QualitySelectorImplOptions>;
+}
+export declare class QualitySelectorImpl implements QualitySelector, LogTarget, Disposable {
+    get [Symbol.toStringTag](): string;
+    readonly logPrefix: string;
+    private _options;
+    private disposer;
+    constructor(deps: QualitySelectorImplDeps);
+    get options(): Required<QualitySelectorImplOptions>;
+    selectQuality(qualities: readonly MediaQualityMetadata[], prefetchState: PrefetchState): number;
+    get disposed(): boolean;
+    dispose(): void;
+}
+//# sourceMappingURL=QualitySelectorImpl.d.ts.map

package/dist/types/ts4.7/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