Skip to main content

Timed metadata

Vindral Live CDN supports sending timed metadata, sometimes 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 CDN, it is tagged with a timecode and emitted client-side when the corresponding frame is shown on the screen (or audio is played, for audio-only streams). Use timed metadata to build frame-synchronized experiences within web pages, mobile applications, and second-screen setups.

When activated on your account, you will receive an API endpoint for your metadata ingestion.

How to send timed metadata​

Metadata is sent using HTTP POST to your ingress site(s):

https://metadata.<your site>-ingress.cdn.vindral.com/api/timed-metadata/<stream key>.

CURL example​

A simple example of metadata ingestion using curl. Update <your site> and stream key to your channel ingress information:

curl -XPOST https://metadata.<your site>-ingress.cdn.vindral.com/api/timed-metadata/<stream key> -d "my raw message" -vvv

Javascript fetch example​

A simple example of metadata ingestion using javascript fetch. Update <your site> and stream key to your channel ingress information:

const data = { meaningOfLife: "42" };

fetch("https://metadata.<your site>-ingress.cdn.vindral.com/api/timed-metadata/<stream key>", {
  method: "POST",
  body: JSON.stringify(data),
})
.then(data => {
  console.log("Success: ", data);
})
.catch((error) => {
  console.log("Error: ", error);
});

Use cases​

Timed metadata fits any case where the user interface should be synchronized with what is shown in the stream.

For instance, you would not want your blackjack card to appear in the GUI before it is shown in the stream. Or vice versa.

Syncing the interface to the stream is key to a better experience for the viewer.

Alternative method​

Since Vindral Live CDN supports using a fixed buffer length for all viewers, the latency is known beforehand. This means it is also possible to offset your metadata events by that known number.

Depending on your infrastructure, this method might be more straightforward and only requires using your fixed buffer (1500 ms by default) or reading the value from the Vindral instance vindralInstance.playbackLatency.

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

While not being frame accurate, it should be pretty much in sync and, in worst cases, around +-200ms. Good enough for most use cases.

Listening to metadata events​

On the WebSDK timed metadata documentation page, you will find examples of how to listen to the metadata event in the WebSDK.