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

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

Once the stream connection has been established, the player can then create its Metadata Connection, in 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.

Sample “ad” Cue Point

{
  "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