ERICADE Radio API v2 — Station Data WebSocket

Overview

The station data WebSocket lets the website receive events the moment they happen, instead of polling /radio/v2/nowplaying on a timer. One connection carries events for both stations; every event states the StationID and StationName it belongs to, so a client can show either station (or both) from a single socket.

Eight station events are pushed. Six carry track data, two carry words:

Authentication: none. The socket is read-only and carries the same public data as the REST endpoints. Clients cannot inject data through it — the only accepted client messages are the control actions listed below. That includes the system-event: it is not shown on the station’s website, but it is not secret — every client receives it.

Connecting

Open the socket, optionally subscribe to a subset of stations, and handle incoming JSON messages. Immediately after connecting the server sends a welcome message followed by a replay of the latest known now-playing, next-up and now-playing-on-playlist events (marked "Replay": 1), so a client is usually up to date without any REST call.

Example (browser JavaScript)

let ws;

function connect() {
  ws = new WebSocket("wss://api.ericade.net/ws/stationdata");

  ws.onopen = () => {
    // Optional: only receive events for station 1.
    ws.send(JSON.stringify({ Action: "subscribe", StationID: [1] }));
  };

  ws.onmessage = (e) => {
    const msg = JSON.parse(e.data);
    switch (msg.Event) {
      case "now-playing":
        console.log(`[${msg.StationName}] Now playing:`,
                    msg.Payload.Track ? msg.Payload.Track.Title : msg.Payload.Title);
        break;
      case "next-up":
        console.log(`[${msg.StationName}] Next up:`, msg.Payload.Title);
        break;
      case "song-request":
        console.log(`[${msg.StationName}] ${msg.Payload.Requester} requested ${msg.Payload.Title}`);
        break;
      case "song-rating":
        console.log(`[${msg.StationName}] ${msg.Payload.Title} rated ${msg.Payload.Stars} stars`);
        break;
      case "station-event":
        // Words for listeners. The text is HTML-escaped plain text - see "Displaying the text".
        showToListeners(msg.Payload.Severity, messageText(msg.Payload.Subject), messageText(msg.Payload.Message));
        break;
      case "system-event":
        // For administrators' tools. A page for listeners does nothing here.
        break;
    }
  };

  // Reconnect with backoff; see "Client best practices".
  ws.onclose = () => setTimeout(connect, 2000 + Math.random() * 3000);
}

connect();

Message envelope

Every message from the server — station events and control messages alike — is a JSON object with this envelope:

Station events

now-playing

Sent when a new song starts playing on a station. The Payload.Track object contains the complete track data — the same object the Now Playing and Track by ID REST endpoints return (Artist, Title, Slug, Image, CompositeRating, TrackArtists, Playlog and so on — and, for a podcast episode that has been scanned, FileData: its length, loudness and ID3 tags, and the address of its waveform chart). See the REST documentation for the full field list.

Example

{
  "Event": "now-playing",
  "StationID": 1,
  "StationName": "24/7 tracked music",
  "Timestamp": 1785440425,
  "TimestampHR": "2026-07-30 21:00:25",
  "Payload": {
    "TrackID": 14906,
    "Artist": "Dr. Future",
    "Title": "Plastic pop",
    "Guid": "4f2c8c31-6b2e-4a44-9d0a-1c2f3e4d5a6b",
    "isListenerRequested": 0,
    "StartedAt": 1785440425,
    "WebStreamingOffset": 12,
    "Track": {
      "Artist": "Dr. Future",
      "Title": "Plastic pop",
      "StationID": 1,
      "StationName": "24/7 tracked music",
      "Slug": "https://ericade.radio/#/song/14906/plastic-pop-dr-future",
      "Image": "https://radio.ericade.net/images/demoscene.png",
      "CompositeRating": 4.2,
      "PlayLength": 213.4,
      "TrackArtists": [ { "ArtistID": 4821, "Artist": "Dr. Future" } ]
    }
  }
}

next-up

Sent when a new “next song” appears for a station. Payload attributes:

song-request

Sent when a listener request passes all checks and is queued. The greeting and the requester’s IP are deliberately not broadcast. Payload attributes:

song-rating

Sent when a listener sets a star rating on a track. The voter’s IP and browser hash are deliberately not broadcast. Payload attributes:

now-playing-on-playlist

Sent when the playlist position of a running show changes. Shows (for example live sets or podcast episodes) carry a PlayList text field with timestamped entries; while such a show is playing, the relay re-evaluates the current entry every 5 seconds and fires this event whenever it changes. The value is a plain text field — there is no artist or song data behind it. Present it as it is.

Example

{
  "Event": "now-playing-on-playlist",
  "StationID": 1,
  "StationName": "24/7 tracked music",
  "Timestamp": 1785441106,
  "TimestampHR": "2026-07-30 21:11:46",
  "Payload": {
    "NowPlayingOnPlaylist": "Jester of Elysium - Elysium"
  }
}

