@amazon/vinyl 1.0.0

package/dist/types/current/track/TrackController.d.ts

@@ -0,0 +1,244 @@
+import { type AnyRecord, type Disposable, EventHostImpl, type Maybe, type ReadonlyEventHost } from '@amazon/vinyl-util';
+import type { PlaybackController } from '../playback/PlaybackController';
+import type { ReadonlyTrack, TrackUri } from '../track/Track';
+import type { TrackFactory, TrackLoadOptions } from '../track/TrackFactory';
+import type { ChangeEvent } from '../event/ChangeEvent';
+export interface TrackControllerEventMap<TrackLoadOptionsType extends TrackLoadOptions> {
+    /**
+     * Emitted when the current track is changing.
+     * This is emitted before the previous track has been deactivated and
+     * new track has been activated.
+     */
+    readonly currentTrackChanging: ChangeEvent<ReadonlyTrack | null>;
+    /**
+     * Emitted when the current track has changed.
+     * If there is a queue change, the currentTrackChange event is always emitted first.
+     * This is emitted after the previous track has been deactivated and
+     * new track has been activated.
+     */
+    readonly currentTrackChange: ChangeEvent<ReadonlyTrack | null>;
+    /**
+     * Dispatched when the queue has changed.
+     */
+    readonly queueChange: ChangeEvent<readonly TrackLoadOptionsType[]>;
+    /**
+     * Emitted when the last track of the playback queue has ended.
+     * When the last track in a queue has ended, the track will not change and therefore a `currentTrackChange`
+     * event will not be emitted.
+     */
+    readonly queueEnded: AnyRecord;
+}
+export declare const ALL_TRACK_CONTROLLER_EVENTS: readonly ["currentTrackChanging", "currentTrackChange", "queueChange", "queueEnded"];
+/**
+ * A readonly interface to the track controller.
+ */
+export interface ReadonlyTrackController<TrackLoadOptionsType extends TrackLoadOptions> extends ReadonlyEventHost<TrackControllerEventMap<TrackLoadOptionsType>> {
+    /**
+     * Returns the current track.
+     */
+    readonly currentTrack: ReadonlyTrack | null;
+    /**
+     * Returns the current queue of TrackLoadOptions.
+     * Observe 'queueChange' for changes to this queue.
+     */
+    readonly queue: readonly TrackLoadOptionsType[];
+    /**
+     * Returns true if there is at least one track in the queue.
+     */
+    hasNext(): boolean;
+    /**
+     * Returns true if the track with the given URI is cached.
+     */
+    isTrackCached(uri: TrackUri): boolean;
+    /**
+     * Returns the cached track for the given URI, or null if the track is not cached.
+     */
+    getCachedTrack(uri: TrackUri): ReadonlyTrack | null;
+    /**
+     * Returns an iterator of currently cached tracks.
+     */
+    getCachedTracks(): IterableIterator<ReadonlyTrack>;
+}
+/**
+ * Responsible for queuing track load configurations.
+ * This is the authority for which is the current track.
+ */
+export interface TrackController<TrackLoadOptionsType extends TrackLoadOptions> extends ReadonlyTrackController<TrackLoadOptionsType> {
+    /**
+     * Preloads the given list of tracks.
+     * The tracks provided will not be enqueued.
+     * The track controller's cache size will automatically increase to accommodate the request.
+     *
+     * Prefetch priority note:
+     * Tracks have a prefetch priority, later calls to preload will have a higher precedence than previous calls.
+     * Previous tracks given to `preload` will drop off when they are evicted from the cache. This is dependent on
+     * cache size.
+     *
+     * @param loadOptionsList
+     */
+    preload(...loadOptionsList: readonly TrackLoadOptionsType[]): void;
+    /**
+     * Sets the current queue to the provided track list.
+     * When the track ends, the next will be played.
+     *
+     * `load` does not begin playback. Call `play()` after a load to start playback.
+     * Browser autoplay policies may require the first call to `play()` to be in response to a user interaction
+     * such as a click, touch, keypress, or voice event.
+     *
+     * Note that if the current track is the first track provided in the list, that track will be restarted.
+     * To set the queue without unloading the current track, use {@link clearQueue} followed by {@link enqueue}.
+     *
+     * @param loadOptionsList A list of load configuration objects to set as a playback queue.
+     */
+    load(...loadOptionsList: readonly TrackLoadOptionsType[]): void;
+    /**
+     * Unloads the active track and clears the queue.
+     * This is the same as calling {@link load} with zero parameters.
+     */
+    unload(): void;
+    /**
+     * Appends the given tracks to the current queue.
+     *
+     * @param loadOptionsList The track load configurations to append.
+     */
+    enqueue(...loadOptionsList: readonly TrackLoadOptionsType[]): void;
+    /**
+     * Activates the next track in the queue.
+     * If the media is not paused the next track will begin playing automatically.
+     *
+     * @see ReadonlyTrackController.hasNext
+     */
+    next(): void;
+    /**
+     * Clears all fetched fragments and source buffers.
+     * Playback will be interrupted, and streaming will resume again when data has been fetched and buffered.
+     * This should be called if a change has been made where the user would expect an immediate change,
+     * for example, changing streaming quality from SD to HD.
+     *
+     * Does not unload manifests.
+     */
+    clearPrefetch(): void;
+    /**
+     * Clears the track cache and unloads the current track.
+     */
+    clearTrackCache(): void;
+    /**
+     * Clears the current queue.
+     * Does not stop the current track or affect the prefetched cache.
+     */
+    clearQueue(): void;
+    /**
+     * Resets the current track's error state.
+     */
+    reset(): void;
+}
+export interface TrackControllerImplDeps<TrackLoadOptionsType extends TrackLoadOptions> {
+    readonly trackFactory: TrackFactory<TrackLoadOptionsType>;
+    readonly playbackController: PlaybackController;
+}
+export interface TrackControllerImplOptions {
+    /**
+     * When tracks are queued, the number of tracks to prefetch ahead of the current track.
+     * Default: 2
+     */
+    readonly trackPrefetchCount: number;
+    /**
+     * The number of seconds before load calls will time out if the first track's metadata is not loaded within
+     * this time.
+     * Default: 60
+     */
+    readonly loadTimeout: number;
+    /**
+     * The number of tracks that may be preloaded at one time (not counting queue prefetch).
+     * This extends the track cache capacity and allows a certain number of tracks no longer in the queue to remain
+     * cached.
+     *
+     * Default: 2
+     */
+    readonly preloadCapacity: number;
+}
+/**
+ * Track priority will be assigned based on calls to `preload`.
+ * Segment background prefetching is shared if there are multiple players instances (in the rare case there would be
+ * multiple players). Having a global incrementing trackPriority prevents one player from starving another.
+ */
+export declare const trackPriority: {
+    value: number;
+};
+export declare class TrackControllerImpl<TrackLoadOptionsType extends TrackLoadOptions> extends EventHostImpl<TrackControllerEventMap<TrackLoadOptionsType>> implements TrackController<TrackLoadOptionsType>, Disposable {
+    private readonly deps;
+    get [Symbol.toStringTag](): string;
+    private _autoPreloadCapacity;
+    private readonly trackCache;
+    private _queue;
+    private _current;
+    private readonly disposer;
+    private _options;
+    private trackEndedTimeoutId;
+    constructor(deps: TrackControllerImplDeps<TrackLoadOptionsType>, initialOptions?: Partial<TrackControllerImplOptions>);
+    private clearTrackEndedTimeout;
+    /**
+     * Returns the currently set configuration.
+     */
+    get options(): TrackControllerImplOptions;
+    /**
+     * Configures this track queue from the provided partial options.
+     *
+     * @param options
+     */
+    configure(options: Maybe<Partial<TrackControllerImplOptions>>): void;
+    /**
+     * Checks if the cache capacity needs to be changed.
+     */
+    private checkCacheCapacity;
+    get queue(): readonly TrackLoadOptionsType[];
+    /**
+     * Returns the subset of the queue that should be prefetched.
+     * @private
+     */
+    private get prefetched();
+    isTrackCached(uri: TrackUri): boolean;
+    getCachedTrack(uri: TrackUri): ReadonlyTrack | null;
+    getCachedTracks(): IterableIterator<ReadonlyTrack>;
+    /**
+     * Returns the current preload capacity.
+     * This automatically increases when preload is called with more tracks than the current capacity.
+     */
+    get preloadCapacity(): number;
+    private validateLoadOptions;
+    preload(...loadOptionsList: readonly TrackLoadOptionsType[]): void;
+    private _preload;
+    load(...loadOptionsList: readonly TrackLoadOptionsType[]): void;
+    unload(): void;
+    enqueue(...loadOptionsList: readonly TrackLoadOptionsType[]): void;
+    hasNext(): boolean;
+    next(): void;
+    clearTrackCache(): void;
+    clearPrefetch(): void;
+    clearQueue(): void;
+    /**
+     * If the given track id is the current track or in the cache, returns that track.
+     * Otherwise, constructs a new track, adds it to the cache, and returns it.
+     *
+     * @param uri The unique resource identifier.
+     * @param loadOptions
+     * @private
+     */
+    private getOrCreateTrack;
+    /**
+     * Get the current track from cache or create a new track, then activates that track.
+     */
+    private activateCurrent;
+    private _currentTrack;
+    get currentTrack(): ReadonlyTrack | null;
+    /**
+     * Sets the current track. If the given track is already current, it will be de-activated and re-activated and
+     * the currentTrackChange event will still be emitted.
+     * The same track may be in the queue multiple times.
+     */
+    private setCurrentTrack;
+    private clearCurrentTrack;
+    reset(): void;
+    dispose(): void;
+}
+//# sourceMappingURL=TrackController.d.ts.map

