@vindral/web-sdk 4.5.1-9-gb7e40eb2c → 4.6.0

package/cast-sender.d.ts

@@ -98,6 +98,17 @@ interface DrmOptions {
 type Media = "audio" | "video" | "audio+video";
 type WebCodecsHardwareAccelerationPreference = "no-preference" | "prefer-hardware" | "prefer-software";
 type DecoderType = "mse" | "webcodecs" | "wasm";
+interface MediaSessionMetadata {
+	title?: string;
+	artist?: string;
+	album?: string;
+	/** Fetched by the operating system, so the URLs should not carry credentials. */
+	artwork?: Array<{
+		src: string;
+		sizes?: string;
+		type?: string;
+	}>;
+}
 interface Options {
 	/**
 	 * URL to use when connecting to the stream
@@ -193,6 +204,20 @@ interface Options {
 	 * Legacy alias kept for backwards compatibility.
 	 */
 	iosBackgroundPlayEnabled?: boolean;
+	/**
+	 * Show the stream in the browser and OS media controls (notification, lock screen, toolbar) and
+	 * let play and pause from there reach the SDK. Enabled by default.
+	 *
+	 * The SDK takes over `navigator.mediaSession` for the document, so a page with its own Media
+	 * Session integration should disable this. On canvas playback paths a silent `<audio>` element is
+	 * added to `document.body` for the controls to attach to.
+	 */
+	mediaSessionEnabled?: boolean;
+	/**
+	 * Title, artist and artwork for the media controls. Without it the browser derives them from the
+	 * page. Read once at construction.
+	 */
+	mediaSessionMetadata?: MediaSessionMetadata;
 	/**
 	 * Enable or disable Adaptive Bit Rate. This allows for automatically adapting the incoming bit rate based on
 	 * the viewers bandwidth and thus avoiding buffering events. This also disables the
@@ -307,6 +332,9 @@ interface Options {
 	 * 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.
 	 *
+	 * On iOS the audio then plays from its own element, so it continues in the background and under
+	 * lock. After an extended pause from the lock screen, reopening Safari may be required to resume.
+	 *
 	 * Disabled by default.
 	 */
 	streamToMediaElementEnabled?: boolean;

package/core.d.ts

@@ -189,6 +189,18 @@ export interface DrmOptions {
 export type Media = "audio" | "video" | "audio+video";
 type WebCodecsHardwareAccelerationPreference = "no-preference" | "prefer-hardware" | "prefer-software";
 type DecoderType = "mse" | "webcodecs" | "wasm";
+/** What the OS media controls show for the stream. Mirrors the `MediaMetadata` fields. */
+export interface MediaSessionMetadata {
+	title?: string;
+	artist?: string;
+	album?: string;
+	/** Fetched by the operating system, so the URLs should not carry credentials. */
+	artwork?: Array<{
+		src: string;
+		sizes?: string;
+		type?: string;
+	}>;
+}
 /**
  * Options for the Vindral instance
  *
@@ -288,6 +300,20 @@ export interface Options {
 	 * Legacy alias kept for backwards compatibility.
 	 */
 	iosBackgroundPlayEnabled?: boolean;
+	/**
+	 * Show the stream in the browser and OS media controls (notification, lock screen, toolbar) and
+	 * let play and pause from there reach the SDK. Enabled by default.
+	 *
+	 * The SDK takes over `navigator.mediaSession` for the document, so a page with its own Media
+	 * Session integration should disable this. On canvas playback paths a silent `<audio>` element is
+	 * added to `document.body` for the controls to attach to.
+	 */
+	mediaSessionEnabled?: boolean;
+	/**
+	 * Title, artist and artwork for the media controls. Without it the browser derives them from the
+	 * page. Read once at construction.
+	 */
+	mediaSessionMetadata?: MediaSessionMetadata;
 	/**
 	 * Enable or disable Adaptive Bit Rate. This allows for automatically adapting the incoming bit rate based on
 	 * the viewers bandwidth and thus avoiding buffering events. This also disables the
@@ -402,6 +428,9 @@ export interface Options {
 	 * 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.
 	 *
+	 * On iOS the audio then plays from its own element, so it continues in the background and under
+	 * lock. After an extended pause from the lock screen, reopening Safari may be required to resume.
+	 *
 	 * Disabled by default.
 	 */
 	streamToMediaElementEnabled?: boolean;
@@ -913,6 +942,13 @@ interface JitterModuleStatistics {
 	audioJitter: JitterStatistics | undefined;
 	videoJitter: JitterStatistics | undefined;
 }
+type DecoyState = "detached" | "attached" | "playing" | "blocked";
+interface MediaSessionModuleStatistics {
+	mediaSessionSupported: boolean;
+	mediaSessionOwner: boolean;
+	mediaSessionPlaybackState: MediaSessionPlaybackState;
+	decoyState?: DecoyState;
+}
 interface MseModuleStatistics {
 	quotaErrorCount: number;
 	mediaSourceOpenTime: number;
@@ -1024,8 +1060,10 @@ interface SyncModuleStatistics {
 interface VideoPlayerStatistics {
 	renderedFrameCount: number;
 	rendererDroppedFrameCount: number;
+	/** The platform's own view of the audio context, which a mute reading cannot tell apart. */
+	audioContextState?: AudioContextState | "none";
 }
-type ModuleStatistics = AdaptivityStatistics & BufferTimeStatistics & ConnectionStatistics & ConstraintCapStatistics & DecoderStatistics & DocumentStateModulesStatistics & IncomingDataModuleStatistics & JitterModuleStatistics & MseModuleStatistics & PlaybackModuleStatistics & QualityOfServiceModuleStatistics & RenditionsModuleStatistics & SyncModuleStatistics & TelemetryModuleStatistics & VideoPlayerStatistics;
+type ModuleStatistics = AdaptivityStatistics & BufferTimeStatistics & ConnectionStatistics & ConstraintCapStatistics & DecoderStatistics & DocumentStateModulesStatistics & IncomingDataModuleStatistics & JitterModuleStatistics & Partial<MediaSessionModuleStatistics> & MseModuleStatistics & PlaybackModuleStatistics & QualityOfServiceModuleStatistics & RenditionsModuleStatistics & SyncModuleStatistics & TelemetryModuleStatistics & VideoPlayerStatistics;
 /**
  * Contains internal statistics.
  *
@@ -1085,6 +1123,8 @@ export type Statistics = ModuleStatistics & ReturnType<UserAgentInformation["get
 	streamToMediaElementEnabled?: boolean;
 	/** @deprecated */
 	iosMediaElementEnabled?: boolean;
+	/** Whether the element carrying the audio is paused right now, on the sinks that have one. */
+	mediaElementPaused?: boolean;
 	/**
 	 * Average bitrate for the entire session in bits/second.
 	 */
@@ -1106,11 +1146,49 @@ export type Statistics = ModuleStatistics & ReturnType<UserAgentInformation["get
 	 */
 	timeshiftAdjustmentsPerMinute: number;
 };
+/**
+ * Represents a Vindral client instance
+ *
+ * The most most essential methods when using the Vindral class are:
+ *
+ * - connect() - this has to be called to actually start connecting
+ * - attach() - to attach the Vindral video view to the DOM so that users can see it
+ * - userInput() - to activate audio on browsers that require a user gesture to play audio
+ * - unload() - unloads the instance, its very important that this is called when cleaning up the Vindral instance, otherwise background timers may leak.
+ *
+ * The Vindral instance will emit a variety of events during its lifetime. Use .on("event-name", callback) to listen to these events.
+ * See [[PublicVindralEvents]] for the events types that can be emitted.
+ *
+ * ```typescript
+ * // minimal configuration of a Vindral client instance
+ * const instance = new Vindral({
+ *   url: "https://lb.cdn.vindral.com",
+ *   channelId: "vindral_demo1_ci_099ee1fa-80f3-455e-aa23-3d184e93e04f",
+ * })
+ *
+ * // Will be called when timed metadata is received
+ * instance.on("metadata", console.log)
+ *
+ * // Will be called when a user interaction is needed to activate audio
+ * instance.on("needs user input", console.log)
+ *
+ * // Start connecting to the cdn
+ * instance.connect()
+ *
+ * // Attach the video view to the DOM
+ * instance.attach(document.getElementById("root"))
+ *
+ * // When done with the instance
+ * instance.unload()
+ * ```
+ */
 export declare class Vindral extends Emitter<PublicVindralEvents> {
 	#private;
 	private static MAX_POOL_SIZE;
 	private static REMOVE_CUE_THRESHOLD;
 	private static BACKGROUND_INACTIVITY_DISCONNECT_TIMEOUT;
+	/** How long a pause on a visible page may still turn out to be the platform backgrounding us. */
+	private static VISIBLE_PAUSE_DISCONNECT_DELAY;
 	/**
 	 * Picture in picture
 	 */
@@ -1153,7 +1231,10 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	private offscreenCanvasElement?;
 	private webCodecsRenditionSupport;
 	private hasCalledConnect;
+	private hasRequestedAudioSession;
 	private isUserPaused;
+	/** Only the sinks that carry the audio report this, so a paused element here means silence. */
+	private isMediaElementPaused;
 	private latestEmittedLanguages;
 	private wakeLock;
 	private pool;
@@ -1169,6 +1250,7 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	private sizes;
 	private isSuspended;
 	private inactivityDisconnectInterval;
+	private visiblePauseTimeout;
 	private offscreenSubtitleInterval?;
 	constructor(options: Options);
 	/**
@@ -1470,6 +1552,8 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	private isSupportedVideoCodecProfile;
 	private supportedAudioCodecs;
 	private initializeDecodingModule;
+	private capturesCanvasOnWebKit;
+	private connectWebKitVideoOutput;
 	/**
 	 * 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'
@@ -1501,6 +1585,12 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	 * Pauses the stream. Call .play() to resume playback again.
 	 */
 	pause: () => void;
+	/**
+	 * A browser-initiated decoy pause means an interruption (another app took the focus, headphones
+	 * unplugged), so give the audio up rather than play over it. WebKit holds the decoy on purpose.
+	 */
+	private yieldToInterruption;
+	private fromNativeControls;
 	private registerDebugInstance;
 	/**
 	 *
@@ -1533,8 +1623,18 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	private resetModules;
 	private disconnectForInactivePage;
 	private scheduleInactivityDisconnect;
+	/**
+	 * iOS pauses the element a moment before it hides the page, and that pause reaches us while the
+	 * page still reports visible. Acting on it at once tears the session down, so every app switch
+	 * comes back as a full reconnect. Wait for the hide that follows a platform pause instead.
+	 * Nowhere else pauses before hiding, so there a visible pause is the viewer's at once.
+	 */
+	private onVisiblePause;
+	private disconnectForVisiblePause;
+	private clearVisiblePauseDisconnect;
 	private clearInactivityDisconnect;
 	private isHiddenWithBackgroundPlayback;
+	private isVideoOnScreen;
 	private isHiddenWithBackgroundPlayDisabled;
 	private suspend;
 	private unsuspend;
@@ -1552,6 +1652,20 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	private get targetSubscription();
 	private timeToFirstFrame;
 	private resolvedDecoder;
+	/**
+	 * On mobile Chromium with WebCodecs audio the play action arrives but no sound comes back until
+	 * the page is visible, so a hidden pause is a stop there. Reads the decoder in use.
+	 */
+	private hiddenPauseIsStop;
+	private usesSplitCanvasAudio;
+	private isWebKitCanvasPath;
+	private holdsDecoyWhilePaused;
+	private streamsToMediaElement;
+	/**
+	 * Safari 16.4+: a playback audio session keeps Web Audio alive in the background. Document-wide
+	 * and not restorable, so it waits for playback to be wanted rather than for construction.
+	 */
+	private requestAudioSessionOnce;
 	private willUseMediaSource;
 	private shouldUseWebCodecs;
 	private isWebCodecsVideoAvailable;

package/core.js

@@ -1,3 +1,3 @@
-import { t as e } from "./Cj61-Cjf.js";
-import { a as t, c as n, d as r, i, l as a, n as o, o as s, r as c, s as l, u } from "./CiWlpwR0.js";
-export { o as AUTHENTICATION_EXPIRED_CODE, c as AUTHENTICATION_FAILED_CODE, i as CHANNEL_NOT_FOUND_CODE, t as CHANNEL_NOT_LIVE_CODE, s as CONNECTION_FAILED_AFTER_RETRIES_CODE, l as CONNECTION_FAILED_CODE, n as DISCONNECTED_BY_EDGE, a as INACTIVITY_CODE, u as NO_INCOMING_DATA, e as Vindral, r as VindralError };
+import { t as e } from "./CN8w7_en.js";
+import { a as t, c as n, d as r, f as i, i as a, l as o, n as s, o as c, r as l, s as u } from "./BBVSf5AB.js";
+export { s as AUTHENTICATION_EXPIRED_CODE, l as AUTHENTICATION_FAILED_CODE, a as CHANNEL_NOT_FOUND_CODE, t as CHANNEL_NOT_LIVE_CODE, c as CONNECTION_FAILED_AFTER_RETRIES_CODE, u as CONNECTION_FAILED_CODE, n as DISCONNECTED_BY_EDGE, o as INACTIVITY_CODE, r as NO_INCOMING_DATA, e as Vindral, i as VindralError };

package/legacy.d.ts

@@ -192,6 +192,18 @@ export interface DrmOptions {
 export type Media = "audio" | "video" | "audio+video";
 type WebCodecsHardwareAccelerationPreference = "no-preference" | "prefer-hardware" | "prefer-software";
 type DecoderType = "mse" | "webcodecs" | "wasm";
+/** What the OS media controls show for the stream. Mirrors the `MediaMetadata` fields. */
+export interface MediaSessionMetadata {
+	title?: string;
+	artist?: string;
+	album?: string;
+	/** Fetched by the operating system, so the URLs should not carry credentials. */
+	artwork?: Array<{
+		src: string;
+		sizes?: string;
+		type?: string;
+	}>;
+}
 /**
  * Options for the Vindral instance
  *
@@ -291,6 +303,20 @@ export interface Options {
 	 * Legacy alias kept for backwards compatibility.
 	 */
 	iosBackgroundPlayEnabled?: boolean;
+	/**
+	 * Show the stream in the browser and OS media controls (notification, lock screen, toolbar) and
+	 * let play and pause from there reach the SDK. Enabled by default.
+	 *
+	 * The SDK takes over `navigator.mediaSession` for the document, so a page with its own Media
+	 * Session integration should disable this. On canvas playback paths a silent `<audio>` element is
+	 * added to `document.body` for the controls to attach to.
+	 */
+	mediaSessionEnabled?: boolean;
+	/**
+	 * Title, artist and artwork for the media controls. Without it the browser derives them from the
+	 * page. Read once at construction.
+	 */
+	mediaSessionMetadata?: MediaSessionMetadata;
 	/**
 	 * Enable or disable Adaptive Bit Rate. This allows for automatically adapting the incoming bit rate based on
 	 * the viewers bandwidth and thus avoiding buffering events. This also disables the
@@ -405,6 +431,9 @@ export interface Options {
 	 * 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.
 	 *
+	 * On iOS the audio then plays from its own element, so it continues in the background and under
+	 * lock. After an extended pause from the lock screen, reopening Safari may be required to resume.
+	 *
 	 * Disabled by default.
 	 */
 	streamToMediaElementEnabled?: boolean;
@@ -928,6 +957,13 @@ interface JitterModuleStatistics {
 	audioJitter: JitterStatistics | undefined;
 	videoJitter: JitterStatistics | undefined;
 }
+type DecoyState = "detached" | "attached" | "playing" | "blocked";
+interface MediaSessionModuleStatistics {
+	mediaSessionSupported: boolean;
+	mediaSessionOwner: boolean;
+	mediaSessionPlaybackState: MediaSessionPlaybackState;
+	decoyState?: DecoyState;
+}
 interface MseModuleStatistics {
 	quotaErrorCount: number;
 	mediaSourceOpenTime: number;
@@ -1039,8 +1075,10 @@ interface SyncModuleStatistics {
 interface VideoPlayerStatistics {
 	renderedFrameCount: number;
 	rendererDroppedFrameCount: number;
+	/** The platform's own view of the audio context, which a mute reading cannot tell apart. */
+	audioContextState?: AudioContextState | "none";
 }
-type ModuleStatistics = AdaptivityStatistics & BufferTimeStatistics & ConnectionStatistics & ConstraintCapStatistics & DecoderStatistics & DocumentStateModulesStatistics & IncomingDataModuleStatistics & JitterModuleStatistics & MseModuleStatistics & PlaybackModuleStatistics & QualityOfServiceModuleStatistics & RenditionsModuleStatistics & SyncModuleStatistics & TelemetryModuleStatistics & VideoPlayerStatistics;
+type ModuleStatistics = AdaptivityStatistics & BufferTimeStatistics & ConnectionStatistics & ConstraintCapStatistics & DecoderStatistics & DocumentStateModulesStatistics & IncomingDataModuleStatistics & JitterModuleStatistics & Partial<MediaSessionModuleStatistics> & MseModuleStatistics & PlaybackModuleStatistics & QualityOfServiceModuleStatistics & RenditionsModuleStatistics & SyncModuleStatistics & TelemetryModuleStatistics & VideoPlayerStatistics;
 /**
  * Contains internal statistics.
  *
@@ -1100,6 +1138,8 @@ export type Statistics = ModuleStatistics & ReturnType<UserAgentInformation["get
 	streamToMediaElementEnabled?: boolean;
 	/** @deprecated */
 	iosMediaElementEnabled?: boolean;
+	/** Whether the element carrying the audio is paused right now, on the sinks that have one. */
+	mediaElementPaused?: boolean;
 	/**
 	 * Average bitrate for the entire session in bits/second.
 	 */
@@ -1121,11 +1161,49 @@ export type Statistics = ModuleStatistics & ReturnType<UserAgentInformation["get
 	 */
 	timeshiftAdjustmentsPerMinute: number;
 };
+/**
+ * Represents a Vindral client instance
+ *
+ * The most most essential methods when using the Vindral class are:
+ *
+ * - connect() - this has to be called to actually start connecting
+ * - attach() - to attach the Vindral video view to the DOM so that users can see it
+ * - userInput() - to activate audio on browsers that require a user gesture to play audio
+ * - unload() - unloads the instance, its very important that this is called when cleaning up the Vindral instance, otherwise background timers may leak.
+ *
+ * The Vindral instance will emit a variety of events during its lifetime. Use .on("event-name", callback) to listen to these events.
+ * See [[PublicVindralEvents]] for the events types that can be emitted.
+ *
+ * ```typescript
+ * // minimal configuration of a Vindral client instance
+ * const instance = new Vindral({
+ *   url: "https://lb.cdn.vindral.com",
+ *   channelId: "vindral_demo1_ci_099ee1fa-80f3-455e-aa23-3d184e93e04f",
+ * })
+ *
+ * // Will be called when timed metadata is received
+ * instance.on("metadata", console.log)
+ *
+ * // Will be called when a user interaction is needed to activate audio
+ * instance.on("needs user input", console.log)
+ *
+ * // Start connecting to the cdn
+ * instance.connect()
+ *
+ * // Attach the video view to the DOM
+ * instance.attach(document.getElementById("root"))
+ *
+ * // When done with the instance
+ * instance.unload()
+ * ```
+ */
 export declare class Vindral extends Emitter<PublicVindralEvents> {
 	#private;
 	private static MAX_POOL_SIZE;
 	private static REMOVE_CUE_THRESHOLD;
 	private static BACKGROUND_INACTIVITY_DISCONNECT_TIMEOUT;
+	/** How long a pause on a visible page may still turn out to be the platform backgrounding us. */
+	private static VISIBLE_PAUSE_DISCONNECT_DELAY;
 	/**
 	 * Picture in picture
 	 */
@@ -1168,7 +1246,10 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	private offscreenCanvasElement?;
 	private webCodecsRenditionSupport;
 	private hasCalledConnect;
+	private hasRequestedAudioSession;
 	private isUserPaused;
+	/** Only the sinks that carry the audio report this, so a paused element here means silence. */
+	private isMediaElementPaused;
 	private latestEmittedLanguages;
 	private wakeLock;
 	private pool;
@@ -1184,6 +1265,7 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	private sizes;
 	private isSuspended;
 	private inactivityDisconnectInterval;
+	private visiblePauseTimeout;
 	private offscreenSubtitleInterval?;
 	constructor(options: Options);
 	/**
@@ -1485,6 +1567,8 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	private isSupportedVideoCodecProfile;
 	private supportedAudioCodecs;
 	private initializeDecodingModule;
+	private capturesCanvasOnWebKit;
+	private connectWebKitVideoOutput;
 	/**
 	 * 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'
@@ -1516,6 +1600,12 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	 * Pauses the stream. Call .play() to resume playback again.
 	 */
 	pause: () => void;
+	/**
+	 * A browser-initiated decoy pause means an interruption (another app took the focus, headphones
+	 * unplugged), so give the audio up rather than play over it. WebKit holds the decoy on purpose.
+	 */
+	private yieldToInterruption;
+	private fromNativeControls;
 	private registerDebugInstance;
 	/**
 	 *
@@ -1548,8 +1638,18 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	private resetModules;
 	private disconnectForInactivePage;
 	private scheduleInactivityDisconnect;
+	/**
+	 * iOS pauses the element a moment before it hides the page, and that pause reaches us while the
+	 * page still reports visible. Acting on it at once tears the session down, so every app switch
+	 * comes back as a full reconnect. Wait for the hide that follows a platform pause instead.
+	 * Nowhere else pauses before hiding, so there a visible pause is the viewer's at once.
+	 */
+	private onVisiblePause;
+	private disconnectForVisiblePause;
+	private clearVisiblePauseDisconnect;
 	private clearInactivityDisconnect;
 	private isHiddenWithBackgroundPlayback;
+	private isVideoOnScreen;
 	private isHiddenWithBackgroundPlayDisabled;
 	private suspend;
 	private unsuspend;
@@ -1567,6 +1667,20 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	private get targetSubscription();
 	private timeToFirstFrame;
 	private resolvedDecoder;
+	/**
+	 * On mobile Chromium with WebCodecs audio the play action arrives but no sound comes back until
+	 * the page is visible, so a hidden pause is a stop there. Reads the decoder in use.
+	 */
+	private hiddenPauseIsStop;
+	private usesSplitCanvasAudio;
+	private isWebKitCanvasPath;
+	private holdsDecoyWhilePaused;
+	private streamsToMediaElement;
+	/**
+	 * Safari 16.4+: a playback audio session keeps Web Audio alive in the background. Document-wide
+	 * and not restorable, so it waits for playback to be wanted rather than for construction.
+	 */
+	private requestAudioSessionOnce;
 	private willUseMediaSource;
 	private shouldUseWebCodecs;
 	private isWebCodecsVideoAvailable;