@amazon/vinyl 1.2.0 → 1.2.1

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

@@ -0,0 +1,183 @@
+import { ChangeEvent } from '../event/ChangeEvent';
+import { ReadonlyEventHost } from '@amazon/vinyl-util';
+import { ObjectSchema } from '@amazon/vinyl-validation';
+/**
+ * Categorizes the role of a text track. Mirrors HTMLMediaElement.TextTrackKind.
+ */
+export type TextTrackKind = 'subtitles' | 'captions' | 'descriptions' | 'chapters' | 'metadata';
+/**
+ * Identifies and describes an available text track.
+ * One TextTrackInfo is produced per discovered subtitle rendition.
+ */
+export interface TextTrackInfo {
+    /**
+     * A stable, unique identifier within the current media presentation.
+     */
+    readonly id: string;
+    /**
+     * The text track kind. Defaults to 'subtitles' when not otherwise specified.
+     */
+    readonly kind: TextTrackKind;
+    /**
+     * The BCP 47 language tag for the cues in this track, or null if unknown.
+     */
+    readonly language: string | null;
+    /**
+     * A human-readable label for the track.
+     */
+    readonly label: string;
+    /**
+     * Set when the source manifest signals this track as the default selection.
+     */
+    readonly default: boolean;
+    /**
+     * Whether this is a forced track: it carries essential text (e.g.
+     * translations of foreign-language dialogue) meant to be shown even when
+     * the user has not enabled subtitles. Two tracks may share a language and
+     * differ only by this flag, so selection must distinguish them.
+     */
+    readonly forced: boolean;
+    /**
+     * Media characteristics / accessibility roles describing the track, e.g.
+     * `public.accessibility.transcribes-spoken-dialog` (HLS CHARACTERISTICS) or
+     * a DASH role/accessibility scheme value. Empty when none are signaled.
+     */
+    readonly characteristics: readonly string[];
+    /**
+     * The full URL of the underlying text resource (typically a WebVTT file).
+     */
+    readonly uri: string;
+    /**
+     * The MIME type signaled by the source manifest, when known.
+     */
+    readonly mimeType: string | null;
+    /**
+     * HLS EXT-X-DEFINE variables inherited from the parent multivariant
+     * playlist. Sidecar text-track media playlists commonly `IMPORT` these
+     * names and reference them in segment URIs. Present only for HLS-sourced
+     * tracks whose parent playlist declared any variables.
+     */
+    readonly variables?: Readonly<Record<string, string>>;
+}
+/**
+ * Events dispatched by a {@link TextTrackController}.
+ */
+export interface TextTrackEventMap {
+    /**
+     * Emitted when the available text tracks change.
+     */
+    readonly textTracksChange: ChangeEvent<readonly TextTrackInfo[]>;
+    /**
+     * Emitted when the active text track changes.
+     */
+    readonly activeTextTrackChange: ChangeEvent<TextTrackInfo | null>;
+    /**
+     * Emitted when an error occurs while loading or activating a text track.
+     */
+    readonly textTrackError: TextTrackErrorEvent;
+}
+export interface TextTrackErrorEvent {
+    readonly track: TextTrackInfo;
+    readonly error: Error;
+}
+/**
+ * Which captions render:
+ * - `'off'` — nothing renders (not even forced narrative captions).
+ * - `'forced'` — only forced (narrative) tracks, so nothing shows unless the
+ *   content carries a forced track for the preferred language.
+ * - `'on'` — the full (non-forced) subtitle track for the preferred language.
+ */
+export type CaptionMode = 'on' | 'off' | 'forced';
+/**
+ * Criteria used to pick which text track to render. Applied in priority order:
+ * an explicit {@link id} wins; otherwise the best {@link language} match is
+ * chosen among tracks filtered by {@link kind} and by forced-ness (from
+ * {@link forced} when set, else from the controller's
+ * {@link TextTrackControllerOptions.enabled} mode).
+ */
+export interface TextTrackSelection {
+    /**
+     * Selects the text track with this exact identifier, ignoring the other
+     * criteria (but still gated by the `'off'` mode). If no track has this id,
+     * nothing is selected.
+     */
+    readonly id?: string | null;
+    /**
+     * Restricts selection to tracks of this kind (e.g. `'captions'`). Unset
+     * considers all kinds.
+     */
+    readonly kind?: TextTrackKind | null;
+    /**
+     * Preferred caption language(s), most-preferred first, as RFC 5646 tags.
+     * When unset (or empty) selection falls back to the platform's
+     * `navigator.languages`.
+     */
+    readonly language?: string | readonly string[] | null;
+    /**
+     * Explicit forced-ness filter. When set, only tracks whose `forced` flag
+     * equals this value are considered, overriding the forced/full split
+     * implied by the `enabled` mode. Unset means the mode decides.
+     */
+    readonly forced?: boolean | null;
+}
+/**
+ * Declarative configuration for a {@link TextTrackController}. Rendering is
+ * driven entirely by this value (via `VinylOptions.text`); there is no
+ * imperative track-select call.
+ */
+export interface TextTrackControllerOptions {
+    /**
+     * Which captions render (see {@link CaptionMode}). Unset defaults to
+     * `'forced'`.
+     */
+    readonly enabled?: CaptionMode | null;
+    /**
+     * The selection criteria (language / id / kind). When unset, the preferred
+     * languages fall back to the platform's `navigator.languages`.
+     */
+    readonly selection?: TextTrackSelection | null;
+}
+export declare const textTrackControllerOptionsValidator: ObjectSchema<TextTrackControllerOptions>;
+export declare const ALL_TEXT_TRACK_EVENTS: readonly [
+    "textTracksChange",
+    "activeTextTrackChange",
+    "textTrackError"
+];
+/**
+ * Read-only view of available text tracks and the active selection.
+ */
+export interface ReadonlyTextTrackController extends ReadonlyEventHost<TextTrackEventMap> {
+    /**
+     * The list of currently discovered text tracks.
+     */
+    readonly textTracks: readonly TextTrackInfo[];
+    /**
+     * The currently active text track, or null if none is active.
+     */
+    readonly activeTextTrack: TextTrackInfo | null;
+    /*
+    * Returns true if this text track controller is active.
+    */
+    readonly active: boolean;
+}
+/**
+ * Full controller for the current media's text tracks. Selection is driven
+ * declaratively through the controller's options (`VinylOptions.text`); this
+ * interface only adds the render lifecycle used by the owning media track.
+ */
+export interface TextTrackController extends ReadonlyTextTrackController {
+    /**
+     * Suspends cue rendering without changing the active selection: cancels any
+     * in-flight load and hides the DOM text track (so its cues stop showing).
+     * Called when the owning media track is deactivated — e.g. while an ad
+     * plays over the suspended content. {@link activate} rebuilds it.
+     */
+    deactivate(): void;
+    /**
+     * Resumes rendering the active selection after a {@link deactivate},
+     * reloading its cues. No-op when nothing is selected or already rendering.
+     * Called when the owning media track is reactivated.
+     */
+    activate(): void;
+}
+//# sourceMappingURL=TextTrack.d.ts.map

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