package/dist/types/current/track/TrackController.d.ts.map

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

package/dist/types/current/track/TrackController.js

@@ -0,0 +1,312 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { countElements, createDisposer, EventHostImpl, first, getOrSet, logDebug, logInfo, LruCache, noop, } from '@amazon/vinyl-util';
+export const ALL_TRACK_CONTROLLER_EVENTS = [
+    'currentTrackChanging',
+    'currentTrackChange',
+    'queueChange',
+    'queueEnded',
+];
+const defaultTrackControllerImplOptions = {
+    trackPrefetchCount: 2,
+    loadTimeout: 60,
+    preloadCapacity: 2,
+};
+/**
+ * Track priority will be assigned based on calls to `preload`.
+ * Segment background prefetching is shared if there are multiple players instances (in the rare case there would be
+ * multiple players). Having a global incrementing trackPriority prevents one player from starving another.
+ */
+export const trackPriority = {
+    value: 0,
+};
+export class TrackControllerImpl extends EventHostImpl {
+    deps;
+    get [Symbol.toStringTag]() {
+        return 'TrackControllerImpl';
+    }
+    // When tracks are preloaded, the cache capacity may expand automatically to accommodate.
+    _autoPreloadCapacity = 0;
+    trackCache = new LruCache(0);
+    _queue = [];
+    _current = null;
+    disposer = createDisposer();
+    _options = defaultTrackControllerImplOptions;
+    trackEndedTimeoutId = null;
+    constructor(deps, initialOptions) {
+        super();
+        this.deps = deps;
+        const { add } = this.disposer;
+        this.trackCache.onEvicting = (track) => {
+            // Do not evict tracks within the prefetch range.
+            return (this.prefetched.find((value) => value.uri === track.uri) == null);
+        };
+        this.trackCache.onEvict = (track) => {
+            logDebug(this, `Disposing track: ${track.uri}`);
+            track.dispose();
+            return true;
+        };
+        add(deps.playbackController.on('ended', () => {
+            this.trackEndedTimeoutId = setTimeout(() => {
+                // Adds a frame delay to allow applications an opportunity to respond to 'ended' events before the
+                // track is changed.
+                this.trackEndedTimeoutId = null;
+                if (this.hasNext()) {
+                    this.next();
+                }
+                else {
+                    logInfo(this, 'queueEnded');
+                    this.dispatch('queueEnded', {});
+                }
+            });
+        }));
+        this.configure(initialOptions);
+    }
+    clearTrackEndedTimeout() {
+        if (this.trackEndedTimeoutId) {
+            clearTimeout(this.trackEndedTimeoutId);
+            this.trackEndedTimeoutId = null;
+        }
+    }
+    /**
+     * Returns the currently set configuration.
+     */
+    get options() {
+        return this._options;
+    }
+    /**
+     * Configures this track queue from the provided partial options.
+     *
+     * @param options
+     */
+    configure(options) {
+        logDebug(this, 'configure', options);
+        this._options = {
+            ...this._options,
+            ...options,
+        };
+        this.checkCacheCapacity();
+    }
+    /**
+     * Checks if the cache capacity needs to be changed.
+     */
+    checkCacheCapacity() {
+        const capacity = this.preloadCapacity + this._options.trackPrefetchCount + 1;
+        if (capacity !== this.trackCache.capacity) {
+            logDebug(this, 'track cache capacity changed:', capacity);
+            this.trackCache.capacity = capacity;
+        }
+    }
+    get queue() {
+        return this._queue;
+    }
+    /**
+     * Returns the subset of the queue that should be prefetched.
+     * @private
+     */
+    get prefetched() {
+        const tracks = [];
+        if (this._current)
+            tracks.push(this._current);
+        tracks.push(...this._queue.slice(0, this.options.trackPrefetchCount));
+        return tracks;
+    }
+    isTrackCached(uri) {
+        return this.trackCache.has(uri);
+    }
+    getCachedTrack(uri) {
+        return this.trackCache.get(uri) ?? null;
+    }
+    getCachedTracks() {
+        return this.trackCache.values();
+    }
+    /**
+     * Returns the current preload capacity.
+     * This automatically increases when preload is called with more tracks than the current capacity.
+     */
+    get preloadCapacity() {
+        return Math.max(this._autoPreloadCapacity, this._options.preloadCapacity);
+    }
+    validateLoadOptions = (loadOptions) => this.deps.trackFactory.validate(loadOptions);
+    preload(...loadOptionsList) {
+        logDebug(this, `preload ${loadOptionsList.length} items`);
+        loadOptionsList.forEach(this.validateLoadOptions);
+        this._preload(loadOptionsList);
+    }
+    _preload(loadOptionsList) {
+        const prefetched = this.prefetched;
+        // Calculate the required preload capacity as the number of tracks requested that are not within the
+        // prefetch window. If this value is greater than the current preloadCapacity, increase the cache size.
+        const requiredPreloadCapacity = countElements(loadOptionsList, (loadOptions) => {
+            return (prefetched.find((element) => {
+                return element.uri === loadOptions.uri;
+            }) == null);
+        });
+        if (this._autoPreloadCapacity < requiredPreloadCapacity) {
+            this._autoPreloadCapacity = requiredPreloadCapacity;
+            this.checkCacheCapacity();
+        }
+        // Tracks requested to preload will have a priority where the first track in the list (next track) has
+        // the highest precedence. (Higher priority values take precedence)
+        trackPriority.value += loadOptionsList.length;
+        let priority = trackPriority.value;
+        for (const loadOptions of loadOptionsList) {
+            const track = this.getOrCreateTrack(loadOptions.uri, loadOptions);
+            track.preload({
+                prefetchPriority: priority--,
+            }, loadOptions.config ?? {});
+        }
+    }
+    load(...loadOptionsList) {
+        logDebug(this, `load ${loadOptionsList.length} items`);
+        loadOptionsList.forEach(this.validateLoadOptions);
+        this.clearTrackEndedTimeout();
+        this._current = loadOptionsList[0] ?? null;
+        const previousQueue = this._queue;
+        this._queue = loadOptionsList.slice(1);
+        this._preload(this.prefetched);
+        this.activateCurrent();
+        this.dispatch('queueChange', {
+            previous: previousQueue,
+            current: this._queue,
+        });
+    }
+    unload() {
+        this.load();
+    }
+    enqueue(...loadOptionsList) {
+        logDebug(this, `enqueue ${loadOptionsList.length} items`);
+        loadOptionsList.forEach(this.validateLoadOptions);
+        const previousQueue = this._queue;
+        this._queue = this._queue.concat(loadOptionsList);
+        this._preload(this.prefetched);
+        if (this.currentTrack == null && this.hasNext())
+            this.next();
+        this.dispatch('queueChange', {
+            previous: previousQueue,
+            current: this._queue,
+        });
+    }
+    hasNext() {
+        return this._queue.length > 0;
+    }
+    next() {
+        this.clearTrackEndedTimeout();
+        const playbackController = this.deps.playbackController;
+        const shouldPlay = playbackController.ended || !playbackController.paused;
+        const next = first(this._queue);
+        const previousQueue = this._queue;
+        this._queue = this._queue.slice(1);
+        this._current = next ?? null;
+        logDebug(this, 'next, nextTrack:', this._current);
+        if (this.options.trackPrefetchCount > 0 &&
+            this._queue.length >= this.options.trackPrefetchCount) {
+            this._preload([this._queue[this.options.trackPrefetchCount - 1]]);
+        }
+        this.activateCurrent();
+        if (shouldPlay)
+            void playbackController.play().catch(noop);
+        this.dispatch('queueChange', {
+            previous: previousQueue,
+            current: this._queue,
+        });
+    }
+    clearTrackCache() {
+        logDebug(this, 'clearTrackCache');
+        this.clearTrackEndedTimeout();
+        const previousQueue = this._queue;
+        this._queue = [];
+        this.trackCache.forEach((track) => {
+            track.dispose();
+        });
+        this.trackCache.clear();
+        this._autoPreloadCapacity = 0;
+        this.checkCacheCapacity();
+        this.clearCurrentTrack();
+        this.dispatch('queueChange', {
+            previous: previousQueue,
+            current: this._queue,
+        });
+    }
+    clearPrefetch() {
+        for (const cachedTrack of this.trackCache.values()) {
+            cachedTrack.clearPrefetch();
+        }
+    }
+    clearQueue() {
+        this.clearTrackEndedTimeout();
+        const previous = this._queue;
+        this._queue = [];
+        this.dispatch('queueChange', {
+            previous,
+            current: this._queue,
+        });
+    }
+    /**
+     * If the given track id is the current track or in the cache, returns that track.
+     * Otherwise, constructs a new track, adds it to the cache, and returns it.
+     *
+     * @param uri The unique resource identifier.
+     * @param loadOptions
+     * @private
+     */
+    getOrCreateTrack(uri, loadOptions) {
+        return getOrSet(this.trackCache, uri, () => {
+            const newTrack = this.deps.trackFactory.createTrack(loadOptions);
+            this.trackCache.set(uri, newTrack);
+            return newTrack;
+        });
+    }
+    /**
+     * Get the current track from cache or create a new track, then activates that track.
+     */
+    activateCurrent() {
+        const loadOptions = this._current;
+        if (!loadOptions) {
+            this.clearCurrentTrack();
+            return;
+        }
+        this.setCurrentTrack(this.getOrCreateTrack(loadOptions.uri, loadOptions), loadOptions);
+    }
+    _currentTrack = null;
+    get currentTrack() {
+        return this._currentTrack;
+    }
+    /**
+     * Sets the current track. If the given track is already current, it will be de-activated and re-activated and
+     * the currentTrackChange event will still be emitted.
+     * The same track may be in the queue multiple times.
+     */
+    setCurrentTrack(value, loadOptions) {
+        const previousTrack = this._currentTrack;
+        this.dispatch('currentTrackChanging', {
+            previous: previousTrack,
+            current: value,
+        });
+        this._currentTrack = value;
+        if (previousTrack?.active === true)
+            previousTrack.deactivate();
+        const loadOptionsConfig = loadOptions?.config ?? {};
+        if (value?.active === false)
+            value.activate(loadOptionsConfig);
+        logDebug(this, `currentTrackChange, previous: ${previousTrack} current: ${value}`);
+        this.dispatch('currentTrackChange', {
+            previous: previousTrack,
+            current: value,
+        });
+    }
+    clearCurrentTrack() {
+        this.setCurrentTrack(null, null);
+    }
+    reset() {
+        this._currentTrack?.reset();
+    }
+    dispose() {
+        logDebug(this, 'dispose');
+        super.dispose();
+        this.clearTrackCache();
+        this.disposer.dispose();
+    }
+}

