@amazon/vinyl 1.2.0 → 2.0.4

package/dist/types/ts3.7/streaming/MediaQualityMetadata.d.ts

@@ -11,6 +11,17 @@ export declare const ALL_CONTENT_TYPES: [
     "audio",
     "text"
 ];
+/**
+ * The content types that can be restricted via an allow list (see
+ * `VinylOptions.allowedContentTypes`). Text is intentionally excluded: text
+ * tracks (subtitles / closed captions) are governed by caption selection, not
+ * by the content-type allow list, so they always remain available.
+ */
+export type RestrictableContentType = Exclude<ContentType, 'text'>;
+export declare const RESTRICTABLE_CONTENT_TYPES: [
+    "video",
+    "audio"
+];
 /**
  * Contains media formatting and encryption metadata.
  */
@@ -117,6 +128,14 @@ export interface MediaQualityMetadata extends MediaFormatMetadata {
      * Specifies the language of the content, using a code as defined by RFC 5646.
      */
     readonly lang: string | null;
+    /**
+     * Media characteristics / accessibility roles describing this rendition,
+     * e.g. `public.accessibility.describes-video` (HLS CHARACTERISTICS) or a
+     * DASH Role / Accessibility scheme value such as `description`. Used to keep
+     * accessibility renditions (e.g. audio description) from being auto-selected
+     * by default. Empty when none are signaled.
+     */
+    readonly characteristics: readonly string[];
     /**
      * Identifies the group this quality belongs to (e.g. the adaptation set).
      */

package/dist/types/ts3.7/streaming/MediaTimeline.d.ts

@@ -1,6 +1,7 @@
 import { SegmentReference } from './SegmentReference';
 import { SegmentDataProvider } from './SegmentDataSlot';
 import { MediaQualityMetadata } from './MediaQualityMetadata';
+import { AdBreakList } from '../ad/AdBreakInfo';
 /**
  * Represents a single quality within a period, providing access to its metadata
  * and segment data.
@@ -32,6 +33,11 @@ export interface MediaTimeline {
      * The minimum duration of the buffer that a client should maintain for uninterrupted playback.
      */
     readonly minBufferTime: number;
+    /**
+     * Ad breaks discovered from the media presentation (e.g. HLS Interstitials,
+     * DASH SCTE-35). Empty when the stream carries no ad signals.
+     */
+    getAdBreaks(): Promise<AdBreakList>;
     /**
      * The total duration of the media, in seconds.
      * Returns `Infinity` for live streams.

package/dist/types/ts3.7/streaming/SegmentController.d.ts

@@ -2,6 +2,7 @@ import { AnyRecord, Disposable, ReadonlyAbort, ReadonlyEventHost, ReadonlyRanges
 import { SegmentReference } from './SegmentReference';
 import { ChangeEvent } from '../event/ChangeEvent';
 import { MediaQualityMetadata } from './MediaQualityMetadata';
+import { LoadSpanMeasurement } from './LoadMetric';
 /**
  * Forward-snap tolerance, in seconds, applied when looking up a segment by time.
  *
@@ -32,6 +33,10 @@ export interface SegmentControllerEventMap {
      * This is dispatched when a new quality is requested.
      */
     readonly streamingQualityChange: ChangeEvent<MediaQualityMetadata | null>;
+    /**
+     * The first init or media segment fetch of this stream completed.
+     */
+    readonly loadSpanMeasured: LoadSpanMeasurement;
 }
 /**
  * The SegmentController provides segments to buffer for the given time.

package/dist/types/ts3.7/streaming/SegmentControllerImpl.d.ts

@@ -44,6 +44,7 @@ export declare class SegmentControllerImpl extends EventHostImpl<SegmentControll
     readonly deps: SegmentControllerImplDeps;
     readonly contentType: ContentType;
     get [Symbol.toStringTag](): string;
+    readonly logPrefix: string;
     private _active;
     get active(): boolean;
     private readonly _fetchedRanges;
@@ -64,6 +65,8 @@ export declare class SegmentControllerImpl extends EventHostImpl<SegmentControll
     private ended;
     private prefetching;
     private _error;
+    private initSpanArmed;
+    private firstSegmentSpanArmed;
     private timeUpdateSub;
     private seekingSub;
     private readonly abort;
@@ -109,6 +112,15 @@ export declare class SegmentControllerImpl extends EventHostImpl<SegmentControll
     private getNextTimeToPrefetch;
     private pollPrefetch;
     private prefetchErrorHandler;
+    /**
+     * Requests init-segment data, measuring the first fetch as a load span.
+     */
+    private requestInitData;
+    /**
+     * Requests media-segment data, measuring the first fetch as a load span.
+     */
+    private requestSegmentData;
+    private measureLoadSpan;
     get fetchedRanges(): ReadonlyRanges;
     get fetchedTime(): number;
     private _streamingQuality;

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

