Plugin controls and panels
How a plugin's controls reach the console's screen: what the plugin formats declare, what openmixer adds on top, and what a plugin you did not write gets today. The decisions are in the specs linked at the end; this page states how the pieces fit.
Standards carry the parameters, not the panel
Both plugin formats describe a flat list of controls. Neither describes a panel layout that the console reads.
- LV2 declares ports in its TTL: range and default,
units:unitandunits:symbol, scale points (labelled choices), and the port properties for toggled, integer, enumeration, logarithmic, trigger and not-on-GUI. The plugin-qualify scan (scan.py) reads all of these. Port groups (pg:Group) are not read, so the console cannot section an LV2 plugin by what it declares. - CLAP declares parameters through
clap.params: id, name, minimum, maximum, default and the stepped, enum and hidden flags. CLAP has no unit, no scale and no symbol. The qualification prober scans a parameter'smodulepath and the plugin's remote-control pages (FreeMixer/plugin-qualify#11, closed). The console's reader (plugin-qualify'sclap-loader.ts) still uses the decimal parameter id as the symbol, draws every parameter linear and does not ask for enum labels, and nothing in the console turns the module paths or the remote pages into sections or pages.
Both scans produce one PluginParam shape (the catalog's), served on
/plugins/{uri}. A row's travel and taper are derived once, in
the catalog's control-travel.ts, and the server builds the panel description from the same
parameters.
What openmixer adds
Everything above "a list of controls" is declared by openmixer.
The parameter contract, org.openmixer.param-contract/1, is a CLAP extension that gives a
parameter the symbol, unit and scale CLAP lacks. The unit vocabulary is LV2's units one for one
plus a vendor block (core's clap-param-units.ts). No plugin serves the extension yet.
The panel description, org.openmixer.panel-description/1, describes the panel itself:
the plugin's family and the role of each parameter (so one compressor view binds any compressor),
ordered sections, a widget per control, displays bound to meters or to a family's closed-form
curve, per-placement defaults, and a SHA-256 fingerprint. Presets, pages and the manual are taken
from the standard CLAP mechanisms, not redeclared. Clients receive it as the ServedDescription
(core's served-description.ts), which also holds the closed vocabularies: the
families, the widgets (auto, knob, fader, switch, selector) and the display kinds
(gain_reduction_bar, transfer_curve, eq_response, meter).
Skin packages replace or refine a description's look and layout. A package is a directory
<xdg>/openmixer/skins/<id>/ holding skin.json and, optionally, an ES-module view written
against the versioned Skin API. The schema, id encoding and view lint are
in @openmixer/omx-panel (the console imports them; the MOD GUI importer is its omx-panel import); the server resolves a plugin's package at three levels and
serves it under /skins/<id>. The client chooses a view
in this order (the web UI's panel-view.ts): a custom skin view, a house view,
level 2 (a generic panel built from the description's sections and roles), then the flat pages of
eight.
House views for delay, dynamics, EQ, reverb and modulation are declared in
the web UI's house-views.ts.
For plugins openmixer ships, the declaration in omx-plugins (plugins/<p>/<p>.decl.json)
refers to omx-contract for every number and adds panel (family, roles, sections) and console
(placement, card, chip, panel) blocks. Each format's output is generated from that one
declaration: the LV2 TTL, the CLAP parameter tables, and the MOD GUI export below.
modgui
modgui is export only. For each of its LV2 bundles, omx-plugins generates a modgui.ttl and the
HTML, CSS and image files MOD-style hosts expect, from the declaration's panel block
(tools/modgui-gen.mjs). Nothing in the console reads a modgui: a modgui that comes with a
third-party LV2 bundle is ignored. Importing third-party modguis as skin packages is specified
and not implemented.
The two doors
A plugin's own interface has two ways in, and the choice is settled:
- The web renderer draws the description as console panels. This is the console's only door: in the mixer every plugin, ours or a third party's, is drawn by the console from its description, never in a native plugin window (operator ruling, 2026-10-19).
- A native window, a pugl and NanoVG renderer for openmixer's own plugins, draws the same
description in a separate window for a DAW or the standalone omx-clap-host, never under the
console. It is a separate static library with no GPU required. A plugin's own window is tried Wayland floating first, then
X11 embedded, then X11 floating (ruled 2026-10-24, omx-clap-core#329). CLAP's Wayland API is
floating only, with no parent handle, so over Wayland the plugin's window is its own top-level
window that the host shows and hides. omx-clap-core 0.19.0 is the release that carries this
order. Hosting a third-party plugin's own
clap.guiwindow or an LV2 desktop UI is a later step for the standalone omx-clap-host only; plugin-hostd has no show or hide message and gets none.
What is wired today
- The roster is curated:
/api/pluginsoffers only the plugins of the curated list (86 on the live console, 2026-10-26) while the host admits every installed LV2 plugin the desk holds (979 of 979, measured 2026-10-20), and no third-party CLAP plugin is offered. Operator ruling 2026-10-26: the roster comes from qualification records, an unsuitable plugin is listed dimmed in place with its reason, and the curated list survives only as a "recommended" mark and the picker's default sort. That is not built yet. - The console builds a
ServedDescriptionfor every plugin on/plugins/{uri}with omx-panel'sdescribe, the one derivation every surface calls: over the plugin's descriptor document (the descriptor directory's, else the catalog row converted once in memory) it serves each control's contract facts, the sections from the port groups, the family from the plugin's declared class kept only when its controls back it, the roles (an EQ's bands inferred and marked), the displays and the pages, cut by the library's one cut. The plugin's skin package is resolved on the same read and handed todescribe, which applies its override before the pages are cut. - The editor (the
PluginEditorcomponent) draws only that description, through the chooser; a trigger draws as a momentary button, a stepped integer with typed entry; an override entry the plugin cannot take is apanel.describe.skin-droppedrefusal onskin, and a plugindescriberefuses is served refused, by itspanel.describe.*code, with no panel. - The browser never derives. Where no console row describes a slot (offline, a plugin outside the roster, before the row lands) the editor says so and draws no control.
- EQ bands: a linear-factor gain (LSP, Calf) is a
coefband gain the response converts to dB, a band's fixed shape rides on itsband_freqrole, and a gainless HP/LP band is the head filter. - The console's own native stages (EQ, gate, dynamics, delay, reverb, drive, modulation, de-esser,
limiter) have bespoke Vue panels fed by the wire's travels (the
FxPanelcomponent).
What a third-party plugin gets
| Plugin | Today | With a skin package or qualification record |
|---|---|---|
| LV2 | Level 2 with one section: ranges, units, logarithmic knobs, toggles and labelled choices. An EQ whose bands the catalogue models gets the EQ house view. | Level 2 or a house view, using the roles and sections the package declares. |
| CLAP | Not offered unless it is in the curated list (none is). If drawn: level 2 with one section, range and default, stepped flags and numeric symbols; enums have no labels, units are missing, log parameters draw linear, module paths and remote pages are not used. | The same, once the package supplies symbols, units and roles. |
Where the declarations differ
- The generated CLAP faces serve only params, latency, audio-ports, state and
org.openmixer.declaration/1: neitherparam-contract/1norpanel-description/1, no remote controls and no track info (omx-plugins#102). - The LV2 faces carry no port groups (omx-plugins#103).
panel.familyandpanel.rolesin the omx-plugins declarations do not follow the closed set the console accepts (omx-plugins#99), the panel is written twice, inpanel.sectionsandconsole.panel.sections(omx-plugins#100), and the widget names differ between the schema, the modgui generator and the console (omx-plugins#101).- omx-contract holds no meter readouts and no kernel sets a scale (omx-contract#22).