The plugin-hostd protocol

The plugin-hostd protocol is a superset of mod-host's text protocol: any mod-host client works unchanged.

Protocol plugin-hostd, version 1 of its JSON declaration (protocol/plugin-hostd.json); mod-host's protocol as the daemon models it is protocol/mod-host.json, version 1, written from the mod-host headers mod-host.h, protocol.h, host-errors.h the daemon is built against. The verbs the daemon adds are declared in data/verbs.json (since 0.12.0, requiring omx-contract-schema >= 3.3.0, omx-clap-core >= 0.23.0).

1. Transport

A command is one line of words, the verb first; a reply is resp <code> [...]: the words after the code are the verb's reply grammar below, and a negative code is a refusal, named in Reply codes. Events go out on the feedback port, one line each (4. Events and feedback).

Discovery: the daemon declares itself in files, not on the socket. The verb tables below are installed as:

pkg-config --variable=protocoldir plugin-hostd-protocol names that directory, and --variable=table, grammar and protocoljson name the files. The protocol and version keys of the protocol JSON identify it; no verb below answers a version.

The verb table and the grammar

protocol/plugin-hostd-protocol.json is the one table of the protocol: every command, each once, with its origin, its argument types, its reply and its refusals, and every feedback line. It is merged from protocol/mod-host.json, protocol/plugin-hostd.json, data/verbs.json, include/plugin-hostd/omx_clap_core_host_verbs.h by tools/protocol-table.py; 48 commands of origin mod-host, 27 commands of origin plugin-hostd, 11 commands of origin omx-clap-core, 21 feedback lines.

grammar/plugin-hostd-protocol.abnf is the grammar of a line, in ABNF (RFC 5234, with RFC 7405's case-sensitive strings): the lexical core, written once by hand (grammar/core.abnf), and a rule per command, per feedback line and per parse refusal generated from the table by tools/abnf-gen.py. Every line of the scenario corpus and every reply the library writes in the golden transcript is held to it (make test-grammar).

A word of another origin that mod-host also has either extends mod-host's command (takes its arguments, in its types, first, and more only where mod-host's command takes a tail), or is a second form of the word told apart from mod-host's by its number of arguments, so that a line of mod-host's form is always answered as mod-host answers it. Any other is refused: the table is not written, and there is no list of exceptions. The words with more than one form:

2. mod-host's verbs on plugin-hostd

required is answered as its grammar says; optional is answered, or refused with -902, and never misread; absent is refused on purpose, and no client of the profile may need it.

Answer: same is relayed to the worker that holds the instance (any other verb to every worker) and answered as that worker answers it; differs is a verb plugin-hostd declares a grammar or a behaviour of its own for, or one the Path A run observed answered otherwise on the LV2 worker; refused is absent of every profile. The argument types are mod-host's templates (int %i, word %s, float %f, ... an optional tail); the declarations carry no unit per argument, and a range or a unit a verb has is in its meaning.

mod-host's templates name no reply codes per verb: a relayed verb answers what its worker answers, or one of -503 WORKER_SPAWN (the worker is not up: the spawn failed, or it is in backoff; ask again after instance_restored) or -507 VERB_DROPPED (the worker died on this very command and the daemon dropped it: it is not replayed, and the instance_verb_dropped event names it; or it died on, or did not answer in rpc_timeout_ms, the pin_expect of an add, which is then never forwarded).

Required of every profile

Optional

Absent: refused on purpose

Verbs of Zynthian's mod-ui that are no mod-host command, each refused:

The Path A evidence

doc/evidence/mod-ui-verbs.tsv: every verb Zynthian's mod-ui sends, replayed against mod-host and against plugin-hostd. The column heads name the versions that ran; the rows are what was observed then, not run again by this page.

3. Verbs mod-host does not have

Each is declared in protocol/plugin-hostd.json; the formats, codes and hosts come from data/verbs.json, or from omx-clap-core's verb table for a verb the two hosts share. A verb whose meaning begins "sent by the daemon to a worker" is the daemon's to a worker, never a controller's.

Placement and supervision

worker_list:

> worker_list
< resp <n> <worker>:<pid>:<format>:<state>:<core>:<pool>:<place>:<i>,<i>,...

