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:unit and units: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's module path and the plugin's remote-control pages (FreeMixer/plugin-qualify#11, closed). The console's reader (plugin-qualify's clap-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.gui window 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/plugins offers 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 ServedDescription for every plugin on /plugins/{uri} with omx-panel's describe, 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 to describe, which applies its override before the pages are cut.
  • The editor (the PluginEditor component) 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 a panel.describe.skin-dropped refusal on skin, and a plugin describe refuses is served refused, by its panel.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 coef band gain the response converts to dB, a band's fixed shape rides on its band_freq role, 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 FxPanel component).

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: neither param-contract/1 nor panel-description/1, no remote controls and no track info (omx-plugins#102).
  • The LV2 faces carry no port groups (omx-plugins#103).
  • panel.family and panel.roles in the omx-plugins declarations do not follow the closed set the console accepts (omx-plugins#99), the panel is written twice, in panel.sections and console.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).