@amazon/vinyl 1.0.0

package/dist/types/current/streaming/ContentTypesValue.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/types/current/streaming/DescriptorRecord.d.ts

@@ -0,0 +1,31 @@
+import { type ObjectSchema, type RecordSchema } from '@amazon/vinyl-validation';
+import { type Maybe, type ReadonlyRecord } from '@amazon/vinyl-util';
+import { type Uri } from '@amazon/vinyl-xml';
+/**
+ * A map of scheme URIs to a descriptor list.
+ */
+export type DescriptorRecord = ReadonlyRecord<Uri, readonly Descriptor[] | undefined>;
+/**
+ * A generic descriptor providing extended information.
+ */
+export interface Descriptor {
+    /**
+     * An optional unique identifier for the descriptor.
+     */
+    readonly id?: Maybe<string>;
+    /**
+     * An optional value associated with the descriptor, whose interpretation depends on the scheme.
+     */
+    readonly value?: Maybe<string>;
+}
+/**
+ * Gets The first matching descriptor value from a record with a matching URI and optional id.
+ *
+ * @param record The descriptor record.
+ * @param uri The URI key.
+ * @param id An optional id. If provided the descriptor must have a matching id.
+ */
+export declare function getDescriptorValue(record: DescriptorRecord, uri: Uri, id?: Maybe<string>): string | null;
+export declare const descriptorValidator: ObjectSchema<Descriptor>;
+export declare const descriptorRecordValidator: RecordSchema<DescriptorRecord>;
+//# sourceMappingURL=DescriptorRecord.d.ts.map

package/dist/types/current/streaming/DescriptorRecord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DescriptorRecord.d.ts","sourceRoot":"","sources":["../../../../src/streaming/DescriptorRecord.ts"],"names":[],"mappings":"AAKA,OAAO,EAGH,KAAK,YAAY,EAEjB,KAAK,YAAY,EAEpB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAS,KAAK,KAAK,EAAE,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAC3E,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,mBAAmB,CAAA;AAE5C;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,cAAc,CACzC,GAAG,EACH,SAAS,UAAU,EAAE,GAAG,SAAS,CACpC,CAAA;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACvB;;OAEG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;IAE3B;;OAEG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAC9B,MAAM,EAAE,gBAAgB,EACxB,GAAG,EAAE,GAAG,EACR,EAAE,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,GACnB,MAAM,GAAG,IAAI,CAKf;AAED,eAAO,MAAM,mBAAmB,EAAE,YAAY,CAAC,UAAU,CAGvD,CAAA;AAEF,eAAO,MAAM,yBAAyB,EAAE,YAAY,CAAC,gBAAgB,CAGL,CAAA"}

package/dist/types/current/streaming/DescriptorRecord.js

@@ -0,0 +1,26 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { array, object, record, string, } from '@amazon/vinyl-validation';
+import { first } from '@amazon/vinyl-util';
+/**
+ * Gets The first matching descriptor value from a record with a matching URI and optional id.
+ *
+ * @param record The descriptor record.
+ * @param uri The URI key.
+ * @param id An optional id. If provided the descriptor must have a matching id.
+ */
+export function getDescriptorValue(record, uri, id) {
+    let arr = record[uri];
+    if (!arr)
+        return null;
+    if (id !== undefined)
+        arr = arr.filter((descriptor) => descriptor.id === id);
+    return first(arr)?.value ?? null;
+}
+export const descriptorValidator = object({
+    id: string().maybe().optional(),
+    value: string().maybe().optional(),
+});
+export const descriptorRecordValidator = record(string(), array(descriptorValidator).readonly().orUndefined());

package/dist/types/current/streaming/DrmInitDataType.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Initialization data formats for EME.
+ * https://www.w3.org/TR/eme-initdata-registry/
+ */
+export type DrmInitDataType = 'cenc' | 'keyids' | 'webm' | string;
+//# sourceMappingURL=DrmInitDataType.d.ts.map