@@ -0,0 +1,24 @@
+/**
+ * Renders a text track's cues. Injected into the player so an application can
+ * paint captions itself (as HTML) instead of relying on the browser's native
+ * `TextTrack` rendering — giving full control over styling and placement.
+ *
+ * The controller hands the renderer the DOM `TextTrack` (set to `'hidden'`, so
+ * the browser tracks cue timing but does not paint); the renderer listens for
+ * the track's active cues and draws them. See {@link HtmlTextTrackRenderer} for
+ * the built-in HTML implementation.
+ */
+export interface TextTrackRenderer {
+    /**
+     * Renders the active cues of `track`, listening for cue changes. Passing
+     * `null` clears anything rendered and detaches from the previous track.
+     */
+    setTextTrack(track: TextTrack | null): void;
+    /**
+     * Supplies the CSS bodies of the track's WebVTT `STYLE` blocks (which carry
+     * `::cue` rules), so the renderer can style cue classes. Optional — a
+     * renderer may ignore authored styles.
+     */
+    setStyles?(styles: readonly string[]): void;
+}
+//# sourceMappingURL=TextTrackRenderer.d.ts.map

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

@@ -0,0 +1,41 @@
+import { ObjectSchema } from '@amazon/vinyl-validation';
+/**
+ * Layout style applied to each rendered WebVTT cue, mirroring the settable
+ * positioning properties of the DOM `VTTCue`. Only the properties that are set
+ * are applied; the rest keep the browser defaults.
+ *
+ * These are the WebVTT cue-box layout controls (not text color/font, which are
+ * only reachable via the non-configurable `::cue` pseudo-element). See
+ * {@link https://developer.mozilla.org/docs/Web/API/VTTCue}.
+ */
+export interface VttCueStyle {
+    /** Text alignment within the cue box. */
+    readonly align?: AlignSetting;
+    /** Line (vertical) position, as a line number/percentage or `'auto'`. */
+    readonly line?: number | AutoKeyword;
+    /** How `line` is anchored. */
+    readonly lineAlign?: LineAlignSetting;
+    /** Inline position of the cue box, as a percentage or `'auto'`. */
+    readonly position?: number | AutoKeyword;
+    /** How `position` is anchored. */
+    readonly positionAlign?: PositionAlignSetting;
+    /** Size of the cue box as a percentage of the video dimension. */
+    readonly size?: number;
+    /** Whether `line` is a line number (true) or a percentage (false). */
+    readonly snapToLines?: boolean;
+    /** Writing direction. */
+    readonly vertical?: DirectionSetting;
+}
+/**
+ * Type guard for a DOM cue that is a `VTTCue` (and so carries the WebVTT layout
+ * properties). On platforms without `VTTCue`, cues are plain `TextTrackCue`s
+ * that cannot be styled.
+ */
+export declare function isVttCue(cue: TextTrackCue): cue is VTTCue;
+/**
+ * Applies the configured layout style to a `VTTCue`, setting only the
+ * properties present in `style`.
+ */
+export declare function applyVttCueStyle(cue: VTTCue, style: VttCueStyle): void;
+export declare const vttCueStyleValidator: ObjectSchema<VttCueStyle>;
+//# sourceMappingURL=VttCueStyle.d.ts.map

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