package/dist/types/current/track/TrackFactory.d.ts

@@ -0,0 +1,50 @@
+import type { AnyRecord, Maybe, ReadonlyRecord } from '@amazon/vinyl-util';
+import type { ObjectSchema } from '@amazon/vinyl-validation';
+import type { Track, TrackTypeId, TrackUri } from '../track/Track';
+export interface TrackLoadOptions {
+    /**
+     * The track type, used to map to a track factory.
+     */
+    readonly type: TrackTypeId;
+    /**
+     * The track identifier.
+     */
+    readonly uri: TrackUri;
+    /**
+     * The track configuration.
+     */
+    readonly config?: Maybe<AnyRecord>;
+}
+export declare const trackLoadOptionsValidator: ObjectSchema<TrackLoadOptions>;
+/**
+ * Produces a new Track for the given configuration options.
+ */
+export interface TrackFactory<TrackLoadOptionsType extends TrackLoadOptions> {
+    /**
+     * Throws a validation error if the track options are invalid.
+     */
+    validate(options: TrackLoadOptionsType): void;
+    /**
+     * Constructs a new track from the provided load options.
+     */
+    createTrack(options: TrackLoadOptionsType): Track;
+}
+export type InferLoadOptionsFromFactory<T extends TrackFactory<any>> = T extends TrackFactory<infer LoadOptions> ? LoadOptions : never;
+export type CombinedTrackFactoryOptions<T extends ReadonlyRecord<TrackTypeId, TrackFactory<TrackLoadOptions>>> = InferLoadOptionsFromFactory<T[keyof T]>;
+export type TrackFactoryRecord = ReadonlyRecord<TrackTypeId, TrackFactory<TrackLoadOptions>>;
+/**
+ * Validates that the keys of the track factory record match the track type
+ * for the track factory.
+ */
+export type ValidTrackFactoryRecord<T extends TrackFactoryRecord> = {
+    readonly [K in keyof T]: K extends InferLoadOptionsFromFactory<T[K]>['type'] ? T[K] : never;
+};
+/**
+ * Given a map of TrackTypeId => TrackFactory, returns a track factory
+ * that supports any of the provided track types.
+ * The factory will be mapped by the track load options `type` property.
+ *
+ * @param factories
+ */
+export declare function createTrackFactory<T extends TrackFactoryRecord>(factories: ValidTrackFactoryRecord<T>): TrackFactory<CombinedTrackFactoryOptions<T>>;
+//# sourceMappingURL=TrackFactory.d.ts.map

