Firmament — User Manual

Open the heavens — a stereo widener and imager for lush orchestral layers.

What Firmament is

Firmament is a Mid/Side stereo widener and imager. It is one of the twelve plugins in the Basilica Audio heavy-music suite, and its job in that suite (and in any mix) is to take content that already has stereo information - strings, choirs, synth pads, doubled/layered guitars, ambience returns - and control how wide it feels, without ever compromising how the mix folds down to mono (club PA, phone speaker, a broadcast mono-check, a bass player checking their part in mono).

Firmament does not create stereo width out of a genuinely mono signal by itself (Width and Low Width can only scale what stereo difference is already present in the input) - the exceptions are Haas Mode and Decorrelate, which can create a sense of width from mono-compatible material. Haas Mode and Classic Decorrelate do so at the cost of some of the exact mono-sum guarantee the rest of the plugin provides (Haas costs the most, Classic Decorrelate much less - see below). The v0.3.0 Velvet Dense/Sparse Decorrelate modes close that gap entirely: they synthesize width from published velvet-noise decorrelator designs while leaving the mono fold-down bit-for-bit identical to the input's own - widening from mono with zero mono-compatibility cost.

v0.2.0 also revised how Auto Mono Safety reacts (calmer ballistics, a dead-zone around zero correlation, a user-adjustable floor, and an optional per-band mode) and widened Bass Mono Freq's range - see the parameter reference and docs/design-brief.md/docs/research-notes.md for the full research behind these changes. Every new parameter defaults to a value that reproduces v0.1.1's behaviour exactly, so nothing changes unless you explicitly opt in.

v0.3.0 upgrades Decorrelate with two velvet-noise modes (published DAFx-conference decorrelator designs) that - unlike Classic Decorrelate and unlike any Haas trick - are fully mono-sum-safe by construction: fold the output down to mono and you get bit-for-bit the input's own mono sum, at any Velvet amount. It also adds a Bass Mono Mode selector (Phase Matched for a seam-free crossover; Linear Phase for mastering-grade zero phase rotation, at the cost of latency), a third width band (High Split / High Width), a faster Dynamic safety response with compressor-style ballistics, opt-in Width Compensation (equal-power loudness across the Width range), and a Mono Audition monitor switch. As always, every new parameter defaults to exact v0.2.0 behaviour.

Where it sits in a heavy production chain

Firmament is a width/imaging tool, which places it toward the back end of a channel or bus chain, after tone-shaping and dynamics have already been decided:

1. Corrective/tonal EQ, compression, saturation (e.g. overture, tenebrae, other suite members) - shape the sound first.
2. Firmament - decide how wide it should feel, once the tone is set.
3. Reverb/delay sends, final bus processing - width decisions made before verb affect how the reverb tail itself is perceived; some engineers prefer to widen after the reverb return instead, which is a valid alternative depending on the source.

Typical placements in a heavy-music production:

• String/choir/pad busses - the primary use case. Push Width up to open the orchestral/choral layers without smearing the guitars/bass/kick that share the mix.
• Doubled rhythm guitar bus - a gentler touch (Width 110-140%) can glue two already-panned doubles into a single, wider-feeling wall without the extreme "hyped" artifacts of some stereo wideners, because Firmament never adds anything that wasn't already in the stereo image (again, aside from Haas Mode).
• Master bus (used sparingly) - Bass Mono is particularly valuable here: keep the kick/bass/low guitar energy centered (mono-compatible, and physically tighter on a PA) while the cymbals/strings/reverb tails above the crossover stay as wide as the mix already has them.
• Mono-source instruments routed through a stereo bus - Firmament accepts a mono input bus gracefully (see "Mono input" below); in that case Width has no effect at all unless Haas Mode/Decorrelate is engaged, since there is no inter-channel difference to scale.

Signal flow (plain-language version)