@@ -0,0 +1,24 @@
+import { DashManifest } from '@amazon/vinyl-mpd-parser';
+import { TextTrackInfo } from './TextTrack';
+/**
+ * Discovers sidecar text tracks from a DASH manifest.
+ *
+ * Considers an `<AdaptationSet>` to carry text when one of:
+ *  - `contentType="text"`
+ *  - `mimeType` starts with `text/` (e.g. `text/vtt`)
+ *  - `mimeType` is `application/mp4` *and* the codec/role indicates text
+ *
+ * Within a text adaptation set, each `<Representation>` becomes one
+ * {@link TextTrackInfo}. The `BaseURL` chain (MPD → Period → AdaptationSet →
+ * Representation) is resolved against the supplied `baseUrl`.
+ *
+ * Only sidecar (single-file) WebVTT renditions are surfaced. Segmented text
+ * tracks (`stpp`/`wvtt` codecs) are ignored - they would require streaming
+ * through MSE which the sidecar pipeline does not support.
+ *
+ * @param manifest The parsed DASH manifest.
+ * @param baseUrl The URL of the manifest, used as the root for `BaseURL`
+ * resolution.
+ */
+export declare function discoverDashTextTracks(manifest: DashManifest, baseUrl: string): readonly TextTrackInfo[];
+//# sourceMappingURL=discoverDashTextTracks.d.ts.map

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

@@ -0,0 +1,19 @@
+import { HlsMainPlaylist } from '@amazon/vinyl-hls-parser';
+import { TextTrackInfo } from './TextTrack';
+/**
+ * Discovers sidecar text tracks from an HLS multivariant playlist.
+ *
+ * Per RFC 8216 §4.3.4.2, subtitle renditions are signaled with
+ * `EXT-X-MEDIA:TYPE=SUBTITLES` and (when usable as sidecar) carry a `URI`
+ * attribute pointing at a media playlist or, in the simplified single-file
+ * case, a `.vtt` file directly.
+ *
+ * Closed captions (`TYPE=CLOSED-CAPTIONS`) are intentionally excluded - they
+ * are delivered in-band with the video stream and are surfaced by the browser
+ * automatically, not through a sidecar fetch.
+ *
+ * @param mainPlaylist The parsed HLS main playlist.
+ * @param baseUrl The URL of the main playlist, used to resolve relative URIs.
+ */
+export declare function discoverHlsTextTracks(mainPlaylist: HlsMainPlaylist, baseUrl: string): readonly TextTrackInfo[];
+//# sourceMappingURL=discoverHlsTextTracks.d.ts.map

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

