@vindral/web-sdk 4.5.0 → 4.5.1-10-g5556eb794

package/legacy.d.ts

@@ -275,11 +275,20 @@ 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;
 	/**
@@ -656,6 +665,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";
@@ -1111,11 +1121,47 @@ 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;
 	/**
 	 * Picture in picture
 	 */
@@ -1158,6 +1204,7 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	private offscreenCanvasElement?;
 	private webCodecsRenditionSupport;
 	private hasCalledConnect;
+	private isUserPaused;
 	private latestEmittedLanguages;
 	private wakeLock;
 	private pool;
@@ -1172,7 +1219,7 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	private readonly unextractableSamplesWarned;
 	private sizes;
 	private isSuspended;
-	private disconnectTimeout;
+	private inactivityDisconnectInterval;
 	private offscreenSubtitleInterval?;
 	constructor(options: Options);
 	/**
@@ -1535,8 +1582,14 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	 */
 	getStatistics: () => Statistics;
 	private resetModules;
+	private disconnectForInactivePage;
+	private scheduleInactivityDisconnect;
+	private clearInactivityDisconnect;
+	private isHiddenWithBackgroundPlayback;
+	private isHiddenWithBackgroundPlayDisabled;
 	private suspend;
 	private unsuspend;
+	private resumeModules;
 	private getRuntimeInfo;
 	private getPlaybackBufferState;
 	private onMediaElementBufferState;
@@ -1560,6 +1613,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 +1786,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 +1856,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 +1886,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 +1948,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;