Publisher - current song / "Now Playing" metadata for live streams

"Now playing" metadata for live streams


Providing "Now Playing" information for a live-stream allows listeners to see this information on your embedded player.

This information is typically available from play-out systems but needs to be pushed into our platform as songs change.

This article looks at supported ways of supplying and retrieving "Now Playing" metadata.

Input methods


1. Input: HTTP POST with query parameters


Every stream has a password protected HTTP endpoint where this information can be pushed to. Data can be passed as URL query parameters:

- event : Required. The type of event that was triggered which indicates roughly the type of content being played. Accepts any of these values: "song", "ad", "news", "interview".

- artist : Name of the artist playing the current song, or name of interviewer, news reader or related vocals. Example: "AC/DC"

- title : Title of the current song, or topic of interview or any other information. Free form text limited to 50 characters. Example: "Back in Black"

- duration : Duration of this event if known in advance, for example length of song. Specified in seconds, for example: 185 (3:05 playing time)

Only the "event" field is required.  The endpoint must be called using an HTTP POST method on port 80. Query parameters may need to be escaped to ensure a valid URL, see this page.

Example:
curl --user USER:PASSWORD \
     --write-out '%{http_code}' \
  --request POST \
    "http://<hostname>/metadata/capture?event=song&artist=AC%2FDC&title=Back%20In%20Black&duration=255"

2. Input: HTTP POST with JSON content


The same endpoint can also accept input as JSON BODY data with the same fields. Escaping is not required in this case:
curl --user USER:PASSWORD \
     --write-out '%{http_code}' \
  --request POST \
    --header 'Content-Type: application/json' \
    --data '{ "event":"song", "artist":"AC/DC", "title":"Back In Black", "duration":255 }' \
    "http://<hostname>/metadata/capture"

3. Input: Jazler Radiostar


We provide native support to receive "Now Playing" metadata from the Jazler Radiostar 2 radio automation software. When current song information changes, it uploads an XML file to a remote FTP server. Our support department can assist customers with configuring their Jazler instance to perform this FTP upload.

4. Input: RCS Zetta


We provide native support to receive "Now Playing" metadata from the RCS Zetta radio automation software. When current song information changes, it sends XML data via an HTTP POST to a remote server. Our support department can assist customers with configuring their Zetta instance to perform this HTTP push.

5. Input: Icecast stream


When using software that sends an Icecast stream into our platform, ICY metadata can be included in this stream which our platform can extract.

6. Other inputs


Support for more play-out systems will be added over time, please contact us to determine if and how we can support yours.


Output methods


1. Output: Embedded player


As long as valid metadata is being received from any input method, our embedded player will display this to users while they are listening to the live-stream.

2. Output: HTTP with JSON content

Any current "Now Playing" metadata we track for a live stream can be retrieved using an HTTP GET to our edge network:
curl --request GET \
    https://edge.iono.fm/xmetadata/<stream_name>
This will return the latest available metadata for the specified stream as a JSON object with all the data fields as documented above. For example:
{
  event: "song",
  dt: "2016-08-12T14:51:16-0200",
  artist: "AC/DC",
  title: "Black in Black",
  duration: 185
}
This endpoint is useful when integrating live streams delivered on our platform into custom mobile applications or other platforms or players.

Please take note of these items when using this endpoint in your own players and client applications:

- All fields except “event" may be empty based on input from the station.

- We reserve the right to change the contents or location of this response in the future to allow extending it with more data. Clients will be notified of any changes to allow time to update any dependencies.
 
- Client polling intervals must never be less than 15 seconds, 30 seconds recommended. We retain the right to rate-limit and/or disable access to any applications that have higher polling rates to prevent unnecessary overheads on our servers. Rate limited requests will respond with the "429 Too Many Requests” HTTP status code.

-While metadata input is offline and not being received from the station, requests will respond with the “404 Not Found” status code.

- The endpoint can return HTTP "304 Not Modified" responses if the "If-Last-Modified” header is used in requests. ETag headers are also available. Clients are urged to make use of this information to ensure low overheads.

- Responses will include the CORS header "Access-Control-Allow-Origin: *" to enable direct consumption from Javascript clients.

- Clients are recommended to only poll for this information while a listener is actively listening to the stream.

Feedback and Knowledge Base