package/dist/types/current/track/TrackFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TrackFactory.d.ts","sourceRoot":"","sources":["../../../../src/track/TrackFactory.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAE1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAQ5D,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAEjE,MAAM,WAAW,gBAAgB;IAC7B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAE1B;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAA;IAEtB;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAA;CACrC;AAED,eAAO,MAAM,yBAAyB,EAAE,YAAY,CAAC,gBAAgB,CAMpE,CAAA;AAED;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,oBAAoB,SAAS,gBAAgB;IACvE;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAAA;IAE7C;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,oBAAoB,GAAG,KAAK,CAAA;CACpD;AAED,MAAM,MAAM,2BAA2B,CAAC,CAAC,SAAS,YAAY,CAAC,GAAG,CAAC,IAC/D,CAAC,SAAS,YAAY,CAAC,MAAM,WAAW,CAAC,GAAG,WAAW,GAAG,KAAK,CAAA;AAEnE,MAAM,MAAM,2BAA2B,CACnC,CAAC,SAAS,cAAc,CAAC,WAAW,EAAE,YAAY,CAAC,gBAAgB,CAAC,CAAC,IACrE,2BAA2B,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;AAE3C,MAAM,MAAM,kBAAkB,GAAG,cAAc,CAC3C,WAAW,EACX,YAAY,CAAC,gBAAgB,CAAC,CACjC,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,uBAAuB,CAAC,CAAC,SAAS,kBAAkB,IAAI;IAChE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,SAAS,2BAA2B,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GACtE,CAAC,CAAC,CAAC,CAAC,GACJ,KAAK;CACd,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,kBAAkB,EAC3D,SAAS,EAAE,uBAAuB,CAAC,CAAC,CAAC,GACtC,YAAY,CAAC,2BAA2B,CAAC,CAAC,CAAC,CAAC,CAa9C"}

