"The LV2 adapter against mod-host and jalv: size and structure"

What is compared

mod-host and jalv are applications, each with one audio backend (JACK) and a socket or user-interface front. The adapter is a library: it presents one LV2 plugin as a CLAP plugin and has no backend. Measuring the host cores without their fronts and backends keeps the three comparable. The script that measures them, tools/hosting-compare.sh in omx-clap-core, clones the subjects and prints every table below.

Size

External dependencies are the distinct include roots: the adapter clap lilv lv2 omxcontract; mod-host jack lilv lv2 mach; jalv lilv lv2 serd sratom zix.

Complexity

Cyclomatic complexity per function (lizard):

The most branched functions are the adapter's instance_make (CCN 86), plugin_process (62), read_ports (57) and read_side (50); mod-host's effects_add (127, 736 lines), ProcessPlugin (122), effects_remove (70) and RunPostPonedEvents (68); jalv's jalv_open (21).

Lines of code by area (functions matched by name, the count in brackets; a heuristic, since code inside one large function is filed under that function's area):

The same tasks in the three

• Instantiate and connect a stereo effect. All three read the plugin through lilv, instantiate it and connect its ports. The adapter judges the plugin from its description and refuses it with a code before any binary is opened, and it connects every port once, to memory the instance owns, copying audio in and out each block. mod-host copies too; jalv connects the JACK buffer in place every cycle.
• A MIDI instrument on an atom port. All three write the incoming events into an event buffer before run and read the outgoing ones after. The adapter's output is bounded by its own capacity.
• The worker extension. The same design in all three: a request ring, a thread, a response ring drained before run, then end_run. The adapter's is 88 lines against 78 and 153.
• State save and restore. All three go through lilv_state_*. The adapter restores live for a plugin that declares state:threadSafeRestore and otherwise holds the state and applies it at the next activate; jalv pauses the audio thread instead. The adapter confines a plugin's make_path to its state directory and refuses a path outside it.
• A sample-rate change. CLAP may activate a plugin again at another rate, so the adapter tells the plugin through options:interface when it can and instantiates it again when it must. Neither JACK host handles a rate change at run time: both read the rate once. All three handle a change of block length.
• CV and aux ports. The adapter groups aux, CV and surround ports by pg:group and designation and offers them as CLAP audio ports. mod-host exposes CV ports as JACK ports and as a control source; jalv as audio ports with CV metadata. Neither turns a port group into a bus.

Where the adapter is bigger, and why

• Refusal before instantiation, with a code for each reason: every plugin is judged from its description before its binary is opened. This is the hosting contract.
• The CLAP face: the parameter table, its text and value maps, the contract and the descriptor (413 lines), which the others have no need of.
• A live rate or block change (157 lines against 7 and 46).
• Layouts, aux, sidechain and surround as CLAP audio ports (236 lines against none).
• State: live and held restore, confined paths and CLAP preset discovery (522 lines against 456 and 177).
• A run path with no lock and no allocation, proven by an allocation witness in the tests; jalv's run path is the same in this respect.

Against jalv, the adapter has 1.42 times the code and 1.76 times the mean complexity. The four areas jalv does not have (the CLAP face, layouts and aux, a rate change, and the part of state beyond jalv's) come to 1151 lines, which covers most of the 1678-line gap.

The accidental complexity is in three functions: instance_make binds ports by testing every role for every port index, plugin_process repeats one "host channel or silence" loop for each kind of leg, and read_ports and read_side hold the rule of every port kind in one function each. Building a role table when the description is read, one helper per leg, and one classifier per port kind would remove most of it, with the existing refusal and allocation tests as the guard.

Coverage

The same question put to the three hosts: of 979 LV2 plugins installed on one Fedora 44 machine, how many does each host instantiate and activate on a live graph? A private namespace with its own PipeWire at 48 kHz, one plugin at a time, ten seconds per reply. Hosted means admitted, instantiated and activated; it is not a claim of identical audio.

In short

The three hosts make the same lilv calls in the same order: instantiate, connect, a worker of two rings and a thread, and state through lilv_state_*. The adapter is smaller and less branched than mod-host's core on every measure above, and 1.4 times jalv, where the difference is almost all features the CLAP contract requires.