Publisher - providing current playing metadata

Publish currently playing metadata for live-streams


Publishing streaming metadata allows users to see relevant information about the currently playing item.

This information is typically available from the play-out system and needs to be pushed into our platform as the information changes.

This documents ways that publishers can push this metadata into our platform. Currently we support two forms of HTTP input that can be triggered by the play-out system: 

HTTP input with query parameters


Every stream has a password protected HTTP endpoint where this information can be pushed to. Publishers will receive this URL and their password when signing up for our streaming solution.

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

- timestamp : Timestamp of when this event was triggered. If omitted the current time is used. Must be a ISO8601 formatted date-time string including the timezone offset. Example: 1975-12-25T14:15:16-0500

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

Endpoint must be called using an HTTP POST method.

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 \
    "https://<hostname>/metadata/capture?event=song&artist=AC%2FDC&title=Back%20In%20Black&duration=255"


HTTP input 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 }' \
    "https://<hostname>/metadata/capture"


Input from other systems


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


Reading currently playing metadata


Current playing metadata for a 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",
  timestamp: "2016-08-12T14:51:16-0200",
  artist: "AC/DC",
  title: "Black in Black",
  duration: 185
}
Some notes:

- Only the event field is required - other fields are optional and will be omitted if not available.

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

- The endpoint will return HTTP 304 Not Modified responses based on Last-Modified headers in the requests and includes an ETag header. Clients are urged to make use of this information to ensure low overheads. 

- Polling intervals should never be less than 5 seconds, recommended 10 seconds.

- In the future a WebSocket implementation will be provided in addition to polling to provide faster updates with less overheads.



Feedback and Knowledge Base