See docs/architecture.md for the full technical breakdown (Mermaid diagram, exact math, the Linkwitz-Riley crossover's real magnitude/phase behaviour, real-time-safety details). In short:

1. The input is split into Mid (mono content, (L+R)/2) and Side (stereo difference content, (L-R)/2).
2. If Bass Mono is off, Width scales the whole Side signal by a single amount.
3. If Bass Mono is engaged, Side is split into a low band (below the Bass Mono frequency) and the rest; Low Width scales the low band. If High Split (v0.3.0) is also engaged, the rest is split again into a mid band (Width) and a high band (High Width) - a 3-band imager. Bass Mono Mode (v0.3.0) decides how the Mid path relates to the split: untouched (Classic), phase-matched through a companion allpass (Phase Matched), or time-aligned with a linear-phase FIR split (Linear Phase, with reported latency).
4. If Auto Mono Safety is on, Side is further attenuated automatically whenever the input is heavily out-of-phase enough to leave a small dead-zone around zero correlation (a safety net against mono cancellation), on top of whatever the width controls already did - either as one global reading, or (if Auto Mono Safety Multiband is also on and Bass Mono is engaged) independently per band, and either with calm meter ballistics (Smooth) or fast compressor-style ballistics (Dynamic, v0.3.0).
5. Mid and the processed Side are recombined back into Left/Right. In Classic bass-mono mode, Mid is never touched by any of the above - and the Phase Matched/Linear Phase modes only ever change Mid's phase/timing, never its content - this is what guarantees the mono-fold-down safety described below.
6. If Width Comp (v0.3.0) is on, an equal-power makeup gain compensates the level change Width introduces.
7. If Decorrelate is on: in Classic mode the Right channel is processed through an allpass network and blended in by Decorrelate Amount; in the Velvet modes (v0.3.0) both channels receive velvet-noise-diffused stereo-difference content instead - fully mono-sum-safe. Otherwise, if Haas Mode is on, the Right channel is delayed slightly relative to Left (Decorrelate and Haas are mutually exclusive) - applied last, before the final trim.
8. Output trims the overall level; Mono Audition (v0.3.0), when engaged, replaces both channels with the exact mono fold-down for checking.

Reported latency

Firmament is latency-asymmetric by mode, and only by one mode. getLatencySamples() reports exactly this:

Everywhere else in the chain the story is the same zero: the crossovers are Linkwitz-Riley IIR structures, the Classic Decorrelate allpass cascade is a direct-form biquad chain, the Velvet Dense/Sparse decorrelators are zero-latency sparse FIRs, and Haas Mode's delay is a deliberate relative channel offset rather than a processing artifact a host needs to compensate for - none of these add reported latency, at any setting, at any sample rate. Only Linear Phase Bass Mono differs: its FIR complementary crossover reports N/2 samples, where N = 4096 * fs / 48000 rounded to even, so the figure scales with sample rate (2048 at 48 kHz; correspondingly more or less at other rates), and it is reported dynamically, off the audio thread, via a 50 ms message-thread servicing timer rather than the audio callback. Switching to or from Linear Phase mid-playback applies a brief (~5 ms) mute and may cause your host to renegotiate plugin delay compensation - some hosts click while doing so, which is why the Tips below recommend picking the mode before a render pass rather than automating it. A click-free transition across a latency change is not achievable in principle.

Parameter reference

Tips

• Start with Width, not Bass Mono. Most material only needs the single global Width control; reach for Bass Mono Freq/Low Width specifically when you hear the low end losing focus or translating poorly in mono as you push Width up.
• A/B in mono, always. Solo the bus, flip your DAW's mono/downmix monitoring on, and confirm nothing phases out oddly - Firmament's own Width/Low Width/Auto Mono Safety path (broadband or multiband) is provably mono-safe by construction (see docs/architecture.md), but Haas Mode and Decorrelate deliberately are not, and even a mono-safe width setting can still expose problems that were already latent in the source material's own stereo image.
• 200% Width is a special-effect setting, not a default. On a whole mix or a loud bus it reads as artificial/phasey quickly; it's much more useful reached for briefly (automated for a chorus lift, a breakdown, a single pad layer) than left engaged throughout.
• Auto Mono Safety is a safety net, not a substitute for listening. It reacts to the correlation of the plugin's input, with meter-style (300 ms) ballistics and a small dead-zone around zero correlation - fast enough to catch a sustained phase problem, not fast enough (nor intended) to police fast transients sample-by-sample, and not so hair-triggered that an occasional small negative reading sets it off.
• Prefer Decorrelate over Haas Mode when mono translation matters at all - and prefer the Velvet modes over Classic when it matters absolutely. Classic Decorrelate's documented cost is mild spectral ripple on mono fold-down; the v0.3.0 Velvet Dense/Sparse modes have zero mono-fold-down cost by construction (the mono sum is bit-for-bit the input's own). Haas Mode's cost is deep, audible comb-filter notches. Reach for Haas Mode specifically when you want its stronger, more dramatic precedence-effect character and mono translation is a secondary concern (a transition effect, a layer that will never be folded to mono).
• Linear Phase Bass Mono is a mastering/render choice, not a live toggle. It reports real latency (2048 samples at 48 kHz) that your host compensates automatically, but switching the mode mid-playback mutes briefly and may click in some hosts while they renegotiate the delay. Pick it when phase purity through the crossover matters (mastering, bus processing feeding further M/S tools); stay on Classic or Phase Matched for tracking/live use, which are latency-free.
• Use Mono Audition instead of hunting for your DAW's downmix button. It is the exact fold-down the mono-compatibility guarantees are about, applied post-everything.
• Haas Mode/Decorrelate and Bass Mono/Low Width combine fine, but think about what each is doing: Bass Mono/Low Width/Auto Mono Safety shape width within the Mid/Side model (provably mono-safe), Haas Mode/Decorrelate are a separate, later, non-Mid/Side effect. If you need guaranteed mono compatibility (broadcast delivery, a club system with an unpredictable mono/summed sub), leave both off and rely on Width/Low Width/Auto Mono Safety alone.
• On a mono-input track/bus, Width/Low Width/Auto Mono Safety have nothing to act on (there is no Side signal) - the plugin passes the source through cleanly. Haas Mode/Decorrelate are the controls that still do something in that situation, since they operate after the (now-identical) L/R pair has been decoded - this is exactly the "widen near-mono material" use case they're built for.

