IPC protocol documentation

JackMoebius IPC protocol reference: the JSON socket API a front-end like JackMate uses to drive routing, exposure and live status.

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, mode 0600 (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 subscribe connection 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).

  • bridge is shm once the shared-memory transport between the driver and the daemon is up, or waiting, with a structured transport_problem that says why (service not installed, switched off, unreachable, version mismatch, slot busy, driver not attached).
  • shared_input says whether the ports shared_input_1/2 exist and which apps share them.
  • capacity is how full the two buses are, in channels (254 usable each way, shared by all apps). held says how many of the used channels are held by a stream that a card kept after its side was dropped, and held_by which apps (see jack_rebuild).
  • default_input_is_jackmoebius tells whether apps without a device menu reach the shared input.
  • licensing carries {state, days_remaining} (state ∈ trial | licensed | expired; days_remaining is present for trial/expired, absent for licensed). 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 via licensing_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 state add set), per direction.
  • out_backing / in_backing: shared (the common JackMoebius device) or private (a card: a virtual device of its own, named JackMoebius 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 in capacity, and jack_rebuild frees 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 with out_status (+ current_device on a mismatch).
  • {"command":"jack_list_in"} → exposed input cards and apps on the shared input, each with in_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 the JackMoebius device 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 closes

On 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.

Back to top