Skip to main content

Timed metadata

Vindral 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 timestamp 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 by default tagged with the timestamp of the frame being handled when received. This means that depending on ingest RTT, metadata request RTT, and potential jitter, the metadata may be a few frames off. If you experience a high diff, you should consider tagging the metadata explicitly with a timestamp.

Metadata is sent using HTTP POST:

https://metadata.global.cdn.vindral.com/api/timed-metadata/<stream key>.

CURL example​

A simple example of metadata ingestion using curl. Replace <stream key> with the channel stream key found in the Portal:

curl -XPOST https://metadata.global.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. Replace <stream key> with the channel stream key found in the Portal:

const data = { meaningOfLife: "42" };

fetch("https://metadata.global.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);
});

Setting timestamp explicitly​

Vindral passes through the origin stream's timestamp. If you are in control of the flow and want to mark a metadata with a specific timestamp, you may do so by adding ?timestamp=<timestamp>. If the timestamp is set to a lower value than what the viewer is playing, it is triggered immediately. Format of timestamp is in milliseconds (integer).

Example using curl with a specific timestamp:

curl -XPOST https://metadata.global.cdn.vindral.com/api/timed-metadata/<stream key>?timestamp=<timestamp> -d "my raw message" -vvv

Note that all timed-metadata will trigger after a maximum of 5 seconds, even if sent with a further away future timestamp. Due to the ultra-low latency nature of Vindral, more extended event timeouts usually do not make sense. If you need to achieve longer timeouts or deactivate timeout entirely, reach out, and we will set it up for you.

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

Server wallclock time​

If you depend on client devices being in sync, using an external backend source is often necessary. Vindral has a built-in feature that emits the server wallclock time every second and can be used to sync viewer experiences outside of the video. While not frame-accurate as explicitly setting timestamp, it is easy to sync the user interface against external data sources.

See the wallclock section for an example on how to listen.

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.