Files
JustOneCacophony/docs/binaural.md
T
TheM14 07a26b41fe Keep only the Rosella and .jochrtf binaural paths
The runtime renders two inputs now: the Rosella .personalized_headphone model and
an already compiled .jochrtf field. SOFA import, the full-HRIR direct renderer
and the SOFA -> .jochrtf fitting compiler leave this checkout; they continue as
an offline tool that only produces caches this repository loads.

The .jochrtf renderer goes back to the implementation that predates the direct
SOFA work: 64-QMF analysis, 77 hybrid bands, per-object hybrid path delays and
the project room (six first-order images plus the shared FDN tail) computed in
code. It is restored verbatim under the .jochrtf vocabulary
(SofaBinauralBackend -> JochrtfBackend) and gains one switch:
--jochrtf-room on|off, off by default. With the room off the renderer outputs
only the field's direct binaural sound, and in either mode it reads no audio
assets.

Because the room is computed in code again, the generated sofa-room*.npz assets
and the modules only the SOFA path used are removed (sofa_canonical, sofa_hrir,
sofa_direct_backend, sofa_room, hybrid_paths, partitioned_convolution,
point_source, compile_hrtf, generate_sofa_room). data/ keeps the decode tables
and the Rosella filterbanks.

The CLI drops --sofa-hrtf, --hrtf-radius-m, --sofa-interpolation,
--hrtf-cache-policy, --hrtf-cache-dir, --sofa-room, --sofa-room-preset and
--source-reference-distance-m. A .jochrtf is still explicit through
--compiled-hrtf-cache, and the default binaural input is the personalized model.

Rosella parsing, filterbank, room and timing are untouched and its output stays
bit-identical. The .jochrtf path reproduces the pre-SOFA renderer sample for
sample, with the room on and with it off.
2026-11-01 19:00:40 +08:00

74 lines
3.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 双耳渲染
[English](binaural.en.md) · [返回 README](../README.md)
JOC 的双耳输出有两条输入路线:
| 输入 | 渲染 | 距离与环境 |
|---|---|---|
| `.personalized_headphone`(默认) | Rosella DSP、滤波器组与模型参数 | 模型自身的 Near/Mid/Far 与房间处理,行为不变 |
| `.jochrtf`(保留项) | 77 带方向场、64-QMF/hybrid 分析与合成 | 默认只输出直达声;`--jochrtf-room on` 开启项目房间 |
`.jochrtf` 由独立的离线编译器从 SOFA 测量数据拟合得到;本仓库负责加载和渲染
编译结果,编译器产出的缓存用 `--compiled-hrtf-cache` 加载。
```powershell
python main.py input.m4a --binaural
python main.py input.m4a --binaural --personalized-headphone --binaural-mode far --rosella-filterbank 2
python main.py input.m4a --binaural --compiled-hrtf-cache C:\HRTF\subject.jochrtf
python main.py input.m4a --binaural --compiled-hrtf-cache C:\HRTF\subject.jochrtf --jochrtf-room on
python main.py input.m4a --binaural --compiled-hrtf-cache C:\HRTF\subject.jochrtf --jochrtf-room on
```
不指定输入时使用项目目录下的 `HRTF/binaural.personalized_headphone`;`.jochrtf` 只能
显式选择,不自动生成,也不回退。双耳 DSP 全程 float64/complex128,参数每 128 样本更新。
## 点声源参考尺度
`.jochrtf` 路线沿用 Near 约 1 m、Mid 约 2.193 m、Far 约 6.402 m 的点声源参考尺度,默认
Mid。对于 ADM 右/前/上坐标 `p=(x,y,z)`:
```text
q_SOFA = (y, -x, z) / ||p||
d_nominal = reference_distance_m * ||p||
```
参考距离只给对象坐标规定标称米制尺度,不改变方向场的响应,也不额外增加 1/r 衰减或
传播延迟。声源与听者重合时沿用该对象最后一个有效方向,没有历史时取正前方。
## `.jochrtf` 房间
默认关闭。`--jochrtf-room on` 启用项目自有房间,算法与 Rosella 之前的公开路线一致,
直接在代码里计算,不读取任何资产:
- 六个一阶镜像反射(`public_room.first_order_image_sources`,18×18×14 m 原房间几何);
- 四路正交 Hadamard 反馈、两级全通扩散、低通阻尼的共享 FDN 晚期(RT60 0.85 s);
- 早反射按测量半径/路径距离给增益,晚期发送按档位与归一化半径给增益。
它不是测量 BRIR,也不是外部标准房间。关闭时跳过房间处理,只输出方向场的双耳直达声;
房间参数在构造时确定,没有预设、没有外部文件。
## 对象接入
输入为每帧 `[1536,16]` PCM:0 是 LFE,1–15 是已经重建的对象/bed 槽。直接使用 ID11
时间线,不重新解码,也不先渲染到扬声器布局。保留 1473 样本对象时间补偿和 32 样本元数据
对齐,参数每 128 样本更新。
LFE 继续使用独立低通处理,不发送至房间。多位置块、ISF、显式无穷远以及需要屏幕校准的
锚定明确报错。`finish()` 仅排空一次,`--binaural-tail-seconds` 规定滤波器组与房间尾声的
排空预算。
## 轻量格式
`.jochrtf` v1 是无 pickle 的 NumPy ZIP,保存 JSON 元数据、77 个频带中心、
`complex128[36,2,77]` 方向系数、`float64[36,2]` 延迟系数及 `float64[2,2]` 边界。加载时
校验格式版本、形状、标量范围,按成员重算载荷哈希,并重新计算 cache key 以确认系数与
配置一致;不匹配的文件直接拒绝。
格式、cache key 与哈希校验由本仓库维护;拟合编译器在独立目录里,两者共用同一个格式
模块,不复制定义。压缩表示保留自身的角向与频带近似误差,不等同于逐点测量的精度。
滤波器组来源见[data说明](../data/README.md)。方向插值与 MCA 的参考文献见
[研究实现依据](https://doi.org/10.1109/TASLP.2023.3313908);算法独立实现,外部测量数据
仍适用其自身许可。