The engine and its libraries: what stays inside an engine stage, and why
The native engine (the pipewire-native package) runs every lane of the console: each input channel,
each bus and MAIN. It does not own the arithmetic that shapes the audio. That lives in omx-dsp, and
the effects live in omx-plugins as CLAP plugins (see Libraries, tools and apps).
This page states the rule that splits the two, what the engine keeps and why, and which omx-dsp
functions each stage calls.
The rule
A formula lives in omx-dsp. Whatever depends on the graph, the clock or the console's state lives in the engine.
A formula is a function of its inputs and of a state struct passed to it: a filter, a dynamics detector, a pan law, a limiter, a loudness meter. It can be tested alone against a closed-form answer at every sample rate, so it belongs to the library that carries those tests. The engine holds what cannot be tested that way: PipeWire's buffers and clock, the order the session declares, which source feeds which bus, the lifetime of each lane's state, what the operator is watching, and what gets published to the server.
What the engine keeps
| The engine keeps | Why it is not a formula |
|---|---|
| The real-time loop over PipeWire's buffers | It owns PipeWire's clock, quantum and ports; the block size and the rate are the graph's, not the audio's. |
| The order of the stages in a lane | The session declares it; the engine walks it (mix_lane.h, mix_order.h). |
| The summing structure: which sources feed which bus | Routing is graph state (mix_sum.h builds the plan; the sends live in mix_bus.h). |
| Per-lane state: its allocation, lifetime and real-time safety | It follows the session. State is allocated on the control thread and handed to the audio thread; nothing on the audio thread allocates, locks or does I/O. |
| Insert slots and the detour's latency bookkeeping | Where a plugin sits in a lane and how many samples its round trip costs are graph facts (mix_insert.h, mix_clap.h). |
| Meter and limiter tap points, and publishing | Where a meter reads and how often it is sent to the server are console decisions (mix_tap.h, mixer_meter.c, mix_main_meter.h). |
| Latches cleared only by an explicit action | The clip latch is console state: it holds until the operator clears it. |
| Solo-in-place, cue and PFL mute logic | Console behaviour, not arithmetic. |
| Whether anyone is watching | Nothing computes unwatched: an analyser or tap with no reader is skipped before any library call. |
| The parameter handover into the audio thread | Threading: coefficients and targets are designed on the control thread and published to the audio thread with release stores. |
| The N-API and PipeWire shells over library kernels | Binding code: addon.c, dsp_addon.c, omx_node.c and the other *_addon.c files wrap omx-dsp entry points for the server. |
| The real-time load meter | It measures the engine itself, not audio. |
A lane, stage by stage
One walk serves a channel, a bus and MAIN. They differ only in what feeds them: an input channel is fed by its port, a bus or MAIN by the sum of the lanes routed to it.
| Stage | omx-dsp calls | State the engine keeps |
|---|---|---|
| Fill (trim gain) | omx_ramp_begin, omx_ramp_at, omx_ramp_end (the click-free ramp) |
the current gain per leg |
| Input alignment delay | omx_align_apply, omx_align_target, omx_align_arm, omx_idelay_* |
the alignment ring, armed off the audio thread |
| Head filters (high-pass, low-pass) | omx_biquad_cascade_stereo |
the section states per leg (pass_state_l, pass_state_r) |
| Gate | omx_dynamics_keyed |
the envelope (gate_env); the key source and its detector filters (omx_biquad) |
| EQ | omx_biquad_cascade_stereo |
the band states per leg (eq_state_l, eq_state_r); the pre- and post-EQ analyser rings (omx_ring_write) when armed |
| Compressor | omx_dynamics_keyed |
the envelope (comp_env) |
| Plugin step (CLAP, in process) | none: omx-clap-core's omx_clap_host_run runs the plugin |
the plugin bank of the lane |
| Insert detour (out-of-process plugin) | none | the insert bank and the latency it adds |
| Out stage (fader, mute, balance or pan) | omx_balance_law, omx_clamp_pan; a bus's out stage omx_bus_out_gains, omx_bus_out_apply, omx_bus_out_run |
the current fader per leg |
| Bus and MAIN limiter | omx_limiter_init, omx_limiter_process, omx_limiter_cap, omx_limiter_mem_floats |
the limiter's look-ahead memory, allocated per lane |
| Output guard | omx_limiter_instance_init, omx_limiter_instance_resolve, omx_limiter_instance_run |
the guard's instance and ceiling |
| Meters and the clip latch | omx_meter_block_peak, omx_meter_leg_peaks, omx_meter_clip_run, omx_lin_to_db, omx_db_to_lin |
the hold and decay state (omx_meter_hold), the latch, the published slots |
| MAIN loudness meter | omx_loudness_init, omx_loudness_process, omx_loudness_momentary, omx_loudness_short_term, omx_loudness_integrated, omx_loudness_range, omx_loudness_true_peak, omx_loudness_reset |
the meter's state, allocated off the audio thread, and its publishing cadence |
| RTA | omx_rta_spectrum, omx_rta_spectrum_complex, omx_decimate_halfband, omx_ring_read_from, omx_rta_fft_size_for |
the sample ring between the audio and control threads |
| Output delay | omx_idelay_pair_apply, omx_idelay_samples |
the delay line per output |
The walk's contract checks (OMX_PRE, OMX_POST) test each block with omx-dsp's
omx_block_finite or omx_lane_finite.
The effects that used to be stages of the engine (drive, delay, reverb, chorus, flanger, de-esser, phaser, pitch, rotary, tremolo, graphic EQ) are CLAP plugins from omx-plugins and run as plugin steps. Their stage ids are retired and never reused.
Where the tree still differs from the rule
No pan, coefficient, fold, accumulate, out-stage or meter-ballistics formula is written in
the native engine's sources: each is an omx-dsp call, and the repository's lean-engine check holds it so
(rule a, the library's own copy check; rule b, no libm formula in the shipped C). The engine keeps the
argument shapes that carry its own contract stages (omx_mix_strip, omx_bus_out_gain) and the out
stage the unit oracles measure (omx_bus_out_stage); each is one or two library calls and the publish
half. What its allowlist still holds, with the issue that ends each, is in
the native engine's lean-engine.allow.
On bus and MAIN lanes the limiter is still before the out stage; moving it after the fader and balance, so its ceiling holds whatever the fader does, is #1008.