Skip to main content

Timed metadata

Vindral has support for sending timed metadata, also called cue points or out-of-band data.

The data is sent as raw text and can be anything from JSON data to Unix timestamps. When received by the Vindral ingress, it is tagged with a timecode and emitted client-side when the corresponding frame is shown on the screen (or when audio is played for audio-only streams).

Listening to timed metadata​

Example using Vindral​

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

const instance = new Vindral({
  url: "https://lb.cdn.vindral.com",
  channelId: "vindral_demo1_ci_099ee1fa-80f3-455e-aa23-3d184e93e04f",
})
// metadata.content contains the raw string, metadata.timestamp contains timestamp in ms
instance.on("metadata", (metadata) => console.log(metadata))

Example using Vindral Player​

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",
})
player.core.play()
player.attach(root)

// metadata.content contains the raw string, metadata.timestamp contains timestamp in ms
player.core.on("metadata", (metadata) => console.log(metadata))

Using playback latency for offsetting events​

Since the Vindral playback latency is known, it can also be used to sync events. While it will not provide exact synchronization, it might be good enough for most use cases.

// pseudo javascript code
myBackend.onMessage((message) => {
  setTimeout(() => {
    handleMyMessage(message)
  }, vindralInstance.playbackLatency)
})

Server wallclock time​

Server wallclock time is emitted every second and can be used to synchronize users for a shared event.

note

The format is Unix timestamp with milliseconds (Milliseconds since Unix Epoch).

note

Server wallclock time may differ slightly between two viewers connected to different edge servers.

Example listening to server wallclock time​

Simple example using javascript:

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

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

// will log timestamp every second
instance.on("server wallclock time", (timestampMs) => console.log(timestampMs))

Stream time​

You may also use the channelCurrentTime property on the Vindral instance for synchronizing. To use it, you need to be aware of your stream timestamps before ingress.