Module protocol 

The newline-delimited JSON wire protocol. This module is its definition.

One JSON value per line in both directions. A client writes Request lines and reads Frame lines, each either a Response echoing a request’s id or an unsolicited EventFrame carrying a full StateSnapshot.

Field names and value spellings are the contract: new fields may be added and readers must ignore ones they do not recognise, but nothing already named may be renamed or respelled.

Structs

DownloadProgress

One entry in a snapshot’s downloads array.

EpisodeRef

The loaded episode, as much of it as a snapshot needs to name.

ErrorObject

A structured failure. Clients branch on code and never parse message.

EventFrame

One event line: {"event":{"type":"state","state":{...}}}. Events carry no id.

Preferences

The interface’s own display preferences.

Request

One request line: {"id":1,"cmd":{"type":"pause"}}.

RequestError

A request line that could not be turned into a Request, together with the response the daemon owes for it.

Response

One response line. Carries exactly one of result or error, and echoes the request’s id, or null when the id could not be recovered from the line.

Spectrum

A frequency spectrum of the audio currently being played.

StateSnapshot

The complete player state.

Enums

Command

The command surface the daemon accepts.

DownloadState

What a download is doing.

Event

The size difference between the two variants buys nothing to box away: an event is built, serialised, and dropped, and never held in bulk.

Frame

One line read from the daemon, which is either a response or a pushed event.

PlaybackState

What playback is doing right now.

ResultBody

Source

Where the audio for the loaded episode is coming from.

Constants

COMMAND_TYPES

Every cmd.type spelling the daemon recognises.

SPECTRUM_BINS

How many frequency bins a Spectrum carries.

SPECTRUM_MAX_DB

The upper bound of the decibel range a Spectrum maps onto 0..=255.

SPECTRUM_MIN_DB

The lower bound of the decibel range a Spectrum maps onto 0..=255.

SPECTRUM_SMOOTHING

The exponential smoothing applied against the previous frame.

Functions

parse_request

Parses one request line, telling a malformed line from an unrecognised command from bad arguments, each of which the spec answers with a different code.