@vindral/web-sdk 3.4.3 → 4.0.0

package/README.md

@@ -30,13 +30,13 @@ Add the following HTML snippet, set `channelId` to channel id credential, and do
 
 ```html
 <iframe
-  src="https://embed.vindral.com/?channelId=vindral_demo1_ci_099ee1fa-80f3-455e-aa23-3d184e93e04f"
+  src="https://player.vindral.com/?channelId=vindral_demo1_ci_099ee1fa-80f3-455e-aa23-3d184e93e04f"
   frameborder="0"
   allowfullscreen
 ></iframe>
 ```
 
-[See the player in action](https://embed.vindral.com/?channelId=vindral_demo1_ci_099ee1fa-80f3-455e-aa23-3d184e93e04f) or [read more about Embed Player here](https://docs.vindral.com/playout/embeddable-player).
+[See the player in action](https://player.vindral.com/?channelId=vindral_demo1_ci_099ee1fa-80f3-455e-aa23-3d184e93e04f) or [read more about Embed Player here](https://docs.vindral.com/playout/embeddable-player).
 
 ## Installation
 
@@ -52,52 +52,47 @@ or `yarn`:
 yarn add @vindral/web-sdk
 ```
 
-### Player SDK
+### Vindral Player
 
-The Player SDK provides a ready-to-go player with controls - perfect for use cases where the embed solution is not enough, such as when access to the javascript API is needed.
+Vindral Player is our ready-to-go web component-based player for easy integration into your web applications. It is ideal for customizing controls or when the embed solution is not sufficient.
 
 **Example**
 
-This example attaches a player to an element with the id `#root`. The player will take care of activating audio when needed and provides a minimalistic UI for fullscreen, channel switching, language selection, etc.
-
-The example assumes that there is an HTML page that loads this script that has at least a div with `id="#root"`.
+To be able to use the `<vindral-player />` in your HTML you have to call `registerComponents`.
 
 ```javascript
-import { Player } from "@vindral/web-sdk"
-
-const root = document.querySelector("#root")
-
-const player = new Player({
-  url: "https://lb.cdn.vindral.com",
-  channelId: "vindral_demo1_ci_099ee1fa-80f3-455e-aa23-3d184e93e04f",
-})
-
-// Starts playback
-player.core.play()
+import { registerComponents } from "@vindral/web-sdk/player"
 
-// Attaches the player view to the DOM
-player.attach(root)
+registerComponents()
 ```
 
-Finally, import `@vindral/web-sdk/style.css` (or `./node_modules/@vindral/web-sdk/style.css` if that doesn't work) into your CSS. This step may differ depending on your build tools, some tools will allow you to import CSS directly in your js:
+Or use vindral-player-component.js is a self-registering variant of the web components player intended to be used from a script tag.
 
-```javascript
-import "@vindral/web-sdk/style.css"
+```html
+<script type="module" async src="https://cdn.jsdelivr.net/npm/@vindral/web-sdk/vindral-player-component.js"></script>
 ```
 
-or, from a CSS file:
+Channel id is the only required attribute when using `<vindral-player />`.
 
-```css
-@import "@vindral/web-sdk/style.css";
+```html
+<vindral-player channelId="vindral_demo1_ci_099ee1fa-80f3-455e-aa23-3d184e93e04f"></vindral-player>
 ```
 
-or, in your html file:
+Easy to customize controls with CSS variables.
 
-```html
-<link rel="stylesheet" href="./node_modules/@vindral/web-sdk/style.css" />
+```css
+<style>
+  vindral-player {
+    aspect-ratio: 16 / 9;
+    --vindral-fg-strong: pink;
+    --vindral-mute-button-display: none;
+    --vindral-pip-button-display: none;
+    --vindral-fullscreen-button-display: none;
+  }
+</style>
 ```
 
-We recommend that you consult the documentation for your build tool for more information.
+[Read the full API reference for all the attributes and CSS variables](https://docs.vindral.com/web-sdk/player)
 
 ### Core SDK
 
@@ -167,6 +162,55 @@ button.addEventListener("click", () => {
 })
 ```
 
+### Player SDK
+
+> **Deprecated**: The Player SDK is deprecated and has been replaced with the [Vindral Player](#vindral-player). It can still be used with `@vindral/web-sdk/legacy`.
+
+The Player SDK provides a ready-to-go player with controls - perfect for use cases where the embed solution is not enough, such as when access to the javascript API is needed.
+
+**Example**
+
+This example attaches a player to an element with the id `#root`. The player will take care of activating audio when needed and provides a minimalistic UI for fullscreen, channel switching, language selection, etc.
+
+The example assumes that there is an HTML page that loads this script that has at least a div with `id="#root"`.
+
+```javascript
+import { Player } from "@vindral/web-sdk/legacy"
+
+const root = document.querySelector("#root")
+
+const player = new Player({
+  url: "https://lb.cdn.vindral.com",
+  channelId: "vindral_demo1_ci_099ee1fa-80f3-455e-aa23-3d184e93e04f",
+})
+
+// Starts playback
+player.core.play()
+
+// Attaches the player view to the DOM
+player.attach(root)
+```
+
+Finally, import `@vindral/web-sdk/style.css` (or `./node_modules/@vindral/web-sdk/style.css` if that doesn't work) into your CSS. This step may differ depending on your build tools, some tools will allow you to import CSS directly in your js:
+
+```javascript
+import "@vindral/web-sdk/style.css"
+```
+
+or, from a CSS file:
+
+```css
+@import "@vindral/web-sdk/style.css";
+```
+
+or, in your html file:
+
+```html
+<link rel="stylesheet" href="./node_modules/@vindral/web-sdk/style.css" />
+```
+
+We recommend that you consult the documentation for your build tool for more information.
+
 #### License and support
 
 Vindral is a commercial product and requires an active, paid license to access and use. To obtain such a license, or in case you have any questions, do not hesitate to [get in touch](https://vindral.com/inquiries)!

package/api-client.d.ts

@@ -0,0 +1,151 @@
+type AudioCodec = "aac" | "opus" | "mp3";
+type VideoCodec = "h264" | "av1";
+interface RenditionProps {
+	id: number;
+	bitRate: number;
+	codecString?: string;
+	language?: string;
+	meta?: Record<string, string>;
+}
+interface VideoRenditionProps {
+	codec: VideoCodec;
+	frameRate: [
+		number,
+		number
+	];
+	width: number;
+	height: number;
+}
+interface AudioRenditionProps {
+	codec: AudioCodec;
+	channels: number;
+	sampleRate: number;
+}
+interface TextRenditionProps {
+	codec: "webvtt";
+	kind: "subtitles" | "captions";
+	label?: string;
+}
+type VideoRendition = VideoRenditionProps & RenditionProps;
+type AudioRendition = AudioRenditionProps & RenditionProps;
+type TextRendition = TextRenditionProps & RenditionProps;
+type Rendition = VideoRendition | AudioRendition | TextRendition;
+/**
+ * Channel
+ */
+export interface Channel {
+	/**
+	 * Channel ID for the channel
+	 */
+	channelId: string;
+	/**
+	 * Display name
+	 */
+	name: string;
+	/**
+	 * Indicates whether there is an incoming source feed for the channel
+	 */
+	isLive: boolean;
+	/**
+	 * URLs to fetch thumbnail from
+	 */
+	thumbnailUrls: string[];
+}
+interface ClientOverrides {
+	maxVideoBitRate?: number;
+	minBufferTime?: number;
+	maxBufferTime?: number;
+	burstEnabled?: boolean;
+	sizeBasedResolutionCapEnabled?: boolean;
+	separateVideoSocketEnabled?: boolean;
+	videoCodecs?: string[];
+}
+interface ChannelWithRenditionsAndOverrides extends Channel {
+	renditions: Rendition[];
+	overrides?: ClientOverrides;
+}
+interface ConnectOptions {
+	channelGroupId?: string;
+	channelId: string;
+}
+interface Telemetry {
+	url: string;
+	probability?: number;
+	includeErrors?: boolean;
+	includeEvents?: boolean;
+	includeStats?: boolean;
+	maxRetries?: number;
+	maxErrorReports?: number;
+	interval?: number;
+}
+export interface ConnectResponse {
+	logsUrl?: string;
+	statsUrl?: string;
+	telemetry?: Telemetry;
+	channels: ChannelWithRenditionsAndOverrides[];
+	edges: string[];
+}
+/**
+ * ApiClientOptions
+ */
+export interface ApiClientOptions {
+	/**
+	 * String representing the URL to the public CDN API.
+	 */
+	publicEndpoint: string;
+	/**
+	 * Function that should return a string containing a signed authentication token.
+	 */
+	tokenFactory?: AuthorizationTokenFactory;
+}
+/**
+ * Represents what authorization that will be requested.
+ */
+export interface AuthorizationContext {
+	/**
+	 * The channelGroupId that might need authorization.
+	 */
+	channelGroupId?: string;
+	/**
+	 * The channelId that might need authorization.
+	 */
+	channelId?: string;
+}
+/**
+ * AuthorizationTokenFactory
+ */
+export type AuthorizationTokenFactory = (context: AuthorizationContext) => string | undefined;
+/**
+ * Convenience class to call the public available endpoints of the Vindral Live CDN.
+ */
+export declare class ApiClient {
+	private baseUrl;
+	private tokenFactory?;
+	constructor(options: ApiClientOptions);
+	/**
+	 * Returns everything needed to setup the connection of Vindral instance.
+	 */
+	connect(options: ConnectOptions): Promise<ConnectResponse>;
+	/**
+	 * Fetches information regarding a single channel.
+	 *
+	 * @param channelId the channel to fetch
+	 * @returns a [[Channel]] containing information about the requested channel.
+	 */
+	getChannel(channelId: string): Promise<Channel>;
+	/**
+	 * Fetches channels within a channel group
+	 *
+	 * Note: The returned list includes inactive channels - check isLive to filter out only active channels
+	 *
+	 * @param channelGroup the channel group to fetch channels from
+	 * @returns an array of [[Channel]] that belong to the channel group
+	 */
+	getChannels(channelGroupId: string): Promise<Channel[]>;
+	private getHeaders;
+	private getAuthToken;
+	private toChannels;
+	private toChannel;
+}
+
+export {};

package/api-client.js

@@ -0,0 +1,4 @@
+import { A as o } from "./B7jz034g.js";
+export {
+  o as ApiClient
+};

package/cast-sender.d.ts

@@ -0,0 +1,396 @@
+type MatchingKeys<TRecord, TMatch, K extends keyof TRecord = keyof TRecord> = K extends (TRecord[K] extends TMatch ? K : never) ? K : never;
+type VoidKeys<Record> = MatchingKeys<Record, void>;
+type EventListenerReturnType = (() => void) | void;
+declare class Emitter<TEvents, TEmits = TEvents, ArgLessEvents extends VoidKeys<TEvents> = VoidKeys<TEvents>, ArgEvents extends Exclude<keyof TEvents, ArgLessEvents> = Exclude<keyof TEvents, ArgLessEvents>, ArgLessEmits extends VoidKeys<TEmits> = VoidKeys<TEmits>, ArgEmits extends Exclude<keyof TEmits, ArgLessEmits> = Exclude<keyof TEmits, ArgLessEmits>> {
+	private listeners;
+	emit<T extends ArgLessEmits>(eventName: T): void;
+	emit<T extends ArgEmits>(eventName: T, args: TEmits[T]): void;
+	off<T extends ArgLessEvents>(eventName: T, fn: () => EventListenerReturnType): void;
+	off<T extends ArgEvents>(eventName: T, fn: (args: TEvents[T]) => EventListenerReturnType): void;
+	/**
+	 * Add an event listener to `eventName`
+	 *
+	 * Event listeners may optionally return a "defer function" that will be called once all other listeners have been called.
+	 * This is useful when one listener may want everone to have reacted to an event before calling something.
+	 */
+	on<T extends ArgLessEvents>(eventName: T, fn: () => void): void;
+	on<T extends ArgEvents>(eventName: T, fn: (args: TEvents[T]) => void): void;
+	/**
+	 * Add an event listener to `eventName` that will be called once only
+	 *
+	 * Event listeners may optionally return a "defer function" that will be called once all other listeners have been called.
+	 * This is useful when one listener may want everone to have reacted to an event before calling something.
+	 */
+	once<T extends ArgLessEvents>(eventName: T, fn: () => void): void;
+	once<T extends ArgEvents>(eventName: T, fn: (args: TEvents[T]) => void): void;
+	reset(): void;
+	private add;
+}
+declare const Levels: readonly [
+	"off",
+	"error",
+	"warn",
+	"info",
+	"debug",
+	"trace"
+];
+type Level = (typeof Levels)[number];
+declare const Level: {
+	ERROR: "error";
+	WARN: "warn";
+	INFO: "info";
+	DEBUG: "debug";
+	TRACE: "trace";
+	OFF: "off";
+};
+type VideoCodec = "h264" | "av1";
+interface Metadata {
+	/**
+	 * The raw string content as it was ingested (if using JSON, it needs to be parsed on your end)
+	 */
+	content: string;
+	/**
+	 * Timestamp in ms
+	 */
+	timestamp: number;
+}
+interface ReconnectState {
+	/**
+	 * The number or retry attempts so far.
+	 * This gets reset on every successful connect, so it will start from zero every
+	 * time the client instance gets disconnected and will increment until the
+	 * client instance makes a connection attempt is successful.
+	 */
+	reconnectRetries: number;
+}
+interface Size {
+	width: number;
+	height: number;
+}
+interface VideoConstraint {
+	width: number;
+	height: number;
+	bitRate: number;
+	codec?: VideoCodec;
+	codecString?: string;
+}
+interface AdvancedOptions {
+	/**
+	 * Constrains wasm decoding to this resolution.
+	 * By default it is set to 1280 in width and height.
+	 * This guarantees better performance on older devices and reduces battery drain in general.
+	 */
+	wasmDecodingConstraint: Partial<VideoConstraint>;
+}
+type Media = "audio" | "video" | "audio+video";
+interface Options {
+	/**
+	 * URL to use when connecting to the stream
+	 */
+	url: string;
+	/**
+	 * Channel ID to connect to initially - can be changed later mid-stream when connected to a channel group.
+	 */
+	channelId: string;
+	/**
+	 * Channel group to connect to
+	 * Note: Only needed for fast channel switching
+	 */
+	channelGroupId?: string;
+	/**
+	 * A container to attach the video view in - can be provided later with .attach() on the vindral core instance
+	 */
+	container?: HTMLElement;
+	/**
+	 * An authentication token to provide to the server when connecting - only needed for channels with authentication enabled
+	 * Note: If not supplied when needed, an "Authentication Failed" error will be raised.
+	 */
+	authenticationToken?: string;
+	/**
+	 * Language to use initially - can be changed during during runtime on the vindral instance
+	 * Note: Only needed when multiple languages are provided - if no language is specified, one will be automatically selected.
+	 */
+	language?: string;
+	/**
+	 * TextTrack to use initially - can be changed during during runtime on the vindral instance
+	 */
+	textTrack?: string;
+	/**
+	 * Sets the log level - defaults to info
+	 */
+	logLevel?: Level;
+	/**
+	 * Sets the minimum and initial buffer time
+	 */
+	minBufferTime?: number;
+	/**
+	 * Sets the maximum buffer time allowed. The vindral instance will automatically slowly increase
+	 * the buffer time if the use experiences to much buffering with the initial buffer time.
+	 */
+	maxBufferTime?: number;
+	/**
+	 * Enables or disables user bandwidth savings by capping the video resolution to the size of the video element.
+	 *
+	 * Is enabled by default.
+	 *
+	 * Note: This is automatically set to false when abrEnabled is set to false.
+	 */
+	sizeBasedResolutionCapEnabled?: boolean;
+	/**
+	 * Enables or disables picture in picture support.
+	 */
+	pictureInPictureEnabled?: boolean;
+	/**
+	 * Enable bursting for initial connection and channel switches. This makes time to first frame faster at the
+	 * cost of stability (more demanding due to the sudden burst of live content)
+	 *
+	 * Is disabled by default.
+	 *
+	 */
+	burstEnabled?: boolean;
+	/**
+	 * Enable usage of the MediaSource API on supported browsers.
+	 *
+	 * Is enabled by default.
+	 *
+	 * Note: We recommend to keep this at the default value unless you have very specific needs.
+	 */
+	mseEnabled?: boolean;
+	/**
+	 * Enable Opus with the MediaSource API on supported browsers.
+	 *
+	 * Is enabled by default.
+	 *
+	 */
+	mseOpusEnabled?: boolean;
+	/**
+	 * Enable or disable support for playing audio in the background for iOS devices.
+	 *
+	 * Is false (disabled) by default.
+	 *
+	 * Note:  This may be enabled by default in a future (major) release
+	 */
+	iosBackgroundPlayEnabled?: boolean;
+	/**
+	 * 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
+	 * sizeBasedResolutionCapEnabled option.
+	 *
+	 * Is enabled by default.
+	 *
+	 * Note:  It is strongly recommended to keep this enabled as user experience can greatly suffer without ABR.
+	 */
+	abrEnabled?: boolean;
+	/**
+	 * Enable or disable telemetry. This allows for telemetry and errors being collected.
+	 *
+	 * Is enabled by default.
+	 *
+	 * We appreciate you turning it off during development/staging to not bloat real telemetry data.
+	 *
+	 * Note: It is strongly recommended to keep this enabled in production as it is required for insights and KPIs.
+	 */
+	telemetryEnabled?: boolean;
+	/**
+	 * Set a cap on the maximum video size.
+	 * This can be used to provide user options to limit the video bandwidth usage.
+	 *
+	 * Note: This takes presedence over any size based resolution caps.
+	 */
+	maxSize?: Size;
+	/**
+	 * Maximum audio bit rate allowed.
+	 * This can be used to provide user options to limit the audio bandwidth usage.
+	 */
+	maxAudioBitRate?: number;
+	/**
+	 * Maximum video bit rate allowed.
+	 * This can be used to provide user options to limit the video bandwidth usage.
+	 */
+	maxVideoBitRate?: number;
+	/**
+	 * Controls video element background behaviour while loading.
+	 * - If `false`, a black background will be shown.
+	 * - If undefined or `true`, a live thumbnail will be shown.
+	 * - If set to a string containing a URL (https://urltoimage), use that.
+	 * Default `true` - meaning a live thumbnail is shown
+	 */
+	poster?: boolean | string;
+	/**
+	 * Whether to start the player muted or to try to start playing audio automatically.
+	 */
+	muted?: boolean;
+	/**
+	 * 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
+	 * false to stop reconnecting. It can also return a promise with true or false if it needs
+	 * to make any async calls before determining wether to reconnect.
+	 *
+	 * The default reconnect handler allows 30 reconnects before stopping.
+	 *
+	 * Note: the ReconnectState gets reset every time the client instance makes a successful connection.
+	 * This means the default reconnect handler will only stop reconnecting after 30 _consecutive_ failed connections.
+	 *
+	 * ```typescript
+	 * // An example reconnect handler that will reconnect forever
+	 * const reconnectHandler = (state: ReconnectState) => true
+	 *
+	 * // An example reconnect handler that will fetch an url and determine whether to reconnect
+	 * const reconnectHandler = async (state: ReconnectState) => {
+	 *   const result = await fetch("https://should-i-reconnect-now.com")
+	 *   return result.ok
+	 * },
+	 * ```
+	 */
+	reconnectHandler?: (state: ReconnectState) => Promise<boolean> | boolean;
+	tags?: string[];
+	ownerSessionId?: string;
+	edgeUrl?: string;
+	logShippingEnabled?: boolean;
+	statsShippingEnabled?: boolean;
+	/**
+	 * Enable wake lock for iOS devices.
+	 * The wake lock requires that the audio has been activated at least once for the instance, othwerwise it will not work.
+	 * Other devices already provide wake lock by default.
+	 *
+	 * This option is redundant and has no effect if iosMediaElementEnabled is enabled since that automatically enables wake lock.
+	 *
+	 * Disabled by default.
+	 */
+	iosWakeLockEnabled?: boolean;
+	/**
+	 * Disabling this will revert to legacy behaviour where Vindral will try to always keep the video element playing.
+	 */
+	pauseSupportEnabled?: boolean;
+	/**
+	 * Enables iOS devices to use a media element for playback. This enables fullscreen and picture in picture support on iOS.
+	 */
+	iosMediaElementEnabled?: boolean;
+	/**
+	 * Advanced options to override default behaviour.
+	 */
+	advanced?: AdvancedOptions;
+	media?: Media;
+	videoCodecs?: VideoCodec[];
+}
+/**
+ * Available events to listen to
+ */
+export interface CastSenderEvents {
+	/**
+	 * When a connection has been established with a CastReceiver
+	 */
+	["connected"]: void;
+	/**
+	 * When a previous session has been resumed
+	 */
+	["resumed"]: void;
+	/**
+	 * When a CastReceiver has lost or stopped a connection
+	 */
+	["disconnected"]: void;
+	/**
+	 * When a connection attempt was initiated unsuccessfully
+	 */
+	["failed"]: void;
+	/**
+	 * When the remote connection emits a metadata event
+	 */
+	["metadata"]: Metadata;
+	/**
+	 * When the remote connection receives a server wallclock time event
+	 */
+	["server wallclock time"]: number;
+}
+/**
+ * Used for initializing the CastSender
+ */
+export interface CastConfig {
+	/**
+	 * The [Vindral Options](./Options) to use for the Cast Receiver
+	 */
+	options: Options;
+	/**
+	 * URL to a background image.
+	 * Example: "https://via.placeholder.com/256x144"
+	 */
+	background?: string;
+	/**
+	 * Override this if you have your own custom receiver
+	 */
+	receiverApplicationId?: string;
+}
+/**
+ * CastSender handles initiation of and communication with the Google Cast Receiver
+ */
+export declare class CastSender extends Emitter<CastSenderEvents> {
+	private state;
+	private config;
+	private unloaded;
+	constructor(config: CastConfig);
+	/**
+	 * True if the instance is casting right now
+	 */
+	get casting(): boolean;
+	/**
+	 * The current volume
+	 */
+	get volume(): number;
+	/**
+	 * Set the current volume. Setting this to zero is equivalent to muting the video
+	 */
+	set volume(volume: number);
+	/**
+	 * The current language
+	 */
+	get language(): string | undefined;
+	/**
+	 * Set the current language
+	 */
+	set language(language: string | undefined);
+	/**
+	 * The current channelId
+	 */
+	get channelId(): string;
+	/**
+	 * Set the current channelId
+	 */
+	set channelId(channelId: string);
+	/**
+	 * Update authentication token on an already established and authenticated connection
+	 */
+	updateAuthenticationToken: (token: string) => void;
+	/**
+	 * Fully unloads the instance. This disconnects the current listener but lets the
+	 * cast session continue on the receiving device
+	 */
+	unload: () => void;
+	/**
+	 * Initiates the CastSender.
+	 * Will reject if Cast is not available on the device or the network.
+	 */
+	init: () => Promise<void>;
+	/**
+	 * Requests a session. It will open the native cast receiver chooser dialog
+	 */
+	start: () => Promise<void>;
+	/**
+	 * Stops a session. It will stop playback on device as well.
+	 */
+	stop: () => void;
+	/**
+	 * Returns a string representing the name of the Cast receiver device or undefined if no receiver exists
+	 */
+	getReceiverName: () => string | undefined;
+	private onGCastApiAvailable;
+	private send;
+	private onMessage;
+	private onSessionStarted;
+	private onSessionStateChanged;
+	private getInstance;
+	private getSession;
+	private castLibrariesAdded;
+	private verifyCastLibraries;
+}
+
+export {};