Presets

Firmament ships with thirteen factory presets covering common use cases (orchestral/choir width, doubled rhythm glue, master-bus bass-mono, automated-width safety nets, one showcase preset each for Decorrelate and Haas Mode, and - new in v0.3.0 - Velvet Width, Mastering: Linear Phase Bass Mono, and Three-Band Imager) - see docs/presets.md for the full list and the intent behind each. The preset bar docked at the top of the plugin window lets you browse factory/user presets, save your own, rename/delete user presets, import/export single presets or a whole bank (a zip of your user presets), and set a preset as the default that loads on a fresh instance. Presets are a layer on top of your host's own plugin-state save mechanism, not a replacement for it - your DAW session still saves whatever state is currently loaded either way.

Under the hood

The reasoning and full technical detail live in docs/architecture.md; the numbers below are what the automated test suite actually enforces on every push.

Mono compatibility is structural, not tuned. Firmament encodes to Mid/Side (mid = (L+R)/2, side = (L-R)/2) and decodes as left = mid + side, right = mid - side. Every width control - Width, Low Width, High Width, Auto Mono Safety - only ever scales Side; in Classic bass-mono mode Mid is never touched by any of them. Because decode is always left + right == 2*mid regardless of what Side is, the mono downmix of the output equals the mono downmix of the input at any width setting, including 0% and 200%. This is checked at the codec level directly, at the engine across a spread of settings, and independently for every stage that could plausibly break it - multiband width, Auto Mono Safety, and the third width band.

