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 nowplaying, nextup and NowPlayingOnPlaylist 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 "nowplaying":
        console.log(`[${msg.StationName}] Now playing:`,
                    msg.Payload.Track ? msg.Payload.Track.Title : msg.Payload.Title);
        break;
      case "nextup":
        console.log(`[${msg.StationName}] Next up:`, msg.Payload.Title);
        break;
      case "songrequested":
        console.log(`[${msg.StationName}] ${msg.Payload.Requester} requested ${msg.Payload.Title}`);
        break;
      case "ratingset":
        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

nowplaying

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": "nowplaying",
  "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,
    "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" } ]
    }
  }
}

nextup

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

songrequested

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

ratingset

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

NowPlayingOnPlaylist

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": "NowPlayingOnPlaylist",
  "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 nowplaying/nextup/NowPlayingOnPlaylist 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 nowplaying/nextup/NowPlayingOnPlaylist 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 (station staff)

This section documents how the WebSocket endpoint works internally and how to run it. API consumers can stop reading here.

Architecture

Apache/PHP cannot hold WebSocket connections, so the endpoint is a separate long-running CLI daemon, websocket/stationdata-server.php (“the relay”), fronted by Apache. The flow is:

1. An API endpoint does its normal work — updatetrack() ingests a new play, nextup() stores the next song, addrequest() accepts a request, updatestar() stores a rating, Settings::Override() flips the override state of a station.
2. At the end of that work it calls PublishStationEvent() (in config/common.php), which sends one small UDP datagram to the relay on loopback. This is fire-and-forget: if the relay is down the datagram is lost and the API call is completely unaffected.
3. The relay authenticates the datagram with the shared key, gates nextup events (buffer window and duplicate suppression, see the nextup section), enriches events that carry a TrackID with the full track data through the existing objGetSong() object (no duplicated SQL), caches the latest nowplaying/nextup/NowPlayingOnPlaylist per station for replay, and broadcasts the result to all subscribed WebSocket clients.
4. One event type originates in the relay itself: while the current track of a station carries a PlayList, the relay re-evaluates the playlist position every 5 seconds through the existing ReturnPlayListData() function (a pure time computation, no database work) and broadcasts a NowPlayingOnPlaylist event whenever the position changes.
5. For the stations listed in $WebSocketPollNowPlaying (station 2, whose “songs” are long podcast episodes), the relay additionally checks every 5 seconds which track is currently playing (one cheap SELECT against the nowplaying table) and re-establishes the playlist watch through objGetSong() when the track changed — so the running episode’s playlist is followed even if the relay started mid-episode. An unchanged episode costs only the SELECT; the full track lookup runs once per episode change.

Configuration (config.php)

Apache

Enable mod_proxy and mod_proxy_wstunnel, then add to the api.ericade.net TLS vhost:

ProxyPass        "/ws/stationdata" "ws://127.0.0.1:8146/"
ProxyPassReverse "/ws/stationdata" "ws://127.0.0.1:8146/"

TLS terminates in Apache; the relay itself speaks plain TCP on loopback only.

Running the relay

The watchdog script websocket/stationdata-ws.sh starts the relay if it is not running and removes duplicates, following the same pattern as the Discord bot. Add to root’s crontab:

* * * * * /var/www/html/api.ericade.net/websocket/stationdata-ws.sh

The relay logs to /var/log/stationdata-ws.txt (via the watchdog’s redirection). A plain HTTP GET /health against the relay port answers 200 OK and can be used for monitoring:

curl -s http://127.0.0.1:8146/health