package/dist/types/current/streaming/DrmInitDataType.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DrmInitDataType.d.ts","sourceRoot":"","sources":["../../../../src/streaming/DrmInitDataType.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAA"}

package/dist/types/current/streaming/DrmInitDataType.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/types/current/streaming/ManifestController.d.ts

@@ -0,0 +1,13 @@
+import type { ObservableValue } from '@amazon/vinyl-observable';
+export interface ManifestController<T> extends ObservableValue<T> {
+    /**
+     * Manually triggers a reload of the manifest.
+     * A manifest reload will not clear currently fetched or buffered segments.
+     */
+    refresh(): void;
+    /**
+     * If the manifest promise has rejected, refresh.
+     */
+    reset(): void;
+}
+//# sourceMappingURL=ManifestController.d.ts.map

package/dist/types/current/streaming/ManifestController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ManifestController.d.ts","sourceRoot":"","sources":["../../../../src/streaming/ManifestController.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAE/D,MAAM,WAAW,kBAAkB,CAAC,CAAC,CAAE,SAAQ,eAAe,CAAC,CAAC,CAAC;IAC7D;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAA;IAEf;;OAEG;IACH,KAAK,IAAI,IAAI,CAAA;CAChB"}

package/dist/types/current/streaming/ManifestController.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/types/current/streaming/MediaQualityMetadata.d.ts

