Interface MixerServerOptions

Pre-built adapter (skips loadAdapter). Used by tests to inject the mock and by embedders that already hold an adapter instance.

The declarative adapter framework. When supplied, the server runs an AdapterManager (loads config/adapters.{yaml,json}, instantiates enabled adapters, persists runtime changes) and serves the /adapter* REST entities (adapter-admin-rows.ts) off it.

The SMART ALIGNMENT measurement door (2026-08-31-smart-alignment.md): the PAIRED complex spectra two lanes give up in one snapshot pass. Its own option rather than a field of rta because it is a different reading — complex, of a PAIR, at one tap — even though it shares the analyser's rings and its demand ledger. A console without it still serves the /align row and the panel; the measurement simply refuses no-capture, which is the honest answer and a visible one.

Debounce window (ms) for the live-session autosave (operator #51): a console-mutating commit schedules a write of the live console under the store's reserved live-autosave id; further mutations within the window collapse into the same write (timed from the last one). Also written once, synchronously, on MixerServer.stop so a graceful shutdown never loses the tail of a show. Only relevant when persistence is configured. Default AUTOSAVE_DEBOUNCE_MS.

The console's plugin CATALOG — what it can rack, whether or not anything is attached to rack it with. /plugins and /plugins/{uri} are rows over this, and the rack door's plugins.values narrows it; a console that loads a catalog but has no plugin host still knows what it holds, and says so. plugins supplies it too, for a console whose host and catalog arrive together; this option wins where both are given.

Clip capture poll period (ms): how often the adapter's read-and-clear over flags are read into the /channel/{kind}/{index}/clip latches (2026-08-29-clip-latch.md §6.4). Runs regardless of demand — a latch catches what nobody is metering. Default CLIP_CAPTURE_INTERVAL_MS; 0 disables the poll.

Clock control for the clock.set verb (the config-zone quantum + sample-rate lever). Explicit injection always wins (tests inject a fake so the suite never touches the real system clock). Left unset, this resolves to a REAL PwMetadataClock — which shells out to pw-metadata -n settings 0 clock.force-quantum|force-rate and can re-clock the running graph — only when realHardwareDefaults is true; otherwise it resolves to NULL_CLOCK, which touches nothing.

Live-clock poll period (ms) for the honest-rate reflection (issue #159): every this-often the server re-reads the graph's LIVE clock.rate / quantum via the clock control's ClockControl.refreshLive and re-broadcasts clock.state when it changed — so a rate change made out-of-band (a PipeWire restart into a new persistent default.clock.rate) shows up in the UI without an operator action. Default CLOCK_POLL_INTERVAL_MS; 0 disables the poll (tests that don't want a background timer). The one-shot boot seed (which reads the live rate before the first client connects) runs regardless.

Validated configuration.

The box model the rig's reac adapter entry PINS (boxModel: s0808), for the reconciliation that says so when the wire disagrees with it.

A pin is the one thing here that is neither observed nor a preference: it is a stored copy of a fact the box states about itself, and on 2026-08-05 the copy said s1608 while an S-0808 was attached, with nothing anywhere comparing the two. Read once at start; a failed read is "nothing pinned", never a guess. Absent by default, so a server without it simply has nothing to contradict.

What the RIG is configured for, independent of any session — read fresh on each missing-hardware diff (the composition root reads the operator's reac adapter entries, which is where a box expectation is authored).

This is the seam behind the rig defect: every other expectation is scoped to the RESTORED SESSION, so a box the operator had configured — with reac-pw actively probing for it — went missing in silence whenever the show happened not to patch it. Absent by default: a server without this option keeps the pre-change, session-only behaviour. Must never throw; a failed read reports "nothing configured", never a phantom box.

The convergence instrument (task #48): the console-wide revision counter every frame and REST body is stamped with, the /telemetry/convergence heartbeat row published while watched, and the corrections log clients report their heals into. Always on when the console has a resource registry; this option only tunes it.

Core-lost watchdog poll period (ms) for engine reconnect-on-disconnect. Every this-often the server asks coreLostProbe whether the shared native PipeWire client has lost its daemon connection; on the first true it fires onCoreLost exactly once (and stops polling). Default CORE_LOST_POLL_INTERVAL_MS (~0.5 s → exit within ~1 s of the daemon going away); 0 disables the watchdog (tests that don't want a background timer, non-PipeWire deployments).

The connection-health probe the core-lost watchdog polls. Defaults to the native nativeCoreLost (reads the atomic latched by mix_host.c on a core -EPIPE). Tests inject a fake to drive the watchdog without a real daemon disconnect.

The native device-profile door (amendment 2026-09-15, later the same evening) — the LIVE half of the device-exclusivity policy, beside the drop-in's boot half. Defaults to deviceProfileDoor over loadPwGraph, which answers NO_BACKEND with no addon. Tests inject a fake card so the actuation and its read-back are exercised with no daemon.

The per-device native-rate probe (amendment 2026-09-15): every ALSA device the exclusivity policy currently sees, each with its own rate menu. Defaults to probeDeviceRates. Sampled on the SAME cadence writeDriverPolicyConfigs already regenerates the drop- ins on (device-set change, not a bare timer) — tests inject a fake so a bare MixerServer never shells out.

Network discovery. Requires adapters (so addAsAdapter has a manager). The provider is consumed through the core DiscoveryProvider interface so the server builds before @freemixer/discovery lands.

The follower-rate probe (2026-09-14): every actively-running sink's own native rate set. Defaults to probeFollowerRates. Sampled on the SAME cadence as xrunProbe — tests inject a fake so the suite never touches the real system graph.

The graph-patchbay GraphSource behind the REST /patchbay/* routes the web-ui Graph tab reads. Defaults to a PipeWireGraphSource (live pw-dump / pw-link), constructed lazily on first request so a host without PipeWire pays nothing at startup. Tests inject a fake to avoid shelling out.

Role-aware insert-suitability configuration (issue #339) — the per-role latency budgets, their enforcement, and any per-bus role/budget override. Unset roles fall back to the documented defaults in @freemixer/core (DEFAULT_LATENCY_BUDGET_MS), so a deployment that says nothing still gets a monitor bus that refuses what would ruin it.

Optional live-I/O enumerator for the patchbay (patchbay.list). Defaults to a PipeWireGraphProvider (a pw-dump graph read: every audio node — external apps, DAWs, ALSA devices — with friendly names) whenever a structural surface is present. Tests inject a fake to avoid shelling out.

How many gestures the undo JOURNAL holds before the oldest drops off the bottom. Default JOURNAL_BOUND (512, argued there). Configurable because a bound is a judgement about a show's length, and because an arm that proves the ring is bounded must be able to reach the bound without making 512 gestures.

Inject a logger setting; defaults to Fastify's default logger off.

Where to look for the prerendered documentation site, in order. Defaults to defaultManualSiteCandidates — the packaged install, then the workspace build. A layout seam, not a knob: it is what lets a test exercise the INSTALLED branch of the derivation without a real /usr/share/openmixer/manual on the machine.

The local plugin analysis (issue #342). Every field is a seam for tests or an unusual layout; a normal deployment sets none of them and the paths resolve from the installed @freemixer/catalog package.

The native door /patchbay/link and /patchbay/unlink dispatch through (patchbay-native-link.ts, nativeLinkDoor). Defaults to the real @freemixer/pipewire-native client. Tests inject a fake so the resolve/create/destroy seam is exercised with no daemon — a test that touches the real one belongs in that module's own private-daemon suite, never a plain unit test (lane-discipline §4).

Runtime-network settings surface (the Setup menu's Network panel): where config.set persists overrides, plus the per-field provenance the boot-time resolver computed (network-config.ts). Without a settingsFile (and no persistence dir to derive one from) config.set is rejected; config.get always works.

The per-node xrun probe (2026-09-14): pw-top's ERR column, kept per node rather than summed. Defaults to probeNodeXruns. Sampled on the same cadence as xrunProbe.

The clock the server reads for timestamps that BECOME STATE — today the tap-tempo detector, whose taps are differenced into a tempo the console then holds. Defaults to Date.now; the six-site convention (telemetry-rows.ts, rta-rows.ts, clock-drift-probe.ts, core's convergence.ts) is the same shape.

Time that MEASURES is deliberately not routed through here: performance.now() around a request, the perf histograms. Those observe the machine and should keep observing the real one. Only time whose value the console goes on to SERVE needs a seam, and it needs one because otherwise the test of a derivation is a test of the scheduler — which is how a 400 ms sleep that took 683 ms was reported as a wrong tempo (#153).

What to do when the core-lost watchdog detects the daemon connection is gone. Defaults to a clean process.exit(1) so systemd restarts the engine into a fresh connection (we do NOT attempt an in-process reconnect+re-export — too risky mid-graph). Tests inject a fake to observe the trigger without exiting the test runner.

Plugin-delay-compensation control for /console/pdc. Defaults — for the built-in software adapter — to the live SoftwareMixer recorded at build time, so a plain software deployment can toggle PDC without extra wiring. Tests inject a fake. Absent (and no software mixer), the row registers no instance.

Engine-seam performance telemetry (task #72): count + latency histograms for every REST resource GET/PATCH/watch (also the meter/telemetry/rta SSE fan-out) and the /patchbay/* routes, exposed at GET /telemetry. Recording is a single performance.now() pair plus an allocation-free PerfHistogram.record per seam call. MEASURED (not guessed) with packages/server/bench/perf-telemetry-overhead.mjs: the raw record() call costs ~25 ns, and enabling it end-to-end (REST dispatch + SSE fan-out, headless mock rig) moved the p50 of a 2000-request burst by less than 1% — within run-to-run noise, well under the task's ">1% → OFF by default" gating rule. Default disabled anyway: this is a deliberate opt-in (new + unproven in a live show), not a response to a measured cost — a disabled registry's record() is one boolean check regardless.

Quantum control for /console/quantum (the latency lever). Defaults — for the built-in software adapter — to the live SoftwareMixer recorded at build time, so a plain software deployment can drive live/floor quantum without extra wiring. Tests inject a fake. Absent (and no software mixer), the row registers no instance.

Remote head-amp scene-watch poll period (ms). Every this-often the server refreshes the adapter's remote head-amp fingerprint (MixerAdapter.refreshSourceCapsSignature); on a change — a reac-pw restart, a stagebox swap, a box width/capability change — it re-advertises capabilities to every open surface AND re-applies the recorded head-amp scene (phantom / pad / SENS) so the device always matches what the UI shows (the scene restore: "if we have phantom on, send phantom"). Default DEFAULT_FABRIC_POLL_MS; 0 disables (tests without a background timer); inert on an adapter without the refresh seam (no REAC fabric).

Follow-up scene re-apply delays (ms after a fabric change). Defaults to DEFAULT_SETTLE_REPLAY_MS — the settle window a power-cycled box needs before it accepts head-amp records (rig 2026-08-19). [] disables the follow-ups; tests inject short delays to observe the retry without waiting out the real window.

EXPLICIT opt-in, THE ONE SWITCH: whether the device-global controls this server always carries — clock and rmeTotalMix — default to their REAL, hardware-touching ACTUATORS (PwMetadataClock: pw-metadata/pw-dump reads and a live re-clock; AmixerRmeTotalmix: amixer cset against ALSA card 0) when the caller injects neither. Default false/absent: an unconfigured boot gets NULL_CLOCK (fully inert — the clock control has no separable actuator) for clock, and a REAL RmeTotalMixController over the inert NULL_RME_TOTAL_MIX_ACTUATOR for rmeTotalMix — its in-memory intent tracking (owned/trims/cells) still moves on a PATCH, so a desk that injects nothing still answers a broadcast battery honestly; only the amixer exec is gated.

Audit item 8 (2026-09-14/15): wireClock() used to construct a real PwMetadataClock() UNCONDITIONALLY whenever options.clock was absent, and start()'s seedClockState() runs on every boot with no test action required — its drift-recovery legs (reassertPersistedRate/reassertPersistedQuantum) call the real setRate/requestQuantum the instant a stale managed drop-in disagreed with the live driver, i.e. a PLAIN SERVER TEST RE-CLOCKED THE OPERATOR'S DESK with no clock.* verb ever invoked. Only console-rig.ts's real startConsole sets this true; every conformance desk and unit test leaves it off, so the class of incident that also wrote the operator's real WirePlumber drop-ins (below) cannot recur from an ordinary test boot — see test-harness-fake-by-default-conformance.test.ts.

MULTITRACK RECORD (2026-07-16-recording-vsc.md §2): the native node a take is captured from. Supplied exactly as rtLoad's source is — the console owns what to record and where it lands, the node owns the capture. Absent means no transport: /record has no instance, which is the honest way to say a console with no engine cannot record.

The console's resource layer (epic #436): the ONE ResourceRegistry its entities were registered into, served over HTTP by a RestRouter this server mounts.

The registry arrives already populated because the composition root is the only place that can build the entities — the native mixer stages a projection writes to live there, not here. Mounting is this server's job for the mirror-image reason: it owns Fastify and the client fan-out, so it is the only place a REST write can reach every open surface.

Absent leaves no /api surface at all rather than an empty one, which is the honest answer for an embedding that declared no entities.

RME Babyface Pro TotalMix ownership control for the rme.* verbs (the config-zone RME routing menu). Explicit injection always wins (tests inject a fake so the suite never shells out to amixer). Left unset, this resolves to a REAL RmeTotalMixController — full in-memory intent tracking, persisting to <stateDir>/rme-totalmix.json when persistence names a dir — wrapping a real AmixerRmeTotalmix actuator (amixer cset against ALSA card 0) only when realHardwareDefaults is true; otherwise the controller wraps the inert NullRmeTotalMixActuator, so the SAME state-tracking behaviour (a PATCH still moves an observable fact) runs with zero real hardware I/O. Always present (the lever is device-global — it drives the RME card directly, not the adapter).

Real-time analyzer (RTA / spectrum). When supplied, the server polls the engine's RtaSource while clients are subscribed and broadcasts a spectrum frame (raw FFT bins, for the standalone panel) + an rta frame (compact 0..1 log-bins, for the EQ-curve overlay) per channel each poll — the channels the operator ARMED (/channel/{kind}/{index}/rta's armed) plus whatever any surface is DISPLAYING, MAIN among them like any other lane. Handles rta.subscribe/unsubscribe.

The engine's RT load meter (task #121): the native mixer's own measured busy-per-quantum reading. When supplied, GET /telemetry carries an rt section, GET /telemetry/rt answers the same one-shot reading (rt-load-resource.ts), and GET /telemetry/rt?watch=1 rides it live. Each surfaced reading also carries the core headroom verdict (level + the honest 'engine at N% of its real-time budget' message) assessed with headroom (defaults: warn > 60%, refuse non-essential DSP adds > 80% — see core RT_HEADROOM_*).

The structural-DSP surface — the live software mixer's buses / sends / DCA / matrix / output layer. When supplied, the server serves the send (send-row.ts), DCA-membership (dca-members-row.ts) and matrix-point (matrix-point-row.ts) REST entities off it (driving it + re-projecting on every change), and the session capture/restore round-trips that state; otherwise those entities are unavailable and the session keeps them empty. The software adapter exposes it; hardware-console adapters do not.

Talkback / test-signal generators. When a structural surface is present the server runs a TalkbackGeneratorManager (the built-in oscillator + white/pink noise, published as patchable NATIVE PipeWire source nodes — never subprocesses) and serves the /talkback/* REST entities (talkback-rows.ts) off it. The backend is injected at the server boundary (NativeGeneratorHost from @freemixer/pipewire-native in production, a fake in tests); omitted — the addon absent / non-native host — the generators degrade to not-running without ever crashing.

Latency telemetry. When supplied, /telemetry/latency exists and the telemetry tick polls the engine's LatencyReportSource on each tick (telemetry-rows.ts). The tick itself runs on every console, for as long as a stream declares any of its rows (/telemetry/latency, /telemetry/rt, /telemetry/process); this option only adds the latency row to it.

The ephemeral fader-touch ledger — shared with the resource layer's /surface/touch/{kind}/ {index} row (surface-touch-row.ts), which is composed BEFORE this server (same reason every other row's engine door is a call-time accessor). Absent = this server owns its own (the pre-resource-layer default, and every bare test server).

VIRTUAL SOUNDCHECK (2026-07-16-recording-vsc.md §3): the native node a take is REPLAYED through. The recorder's block read backwards, and deliberately the same shape — the console decides which take and which channels, the node owns the playback. Absent means no soundcheck: /vsc has no instance, which is the honest way to say a console with no engine cannot replay one.

laneOf is the SAME resolver record is given, and it has to be: a take is played back into the lanes it was captured from, and a soundcheck feeding channel 4's recording into channel 5's strip would be somebody else's audio with nothing about it looking wrong.

EXPLICIT opt-in: write the generated WirePlumber drop-ins (driver ring depth + device exclusivity, driver-ring-policy.ts) into the REAL ~/.config/wireplumber/ wireplumber.conf.d/ whenever the graded clock candidates move. Default false/absent — every conformance desk and unit test boots with this OFF, mirroring realHardwareDefaults (a separate switch: a desk could in principle want a real, moving clock reading without also writing config — the incident that forced this flag needed both off). Only console-rig.ts's real startConsole sets this true — see an internal spec §"the fix" and the 2026-09-14 23:25 device-exclusivity ruling.

Xrun-health poll period (ms) — how often xrunProbe is sampled into the delta /clock/warnings judges (issue #657). Default XRUN_POLL_INTERVAL_MS; 0 disables the poll (tests that don't want a background timer).

The xrun-health probe (issue #657): pw-top's ERR column, the effective quantum/rate, and who is asking for the largest buffer on the graph. Defaults to probeXrunHealth (shells out through the hardened exec runner). Tests inject a fake so the suite never touches the real system graph.