@amazon/vinyl 1.1.1 → 2.0.0

package/dist/types/ts4.1/streaming/util/segment.d.ts

@@ -1,4 +1,4 @@
-import type { MediaSegmentMetadata } from '../../streaming/SegmentReference';
+import type { MediaSegmentMetadata } from '../SegmentReference';
 /**
  * Returns the segment whose range covers `time` (`startTime <= time < endTime`), or
  * — when `affordance > 0` — the next segment if `time` falls within `affordance`

package/dist/types/ts4.1/text/SidecarTextTrackController.d.ts

@@ -0,0 +1,92 @@
+import type { Maybe, RequestInitOptions } from '@amazon/vinyl-util';
+import { EventHostImpl } from '@amazon/vinyl-util';
+import type { TextTrackController, TextTrackEventMap, TextTrackInfo } from './TextTrack';
+import type { ObservableValue } from '@amazon/vinyl-observable';
+import type { 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/ts4.1/text/SidecarTextTrackLoader.d.ts

@@ -0,0 +1,60 @@
+import type { Maybe, ReadonlyAbort, RequestInitOptions } from '@amazon/vinyl-util';
+import type { 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

package/dist/types/ts4.1/text/TextTrack.d.ts

@@ -0,0 +1,129 @@
+import type { ChangeEvent } from '../event/ChangeEvent';
+import type { ReadonlyEventHost } from '@amazon/vinyl-util';
+/**
+ * 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;
+}
+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;
+}
+/**
+ * Provides access to the text tracks of the current media and allows
+ * selecting one for playback.
+ *
+ * Selection is persisted across track changes only when applications choose
+ * to call {@link setActiveTextTrack} again on the new track. This matches
+ * how audio tracks are typically driven.
+ */
+export interface TextTrackController extends ReadonlyTextTrackController {
+    /**
+     * Selects the text track with the given id, or clears the active text
+     * track when called with null. No-op if the id does not match a known
+     * text track.
+     */
+    setActiveTextTrack(id: string | null): void;
+    /**
+     * Suspends cue rendering without changing the active selection: cancels any
+     * in-flight load and tears down 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 resume} rebuilds it.
+     */
+    suspend(): void;
+    /**
+     * Rebuilds the DOM text track for the active selection after a
+     * {@link suspend}, reloading its cues. No-op when nothing is active or when
+     * already rendering. Called when the owning media track is reactivated.
+     */
+    resume(): void;
+}
+//# sourceMappingURL=TextTrack.d.ts.map

package/dist/types/ts4.1/text/VttCueStyle.d.ts