@@ -0,0 +1,141 @@
+import { type Maybe, type MutableDeep } from '@amazon/vinyl-util';
+import type { ObjectSchema } from '@amazon/vinyl-validation';
+import { type DescriptorRecord } from '../streaming/DescriptorRecord';
+import type { DrmInitDataType } from '../streaming/DrmInitDataType';
+import type { CencEncryptionScheme } from '../drm/CencEncryptionScheme';
+import { DrmKeySystem } from '../drm/DrmKeySystem';
+import type { FrameRate } from '@amazon/vinyl-mpd-parser';
+export type ContentType = 'audio' | 'video' | 'text';
+export declare const ALL_CONTENT_TYPES: ["video", "audio", "text"];
+/**
+ * Contains media formatting and encryption metadata.
+ */
+export interface MediaFormatMetadata {
+    /**
+     * The content type of the representation, e.g. 'audio', 'video', 'text'
+     * Must be non-null for segmented media.
+     */
+    readonly contentType: ContentType | null;
+    /**
+     * The full MIME type of the media.
+     *
+     * Must be non-null for segmented media.
+     */
+    readonly mimeType: string | null;
+    /**
+     * The initialization data format.
+     */
+    readonly initDataType: DrmInitDataType | null;
+    /**
+     * The method of encryption, or null.
+     */
+    readonly encryptionScheme: CencEncryptionScheme | null;
+    /**
+     * Protection schemes used in this media.
+     */
+    readonly contentProtections: readonly DrmProtection[];
+}
+/**
+ * Protection information for a key system.
+ * Media may have more than one protection system.
+ */
+export interface DrmProtection {
+    /**
+     * The key system used in the encryption.
+     */
+    readonly keySystem: DrmKeySystem;
+    /**
+     * The initialization key, in base 64.
+     */
+    readonly pssh?: Maybe<string>;
+    /**
+     * PlayReady object.
+     */
+    readonly pro?: Maybe<string>;
+}
+export declare const drmProtectionValidator: ObjectSchema<DrmProtection>;
+export declare const mediaFormatMetadataValidator: ObjectSchema<MediaFormatMetadata>;
+/**
+ * Metadata representing attributes of a media representation.
+ */
+export interface MediaQualityMetadata extends MediaFormatMetadata {
+    /**
+     * Provides a decoding identifier. If this value changes from the previously buffered
+     * segment, the initialization segment must be buffered before appending the media segment.
+     * Unique to the track.
+     */
+    readonly decoderId: string;
+    /**
+     * The quality id identifies the quality representation.
+     * Unique to the track.
+     */
+    readonly qualityId: string;
+    /**
+     * Optional string specifying the codec(s) used for this representation. The format follows the RFC 6381 codec
+     * string format.
+     */
+    readonly codecs: string | null;
+    /**
+     * The average bandwidth in bits per second required for playing this representation.
+     * For HLS, and non-segmented media this will be null.
+     */
+    readonly bandwidth: number | null;
+    /**
+     * The peak bandwidth in bits per second required for playing this representation
+     * with its cumulative A/V content streams.
+     *
+     * Guaranteed to be set for segmented media.
+     */
+    readonly bandwidthTotal: number | null;
+    /**
+     * Audio sampling rate(s) in samples per second.
+     * An array of either one or two decimal integer values. If there are two elements this represents a minimum and
+     * maximum sampling rate of the audio media.
+     */
+    readonly audioSamplingRate: readonly number[] | null;
+    /**
+     * Frame rate for video representations, specified either as a ratio of integers, e.g. [30000, 1001]
+     */
+    readonly frameRate: FrameRate | null;
+    /**
+     * For video representations, the width of the video in pixels.
+     */
+    readonly width: number | null;
+    /**
+     * For video representations, the height of the video in pixels.
+     */
+    readonly height: number | null;
+    /**
+     * Information that may enhance playback or presentation.
+     */
+    readonly supplementalProperties: DescriptorRecord;
+    /**
+     * Specifies the language of the content, using a code as defined by RFC 5646.
+     */
+    readonly lang: string | null;
+    /**
+     * Identifies the group this quality belongs to (e.g. the adaptation set).
+     */
+    readonly groupId: string;
+    /**
+     * The group IDs that this quality is permitted to switch to during playback.
+     * Derived from the DASH `urn:mpeg:dash:adaptation-set-switching:2016` supplemental property.
+     * Includes the quality's own groupId.
+     * Null means no switching constraint (all groups are permitted).
+     * An array restricts switching to only the listed group IDs.
+     * Default behavior:
+     * - DASH: restricted to own group unless adaptation-set-switching property is present.
+     * - HLS: restricted to variants with the same base codec and language.
+     */
+    readonly switchingGroupIds: readonly string[] | null;
+}
+/**
+ * Creates a new, empty media format metadata object.
+ */
+export declare function createEmptyMediaFormatMetadata(): MutableDeep<MediaFormatMetadata>;
+/**
+ * Creates a new empty media quality metadata object.
+ */
+export declare function createEmptyMediaQualityMetadata(): MutableDeep<MediaQualityMetadata>;
+export declare const mediaQualityMetadataValidator: ObjectSchema<MediaQualityMetadata>;
+//# sourceMappingURL=MediaQualityMetadata.d.ts.map

package/dist/types/current/streaming/MediaQualityMetadata.d.ts.map

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

package/dist/types/current/streaming/MediaQualityMetadata.js

