Skip to main content

Getting Started with WebSDK

Depending on the use case, there are multiple ways to integrate the Web SDK.

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

The two other alternatives are Vindral Player and Core SDK - these are the recommended options if the integration requires access to the APIs, such as timed metadata or other controls. The Vindral Player is a web component-based player for easy integration and customization, while 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 the channel id credential, and done!

<iframe
  src="https://player.vindral.com/?channelId=vindral_demo1_ci_099ee1fa-80f3-455e-aa23-3d184e93e04f"
  frameborder="0"
  allow="autoplay; fullscreen"
  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

Equivalent for yarn:

yarn add @vindral/web-sdk

Core SDK​

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

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 mean 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 while buffering
instance.on("playback state", (state) => (playbackState.textContent = state))

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

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

// Will connect, start the stream and try to play
instance.play()

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

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

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>

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.

Example

This example attaches a player to an element with the id root. The player will activate audio when needed and provide a minimalistic UI for controls such as fullscreen, channel switching, and language selection.

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",
  channelGroupId: "vindral_demo_pk_932730be-db0c-46a0-a592-cfce7bdc5a43",
})

// Will connect, start the stream and try to play
player.core.play()

// Attaches the player view to the DOM
player.attach(root)