@@ -0,0 +1,41 @@
+import type { 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/ts4.1/text/discoverDashTextTracks.d.ts

@@ -0,0 +1,24 @@
+import type { DashManifest } from '@amazon/vinyl-mpd-parser';
+import type { 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/ts4.1/text/discoverHlsTextTracks.d.ts

@@ -0,0 +1,19 @@
+import type { HlsMainPlaylist } from '@amazon/vinyl-hls-parser';
+import type { 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/ts4.1/text/parseWebVtt.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 result of parsing a WebVTT document.
+ */
+export interface WebVttDocument {
+    /**
+     * Parsed cues in document order.
+     */
+    readonly cues: readonly WebVttCue[];
+}
+/**
+ * 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 (skipped), cue identifiers, and HH:MM:SS.mmm or MM:SS.mmm timestamps.
+ * Cue settings on the timing line are tolerated and ignored.
+ *
+ * @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.
+ */
+export declare function parseWebVtt(input: string): WebVttDocument;
+//# sourceMappingURL=parseWebVtt.d.ts.map

package/dist/types/ts4.1/text/pickPreferredTextTrack.d.ts

@@ -0,0 +1,14 @@
+import type { TextTrackInfo } from './TextTrack';
+/**
+ * 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: string | readonly string[] | null): TextTrackInfo | null;
+//# sourceMappingURL=pickPreferredTextTrack.d.ts.map

package/dist/types/ts4.1/track/AutoResetController.d.ts

@@ -1,36 +1,60 @@
 import type { AnyRecord, Clearable, Disposable, ReadonlyEventHost } from '@amazon/vinyl-util';
 import { EventHostImpl } from '@amazon/vinyl-util';
 import type { PlaybackController } from '../playback/PlaybackController';
+import type { ChangeEvent } from '../event/ChangeEvent';
 export interface AutoResetControllerEventMap {
     /**
      * Notifies that playback errors should be reset and retried.
      */
     readonly reset: AnyRecord;
+    /**
+     * Dispatched when {@link AutoResetController.resetPending} changes.
+     */
+    readonly resetPendingChange: ChangeEvent<boolean>;
 }
 /**
- * Notifies when playback should be reset and retried.
+ * Notifies when playback should be reset and retried after a transient,
+ * potentially-recoverable error.
  *
- * The controller monitors for retry opportunities after an error is set:
- * - Immediately on network 'online' events
- * - After a timeout interval if online
+ * Once an eligible error is set, the controller watches for opportunities
+ * to emit a `reset` event:
+ * - Immediately when the network transitions back to online
+ * - After a timeout interval, if online and retries are not exhausted
  * - Immediately on user playback actions (play, pause, seeking, playing)
  *
- * Each error triggers a single timeout. If another error occurs after a reset,
- * setError() should be called again to schedule the next retry attempt.
+ * Each error triggers a single retry timeout. If another error occurs
+ * after a reset, {@link AutoResetController.setError} should be called again
+ * to schedule the next retry attempt.
  */
 export interface AutoResetController extends ReadonlyEventHost<AutoResetControllerEventMap>, Clearable {
     /**
-     * Sets the current playback error and begins monitoring for retry opportunities.
+     * Sets the current playback error and, if eligible, begins watching for
+     * retry opportunities.
+     *
+     * An error is eligible when it is a {@link RequestError} that did not
+     * receive an HTTP response (i.e. `response == null`), indicating a
+     * transient network failure such as connection loss or DNS failure.
+     * All other errors — including HTTP failures with a response (4xx/5xx),
+     * and non-RequestError errors — are ignored, since those are unlikely
+     * to recover on their own.
      *
-     * Only SERVICE_INTERNAL ReportableErrors are monitored. Subsequent calls while
-     * an error is already set are ignored until the error is cleared via reset or clear().
+     * Subsequent calls while an error is already set are ignored until the
+     * error is cleared via a reset emission or {@link Clearable.clear}.
      *
-     * After a reset, if another error occurs, this method should be called again
-     * to schedule the next retry attempt.
+     * After a reset, if another eligible error occurs, this method should
+     * be called again to schedule the next retry attempt.
      *
      * @param error The error to monitor for retry opportunities
      */
     setError(error: Error): void;
+    /**
+     * True while an eligible error is being watched and a `reset` event
+     * may still be emitted. Becomes false once the error is cleared, a
+     * reset is emitted, or all retries are exhausted.
+     *
+     * Listen to `resetPendingChange` events for changes.
+     */
+    readonly resetPending: boolean;
 }
 export interface AutoResetControllerImplDeps {
     readonly playbackController: PlaybackController;
@@ -75,7 +99,8 @@ export declare class AutoResetControllerImpl extends EventHostImpl<AutoResetCont
     private disposer;
     constructor(deps: AutoResetControllerImplDeps, options?: Partial<AutoResetControllerImplOptions>);
     setError(error: Error): void;
-    private setWatching;
+    get resetPending(): boolean;
+    private setResetPending;
     private reset;
     clear(): void;
     get disposed(): boolean;

package/dist/types/ts4.1/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/ts4.1/track/Track.d.ts

@@ -1,11 +1,18 @@
-import type { AnyRecord, Disposable, LogTarget, ReadonlyEventHost, ReadonlyRanges, ReadonlySet } from '@amazon/vinyl-util';
+import type { AnyRecord, Covariant, Disposable, EventHandler, LogTarget, Maybe, ReadonlyEventHost, ReadonlyRanges, ReadonlySet, SignalOptions, Unsubscribe } from '@amazon/vinyl-util';
 import type { ContentType, MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
 import type { StreamingEventMap } from '../streaming/StreamingEventMap';
+import type { ReadonlyTextTrackController, TextTrackController } from '../text/TextTrack';
+import type { SeekRange } from './SeekRange';
+import type { TrackAds } from '../ad/AdBreakInfo';
+import type { TrackConfigOptions } from './TrackFactory';
+export type { SeekRange } from './SeekRange';
 /**
  * All events a track may emit.
  * Streaming-related events are separated as they will be bubbled by the player.
  */
-export type TrackEventMap = StreamingEventMap;
+export type TrackEventMap = StreamingEventMap & {
+    readonly adsChange: AnyRecord;
+};
 /**
  * An identifier for a Track, used for referencing a track.
  */
@@ -93,10 +100,13 @@ export interface StreamingState extends ReadonlyStreamingState {
     /**
      * Resets the track to recover from error states.
      * This will reset failed segments and clear error conditions to allow streaming to resume.
+     *
+     * @param hard If true, the track will reset the playback state and
+     * recreate media sources.
      */
-    reset(): void;
+    reset(hard?: boolean): void;
 }
-export interface ReadonlyTrack extends ReadonlyStreamingState, LogTarget {
+export interface ReadonlyTrack extends ReadonlyEventHost<TrackEventMap>, ReadonlyStreamingState, LogTarget {
     /**
      * The track identifier.
      */
@@ -122,18 +132,44 @@ export interface ReadonlyTrack extends ReadonlyStreamingState, LogTarget {
      * The last error that occurred in this track, or null if no error.
      */
     readonly error: Error | null;
+    /**
+     * Controller for sidecar text tracks discovered for this track, or null
+     * if the track type does not surface text tracks.
+     */
+    readonly textTrackController: ReadonlyTextTrackController | null;
+    /**
+     * The seekable range on the media timeline, or null when not yet known
+     * (e.g. before the manifest is loaded). Based on the media timeline, not
+     * the element's native seekable ranges.
+     */
+    readonly seekRange: SeekRange | null;
+    /**
+     * Resolves to the ads for this track.
+     * The track's ads may change if the media timeline changes.
+     *
+     * @see {@link TrackEventMap} — the `adsChange` event.
+     */
+    getAds(): Promise<TrackAds>;
+    readonly __eventMapType: Covariant<TrackEventMap>;
+    hasListeners(type: keyof TrackEventMap): boolean;
+    on<K extends keyof TrackEventMap>(type: K, handler: EventHandler<TrackEventMap[K]>, options?: SignalOptions): Unsubscribe;
 }
 /**
  * One track is active on the track controller at a time.
  */
-export interface Track<LoadOptionsType extends AnyRecord = AnyRecord> extends ReadonlyTrack, StreamingState, Disposable {
+export interface Track<ConfigType extends TrackConfigOptions = TrackConfigOptions> extends ReadonlyTrack, StreamingState, Disposable {
+    /**
+     * Mutable view of {@link ReadonlyTrack.textTrackController} that allows
+     * selecting the active text track.
+     */
+    readonly textTrackController: TextTrackController | null;
     /**
      * Provides configuration to the track and begins preloading (if applicable).
      *
      * @param trackOptions Configuration provided by the TrackController.
      * @param loadOptions Configuration from `TrackLoadOptions.config`, provided by the Application.
      */
-    preload(trackOptions: TrackPreloadOptions, loadOptions: LoadOptionsType): void;
+    preload(trackOptions: TrackPreloadOptions, loadOptions: Maybe<ConfigType>): void;
     /**
      * Sets this track as active, deactivating any currently active track.
      * This should set sources on the playback source and add any listeners needed for shared
@@ -141,7 +177,7 @@ export interface Track<LoadOptionsType extends AnyRecord = AnyRecord> extends Re
      *
      * @param loadOptions Configuration from `TrackLoadOptions.config`, provided by the Application.
      */
-    activate(loadOptions: LoadOptionsType): void;
+    activate(loadOptions: Maybe<ConfigType>): void;
     /**
      * Sets this track as inactive.
      * This should unset sources, and remove any listeners. Tracks do not implement disposable,
@@ -149,5 +185,12 @@ export interface Track<LoadOptionsType extends AnyRecord = AnyRecord> extends Re
      * are no longer references to the track.
      */
     deactivate(): void;
+    /**
+     * True if this track is disposed.
+     */
+    readonly disposed: boolean;
+    readonly __eventMapType: Covariant<TrackEventMap>;
+    hasListeners(type: keyof TrackEventMap): boolean;
+    on<K extends keyof TrackEventMap>(type: K, handler: EventHandler<TrackEventMap[K]>, options?: SignalOptions): Unsubscribe;
 }
 //# sourceMappingURL=Track.d.ts.map