Skip to main content
Version: v2

Metadata insertion

Metadata insertion lets you push custom timed data into a running channel via the API. The metadata is carried through the OptiView Live pipeline alongside the live stream, so it arrives at the player synchronized with the video. Use it for cuepoints, score updates, statistics, or any other event-driven information you want to deliver to viewers in real time.

info

Metadata insertion must be explicitly enabled on your account by a Dolby administrator. Contact your account manager to get started.

How it works​

  1. Enable metadata insertion on your channel.
  2. While the channel is running, send a binary payload to the dedicated endpoint, addressing it with the channel ID and a UUID.
  3. The payload is attached to the live stream at the moment it is received and is delivered to the player as part of playback.

Configuration​

Enable metadata insertion on your channel by setting instreamMetadata.enabled to true when creating or updating your channel.

POST https://api.theo.live/v2/channels

{
  "name": "my-channel",
  "instreamMetadata": {
    "enabled": true
  }
}

Sending metadata​

Once your channel is running, send a binary payload to the metadata insertion endpoint. The body is opaque to the platform — you decide its format (for example UTF-8 encoded JSON, protobuf, or your own binary layout) and your application is responsible for parsing it on the player side.

POST https://api.theo.live/v2/channels/{channelId}/instream-metadata/{uuid}

curl -X POST \
  "https://api.theo.live/v2/channels/ch_abc123/instream-metadata/11111111-1111-1111-1111-111111111111" \
  -H "Authorization: Basic $AUTH" \
  -H "Content-Type: application/octet-stream" \
  --data-binary '{"event":"goal","team":"home","score":"1-0"}'

A 200 response indicates the metadata was accepted and queued for delivery on the stream.

See the API reference for Send instream metadata for the full request specification.

Consuming on the player​

The platform exposes the inserted payloads to the player as cues on a metadata text track. See the text tracks introduction for how to listen for and parse these cues in your application. Suppose your uuid is 11111111-1111-1111-1111-111111111111, then this is a full code example for web:

player.textTracks.addEventListener('addtrack', (event) => {
  if (event.track.type === 'emsg' && event.track.inBandMetadataTrackDispatchType === 'urn:uuid:11111111-1111-1111-1111-111111111111') {
    event.track.addEventListener('addcue', (e) => {
      console.log('cue', e.cue.content);
    });
  }
});