@@ -0,0 +1,34 @@
+import { TextTrackKind } from './TextTrack';
+/**
+ * A handle to a DOM {@link TextTrack} created on the media element, plus a way
+ * to clear its cues.
+ */
+export interface TextTrackRef {
+    readonly track: TextTrack;
+    /**
+     * Removes all cues from the track. Must be called while the track is not
+     * `disabled` — `TextTrack.cues` reads null in the disabled state, so
+     * clearing a disabled track silently leaves its cues attached.
+     */
+    clear(): void;
+}
+/**
+ * Creates and hands out DOM text tracks for a media element, memoized per
+ * `(kind, label, language)`.
+ *
+ * `HTMLMediaElement.addTextTrack` tracks can never be removed, so creating a
+ * fresh one per activation would accumulate tracks — and any left in `showing`
+ * mode renders alongside the active one (captions "bleed through"). Reusing one
+ * track per key keeps exactly one track per distinct rendition.
+ */
+export interface MediaTextTrackProvider {
+    getOrCreate(kind: TextTrackKind, label?: string, language?: string): TextTrackRef;
+}
+export declare function createMediaTextTrackProvider(deps: {
+    /**
+     * The HTML media element on which to attach the in-band TextTrack
+     * representation.
+     */
+    readonly media: HTMLMediaElement;
+}): MediaTextTrackProvider;
+//# sourceMappingURL=mediaTextTrackProvider.d.ts.map

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

@@ -0,0 +1,60 @@
+import { VttCueStyle } from './VttCueStyle';
+/**
+ * A single WebVTT cue.
+ *
+ * @see https://www.w3.org/TR/webvtt1/
+ */
+export interface WebVttCue {
+    /**
+     * Optional cue identifier, the line that appears before the timing line.
+     */
+    readonly id: string | null;
+    /**
+     * Cue start time in seconds.
+     */
+    readonly startTime: number;
+    /**
+     * Cue end time in seconds.
+     */
+    readonly endTime: number;
+    /**
+     * The cue text payload, with line breaks preserved as `\n`.
+     */
+    readonly text: string;
+    /**
+     * The authored cue settings from the timing line (position/line/size/
+     * align/vertical), when any were present. Preserved so a renderer can
+     * position the cue faithfully. Absent when the cue declared no settings.
+     */
+    readonly settings?: VttCueStyle;
+}
+/**
+ * The result of parsing a WebVTT document.
+ */
+export interface WebVttDocument {
+    /**
+     * Parsed cues in document order.
+     */
+    readonly cues: readonly WebVttCue[];
+    /**
+     * The raw CSS body of each `STYLE` block, in document order. These carry
+     * `::cue` rules (e.g. `::cue(.loud) { font-weight: bold }`) an HTML renderer
+     * can apply. Empty when the document declared no styles.
+     */
+    readonly styles: readonly string[];
+}
+/**
+ * Parses a WebVTT document into a list of cues.
+ *
+ * Implements a forgiving subset of the WebVTT 1.0 specification: header
+ * detection, comment blocks (lines starting with `NOTE`), styling/region
+ * blocks (STYLE bodies are captured, REGION skipped), cue identifiers, and
+ * HH:MM:SS.mmm or MM:SS.mmm timestamps with optional cue settings.
+ *
+ * @param input The raw WebVTT document text. Both LF and CRLF line endings
+ * are supported, and a leading BOM is stripped if present.
+ * @throws ValidationError if the input is missing the WEBVTT header.
+ * @see https://www.w3.org/TR/webvtt1/#webvtt-timestamp
+ */
+export declare function parseWebVtt(input: string): WebVttDocument;
+//# sourceMappingURL=parseWebVtt.d.ts.map

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

