Add --rosella-filterbank and restore the public bank as the default
ci / ubuntu-latest (push) Failing after 16s
ci / macos-latest (push) Canceled after 0s
ci / windows-latest (push) Canceled after 0s
ci / release (push) Canceled after 0s

The Rosella path picks its analysis and synthesis bank instead of
hard-coding one. Bank 1 is the shared public bank the renderer used
before the captured variant landed: 13-tap hybrid filters, the 6-slot
high-band delay and 961 samples of latency. Bank 2 is the captured
Rosella bank: 11-tap filters, the 3-slot delay and 448 samples. Both
keep their own coefficients, histories and flush behaviour.

- Drive either bank through one RosellaBank interface, and derive the
  startup skip and the flush capacity from the selected bank
- Add joc_rosella_filterbank to joc_task_config and joc_stream_config
  by replacing the reserved words (struct sizes unchanged, config
  version 3 -> 4)
- Reject an out-of-range value and bank 2 without a Rosella model
  instead of silently falling back
- Expose --rosella-filterbank 1|2 in the CLI with bank 1 as default,
  and reject it outside the personalized headphone path
- Cover bank identity, chunking, reset and per-bank latency in tests
- Document both banks, the selector and the CLI help

Renders of --rosella-filterbank 1 (and the default) match the pre-merge
reference byte for byte; --rosella-filterbank 2 matches the PR #3
reference byte for byte.
This commit is contained in:
TheM14 committed 2026-10-31 01:11:44 +08:00
1 parent 6674cb5386
commit 34a722f56a
19 files changed
+477 -34

No files matched your search

+7 -3
View File
@@ -121,9 +121,13 @@ The SOFA and `.jochrtf` 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.
The `.personalized_headphone` path uses a separate Rosella filterbank with
448 samples of latency. See [Rosella filterbank](rosella_filterbank.en.md) for
its parameters and validation results. The SOFA bank described here is unchanged.
The `.personalized_headphone` path selects its bank rather than fixing it. The
default is the shared public bank described here (961 samples of latency); bank
2 is the captured Rosella bank (448 samples). Both keep their own coefficients,
history and high-band delay, and the runtime skips the selected bank's latency
and sizes the flush with it. See [Rosella filterbank](rosella_filterbank.en.md)
for the parameters, the CLI switch and the validation results. The SOFA and
`.jochrtf` banks described here are unchanged and never use the selector.
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
+16
View File
@@ -177,6 +177,22 @@ key。writer 使用同目录临时文件、`fsync`、进程持有的 OS 文件
私有 cache,不随程序或构建产物发布。`source_sha256` 只用于内容一致性校验,不是许可
或来源证明。
## Rosella 个性化模型
`.personalized_headphone` 走独立的 Rosella 渲染器,滤波器组可以二选一,
由 `--rosella-filterbank 1|2`(库接口为 `joc_task_config::rosella_filterbank` /
`joc_stream_config::rosella_filterbank`,`0` 表示默认)选择:
| 取值 | 滤波器组 | 低频 hybrid | 高频 slot delay | 延迟 |
| --- | --- | --- | --- | ---: |
| `1`(默认) | `PublicFilterbank`(与 SOFA 路径共用) | 13 taps | 6 slots | 961 samples |
| `2` | `RosellaFilterbank`(从参考渲染器捕获) | 11 taps | 3 slots | 448 samples |
两套实现通过同一组四个有状态 half-step 调用,因此切换时系数、高频 delay、历史缓冲
布局、起始延迟跳过量和 flush 容量一起改变,分析与合成两级互不共享状态。其它取值直接
报错;非 Rosella 输入给出该选项也报错,不会静默忽略。详见
[Rosella filterbank](rosella_filterbank.en.md)。
## JOC 对象与房间
生产适配器继续使用现有 JOC 调度:
+31 -7
View File
@@ -1,7 +1,28 @@
# Rosella filterbank
The Rosella renderer uses a separate 64-band QMF and 77-band hybrid filterbank.
The SOFA compiler and renderer continue to use `PublicFilterbank`.
The Rosella renderer runs one of two 64-band QMF / 77-band hybrid filterbanks.
The shared public bank is the default; the captured Rosella bank reproduces the
reference headphone renderer. The SOFA compiler and renderer always use
`PublicFilterbank`.
## Which bank runs
`--rosella-filterbank 1|2` selects the bank for the `.personalized_headphone`
path; `joc_task_config::rosella_filterbank` and
`joc_stream_config::rosella_filterbank` carry the same value, with `0` meaning
the default.
| Value | Bank | Low-band hybrid | High-band delay | Latency |
| --- | --- | --- | --- | ---: |
| `1` (default) | `PublicFilterbank` | 13 taps | 6 slots | 961 samples |
| `2` | `RosellaFilterbank` | 11 taps | 3 slots | 448 samples |
Both banks are driven through the same four stateful half-steps, 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 banks never
share state. Any other value is rejected, and the option is an error when the
binaural input is not a Rosella model: the SOFA and `.jochrtf` paths do not use
it and must not silently ignore it.
## Why the banks differ
@@ -33,9 +54,9 @@ each channel. QMF data uses `[slot, channel, 64]` order. Hybrid data uses
and hybrid coefficients as hexadecimal literals. Processing uses double
precision. The tables do not contain the personalized HRTF or room tuning.
The runtime removes 448 startup samples and uses the same latency when it
calculates flush capacity. Its rendered buffer is resized to the current block
length, including a short final block.
The runtime removes the selected bank's startup samples and uses the same
latency when it calculates flush capacity. Its rendered buffer is resized to the
current block length, including a short final block.
## Validation
@@ -49,8 +70,11 @@ ctest --test-dir build --output-on-failure
`rosella_filterbank` checks deterministic analysis, hybrid, folding, and synthesis
vectors from an independent NumPy implementation. It also checks empty and
unequal chunks, reset, channel isolation, and impulse latency. The tests need no
reference binary, audio fixture, or personalized headphone file.
unequal chunks, reset, channel isolation, and impulse latency. A second group
checks the bank selector: each kind reproduces exactly what its own class
computes, the two produce different hybrid data, chunking and reset are
invariant for both, and each reports its own latency (961 or 448 samples). The
tests need no reference binary, audio fixture, or personalized headphone file.
Before integration with the upstream bed-layout changes, four captured-input
tests gave the following room PCM residuals. No gain fitting was used for this