The djctl WebSocket API provides a simple mechanism for providing real-time track transition updates to connected clients.

Connection details

The WebSocket service is available at the following location:


Once connected, the service will push JSON events to the client.

Event data

As a new track transitions into “featured” state, a JSON formatted message is sent to all WebSocket clients. The following is an example message:

{"artist":"Fred Falke","title":"So Good","art":"iVBORw0...[REDUCED]","spotify_code":"iVBORaa...[REDUCED]","duration":235,"timestamp_epoch":1644597809584,"timestamp":"2022-02-11T08:43:29.58463-08:00","elapsed":"00:01:05"}

Attribute dictionary

The following table enumerates attributes found in the event JSON.

titlestringTrack title
artiststringTrack artist
genrestringTrack genre
artstringBase64 encoded PNG (RGB, 256x256)
spotify_codestringBase64 encoded PNG
durationintegerTotal track duration in seconds
timestampstringTimestamp in format 2022-02-11T08:24:47.162918-08:00
timestamp_epochintegerUnix time; the number of seconds elapsed since January 1, 1970 UTC
elapsedstringElapsed time since the first track triggered in format hh:mm:ss