Honor OAMD warp modes and position-dependent speaker trims

Read warp mode from OAMD instead of always scaling the floor Y coordinate.
For eligible layouts, mode 1 uses clamp(2Y, 0, 1), while mode 0 leaves Y
unchanged. Height coordinates are not scaled. Modes 2/3 remain explicitly
unsupported, and the CLI provides no warp override.

Keep separate coordinates for floor panning, height panning and trim
evaluation, with W denoting warp and B denoting front-back balance:

    floor Y  = B(W(Y))
    height Y = B(Y)
    trim Y   = B(Y)

Apply explicit trims as a position-dependent gain for each object before
accumulation, replacing fixed gains applied to output channels after mixing.
Automatic, disabled and explicit trim modes are mutually exclusive.
Per-object bypass disables balance and trim while retaining warp.

Update controls at OAMD metadata events and retain the previous controls
when a payload has no trim element. Keep source trajectories and binaural
rendering unchanged.

Write the OAMD warp code into dbmd segment 9 while preserving the other
packed fields. Update the bilingual mathematical notes, README files and
code comments to describe parameters and rendering behavior.

Checked: warp 0/1, Y clipping, height coordinates, balance/trim ordering,
per-object bypass, metadata updates, bed positions and LFE passthrough.
This commit is contained in:
TheM14 committed 2026-11-03 00:11:23 +08:00
1 parent 8424e6bdfb
commit 0e28cd085c
17 files changed
+335 -191

No files matched your search

+12 -35
View File
@@ -3,8 +3,8 @@
[中文](rosella_filterbank.md) · [Back to README](../README.en.md)
The Rosella `.personalized_headphone` path can run either of two 64-QMF /
77-hybrid filterbanks: the shared public bank (the default) or the Rosella bank
captured from the reference renderer. The SOFA and `.jochrtf` paths always use
77-hybrid filterbanks: the 13-tap public bank (the default) or the 11-tap Rosella
bank. The SOFA and `.jochrtf` paths always use
the public bank and never consult the selector.
## Which bank runs
@@ -26,30 +26,21 @@ and never share it. Any other value is rejected, and the option is an error when
the binaural input is not a Rosella model: a SOFA or `.jochrtf` render must not
silently ignore it.
## Why the banks differ
## Bank parameters
The reference headphone renderer selects its analysis and synthesis callbacks
during preparation, after initialization. Capturing only the initial callbacks
identified the wrong filterbank variant. Runtime buffer captures gave these
parameters:
| Parameter | Captured Rosella bank | Public bank |
| Parameter | 11-tap Rosella bank | 13-tap public bank |
| --- | --- | --- |
| QMF prototype | 640 asymmetric coefficients | polyphase reorder of the public 640-tap prototype |
| Low-band hybrid filter | 11 taps | 13 taps |
| High-band hybrid delay | 3 slots | 6 slots |
| Analysis/synthesis latency | 448 samples | 961 samples |
The wrong variant produced a frequency-dependent room-tail error. With the
captured room send as input, the existing room recursion already matched the
reference, so the fix changes only the filterbank: not the room coefficients,
the direct HRTF calculation, the phase mapping, or the output EQ. The public
bank stayed as bank `1` so historical renders remain reproducible; the captured
bank is bank `2`.
The selector does not change room coefficients, direct HRTF calculation, phase
mapping or output EQ. Bank `1` is the default.
## Implementation
`rosella_captured_filterbank.py` reproduces the four half-steps of the captured
`rosella_captured_filterbank.py` executes the four half-steps of the 11-tap
bank in float64/complex128:
- QMF analysis keeps a 9-slot ring history, reads `(position + tap + 1) mod 10`,
@@ -60,30 +51,16 @@ bank in float64/complex128:
- QMF synthesis keeps a 9-slot history and accumulates 10 prototype-matched
lags, taking the imaginary part on odd lags.
`data/rosella_captured_kernels.npz` stores the captured prototype
`data/rosella_captured_kernels.npz` stores the 11-tap bank's prototype
(`float32[64,10]`), rotation (`complex64[64]`) and hybrid coefficients
(`complex64[22]`); they are promoted to float64/complex128 on load. The values
are the ones the C++ core compiles in as `src/hrtf/rosella_filterbank_tables.h`
and contain no personalized HRTF or room tuning.
(`complex64[22]`); they are promoted to float64/complex128 on load and contain
no personalized HRTF or room tuning.
The startup skip and the flush capacity both come from the selected bank (961 or
448 samples). `.report.json` records the actual choice in
`binaural_renderer_backend`, as `filterbank`, `filterbank_name` and
`latency_compensated_samples`.
## Validation
The local regression script lives in `tests/`, which this repository does not
track (like the rest of its local checks). It covers:
- reference vectors for the four captured half-steps, the same samples the C++
core checks, generated by an independent NumPy implementation, to within
`1e-10` per sample;
- an impulse roundtrip peak at 961 and 448 samples for the two banks;
- chunk invariance (including zero-length and unequal chunks) and `reset()`;
- independence: processing one bank never changes the other bank's state;
- rejection of out-of-range values.
The public filterbank formulas and `.jochrtf` direction field described in
`docs/binaural.md` are unchanged; the captured bank only affects the Rosella
The public filterbank formulas and `.jochrtf` direction field are described in
`docs/binaural.md`; the 11-tap bank only affects the Rosella
path.