@amazon/vinyl 1.2.0 → 1.2.1

package/dist/types/ts3.7/ad/AdError.d.ts

@@ -0,0 +1,6 @@
+import { ErrorLevel, ReportableError } from '@amazon/vinyl-util';
+export declare class AdError extends ReportableError {
+    get [Symbol.toStringTag](): string;
+    constructor(message: string, origin?: string, level?: ErrorLevel);
+}
+//# sourceMappingURL=AdError.d.ts.map

package/dist/types/ts3.7/ad/AdsProvider.d.ts

@@ -0,0 +1,28 @@
+import { AnyRecord, ReadonlyEventHost } from '@amazon/vinyl-util';
+import { TrackAds } from './AdBreakInfo';
+/**
+ * Events dispatched by an {@link AdsProvider}.
+ */
+export interface AdsProviderEventMap {
+    /**
+     * The set of ads has changed; consumers should re-read via
+     * {@link AdsProvider.getAds}.
+     */
+    readonly adsChange: AnyRecord;
+}
+/**
+ * The minimal surface an {@link AdController} needs to source its ad breaks:
+ * a resolver for the current break list, plus an `adsChange` event to signal
+ * when that list changes. A {@link ReadonlyTrack} satisfies this directly, so
+ * the current playing track can be passed as-is; applications may also
+ * implement it to supply ads out of band (e.g. from an external ad server).
+ */
+export interface AdsProvider extends ReadonlyEventHost<AdsProviderEventMap> {
+    /**
+     * Resolves to the provider's current ad breaks. The result may change over
+     * the provider's lifetime; each `adsChange` event indicates that a
+     * subsequent call may return different breaks.
+     */
+    getAds(): Promise<TrackAds>;
+}
+//# sourceMappingURL=AdsProvider.d.ts.map

package/dist/types/ts3.7/ad/defaultAdLoadOptionsResolver.d.ts

@@ -0,0 +1,12 @@
+import { AdInfo } from './AdBreakInfo';
+import { VinylTrackLoadOptions } from '../track/createVinylTrackFactories';
+import { ReportableError } from '@amazon/vinyl-util';
+export declare function defaultAdLoadOptionsResolver(adInfo: AdInfo): Promise<VinylTrackLoadOptions>;
+/**
+ * An error indicating that a method was called with illegal arguments.
+ */
+export declare class UnresolvableAdError extends ReportableError {
+    get [Symbol.toStringTag](): string;
+    constructor(message: string);
+}
+//# sourceMappingURL=defaultAdLoadOptionsResolver.d.ts.map

package/dist/types/ts3.7/ad/discoverHlsInterstitials.d.ts

@@ -0,0 +1,22 @@
+import { HlsMediaPlaylist } from '@amazon/vinyl-hls-parser';
+import { AdBreakList } from './AdBreakInfo';
+/**
+ * Discovers HLS Interstitial ad breaks from a parsed media playlist and maps
+ * them to the provider-agnostic {@link AdBreakInfo} model.
+ *
+ * HLS Interstitials (Apple's SGAI primitive) are carried as EXT-X-DATERANGE
+ * tags with `CLASS="com.apple.hls.interstitial"`. Each such range is anchored
+ * to a wall-clock `START-DATE`; this function converts that to a media-timeline
+ * start time by correlating it with the playlist's EXT-X-PROGRAM-DATE-TIME
+ * anchor. When the playlist carries no program date-time, and the range's
+ * start-date is not otherwise resolvable, the break is anchored to the start of
+ * the timeline (pre-roll) as a best effort.
+ *
+ * @param playlist The parsed HLS media playlist.
+ * @param baseUrl  The URL of the media playlist, used to resolve relative
+ *   `X-ASSET-URI` values.
+ * @param contentDuration The total content duration in seconds, if known, used
+ *   to classify post-rolls. Pass null/undefined for live or unknown durations.
+ */
+export declare function discoverHlsInterstitials(playlist: HlsMediaPlaylist, baseUrl: string, contentDuration?: number | null): Promise<AdBreakList>;
+//# sourceMappingURL=discoverHlsInterstitials.d.ts.map

package/dist/types/ts3.7/playback/PlaybackControllerImpl.d.ts