@@ -0,0 +1,73 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { createShortUid, } from '@amazon/vinyl-util';
+import { array, enumOf, isOneOf, number, object, string, tuple, } from '@amazon/vinyl-validation';
+import { descriptorRecordValidator, descriptorValidator, } from '../streaming/DescriptorRecord';
+import { DrmKeySystem } from '../drm/DrmKeySystem';
+export const ALL_CONTENT_TYPES = [
+    'video',
+    'audio',
+    'text',
+];
+export const drmProtectionValidator = descriptorValidator.extend({
+    keySystem: enumOf(DrmKeySystem),
+    pro: string().maybe().optional(),
+    pssh: string().maybe().optional(),
+});
+export const mediaFormatMetadataValidator = object({
+    contentProtections: array(drmProtectionValidator).readonly(),
+    contentType: isOneOf('audio', 'video', 'text').orNull(),
+    initDataType: string().orNull(),
+    encryptionScheme: string().orNull(),
+    mimeType: string().orNull(),
+});
+/**
+ * Creates a new, empty media format metadata object.
+ */
+export function createEmptyMediaFormatMetadata() {
+    return {
+        contentType: null,
+        mimeType: null,
+        initDataType: null,
+        encryptionScheme: null,
+        contentProtections: [],
+    };
+}
+/**
+ * Creates a new empty media quality metadata object.
+ */
+export function createEmptyMediaQualityMetadata() {
+    return {
+        ...createEmptyMediaFormatMetadata(),
+        decoderId: createShortUid(),
+        qualityId: createShortUid(),
+        codecs: null,
+        bandwidth: null,
+        bandwidthTotal: null,
+        supplementalProperties: {},
+        audioSamplingRate: null,
+        frameRate: null,
+        height: null,
+        width: null,
+        lang: null,
+        groupId: createShortUid(),
+        switchingGroupIds: null,
+    };
+}
+export const mediaQualityMetadataValidator = mediaFormatMetadataValidator.extend({
+    audioSamplingRate: array(number()).readonly().orNull(),
+    bandwidth: number().orNull(),
+    bandwidthTotal: number().orNull(),
+    codecs: string().orNull(),
+    decoderId: string(),
+    frameRate: tuple(number(), number()).readonly().orNull(),
+    height: number().orNull(),
+    qualityId: string(),
+    supplementalProperties: descriptorRecordValidator,
+    width: number().orNull(),
+    lang: string().orNull(),
+    groupId: string(),
+    switchingGroupIds: array(string()).readonly().orNull(),
+});

package/dist/types/current/streaming/MediaTimeline.d.ts