Velvet-noise decorrelation had to resolve a real contradiction, not just implement a published design. The published optimized velvet-noise decorrelator pairs (coefficients transcribed as data from the open-access paper's own tables, no third-party code) decorrelate well individually, but their sum carries a real ~17 dB notch around 320 Hz at 48 kHz - because the optimization that produced them constrains each filter's own flatness and the pair's coherence, but never the pair's sum. Applied as a raw per-channel wet mix, that notch would show up directly in the mono fold-down. Firmament instead keeps the widening half of the topology intact but pins the mono content dry: S' = (1-d)S + d*(A(L) - B(R))/2, M' = M. The result is a decorrelator whose mono compatibility is structural rather than tuned - measured fold-down dip ~0.0000003 dB at Velvet Dense, Width 150%, Amount 100%, against 16.2 dB for a Haas-style control on the identical program - and both channels are genuinely processed rather than only one, unlike Classic mode.

Phase Matched proves its own claim with a negative control. Rather than hand-rolling a second-order allpass to track the crossover's phase, Phase Matched wraps the same Linkwitz-Riley filter class in its own documented allpass mode, so the companion Mid path shares the identical internal state equations and coefficients as the crossover itself - the phase-tracking guarantee holds by construction, not by careful duplication. The test that proves it re-runs the same phase-tracking assertion with the companion allpass replaced by unity and requires that run to fail - it measures 179.8 degrees of phase error there, against 5e-6 degrees when the real allpass is in place, which is a guard against the test silently no longer measuring anything.

Linear Phase is a genuine perfect-reconstruction FIR pair, not an approximation: a Kaiser-windowed sinc lowpass on the mono Side stream, with the high band and the Mid path both delayed to match. Measured residual against a pure N/2-sample delay: ~7e-9. Group delay deviates from flat by 0.0002 samples across 20 Hz - 20 kHz. The kernel is recomputed on the message thread and installed via a single Convolution::loadImpulseResponse call, which handles its own background loading and output crossfade, rather than a hand-rolled double buffer - deliberately, because JUCE's plain FIR filter class cannot have its coefficients reassigned from the message thread while the audio thread reads them without a data race.

Three-band width sums flat because the low band gets phase-corrected before the sum. Standard 3-way Linkwitz-Riley practice, and the detail naive 3-band splits usually get wrong: the low band passes an allpass matched to the high split before the band sum, so all three bands carry identical phase there. Measured band-sum deviation: within ±0.1 dB, in both the 3-band case and the high-split-alone 2-band case.

The correlation guard's energy gate exists because of a real trap. A leaky Pearson correlation ratio is invariant under silence - numerator and denominator decay at the same rate, so the ratio never moves. Every correlation estimator in the plugin - the display meters and the Dynamic safety detector alike - therefore decays its estimate toward zero below an energy gate; without it, meters would read ±1 on silence and the Dynamic guard could latch at maximum attenuation after an anti-phase burst and never release. Dynamic's own ballistics are specified and measured as times to 90% settling (5 ms attack, 250 ms release) rather than raw time constants, because a raw-time-constant reading of the original specification turned out to be unsatisfiable - a 250 ms time constant only reaches 90% recovery after roughly 575 ms, not 250.

Engineering hygiene: zero heap allocations on the audio thread, proven under a replaced allocator across every decorrelate/bass-mono/safety mode combination, including mode switches inside the guarded region and the Linear Phase path swap's reset(). Every conditional DSP stage runs on every sample regardless of whether it is currently engaged - only the output selection is gated - because gating the processing call itself once left filter state frozen rather than decaying, producing an audible transient the one time it shipped that way (fixed in v0.1.1). Every input sample is checked for NaN/Inf and zeroed before it reaches the M/S encode, because the crossover's IIR state and the correlation estimator's leaky integrators would otherwise carry a single poisoned sample forward indefinitely. Sessions from v0.1.x and v0.2.0 load with every stored value intact, verified both as a same-binary tolerance-0 null and against a frozen, checked-in v0.2.0 reference render.

Known limitations

• Haas Mode and Classic Decorrelate are deliberate, documented exceptions to the mono-sum guarantee - the Velvet Decorrelate modes are not. Haas Mode measurably costs 16.2 dB of third-octave mono fold-down dip on a representative program (deep comb-filter notches from summing two time-offset channels); Classic Decorrelate's cost is smaller and bounded (under 9 dB at 50% Amount - bounded spectral ripple rather than deep nulls) but is still real. Velvet Dense/Sparse cost ~0.0000003 dB on the same class of program - not merely low, but structurally incapable of costing more, because only the stereo-difference signal is ever synthesized.
• Width Compensation is computed from the broadband Width parameter only. With the multiband splits engaged, Low Width and High Width do not enter the makeup-gain formula. This is why the control defaults off.
• There is no limiter or ceiling anywhere in the signal path. Firmament is a purely linear processor - Width above 100% and Output above 0 dB both genuinely add gain, which is the control doing exactly what it is documented to do, not a safety mechanism failing.
• Width, Low Width and High Width cannot create stereo width from a genuinely mono signal by themselves - they can only scale stereo difference that is already present. On a mono input bus, Side is exactly 0 and the plugin passes the source through cleanly; Haas Mode and Decorrelate are the only controls that do anything in that situation.
• The voicing is research-derived, not measured against any commercial plugin's output - see Research-derived voicing below for the full sourcing and its own confidence caveats, including the specific note that Bass Mono Freq's 500-600 Hz range extension is the single lowest-confidence, most-reasoned value in the plugin.
• Deliberately out of scope for this release: Gerzon shuffler shelves on the Side signal, an ERB-warped allpass-cascade "Diffuse" decorrelator tier, ambience recovery / external sidechain / a dry-wet mixer for the whole plugin, a goniometer or vectorscope widget, width-guard lookahead, and rotation/asymmetry/pan of the stereo field.
• Pre-1.0. Release binaries for macOS are Developer-ID-signed, notarised and stapled; Windows binaries are not yet Authenticode-signed. Licensed AGPLv3. Breaking changes remain possible until v1.0.0.

Research-derived voicing (honesty note)

Firmament's default values and ranges (Bass Mono Freq's 80-200 Hz "typical" range, the Linkwitz-Riley crossover order, the Haas Time window, Auto Mono Safety's ballistics/dead-zone, Decorrelate's approach) are research-derived from public manuals, developer/product documentation, mastering-forum and trade-press consensus, and acoustics/psychoacoustics literature (see docs/research-notes.md for the full sourcing) - not measured against any commercial stereo-widener plugin's actual audio output, and no proprietary DSP algorithm from any other vendor was inspected, decompiled, or approximated. docs/design-brief.md documents exactly which numbers are directly sourced, which are sourced-but-lower-confidence, and which are reasoned choices where a source establishes a principle but not an exact number.

