@amazon/vinyl 1.1.1 → 2.0.0

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

@@ -1,7 +1,15 @@
 import { AnyRecord, Disposable, EventHostImpl, Json, LogTarget, ReadonlyEventHost, ReportableError } from '@amazon/vinyl-util';
-import { ContentTypesValue } from '../../streaming/ContentTypesValue';
+import { ObservableValue } from '@amazon/vinyl-observable';
+import { ContentTypesValue } from '../ContentTypesValue';
 import { BasicErrorEvent } from '../../event/BasicErrorEvent';
-import { ContentType } from '../../streaming/MediaQualityMetadata';
+import { ContentType } from '../MediaQualityMetadata';
+import { MediaTimeline } from '../MediaTimeline';
+/**
+ * Chrome 52 has decoding errors when duration is set to the mediaPresentationDuration.
+ * Adds a slight padding as a workaround.
+ * @private
+ */
+export declare const DURATION_PADDING = 0.1;
 export interface SourceBufferRef extends Disposable {
     /**
      * The source buffer.
@@ -22,7 +30,8 @@ export interface MediaSourceControllerEventMap {
      */
     readonly sourceOpen: AnyRecord;
     /**
-     * All source buffers have been created and data may be appended.
+     * All source buffers have been created, the media source duration has been set, and data
+     * may be appended.
      */
     readonly readyToAppend: AnyRecord;
     /**
@@ -35,20 +44,12 @@ export interface ReadonlyMediaSourceController extends ReadonlyEventHost<MediaSo
      * Returns the parent media source ready state.
      */
     readonly readyState: ReadyState;
-    /**
-     * Gets the media source's duration.
-     */
-    readonly duration: number;
     /**
      * True if all source buffers have been created and data may be appended.
      */
     readonly readyToAppend: boolean;
 }
 export interface MediaSourceController extends ReadonlyMediaSourceController {
-    /**
-     * Sets/gets the media source's duration.
-     */
-    duration: number;
     /**
      * Constructs a new SourceBuffer with the given content type and mime type.
      */
@@ -59,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 {
     /**
@@ -72,25 +81,47 @@ export interface MediaSourceControllerImplDeps {
      * Provides the streams that must be created before appending.
      */
     readonly contentTypesValue: ContentTypesValue;
+    /**
+     * The media timeline used to determine duration.
+     */
+    readonly mediaTimelineTransformed: ObservableValue<Promise<MediaTimeline>>;
 }
 export declare class MediaSourceControllerImpl extends EventHostImpl<MediaSourceControllerEventMap> implements MediaSourceController, LogTarget {
+    private readonly deps;
     get [Symbol.toStringTag](): string;
-    private sourceBufferCount;
-    private readonly mediaSource;
-    private readonly disposer;
+    private readonly sourceBuffers;
+    private mediaSource;
+    private objectUrl;
+    private activateDisposer;
     private contentTypes;
+    private durationSet;
+    /**
+     * Token for the in-flight duration update; used to discard stale results when
+     * the timeline changes or the source closes mid-fetch.
+     */
+    private durationToken;
     constructor(deps: MediaSourceControllerImplDeps);
-    private initializeEvents;
-    get duration(): number;
-    set duration(value: number);
+    get active(): boolean;
+    activate(): string;
+    deactivate(): void;
+    private get sourceBufferCount();
+    private readonly errorHandler;
+    /**
+     * Sets the duration on the media source from the current media timeline.
+     * Live streams use LIVE_DURATION since not all browsers support +Infinity duration.
+     *
+     * MSE throws InvalidStateError if duration is set while any source buffer is updating,
+     * so we wait for all tracked source buffers to be idle first.
+     */
+    private refreshDuration;
     get readyState(): ReadyState;
     createSourceBuffer(contentType: ContentType, mimeType: string): SourceBufferRef;
     /**
-     * Emits a 'readyToAppend' event if all source buffers have been created.
+     * Emits a 'readyToAppend' event if all source buffers have been created and the duration
+     * has been applied to the media source.
      */
     private readonly checkReady;
     endOfStream(error?: EndOfStreamError): void;
-    createUrl(): string;
     get readyToAppend(): boolean;
     dispose(): void;
 }

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

@@ -1,6 +1,6 @@
 import { Disposable, LogTarget, ReadonlyRanges, Task } from '@amazon/vinyl-util';
 import { MediaSourceController } from './MediaSourceController';
-import { ContentType } from '../../streaming/MediaQualityMetadata';
+import { ContentType } from '../MediaQualityMetadata';
 export declare const APPEND_WINDOW_START_OFFSET = 0.05;
 export declare const APPEND_WINDOW_END_OFFSET = 0.01;
 export declare const READY_TO_APPEND_TIMEOUT = 30;

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

@@ -1,13 +1,16 @@
 import { ObservableValue } from '@amazon/vinyl-observable';
 import { Capabilities } from '../client/Capabilities';
 import { DrmController } from '../drm/DrmController';
-import { MediaTimeline } from '../streaming/MediaTimeline';
+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/mediaTimelineFilter.d.ts

@@ -1,5 +1,5 @@
-import { MediaTimeline } from '../streaming/MediaTimeline';
-import { MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
+import { MediaTimeline } from './MediaTimeline';
+import { MediaQualityMetadata } from './MediaQualityMetadata';
 import { FilterPredicate, FilterPredicateAsync, Maybe } from '@amazon/vinyl-util';
 /**
  * Filters qualities in a MediaTimeline using a synchronous predicate.
@@ -14,5 +14,5 @@ export declare function filterTimelineQualitiesAsync(filter: FilterPredicateAsyn
 /**
  * Creates a language filter predicate for use with filterTimelineQualities.
  */
-export { createLanguageFilter } from '../streaming/mediaTimelineLanguageFilter';
+export { createLanguageFilter } from './mediaTimelineLanguageFilter';
 //# sourceMappingURL=mediaTimelineFilter.d.ts.map

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

@@ -1,14 +1,32 @@
-import { MediaQualityMetadata } from '../streaming/MediaQualityMetadata';
+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/streaming/util/segment.d.ts

@@ -1,4 +1,4 @@
-import { MediaSegmentMetadata } from '../../streaming/SegmentReference';
+import { 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/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

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

@@ -0,0 +1,129 @@
+import { ChangeEvent } from '../event/ChangeEvent';
+import { 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/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