Files
JustOneCacophony/docs/binaural.md
T
TheM14 fd842db26f
ci / ubuntu-latest (push) Failing after 11s
ci / macos-latest (push) Canceled after 0s
ci / windows-latest (push) Canceled after 0s
ci / release (push) Canceled after 0s
Render SOFA HRIRs directly and place bed channels by their labels
Two changes that belong to the same reproduction model: a bed channel has
one position, defined by its label, and a SOFA set keeps the impulse
responses it was measured with.

CBA bed channels: the position comes from the channel's label in ETSI
TS 103 420 Table B.10, not from the layout the decoder is asked to render
to. The per-layout anchor table displaced bed channels onto the nearest
target speaker, which silently moved content whenever the target layout
changed.

- Drop the anchor table and the geometry lookup; bed_channel_q15 is the
  only source of bed positions, so stream and task no longer need a
  layout to ask for one
- Keep the 17-bit non-standard bed mask in channel order, as Table 13 /
  TS 103 190-2 Table 65 transmit it
- Exclude LFE channels from the object list while keeping them in the
  coverage mask
- Cover the Table B.10 coordinates, the q15 encoding, the 10-bit and
  17-bit masks and the LFE split in tests

SOFA rendering: compiling a SOFA set into a fifth-order directional field
threw away the measured impulse response - the SH projection, the
64-QMF/77-hybrid round trip and the synthetic room replaced it. The full
IRs are now kept and rendered as such, with the reproduction defined by a
configuration that names a personalized model rather than by the renderer
itself.

- Add SphericalMesh: incremental convex hull over the measurement
  directions, barycentric weights inside the containing triangle and
  spherical Voronoi areas for the centre spectrum
- Add FullHrirField: rfft of the selected shell, 200-1500 Hz phase fit for
  the delay, delay-aligned spectra, log-magnitude/phase or MCA
  interpolation, rigid-sphere radial ratio, recording origin and the
  common FFT/2 latency
- Add Uniform/MultiSourcePartitionedConvolver: block 128, numpy FFT
  conventions, zero-fade filter rebuild from the blocks in flight
- Move the Rosella reference arithmetic (profile geometry, direction
  basis, direct gains and room send, table-A room) out of the renderer
  into rosella_reference so both renderers share it
- Add ReferenceEnvironment and SofaReferenceRuntime: JSON configuration
  with model hash and distance-profile mapping, level calibration over
  equal-area directions, the reference room, 1536-sample batching and a
  single latency removal
- Keep .jochrtf an explicit input and the SOFA compile step behind
  --hrtf-cache-policy/--hrtf-cache-dir; add --reference-config and
  --sofa-interpolation, and make --hrtf-radius-m optional for a single
  shell
- Cover the mesh weights and Voronoi areas, the sphere series and the
  partitioned convolver with reference values in tests
- Document both rules in the READMEs and the binaural notes

Rosella renders stay byte-identical (d5877e89...) and so do renders of
the legacy compiled path (6f0a75d2...). Direct SOFA renders match the
Python reference to 1e-4 in level; the residual comes from the
barycentric solve (analytic inverse here, LAPACK there) on near-degenerate
triangles.
2026-11-01 02:54:55 +08:00

