Sign In
Player SDK

Now playing feed

The public feed of what is on air - JSON for polling, a live stream of updates, and the recent tracks. No key needed.

The feed is what the SDK reads. It is public, needs no API key, and allows requests from any website (CORS), so it can be used directly from a browser, an app or a script. Programs are addressed as BRAND_KEY:PROGRAM_KEY; the program uid works as well.

Current state

What is on air
curl https://sonicast.io/api/now-playing/BRAND_KEY:PROGRAM_KEY
{
  "program": { "uid": "PROGRAM_UID", "key": "PROGRAM_KEY", "brand_key": "BRAND_KEY" },
  "updated_at": "2026-11-11T17:41:37.851099Z",
  "item": {
    "type": "music",
    "title": "Enjoy the Silence",
    "artist": "Depeche Mode",
    "duration": null,
    "starts_at": "2026-11-11T17:41:37.821178Z",
    "image_url": null
  },
  "show": null,
  "stream_text": "Depeche Mode - Enjoy the Silence"
}

item and show are the two layers of the Metadata API; with the metadata source Encoder, item carries the title your encoder sends. stream_text is the text in the stream. updated_at is the version of the state and doubles as the ETag: poll with If-None-Match and the answer is a 304 until something changes. The response is cacheable for five seconds.

Live updates

The same state as server-sent events: the current state right away, then every change, with a keepalive in between.

Follow the updates
curl -N https://sonicast.io/api/now-playing/BRAND_KEY:PROGRAM_KEY/stream
id: 2026-11-11T17:41:37.851099Z
event: now-playing
data: {"program": …, "updated_at": "2026-11-11T17:41:37.851099Z", "item": …}
retry: 3000

In a browser, EventSource does the work, including reconnecting:

EventSource
const source = new EventSource(  "https://sonicast.io/api/now-playing/BRAND_KEY:PROGRAM_KEY/stream",);source.addEventListener("now-playing", (event) => {  const state = JSON.parse(event.data);  console.log(state.stream_text);});

Every event carries its id. When a connection drops, the browser reconnects with the last id it received, and the feed first replays the updates missed in between, oldest first - nothing is lost across a reconnect.

Recent tracks

The items that were on air, newest first.

The history
curl "https://sonicast.io/api/now-playing/BRAND_KEY:PROGRAM_KEY/history?limit=20"
{
  "program": { "uid": "PROGRAM_UID", "key": "PROGRAM_KEY", "brand_key": "BRAND_KEY" },
  "entries": [
    { "item": { "type": "music", "title": "Enjoy the Silence", "artist": "Depeche Mode", … }, "updated_at": "2026-11-11T17:41:37.851099Z" },
    { "item": { "type": "music", "title": "Personal Jesus", "artist": "Depeche Mode", … }, "updated_at": "2026-11-11T17:37:02.118778Z" }
  ]
}

updated_at is when the item came on air. limit is at most 100; before (an updated_at) pages further back. The feed keeps the last 200 changes of a program, at most a week.

Errors

An unknown program answers 404 with {"detail": "…", "code": "not_found"}.

In questa pagina

Now playing feed