Playlist signals (Now Playing)#

The playout system signals every start and stop of an audio element to the Replacer. As soon as a point in the playlist is reached where a replacement is useful and possible, the Replacer starts working.

Signaling is performed by calling a URL of the Replacer API. Three parameters must be transmitted:

  • send_id: The unique ID assigned to the start of the element in the playlist. For example, 81655954446880

  • isplaying: This flag indicates whether the audio is currently starting or stopping. Values: true|false

  • api_key: The access key for the API.

Structure of the request URL#

replacer-<station_key>.radio-creator.com:5008/api/signal?send_id=<send_id>&isplaying=<true|false>&api_key=<api_key>

Example:

replacer-ffh.radio-creator.com:5008/api/signal?send_id=81655954446880&isplaying=true&api_key=12345678-1234-5678-1234-123456789012

Setting up signaling for the Zenon playout system is described in detail in the article Zenon Signaling.

Replacer signals#

Conversely, the Replacer can signal the start/stop events of each audio element to one of your APIs as an HTTP GET request or HTTP POST request. Multiple different APIs can be addressed, and the events sent can be filtered and configured separately for each API.

The Replacer takes the current delay into account so that, for example, you can receive synchronized Now Playing information or trigger ad inserts.

The Replacer can signal the following parameters:

  • send_time: Start/stop time in ms.

  • timestamp: Start/stop time in s. (float)

  • utc_str: UTC start time as a string in the format YYYY-MM-DDTHH:MM:SS - this is the format accepted by Radioplayer Ingest. (string)

  • total_delay: Total delay from the Replacer input to the output.

  • channel_key: Channel key. For example, “plus80er”

  • isplaying: true | false. Indicates whether an element is starting (true) or stopping (false).

  • type_name: “ad”, “song”, “dropper”…

  • planner_id: ID from music scheduling.

  • audio_id: ID from the playlist.

  • next_audio_id: The audio_id of the following track.

  • replaced: true | false. Indicates whether the Replacer has replaced the track.

  • original_playlist: true | false. Indicates whether this was a track from the original playlist/schedule.

  • artist: Artist.

  • title: Song title.

  • artist_title: Artist - title (combined field for supplying Icecast)

  • length: Length of the element in ms. (integer)

  • length_s: Length of the element in s. (integer)

The signals are configured in Radio Creator Manager. This is done using a JSON expression that defines the target URL <url>, the conditions <conditions> under which the HTTP request is executed, and the data <payload> to be transmitted.

<payload> defines parameters that are appended to the URL. For a POST request, form fields (body) can also be sent to the API. This is handled via the configuration in the optional data field.

Additional settings options:

  • mode: GET or POST request: get|post. If this setting is omitted, a GET request is used.

  • signal_delay: Each API call can be delayed by the individual signal_delay value in milliseconds. In addition, the r_additional_signal_delay value from the station_settings must be added, as it applies to all APIs.

  • send_time_delay: This adds an offset in ms to the send_time, timestamp and utc_str values. The signal itself is not delayed. Only the specified time values are increased. (Radioplayer Ingest)

  • additional_params: This can be used to pass additional fixed URL parameters to the API.

  • additional_data: This can be used to pass additional fixed data fields to the API as form data (body) in a POST request.

[
  {
   "url": "<url>",
   "conditions": {<conditions>},
   "payload": {<payload>},
   "data": {<data>},
   "mode": "get|post",
   "send_time_delay": <send_time_delay>,
   "additional_params": {<additional_params>},
   "additional_data": {<additional_data>}
  }
]

Example: When ad spots start, send the channel_key and audio_id to an API

[
  {
   "url": "http://0.0.0.1/instreamads/trigger.php",
   "conditions": {"isplaying": [true], "type_name": ["ad"]},
   "payload": {"station": "channel_key", "numrotation": "audio_id"}
  }
]

This configuration generates the following HTTP GET request, for example:

http://0.0.0.1/instreamads/trigger.php?station=plus80er&numrotation=12345