instance_info:

> instance_info 0
< resp 0 <worker> <pid> <state> <crashes> <quarantined>

supervisor_reset:

> supervisor_reset
< resp 0

quarantine_clear:

> quarantine_clear 0
< resp 0

policy_set:

> policy_set clap own
< resp 0

pool_config:

> pool_config fx 4
< resp 0

worker_env:

> worker_env clap - -
< resp 0

lv2_worker_set:

> lv2_worker_set lv2:urn:openmixer:comp omx-clap-host
< resp 0

Pins and qualification

pin_set:

> pin_set clap:/usr/lib/clap/omx-comp.clap#org.openmixer.comp <path>=<sha256> <scheme>:<sha256>
< resp 0

pin_clear:

> pin_clear clap:/usr/lib/clap/omx-comp.clap#org.openmixer.comp
< resp 0

pin_reload:

> pin_reload
< resp 0

pin_changed:

> pin_changed
< resp 0

pin_accept:

> pin_accept clap:/usr/lib/clap/omx-comp.clap#org.openmixer.comp
< resp 0

pin_layout:

> pin_layout 0
< resp 0 <scheme>:<sha256>

pin_expect:

> pin_expect 0 <scheme>:<sha256>
< resp 0

Chains and plans

chain:

> chain 1 0 1
< resp 0

chain_clear:

> chain_clear 1
< resp 0

chain_get:

> chain_get 1
< resp 0 <worker> <instance>,... <instance>,...

plan:

> plan 1 0 1
< resp 0 <instance>,...;<instance>,...;... <core>,...;<core>,...;...

plan_get:

> plan_get 1
< resp 0 <instance>,...;<instance>,...;... <instance>:<reason>,... <core>,...;<core>,...;...

plan_clear:

> plan_clear 1
< resp 0

estimate:

> estimate <rate> <quantum> clap:/usr/lib/clap/omx-comp.clap#org.openmixer.comp
< resp 0 <latency_frames> <cpu_percent> <ram_bytes> <workers> <unknown_count> <member>:<code>,... <ram_used_bytes> <ram_added_bytes> <ram_budget_bytes> <ram_unknown_count>

Descriptors, panels and the running history

descriptor_get:

> descriptor_get clap:/usr/lib/clap/omx-comp.clap#org.openmixer.comp
< resp 0 "<path>"

panel_get:

> panel_get clap:/usr/lib/clap/omx-comp.clap#org.openmixer.comp
< resp 0 "<path>"

history_get:

> history_get clap:/usr/lib/clap/omx-comp.clap#org.openmixer.comp
< resp 0 <history>

history_clear:

> history_clear clap:/usr/lib/clap/omx-comp.clap#org.openmixer.comp
< resp 0

Presets and notes, by instance

preset_list:

> preset_list 0
< resp <count>

preset_get:

> preset_get 0 0
< resp 0 <load_key> <name>

note_input:

> note_input 0
< resp 0 <port | ->

note_on:

> note_on 0 0 60 100
< resp 0

note_off:

> note_off 0 0 60 100
< resp 0

all_notes_off:

> all_notes_off 0
< resp 0

4. Events and feedback

mod-host's feedback lines, relayed as the worker wrote them:

The daemon's events and the worker lines it relays:

The relay rules:

• VERBATIM: every line a worker writes on its feedback port goes out on the daemon's feedback port as the worker wrote it: output_set, param_set, data_finish and the rest of mod-host's feedback, and a line the daemon does not know
• INSTANCE: the instance number in a relayed line is already the controller's: add hands it to the worker unchanged, so nothing in a line is rewritten
• ORDER: a worker's lines go out in the order it wrote them, and what a worker wrote before it died goes out before its worker_died event; an instance lives in one worker at a time, so its lines keep their order across a respawn; the lines of different workers interleave
• SUBSCRIPTION: monitor_output is in the ledger, one line per output, and param_monitor as it was sent; a respawn replays them after the add, so a respawned instance reports the same outputs, each once, starting again from its first value
• HANDSHAKE: output_data_ready names no instance and goes to every worker; each worker's data_finish is relayed
• NO_CONTROLLER: with no feedback port, or no controller on it, a line is dropped, as mod-host drops it; the daemon reads every worker's feedback all the time, so no worker waits on it

