@vindral/web-sdk 4.5.1 → 4.6.0-11-g50f93209

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
  *
@@ -275,13 +287,36 @@ export interface Options {
 	 */
 	mseOpusEnabled?: boolean;
 	/**
-	 * Enable or disable support for playing audio in the background for iOS devices.
+	 * Keep playback running while the page is in the background. Enabled by default.
+	 * When disabled, the session disconnects while hidden and reconnects when visible.
 	 *
-	 * Is false (disabled) by default.
+	 * Browser media policies still apply; iOS Safari pauses hidden video regardless.
+	 * Call `play()` again from a user gesture or media-control action to resume.
 	 *
-	 * Note:  This may be enabled by default in a future (major) release
+	 * When enabled, hidden sessions that are muted outside Picture-in-Picture or browser-paused
+	 * are disconnected after the inactivity timeout; an explicit `pause()` disconnects at once.
+	 */
+	backgroundPlayEnabled?: boolean;
+	/**
+	 * @deprecated Use `backgroundPlayEnabled` instead.
+	 *
+	 * 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
@@ -396,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;
@@ -656,6 +694,7 @@ export declare const CONNECTION_FAILED_AFTER_RETRIES_CODE = "connection_failed_w
 export declare const AUTHENTICATION_FAILED_CODE = "authentication_error";
 export declare const AUTHENTICATION_EXPIRED_CODE = "authentication_expired";
 export declare const CHANNEL_NOT_FOUND_CODE = "channel_not_found";
+export declare const CHANNEL_NOT_LIVE_CODE = "channel_not_live";
 export declare const NO_INCOMING_DATA = "no_incoming_data_error";
 export declare const INACTIVITY_CODE = "connection_inactivity";
 export declare const DISCONNECTED_BY_EDGE = "disconnected_by_edge";
@@ -918,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;
@@ -1029,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.
  *
@@ -1090,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.
 	 */
@@ -1111,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 DISCONNECT_TIMEOUT;
 	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
 	 */
@@ -1158,6 +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;
@@ -1172,7 +1264,8 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	private readonly unextractableSamplesWarned;
 	private sizes;
 	private isSuspended;
-	private disconnectTimeout;
+	private inactivityDisconnectInterval;
+	private visiblePauseTimeout;
 	private offscreenSubtitleInterval?;
 	constructor(options: Options);
 	/**
@@ -1474,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'
@@ -1505,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;
 	/**
 	 *
@@ -1535,8 +1636,24 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	 */
 	getStatistics: () => Statistics;
 	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;
+	private resumeModules;
 	private getRuntimeInfo;
 	private getPlaybackBufferState;
 	private onMediaElementBufferState;
@@ -1550,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;
@@ -1560,6 +1691,8 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	 * is the optimal rendering path for WebCodecs (worker renders VideoFrames directly).
 	 */
 	private shouldUseOffscreenCanvas;
+	private isBackgroundPlayEnabled;
+	private shouldAllowBackgroundPlayback;
 }
 interface TelemetryModuleStatistics {
 	/**
@@ -1731,7 +1864,8 @@ export interface PublicVindralEvents {
 	 * Is emitted during connection whether the channel is live or not.
 	 *
 	 * If the channel is not live, the Vindral instance will try to reconnect until the `reconnectHandler`
-	 * determines that no more retries should be made.
+	 * determines that no more retries should be made. Each attempt also emits a non-fatal `error` with
+	 * the code `channel_not_live`.
 	 *
 	 * Note: If the web-sdk is instantiated at the same time as you are starting the stream it is possible
 	 * that this emits false until the started state has propagated through the system.
@@ -1800,6 +1934,10 @@ export interface CastSenderEvents {
 	 * When the remote connection receives a server wallclock time event
 	 */
 	"server wallclock time": number;
+	/**
+	 * When receiver availability changes. True when at least one receiver is reachable.
+	 */
+	"devices available": boolean;
 }
 /**
  * Used for initializing the CastSender
@@ -1826,6 +1964,9 @@ export declare class CastSender extends Emitter<CastSenderEvents> {
 	private state;
 	private config;
 	private unloaded;
+	private logger;
+	/** Last reported availability, undefined until the Cast API tells us */
+	private devicesAvailable;
 	constructor(config: CastConfig);
 	/**
 	 * True if the instance is casting right now
@@ -1885,6 +2026,9 @@ export declare class CastSender extends Emitter<CastSenderEvents> {
 	private send;
 	private onMessage;
 	private onSessionStarted;
+	private onCastStateChanged;
+	/** Emits on change only, since connecting and connected are all "available" */
+	private updateDevicesAvailable;
 	private onSessionStateChanged;
 	private getInstance;
 	private getSession;