Add the captured Rosella filterbank and select it per bank

The Rosella path now chooses its filterbank. Bank 1 is the public bank
the reference implementation has always used (13 taps / 6 slots,
961 samples); bank 2 is the captured bank the reference headphone
renderer actually runs (11 taps / 3 slots, 448 samples).

- src/rosella_captured_filterbank.py implements the four half-steps in
  float64/complex128; the captured prototype, rotation and hybrid
  coefficients live in data/rosella_captured_kernels.npz
- src/rosella_bank.py owns the choice: both banks expose the same four
  stages, each with its own coefficients, history and latency
- RosellaBinauralRenderer takes filterbank= and derives the startup
  skip, the flush capacity and the report fields from it
- --rosella-filterbank 1|2 selects the bank, default 1; it is rejected
  for the SOFA and .jochrtf inputs instead of being ignored
- document both banks in docs/rosella_filterbank.{md,en.md}, and point
  the binaural docs, the data README and the options tables at it

Checked: the captured stages reproduce the reference vectors the C++
core checks (within 1e-10), an impulse returns at 961 and 448 samples,
and chunking, reset and bank independence hold for both.
This commit is contained in:
TheM14 committed 2026-10-31 02:26:55 +08:00
1 parent 247e2a90b6
commit 0e98e91762
13 files changed
+606 -24

No files matched your search

