@vindral/web-sdk 4.1.10 → 4.2.0-10-g4d54d36c

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.1.10",
+  "version": "4.2.0-10-g4d54d36c",
   "name": "@vindral/web-sdk",
   "main": "./legacy.umd.js",
   "module": "./legacy.es.js",

package/player.d.ts

@@ -63,6 +63,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
 	 */
@@ -135,72 +139,13 @@ 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;
-}
-type VideoRendition = VideoRenditionProps & RenditionProps;
-type AudioRendition = AudioRenditionProps & RenditionProps;
-type TextRendition = TextRenditionProps & RenditionProps;
-type Rendition = VideoRendition | AudioRendition | TextRendition;
 interface Size {
 	/** */
 	width: number;
 	/** */
 	height: number;
 }
-interface VideoConstraint {
-	/** */
-	width: number;
-	/** */
-	height: number;
-	/** */
-	bitRate: number;
-	/** */
-	codec?: VideoCodec;
-	/** */
-	codecString?: string;
-}
 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>;
 }
 interface DrmOptions {
 	/**
@@ -228,6 +173,7 @@ interface DrmOptions {
 }
 type Media = "audio" | "video" | "audio+video";
 type WebCodecsHardwareAccelerationPreference = "no-preference" | "prefer-hardware" | "prefer-software";
+type DecoderType = "mse" | "webcodecs" | "wasm";
 interface Options {
 	/**
 	 * URL to use when connecting to the stream
@@ -294,11 +240,9 @@ 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;
 	/**
@@ -415,7 +359,7 @@ 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.
 	 */
@@ -425,26 +369,20 @@ 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.
 	 *
@@ -452,14 +390,29 @@ 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.
 	 */
@@ -478,7 +431,6 @@ interface ClientOverrides {
 	burstEnabled?: boolean;
 	sizeBasedResolutionCapEnabled?: boolean;
 	separateVideoSocketEnabled?: boolean;
-	webcodecsEnabled?: boolean;
 	webcodecsHardwareAcceleration?: WebCodecsHardwareAccelerationPreference;
 	offscreenCanvasEnabled?: boolean;
 	videoCodecs?: string[];
@@ -522,6 +474,47 @@ 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;
+}
+type VideoRendition = VideoRenditionProps & RenditionProps;
+type AudioRendition = AudioRenditionProps & RenditionProps;
+type TextRendition = TextRenditionProps & RenditionProps;
+type Rendition = VideoRendition | AudioRendition | TextRendition;
 interface Telemetry {
 	url: string;
 	probability?: number;
@@ -785,6 +778,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;
@@ -834,6 +834,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 {
 	/**
@@ -914,8 +919,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;
 type Statistics = ModuleStatistics & ReturnType<UserAgentInformation["getUserAgentInformation"]> & {
@@ -958,6 +961,8 @@ type Statistics = ModuleStatistics & ReturnType<UserAgentInformation["getUserAge
 	 * 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.
@@ -1024,6 +1029,8 @@ declare class Vindral extends Emitter<PublicVindralEvents> {
 	private clientId;
 	private _channels;
 	private createdAt;
+	private offscreenCanvasElement?;
+	private webCodecsRenditionSupport;
 	private hasCalledConnect;
 	private latestEmittedLanguages;
 	private wakeLock;
@@ -1034,6 +1041,7 @@ 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
@@ -1042,6 +1050,7 @@ 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.
@@ -1152,6 +1161,14 @@ declare class Vindral extends Emitter<PublicVindralEvents> {
 	 * setting targetBufferTime within that range for consistancy if using both min/max.
 	 */
 	set targetBufferTime(bufferTimeMs: number);
+	/**
+	 * Update the dynamic buffer time configuration at runtime.
+	 * Allows adjusting min and max buffer time without recreating the Vindral instance.
+	 */
+	updateBufferTimeConfig(config: {
+		minBufferTime?: number;
+		maxBufferTime?: number;
+	}): void;
 	/**
 	 * The estimated playback latency based on target buffer time, the connection rtt and local playback drift
 	 */
@@ -1262,6 +1279,10 @@ 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.
 	 */
@@ -1321,9 +1342,16 @@ 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>;
 	/**
@@ -1387,7 +1415,17 @@ 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 {
 	/**
@@ -1451,6 +1489,12 @@ interface TimeShiftInfo {
 	urls: string[];
 	duration: string;
 }
+interface CmafFragmentEvent {
+	mediaType: "video" | "audio";
+	initSegment: Readonly<Uint8Array<ArrayBuffer>>;
+	fragment: Readonly<Uint8Array<ArrayBuffer>>;
+	isKeyframe: boolean;
+}
 interface PublicVindralEvents {
 	/**
 	 * When an error that requires action has occured
@@ -1551,6 +1595,13 @@ 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;
 }
@@ -1787,7 +1838,7 @@ type ControllerAttributes = (typeof Controller.observedAttributes)[number];
 export declare class Controller extends HTMLElement {
 	#private;
 	static observedAttributes: readonly [
-		...("language" | "channels" | "buffering" | "paused" | "volume" | "muted" | "duration" | "user-interacting" | "is-casting" | "cast-available" | "cast-receiver-name" | "ui-locked" | "hide-ui-on-pause" | "is-fullscreen" | "is-fullscreen-fallback" | "rendition-levels" | "rendition-level" | "max-video-bit-rate" | "max-initial-bit-rate" | "abr-enabled" | "size-based-resolution-cap-enabled" | "channel-id" | "channel-group-id" | "pip-available" | "is-pip" | "airplay-available" | "is-airplaying" | "media" | "languages" | "text-tracks" | "text-track" | "needs-user-input-video" | "needs-user-input-audio" | "authentication-token" | "volume-level" | "cast" | "airplay" | "pip" | "fullscreen" | "vu-meter" | "timeshift" | "timeshift-position" | "poster-src")[],
+		...("language" | "channels" | "buffering" | "paused" | "volume" | "muted" | "duration" | "user-interacting" | "is-casting" | "cast-available" | "cast-receiver-name" | "ui-locked" | "hide-ui-on-pause" | "is-fullscreen" | "is-fullscreen-fallback" | "rendition-levels" | "rendition-level" | "max-video-bit-rate" | "max-initial-bit-rate" | "abr-enabled" | "size-based-resolution-cap-enabled" | "channel-id" | "channel-group-id" | "pip-available" | "is-pip" | "airplay-available" | "is-airplaying" | "media" | "languages" | "text-tracks" | "text-track" | "needs-user-input-video" | "needs-user-input-audio" | "authentication-token" | "volume-level" | "cast" | "airplay" | "pip" | "fullscreen" | "vu-meter" | "timeshift" | "timeshift-position" | "poster-src" | "debug-panel-open" | "target-buffer-time" | "drift" | "playback-latency" | "connection-state")[],
 		"url",
 		"edge-url",
 		"target-buffer-time",
@@ -1804,6 +1855,7 @@ export declare class Controller extends HTMLElement {
 		"mse-opus-enabled",
 		"ios-background-play-enabled",
 		"ios-wake-lock-enabled",
+		"stream-to-media-element-enabled",
 		"ios-media-element-enabled",
 		"abr-enabled",
 		"size-based-resolution-cap-enabled",
@@ -1818,8 +1870,8 @@ export declare class Controller extends HTMLElement {
 		"drm-playready-video-robustness",
 		"drm-playready-audio-robustness",
 		"webtransport-enabled",
-		"webcodecs-enabled",
 		"webcodecs-hardware-acceleration",
+		"decoders",
 		"offscreen-canvas-enabled",
 		"reconnect-retries",
 		"auto-instance-enabled",
@@ -1908,7 +1960,7 @@ export declare class PlayButton extends VindralButton {
  */
 export declare class Player extends HTMLElement {
 	#private;
-	static observedAttributes: readonly ("title" | "offline" | "advanced" | "poster" | "language" | "channels" | "buffering" | "paused" | "volume" | "muted" | "duration" | "user-interacting" | "is-casting" | "cast-available" | "cast-receiver-name" | "ui-locked" | "hide-ui-on-pause" | "is-fullscreen" | "is-fullscreen-fallback" | "rendition-levels" | "rendition-level" | "max-video-bit-rate" | "max-initial-bit-rate" | "abr-enabled" | "size-based-resolution-cap-enabled" | "channel-id" | "channel-group-id" | "pip-available" | "is-pip" | "airplay-available" | "is-airplaying" | "media" | "languages" | "text-tracks" | "text-track" | "needs-user-input-video" | "needs-user-input-audio" | "authentication-token" | "volume-level" | "cast" | "airplay" | "pip" | "fullscreen" | "vu-meter" | "timeshift" | "timeshift-position" | "poster-src" | "url" | "edge-url" | "target-buffer-time" | "cast-receiver-id" | "cast-background" | "log-level" | "max-size" | "min-buffer-time" | "max-buffer-time" | "max-audio-bit-rate" | "burst-enabled" | "mse-enabled" | "mse-opus-enabled" | "ios-background-play-enabled" | "ios-wake-lock-enabled" | "ios-media-element-enabled" | "telemetry-enabled" | "video-codecs" | "drm-headers" | "drm-queryparams" | "drm-widevine-video-robustness" | "drm-widevine-audio-robustness" | "drm-playready-video-robustness" | "drm-playready-audio-robustness" | "webtransport-enabled" | "webcodecs-enabled" | "webcodecs-hardware-acceleration" | "offscreen-canvas-enabled" | "reconnect-retries" | "auto-instance-enabled" | "advanced-rendition-menu-enabled" | "refresh-poster-enabled" | "stream-poll-enabled")[];
+	static observedAttributes: readonly ("title" | "offline" | "advanced" | "poster" | "language" | "channels" | "buffering" | "paused" | "volume" | "muted" | "duration" | "user-interacting" | "is-casting" | "cast-available" | "cast-receiver-name" | "ui-locked" | "hide-ui-on-pause" | "is-fullscreen" | "is-fullscreen-fallback" | "rendition-levels" | "rendition-level" | "max-video-bit-rate" | "max-initial-bit-rate" | "abr-enabled" | "size-based-resolution-cap-enabled" | "channel-id" | "channel-group-id" | "pip-available" | "is-pip" | "airplay-available" | "is-airplaying" | "media" | "languages" | "text-tracks" | "text-track" | "needs-user-input-video" | "needs-user-input-audio" | "authentication-token" | "volume-level" | "cast" | "airplay" | "pip" | "fullscreen" | "vu-meter" | "timeshift" | "timeshift-position" | "poster-src" | "debug-panel-open" | "target-buffer-time" | "drift" | "playback-latency" | "connection-state" | "url" | "decoders" | "min-buffer-time" | "max-buffer-time" | "edge-url" | "cast-receiver-id" | "cast-background" | "log-level" | "max-size" | "max-audio-bit-rate" | "burst-enabled" | "mse-enabled" | "mse-opus-enabled" | "ios-background-play-enabled" | "ios-wake-lock-enabled" | "stream-to-media-element-enabled" | "ios-media-element-enabled" | "telemetry-enabled" | "video-codecs" | "drm-headers" | "drm-queryparams" | "drm-widevine-video-robustness" | "drm-widevine-audio-robustness" | "drm-playready-video-robustness" | "drm-playready-audio-robustness" | "webtransport-enabled" | "webcodecs-hardware-acceleration" | "offscreen-canvas-enabled" | "reconnect-retries" | "auto-instance-enabled" | "advanced-rendition-menu-enabled" | "refresh-poster-enabled" | "stream-poll-enabled")[];
 	constructor();
 	connectedCallback(): void;
 	disconnectedCallback(): void;
@@ -2025,6 +2077,14 @@ export declare class VolumeRange extends VindralRange {
  * Register custom elements for the Vindral player
  */
 export declare function registerComponents(): void;
+/**
+ * Register debug custom elements for the Vindral player.
+ *
+ * Call this in addition to `registerComponents()` to enable the debug button and panel.
+ * Without calling this, `<vindral-debug-button>` and `<vindral-debug-panel>` remain
+ * inert and the debug code is tree-shaken from the bundle.
+ */
+export declare function registerDebugComponents(): void;
 /**
  * @ignore
  */