package/dist/types/current/track/TrackFactory.js

@@ -0,0 +1,31 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ErrorOrigin, ownKeys } from '@amazon/vinyl-util';
+import { isOneOf, object, string, } from '@amazon/vinyl-validation';
+export const trackLoadOptionsValidator = object({
+    type: string(),
+    uri: string().notEmpty(),
+    config: object({}).maybe().optional(),
+});
+/**
+ * Given a map of TrackTypeId => TrackFactory, returns a track factory
+ * that supports any of the provided track types.
+ * The factory will be mapped by the track load options `type` property.
+ *
+ * @param factories
+ */
+export function createTrackFactory(factories) {
+    // Validates that the track type attempting to be created exists in the factory map.
+    const typeValidator = isOneOf(...ownKeys(factories));
+    return {
+        validate(options) {
+            typeValidator.assert(options.type, ErrorOrigin.API);
+            factories[options.type].validate(options);
+        },
+        createTrack(options) {
+            return factories[options.type].createTrack(options);
+        },
+    };
+}

package/dist/types/current/track/createSegmentDataProvider.d.ts

@@ -0,0 +1,18 @@
+import type { Maybe, RequestInitOptions, RequestInterceptor } from '@amazon/vinyl-util';
+import { type ByteRange } from '@amazon/vinyl-mpd-parser';
+import type { SegmentDataProvider } from '../streaming/SegmentDataSlot';
+export interface CreateSegmentDataProviderDeps {
+    readonly requestInterceptor: RequestInterceptor;
+    readonly segmentRequestInit: Maybe<RequestInitOptions>;
+}
+export interface CreateSegmentDataProviderOptions {
+    readonly url: string;
+    readonly mediaRange?: Maybe<ByteRange>;
+    readonly serviceId?: Maybe<string>;
+    /**
+     * If true, reports downlink transfer speeds to network metrics.
+     */
+    readonly reportDownlinkMetrics: boolean;
+}
+export declare function createSegmentDataProvider(deps: CreateSegmentDataProviderDeps, options: CreateSegmentDataProviderOptions): SegmentDataProvider;
+//# sourceMappingURL=createSegmentDataProvider.d.ts.map

package/dist/types/current/track/createSegmentDataProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createSegmentDataProvider.d.ts","sourceRoot":"","sources":["../../../../src/track/createSegmentDataProvider.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACR,KAAK,EAIL,kBAAkB,EAClB,kBAAkB,EAErB,MAAM,oBAAoB,CAAA;AAQ3B,OAAO,EAAE,KAAK,SAAS,EAAsB,MAAM,0BAA0B,CAAA;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AAEtE,MAAM,WAAW,6BAA6B;IAC1C,QAAQ,CAAC,kBAAkB,EAAE,kBAAkB,CAAA;IAC/C,QAAQ,CAAC,kBAAkB,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAA;CACzD;AAED,MAAM,WAAW,gCAAgC;IAC7C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAA;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;IAClC;;OAEG;IACH,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAA;CAC1C;AAED,wBAAgB,yBAAyB,CACrC,IAAI,EAAE,6BAA6B,EACnC,OAAO,EAAE,gCAAgC,GAC1C,mBAAmB,CAyDrB"}