atagen ca1910de60 stage 2

2026-05-19 16:33:09 +10:00

11 KiB

Raw Blame History

Headroom IPC — wire protocol

Normative specification of Headroom's control protocol. Version 1.

This is the contract between the daemon and any client (the first-party headroom CLI, the first-party headroom-client Rust crate, and any third party — Qt/QuickShell panel, Eww widget, shell script). The Rust representation lives in the headroom-ipc crate; this document is the authoritative source.

1. Transport

Type: Unix-domain socket, SOCK_STREAM.
Path: ${XDG_RUNTIME_DIR}/headroom/control.sock, falling back to /run/user/${UID}/headroom/control.sock if XDG_RUNTIME_DIR is unset.
Permissions: the parent directory is created 0700, the socket itself 0600. Authn/authz is purely filesystem-based, matching the conventions of PipeWire and Wayland.
Encoding: UTF-8 JSON, one message per frame.

2. Framing

Each frame is a 4-byte big-endian unsigned length followed by exactly that many bytes of JSON payload.

+--------+--------+--------+--------+----...----+
|  len high                       low | payload |
+--------+--------+--------+--------+----...----+

Maximum frame size: 1 MiB (1 048 576 bytes). Larger frames are a protocol violation; the server closes the connection.
The payload MUST be a single JSON value (object). Pretty-printing is permitted but discouraged.
No trailing newline or NUL terminator inside the frame.

3. Message shapes

Every payload is a JSON object with one of three top-level shapes, distinguished by which discriminating field is present.

3.1 Request — client → server

{
  "id": <u64>,
  "op": "<string>",
  "args": <object | omitted>
}

id: client-chosen identifier, must be unique across in-flight requests on a connection. The server echoes this verbatim in the paired response. Clients may reuse an id once they have received the corresponding response.
op: operation name. See §5.
args: optional argument object. May be omitted if the operation takes no arguments.

3.2 Response — server → client

Exactly one response is emitted per request, with the same id.

{ "id": <u64>, "result": <value> }

{ "id": <u64>, "error": { "code": "<string>", "message": "<string>" } }

Mutually exclusive: either result or error, never both. (Both fields together is a server bug.)
result may be any JSON value, including null for operations that succeed with no data.
error.code is a stable machine-readable string from §6.
error.message is human-readable English. Not stable; do not pattern match.

3.3 Event — server → client

{
  "event": "<string>",
  "topic": "<string>",
  "data": <object>
}

Events have no id. A client distinguishes events from responses by presence of event / topic (events) vs. id (responses).
topic: subscription topic the event belongs to (§4).
event: name of the event within that topic.
A client only receives events for topics it has explicitly subscribed to, with one exception: every new connection receives a hello event before any other traffic (see §7).

4. Subscriptions

A client opts in to event streams by calling subscribe with a list of topics, and opts out with unsubscribe. Subscription state is per-connection and resets when the connection closes.

Topics

Topic	Cadence	Purpose
`meters`	publish_hz (≤ 60)	Live loudness, peak, gain-reduction telemetry.
`profile`	on change	Profile use/reload events.
`routing`	on change	Rule changes; per-stream routing decisions.
`daemon`	on change	Lifecycle, errors, overflow notifications.

Backpressure

The server maintains a bounded queue per subscriber per topic (default 64 messages; topic-overrideable in profile). When a queue is full at publish time, the new event is dropped, the per-(subscriber, topic) drop counter increments, and a daemon overflow event is emitted to the affected subscriber describing the loss:

{
  "event": "overflow",
  "topic": "daemon",
  "data": { "lost_topic": "meters", "lost": 42, "total_lost": 197 }
}

overflow events themselves cannot be dropped — if the daemon queue is also full, the server closes the connection. A well-behaved client either drains promptly or filters topics it doesn't care about.

The control thread never blocks on a slow client. Audio is never affected by subscriber behaviour: meter publishing is rate-limited, runs on a dedicated thread, and reads from a non-blocking source.

5. Operations

All operations are listed below with their full argument and result schemas. args is omitted from the request when its schema is empty.

Catalogue

op	args	result
`status`	—	`Status`
`profile.list`	—	`{ profiles: ProfileInfo[] }`
`profile.use`	`{ name: string }`	`{ name: string }`
`profile.show`	`{ name?: string }`	`Profile`
`profile.reload`	—	`{ reloaded: string[] }`
`route.list`	—	`RouteList`
`route.set`	`{ app: string, to: "processed"\|"bypass" }`	`null`
`route.unset`	`{ app: string }`	`null`
`route.stream`	`{ node_id: u32, to: "processed"\|"bypass" }`	`null`
`setting.get`	`{ key: string }`	`{ key: string, value: any }`
`setting.set`	`{ key: string, value: any }`	`null`
`setting.list`	—	`{ settings: object }`
`bypass.set`	`{ enabled: bool }`	`null`
`subscribe`	`{ topics: string[] }`	`{ subscribed: string[] }`
`unsubscribe`	`{ topics: string[] }`	`{ unsubscribed: string[] }`

