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

package/react.d.ts

@@ -17,6 +17,10 @@ interface Channel {
 	 * URLs to fetch thumbnail from
 	 */
 	thumbnailUrls: string[];
+	/**
+	 * Urls for timeshift if available
+	 */
+	timeshiftUrls?: string[];
 }
 interface ClientOverrides {
 	maxVideoBitRate?: number;
@@ -215,6 +219,10 @@ interface MoQConnectInfo {
 	telemetry?: Telemetry;
 	channels: ChannelWithCatalog[];
 	edges: Edge[];
+	timeshift: {
+		urls: string[];
+		duration: string;
+	};
 }
 interface VindralConnectInfo {
 	logsUrl?: string;
@@ -425,6 +433,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.
@@ -437,6 +453,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
@@ -723,6 +747,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;
@@ -746,11 +784,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 {
@@ -797,7 +835,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.
@@ -839,11 +877,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;
 	/**
@@ -1303,6 +1344,10 @@ interface VolumeState {
 	 */
 	volume: number;
 }
+interface TimeShiftInfo {
+	urls: string[];
+	duration: string;
+}
 interface PublicVindralEvents {
 	/**
 	 * When an error that requires action has occured
@@ -1399,6 +1444,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;
 }
@@ -1589,11 +1638,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];
 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",
@@ -1604,6 +1671,7 @@ 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",
@@ -1634,7 +1702,9 @@ 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;
 }
@@ -1720,7 +1790,7 @@ declare class PlayButton extends VindralButton {
 type PlayerAttributes = (typeof Player.observedAttributes)[number];
 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;
@@ -1786,6 +1856,20 @@ 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[];
+}
 type UserInputPlayOverlayAttributes = (typeof VindralUserInputPlayOverlay.observedAttributes)[number];
 declare class VindralUserInputPlayOverlay extends HTMLElement {
 	#private;
@@ -1815,20 +1899,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[];
-}
 type VolumeRangeAttributes = (typeof VolumeRange.observedAttributes)[number];
 declare class VolumeRange extends VindralRange {
 	#private;
@@ -1840,11 +1910,11 @@ declare class VolumeRange extends VindralRange {
 	get volume(): string;
 	get muted(): boolean;
 }
-type CustomElement<T, K extends string> = DetailedHTMLProps<HtmlHTMLAttributes<T> & {
+type CustomElement<T, K extends string> = Partial<Omit<DetailedHTMLProps<HtmlHTMLAttributes<T>, T>, "class"> & {
 	[Key in K]?: string;
 } & {
 	class?: string;
-}, T>;
+}>;
 /**
  * @ignore
  */