@vindral/web-sdk 3.0.5 → 3.0.6

package/README.md

@@ -70,8 +70,8 @@ const player = new Player({
   channelId: "vindral_demo1_ci_099ee1fa-80f3-455e-aa23-3d184e93e04f",
 })
 
-// Starts connecting to the channel
-player.core.connect()
+// Starts playback
+player.core.play()
 
 // Attaches the player view to the DOM
 player.attach(root)

package/index.d.ts

@@ -29,8 +29,17 @@ declare class Emitter<TEvents, TEmits = TEvents, ArgLessEvents extends VoidKeys<
 	private add;
 }
 interface MinMaxAverage {
+	/**
+	 * Average value over a given interval.
+	 */
 	average: number;
+	/**
+	 * Maximum value over a given interval.
+	 */
 	max: number;
+	/**
+	 * Minimum value over a given interval.
+	 */
 	min: number;
 }
 interface RenditionProps {
@@ -339,14 +348,24 @@ interface NeedsUserInputContext {
 declare type PlaybackState = "buffering" | "playing" | "paused";
 declare type BufferStateEvent = "filled" | "drained";
 interface PlaybackModuleStatistics {
+	/**
+	 * Current target buffer time if using dynamic buffer. Otherwise, this is the statically set buffer time from instantiation.
+	 */
 	bufferTime: number;
 	needsInputForAudioCount: number;
 	needsInputForVideoCount: number;
 }
 interface AdaptivityStatistics {
+	/**
+	 * True if adaptive bitrate (ABR) is enabled.
+	 */
 	isAbrEnabled: boolean;
 }
 interface BufferTimeStatistics {
+	/**
+	 * Number of time buffer time has been adjusted. This will only happen when using dynamic buffer time
+	 * (different min/max values of bufferTime).
+	 */
 	bufferTimeAdjustmentCount: number;
 }
 interface VindralErrorProps {
@@ -395,17 +414,35 @@ export declare class VindralError extends Error {
 declare type State = "connected" | "disconnected" | "connecting";
 declare type ContextSwitchState = "completed" | "started";
 interface ConnectionStatistics {
+	/**
+	 * RTT (round trip time) between client and server(s).
+	 */
 	rtt: MinMaxAverage;
+	/**
+	 * A very rough initial estimation of minimum available bandwidth.
+	 */
 	estimatedBandwidth: number;
 	edgeUrl?: string;
+	/**
+	 * Total number of connections that have been established since instantiation.
+	 */
 	connectCount: number;
+	/**
+	 * Total number of connection attempts since instantiation.
+	 */
 	connectionAttemptCount: number;
 }
+/**
+ * Represents a rendition (quality level).
+ */
 export interface RenditionLevel {
 	audio?: AudioRendition;
 	video?: VideoRendition;
 }
 declare type RenditionLevelChangedReason = "abr" | "manual";
+/**
+ * Contextual information about the rendition level change.
+ */
 export interface RenditionLevelChanged {
 	from?: RenditionLevel;
 	to?: RenditionLevel;
@@ -416,19 +453,52 @@ interface RenditionLevel {
 	video?: VideoRendition;
 }
 interface RenditionsModuleStatistics {
+	/**
+	 * Id of current video rendition subscribed to.
+	 */
 	videoRenditionId?: number;
+	/**
+	 * Id of current audio rendition subscribed to.
+	 */
 	audioRenditionId?: number;
+	/**
+	 * Current video codec being used.
+	 */
 	videoCodec?: string;
+	/**
+	 * Current audio codec being used.
+	 */
 	audioCodec?: string;
+	/**
+	 * Width of current video rendition (if any).
+	 */
 	videoWidth?: number;
+	/**
+	 * Height of current video rendition (if any).
+	 */
 	videoHeight?: number;
+	/**
+	 * Currently expected video bit rate according to metadata in bits/s.
+	 */
 	expectedVideoBitRate?: number;
+	/**
+	 * Currently expected audio bit rate according to metadata in bits/s.
+	 */
 	expectedAudioBitRate?: number;
+	/**
+	 * Current language. For non-multi language streams, this will often be unset.
+	 */
 	language?: string;
+	/**
+	 * Frame rate. Example: `"frameRate": [24000, 1001]`.
+	 */
 	frameRate?: [
 		number,
 		number
 	];
+	/**
+	 * Total count of rendition level changes (quality downgrades/upgrades).
+	 */
 	renditionLevelChangeCount: number;
 }
 interface VideoConstraintCap {
@@ -472,8 +542,17 @@ interface DocumentStateModulesStatistics {
 	navigatorDownlink?: number;
 }
 interface IncomingDataModuleStatistics {
-	videoBitRate: number;
-	audioBitRate: number;
+	/**
+	 * Current video bitrate in bits/second.
+	 */
+	videoBitRate?: number;
+	/**
+	 * Current audio bitrate in bits/second.
+	 */
+	audioBitRate?: number;
+	/**
+	 * Counter of number of bytes received.
+	 */
 	bytesReceived: number;
 }
 interface VideoPlayerStatistics {
@@ -491,9 +570,23 @@ interface MseModuleStatistics {
 	successfulAudioAppendsCalls?: number;
 }
 interface QualityOfServiceModuleStatistics {
+	/**
+	 * Time in milliseconds spent in buffering state. Note that this value will increase while in background if
+	 * buffering when leaving foreground.
+	 */
 	timeSpentBuffering: number;
+	/**
+	 * Total number of buffering events since instantiation.
+	 */
 	bufferingEventsCount: number;
+	/**
+	 * Number of fatal quality of service events.
+	 */
 	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.
+	 */
 	timeSpentRatio: {
 		[bitRate: string]: number;
 	};
@@ -511,18 +604,53 @@ interface UserAgentInformation {
 	ancestorOrigins?: string[];
 }
 declare type ModuleStatistics = AdaptivityStatistics & BufferTimeStatistics & ConnectionStatistics & ConstraintCapStatistics & DecoderStatistics & DocumentStateModulesStatistics & IncomingDataModuleStatistics & MseModuleStatistics & PlaybackModuleStatistics & QualityOfServiceModuleStatistics & RenditionsModuleStatistics & SyncModuleStatistics & TelemetryModuleStatistics & VideoPlayerStatistics;
-declare type Statistics = ModuleStatistics & UserAgentInformation & {
+/**
+ * Contains internal statistics.
+ *
+ * Note that this object will have some undocumented properties, used internally or temporarily,
+ * for monitoring and improving the performance of the service.
+ *
+ * @interface
+ */
+export declare type Statistics = ModuleStatistics & UserAgentInformation & {
+	/**
+	 * Version of the @vindral/web-sdk being used.
+	 */
 	version: string;
+	/**
+	 * IP of the client.
+	 */
 	ip?: string;
+	/**
+	 * URL being used for connecting to the stream.
+	 */
 	url: string;
+	/**
+	 * A session is bound to a connection. If the client reconnects for any reason (e.g. coming back from inactivity
+	 * or a problem with network on client side), a new sessionId will be used.
+	 *
+	 */
 	sessionId?: string;
+	/**
+	 * Unlike `sessionId`, `clientId` will remain the same even after reconnections and represents this unique Vindral instance.
+	 */
 	clientId: string;
+	/**
+	 * How long in milliseconds since the instance was created.
+	 */
 	uptime: number;
-	videoBitRate?: number;
-	audioBitRate?: number;
-	bytesReceived: number;
+	/**
+	 * Current channel ID being subscribed to.
+	 */
 	channelId: string;
+	/**
+	 * Channel group being subscribed to.
+	 */
 	channelGroupId?: string;
+	/**
+	 * Time in milliseconds from instantiation to playback of video and audio being started.
+	 * Note that an actual frame render often happens much quicker, but that is not counted as TTFF.
+	 */
 	timeToFirstFrame?: number;
 	iosMediaElementEnabled?: boolean;
 };
@@ -892,6 +1020,12 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	 * How long in milliseconds since the instance was created
 	 */
 	get uptime(): number;
+	/**
+	 * This method collects a statistics report from internal modules. While many of the report's properties are documented, the report may also contain undocumented
+	 * properties used internally or temporarily for monitoring and improving the performance of the service.
+	 *
+	 * Use undocumented properties at your own risk.
+	 */
 	getStatistics: () => Statistics;
 	private resetModules;
 	private suspend;
@@ -909,6 +1043,12 @@ export declare class Vindral extends Emitter<PublicVindralEvents> {
 	private willUseMediaSource;
 }
 interface TelemetryModuleStatistics {
+	/**
+	 * The total amount of errors being spawned. Note that some media errors can trigger
+	 * thousands of errors for a single client in a few seconds before recovering. Therefore,
+	 * consider the number of viewers with errors, not just the total amount. Also, consider the median
+	 * instead of the mean for average calculation.
+	 */
 	errorCount: number;
 }
 /**