@amazon/vinyl 1.0.0

package/dist/types/ts4.1/streaming/buffering/BufferingController.d.ts

@@ -0,0 +1,240 @@
+import type { AnyRecord, Clearable, Disposable, ReadonlyEventHost } from '@amazon/vinyl-util';
+import { EventHostImpl } 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;
+    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);
+    get bufferingQuality(): (MediaQualityMetadata | null);
+    private set bufferingQuality(value: (MediaQualityMetadata | null));
+    /**
+     * Sets the current playback quality and emits a playbackQualityChange event.
+     * No-ops if quality id has not changed.
+     */
+    private set playbackQuality(value: (MediaQualityMetadata | null));
+    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();
+    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/ts4.1/streaming/buffering/MediaSourceController.d.ts

@@ -0,0 +1,104 @@
+import type { AnyRecord, Disposable, Json, LogTarget, ReadonlyEventHost } from '@amazon/vinyl-util';
+import { EventHostImpl, ReportableError } from '@amazon/vinyl-util';
+import type { ContentTypesValue } from '../../streaming/ContentTypesValue';
+import type { BasicErrorEvent } from '../../event/BasicErrorEvent';
+import type { ContentType } from '../../streaming/MediaQualityMetadata';
+export interface SourceBufferRef extends Disposable {
+    /**
+     * The source buffer.
+     */
+    readonly value: SourceBuffer;
+}
+export interface MediaSourceControllerEventMap {
+    /**
+     * The media source has entered a 'closed' state.
+     */
+    readonly sourceClose: AnyRecord;
+    /**
+     * The media source has entered an 'ended' state.
+     */
+    readonly sourceEnded: AnyRecord;
+    /**
+     * The media source has entered an 'open' state.
+     */
+    readonly sourceOpen: AnyRecord;
+    /**
+     * All source buffers have been created and data may be appended.
+     */
+    readonly readyToAppend: AnyRecord;
+    /**
+     * An error has occurred.
+     */
+    readonly error: BasicErrorEvent;
+}
+export interface ReadonlyMediaSourceController extends ReadonlyEventHost<MediaSourceControllerEventMap> {
+    /**
+     * Returns the parent media source ready state.
+     */
+    readonly readyState: ReadyState;
+    /**
+     * Gets the media source's duration.
+     */
+    readonly duration: number;
+    /**
+     * True if all source buffers have been created and data may be appended.
+     */
+    readonly readyToAppend: boolean;
+}
+export interface MediaSourceController extends ReadonlyMediaSourceController {
+    /**
+     * Sets/gets the media source's duration.
+     */
+    duration: number;
+    /**
+     * Constructs a new SourceBuffer with the given content type and mime type.
+     */
+    createSourceBuffer(contentType: ContentType, mimeType: string): SourceBufferRef;
+    /**
+     * Signals the end of the stream.
+     * @param error A string representing an error to throw when the end of the stream is reached.
+     */
+    endOfStream(error?: EndOfStreamError): void;
+    /**
+     * Creates an Object URL to use as the source for this stream.
+     */
+    createUrl(): string;
+}
+export interface MediaSourceControllerImplDeps {
+    /**
+     * Creates a new media source.
+     */
+    readonly mediaSourceFactory: () => MediaSource;
+    /**
+     * Provides the streams that must be created before appending.
+     */
+    readonly contentTypesValue: ContentTypesValue;
+}
+export declare class MediaSourceControllerImpl extends EventHostImpl<MediaSourceControllerEventMap> implements MediaSourceController, LogTarget {
+    get [Symbol.toStringTag](): string;
+    private sourceBufferCount;
+    private readonly mediaSource;
+    private readonly disposer;
+    private contentTypes;
+    constructor(deps: MediaSourceControllerImplDeps);
+    private initializeEvents;
+    get duration(): number;
+    set duration(value: number);
+    get readyState(): ReadyState;
+    createSourceBuffer(contentType: ContentType, mimeType: string): SourceBufferRef;
+    /**
+     * Emits a 'readyToAppend' event if all source buffers have been created.
+     */
+    private readonly checkReady;
+    endOfStream(error?: EndOfStreamError): void;
+    createUrl(): string;
+    get readyToAppend(): boolean;
+    dispose(): void;
+}
+export declare class MediaSourceError extends ReportableError {
+    private readonly reason;
+    get [Symbol.toStringTag](): string;
+    constructor(message: string, reason: Error);
+    toJSON(): Json;
+}
+//# sourceMappingURL=MediaSourceController.d.ts.map

