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.
271 lines
14 KiB
Markdown
271 lines
14 KiB
Markdown
# 双耳渲染
|
||
|
||
[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)。
|