@vindral/web-sdk 4.1.10 → 4.2.0

package/legacy.d.ts

@@ -66,6 +66,10 @@ declare class Emitter<TEvents, TEmits = TEvents, ArgLessEvents extends VoidKeys<
 	 */
 	once<T extends ArgLessEvents>(eventName: T, fn: () => void): void;
 	once<T extends ArgEvents>(eventName: T, fn: (args: TEvents[T]) => void): void;
+	/**
+	 * Check whether there are any listeners registered for the given event.
+	 */
+	hasListeners<T extends keyof TEvents | keyof TEmits>(eventName: T): boolean;
 	/**
 	 * Reset the event emitter
 	 */
@@ -141,53 +145,6 @@ export interface ReconnectState {
 	 */
 	reconnectRetries: number;
 }
-interface RenditionProps {
-	id: number;
-	/** */
-	bitRate: number;
-	/** */
-	codecString?: string;
-	/** */
-	language?: string;
-	/** */
-	meta?: Record<string, string>;
-}
-interface VideoRenditionProps {
-	/** */
-	codec: VideoCodec;
-	/** */
-	frameRate: [
-		number,
-		number
-	];
-	/** */
-	width: number;
-	/** */
-	height: number;
-}
-interface AudioRenditionProps {
-	/** */
-	codec: AudioCodec;
-	/** */
-	channels: number;
-	/** */
-	sampleRate: number;
-}
-interface TextRenditionProps {
-	codec: "webvtt";
-	kind: "subtitles" | "captions";
-	label?: string;
-}
-/**
- * @interface
- */
-export type VideoRendition = VideoRenditionProps & RenditionProps;
-/**
- * @interface
- */
-export type AudioRendition = AudioRenditionProps & RenditionProps;
-type TextRendition = TextRenditionProps & RenditionProps;
-type Rendition = VideoRendition | AudioRendition | TextRendition;
 /**
  * Represents a size with a width and height.
  */
@@ -197,28 +154,10 @@ export interface Size {
 	/** */
 	height: number;
 }
-export interface VideoConstraint {
-	/** */
-	width: number;
-	/** */
-	height: number;
-	/** */
-	bitRate: number;
-	/** */
-	codec?: VideoCodec;
-	/** */
-	codecString?: string;
-}
 /**
  * Advanced options to override default behaviour.
  */
 export interface AdvancedOptions {
-	/**
-	 * Constrains wasm decoding to this resolution.
-	 * By default it is set to 1280 in width and height.
-	 * This guarantees better performance on older devices and reduces battery drain in general.
-	 */
-	wasmDecodingConstraint: Partial<VideoConstraint>;
 }
 /**
  * DRM options to provide to the Vindral instance
@@ -252,6 +191,7 @@ export interface DrmOptions {
  */
 export type Media = "audio" | "video" | "audio+video";
 type WebCodecsHardwareAccelerationPreference = "no-preference" | "prefer-hardware" | "prefer-software";
+type DecoderType = "mse" | "webcodecs" | "wasm";
 /**
  * Options for the Vindral instance
  *
@@ -322,11 +262,9 @@ export interface Options {
 	 */
 	burstEnabled?: boolean;
 	/**
-	 * Enable usage of the MediaSource API on supported browsers.
-	 *
-	 * Is enabled by default.
-	 *
-	 * Note: We recommend to keep this at the default value unless you have very specific needs.
+	 * @deprecated Use `decoders` instead.
+	 * Setting `mseEnabled: false` is equivalent to `decoders: ["wasm"]`.
+	 * When both `mseEnabled` and `decoders` are provided, `decoders` takes precedence.
 	 */
 	mseEnabled?: boolean;
 	/**
@@ -443,7 +381,7 @@ export interface Options {
 	 * The wake lock requires that the audio has been activated at least once for the instance, othwerwise it will not work.
 	 * Other devices already provide wake lock by default.
 	 *
-	 * This option is redundant and has no effect if iosMediaElementEnabled is enabled since that automatically enables wake lock.
+	 * This option is redundant and has no effect if streamToMediaElementEnabled is enabled since that automatically enables wake lock.
 	 *
 	 * Disabled by default.
 	 */