override

Sent when a station’s override state changes in the settings table — that is, when a live broadcast takes over the station (override on) or the station returns to normal broadcast operations (override off). The event only fires on an actual state change, not on every call to the settings endpoint.

Example

{
  "Event": "override",
  "StationID": 1,
  "StationName": "24/7 tracked music",
  "Timestamp": 1785442000,
  "TimestampHR": "2026-07-30 21:26:40",
  "Payload": {
    "Override": 1,
    "Message": "Just went live",
    "Artist": "ericade.radio",
    "Title": "Live from the demo party!",
    "Image": "https://radio.ericade.net/images/live.png"
  }
}

Messages: station-event and system-event

Two events carry words instead of track data. They share one payload and differ in whom they are for:

Messages are sent by an administrator through /radio/v2/message (the form is radio.ericade.net/conelrad/message/), by the broadcast automation server, or by the API’s own code (PublishStationMessage() in config/common.php). They are never cached and never replayed: a client that connects a second later does not get them, and a snapshot does not bring them back. Timestamp / TimestampHR in the envelope say when the message was sent. StationID is 0 for the whole network — every client gets it — or one station, for the clients following it.

Payload

Payload attributes, the same for station-event and system-event:

Example

{
  "Event": "station-event",
  "StationID": 0,
  "StationName": "",
  "Timestamp": 1789725600,
  "TimestampHR": "2026-09-18 12:00:00",
  "Payload": {
    "Severity": "medium",
    "Source": "LeisaWolfe",
    "Subject": "Maintenance tonight",
    "Message": "The stream moves to a new server at 22:00 CET.\nExpect a short break & thank you for waiting <3"
  }
}

Displaying the text

Subject, Message and Source are plain text and never markup — there are no tags, no links and no formatting in these events, and there never will be. They are valid UTF-8 without control characters or Unicode direction overrides, and they arrive HTML-escaped: the five characters & < > " ' travel as & < > " ', as in the example above. That is a seat belt: a client that carelessly assigns the text to innerHTML still shows text. It is no reason to be careless.

// One pass, so that "&amp;lt;" - somebody typed "&lt;" - comes out as "&lt;" and not as "<".
function messageText(s) {
  const map = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
  return typeof s !== "string" ? "" :
    s.replace(/&(amp|lt|gt|quot|apos|#0*39|#[xX]0*27);/g, (whole, name) => map[name] || "'");
}

subjectElement.textContent = messageText(msg.Payload.Subject);
bodyElement.textContent    = messageText(msg.Payload.Message);   // CSS: white-space: pre-line

Control messages

Control messages use StationID: 0 and an empty StationName.

welcome

First message after the connection is established.

subscribed

Acknowledges a subscribe action. Subscribed lists the station IDs the connection now receives. After the acknowledgement, cached now-playing/next-up/now-playing-on-playlist messages for the chosen stations are replayed (marked "Replay": 1).

pong

Answer to the application-level ping action.

error

Sent when a client message could not be processed. Message contains a human-readable explanation. The connection stays open.

Client actions

Clients may send the following JSON messages. Anything else is answered with an error message.

subscribe

Restrict (or widen) which stations the connection receives events for. Without a subscribe, a connection receives all stations.

{ "Action": "subscribe", "StationID": [1, 2] }

snapshot

Asks the server to resend the cached now-playing/next-up/now-playing-on-playlist messages (marked "Replay": 1) for the subscribed stations. Useful after a mobile browser wakes a background tab.

{ "Action": "snapshot" }

ping

Application-level keepalive for clients that cannot send protocol-level pings (browsers). The server answers with pong. Not normally needed — the server pings every client at the protocol level anyway.

{ "Action": "ping" }

Client best practices

Limits

These values are configurable server-side; see Operations.

Operations

The relay exposes two plain-HTTP endpoints on the same TCP port as the WebSocket listener (before the upgrade handshake), for use by uptime monitors and dashboards — not by station-data clients.

GET /health

Liveness check. Always returns 200 OK with the body OK as long as the relay's event loop is running. Does not reflect capacity.

GET /status

Current connection capacity, as plain text:

Used websockets: 42, Available websockets: 158, Total websockets: 200

Capacity event log

The relay writes capacity and connection-availability events to /var/log/websocket_stationdata_events/<YYYY-MM-DD>.log, one file per day, so an operator can see when the relay approached or hit its limits without polling /status. Each line is [timestamp] [event-type] message. Events:

Each threshold event fires once per crossing and resets once usage falls back under it, so a station going 90% → 100% → 80% → 95% logs capacity-total-90, capacity-total-100, then capacity-total-90 again — not a line per connection.