@amazon/vinyl 1.0.0

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

@@ -0,0 +1,168 @@
+import type { ReadonlyAbort, ReadonlyRanges } from '@amazon/vinyl-util';
+import { EventHostImpl } from '@amazon/vinyl-util';
+import type { ReadonlyPlaybackController } from '../playback/ReadonlyPlaybackController';
+import type { PrefetchOptions, SegmentController, SegmentControllerEventMap } from '../streaming/SegmentController';
+import type { SegmentReference } from '../streaming/SegmentReference';
+import type { ContentType, MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
+import type { ObservableValue } from '@amazon/vinyl-observable';
+import type { MediaTimeline } from '../streaming/MediaTimeline';
+import type { QualitySelector } from '../streaming/abr/QualitySelector';
+/**
+ * The interval to check if additional segments should be prefetched.
+ */
+export declare const PREFETCH_POLL_THROTTLE = 1;
+export interface SegmentControllerImplDeps {
+    readonly playbackController: ReadonlyPlaybackController;
+    readonly mediaTimelineTransformed: ObservableValue<Promise<MediaTimeline>>;
+    readonly qualitySelector: QualitySelector;
+}
+export interface SegmentControllerImplOptions {
+    /**
+     * The amount of time ahead of the playhead to prefetch when the track is active.
+     * Default: 240
+     */
+    readonly prefetchActive: number;
+    /**
+     * The amount of time to prefetch when the track is not active.
+     * Default: 20
+     */
+    readonly prefetchInactive: number;
+    /**
+     * The number of seconds behind the playhead to retain segments.
+     * Default: 30
+     */
+    readonly retainTail: number;
+}
+export declare const defaultSegmentControllerBaseOptions: SegmentControllerImplOptions;
+/**
+ * Default SegmentController implementation.
+ * Provides segments for a given time.
+ * Handles segment prefetching and caching.
+ *
+ * Uses mediaTimelineTransformed to resolve segments directly from the MediaTimeline.
+ */
+export declare class SegmentControllerImpl extends EventHostImpl<SegmentControllerEventMap> implements SegmentController {
+    readonly deps: SegmentControllerImplDeps;
+    readonly contentType: ContentType;
+    get [Symbol.toStringTag](): string;
+    private _active;
+    get active(): boolean;
+    private readonly _fetchedRanges;
+    private _startTime;
+    /**
+     * A map of decoder id to init segment slots.
+     * This allows representations with seamless bitstream switching to share initialization segments without
+     * making unnecessary requests or decoder re-initializations.
+     */
+    private readonly cachedInitSegments;
+    private readonly cachedSegments;
+    private readonly disposer;
+    readonly options: SegmentControllerImplOptions;
+    private prefetchingPriority;
+    /**
+     * True if the last segment in the prefetch range has been cached.
+     */
+    private ended;
+    private prefetching;
+    private _error;
+    private timeUpdateSub;
+    private seekingSub;
+    private readonly abort;
+    /**
+     * Cached last period lookup for fast repeated access.
+     */
+    private _cachedPeriod;
+    constructor(deps: SegmentControllerImplDeps, contentType: ContentType, options?: Partial<SegmentControllerImplOptions>);
+    get error(): (Error | null);
+    getDuration(): Promise<number | null>;
+    /**
+     * Gets the period at the given time, using a cache for the last returned period.
+     */
+    private getPeriodAtTime;
+    /**
+     * Configures this segment provider and initiates prefetching.
+     * This may be called multiple times, for example when re-using a cached track a new track priority and start time
+     * can be provided.
+     */
+    configure(options: Partial<PrefetchOptions>): void;
+    get startTime(): number;
+    get trackPrefetchPriority(): number;
+    /**
+     * Returns the range that should be prefetched.
+     */
+    private get prefetchRange();
+    /**
+     * Returns the range that should be prefetched when inactive.
+     * This range will not be removed during sweeps unless `clear` is called.
+     */
+    private get prefetchRangeInactive();
+    /**
+     * Returns the range that should be prefetched while active.
+     */
+    private get prefetchRangeActive();
+    /**
+     * Clears data segments no longer within the current prefetch range.
+     * Init segments will not be changed.
+     */
+    private sweepCachedSegments;
+    /**
+     * Gets the next time to prefetch, or null if the prefetch range has been filled.
+     */
+    private getNextTimeToPrefetch;
+    private pollPrefetch;
+    private prefetchErrorHandler;
+    get fetchedRanges(): ReadonlyRanges;
+    get fetchedTime(): number;
+    private _streamingQuality;
+    get streamingQuality(): (MediaQualityMetadata | null);
+    private set streamingQuality(value: (MediaQualityMetadata | null));
+    getSegment(time: number, abort?: ReadonlyAbort): Promise<SegmentReference<ArrayBuffer> | null>;
+    private _getSegment;
+    /**
+     * Gets the minimum buffer time from the timeline.
+     * Falls back to a reasonable default.
+     */
+    private getMinBufferTime;
+    /**
+     * Prefetches the segment at the given time. Does not use the background scheduler.
+     *
+     * @param time
+     */
+    private prefetchImmediate;
+    /**
+     * Gets a streaming segment slot that spans the given time, or null if there is no media at that time.
+     * Slots will be cached until they slide out of the retention range or `clear` is called.
+     */
+    private getSlotAtTime;
+    /**
+     * Gets a cached init segment slot for the given decoder id. If a slot is not cached, create one.
+     */
+    private getOrCreateInitSlot;
+    /**
+     * Creates a slot that spans the given time, or returns null if there is no media at that time.
+     * Uses the mediaTimelineTransformed to resolve segments directly.
+     */
+    private createSlotForTime;
+    /**
+     * Indicates that this segment provider is providing segments for an active track and should be prioritized
+     * accordingly.
+     * Time ranges to be prefetched will change to the active prefetch window.
+     */
+    activate(): void;
+    /**
+     * Deactivates the segment provider.
+     * This clears cached segments not within the inactive prefetch range.
+     * Time ranges to be prefetched will change to the inactive prefetch window.
+     */
+    deactivate(): void;
+    clear(): void;
+    reset(): void;
+    /**
+     * Resets the slot if it's in an error state.
+     * @param slot
+     */
+    private resetSlot;
+    get disposed(): boolean;
+    dispose(): void;
+}
+//# sourceMappingURL=SegmentControllerImpl.d.ts.map

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

@@ -0,0 +1,55 @@
+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);
+    get status(): SegmentStatus;
+    private set status(value: SegmentStatus);
+    /**
+     * 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.1/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.1/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.1/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.1/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.1/streaming/abr/QualitySelectorImpl.d.ts

@@ -0,0 +1,100 @@
+import type { PrefetchState, QualitySelector } from '../../streaming/abr/QualitySelector';
+import type { Disposable, 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