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.

Six station events are pushed:

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.

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;
    }
  };

  // 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). 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"
  }
}

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.