@@ -0,0 +1,15 @@
+import { TextTrackInfo } from './TextTrack';
+import { Maybe } from '@amazon/vinyl-util';
+/**
+ * Chooses the text track that best matches the preferred language(s), or null
+ * when none relate (or there is no preference / no tracks).
+ *
+ * Language dominates: a track is ranked first by which preference it relates to
+ * (earlier entries win) and how closely (see {@link languageRelatedness}).
+ * Within a single language, a full track is preferred over a forced-only track
+ * (a user asking for a caption language wants the full captions, not just the
+ * forced foreign-dialogue cues), and a manifest-default track breaks any
+ * remaining tie.
+ */
+export declare function pickPreferredTextTrack(tracks: readonly TextTrackInfo[], preferred: Maybe<string | readonly string[]>): TextTrackInfo | null;
+//# sourceMappingURL=pickPreferredTextTrack.d.ts.map

package/dist/types/ts3.7/track/SeekRange.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The seekable time range on the media timeline, in seconds.
+ * `end` will be `Infinity` when a live stream.
+ */
+export type SeekRange = {
+    readonly start: number;
+    readonly end: number;
+};
+//# sourceMappingURL=SeekRange.d.ts.map

package/dist/types/ts3.7/track/hls/HlsManifestData.d.ts

@@ -0,0 +1,19 @@
+import { HlsMainPlaylist, HlsMediaPlaylist } from '@amazon/vinyl-hls-parser';
+export interface HlsManifestData {
+    /**
+     * The main HLS playlist manifest.
+     * Use getMediaPlaylist to resolve bitrate manifests.
+     */
+    readonly mainPlaylist: HlsMainPlaylist;
+    /**
+     * The URL to be used for relative requests. Guaranteed to be absolute.
+     *
+     * Media with relative paths in the manifests will be resolved relative to this URL.
+     */
+    readonly baseUrl: string;
+    /**
+     * Lazily fetches and caches a media playlist by variant URI.
+     */
+    readonly getMediaPlaylist: (uri: string) => Promise<HlsMediaPlaylist>;
+}
+//# sourceMappingURL=HlsManifestData.d.ts.map

package/dist/types/ts3.7/track/hls/createHlsManifestProvider.d.ts

@@ -0,0 +1,6 @@
+import { HlsTrackLoadOptions } from './HlsTrack';
+import { ManifestProvider } from '../../streaming/ManifestController';
+import { HlsManifestData } from './HlsManifestData';
+export declare function createHlsManifestProvider(loadOptions: HlsTrackLoadOptions): HlsManifestProvider;
+export type HlsManifestProvider = ManifestProvider<HlsManifestData>;
+//# sourceMappingURL=createHlsManifestProvider.d.ts.map

package/dist/types/ts3.7/track/inferLoadOptionsFromUri.d.ts

@@ -0,0 +1,15 @@
+import { VinylTrackLoadOptions } from './createVinylTrackFactories';
+/**
+ * The built-in track types Vinyl can infer from a URI.
+ */
+export type TrackType = 'hls' | 'dash' | 'src';
+/**
+ * Infers the track type from a URI based first on its file extension
+ * then mime type.
+ *
+ * Returns null if the type cannot be determined.
+ */
+export declare function inferTrackTypeFromUrl(url: string): Promise<TrackType | null>;
+export declare function inferTrackTypeFromUrlPath(url: string): TrackType | null;
+export declare function createTrackLoadOptionsFromUrl(url: string): Promise<VinylTrackLoadOptions | null>;
+//# sourceMappingURL=inferLoadOptionsFromUri.d.ts.map

package/dist/types/ts3.7/util/media/codecOverrides.d.ts

