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:
1 parent
247e2a90b6
commit
0e98e91762
13 files changed
+606
-24
No files matched your search
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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 路径。
|
||||
Reference in new issue
Block a user