@vindral/web-sdk 4.1.4 → 4.1.5-10-g4a74bcc5

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.1.4",
+  "version": "4.1.5-10-g4a74bcc5",
   "name": "@vindral/web-sdk",
   "main": "./legacy.umd.js",
   "module": "./legacy.es.js",

package/player.d.ts

@@ -15,6 +15,10 @@ interface Channel {
 	 * URLs to fetch thumbnail from
 	 */
 	thumbnailUrls: string[];
+	/**
+	 * Urls for timeshift if available
+	 */
+	timeshiftUrls?: string[];
 }
 interface ClientOverrides {
 	maxVideoBitRate?: number;
@@ -213,6 +217,10 @@ interface MoQConnectInfo {
 	telemetry?: Telemetry;
 	channels: ChannelWithCatalog[];
 	edges: Edge[];
+	timeshift: {
+		urls: string[];
+		duration: string;
+	};
 }
 interface VindralConnectInfo {
 	logsUrl?: string;
@@ -423,6 +431,14 @@ interface Options {
 	 * This can be used to provide user options to limit the video bandwidth usage.
 	 */
 	maxVideoBitRate?: number;
+	/**
+	 * Initial maximum bit rate cap applied when first connecting to a channel.
+	 * This helps prevent buffering on initial connection by starting at a conservative bitrate.
+	 * The client will adapt to higher bitrates as bandwidth allows if ABR is enabled.
+	 *
+	 * Default is 2.5 Mbps (2500000 bits per second).
+	 */
+	maxInitialBitRate?: number;
 	/**
 	 * Controls video element background behaviour while loading.
 	 * - If `false`, a black background will be shown.
@@ -435,6 +451,14 @@ interface Options {
 	 * Whether to start the player muted or to try to start playing audio automatically.
 	 */
 	muted?: boolean;
+	/**
+	 * Initial volume level for the player. A floating point value between 0-1.
+	 * Default is 1 (100% volume).
+	 *
+	 * Note: Volume cannot be set on iOS devices due to system restrictions.
+	 * The volume property is not settable in JavaScript on iOS, and reading it always returns 1.
+	 */
+	volume?: number;
 	/**
 	 * Provide a custom reconnect handler to control when the instance should stop trying to
 	 * reconnect. The reconnect handler should either return true to allow the reconnect or
@@ -721,6 +745,20 @@ interface IncomingDataModuleStatistics {
 	 */
 	bytesReceived: number;
 }
+interface JitterStatistics {
+	/** Minimum jitter in the recent window */
+	min: number;
+	/** Maximum jitter in the recent window for spike detection */
+	max: number;
+	/** Latest average jitter in ms (recent window) */
+	last: number;
+	/** Average jitter in ms (RFC 3550 style, smoothed with /16) */
+	average: number;
+}
+interface JitterModuleStatistics {
+	audioJitter: JitterStatistics | undefined;
+	videoJitter: JitterStatistics | undefined;
+}
 interface MseModuleStatistics {
 	quotaErrorCount: number;
 	mediaSourceOpenTime: number;
@@ -744,11 +782,11 @@ interface QualityOfServiceModuleStatistics {
 	 */
 	fatalQosCount: number;
 	/**
-	 * Ratio of time being spent on different bitrates.
-	 * Example: `"timeSpentRatio": { "1160000": 0.2, "2260000": 0.8 }` shows 20% spent on 1.16 Mbps, 80% spent on 2.26 Mbps.
+	 * Ratio of time being spent on different quality indexes. Index 0 is always the highest quality.
+	 * Example: `"timeSpentRatio": { "0": 0.8, "1": 0.2 }` shows 80% spent on the best level, 20% on the next one.
 	 */
 	timeSpentRatio: {
-		[bitRate: string]: number;
+		[qualityIndex: string]: number;
 	};
 }
 interface SyncModuleStatistics {
@@ -795,7 +833,7 @@ declare class UserAgentInformation {
 		userAgent: string;
 	};
 }
-type ModuleStatistics = AdaptivityStatistics & BufferTimeStatistics & ConnectionStatistics & ConstraintCapStatistics & DecoderStatistics & DocumentStateModulesStatistics & IncomingDataModuleStatistics & MseModuleStatistics & PlaybackModuleStatistics & QualityOfServiceModuleStatistics & RenditionsModuleStatistics & SyncModuleStatistics & TelemetryModuleStatistics & VideoPlayerStatistics;
+type ModuleStatistics = AdaptivityStatistics & BufferTimeStatistics & ConnectionStatistics & ConstraintCapStatistics & DecoderStatistics & DocumentStateModulesStatistics & IncomingDataModuleStatistics & JitterModuleStatistics & MseModuleStatistics & PlaybackModuleStatistics & QualityOfServiceModuleStatistics & RenditionsModuleStatistics & SyncModuleStatistics & TelemetryModuleStatistics & VideoPlayerStatistics;
 type Statistics = ModuleStatistics & ReturnType<UserAgentInformation["getUserAgentInformation"]> & {
 	/**
 	 * Version of the @vindral/web-sdk being used.
@@ -837,11 +875,14 @@ type Statistics = ModuleStatistics & ReturnType<UserAgentInformation["getUserAge
 	 */
 	timeToFirstFrame?: number;
 	iosMediaElementEnabled?: boolean;
+	/**
+	 * Average bitrate for the entire session in bits/second.
+	 */
+	averageBitRate?: number;
 };
 declare class Vindral extends Emitter<PublicVindralEvents> {
 	#private;
 	private static MAX_POOL_SIZE;
-	private static INITIAL_MAX_BIT_RATE;
 	private static DISCONNECT_TIMEOUT;
 	private static REMOVE_CUE_THRESHOLD;
 	/**
@@ -1301,6 +1342,10 @@ interface VolumeState {
 	 */
 	volume: number;
 }
+interface TimeShiftInfo {
+	urls: string[];
+	duration: string;
+}
 interface PublicVindralEvents {
 	/**
 	 * When an error that requires action has occured
@@ -1397,6 +1442,10 @@ interface PublicVindralEvents {
 	 * from external sources such as OS media shortcuts or other native UI outside of the browser.
 	 */
 	["volume state"]: Readonly<VolumeState>;
+	/**
+	 * Emitted when the timeshift URLs are updated.
+	 */
+	["timeshift info"]: Readonly<TimeShiftInfo>;
 	["buffer state event"]: Readonly<BufferStateEvent>;
 	["initialized media"]: void;
 }
@@ -1580,11 +1629,29 @@ declare class AirPlaySender extends Emitter<AirPlaySenderEvents> {
 	private getHlsUrl;
 	private checkHlsUrl;
 }
+interface FullscreenEvents {
+	["on fullscreen change"]: boolean;
+}
+declare class Fullscreen extends Emitter<FullscreenEvents> {
+	private container;
+	constructor(container: HTMLElement);
+	unload: () => void;
+	request: () => Promise<void>;
+	exit: () => Promise<void>;
+	private onChange;
+	isFullscreen: () => boolean;
+	isSupported: () => boolean;
+	isFullscreenApiSupported: () => boolean;
+	static isFullscreenApiSupported: (element: HTMLElement) => boolean;
+	private isInIframe;
+	private get requestFn();
+	private get exitFn();
+}
 type ControllerAttributes = (typeof Controller.observedAttributes)[number];
 export declare class Controller extends HTMLElement {
 	#private;
 	static observedAttributes: readonly [
-		...("language" | "channels" | "buffering" | "paused" | "volume" | "muted" | "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" | "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" | "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" | "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" | "poster-src" | "timeshift")[],
 		"url",
 		"edge-url",
 		"target-buffer-time",
@@ -1595,6 +1662,7 @@ export declare class Controller extends HTMLElement {
 		"min-buffer-time",
 		"max-buffer-time",
 		"max-audio-bit-rate",
+		"max-initial-bit-rate",
 		"burst-enabled",
 		"mse-enabled",
 		"mse-opus-enabled",
@@ -1625,7 +1693,9 @@ export declare class Controller extends HTMLElement {
 	attributeChangedCallback(name: ControllerAttributes, oldValue: string, newValue?: string): void;
 	connectListener(component: HTMLElement): void;
 	disconnectListener(component: HTMLElement): void;
+	handleTimeShiftUpdate: (timeShift: string | false) => void;
 	get instance(): Vindral | undefined;
+	get fullscreen(): Fullscreen | undefined;
 	get airPlay(): AirPlaySender | undefined;
 	connect(): void;
 }
@@ -1704,7 +1774,7 @@ export declare class PlayButton extends VindralButton {
 }
 export declare class Player extends HTMLElement {
 	#private;
-	static observedAttributes: readonly ("title" | "advanced" | "poster" | "language" | "channels" | "buffering" | "paused" | "volume" | "muted" | "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" | "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" | "poster-src" | "url" | "offline" | "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" | "abr-enabled" | "size-based-resolution-cap-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" | "reconnect-retries" | "auto-instance-enabled" | "refresh-poster-enabled" | "stream-poll-enabled")[];
+	static observedAttributes: readonly ("title" | "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" | "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" | "poster-src" | "timeshift" | "url" | "offline" | "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" | "abr-enabled" | "size-based-resolution-cap-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" | "reconnect-retries" | "auto-instance-enabled" | "refresh-poster-enabled" | "stream-poll-enabled")[];
 	constructor();
 	connectedCallback(): void;
 	disconnectedCallback(): void;
@@ -1767,6 +1837,20 @@ export declare class ScrollOverlay extends HTMLElement {
 	set visible(value: boolean);
 	get visible(): boolean;
 }
+declare class VindralRange extends HTMLElement {
+	#private;
+	static observedAttributes: string[];
+	range: HTMLInputElement;
+	constructor();
+	connectedCallback(): void;
+	disconnectedCallback(): void;
+	attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
+	enable(): void;
+	disable(): void;
+	handleEvent(event: Event): void;
+	updateBar(): void;
+	get keysUsed(): string[];
+}
 declare class VindralUserInputPlayOverlay extends HTMLElement {
 	#private;
 	static observedAttributes: string[];
@@ -1793,20 +1877,6 @@ declare class VindralPlayOverlay extends HTMLElement {
 	disconnectedCallback(): void;
 	attributeChangedCallback(name: string, old: string | null, value: string | null): void;
 }
-declare class VindralRange extends HTMLElement {
-	#private;
-	static observedAttributes: string[];
-	range: HTMLInputElement;
-	constructor();
-	connectedCallback(): void;
-	disconnectedCallback(): void;
-	attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
-	enable(): void;
-	disable(): void;
-	handleEvent(event: Event): void;
-	updateBar(): void;
-	get keysUsed(): string[];
-}
 export declare class VolumeRange extends VindralRange {
 	#private;
 	static observedAttributes: string[];