@@ -0,0 +1,33 @@
+/**
+ * An explicit application-provided decision to allow or deny a codec,
+ * bypassing the browser's support detection.
+ *
+ *  - `'allow'` forces the codec to be treated as supported even if the browser
+ *    reports it unsupported (e.g. to opt in to a codec the app knows the
+ *    platform can decode via an external path).
+ *  - `'deny'` forces the codec to be treated as unsupported even if the browser
+ *    reports it supported (e.g. to work around a browser that falsely claims
+ *    support, or to exclude a codec by policy).
+ */
+export type CodecOverride = 'allow' | 'deny';
+/**
+ * Explicit codec allow/deny overrides. Keys are RFC 6381 codec strings or
+ * prefixes (matched case-insensitively against the start of each codec in a
+ * mimeType's `codecs=` list, so `"hvc1"` matches `"hvc1.2.20000000.L123.B0"`).
+ *
+ * An override supersedes the browser's support detection entirely. When a
+ * mimeType contains multiple codecs, a `'deny'` on any of them denies the
+ * mimeType; an `'allow'` applies only when no codec is denied.
+ */
+export type CodecOverrides = Readonly<Record<string, CodecOverride>>;
+/**
+ * Resolves the effective override decision for a mimeType against a set of
+ * {@link CodecOverrides}, or undefined when no override applies (in which case
+ * the caller should fall back to normal support detection).
+ *
+ * A `'deny'` on any contained codec wins over an `'allow'` on another, so an
+ * explicit deny is never silently overridden by an allow elsewhere in the
+ * mimeType.
+ */
+export declare function resolveCodecOverride(mimeType: string, overrides: CodecOverrides | undefined): CodecOverride | undefined;
+//# sourceMappingURL=codecOverrides.d.ts.map

package/dist/types/ts3.7/util/media/codecSupport.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Extracts the individual codec strings from a mimeType's `codecs=` parameter.
+ * Returns an empty array when no codecs parameter is present.
+ */
+export declare function extractCodecs(mimeType: string): string[];
+//# sourceMappingURL=codecSupport.d.ts.map

package/dist/types/ts3.7/util/media/mimeType.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Extracts the container subtype from a MIME type, lowercased — the portion
+ * after the `/`, ignoring any parameters. For example
+ * `video/webm; codecs="vp9"` → `webm` and `audio/mp4` → `mp4`. Returns an empty
+ * string when the MIME type has no subtype.
+ */
+export declare function mimeSubtype(mimeType: string): string;
+//# sourceMappingURL=mimeType.d.ts.map

package/dist/types/ts4.1/ad/AdBreakInfo.d.ts

