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.

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://embed.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

Player SDK

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"

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.

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()
})

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