---
title: "Sideband Metadata"
slug: "sideband-metadata"
updated: 2024-09-09T16:33:38Z
published: 2024-09-09T16:33:38Z
canonical: "help.tritondigital.com/sideband-metadata"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.tritondigital.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sideband Metadata

Sideband Metadata (SBM) is a metadata transport mechanism offered to players that are unable to use metadata multiplexed into the stream itself (as with FLV, Shoutcast V1/V2, etc.), either because it is impossible, difficult, or resource intensive. For examples, players that use the HTML5 **<audio>** tag, or that delegate stream playback to the operating system's standard media player (e.g., iOS, Android), need a way to receive cue points without having to process the stream itself.

This is done by using a separate metadata connection (correlated to the stream), using [Server-Sent Events](http://en.wikipedia.org/wiki/Server-sent_events) (SSE). Players are responsible for queuing the received events and triggering them when the media player reaches the correct timestamp associated with each individual event.

#### Sideband Metadata Session ID

In order to correlate a stream connection with its associated metadata connection, it is necessary to use a common ID shared by both connections.

The player is responsible for generating this SBM Session ID, which takes the form of a Type 4 (i.e. random) UUID, formatted as a **lowercase** hex string, such as:

`fde807eb-6931-47db-a758-9c3b0c7e84d5`

The player is also responsible for passing the SBM Session ID when connecting to the stream, as well as the SBM SSE endpoint. This is explained in the following sections.

The player must generate a new SBM Session ID each time it connects or reconnects to the stream!**Warning!** If the SBM Session ID is malformed, connections using this ID will be refused.

#### Stream Connection

For HTML5 players, the player should connect to the standard Shoutcast or HTTP Live Streaming (HLS) stream (i.e., the **shoutcast** and **hls** transports). In addition, if the player intends to use SBM, it **must** include the Side-Band Metadata Session ID described in the [previous section](/v1/docs/sideband-metadata#sideband-metadata-session-id) via the **sbmid** query parameter. If the player does not intend to use SBM, it **should not** include the **sbmid** parameter (as it costs some resources in the streaming servers to maintain the SBM session information).

For example:

`http://1234.live.streamtheworld.com:80/KROQFM_SC?sbmid=fde807eb-6931-47db-a758-9c3b0c7e84d5`

As mentioned previously, a new SBM Session ID must be generated each time the player connects or reconnects to the stream.

This query parameter is in addition to any other parameters used for targeting, etc. See [Advertising Technical Specification](/v1/docs/advertising-specification) for details.

Once the stream connection has been established, the player can then create its Metadata Connection, in [Metadata Connection](/v1/docs/sideband-metadata#metadata-connection).

#### Metadata Connection

To receive its metadata, the player uses an SSE (Server-Sent Events) connection to the Metadata Connection endpoint. The player **must** connect to the **same** streaming server instance it has connected to for its stream (i.e., same IP, and same port).

The Metadata Connection uses the suffix (specified by the **<sse-sideband mountSuffix="...">** element received from the Player Provisioning API), appended to the mount’s name. The same **sbmid** that was used for the stream connection must also be passed by the player. For example, for the stream connection shown in the previous example, the associated Metadata Connection URL would be:

`http://1234.live.streamtheworld.com:80/KROQFM_SBM?sbmid=fde807eb-6931-47db-a758-9c3b0c7e84d5`

If, for some reason, the player cannot connect to the SBM endpoint, or receives an error from the MG, it **must** throttle its reconnection attempts, using the same exponential-backoff algorithm that is used for stream connections (as detailed in this document).

Individual cue points will be sent as separate Server-Sent Events over the same connection. The player thus remains connected to the SBM endpoint until the stream connection is closed. If the SBM connection is prematurely closed, and the stream connection itself remains active, the player must reconnect to the SBM endpoint using the same SBM Session ID it previously used. If, however, the stream connection has closed (voluntarily or not), the SBM connection **must** also be closed. Reconnecting requires the generation of a new SBM Session ID, prior to reconnecting to the stream and SBM endpoints.

#### Player-side Metadata Handling

With SBM the cue points will arrive ahead of time, and this must managed by the player. The player must queue all received cue points received (as Server-Sent Events) over the SBM connection. This queue must support dequeuing of events based on their timestamp. The dequeuing will occur (typically) in a **timeupdate** event handler attached to the **<audio>** HTML5 tag. The queue should return the next event in the queue, as long as its timestamp is lower than the stream's current timestamp. When an event is dequeued, it should be handled as a normal cue point (i.e., triggering label changes, companion ad presentation, etc.).

#### Sideband Metadata Payload

Metadata is sent as JSON-formatted data. The JSON format is a straightforward mapping of FLV cue points to JSON.

All cue points comply with the Triton Digital *STWCue Metadata Dictionary*. Mounts using AndoXML do **not** support HTML5 Sideband Metadata.

Remember that each line will be prefixed by “data: “ since the metadata is sent using the SSE protocol.

**Sample “ad” Cue Point**

```json
{
  "type": "onCuePoint",
  "name": "ad",
  "timestamp": 114832,
  "parameters": {
    "ad_id": "cm-2134",
    "ad_type": "break",
    "cue_time_duration": "32000",
    "cue_title": "Annoying Ad"
                }
}
```

As with standard STWCue cue points, all parameters’ values are strings. Note that the timestamp attribute is an integer, representing the number of **milliseconds** since the stream has started.

There are four types of events that can be received, as shown in the table below.

**“Ad” Cue Point Events Types**

| Type | Description |
| --- | --- |
| **onMetaData** | Received at initial stream start-up. Usually contains information about the stream itself (such as width/height for video, etc.) |
| **onCuePoint** | A normal cue point. Can appear anywhere in the stream. Should be handled identically to standard FLV cue points. |
| **onCuePointPreview** | A cue point preview, used for pre-loading resources. |
| **onCuePointPreviewExpired** | A cue point preview has expired, and its resources should be released. |

Players **must** ignore event types they do not recognize or know how to handle! This list of event types will grow in the future, and players should not trigger unwanted behavior when receiving an unknown type.