@@ -41,7 +41,7 @@ export declare const defaultPlaybackControllerImplOptions: {
  * Firefox can but if the playhead reaches the end of track before the media stream is closed, an 'ended' event
  * will never fire.
  */
-export declare function getMinSeekableBufferDefault(): 2 | 5;
+export declare function getMinSeekableBufferDefault(): 5 | 2;
 export interface PlaybackControllerImplDeps {
     readonly media: HTMLMediaElement;
     readonly loudnessNormalizationController: LoudnessNormalizationController;

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

@@ -0,0 +1,39 @@
+import { ObjectSchema } from '@amazon/vinyl-validation';
+/**
+ * Criteria used to pick which audio rendition to play.
+ */
+export interface AudioSelection {
+    /**
+     * Preferred language(s) for audio content, as RFC 5646 codes (e.g. `'en'`,
+     * `'ja'`, `'fr-CA'`). May be a single tag or an ordered list of tags —
+     * earlier entries are preferred, with the best relatedness match kept for
+     * each period (audio without a language tag is always kept). `null` (the
+     * default) is NOT "no preference": it orders by the platform's
+     * `navigator.languages`. To keep every language, this option is not the
+     * mechanism — omit language content or pass a tag matching all.
+     */
+    readonly language?: string | readonly string[] | null;
+    /**
+     * Opt in to audio-description (a.k.a. described-video / DVS) audio: audio
+     * renditions carrying an accessibility "describes video" characteristic that
+     * narrate on-screen action. `false` (the default) keeps them out of the
+     * automatic default-audio selection — they are chosen only when this is set.
+     * When `true`, a description rendition is preferred where one exists for the
+     * selected language. Changing this reselects audio immediately.
+     */
+    readonly descriptive?: boolean;
+}
+/**
+ * Declarative audio configuration. Mirrors `VinylOptions.text`: the audio
+ * rendition is chosen from {@link selection}; changing it reselects audio
+ * immediately.
+ */
+export interface AudioOptions {
+    /**
+     * The audio selection criteria (language / descriptive).
+     */
+    readonly selection?: AudioSelection;
+}
+export declare const defaultAudioOptions: AudioOptions;
+export declare const audioOptionsValidator: ObjectSchema<AudioOptions>;
+//# sourceMappingURL=AudioOptions.d.ts.map

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

@@ -0,0 +1,58 @@
+import { Timestamp } from '@amazon/vinyl-util';
+import { TrackUri } from '../track/Track';
+/**
+ * The stage of the track-load journey a {@link LoadSpanMeasurement} describes.
+ *
+ * - `manifest`: fetching and parsing the DASH/HLS manifest.
+ * - `license`: the DRM license request/response exchange.
+ * - `initSegment`: fetching the initialization segment.
+ * - `firstSegment`: fetching the first media segment.
+ */
+export type LoadSpanKind = 'manifest' | 'license' | 'initSegment' | 'firstSegment';
+/**
+ * A timed span for one stage of a track load.
+ *
+ * Dispatched by the controller that owns the stage. Emitters attribute the span
+ * to the track it was measured for at the source (see {@link trackUri}); the
+ * player republishes it as a {@link LoadSpanEvent}. When the emitter cannot know
+ * the owning track, `trackUri` is omitted and the span is dropped rather than
+ * misattributed.
+ */
+export interface LoadSpanMeasurement {
+    readonly kind: LoadSpanKind;
+    /**
+     * When the stage began, as a unix millisecond timestamp.
+     */
+    readonly startTime: Timestamp;
+    /**
+     * When the stage completed, as a unix millisecond timestamp.
+     */
+    readonly endTime: Timestamp;
+    /**
+     * The track this span was measured for, stamped at the source by the
+     * emitter that knows which track initiated the load. Omitted only when the
+     * initiating track is not yet known (e.g. an encrypted event handled before
+     * buffering DRM info is set).
+     */
+    readonly trackUri?: TrackUri;
+}
+/**
+ * A {@link LoadSpanMeasurement} attributed to the track it was measured for.
+ *
+ * Emitted on the player as the `loadSpan` event.
+ */
+export interface LoadSpanEvent extends LoadSpanMeasurement {
+    readonly trackUri: TrackUri;
+}
+/**
+ * Player-level load metric events.
+ */
+export interface LoadMetricEventMap {
+    /**
+     * A stage of a track load completed. Reports the time span of the stage
+     * together with the track it belongs to. Consumers measuring end-to-end
+     * load latency key on the first event per `kind` and `trackUri`.
+     */
+    readonly loadSpan: LoadSpanEvent;
+}
+//# sourceMappingURL=LoadMetric.d.ts.map

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

@@ -0,0 +1,40 @@
+import { MutableValue } from '@amazon/vinyl-observable';
+import { EventHandler, SignalOptions, Unsubscribe } from '@amazon/vinyl-util';
+import { ManifestController, ManifestControllerEventMap, ManifestProvider } from './ManifestController';
+export interface ManifestControllerImplDeps<T> {
+    readonly manifestProvider: ManifestProvider<T>;
+}
+export declare class ManifestControllerImpl<T> implements ManifestController<Promise<T>> {
+    private readonly deps;
+    get [Symbol.toStringTag](): string;
+    get logPrefix(): string;
+    private readonly _data;
+    private _error;
+    private readonly abortSlot;
+    private readonly disposer;
+    private readonly events;
+    private manifestSpanArmed;
+    constructor(deps: ManifestControllerImplDeps<T>);
+    on<K extends keyof ManifestControllerEventMap>(type: K, handler: EventHandler<ManifestControllerEventMap[K]>, options?: SignalOptions): Unsubscribe;
+    hasAnyListeners(): boolean;
+    hasListeners(type: keyof ManifestControllerEventMap): boolean;
+    readonly __eventMapType: import("@amazon/vinyl-util").Covariant<ManifestControllerEventMap>;
+    get error(): (Error | null);
+    refresh(): void;
+    private requestManifest;
+    /**
+     * Measures the initial manifest fetch as a load span, re-arming on failure
+     * so a recovered load is still measured.
+     */
+    private measureLoadSpan;
+    reset(): void;
+    get value(): Promise<T>;
+    get changeId(): number;
+    getValue(): Promise<T>;
+    onData(callback: (value: Promise<T>, previous?: Promise<T>) => void): () => void;
+    map<U>(fn: (value: Promise<T>) => U): import("@amazon/vinyl-observable").ObservableValue<U>;
+    pick<K extends keyof NonNullable<Promise<T>>>(key: K): MutableValue<Promise<T>[K]>;
+    get disposed(): boolean;
+    dispose(): void;
+}
+//# sourceMappingURL=ManifestControllerImpl.d.ts.map

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/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/text/HtmlTextTrackRenderer.d.ts

@@ -0,0 +1,60 @@
+import { Disposable } from '@amazon/vinyl-util';
+import { TextTrackRenderer } from './TextTrackRenderer';
+/**
+ * The subset of a `VTTCue`'s positioning properties {@link computeCueLayout}
+ * reads. A native `VTTCue` satisfies this; a plain `TextTrackCue` (platforms
+ * without `VTTCue`) leaves them undefined and falls back to defaults.
+ */
+export interface CueGeometry {
+    readonly align?: string | null;
+    readonly line?: number | AutoKeyword;
+    readonly lineAlign?: LineAlignSetting;
+    readonly position?: number | AutoKeyword;
+    readonly positionAlign?: PositionAlignSetting;
+    readonly size?: number;
+    readonly snapToLines?: boolean;
+    readonly vertical?: DirectionSetting;
+}
+/** Inline styles (camelCase CSS properties) to apply to a rendered cue box. */
+export type CueLayout = Record<string, string>;
+/**
+ * Maps a cue's WebVTT positioning settings to inline CSS. Pure and DOM-free so
+ * the (branchy) placement logic is unit-testable in isolation.
+ *
+ * A cue with neither `line` nor `position` set flows in the renderer's
+ * bottom-anchored, centered container (the common subtitle case). Otherwise it
+ * is absolutely positioned: `size` → width, `position`/`positionAlign` →
+ * horizontal, `line`/`lineAlign`/`snapToLines` → vertical (percentage lines, or
+ * whole rows counted from the bottom for negative integers), `align` → text
+ * alignment, `vertical` → writing mode.
+ */
+export declare function computeCueLayout(cue: CueGeometry): CueLayout;
+/**
+ * Renders a cue's text payload as safe HTML. Text is escaped (so it can't
+ * inject nodes); newlines become `<br>`; and WebVTT cue tags are converted:
+ * `<c.foo>`→`<span class="foo">`, `<i>/<b>/<u>/<ruby>/<rt>` pass through,
+ * `<v Name>`→`<span title>`, `<lang xx>`→`<span lang>`, timestamp tags are
+ * dropped. Class-based styling requires matching app CSS (STYLE blocks in the
+ * VTT are not applied).
+ */
+export declare function renderCueText(text: string): string;
+/**
+ * A {@link TextTrackRenderer} that paints cues as HTML into {@link element}.
+ * Mount `element` over the video; it stacks cues at the bottom, centered, and
+ * positions any cue that carries explicit WebVTT settings. The DOM track is
+ * expected to be `'hidden'` so only this renderer paints.
+ */
+export declare class HtmlTextTrackRenderer implements TextTrackRenderer, Disposable {
+    /** The overlay container to mount over the video. */
+    readonly element: HTMLElement;
+    private track;
+    private readonly styleElement;
+    private readonly onCueChange;
+    constructor();
+    setTextTrack(track: TextTrack | null): void;
+    setStyles(styles: readonly string[]): void;
+    dispose(): void;
+    private renderActiveCues;
+    private createCueBox;
+}
+//# sourceMappingURL=HtmlTextTrackRenderer.d.ts.map

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

@@ -0,0 +1,103 @@
+import { EventHostImpl, Maybe, RequestInitOptions } from '@amazon/vinyl-util';
+import { TextTrackController, TextTrackControllerOptions, TextTrackEventMap, TextTrackInfo } from './TextTrack';
+import { ObservableValue } from '@amazon/vinyl-observable';
+import { MediaTextTrackProvider } from './mediaTextTrackProvider';
+import { ReadonlyPlaybackController } from '../playback/ReadonlyPlaybackController';
+import { TextTrackRenderer } from './TextTrackRenderer';
+export interface SidecarTextTrackControllerDeps {
+    /**
+     * Hands out (memoized) DOM text tracks. Text tracks can only be created on a
+     * media element and never removed, so the provider reuses one track per
+     * rendition rather than accumulating them.
+     */
+    readonly textTrackProvider: MediaTextTrackProvider;
+    /**
+     * Optional request init options forwarded with each VTT fetch (e.g. CORS).
+     */
+    readonly requestInit?: Maybe<RequestInitOptions>;
+    /**
+     * The discovered text tracks, re-emitted whenever the manifest changes.
+     */
+    readonly textTracks: ObservableValue<Promise<readonly TextTrackInfo[]>>;
+    /**
+     * Declarative selection / rendering configuration. Re-applied on change.
+     */
+    readonly options: ObservableValue<TextTrackControllerOptions>;
+    /**
+     * Supplies the current playhead used to fetch caption segments in a window
+     * around it.
+     */
+    readonly playbackController: ReadonlyPlaybackController;
+    /**
+     * Optional renderer that paints cues itself (HTML overlay). When provided,
+     * the DOM text track is kept `'hidden'` (timing only) and the renderer is
+     * handed the active track; without one, the track renders natively
+     * (`'showing'`).
+     */
+    readonly textTrackRenderer?: Maybe<TextTrackRenderer>;
+}
+/**
+ * Selects the text track that matches the given options, or null for none.
+ *
+ * The `enabled` mode gates everything: `'off'` renders nothing (default is
+ * `'forced'`). Otherwise an explicit {@link TextTrackSelection.id} wins; else
+ * the best language match is chosen among tracks filtered by kind and
+ * forced-ness. Forced-ness comes from {@link TextTrackSelection.forced} when
+ * set, otherwise from the mode (`'forced'` keeps only forced tracks, `'on'`
+ * only full tracks).
+ *
+ * @private
+ */
+export declare function resolveSelectedTrack(tracks: readonly TextTrackInfo[], options: TextTrackControllerOptions): TextTrackInfo | null;
+/**
+ * Manages a sidecar WebVTT-based text track lifecycle:
+ *
+ *  - tracks the discovered {@link TextTrackInfo} list (from the `textTracks`
+ *    observable) and the current selection (from the `options` observable)
+ *  - on selection, fetches the chosen track's WebVTT and pushes cues to a DOM
+ *    `TextTrack` obtained from the {@link MediaTextTrackProvider}
+ *  - clears cues and hides the DOM track when the selection changes or clears
+ *
+ * The controller is agnostic of HLS/DASH discovery details; its inputs are the
+ * observables supplied by the manifest layer.
+ */
+export declare class SidecarTextTrackController extends EventHostImpl<TextTrackEventMap> implements TextTrackController {
+    private readonly deps;
+    get [Symbol.toStringTag](): string;
+    private _active;
+    private _tracks;
+    private _activeTextTrack;
+    private _ref;
+    private readonly loadAbort;
+    private readonly disposer;
+    constructor(deps: SidecarTextTrackControllerDeps);
+    get textTracks(): readonly TextTrackInfo[];
+    get activeTextTrack(): (TextTrackInfo | null);
+    get active(): boolean;
+    get disposed(): boolean;
+    /**
+     * Replaces the discovered track list, emits `textTracksChange`, then
+     * re-applies the current selection against the new list.
+     */
+    private setTracks;
+    /**
+     * Recomputes the selection from the current options and track list,
+     * emitting `activeTextTrackChange` on change and (re)rendering when active.
+     */
+    private refreshSelection;
+    deactivate(): void;
+    activate(): void;
+    private startLoad;
+    private appendCues;
+    /**
+     * Clears cues from the current DOM track and hides it, keeping the track for
+     * later reuse via the provider.
+     */
+    private hideCurrent;
+    /**
+     * Cancels any in-flight load, hides the DOM text track, and resets state.
+     * Called by the host when the underlying media is unloaded.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=SidecarTextTrackController.d.ts.map

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

@@ -0,0 +1,65 @@
+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;
+    /**
+     * Invoked with the CSS body of any `STYLE` blocks parsed from a document.
+     * Only called when a document actually declares styles.
+     */
+    readonly onStyles?: Maybe<(styles: readonly string[]) => 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