@@ -0,0 +1,160 @@
+import type { TrackUri } from '../track/Track';
+import type { ValueProvider } from '@amazon/vinyl-util';
+export interface TrackAds {
+    /**
+     * The URI of the parent track.
+     */
+    readonly trackUri: TrackUri;
+    /**
+     * An array of the ad breaks for this track.
+     */
+    readonly adBreaks: AdBreakList;
+}
+/**
+ * Where an ad break is scheduled relative to the main content.
+ *
+ *  - `preroll`  - before content playback begins (start time at or near 0).
+ *  - `midroll`  - during content playback.
+ *  - `postroll` - at the end of content playback.
+ */
+export type AdBreakPlacement = 'preroll' | 'midroll' | 'postroll';
+/**
+ * Restrictions on user interaction during an ad break.
+ */
+export interface AdRestriction {
+    /**
+     * When true, the user should not be allowed to skip this ad.
+     *
+     * This is not enforced by the player; the application is expected
+     * to respect this flag when showing ad skip controls.
+     */
+    readonly skip?: boolean;
+    /**
+     * When true, the user should not be allowed to seek past this ad.
+     */
+    readonly jump?: boolean;
+}
+/**
+ * A provider-agnostic description of a single ad break on the media timeline.
+ *
+ * An ad break is a span of the presentation that carries advertising rather
+ * than primary content. The same shape is produced from HLS Interstitials
+ * (EXT-X-DATERANGE with `CLASS="com.apple.hls.interstitial"`) and, in the
+ * future, from DASH SCTE-35 splice signals, so applications observe one
+ * interface regardless of the streaming protocol.
+ *
+ * Times are expressed on the player's media timeline, in seconds, so they can
+ * be compared directly against the media's current time.
+ */
+export interface AdBreakInfo {
+    /**
+     * A stable identifier for this ad break, unique within the current media
+     * presentation. Derived from the source signal (e.g. the HLS DATERANGE ID).
+     */
+    readonly id: string;
+    /**
+     * The start time of the ad break on the media timeline, in seconds.
+     */
+    readonly startTime: number;
+    /**
+     * The duration of the ad break in seconds, or null when unknown (e.g. a
+     * still-open live break that has not yet resolved its end).
+     */
+    readonly duration: number | null;
+    /**
+     * The scheduled placement of the break relative to primary content.
+     */
+    readonly placement: AdBreakPlacement;
+    /**
+     * The individual ad assets that make up this break, in playback order.
+     */
+    readonly ads: ValueProvider<AdList>;
+    /**
+     * Restrictions on user interaction during this ad break.
+     */
+    readonly restrict: AdRestriction;
+    /**
+     * When true, this break plays at most once for the presentation and is not
+     * replayed even if the playhead re-crosses it (e.g. after a seek back). When
+     * false, the break may replay each time the playhead re-enters its region.
+     *
+     * (An HLS interstitial sets this from a `CUE=ONCE` hint.)
+     */
+    readonly once: boolean;
+    /**
+     * The offset, in seconds, from this break's scheduled {@link startTime} at
+     * which primary content resumes after the break. A signed value: 0 resumes
+     * in place (the break is purely additive). `null` means no resume offset was
+     * specified, in which case content resumes advanced by the break's actual
+     * playout duration (i.e. the break replaces that much primary content) —
+     * this is distinct from an explicit 0.
+     *
+     * (An HLS interstitial sets this from `X-RESUME-OFFSET`.)
+     */
+    readonly resumeOffset: number | null;
+    /**
+     * The maximum total playout time of the whole break, in seconds, summed
+     * across all of its ads, or `null` when the break's playout is uncapped.
+     * Distinct from {@link duration} (the break's timeline span) and from an
+     * individual {@link AdInfo.duration}.
+     *
+     * (An HLS interstitial sets this from `X-PLAYOUT-LIMIT`.)
+     */
+    readonly playoutLimit: number | null;
+    /**
+     * How far ahead of this break's {@link startTime}, in seconds, the player
+     * should resolve and preload the break's ad assets so they are ready when
+     * the playhead reaches it. `null` when the source specifies no offset, in
+     * which case the controller falls back to its `preloadAheadTime` option.
+     * Applies to midroll and postroll breaks; prerolls are preloaded up front.
+     *
+     * (An HLS interstitial sets this from `X-RESOLUTION-TIME-OFFSET`.)
+     */
+    readonly resolutionTimeOffset: number | null;
+    /**
+     * The window during which the user may skip this break, or a provider
+     * resolving to `null` when the break carries no skip window (skippability is
+     * then governed by {@link AdRestriction.skip}). Resolved lazily because, like
+     * {@link ads}, it may require fetching the break's asset list.
+     *
+     * (An HLS interstitial sets this from the `X-ASSET-LIST` `SKIP-CONTROL`.)
+     */
+    readonly skipControl: ValueProvider<SkipControl | null>;
+}
+/**
+ * Describes when a user may skip an ad break: skipping becomes available
+ * {@link offset} seconds into the break and remains offered for {@link duration}
+ * seconds (or the rest of the break when null).
+ */
+export interface SkipControl {
+    /** Seconds from the break start at which skipping becomes available. */
+    readonly offset: number;
+    /**
+     * Seconds the skip control remains offered after {@link offset}, or `null`
+     * to offer it for the remainder of the break.
+     */
+    readonly duration: number | null;
+}
+/**
+ * An ad break list, sorted by start time ascendingly.
+ */
+export type AdBreakList = readonly AdBreakInfo[];
+/**
+ * A single ad within an {@link AdBreakInfo}.
+ */
+export interface AdInfo {
+    /** A stable identifier for this ad within its break. */
+    readonly id: string;
+    /** The start time of this ad on the media timeline, in seconds. */
+    readonly startTime: number;
+    /** The duration of this ad in seconds, or null when unknown. */
+    readonly duration: number | null;
+    /**
+     * The URI of the ad asset, when the source signal provides one directly
+     * (e.g. an HLS interstitial `X-ASSET-URI`). Null when the ad is described
+     * only indirectly.
+     */
+    readonly uri: TrackUri | null;
+}
+export type AdList = readonly AdInfo[];
+//# sourceMappingURL=AdBreakInfo.d.ts.map