Object schemas

`Status`

{
  "version": "0.1.0",
  "protocol": 1,
  "uptime_s": 482,
  "profile": "default",
  "bypass": false,
  "sinks": {
    "processed": { "node_id": 51, "ready": true },
    "real":      { "node_id": 35, "name": "alsa_output.pci-0000_00_1f.3.analog-stereo" }
  },
  "streams": [
    { "node_id": 73, "app": "firefox", "route": "processed" },
    { "node_id": 81, "app": "spotify", "route": "bypass" }
  ]
}

`ProfileInfo`

{ "name": "default", "active": true, "description": "Gentle …" }

`Profile`

The full profile document. Identical to the TOML profile, serialized as JSON. See PLAN.md §5 for the field set.

`RouteList`

{
  "rules": [
    { "match": { "process_binary": ["firefox"] }, "route": "processed" }
  ],
  "current": [
    { "node_id": 73, "app": "firefox", "route": "processed" }
  ],
  "default_route": "processed"
}

Setting keys

setting.get/setting.set use dotted keys into the active profile. Examples:

agc.target_lufs (float)
agc.enabled (bool)
compressor.threshold_db (float)
compressor.ratio (float)
limiter.ceiling_dbtp (float)
limiter.lookahead_ms (float)
limiter.oversample (integer, one of 1/2/4/8)
meters.publish_hz (float)

Headroom rejects sets that would violate invariants (e.g. limiter.ceiling_dbtp > 0.0). See §6 for error codes.

6. Errors

error.code is one of:

code	meaning
`INVALID_FRAME`	Malformed framing or non-JSON payload. Connection is closed.
`INVALID_MESSAGE`	Valid JSON, but doesn't fit a known message shape.
`UNKNOWN_OP`	`op` does not name a known operation.
`INVALID_ARGS`	`args` missing a required field, wrong type, or out of range.
`NOT_FOUND`	Profile / app / stream / setting key does not exist.
`CONFLICT`	Operation would violate an invariant (e.g. ceiling > 0).
`BUSY`	Daemon transiently cannot serve the request (rare).
`INTERNAL`	Bug. Includes a `message` for debugging.

Frame-level violations (INVALID_FRAME of size, framing, encoding) cause the connection to be closed after the error is sent. Message-level errors leave the connection open.

7. Connection lifecycle

Client connects. Server immediately emits a hello event:

{
  "event": "hello",
  "topic": "control",
  "data": {
    "daemon": "headroom",
    "version": "0.1.0",
    "protocol": 1
  }
}

This event is not gated on subscription — every client gets it.

Client sends requests; server replies. Client may subscribe to topics at any time and will start receiving events for those topics.
Either side may close the socket at any time. The server cleans up subscription state. Outstanding requests are dropped (no response).

There is no formal bye. Closing the socket is the protocol.

8. Versioning

The protocol uses a single integer version number, currently 1.

Additions (new ops, new optional fields, new events, new error codes) do not bump the protocol version. Clients MUST ignore unknown fields on objects they receive and MUST be tolerant of new event topics they did not subscribe to (they should never see those, but belt and braces).
Removals or semantic changes bump the protocol version. The daemon may reject connections from clients that declare incompatible versions (TBD: client may include Hello request with declared version; not yet specified).

Clients SHOULD log a warning if the protocol value in hello does not match the version they were built against, and proceed.

9. Example exchange

C → S  len=58
       {"id":1,"op":"profile.use","args":{"name":"night"}}

S → C  len=24
       {"id":1,"result":{"name":"night"}}

C → S  len=49
       {"id":2,"op":"subscribe","args":{"topics":["meters"]}}

S → C  len=37
       {"id":2,"result":{"subscribed":["meters"]}}

S → C  len=137
       {"event":"tick","topic":"meters","data":{
         "momentary_lufs":-19.3,"shortterm_lufs":-20.1,
         "integrated_lufs":-19.8,"true_peak_dbtp":-1.4,
         "gain_reduction_db":-2.1,"agc_gain_db":0.5
       }}

10. Reference

The authoritative Rust binding to this protocol is the headroom-ipc crate; the headroom-client crate wraps it with a blocking Client (and an optional async AsyncClient behind the async feature). Both live in this repository.

Third-party clients should target this document, not the Rust types, to remain interoperable across implementations.

11 KiB Raw Blame History