@@ -2,6 +2,8 @@ import { ChangeEvent } from '../event/ChangeEvent';
 import { ContentType, MediaQualityMetadata } from './MediaQualityMetadata';
 import { BasicErrorEvent } from '../event/BasicErrorEvent';
 import { AnyRecord } from '@amazon/vinyl-util';
+import { SeekRange } from '../track/SeekRange';
+import { LoadSpanMeasurement } from './LoadMetric';
 /**
  * Events a track dispatches related to streaming quality and status.
  */
@@ -32,6 +34,10 @@ export interface StreamingEventMap {
      * The last segment has finished appending.
      */
     readonly bufferingEnded: AnyRecord;
+    /**
+     * The buffer went from empty to holding data, or back to empty.
+     */
+    readonly hasDataChange: ChangeEvent<boolean>;
     /**
      * Dispatched when a streaming error occurs.
      */
@@ -48,6 +54,37 @@ export interface StreamingEventMap {
      * The available unfiltered qualities for the current period have changed.
      */
     readonly qualitiesUnfilteredChange: ChangeEvent<readonly MediaQualityMetadata[]>;
+    /**
+     * A codec the browser reported as supported failed to decode on append and
+     * has been denylisted at runtime. The current media should be reloaded so
+     * quality selection can fall back to a codec that decodes. Recoverable:
+     * this is dispatched instead of an `error`, and the player reloads the
+     * track in response.
+     */
+    readonly codecUnsupported: CodecUnsupportedEvent;
+    /**
+     * The seekable range on the media timeline has changed.
+     */
+    readonly seekRangeChange: ChangeEvent<SeekRange | null>;
+    /**
+     * A stage of the track load completed. Rather than redispatch this raw
+     * measurement, the player attributes it to the current track and
+     * republishes it as the `loadSpan` event.
+     */
+    readonly loadSpanMeasured: LoadSpanMeasurement;
+}
+/**
+ * Payload for {@link StreamingEventMap.codecUnsupported}.
+ */
+export interface CodecUnsupportedEvent {
+    /**
+     * The mimeType (including the failing codec) that was denylisted.
+     */
+    readonly mimeType: string;
+    /**
+     * The content type of the stream whose append failed.
+     */
+    readonly contentType: ContentType;
 }
 /**
  * All streaming-related events a track may emit.
@@ -60,9 +97,13 @@ export declare const ALL_STREAMING_EVENTS: readonly [
     "bufferingQualityChange",
     "playbackQualityChange",
     "bufferingEnded",
+    "hasDataChange",
     "error",
     "reset",
     "qualitiesChange",
-    "qualitiesUnfilteredChange"
+    "qualitiesUnfilteredChange",
+    "codecUnsupported",
+    "seekRangeChange",
+    "loadSpanMeasured"
 ];
 //# sourceMappingURL=StreamingEventMap.d.ts.map

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

@@ -66,6 +66,32 @@ export interface QualitySelectorImplOptions {
      * Default: null (no limit).
      */
     readonly maxBandwidth?: Maybe<number>;
+    /**
+     * Maximum video height, in pixels, a quality may have to be selectable.
+     * Mirrors Shaka's `restrictions.maxHeight`.
+     *
+     * Only affects video qualities; audio (and other non-video) qualities are
+     * never restricted by resolution. Qualities with an unknown height (null)
+     * are treated as within the cap.
+     *
+     * Soft cap: if no video quality fits within the resolution limit, the
+     * quality with the smallest bandwidth is selected so video still plays.
+     *
+     * Has no effect when {@link strategy} is {@link AbrStrategy.LOWEST} or
+     * {@link AbrStrategy.HIGHEST}, since those strategies pin the selection
+     * regardless of resolution.
+     *
+     * Default: null (no limit).
+     */
+    readonly maxHeight?: Maybe<number>;
+    /**
+     * Maximum video width, in pixels, a quality may have to be selectable.
+     * Mirrors Shaka's `restrictions.maxWidth`. Behaves like {@link maxHeight}
+     * but constrains the width dimension.
+     *
+     * Default: null (no limit).
+     */
+    readonly maxWidth?: Maybe<number>;
 }
 export declare enum AbrStrategy {
     /**
@@ -97,6 +123,8 @@ export declare const defaultQualitySelectorImplOptions: {
     readonly bandwidthMultiplierHigh: 0.9;
     readonly restrictDecoderChangeOnAudioAbrUp: false;
     readonly maxBandwidth: null;
+    readonly maxHeight: null;
+    readonly maxWidth: null;
 };
 export interface QualitySelectorImplDeps {
     readonly options: ObservableValue<QualitySelectorImplOptions>;

package/dist/types/ts3.7/streaming/buffering/BufferingController.d.ts

@@ -5,6 +5,7 @@ import { ReadonlySegmentController } from '../SegmentController';
 import { BasicErrorEvent } from '../../event/BasicErrorEvent';
 import { ChangeEvent } from '../../event/ChangeEvent';
 import { ContentType, MediaQualityMetadata } from '../MediaQualityMetadata';
+import { CodecUnsupportedEvent } from '../StreamingEventMap';
 import { MediaSourceController } from './MediaSourceController';
 /**
  * The interval to throttle polling the buffer.
@@ -43,6 +44,16 @@ export interface BufferingControllerEventMap {
      * The last segment has finished appending.
      */
     readonly bufferingEnded: AnyRecord;
+    /**
+     * The buffer went from empty to holding data, or back to empty.
+     */
+    readonly hasDataChange: ChangeEvent<boolean>;
+    /**
+     * A codec the browser reported as supported failed to decode on append and
+     * has been denylisted. Dispatched instead of `error` so the media can be
+     * reloaded and fall back to a codec that decodes.
+     */
+    readonly codecUnsupported: CodecUnsupportedEvent;
 }
 export interface BufferingController extends ReadonlyEventHost<BufferingControllerEventMap>, Clearable, Disposable {
     /**
@@ -72,6 +83,10 @@ export interface BufferingController extends ReadonlyEventHost<BufferingControll
      * True if the stream has buffered the last segment.
      */
     readonly bufferingEnded: boolean;
+    /**
+     * True while the buffer holds any data (false when empty or cleared).
+     */
+    readonly hasData: boolean;
     /**
      * Begins buffering.
      */
@@ -124,6 +139,7 @@ export declare class BufferingControllerImpl extends EventHostImpl<BufferingCont
     readonly deps: BufferingControllerImplDeps;
     readonly contentType: ContentType;
     get [Symbol.toStringTag](): string;
+    readonly logPrefix: string;
     readonly options: BufferingControllerImplOptions;
     private readonly mediaSourceController;
     private readonly playbackController;
@@ -147,6 +163,7 @@ export declare class BufferingControllerImpl extends EventHostImpl<BufferingCont
     private reopen;
     private _error;
     private _bufferingEnded;
+    private _hasData;
     private readonly queue;
     private disposer;
     private _active;
@@ -207,12 +224,32 @@ export declare class BufferingControllerImpl extends EventHostImpl<BufferingCont
      */
     private get mediaSourceClosed();
     get bufferingEnded(): boolean;
+    get hasData(): boolean;
+    private setHasData;
     private readonly handleError;
+    /**
+     * Attempts to recover from a SourceBuffer decode/append failure caused by a
+     * codec the browser reported as supported but cannot actually decode.
+     *
+     * Denylists the failing quality's codec so subsequent quality selection
+     * avoids it, then clears and retries. Returns true when a fallback was
+     * initiated (the caller should not enter an error state), false otherwise.
+     *
+     * Guards against loops: recovery only proceeds when the codec was newly
+     * denylisted. A repeat failure for an already-denylisted codec (e.g. a
+     * single-codec stream with no alternative) returns false and falls through
+     * to the normal error path, so playback errors out rather than looping.
+     */
+    private tryCodecFallback;
     /**
      * Returns the amount of time buffered at the current media position.
      * @private
      */
     getBufferedTime(): number;
+    /**
+     * Returns true if the playhead has become disconnected from the continuous buffer.
+     */
+    private needsBufferClear;
     /**
      * Cancels any currently buffering fragments and clears the source buffer.
      */

package/dist/types/ts3.7/streaming/buffering/MediaSourceController.d.ts

@@ -60,9 +60,17 @@ export interface MediaSourceController extends ReadonlyMediaSourceController {
      */
     endOfStream(error?: EndOfStreamError): void;
     /**
-     * Creates an Object URL to use as the source for this stream.
+     * Creates the internal media source.
+     * Returns an Object URL to use as the source for this stream.
+     *
+     * Implementation note:
+     * Only the first
+     */
+    activate(): string;
+    /**
+     * Deactivates the controller, disposing underlying resources.
      */
-    createUrl(): string;
+    deactivate(): void;
 }
 export interface MediaSourceControllerImplDeps {
     /**
@@ -82,8 +90,9 @@ export declare class MediaSourceControllerImpl extends EventHostImpl<MediaSource
     private readonly deps;
     get [Symbol.toStringTag](): string;
     private readonly sourceBuffers;
-    private readonly mediaSource;
-    private readonly disposer;
+    private mediaSource;
+    private objectUrl;
+    private activateDisposer;
     private contentTypes;
     private durationSet;
     /**
@@ -92,14 +101,11 @@ export declare class MediaSourceControllerImpl extends EventHostImpl<MediaSource
      */
     private durationToken;
     constructor(deps: MediaSourceControllerImplDeps);
+    get active(): boolean;
+    activate(): string;
+    deactivate(): void;
     private get sourceBufferCount();
     private readonly errorHandler;
-    /**
-     * Subscription to mediaTimelineTransformed; only attached while the media source is open
-     * so the timeline pipeline isn't forced to evaluate before the source has opened.
-     */
-    private timelineSub;
-    private initializeEvents;
     /**
      * Sets the duration on the media source from the current media timeline.
      * Live streams use LIVE_DURATION since not all browsers support +Infinity duration.
@@ -116,7 +122,6 @@ export declare class MediaSourceControllerImpl extends EventHostImpl<MediaSource
      */
     private readonly checkReady;
     endOfStream(error?: EndOfStreamError): void;
-    createUrl(): string;
     get readyToAppend(): boolean;
     dispose(): void;
 }

package/dist/types/ts3.7/streaming/buffering/codecDenylist.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Records every codec in the given mimeType as denylisted. Returns true if any
+ * codec was newly added (i.e. was not already denylisted), false if all codecs
+ * were already present. The return value lets callers bound retry loops: a
+ * repeat failure for an already-denylisted codec should not trigger another
+ * fallback attempt.
+ */
+export declare function denylistCodecsFromMimeType(mimeType: string): boolean;
+/**
+ * Returns true when any codec in the given mimeType has been denylisted.
+ */
+export declare function isMimeTypeDenylisted(mimeType: string): boolean;
+/**
+ * Returns the currently denylisted codec strings (lowercased). Primarily for
+ * diagnostics and testing.
+ */
+export declare function getDenylistedCodecs(): readonly string[];
+/**
+ * Clears the runtime codec denylist. Intended for tests and for re-detecting
+ * support (e.g. after an environment change).
+ */
+export declare function clearCodecDenylist(): void;
+//# sourceMappingURL=codecDenylist.d.ts.map

package/dist/types/ts3.7/streaming/createAllowedContentTypesValue.d.ts

@@ -0,0 +1,30 @@
+import { RestrictableContentType } from './MediaQualityMetadata';
+import { ContentTypesValue } from './ContentTypesValue';
+import { ObservableValue } from '@amazon/vinyl-observable';
+export interface AllowedContentTypesValueDeps {
+    /**
+     * The unfiltered content types present in the manifest.
+     */
+    readonly baseContentTypesValue: ContentTypesValue;
+    /**
+     * The player options. The `allowedContentTypes` allow list restricts which
+     * media content types are streamed; `null` means no restriction.
+     */
+    readonly options: ObservableValue<{
+        readonly allowedContentTypes: readonly RestrictableContentType[] | null;
+    }>;
+}
+/**
+ * Wraps a {@link ContentTypesValue} with the `allowedContentTypes` allow list
+ * from the player options. When the allow list is set, only media content
+ * types (`'audio'`, `'video'`) in the list are emitted; other media streams
+ * are ignored. When it is `null`, the underlying content types pass through
+ * unchanged. Text is never restricted by the allow list and always passes
+ * through (captions are governed by caption selection).
+ *
+ * Because the result is derived from the `allowedContentTypes` option via
+ * {@link combineData}, changing the option re-emits a newly filtered set, which
+ * reloads the track using only the allowed content types.
+ */
+export declare function createAllowedContentTypesValue(deps: AllowedContentTypesValueDeps): ContentTypesValue;
+//# sourceMappingURL=createAllowedContentTypesValue.d.ts.map

package/dist/types/ts3.7/streaming/createDefaultMediaTimelineTransformer.d.ts

@@ -2,12 +2,15 @@ import { ObservableValue } from '@amazon/vinyl-observable';
 import { Capabilities } from '../client/Capabilities';
 import { DrmController } from '../drm/DrmController';
 import { MediaTimeline } from './MediaTimeline';
+import { CodecOverrides } from '../util/media/codecOverrides';
 export interface DefaultMediaTimelineTransformerDeps {
     readonly capabilities: Capabilities;
     readonly drmController: DrmController;
     readonly mediaTimeline: ObservableValue<Promise<MediaTimeline>>;
     readonly options: ObservableValue<{
-        readonly preferredAudioLanguage: string | null;
+        readonly preferredAudioLanguage: string | readonly string[] | null;
+        readonly preferDescriptiveAudio?: boolean;
+        readonly codecOverrides?: CodecOverrides;
     }>;
 }
 /**

package/dist/types/ts3.7/streaming/mediaTimelineAccessibilityFilter.d.ts

@@ -0,0 +1,35 @@
+import { MediaQualityMetadata } from './MediaQualityMetadata';
+import { FilterPredicate } from '@amazon/vinyl-util';
+/**
+ * Thrown if the audio-description filter ever emptied a period's audio. The
+ * filter keeps at least one audio rendition per period by design, so this is a
+ * defensive guard rather than an expected path.
+ */
+export declare function throwNoPlayableAudio(): never;
+/**
+ * Characteristics that mark an audio rendition as an audio description (a.k.a.
+ * described video / DVS) — narration of on-screen action for viewers who cannot
+ * see it. HLS signals this with the `public.accessibility.describes-video`
+ * CHARACTERISTIC; DASH with a `description` Role. Such renditions must not be
+ * chosen as the default audio; they are an accessibility opt-in.
+ */
+export declare const AUDIO_DESCRIPTION_CHARACTERISTICS: readonly string[];
+/**
+ * Whether an audio quality is an audio-description rendition.
+ */
+export declare function isAudioDescription(quality: MediaQualityMetadata): boolean;
+/**
+ * Creates a filter that keeps audio-description renditions out of (or, when
+ * opted in, restricts audio to) the audio selection.
+ *
+ * - `preferDescription: false` (default): drop audio-description renditions
+ *   from each period *when a non-description audio alternative exists*, so the
+ *   main audio is chosen by default instead of the description track. If a
+ *   period has only description audio, it is kept (playback is never stranded).
+ * - `preferDescription: true`: keep only description renditions when the period
+ *   has any; otherwise keep all (again, never strand playback).
+ *
+ * Non-audio qualities are always kept.
+ */
+export declare function createAudioDescriptionFilter(preferDescription: boolean): FilterPredicate<MediaQualityMetadata>;
+//# sourceMappingURL=mediaTimelineAccessibilityFilter.d.ts.map

package/dist/types/ts3.7/streaming/mediaTimelineLanguageFilter.d.ts

@@ -1,14 +1,32 @@
 import { MediaQualityMetadata } from './MediaQualityMetadata';
 import { 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.
+ * Resolves the preferred-language option to an ordered list of BCP 47 tags,
+ * most-preferred first.
  *
- * Qualities not matching the content type or without a language tag are always kept.
+ * - a string becomes a single-element list
+ * - an array is used as-is (already ordered)
+ * - `null` falls back to the platform's `navigator.languages` order — `null`
+ *   means "use the platform preference", not "no preference"
+ * - an empty list (empty array, or `navigator.languages` unavailable) means no
+ *   preference: keep all languages
+ */
+export declare function resolvePreferredLanguages(preferred: string | readonly string[] | null): readonly string[];
+/**
+ * Creates a filter predicate that keeps the qualities best matching the
+ * preferred language(s). The preference is an ordered list (see
+ * {@link resolvePreferredLanguages}): earlier entries win, and relatedness
+ * (exact > parent > sibling > child) breaks ties within a single preference.
+ *
+ * The best match is computed per period (per unique array reference), so
+ * periods with different available languages are handled independently. When no
+ * available language relates to any preference, all are kept (playback is never
+ * stranded). 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 preferredLanguage BCP 47 tag, ordered list of tags, or null (which
+ *   falls back to `navigator.languages`).
  * @param contentType Only filter qualities matching this content type (e.g. 'audio').
  */
-export declare function createLanguageFilter(preferredLanguage: string | null, contentType: string): FilterPredicate<MediaQualityMetadata> | null;
+export declare function createLanguageFilter(preferredLanguage: string | readonly string[] | null, contentType: string): FilterPredicate<MediaQualityMetadata> | null;
 //# sourceMappingURL=mediaTimelineLanguageFilter.d.ts.map

package/dist/types/ts3.7/text/SidecarTextTrackController.d.ts

@@ -0,0 +1,91 @@
+import { EventHostImpl, Maybe, RequestInitOptions } from '@amazon/vinyl-util';
+import { TextTrackController, TextTrackEventMap, TextTrackInfo } from './TextTrack';
+import { ObservableValue } from '@amazon/vinyl-observable';
+import { VttCueStyle } from './VttCueStyle';
+export interface SidecarTextTrackControllerDeps {
+    /**
+     * The HTML media element on which to attach the in-band TextTrack
+     * representation. Cues for the active text track are added to a TextTrack
+     * created via `media.addTextTrack`. Setting this to null disables DOM
+     * integration; cues are still loaded and surfaced via events.
+     */
+    readonly media: HTMLMediaElement | null;
+    /**
+     * Optional request init options forwarded with each VTT fetch (e.g. CORS).
+     */
+    readonly requestInit?: Maybe<RequestInitOptions>;
+    /**
+     * Preferred caption language(s), most-preferred first. A non-null
+     * preference auto-selects the best-matching track, re-applied as the track
+     * list changes. Changing the preference to null clears the selection
+     * (captions off). An initial null (or an absent observable) is "no
+     * preference": forced tracks still auto-select until the app makes an
+     * explicit choice — it does not force captions off.
+     */
+    readonly preferredTextLanguage?: ObservableValue<string | readonly string[] | null>;
+    /**
+     * Layout style applied to each rendered VTTCue (see
+     * {@link VttCueStyle}). Read per cue as it is appended, so a change affects
+     * subsequently-rendered cues. Absent means no styling (browser defaults).
+     */
+    readonly cueStyle?: ObservableValue<VttCueStyle | null>;
+}
+/**
+ * Manages a sidecar WebVTT-based text track lifecycle:
+ *
+ *  - holds a discovered list of {@link TextTrackInfo}
+ *  - on activation, fetches the chosen track's WebVTT and pushes cues to a
+ *    `TextTrack` created on the `HTMLMediaElement`
+ *  - clears any previously activated cues when switching tracks
+ *
+ * The controller is intentionally agnostic of HLS/DASH discovery details. Its
+ * input is whatever list of {@link TextTrackInfo} entries the manifest layer
+ * decides to surface.
+ */
+export declare class SidecarTextTrackController extends EventHostImpl<TextTrackEventMap> implements TextTrackController {
+    private readonly deps;
+    get [Symbol.toStringTag](): string;
+    private _tracks;
+    private _active;
+    private _domTrack;
+    private loadAbort;
+    private _userSelected;
+    private readonly preferredLanguageSub;
+    constructor(deps: SidecarTextTrackControllerDeps);
+    get textTracks(): readonly TextTrackInfo[];
+    get activeTextTrack(): (TextTrackInfo | null);
+    /**
+     * Replaces the discovered text track list. Emits `textTracksChange`. If
+     * the previously active track is no longer present, clears the active
+     * selection and emits `activeTextTrackChange`.
+     */
+    setTextTracks(tracks: readonly TextTrackInfo[]): void;
+    setActiveTextTrack(id: string | null): void;
+    /**
+     * Selects the track best matching the preferred language(s), or clears the
+     * selection when the preference is null or nothing matches.
+     */
+    private applyPreferredLanguage;
+    /**
+     * Applies a selection by id (null clears it) without marking it as an
+     * explicit user choice. Shared by setActiveTextTrack and forced auto-select.
+     */
+    private selectById;
+    /**
+     * The forced track to auto-select, or null. Prefers the default track's
+     * language, else the first forced track.
+     */
+    private pickForcedTrack;
+    suspend(): void;
+    resume(): void;
+    /**
+     * Cancels any in-flight load, clears the DOM TextTrack, and resets state.
+     * Called by the host when the underlying media is unloaded.
+     */
+    dispose(): void;
+    private startLoad;
+    private ensureDomTrack;
+    private appendCues;
+    private clearDomTrack;
+}
+//# sourceMappingURL=SidecarTextTrackController.d.ts.map

package/dist/types/ts3.7/text/SidecarTextTrackLoader.d.ts

@@ -0,0 +1,60 @@
+import { Maybe, ReadonlyAbort, RequestInitOptions } from '@amazon/vinyl-util';
+import { WebVttCue } from './parseWebVtt';
+/**
+ * Seconds ahead of the playhead to keep cues buffered. Mirrors the media
+ * pipeline's default HLS `minBufferTime` so captions stay in step with the
+ * audio/video buffer.
+ */
+export declare const DEFAULT_TEXT_LOOK_AHEAD = 10;
+/**
+ * Seconds behind the playhead to keep cues buffered. Small window so that a
+ * short rewind (e.g. accidental skip-back) doesn't force a refetch.
+ */
+export declare const DEFAULT_TEXT_LOOK_BEHIND = 2;
+export interface LoadWebVttCuesOptions {
+    readonly abort?: Maybe<ReadonlyAbort>;
+    readonly requestInit?: Maybe<RequestInitOptions>;
+    /**
+     * HLS EXT-X-DEFINE variables to make available for `IMPORT` and for
+     * substitution of segment URIs when loading from an HLS media playlist.
+     */
+    readonly variables?: Maybe<Readonly<Record<string, string>>>;
+    /**
+     * Invoked with each batch of cues as soon as they are parsed. Called once
+     * per HLS segment, or once for a direct `.vtt` document.
+     */
+    readonly onCues: (cues: readonly WebVttCue[]) => void;
+    /**
+     * Returns the current playback time (seconds on the presentation
+     * timeline). Used to fetch caption segments in a window around the
+     * playhead rather than draining the entire playlist up front.
+     */
+    readonly getCurrentTime: () => number;
+    /**
+     * Seconds ahead of the playhead to keep buffered. Default 10s.
+     */
+    readonly lookAhead?: Maybe<number>;
+    /**
+     * Seconds behind the playhead to keep buffered. Default 2s.
+     */
+    readonly lookBehind?: Maybe<number>;
+}
+/**
+ * Loads WebVTT cues from a URI, streaming them by playhead position.
+ *
+ * Two URI shapes are accepted:
+ *  - Direct `.vtt` document: fetched once and delivered via `onCues`.
+ *  - HLS media playlist (`.m3u8`): the playlist is parsed, then segments
+ *    whose time range overlaps the buffer window around `getCurrentTime()`
+ *    are fetched (closest to the playhead first), one at a time. Each
+ *    segment's cues are delivered via `onCues` as it is parsed.
+ *
+ * Cue start/end times are expected to already be on the presentation
+ * timeline (Shaka packager's default WebVTT output), so segments are joined
+ * without offset.
+ *
+ * The returned promise resolves once every segment has been fetched, or the
+ * abort signal fires. Fetch failures reject the promise.
+ */
+export declare function loadWebVttCues(uri: string, options: LoadWebVttCuesOptions): Promise<void>;
+//# sourceMappingURL=SidecarTextTrackLoader.d.ts.map