IPC protocol documentation
jackmoebiusd exposes a small JSON protocol over a local Unix-domain socket. It’s the same contract the jackmoebius CLI and the JackMate GUI use, so you can drive JackMoebius from any language that can open a socket.
Transport
- Socket:
/tmp/jackmoebius.sock, mode0600(owner only). - Request / response: send one JSON line, read one JSON line, the connection closes:
→ {"command":"status"}
← {"status":"ok","data":{ … }}Every reply is {"status":"ok","data":…} or {"status":"error","message":"…"}. An error may carry an optional code, a machine-readable marker (e.g. "licensing" when a routing command is refused because the trial has expired), so a client can react to a class of error without parsing message.
- Event stream: a
subscribeconnection stays open and streams invalidation events (see Event stream).
Health: status
→ {"command":"status"}
← {"status":"ok","data":{
"version":"1.1.0","device_acquired":true,"jack_connected":true,
"exposed_out":2,"exposed_in":1,"uptime_s":1234,
"bridge":"shm","shared_input":{"on":true,"apps":["Safari"]},
"capacity":{"forward":{"used":6,"total":254,"held":0},"reverse":{"used":2,"total":254,"held":0}},
"default_input_is_jackmoebius":true,
"licensing":{"state":"trial","days_remaining":9}, … }}Always present: version, device_acquired, jack_connected, exposed_out, exposed_in, uptime_s, bridge, capacity, licensing. version is the installed JackMoebius version (handy for an “About” box, and it answers even before the audio device is acquired).
bridgeisshmonce the shared-memory transport between the driver and the daemon is up, orwaiting, with a structuredtransport_problemthat says why (service not installed, switched off, unreachable, version mismatch, slot busy, driver not attached).shared_inputsays whether the portsshared_input_1/2exist and which apps share them.capacityis how full the two buses are, in channels (254 usable each way, shared by all apps).heldsays how many of the used channels are held by a stream that a card kept after its side was dropped, andheld_bywhich apps (seejack_rebuild).default_input_is_jackmoebiustells whether apps without a device menu reach the shared input.licensingcarries{state, days_remaining}(state ∈trial | licensed | expired;days_remainingis present fortrial/expired, absent forlicensed). Reading or changing the license itself (status while stopped, activation) is a CLI concern. See the CLI reference; the socket only reports the live state here and notifies changes vialicensing_changed.
App state: apps
Returns one entry per app the driver knows about, both directions in one call:
← {"status":"ok","data":[
{"name":"Music","key":"com.apple.Music","pid":606,
"out_exposed":true,"out_backing":"shared","out_channels":[2,3],
"in_exposed":false,"in_backing":"shared","in_channels":[],
"can_capture":false,"blacklisted":false}, … ]}key: bundle ID (stable persistence key) ·name: display name ·pid.out_exposed/in_exposed: whether the box is exposed (the stateaddset), per direction.out_backing/in_backing:shared(the commonJackMoebiusdevice) orprivate(a card: a virtual device of its own, namedJackMoebius for <App>).out_channels/in_channels: the reserved bus channels (persistent), or[]. For a shared output it is the stereo pair; for a shared input there is nothing to reserve.out_held_channels/in_held_channels: the channels a card still holds for a stream whose side was removed ([]when none). They count incapacity, andjack_rebuildfrees them.can_capture: the app can be routed on the input side.blacklisted: hidden from routing selectors.
Expose & hide
Each direction has a backing, shared or private, and always send it explicitly.
| Command | Effect | Reply |
|---|---|---|
{"command":"jack_add","app":"<key>","backing":"shared"} |
expose the output as a stereo pair of the shared device | {name,key,backing,channel_offset} |
{"command":"jack_add","app":"<key>","backing":"private","n":8} |
expose the output as a card of n channels (1 to 64, default 2) |
{name,key,backing,channels, …} |
{"command":"jack_add_in","app":"<key>","backing":"shared"} |
expose the input as the shared input | {name,key,backing,channels} |
{"command":"jack_add_in","app":"<key>","backing":"private","n":2} |
expose the input as a card of n channels (1 to 64, default 2) |
{name,key,backing,channels, …} |
{"command":"jack_apply","app":"<key>","in":{…},"out":{…}} |
set both directions in one call (each {backing, n}; a missing side stays as it is) |
{name,key,in,out} |
{"command":"jack_rebuild","app":"<key>"} |
rebuild the app’s card as it is and free the channels a dead stream holds (nothing held: nothing happens) | {name,key,released,rebuilt, …} |
{"command":"jack_remove","app":"<key>"} / jack_remove_in |
hide the output / the input (reservation kept) | null |
{"command":"jack_clear_assignment","app":"<key>"} / jack_clear_in |
drop the reservation | null |
jack_add {app} with no backing and no n is the 1.0 form: the stereo stem. {app, n} without backing is an error. jack_add_in without backing means private. Only an explicit backing:"shared" ever takes a card away.
Changing the backing of a direction is one call. A card only holds the directions that are private, so the effect on the device the app sees is:
| Call | The other direction has a card | Effect |
|---|---|---|
shared → private |
yes | the card is rebuilt with this side added: the app sees its device go and come back |
shared → private |
no | the card is created |
private → shared |
yes | the card is kept as it is: this side is no longer wired, its channels stay reserved until the card is deleted or rebuilt |
private → shared |
no | the card is deleted: an app that had chosen it falls back to another device |
private with another n |
the card is rebuilt with the new width |
jack_apply is all or nothing: everything is checked first, then both sides are applied and the card is created, rebuilt or deleted at most once. If an app has a single device setting for input and output and you want it on a card, make both directions private (or leave both shared and let it select JackMoebius).
Listings
{"command":"jack_list"}→ exposed output boxes (stems and cards), each without_status(+current_deviceon a mismatch).{"command":"jack_list_in"}→ exposed input cards and apps on the shared input, each within_status.{"command":"jack_assignments"}/jack_assignments_in→ the persistent reservations.
Volume and blacklist
{"command":"set_volume","app":"<name>","locked":false,"gain":0.5}→ per-app output volume (locked = follows theJackMoebiusdevice volume; unlocked = independent linear gain). Reply{app,key,locked,gain}.{"command":"blacklist_show|blacklist_add|blacklist_remove|blacklist_reset", …}.
Doctor
→ {"command":"doctor"}
← {"status":"ok","data":{"messages":[
{"code":"app_input_mismatch","severity":"warning","app":"REAPER",
"text":"REAPER does not read its JackMoebius card.",
"remedy":"In REAPER, choose \"JackMoebius for REAPER\" as the input device."}]}}messages is empty when nothing is wrong, errors come before warnings. Each message has a stable code (localize from it; text and remedy are English sentences), a severity (error | warning), the display name of the app when the message is about one, a text and a remedy. The CLI prints the same list (jackmoebius doctor, --json for this object).
Errors
An error reply carries a stable code and, when it helps, a details object. Show the English message as a fallback and translate from the code. A refused request changes nothing: the check happens before any change, so you can read apps and status as they were.
← {"status":"error","message":"not enough free forward channels (need 16, 4 free)","code":"capacity_forward_full",
"details":{"needed":16,"free":4,"held":0,"largest_holders":[{"app":"REAPER","key":"com.cockos.reaper","channels":64,"dead":0}]}}code |
When |
|---|---|
jack_not_running |
no JACK server |
transport_not_ready |
a card is asked while the shared-memory bridge is not up |
app_not_running, no_audio_context |
no running app matches, or it holds no audio context yet (details.app) |
not_capture_capable |
an input is asked of an app that cannot capture |
app_blacklisted |
the app is on the blacklist |
invalid_channel_count |
a width outside 1 to 64 (details.direction, given, min, max) |
capacity_forward_full, capacity_reverse_full |
not enough free channels (details.needed, free, held, largest_holders). For a shared output (a stereo pair), free counts what a pair can really use, free_pairs the free stereo pairs among them (free above 0 with free_pairs at 0 means a fragmented bus), and own_held, when present, the app’s own output channels that would stay held because its input card keeps the device |
slot_exhausted |
no card slot left |
jack_port_limit |
JACK refused to register a port (details.ports_registered) |
backing_required, nothing_to_apply |
a malformed jack_add or jack_apply |
card_not_created, no_card |
the driver did not create the card, or jack_rebuild found no card |
licensing |
the trial has expired |
Event stream
Send {"command":"subscribe"} on a dedicated connection. The daemon keeps it open and streams one event line per change (invalidations, never full state):
→ {"command":"subscribe"}
← {"event":"exposure_changed"} # a box was added/removed (out or in)
← {"event":"apps_changed"} # app launched/quit, capture-capability, blacklist
← {"event":"routing_changed"} # an app's device usage may have changed
← {"event":"shared_input_changed"} # an app entered or left the shared input, or its ports came or went
← {"event":"transport_changed"} # the shared-memory transport came up, or its problem changed
← {"event":"jack_changed"} # JACK came up / went down
← {"event":"licensing_changed"} # trial/license state changed (day count, activation, revoke)
← {"event":"stopping"} # clean shutdown, just before the socket closesOn each event, re-fetch the matching query (single source of truth). Ordering matters: subscribe then your first fetch, so nothing slips through the gap.
Liveness is free: while the connection is open, the daemon is alive. An EOF preceded by stopping = a clean stop; a bare EOF = a crash.
Routing status
jack_list / jack_list_in report, per box, whether the app actually uses the right JackMoebius device:
| value | meaning |
|---|---|
ok |
the app reads/writes the right JackMoebius device |
mismatch |
the app uses another device (also returns current_device + current_device_uid) |
idle |
the app uses no device of that direction yet |
absent |
the app is not running |
The colour is the front-end’s choice: a GUI shows a green / red / amber indicator, and raises an alert only for boxes it knows are wired.