This section applies to SSAI (server-side ad insertion) in the live streaming services only.
Cue Point Formats
Cue points contain a list of key-value properties that players can decode and use to trigger various actions. Cue points are used to mark significant events in a stream, such as beginning of songs (with title/artist/album information) and ads (with companion banner information). Players usually listen to these cue points to present "now playing" information to listeners, such as cover art, or synchronized companion banners. Some players may also modify their UI dynamically to adapt to the contents of the stream (such as showing a video player when displaying video ads).
This document only describes ad type cue points. Cue points for these and other uses are documented more fully in the following documents:
STWCue Detailed Metadata Guide
Triton Digital Shoutcast V2 Metadata Mapping
Ask your Triton Digital Client Success Manager for access to those documents.
Cue Point Attribute | STWCue | AndoXML | Shoutcast V2 | Required | Comment |
|---|---|---|---|---|---|
Cue Type | ad | Ad | TXXX cue_type="ad" | ✅ | |
Unique Ad ID | ad_id | BREAKADID | TXXX ad_id="..." | ||
Ad Sub-Type | ad_type (break, | Type (BREAK, | TXXX | ✅ | |
Ad Title | cue_title | Title | TIT2 | Can be displayed to listener during ad. | |
Ad Duration | cue_time_duration | Time (in seconds) | TLEN | ||
Companion Banners (Legacy) | ad_url | IMGURL | TXXX ad_url="..." | ||
Companion Banners (VAST 2.0 – remote) | ad_vast_url | – | TXXX ad_vast_url="..." | Contains a URL to the VAST XML that the Player must retrieve. VAST may contain a video ad – see below | |
Companion Banners (VAST 2.0 – in-line) | ad_vast | – | TXXX ad_vast="..." | Contains the VAST XML (not an URL). Can also contain video ad – see below |
AndoXML is a deprecated cue point type, and has been superseded by STWCue, but it is still used by many stations (mostly due to legacy in-station setups or existing players), and is documented here for the sake of completeness. New players and stations are strongly encouraged to use STWCue, as it provides more features, consistency, and support.
Companion Banner Format Precedence
An ad’s cue point can contain references to companion banners in multiple formats (i.e., Legacy, remote and/or in-line VAST 2.0) at the same time. The player must look at the attributes in this precedence order:
ad_vast
ad_vast_url
ad_url (IMGURL for AndoXML)
The first supported format (in the order shown above) should be used for companion banner display, and other attributes (of lower priority) ignored. This ensures that players always use the most feature-rich format first, and can fallback to older formats if, for example, VAST is not available (either for the ad, or in the player itself). It also ensures that we can preserve backwards compatibility with existing players, while introducing better formats in the future.
It is suggested that players always implement VAST 2.0 support, and preferably, legacy format support as well. While most ad sources in Triton Digital's Ad Platform support VAST, some have not yet been retrofitted with VAST support. By implementing legacy format support as a fallback method, it ensures that the player will always display companion banners to accompany the in-stream audio ad.
Legacy Companion Banners
The legacy companion banner URLs (i.e., the ad_url/IMGURL attributes) support two banner sizes, and is always rendered in HTML format (suitable as the content of an IFrame). The URLs are separated by the pipe symbol ("|"), according to the following syntax:
[<leaderboard-url>][|<bigbox-url>]
It is possible to receive only one of the sizes. If only a Big Box is provided, the URL will start with the pipe symbol. Alternatively, if only a leaderboard is present, the URL has no preceding pipe symbol, but it might have a trailing pipe symbol.
When no companion banners are present, the ad_url/IMGURL attribute might be completely absent, or it might be an empty string, or it could have a single pipe symbol, with no preceding or trailing URLs.
Players should be tolerant of the presence of extraneous pipe symbols. However, the two positions will always be in the same order, and the pipe symbol is guaranteed to be present if only a Big Box is provided.
The player should use the provided URLs as the source for the inner HTML of an iFrame tag.