package/dist/types/ts4.1/streaming/buffering/SourceBufferController.d.ts

@@ -0,0 +1,91 @@
+import type { Disposable, LogTarget, ReadonlyRanges, Task } from '@amazon/vinyl-util';
+import type { MediaSourceController } from './MediaSourceController';
+import type { ContentType } from '../../streaming/MediaQualityMetadata';
+export declare const APPEND_WINDOW_START_OFFSET = 0.05;
+export declare const APPEND_WINDOW_END_OFFSET = 0.01;
+export declare const READY_TO_APPEND_TIMEOUT = 30;
+export type SourceBufferControllerFactory = () => SourceBufferController;
+export interface SourceBufferController extends Disposable {
+    readonly buffered: ReadonlyRanges;
+    /**
+     * Returns true if an operation is currently running.
+     */
+    isBusy(): boolean;
+    /**
+     * Enqueues an operation.
+     * Guaranteed to be invoked when the source buffer is not updating.
+     */
+    enqueue<T = void>(task: Task<T>): Promise<T>;
+    /**
+     * Enqueues appending an initialization segment, reinitializing the decoder.
+     */
+    appendInit(data: ArrayBuffer, mimeType: string): Promise<void>;
+    /**
+     * Enqueues appending a media segment.
+     * An `appendInit` call must precede appending media segments.
+     * A promise is returned that will resolve when the task is complete.
+     */
+    append(data: ArrayBuffer): Promise<void>;
+    /**
+     * Sets the timestampOffset on the backing source buffer.
+     */
+    setTimestampOffset(timestampOffset: number): Promise<void>;
+    /**
+     * Sets the append window on the backing source buffer.
+     * Keyframes outside this range will be discarded.
+     */
+    setAppendWindow(appendWindowStart?: number, appendWindowEnd?: number): Promise<void>;
+    /**
+     * Removes media segments within a specific time range from the SourceBuffer.
+     */
+    remove(startTime: number, endTime: number): Promise<void>;
+    /**
+     * Aborts any pending buffers and clears all buffered ranges.
+     */
+    clear(): Promise<void>;
+}
+export interface SourceBufferControllerImplDeps {
+    /**
+     * Produces the source buffer for appending.
+     */
+    readonly mediaSourceController: MediaSourceController;
+}
+/**
+ * The SourceBufferController manages a single source buffer. It provides queued commands for appending and clearing
+ * data.
+ */
+export declare class SourceBufferControllerImpl implements LogTarget, SourceBufferController, Disposable {
+    readonly contentType: ContentType;
+    get [Symbol.toStringTag](): string;
+    private sourceBufferRef;
+    private mimeType;
+    private queue;
+    readonly logPrefix: string;
+    private readonly mediaSourceController;
+    constructor(deps: SourceBufferControllerImplDeps, contentType: ContentType);
+    private get sourceBuffer();
+    private _buffered;
+    get buffered(): ReadonlyRanges;
+    /**
+     * Clears the cached buffered ranges. They will be recreated next access.
+     */
+    private clearBufferedCache;
+    isBusy(): boolean;
+    enqueue<T = void>(task: Task<T>): Promise<T>;
+    appendInit(data: ArrayBuffer, mimeType: string): Promise<void>;
+    append(data: ArrayBuffer): Promise<void>;
+    setTimestampOffset(timestampOffset: number): Promise<void>;
+    setAppendWindow(appendWindowStart?: number, appendWindowEnd?: number): Promise<void>;
+    remove(startTime: number, endTime: number): Promise<void>;
+    /**
+     * Returns a promise that resolves when the source buffer is no longer updating.
+     * @private
+     */
+    private nextIdle;
+    clear(): Promise<void>;
+    /**
+     * Aborts any pending operations and disposes the backed SourceBuffer.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=SourceBufferController.d.ts.map

package/dist/types/ts4.1/streaming/buffering/error/SourceBufferError.d.ts

@@ -0,0 +1,9 @@
+import { ReportableError } from '@amazon/vinyl-util';
+/**
+ * An error emitted from the SourceBuffer.
+ */
+export declare class SourceBufferError extends ReportableError {
+    get [Symbol.toStringTag](): string;
+    constructor(message?: string, origin?: string);
+}
+//# sourceMappingURL=SourceBufferError.d.ts.map

package/dist/types/ts4.1/streaming/createDefaultMediaTimelineTransformer.d.ts

@@ -0,0 +1,18 @@
+import type { ObservableValue } from '@amazon/vinyl-observable';
+import type { Capabilities } from '../client/Capabilities';
+import type { DrmController } from '../drm/DrmController';
+import type { MediaTimeline } from '../streaming/MediaTimeline';
+export interface DefaultMediaTimelineTransformerDeps {
+    readonly capabilities: Capabilities;
+    readonly drmController: DrmController;
+    readonly mediaTimeline: ObservableValue<Promise<MediaTimeline>>;
+    readonly options: ObservableValue<{
+        readonly preferredAudioLanguage: string | null;
+    }>;
+}
+/**
+ * The default media timeline transformer filters out unplayable qualities
+ * and applies language preferences. Shared by Dash and HLS.
+ */
+export declare function createDefaultMediaTimelineTransformer(deps: DefaultMediaTimelineTransformerDeps): ObservableValue<Promise<MediaTimeline>>;
+//# sourceMappingURL=createDefaultMediaTimelineTransformer.d.ts.map

package/dist/types/ts4.1/streaming/mediaTimelineFilter.d.ts

@@ -0,0 +1,18 @@
+import type { MediaTimeline } from '../streaming/MediaTimeline';
+import type { MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
+import type { FilterPredicate, FilterPredicateAsync, Maybe } from '@amazon/vinyl-util';
+/**
+ * Filters qualities in a MediaTimeline using a synchronous predicate.
+ * If filtering would remove all qualities from any period, throws via `throwError`.
+ */
+export declare function filterTimelineQualities(filter: Maybe<FilterPredicate<MediaQualityMetadata>>, throwError: () => never, timeline: MediaTimeline): MediaTimeline;
+/**
+ * Filters qualities in a MediaTimeline using an asynchronous predicate.
+ * If filtering would remove all qualities from any period, throws via `throwError`.
+ */
+export declare function filterTimelineQualitiesAsync(filter: FilterPredicateAsync<MediaQualityMetadata>, throwError: () => never, timeline: MediaTimeline): Promise<MediaTimeline>;
+/**
+ * Creates a language filter predicate for use with filterTimelineQualities.
+ */
+export { createLanguageFilter } from '../streaming/mediaTimelineLanguageFilter';
+//# sourceMappingURL=mediaTimelineFilter.d.ts.map

package/dist/types/ts4.1/streaming/mediaTimelineLanguageFilter.d.ts

@@ -0,0 +1,14 @@
+import type { MediaQualityMetadata } from '../streaming/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.
+ *
+ * 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 contentType Only filter qualities matching this content type (e.g. 'audio').
+ */
+export declare function createLanguageFilter(preferredLanguage: string | null, contentType: string): FilterPredicate<MediaQualityMetadata> | null;
+//# sourceMappingURL=mediaTimelineLanguageFilter.d.ts.map

package/dist/types/ts4.1/streaming/util/segment.d.ts

@@ -0,0 +1,28 @@
+import type { MediaSegmentMetadata } from '../../streaming/SegmentReference';
+/**
+ * Returns the segment whose range covers `time` (`startTime <= time < endTime`), or
+ * — when `affordance > 0` — the next segment if `time` falls within `affordance`
+ * seconds before its `startTime`. Returns `null` if neither applies.
+ *
+ * Note: with `affordance > 0`, when `time` lies in the last `affordance` seconds of a
+ * segment that does cover it, the *next* segment is returned instead. This is
+ * deliberate — callers use `affordance` to absorb sub-second boundary differences
+ * across qualities — but it means the result is not strictly the segment containing
+ * `time`. Callers needing exact containment should pass `affordance = 0`.
+ *
+ * @param time Lookup time, in seconds.
+ * @param segments Segments sorted by `startTime` ascending.
+ * @param affordance Forward-snap tolerance in seconds: if `time` falls just before a
+ * segment's `startTime` (within `affordance`), that segment is returned. The original
+ * `time` is still compared against `endTime`, so coverage never extends past it.
+ */
+export declare function getSegmentAtTime<T extends MediaSegmentMetadata>(time: number, segments: readonly T[], affordance?: number): T | null;
+/**
+ * Returns the count of segments whose `startTime <= time` — i.e. the index at which a
+ * segment with that `startTime` would be inserted to keep the array sorted ascending.
+ *
+ * @param time Lookup time, in seconds.
+ * @param segments Segments sorted by `startTime` ascending.
+ */
+export declare function getSegmentInsertionIndexAtTime(time: number, segments: readonly MediaSegmentMetadata[]): number;
+//# sourceMappingURL=segment.d.ts.map

package/dist/types/ts4.1/track/AutoResetController.d.ts

@@ -0,0 +1,84 @@
+import type { AnyRecord, Clearable, Disposable, ReadonlyEventHost } from '@amazon/vinyl-util';
+import { EventHostImpl } from '@amazon/vinyl-util';
+import type { PlaybackController } from '../playback/PlaybackController';
+export interface AutoResetControllerEventMap {
+    /**
+     * Notifies that playback errors should be reset and retried.
+     */
+    readonly reset: AnyRecord;
+}
+/**
+ * Notifies when playback should be reset and retried.
+ *
+ * The controller monitors for retry opportunities after an error is set:
+ * - Immediately on network 'online' events
+ * - After a timeout interval if online
+ * - Immediately on user playback actions (play, pause, seeking, playing)
+ *
+ * Each error triggers a single timeout. If another error occurs after a reset,
+ * setError() should be called again to schedule the next retry attempt.
+ */
+export interface AutoResetController extends ReadonlyEventHost<AutoResetControllerEventMap>, Clearable {
+    /**
+     * Sets the current playback error and begins monitoring for retry opportunities.
+     *
+     * Only SERVICE_INTERNAL ReportableErrors are monitored. Subsequent calls while
+     * an error is already set are ignored until the error is cleared via reset or clear().
+     *
+     * After a reset, if another error occurs, this method should be called again
+     * to schedule the next retry attempt.
+     *
+     * @param error The error to monitor for retry opportunities
+     */
+    setError(error: Error): void;
+}
+export interface AutoResetControllerImplDeps {
+    readonly playbackController: PlaybackController;
+}
+export interface AutoResetControllerImplOptions {
+    /**
+     * If false, disables auto reset behavior.
+     * default: true
+     */
+    readonly enabled: boolean;
+    /**
+     * The total number of times to reset when there has not been successful
+     * playback.
+     *
+     * E.g. a retryInterval of 30 and maxRetries of 30 will retry for 15 minutes before stopping.
+     *
+     * default: 30
+     */
+    readonly maxRetries: number;
+    /**
+     * The number of seconds between retries.
+     *
+     * When an error is set, a single timeout is scheduled for this interval.
+     * If the retry limit hasn't been reached and the device is online, a reset
+     * event is emitted. For subsequent errors after reset, setError() must be
+     * called again to schedule the next retry timeout.
+     */
+    readonly retryInterval: number;
+}
+export declare const defaultResetControllerOptions: {
+    readonly enabled: true;
+    readonly maxRetries: 30;
+    readonly retryInterval: 30;
+};
+export declare class AutoResetControllerImpl extends EventHostImpl<AutoResetControllerEventMap> implements AutoResetController, Disposable {
+    readonly deps: AutoResetControllerImplDeps;
+    get [Symbol.toStringTag](): string;
+    private readonly options;
+    private _error;
+    private watchSub;
+    private currentRetry;
+    private disposer;
+    constructor(deps: AutoResetControllerImplDeps, options?: Partial<AutoResetControllerImplOptions>);
+    setError(error: Error): void;
+    private setWatching;
+    private reset;
+    clear(): void;
+    get disposed(): boolean;
+    dispose(): void;
+}
+//# sourceMappingURL=AutoResetController.d.ts.map