Host settings

• TEMPO: the tempo, the metre and the transport a controller sets (mod-host's set_bpm, set_bpb, transport and transport_sync) are kept, the latest line of each as it was sent, in the order they were last sent
• REPLAY: a worker is handed them before anything else: a respawned one before its first add, and a worker started later, of a new placement, as well; a worker's refusal of one is written to stderr and is no failure
• GRAMMAR: a line whose words are not that command's grammar is passed on and not kept

Reply codes

mod-host's parse refusals (protocol.h): -1 PROTOCOL_NOT_FOUND (not found); -2 PROTOCOL_MANY_ARGUMENTS (many arguments); -3 PROTOCOL_FEW_ARGUMENTS (few arguments); -4 PROTOCOL_INVALID_ARGUMENT (invalid argument).

mod-host's reply codes (host-errors.h): 0 SUCCESS; -1 ERR_INSTANCE_INVALID; -2 ERR_INSTANCE_ALREADY_EXISTS; -3 ERR_INSTANCE_NON_EXISTS; -4 ERR_INSTANCE_UNLICENSED; -101 ERR_HOST_INVALID_URI; -102 ERR_HOST_INSTANTIATION; -103 ERR_HOST_INVALID_PARAM_SYMBOL; -104 ERR_HOST_INVALID_PRESET_URI; -105 ERR_HOST_CANT_LOAD_STATE; -101 ERR_LV2_INVALID_URI; -102 ERR_LV2_INSTANTIATION; -103 ERR_LV2_INVALID_PARAM_SYMBOL; -104 ERR_LV2_INVALID_PRESET_URI; -105 ERR_LV2_CANT_LOAD_STATE; -201 ERR_JACK_CLIENT_CREATION; -202 ERR_JACK_CLIENT_ACTIVATION; -203 ERR_JACK_CLIENT_DEACTIVATION; -204 ERR_JACK_PORT_REGISTER; -205 ERR_JACK_PORT_CONNECTION; -206 ERR_JACK_PORT_DISCONNECTION; -207 ERR_JACK_VALUE_OUT_OF_RANGE; -301 ERR_ASSIGNMENT_ALREADY_EXISTS; -302 ERR_ASSIGNMENT_INVALID_OP; -303 ERR_ASSIGNMENT_LIST_FULL; -304 ERR_ASSIGNMENT_FAILED; -305 ERR_ASSIGNMENT_UNUSED; -401 ERR_CONTROL_CHAIN_UNAVAILABLE; -402 ERR_ABLETON_LINK_UNAVAILABLE; -403 ERR_HMI_UNAVAILABLE; -404 ERR_EXTERNAL_UI_UNAVAILABLE; -901 ERR_MEMORY_ALLOCATION; -902 ERR_INVALID_OPERATION.

The codes omx-clap-host answers too (omx-clap-core's reply.host.*):

The codes the daemon adds:

5. JSON documents

Counts: 48 mod-host commands, 34 same, 8 differs, 6 refused; 32 verbs mod-host does not have.

Appendix: mod-host's command reference

The "Commands (or Protocol)" section of mod-host's README (FreeMixer/mod-host, branch freemixer, 013ac7d), kept as it is. Copyright 2013-2026 Filipe Coelho, MOD Audio UG and the mod-host contributors, GPL-3.0-or-later.

Where it says "mod-host", read "the host": any host built on this library answers these commands. The library parses and dispatches them; what a command does to a plugin is the host's backend (host_backend_t, include/host-backend.h).

Commands (or Protocol)

The commands supported by mod-host are:

add <lv2_uri> <instance_number> [client_name]
    * add an LV2 plugin encapsulated as a jack client
    e.g.: add "http://lv2plug.in/plugins/eg-amp" 0
    instance_number must be any value between 0 ~ 9990, inclusively
    client_name is optional; when omitted the jack client (and so the graph node) is
    named "effect_<instance_number>", same as always. When given, mod-host tries to
    open the jack client under that name instead -- so a host running many plugins
    shows a graph with a name per plugin instead of an undifferentiated effect_0,
    effect_1, effect_2... The name is sanitised for jack (':' is replaced with '_',
    since jack uses ':' as the client:port separator, and it is truncated to the
    running jack backend's client name limit) and, on a collision with an existing
    jack client, disambiguated by appending "_<instance_number>". If the sanitised
    name is empty, or the name still collides after the instance number is appended,
    mod-host falls back to the default "effect_<instance_number>" rather than fail
    the add.
    e.g.: add "http://lv2plug.in/plugins/eg-amp" 0 "channel1-eg-amp"

remove <instance_number>
    * remove an LV2 plugin instance (and also the jack client)
    e.g.: remove 0
    when instance_number is -1 all plugins will be removed

preset_load <instance_number> <preset_uri>
    * load a preset state of an effect instance
    e.g.: preset_load 0 "http://drobilla.net/plugins/mda/presets#JX10-moogcury-lite"

preset_save <instance_number> <preset_name> <dir> <file_name>
    * save a preset state of an effect instance
    e.g.: preset_save 0 "My Preset" "/home/user/.lv2/my-presets.lv2" "mypreset.ttl"

preset_show <preset_uri>
    * show the preset information of requested URI
    e.g.: preset_show "http://drobilla.net/plugins/mda/presets#EPiano-bright"

connect <origin_port> <destination_port>
    * connect two jack ports
    e.g.: connect "system:capture_1" "effect_0:in"

disconnect <origin_port> <destination_port>
    * disconnect two jack ports
    e.g.: disconnect "system:capture_1" "effect_0:in"

bypass <instance_number> <bypass_value>
    * toggle effect processing
    e.g.: bypass 0 1
    if bypass_value = 1 bypass effect
    if bypass_value = 0 process effect

param_set <instance_number> <param_symbol> <param_value>
    * set the value of a control port
    e.g.: param_set 0 "gain" 2.5

param_get <instance_number> <param_symbol>
    * get the value of a control port
    e.g.: param_get 0 "gain"

param_monitor <instance_number> <param_symbol> <cond_op> <value>
    * monitor a control port according to a condition
    e.g: param_monitor 0 "gain" ">" 2.5

patch_set <instance_number> <property_uri> <value>
    * set the value of a control port
    e.g.: patch_set 0 "gain" 2.5

patch_get <instance_number> <property_uri>
    * get the value of a control port
    e.g.: patch_get 0 "gain"

licensee <instance_number>
    * get the licensee name for a commercial plugin
    e.g.: licensee 0

monitor <addr> <port> <status>
    * open a socket port for monitoring parameter changes
    e.g: monitor localhost 12345 1
    if status = 1 start monitoring
    if status = 0 stop monitoring

monitor_output <instance_number> <param_symbol>
    * request monitoring of an output control port (on the feedback port)
    e.g.: monitor_output 0 "meter"

midi_learn <instance_number> <param_symbol> <minimum> <maximum>
    * start MIDI learn for a control port
    e.g.: midi_learn 0 "gain" 0.0 1.0

midi_map <instance_number> <param_symbol> <midi_channel> <midi_cc> <minimum> <maximum>
    * map a MIDI controller to a control port
    e.g.: midi_map 0 "gain" 0 7 0.0 1.0
    a non-standard midi_cc value of 131 (0x83) is used for pitchbend

midi_unmap <instance_number> <param_symbol>
    * unmap the MIDI controller from a control port
    e.g.: midi_unmap 0 "gain"

monitor_midi_program <midi_channel> <enable>
    * listen to MIDI program change messages (on the feedback port)
    e.g.: monitor_midi_program 0 1

set_midi_program_change_pedalboard_bank_channel <enable> <midi_channel>
    * set the MIDI channel which changes pedalboard banks on MIDI program change. <midi_channel> is in the range of [0,15].
    e.g.: set_midi_program_change_pedalboard_bank_channel 1 5 to enable listening for bank changes on channel 6

set_midi_program_change_pedalboard_snapshot_channel <enable> <midi_channel>
    * set the MIDI channel which changes pedalboard snapshots on MIDI program change. <midi_channel> is in the range of [0,15].
    e.g.: set_midi_program_change_pedalboard_snapshot_channel 1 4 to enable listening for preset changes on channel 5

cc_map <instance_number> <param_symbol> <device_id> <actuator_id> <label> <value> <minimum> <maximum> <steps> <extraflags> <unit> <scalepoints_count> <scalepoints...>
    * map a Control Chain actuator to a control port
    e.g.: cc_map 0 "gain" 0 1 "Gain" 0.0 -24.0 3.0 33 0 "dB" 0

cc_unmap <instance_number> <param_symbol>
    * unmap the Control Chain actuator from a control port
    e.g.: cc_unmap 0 "gain"

cc_value_set <instance_number> <param_symbol> <value>
    * set the value of a  mapped Control Chain actuator
    e.g.: cc_value_set 0 "gain" 2.5

cv_map <instance_number> <param_symbol> <source_port_name> <minimum> <maximum> <operational-mode>
    * map a CV source port to a control port, operational-mode being one of '-', '+', 'b' or '='
    e.g.: cv_map 0 "gain" "AMS CV Source:CV Out 1" -24.0 3.0 =

cv_unmap <instance_number> <param_symbol>
    * unmap the CV source port actuator from a control port
    e.g.: cv_unmap 0 "gain"

cpu_load
    * return current jack cpu load

load <file_name>
    * load a history command file
    * dummy way to save/load workspace state
    e.g.: load my_setup

save <file_name>
    * saves the history of typed commands
    * dummy way to save/load workspace state
    e.g.: save my_setup

bundle_add <bundle_path>
    * add a bundle to the running lv2 world
    e.g.: bundle_add "/path/to/bundle.lv2"

bundle_remove <bundle_path> <resource>
    * remove a bundle from the running lv2 world
    e.g.: bundle_remove "/path/to/bundle.lv2" ""

feature_enable <feature> <enable>
    * enable or disable a feature
    * feature can be one of "aggregated-midi", "freewheeling" or "processing"
    * the "aggregated-midi" feature requires the use of jack2 and mod-midi-merger to be installed system-wide
    e.g.: feature_enable link 1

set_bpm <beats_per_minute>
    * set the global beats per minute transport value
    e.g.: set_bpm 120

set_bpb <beats_per_bar>
    * set the global beats per bar transport value
    e.g.: set_bpb 4

transport <rolling> <beats_per_bar> <beats_per_minute>
    * change the global transport state
    e.g.: transport 1 4 120

transport_sync <mode>
    * change the transport sync mode
    * mode can be one of "none", "link" or "midi"
    e.g.: transport_sync "midi"

output_data_ready
    * report feedback port ready for more messages

track_info <instance_number> <name> <color> [bus|return|master]
    * pass the name and color of the mixer track the instance sits on, color as #RRGGBB or - for none
    * an LV2 plugin has no way to receive them, so mod-host answers -902
    e.g.: track_info 0 "Kick In" #FF8000

remote_pages <instance_number>
    * get the number of remote-control pages of the plugin (8 parameters per page); 0 for an LV2 plugin
    e.g.: remote_pages 0

remote_page_get <instance_number> <page_index>
    * get one remote-control page: resp 0 <page_id> <section_name> <page_name> <symbol> x8, - for an empty slot
    e.g.: remote_page_get 0 0

param_info <instance_number> <param_symbol>
    * get what a control means: resp 0 <unit> <scale> <minimum> <maximum> <default> <step> <stable_symbol>
    * unit is an LV2 unit name (db, hz, ms, ...) or none, scale is linear, log or stepped, step 0 is continuous
    e.g.: param_info 0 "gain"

help
    * show a help message

quit
    bye!

For each effect added one client on JACK will be created. The names of clients follow the standard: effect_<instance_number>

If a valid command is executed a response is given as following:

resp <status> [value]

If status is a negative number an error has occurred. The table below shows the number of each error.

A status zero or positive means that the command was executed successfully. In case of the add command, the status returned is the instance number. The value field exists for the param_get, remote_page_get and param_info commands.

When the plugin changes its remote-control pages, the feedback port gets:

remote_pages_changed <instance_number>