271 lines
14 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)
JustOneCacophony 的双耳后端支持三种 HRTF 来源:`SimpleFreeFieldHRIR` SOFA、
杜比官方软件个性化扫描导出的 Rosella `.personalized_headphone`(JSON 解析由本项目
自行实现,不调用杜比软件),以及 `.jochrtf`(JOC compiled HRTF cache)。
SOFA 默认保留完整 HRIR,按“参考环境”直连渲染,不再编译成方向场:
```text
SOFA 完整 HRIR [M,2,N]
-> CanonicalHrtf(48 kHz / 单 radius shell)
-> 延迟对齐的复数频谱(200-1500 Hz 相位拟合,含 Data.Delay)
-> 球面三角形重心插值(lf_logmag_phase 或 lf_mca_zero)
-> 刚性球径向修正(按参考环境距离)
-> 逐对象 partitioned convolution(block 128,FFT = max(2048, ≥2×support))
-> 参考环境的递归房间模型
-> stereo float64(统一扣除 latency)
```
`.jochrtf` 仍是显式输入(`--compiled-hrtf-cache`),走球谐方向场渲染;显式给出
`--hrtf-cache-policy` / `--hrtf-cache-dir` 会回到旧的“SOFA → `.jochrtf`”编译路径。
## 参考环境
SOFA 直连渲染需要一个参考环境配置(`--reference-config`,默认
`<exe>/local/binaural_reference.json`)。配置给出 Rosella `.personalized_headphone`
模型的路径与 SHA-256、`profile_index`(2=far、3=mid,作为 level 校准锚点)、
`room_impulse_slots`(默认 4096)与 `level_calibration_directions`(默认 128)。
渲染时每个 SOFA 方向先经该模型的 distance profile 映射成参考环境中的位置:
```text
ADM position -> int16 metadata grid -> distance profile
-> direction(单位向量)+ 距离 scale
-> direct gain a = 1/sqrt(1+coupling·(h0·d)^2)(near 恒为 1)
-> room send = h0·d·a(near 恒为 0)
-> 近中心正则化:ear distance 取 max(d, minimum_distance)
```
`near|mid|far` 选择该模型的三个 distance profile 之一(`--binaural-mode`),level 校准
始终用配置里的 `profile_index` 作为锚点,因此三种模式共享同一个 level。
指向同一声道的直达声是延迟对齐后的完整 HRIR 插值结果,房间 send 只进参考环境的
房间模型(LFE 声道不进房间)。两者的 latency 由 field(FFT/2 与 recording origin)
和 bank(961)中的较大者决定,输出前统一扣除。
## 输入接口
SOFA 输入直接按完整 HRIR 渲染,只需要 SOFA 与参考环境配置:
```powershell
joc_cli input.m4a --binaural `
--sofa-hrtf HRTF\subject.sofa `
--reference-config local\binaural_reference.json `
--binaural-mode mid --sofa-interpolation lf_logmag_phase
```
`.jochrtf` 输入(以及 `.personalized_headphone`)需要共享滤波器组表,两者都是只读输入:
```powershell
joc_cli input.m4a --binaural `
--compiled-hrtf-cache path\to\subject.jochrtf `
--kernels data\rosella_kernels.npz `
--binaural-mode mid --binaural-tail-seconds 5.0
```
多球壳 SOFA 必须用 `--hrtf-radius-m` 指定球壳(单球壳自动选择);`--hrtf-radius-m`
对已编译的 `.jochrtf` 不再生效。`--sofa-interpolation` 选择完整 HRIR 的局部插值:
`lf_logmag_phase`(默认,对数幅度 + 相位)或 `lf_mca_zero`(听觉带幅度修正)。
库接口使用同一组字段:文件任务用 `joc_task_config`,流式用 `joc_stream_config`,
其中 `hrtf_sofa_path`(或 `hrtf_path`)、`reference_config_path`、`sofa_interpolation`、
`hrtf_compile`、`kernels_path`、`binaural_mode`、`binaural_tail_seconds` 决定双耳通路。
`.jochrtf` 是**输入**而不是本库的产物:从 SOFA 或测量数据编译该缓存属于工具链的职责,
与本仓库解耦。缓存加载时会校验成员集合、dtype 与形状、C 连续性、CRC-32 以及按成员重算的
载荷哈希(见下文 `.jochrtf` 一节)。
`binaural_mode` 取 `near`、`mid`、`far`,选择后端的三组预置参数;`binaural_tail_seconds`
决定 flush 时排空的房间尾音长度(默认 5.0 s)。
## 双耳渲染模式
`--binaural-mode off|near|mid|far`(默认 `mid`)是**人为指定的渲染提示**,不是
从输入 E-AC-3 JOC 码流提取或还原的原始双耳元数据:
- 直接双耳渲染(`--binaural`):near/mid/far 生效,默认 `mid`;`off` 报错;
- ADM BWF:DBMD segment 10 中后 15 个 JOC 对象的 binaural render mode 写
`off=0/near=1/far=2/mid=3`,前 10 个 bed 保持不变,默认 `mid`;`off` 用于显式
关闭双耳元数据提示。
## Canonical SOFA 契约
当前 strict importer 接受:
- `Conventions=SOFA`;
- `SOFAConventions=SimpleFreeFieldHRIR`,version `0.4`、`1.0` 或 `1.1`;
- `DataType=FIR`,`Data.IR[M,2,N]`;
- 单一正有限 `Data.SamplingRate`,单位为 hertz/Hz;
- spherical 或 Cartesian `SourcePosition`;
- 单值或 per-measurement 的 `ListenerPosition/View/Up`;
- 两个能由 listener-local lateral 坐标唯一识别左右的 receiver;
- 单一且零偏移的 emitter;
- causal `Data.Delay[I,2]` 或 `[M,2]`;
- 明确的 free-field/anechoic `RoomType`。
receiver 左右顺序由几何决定,不能假定 `Data.IR` 的 receiver index。SOFA listener
坐标为 $+X$ front、
$+Y$ left、
$+Z$ up;ADM 坐标为
$+X$ right、
$+Y$ front、
$+Z$ up,转换为:
$$\bigl(x_{\mathrm{SOFA}},\ y_{\mathrm{SOFA}},\ z_{\mathrm{SOFA}}\bigr) = \bigl(y_{\mathrm{ADM}},\ -x_{\mathrm{ADM}},\ z_{\mathrm{ADM}}\bigr)$$
`CanonicalHrtf` 将 `Data.IR` 与 `Data.Delay` 分开保存。只有时域 baseline 才调用
`materialized_measurement()` 将 delay 应用一次;运行时 SH 路径不先 materialize。
非 48 kHz HRIR 使用 float64 `scipy.signal.resample_poly` 规范化,delay samples 按
相同比例缩放。
GeneralFIR、BRIR、TF、多 emitter、多义 receiver 或非 free-field 数据需要单独的
convention adapter,不能只通过 reshape 进入核心 importer。
## Delay/phase:exactly once
编译器只允许三种互斥语义:
1. 非零 `Data.Delay` 是 `Data.IR` 外部 delay;FIR 不去旋,运行时应用一次。
2. `Data.Delay=0` 且 HRIR 有普通正 onset:以每耳 main peak 分离 arrival,拟合后
在运行时恢复一次;当前阈值为 peak index 大于 2 samples。
3. `Data.Delay=0` 且双耳 FIR 共享 sample-0 起点:不发明外部 delay,原 complex
phase 直接进入五阶场。
任何路径都不能再叠加第二套 ear delay 或 phase-group delay。
SOFA 直连路径不走这套编译期语义:它保留完整 IR,用 200-1500 Hz 相位拟合估计到达时间,
`Data.Delay` 与拟合出的延迟各应用一次(先去掉 `Data.Delay`,再用插值后的延迟复原)。
## 公开 filterbank 与方向场
运行时固定为:
- 48 kHz;
- 64-sample QMF hop;
- 64-QMF / 77-hybrid;
- analysis/synthesis latency 961 samples;
- 五阶、36 项、ACN/N3D real spherical harmonics;
- PCM、delay、SH、room state 为 float64;频带传递和频域状态为 complex128。
每个 hybrid band 的 real/imaginary 单位增益都通过同一套 analysis/synthesis 链生成
脉冲字典,共 154 个实参数;编译不是直接读取 77 个 FFT bin。默认 projection
ridge 为 `1e-3`,SH ridge 为 `1e-5`。同方向 measurement 先合并,再用球面 Voronoi
面积权重做 ridge fit。
固定表位于 `data/rosella_kernels.npz`,实现公开标准化的滤波器组,各表可由如下
公式计算。
hybrid 分析核定义于 [3GPP TS 26.405 / ETSI TS 126 405](https://www.etsi.org/deliver/etsi_ts/126400_126499/126405/06.00.00_60/ts_126405v060000p.pdf)
第 5.2.2 节(Table 1 的 $Q=8$/
$Q=4$ 系数,delay 6):
$$G_q^p[n] = g^p[n]\cdot\exp\Bigl(j\,\frac{2\pi}{Q^p}\bigl(q+\tfrac12\bigr)(n-6)\Bigr),\qquad n=0,\dots,12$$
QMF analysis 表即 MPEG-4 AAC/SBR(ISO/IEC 14496-3/AMD1:2003 第 4.B.18.2 节)
的 64 complex QMF bank;打包的 $64\times10$ 表是公开 640-tap prototype
$c_0,\dots,c_{639}$ 的多相重排:
$$A_{r,t} = \frac{(-1)^t}{128}\,c_{63-r+64t},\qquad r=0,\dots,63,\ t=0,\dots,9$$
QMF synthesis 表为上述 analysis 多相矩阵 $\mathbf{A}$ 的因果左逆,即求解
$\mathbf{A}\,\mathbf{W}=\mathbf{P}$(
$\mathbf{P}$ 为 577-sample 延迟置换;
全链 $961 = 577 + 6\times64$),以 rank-4 分解形式存储:
$$W_{b,l} = \sum_{r=1}^{4} t_{b,l,r}\,\mathbf{b}_{b,r}^{\top}$$
hybrid synthesis 表为 77→64 重组:高频带恒等 $Y_{3+b}=X_{16+b}$;低频带(
$C_p$ 为
$8+4+4$ 子带划分):
$$Y_p = \sum_{q\in C_p}\Bigl(\mathrm{Re}X_q + j\,s_q\,\mathrm{Im}X_q\Bigr),\qquad s_q\in\{\pm1\}$$
loader 校验 archive 和每个数组的 SHA-256;table version、所有数组 hash 与
77 个 band-center 参考值都属于 cache key。标准可公开获取不等于获准实施相关
专利;更多来源信息见 [`data/README.md`](../data/README.md) 与
[`THIRD_PARTY_NOTICES.md`](../THIRD_PARTY_NOTICES.md)。
## `.jochrtf`
`.jochrtf` 是无 pickle 的压缩 NumPy archive,固定包含:
| key | dtype / shape |
|---|---|
| `metadata_json` | 含 JSON 文本的 NumPy Unicode scalar(`dtype.kind == "U"`) |
| `band_center_frequencies_hz` | little-endian `float64[77]` |
| `coefficients` | little-endian `complex128[36,2,77]` |
| `delay_coefficients` | little-endian `float64[36,2]` |
| `delay_bounds` | little-endian `float64[2,2]` |
metadata magic 固定为 `JOC-HRTF-CACHE`,并记录 schema/compiler/phase-policy、
ACN/N3D、filterbank table hashes、SOFA content SHA-256、采样率、radius、order、
两个 ridge、payload hash 和 fit report。cache key 覆盖所有会改变编译结果的字段。
metadata 不保存本机绝对 `source_path`,仅可保存 source display name。
loader 使用 `allow_pickle=False`,并在构造对象前检查 ZIP 成员集、解压大小、shape、
dtype、端序、连续布局、有限值、delay bounds、band centers、payload hash 和 cache
key。writer 使用同目录临时文件、`fsync`、进程持有的 OS 文件锁和原子
`os.replace`;对应的隐藏 `.lock` sidecar 可保留,但不代表仍有 writer 持锁。
旧版本、损坏或配置不匹配的 cache 不能命中;从 SOFA 启动时会重建,显式 cache
入口则直接报错。
删除磁盘 cache 后,从同一 SOFA 和同一编译配置得到的场与渲染结果不得改变。
`.jochrtf` 包含由源 HRIR 变换得到的方向场系数与 delay 数据,因此“可以重建”不表示
它不受数据许可约束。生成 cache 不会扩大源 SOFA/HRTF 数据集授予的权利;cache 的
使用、复制和再分发仍须遵守源数据集条款。不能确认条款时,应把 `.jochrtf` 作为本地
私有 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 调度:
- 每帧输入 `[1536,16]`;
- channel 0 是 special LFE,channel 1..15 是 JOC objects;
- ID11/OAMD position 使用 sample-timed timeline;
- 每 512 samples 更新方向/profile;
- 每个对象拥有独立 direct/early history,late FDN 全局共享;
- `finish()` 排空 early/late tail;输出增益显式应用,不隐含 limiter 或节目响度归一化。
Near/Mid/Far、equal-power direct level、六面 shoebox 一阶 image source、late send、
unitary FDN、LFE 120–180 Hz cosine-squared 低通及 room calibration 都是 JOC
项目定义行为,不是 SOFA 或 Dolby 公布常数。
双耳渲染在本库内实现:filterbank、SH 方向场求值、逐对象 early/direct 历史与共享 FDN
全部执行于 `joc_core`(`ejoc_sofa_binaural_*` 内核),对外只消费编译好的方向场与
512-sample 粒度的元数据更新。
## 技术引用与权利边界
- [SOFA SimpleFreeFieldHRIR convention](https://www.sofaconventions.org/mediawiki/index.php/SimpleFreeFieldHRIR)
- [3GPP TS 26.405 / ETSI TS 126 405(64-QMF/77-hybrid 定义)](https://www.etsi.org/deliver/etsi_ts/126400_126499/126405/06.00.00_60/ts_126405v060000p.pdf)
- [Dolby binaural render mode workflow](https://professionalsupport.dolby.com/s/article/What-is-Binaural-Render-Mode-and-how-do-the-settings-affect-my-mix)
- [EP3090576A1](https://patents.google.com/patent/EP3090576A1/en),仅作 direct/early/late、
subband 与 FDN 架构背景,不证明某个产品使用特定实施例。
规范、源码或专利文献可公开获取,不等于获准复制其内容、再分发派生产物或实施其中的
专利权利要求。本项目的技术引用本身不授予专利许可,也不作不侵权保证;准备发布或集成
到产品的一方应自行审查适用的数据许可、软件许可、专利许可及 freedom-to-operate。
公开标准来源与权利边界见
[`THIRD_PARTY_NOTICES.md`](../THIRD_PARTY_NOTICES.md)。