+7
View File
@@ -153,6 +153,13 @@ The runtime is fixed at:
- fifth order, 36 terms, ACN/N3D real spherical harmonics;
- float64 PCM, delay, SH, and room state; complex128 band transfers and spectra.
Those are the SOFA / `.jochrtf` path and the public filterbank. The Rosella
`.personalized_headphone` path selects its bank: the public bank above is the
default (961 samples), and `--rosella-filterbank 2` switches to the bank captured
from the reference renderer (11 taps / 3 slots, 448 samples). Parameters,
buffers, latency and validation of both are in
[Rosella filterbank](rosella_filterbank.en.md).
Real and imaginary unit gains for every hybrid band pass through the same
analysis/synthesis chain to form a 154-real-parameter impulse dictionary. The
compiler does not sample 77 FFT bins. Defaults are `1e-3` projection ridge and
+6
View File
@@ -139,6 +139,12 @@ convention adapter,不能只通过 reshape 进入核心 importer。
- 五阶、36 项、ACN/N3D real spherical harmonics;
- PCM、delay、SH、room state 为 float64;频带传递和频域状态为 complex128。
上面是 SOFA / `.jochrtf` 路径与公开滤波器组的固定参数。Rosella
`.personalized_headphone` 路径的滤波器组可选:默认仍是这一套公开滤波器组(961
samples),`--rosella-filterbank 2` 换成从参考渲染器捕获的版本(11 taps / 3 slots、
448 samples)。两套实现的参数、缓冲、延迟与验证见
[Rosella 滤波器组](rosella_filterbank.md)。
每个 hybrid band 的 real/imaginary 单位增益都通过同一套 analysis/synthesis 链生成
脉冲字典,共 154 个实参数;编译不是直接读取 77 个 FFT bin。默认 projection
ridge 为 `1e-3`,SH ridge 为 `1e-5`。同方向 measurement 先合并,再用球面 Voronoi
+89
View File
@@ -0,0 +1,89 @@
# Rosella filterbank
[中文](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
the public bank and never consult the selector.
## Which bank runs
`--rosella-filterbank 1|2` selects the bank of the Rosella path; the library
form is `RosellaBinauralRenderer(..., filterbank=...)`, where omitting the
argument means `1`.
| Value | Implementation | Low-band hybrid | High-band delay | Latency |
| --- | --- | --- | --- | ---: |
| `1` (default) | `rosella_filterbank.py` | 13 taps | 6 slots | 961 samples |
| `2` | `rosella_captured_filterbank.py` | 11 taps | 3 slots | 448 samples |
Both banks expose the same four stateful half-steps (QMF analysis, hybrid
analysis, hybrid synthesis, QMF synthesis), so the choice switches the
coefficients, the high-band delay, the history layout, the startup skip and the
flush capacity together. The analysis and synthesis stages keep their own state
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
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 |
| --- | --- | --- |
| 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`.
## Implementation
`rosella_captured_filterbank.py` reproduces the four half-steps of the captured
bank in float64/complex128:
- QMF analysis keeps a 9-slot ring history, reads `(position + tap + 1) mod 10`,
and writes `spectrum[2b] = F[b]/64`, `spectrum[2b+1] = conj(F[63-b])/64`;
- hybrid analysis keeps a 10-slot history, transforms the three low bands with
8/4/4-point transforms, reorders them with a fixed map, conjugates bands 1 and
3, and passes the high bands through delayed by 3 slots;
- 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
(`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.
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
path.
+71
View File
@@ -0,0 +1,71 @@
# Rosella 滤波器组
[English](rosella_filterbank.en.md) · [返回 README](../README.md)
Rosella `.personalized_headphone` 路径可以在两套 64-QMF / 77-hybrid 滤波器组之间选择:
公开滤波器组(默认)与从参考渲染器捕获的 Rosella 滤波器组。SOFA 与 `.jochrtf` 路径
始终使用公开滤波器组,不经过该选择。
## 选择哪一套
`--rosella-filterbank 1|2` 选择 Rosella 路径的滤波器组;库接口是
`RosellaBinauralRenderer(..., filterbank=...)`,省略参数等于 `1`。
| 取值 | 实现 | 低频 hybrid | 高频 slot delay | 延迟 |
| --- | --- | --- | --- | ---: |
| `1`(默认) | `rosella_filterbank.py` | 13 taps | 6 slots | 961 samples |
| `2` | `rosella_captured_filterbank.py` | 11 taps | 3 slots | 448 samples |
两套实现暴露同一组四个有状态的 half-step(QMF 分析、hybrid 分析、hybrid 合成、
QMF 合成),因此切换会同时改变系数、高频延迟、历史缓冲布局、起始延迟跳过量和
flush 容量;分析与合成两级各自持有状态,互不共享。其它取值直接报错;非 Rosella
输入(SOFA、`.jochrtf`)给出该选项也报错,不会静默忽略。
## 为什么两套不同
参考头戴渲染器在初始化之后的准备阶段才选定 analysis/synthesis 回调,只捕获初始化
时的回调会拿到错误的滤波器组变体。运行时缓冲捕获得到的参数是:
| 参数 | Rosella 捕获版 | 公开版 |
| --- | --- | --- |
| QMF prototype | 640 个非对称系数 | 公开 640-tap prototype 的多相重排 |
| 低频 hybrid 滤波 | 11 taps | 13 taps |
| 高频 hybrid delay | 3 slots | 6 slots |
| analysis/synthesis 延迟 | 448 samples | 961 samples |
用错变体会在 room 尾音上引入随频率变化的误差;把捕获到的 room send 作为输入时,
现有 room 递推已经能对上参考,因此修复只更换滤波器组,不改 room 系数、direct HRTF、
相位映射或输出 EQ。公开版是 `1`,捕获版是 `2`;默认保留公开版,便于与历史输出对齐。
## 实现
`rosella_captured_filterbank.py` 用 float64/complex128 复现捕获版的四个 half-step:
- QMF 分析保留 9 slot 环形历史,按 `(position + tap + 1) mod 10` 读取,输出
`spectrum[2b] = F[b]/64`、`spectrum[2b+1] = conj(F[63-b])/64`;
- hybrid 分析保留 10 slot 历史,低频三个 band 分别做 8/4/4 点变换后按固定顺序重排,
band 1 与 band 3 取共轭;高频带原样延迟 3 slot;
- QMF 合成保留 9 slot 历史,用 10 个 lag 的 prototype 匹配累加,奇数 lag 取虚部。
`data/rosella_captured_kernels.npz` 保存捕获版的 prototype(`float32[64,10]`)、
rotation(`complex64[64]`)与 hybrid 系数(`complex64[22]`);载入后提升为
float64/complex128。这些数值与 C++ 内核编译进去的
`src/hrtf/rosella_filterbank_tables.h` 相同,不包含个性化 HRTF 或 room 调参。
运行时的起始延迟跳过与 flush 容量都取自所选滤波器组:`961` 或 `448` samples,
`.report.json` 的 `binaural_renderer_backend` 用 `filterbank`、`filterbank_name` 与
`latency_compensated_samples` 记录实际选择。
## 验证
本地回归脚本放在 `tests/`(该目录不随仓库跟踪,与其余本地验证脚本一致),覆盖:
- 捕获版四个 half-step 的参考向量(与 C++ 内核 `tests/rosella_filterbank_vectors.h`
同一组、由独立 NumPy 实现生成),逐样本误差小于 `1e-10`;
- 两套滤波器组的脉冲往返延迟分别落在 `961` 与 `448` samples;
- 分块处理(含 0 长度与不等长切分)与 `reset()` 不变性;
- 两套滤波器组互不干扰:交叉处理一个 bank 不改变另一个 bank 的状态;
- 越界取值被拒绝。
`docs/binaural.md` 描述的公开滤波器组公式与 `.jochrtf` 方向和公开版一致;捕获版只
作用于 Rosella 路径。