@@ -0,0 +1,45 @@
+import type { SegmentReference } from '../streaming/SegmentReference';
+import type { SegmentDataProvider } from '../streaming/SegmentDataSlot';
+import type { MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
+/**
+ * Represents a single quality within a period, providing access to its metadata
+ * and segment data.
+ */
+export interface MediaQualityData {
+    readonly metadata: MediaQualityMetadata;
+    /**
+     * Gets the segment reference at the given time, or null if the time is outside the range.
+     * @param time The time, in seconds, relative to the presentation timeline.
+     * @param affordance Forward-snap tolerance in seconds: if `time` falls just before a
+     * segment's start (within `affordance`), that segment is returned. Defaults to `0`.
+     */
+    getSegment(time: number, affordance?: number): Promise<SegmentReference<SegmentDataProvider> | null>;
+}
+/**
+ * Represents a period within the media timeline.
+ */
+export interface MediaPeriod {
+    readonly startTime: number;
+    readonly endTime: number;
+    readonly qualities: readonly MediaQualityData[];
+}
+/**
+ * Represents the full media timeline, composed of one or more periods.
+ */
+export interface MediaTimeline {
+    readonly periods: readonly MediaPeriod[];
+    /**
+     * The minimum duration of the buffer that a client should maintain for uninterrupted playback.
+     */
+    readonly minBufferTime: number;
+    /**
+     * The total duration of the media, in seconds.
+     * Returns null if duration cannot be determined.
+     */
+    getDuration?(): Promise<number | null>;
+}
+/**
+ * Gets the period spanning the given presentation time.
+ */
+export declare function getMediaPeriodAtTime(timeline: MediaTimeline, time: number): MediaPeriod | null;
+//# sourceMappingURL=MediaTimeline.d.ts.map

package/dist/types/current/streaming/MediaTimeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MediaTimeline.d.ts","sourceRoot":"","sources":["../../../../src/streaming/MediaTimeline.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AACpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACtE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAG5E;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAA;IAEvC;;;;;OAKG;IACH,UAAU,CACN,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,gBAAgB,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAAC,CAAA;CAC3D;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAA;CAClD;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAA;IAExC;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAE9B;;;OAGG;IACH,WAAW,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CACzC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAChC,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,MAAM,GACb,WAAW,GAAG,IAAI,CAQpB"}

package/dist/types/current/streaming/MediaTimeline.js

@@ -0,0 +1,17 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { sortedInsertionIndex } from '@amazon/vinyl-util';
+/**
+ * Gets the period spanning the given presentation time.
+ */
+export function getMediaPeriodAtTime(timeline, time) {
+    const index = sortedInsertionIndex(timeline.periods, time, (time, period) => {
+        return time - period.startTime;
+    }) - 1;
+    if (index < 0)
+        return null;
+    const period = timeline.periods[index];
+    return time >= period.endTime ? null : period;
+}

package/dist/types/current/streaming/SegmentController.d.ts

@@ -0,0 +1,117 @@
+import type { AnyRecord, Disposable, ReadonlyAbort, ReadonlyEventHost, ReadonlyRanges } from '@amazon/vinyl-util';
+import type { SegmentReference } from '../streaming/SegmentReference';
+import type { ChangeEvent } from '../event/ChangeEvent';
+import type { MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
+/**
+ * Forward-snap tolerance, in seconds, applied when looking up a segment by time.
+ *
+ * If the requested time falls within this window before a segment's `startTime`,
+ * that segment is returned rather than treating the gap as uncovered. This absorbs
+ * small alignment differences between qualities, where one quality's segment may
+ * begin a few milliseconds later than another's at the same logical boundary.
+ *
+ * Pass to `getSegmentAtTime` (and `MediaQualityData.getSegment`) as the `affordance`
+ * argument. Callers resuming streaming after a seek should also bias the requested
+ * time *behind* the playhead by at least this amount, so any subsequent appends
+ * cover the playhead without leaving a gap. The `SegmentController` clamps negative
+ * request times to `0`, so callers don't need to guard against the bias going below
+ * the start of the timeline.
+ */
+export declare const SEGMENT_START_AFFORDANCE = 0.2;
+export interface SegmentControllerEventMap {
+    /**
+     * fetchedRanges have been updated.
+     */
+    readonly fetchedRangesChange: AnyRecord;
+    /**
+     * Emitted when the timeline has changed.
+     */
+    readonly change: AnyRecord;
+    /**
+     * Dispatched when the current streaming quality changes.
+     * This is dispatched when a new quality is requested.
+     */
+    readonly streamingQualityChange: ChangeEvent<MediaQualityMetadata | null>;
+}
+/**
+ * The SegmentController provides segments to buffer for the given time.
+ * It is expected to prefetch segments based on the expectation of when the segments will be
+ * needed next.
+ */
+export interface ReadonlySegmentController extends ReadonlyEventHost<SegmentControllerEventMap> {
+    readonly error: Error | null;
+    /**
+     * The time ranges currently fetched.
+     */
+    readonly fetchedRanges: ReadonlyRanges;
+    /**
+     * The most recently requested quality metadata.
+     */
+    readonly streamingQuality: MediaQualityMetadata | null;
+    /**
+     * The duration of the media, in seconds.
+     * Returns null if duration cannot be determined.
+     */
+    getDuration(): Promise<number | null>;
+    /**
+     * Returns a Promise for a segment covering the given time, with quality chosen by
+     * the configured `QualitySelector`. Resolves to `null` if no media exists at that
+     * time. Negative `time` values are clamped to `0`.
+     *
+     * The lookup forward-snaps by `SEGMENT_START_AFFORDANCE`: if `time` falls within
+     * that window before a segment's `startTime`, that segment is returned. This
+     * absorbs sub-second segment-boundary differences across qualities so an ABR
+     * switch doesn't replay or skip media at the boundary.
+     *
+     * Calling this also blocks the prefetch queue until the returned promise settles,
+     * so the active request is prioritized over background prefetching.
+     *
+     * @param time The time, in seconds, the requested segment should span.
+     * @param abort Aborts the returned promise (rejecting with `AbortError`) and
+     * releases the prefetch-queue lock. The underlying network request may continue
+     * so its result can still populate the cache.
+     */
+    getSegment(time: number, abort?: ReadonlyAbort): Promise<SegmentReference<ArrayBuffer> | null>;
+}
+/**
+ * Configuration the track is expected to provide to the SegmentController.
+ */
+export interface PrefetchOptions {
+    /**
+     * The prefetching priority of the track. Higher numbers take precedence.
+     */
+    readonly trackPrefetchPriority: number;
+    /**
+     * When the track is inactive, the starting time to prefetch from.
+     */
+    readonly startTime: number;
+}
+/**
+ * Provides segments for a given time.
+ * Handles segment prefetching and caching.
+ */
+export interface SegmentController extends ReadonlySegmentController, Disposable {
+    /**
+     * Configures this segment provider.
+     */
+    configure(options: Partial<PrefetchOptions>): void;
+    /**
+     * Clears the cached segments.
+     * Currently pending segment promises will be rejected with an abort reason.
+     */
+    clear(): void;
+    /**
+     * Indicates that this segment provider is providing segments for an active track and should be prioritized
+     * accordingly.
+     */
+    activate(): void;
+    /**
+     * Indicates that this segment provider is providing segments for an inactive track.
+     */
+    deactivate(): void;
+    /**
+     * Resets failed segments to a pending state.
+     */
+    reset(): void;
+}
+//# sourceMappingURL=SegmentController.d.ts.map

package/dist/types/current/streaming/SegmentController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SegmentController.d.ts","sourceRoot":"","sources":["../../../../src/streaming/SegmentController.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACR,SAAS,EACT,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,cAAc,EACjB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAE5E;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAA;AAE3C,MAAM,WAAW,yBAAyB;IACtC;;OAEG;IACH,QAAQ,CAAC,mBAAmB,EAAE,SAAS,CAAA;IAEvC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;IAE1B;;;OAGG;IACH,QAAQ,CAAC,sBAAsB,EAAE,WAAW,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAA;CAC5E;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAA0B,SAAQ,iBAAiB,CAAC,yBAAyB,CAAC;IAC3F,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IAE5B;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,cAAc,CAAA;IAEtC;;OAEG;IACH,QAAQ,CAAC,gBAAgB,EAAE,oBAAoB,GAAG,IAAI,CAAA;IAEtD;;;OAGG;IACH,WAAW,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAErC;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CACN,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,gBAAgB,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC,CAAA;CACnD;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B;;OAEG;IACH,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAA;IAEtC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,iBACb,SAAQ,yBAAyB,EAAE,UAAU;IAC7C;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAAA;IAElD;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAA;IAEb;;;OAGG;IACH,QAAQ,IAAI,IAAI,CAAA;IAEhB;;OAEG;IACH,UAAU,IAAI,IAAI,CAAA;IAElB;;OAEG;IACH,KAAK,IAAI,IAAI,CAAA;CAChB"}

package/dist/types/current/streaming/SegmentController.js

@@ -0,0 +1,20 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Forward-snap tolerance, in seconds, applied when looking up a segment by time.
+ *
+ * If the requested time falls within this window before a segment's `startTime`,
+ * that segment is returned rather than treating the gap as uncovered. This absorbs
+ * small alignment differences between qualities, where one quality's segment may
+ * begin a few milliseconds later than another's at the same logical boundary.
+ *
+ * Pass to `getSegmentAtTime` (and `MediaQualityData.getSegment`) as the `affordance`
+ * argument. Callers resuming streaming after a seek should also bias the requested
+ * time *behind* the playhead by at least this amount, so any subsequent appends
+ * cover the playhead without leaving a gap. The `SegmentController` clamps negative
+ * request times to `0`, so callers don't need to guard against the bias going below
+ * the start of the timeline.
+ */
+export const SEGMENT_START_AFFORDANCE = 0.2;