The editor

Firmament ships the suite's M3 vector editor: a fully runtime-drawn black/gold surface (no bitmap assets) with pointer knobs on engraved scale rings, lamp toggles, and five section panels laid out in signal-flow order - Width (the core M/S scale and its equal-power compensation switch), Bands (the two Side-path crossovers and per-band widths), Mono Safety, Widen (Decorrelate and Haas), and Output. Choice parameters (Bass Mono Mode, Decorrelate Mode, Safety Response) are detented knobs that snap to and announce their mode names.

Two needle meters show the engine's correlation estimates live: IN (the broadband input correlation that also drives Auto Mono Safety) on the Width panel and OUT (post-processing) on the Output panel, both on a -1...+1 scale with gentle meter ballistics. +1 means fully mono-compatible; readings pinned toward -1 warn that the output would cancel on a mono fold-down.

Accessibility

The editor is built to WCAG 2.1 AA:

• Keyboard: every knob and toggle is Tab-reachable. Arrows step knobs by 1% of their range, Shift+Arrow steps fine (0.1%), PageUp/PageDown by 10%, Home/End jump to the extremes; choice knobs step exactly one mode per arrow press. Toggles flip with Space/Enter. Shift-drag is the mouse analog of Shift+Arrow (fine adjustment).
• Visible focus: a gold focus ring (with a dark halo) marks the focused control at all times.
• Screen readers: every control exposes its printed label as its accessible name, its value with unit ("120.0 %", "-9.1 dB"), and its proper role; the five panels are announced as named groups; the meters expose their smoothed reading as a read-only value on demand.
• Contrast: all rendered text/marking pairs hold at least 4.5:1 (WCAG AA), enforced by unit tests against the exact colours drawn.