@@ -453,26 +391,20 @@ export interface Options {
 	 */
 	pauseSupportEnabled?: boolean;
 	/**
-	 * Enables iOS devices to use a media element for playback. This enables fullscreen and picture in picture support on iOS.
-	 */
-	iosMediaElementEnabled?: boolean;
-	/**
-	 * Enable WebCodecs API for hardware-accelerated decoding.
+	 * Stream canvas-rendered video/audio to a media element via captureStream.
 	 *
-	 * When enabled, the browser's native VideoDecoder and AudioDecoder APIs will be used instead
-	 * of WASM decoding on supported browsers (Chrome 94+, Edge 94+, Safari 16.4+). This provides:
-	 * - Hardware-accelerated decoding (uses GPU for video)
-	 * - Better performance at higher resolutions
-	 * - Lower CPU usage and battery consumption
+	 * This enables platform media features such as fullscreen and picture-in-picture
+	 * for non-MSE playback by routing the canvas output through a `<video>` element.
 	 *
-	 * Disabled by default to allow gradual rollout and testing.
+	 * Disabled by default.
+	 */
+	streamToMediaElementEnabled?: boolean;
+	/**
+	 * @deprecated Use `streamToMediaElementEnabled` instead.
 	 *
-	 * Note: Automatically falls back to WASM decoding if:
-	 * - The browser doesn't support WebCodecs
-	 * - WebCodecs initialization fails
-	 * - This option is set to false or undefined
+	 * Legacy alias kept for backwards compatibility.
 	 */
-	webcodecsEnabled?: boolean;
+	iosMediaElementEnabled?: boolean;
 	/**
 	 * Hardware acceleration preference for WebCodecs video decoding.
 	 *
@@ -480,14 +412,29 @@ export interface Options {
 	 */
 	webcodecsHardwareAcceleration?: WebCodecsHardwareAccelerationPreference;
 	/**
-	 * Enable OffscreenCanvas rendering in worker thread (requires webcodecsEnabled: true).
+	 * Enable OffscreenCanvas rendering in worker thread.
 	 *
 	 * When enabled, video rendering happens in the worker thread using OffscreenCanvas.
-	 * Disabled by default to allow gradual rollout and testing.
+	 * Automatically enabled when `decoders` resolves to WebCodecs. Set to `false`
+	 * to explicitly disable even when WebCodecs is active.
 	 *
-	 * Note: Requires browser support for OffscreenCanvas and webcodecsEnabled must be true, and iosMediaElementEnabled must be false.
+	 * Requires browser support for OffscreenCanvas and WebCodecs.
+	 * Works with `streamToMediaElementEnabled` for fullscreen/PiP support.
 	 */
 	offscreenCanvasEnabled?: boolean;
+	/**
+	 * Ordered list of decoders to try.
+	 *
+	 * The runtime walks the list and uses the first decoder that is available on the
+	 * current platform. When DRM is active, MSE is forced regardless of order.
+	 *
+	 * When omitted, the platform default order is used (`["mse", "wasm"]`).
+	 *
+	 * @example
+	 * // Prefer WebCodecs over MSE
+	 * decoders: ["webcodecs", "mse", "wasm"]
+	 */
+	decoders?: DecoderType[];
 	/**
 	 * Advanced options to override default behaviour.
 	 */
@@ -506,7 +453,6 @@ interface ClientOverrides {
 	burstEnabled?: boolean;
 	sizeBasedResolutionCapEnabled?: boolean;
 	separateVideoSocketEnabled?: boolean;
-	webcodecsEnabled?: boolean;
 	webcodecsHardwareAcceleration?: WebCodecsHardwareAccelerationPreference;
 	offscreenCanvasEnabled?: boolean;
 	videoCodecs?: string[];
@@ -550,6 +496,53 @@ interface TracksCatalog extends CatalogRoot {
 	namespace: Namespace;
 	tracks: Array<TrackObject>;
 }
+interface RenditionProps {
+	id: number;
+	/** */
+	bitRate: number;
+	/** */
+	codecString?: string;
+	/** */
+	language?: string;
+	/** */
+	meta?: Record<string, string>;
+}
+interface VideoRenditionProps {
+	/** */
+	codec: VideoCodec;
+	/** */
+	frameRate: [
+		number,
+		number
+	];
+	/** */
+	width: number;
+	/** */
+	height: number;
+}
+interface AudioRenditionProps {
+	/** */
+	codec: AudioCodec;
+	/** */
+	channels: number;
+	/** */
+	sampleRate: number;
+}
+interface TextRenditionProps {
+	codec: "webvtt";
+	kind: "subtitles" | "captions";
+	label?: string;
+}
+/**
+ * @interface
+ */
+export type VideoRendition = VideoRenditionProps & RenditionProps;
+/**
+ * @interface
+ */
+export type AudioRendition = AudioRenditionProps & RenditionProps;
+type TextRendition = TextRenditionProps & RenditionProps;
+type Rendition = VideoRendition | AudioRendition | TextRendition;
 interface Telemetry {
 	url: string;
 	probability?: number;
@@ -641,6 +634,18 @@ export interface RenditionLevelChanged {
 	/** */
 	reason: RenditionLevelChangedReason;
 }
+export interface VideoConstraint {
+	/** */
+	width: number;
+	/** */
+	height: number;
+	/** */
+	bitRate: number;
+	/** */
+	codec?: VideoCodec;
+	/** */
+	codecString?: string;
+}
 interface VindralErrorProps {
 	isFatal: boolean;
 	type?: ErrorType;
@@ -864,6 +869,13 @@ interface DecoderStatistics {
 	videoDecodeTime: MinMaxAverage;
 	audioDecodeTime: MinMaxAverage;
 	videoTransportTime: MinMaxAverage;
+	videoKeyframeIntervalMs?: number;
+	renderedFrameCount?: number;
+	rendererDroppedFrameCount?: number;
+	videoRenderer?: "OffscreenCanvas" | "Canvas" | "MSE";
+	videoDecoder?: "WebCodecs" | "WASM" | "MSE";
+	audioRenderer?: "AudioContext" | "MSE";
+	audioDecoder?: "WebCodecs" | "WASM" | "MSE";
 }
 interface DocumentStateModulesStatistics {
 	isVisible: boolean;
@@ -913,6 +925,11 @@ interface MseModuleStatistics {
 	droppedVideoFrames?: number;
 	successfulVideoAppendCalls?: number;
 	successfulAudioAppendsCalls?: number;
+	videoKeyframeIntervalMs?: number;
+	videoRenderer?: "OffscreenCanvas" | "Canvas" | "MSE";
+	videoDecoder?: "WebCodecs" | "WASM" | "MSE";
+	audioRenderer?: "AudioContext" | "MSE";
+	audioDecoder?: "WebCodecs" | "WASM" | "MSE";
 }
 interface QualityOfServiceModuleStatistics {
 	/**
@@ -993,8 +1010,6 @@ interface SyncModuleStatistics {
 interface VideoPlayerStatistics {
 	renderedFrameCount: number;
 	rendererDroppedFrameCount: number;
-	contextLostCount: number;
-	contextRestoredCount: number;
 }
 type ModuleStatistics = AdaptivityStatistics & BufferTimeStatistics & ConnectionStatistics & ConstraintCapStatistics & DecoderStatistics & DocumentStateModulesStatistics & IncomingDataModuleStatistics & JitterModuleStatistics & MseModuleStatistics & PlaybackModuleStatistics & QualityOfServiceModuleStatistics & RenditionsModuleStatistics & SyncModuleStatistics & TelemetryModuleStatistics & VideoPlayerStatistics;
 /**
@@ -1045,6 +1060,8 @@ export type Statistics = ModuleStatistics & ReturnType<UserAgentInformation["get
 	 * Note that an actual frame render often happens much quicker, but that is not counted as TTFF.
 	 */
 	timeToFirstFrame?: number;
+	streamToMediaElementEnabled?: boolean;
+	/** @deprecated */
 	iosMediaElementEnabled?: boolean;
 	/**
 	 * Average bitrate for the entire session in bits/second.
@@ -1147,6 +1164,8 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	private clientId;
 	private _channels;
 	private createdAt;
+	private offscreenCanvasElement?;
+	private webCodecsRenditionSupport;
 	private hasCalledConnect;
 	private latestEmittedLanguages;
 	private wakeLock;
@@ -1157,6 +1176,7 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	private sizes;
 	private isSuspended;
 	private disconnectTimeout;
+	private offscreenSubtitleInterval?;
 	constructor(options: Options);
 	/**
 	 * Attaches the video view to a DOM element. The Vindral video view will be sized to fill this element while
@@ -1165,6 +1185,7 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	 * @returns
 	 */
 	attach: (container: HTMLElement) => void;
+	private setElement;
 	/**
 	 * Set the current volume.
 	 * Setting this to 0 is not equivalent to muting the audio.
@@ -1385,6 +1406,10 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	 * The ranges are specified in milliseconds.
 	 */
 	get audioBufferedRanges(): ReadonlyArray<TimeRange>;
+	/**
+	 * The timestamps (in milliseconds) of video keyframes currently in the buffer.
+	 */
+	get videoKeyframeTimestamps(): ReadonlyArray<number>;
 	/**
 	 * The API client for calls to the public available endpoints of the Vindral Live CDN.
 	 */
@@ -1444,9 +1469,16 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	private isSupportedVideoCodecProfile;
 	private supportedAudioCodecs;
 	private initializeDecodingModule;
+	/**
+	 * Set up a polling interval that forwards subtitle cues to the decoder worker
+	 * when OffscreenCanvas rendering is active. This is needed because the canvas modules'
+	 * own subtitle intervals either get killed (LegacyCanvasModule) or don't have the
+	 * OffscreenCanvas reference at construction time (ModernCanvasModule).
+	 */
+	private setupOffscreenSubtitleRouting;
 	/**
 	 * Fully unloads the instance. This disconnects the clients and stops any background tasks.
-	 * This client instance can not be used after this has been called.
+	 * This client instance cannot be used after this has been called.
 	 */
 	unload: () => Promise<void>;
 	/**
@@ -1510,7 +1542,17 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	private get currentSubscription();
 	private get targetSubscription();
 	private timeToFirstFrame;
+	private resolvedDecoder;
 	private willUseMediaSource;
+	private shouldUseWebCodecs;
+	private isWebCodecsVideoAvailable;
+	private isWebCodecsAudioAvailable;
+	/**
+	 * Returns true if OffscreenCanvas should be used.
+	 * Implicitly enabled when the resolved decoder is WebCodecs, since OffscreenCanvas
+	 * is the optimal rendering path for WebCodecs (worker renders VideoFrames directly).
+	 */
+	private shouldUseOffscreenCanvas;
 }
 interface TelemetryModuleStatistics {
 	/**
@@ -1590,6 +1632,12 @@ interface TimeShiftInfo {
 	urls: string[];
 	duration: string;
 }
+interface CmafFragmentEvent {
+	mediaType: "video" | "audio";
+	initSegment: Readonly<Uint8Array<ArrayBuffer>>;
+	fragment: Readonly<Uint8Array<ArrayBuffer>>;
+	isKeyframe: boolean;
+}
 /**
  * The events that can be emitted from the Vindral instance
  */
@@ -1693,6 +1741,13 @@ export interface PublicVindralEvents {
 	 * Emitted when the timeshift URLs are updated.
 	 */
 	["timeshift info"]: Readonly<TimeShiftInfo>;
+	/**
+	 * Emitted for each CMAF fragment received via the MoQ/VoQ path.
+	 * Contains raw fMP4 bytes suitable for recording.
+	 *
+	 * @internal Not part of the public API — may change without notice.
+	 */
+	["cmaf fragment"]: Readonly<CmafFragmentEvent>;
 	["buffer state event"]: Readonly<BufferStateEvent>;
 	["initialized media"]: void;
 }