Vindral Web SDK

Ultra-low latency streaming on all modern web browsers.

This package contains the Web SDK for Vindral - the ultra-low latency streaming platform for synchronized live experiences.

For information about the Vindral product family and how the Web SDK fits into the system, make sure to check out the Vindral documentation.

Make sure to check out the Web SDK guides as well.

Check out our demo to see some of Vindral's features.

For detailed information about our latest updates, visit the changelog.

Getting Started

There are multiple ways to integrate the Web SDK, depending on the use case.

The most simple way to get started is to use the iframe-based Embed Player. This requires the least amount of code, and will automatically be updated when new releases are available.

The two other alternatives are Player SDK and Core SDK - these are the recommended options if the integration requires access to the APIs, such as timed metadata or other controls. The two SDKs have very similar APIs, but the Player SDK provides controls and buffering indication built in - the Core SDK is the most stripped-down implementation for use cases where all UI components are customized.

If you are going for one of the SDK alternatives, follow the steps at Installation to get started:

Embed Player

This is the simplest way to integrate. It allows you to add a fully functional video player to your site in no time. It will also be automatically updated when improvements are released.

Add the following HTML snippet, set channelId to channel id credential, and done!

<iframe
  src="https://player.vindral.com/?channelId=vindral_demo1_ci_099ee1fa-80f3-455e-aa23-3d184e93e04f"
  frameborder="0"
  allowfullscreen
></iframe>

See the player in action or read more about Embed Player here.

Installation

Install @vindral/web-sdk using npm:

npm install --save @vindral/web-sdk

or yarn:

yarn add @vindral/web-sdk

Vindral Player

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

To be able to use the <vindral-player /> in your HTML you have to call registerComponents.

import { registerComponents } from "@vindral/web-sdk/player"

registerComponents()

Or use vindral-player-component.js is a self-registering variant of the web components player intended to be used from a script tag.

<script type="module" async src="https://cdn.jsdelivr.net/npm/@vindral/web-sdk/vindral-player-component.js"></script>

Channel id is the only required attribute when using <vindral-player />.

<vindral-player channelId="vindral_demo1_ci_099ee1fa-80f3-455e-aa23-3d184e93e04f"></vindral-player>

Easy to customize controls with CSS variables.

<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>

Read the full API reference for all the attributes and CSS variables

Core SDK

The Core SDK is the lowest level method to integrate that provides only a video view and audio playback - this allows for full customization of the look of buffering indication, controls, etc.

Example

The example assumes that there is an HTML page that loads this script that has at least a div with id="#root", id="#playback-state" and a button with id="#activate-audio-button".

import { Vindral } from "@vindral/web-sdk"

const root = document.querySelector("#root")!
const button = document.querySelector("#activate-audio-button")!
const playbackState = document.querySelector("#playback-state")!

button.style.display = "none"

const instance = new Vindral({
  url: "https://lb.cdn.vindral.com",
  channelId: "vindral_demo1_ci_099ee1fa-80f3-455e-aa23-3d184e93e04f",
})

// Errors are emitted when they can not be handled internally
// fatal errors means that the client has been unloaded and will need to be re-initialized
instance.on("error", (error) => {
  if (error.isFatal()) {
    // A fatal error has occured and the instance has been unloaded, read error.message to see what
    // This can happen if the client has been unsuccessful to connect or authentication failed
    // In this case a new Vindral instance needs to be created to restore the session
  }
})

// This event is emitted when the playback state changes - can be used to show a buffer spinner during buffering
instance.on("playback state", (state) => {
  switch (state) {
    case "paused":
      // Here would be a good place to show some play button to allow the user to start playing again
      break
    case "playing":
      // Hide any buffering or paused state from the UI
      break
    case "buffering":
      // Show some buffering spinner
      break
  }
})

// This event is emitted when timed metadata events occur
instance.on("metadata", (metadata) => console.log("metadata: ", metadata.content))

// This event is emitted when the vindral detects that the browser requires a user initiated click event to start media playback
instance.on("needs user input", () => (button.style.display = "block"))

// Starts connecting to the channel
instance.play()

// Attaches the video view to the DOM
instance.attach(root)

// This activates audio on browsers that need a user input before audio can be played
button.addEventListener("click", () => {
  button.style.display = "none"

  // Calling play again within a user click will activate audio if needed
  instance.play()
})

Player SDK

Deprecated: The Player SDK is deprecated and has been replaced with the 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".

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:

import "@vindral/web-sdk/style.css"

or, from a CSS file:

@import "@vindral/web-sdk/style.css";

or, in your html file:

<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!

Copyright RealSprint AB