Files
JustOneCacophony/docs/binaural.md
T
TheM14 0bb82e4115
ci / ubuntu-latest (push) Failing after 19s
ci / macos-latest (push) Canceled after 0s
ci / windows-latest (push) Canceled after 0s
ci / release (push) Canceled after 0s
Port the OAMD metadata rendering and the frame-level JOC core
The JOC bitstream reports a per-frame parse status instead of treating every
anomaly as an exception: an unsupported downmix configuration, a clamped
object count, an unknown parameter-band count, bad offset_ts values and
trailing bytes each get their own status. The raw 5-bit offset_ts values are
kept as coded and validated to be strictly increasing per object, and the
clipgain uses 2^(x-4) * (1 + y/32).

The JOC core gains a frame-level state machine. It keeps the per-object
previous matrix and its presence marker, the seq counter, the 8-plane
passthrough history, the LFE clipgain ramp start and the previous actual
core-channel count. Normal, hold, hard-cut and passthrough frames are
distinguished: a frame without a previous state interpolates per the
data-point rules, an object that disappears keeps publishing a zero matrix,
a frame without metadata passes the 8 core planes through to slots 0..7 with
the 1217-sample delay, and a declared core-channel-count change hard-cuts and
clears the LFE ring while the clipgain ramp state is kept. The core LFE
applies the full clipgain as a sample-wise ramp before its delay.

The OAMD parser exposes the full frame state: every object's state in every
position block, the programme assignment and the trim element, with multiple
blocks and up to 30 declared objects accepted. The speaker renderer applies
this state: per-block gain/inactive, zone/elevation, the size kernel, snap,
divergence, element 5 refinement, the priority size budget, ISF basis
matrices and bed channel distribution, scheduled on the 32-sample metadata
grid with block alignment and gain ramps. The size kernel, ISF basis
assembly, bed routing and compensation are computed in oamd_math from the
speaker layout geometry; bed labels and reference positions derive from the
layout tables. The six ISF configurations and twelve layout descriptors are
compiled in as static tables (oamd/isf_tables.h); the JSON loader and the
configure-time embedding are gone. The layout tables gain 6.0, and the layout
lookup, bed map and trim probe follow.

The binaural position timeline consumes the full frame state as well: every
position block is scheduled at its own offset and ramp, and its track list
grows with the declared object count, so multi-block and over-16-object
programmes are rendered instead of rejected. The JOC binaural input stays one
LFE plus fifteen object sources; the extra tracks are followed but not
panned.

The file task and the stream parse the full state for speaker and binaural,
while the ADM export keeps the 15-track single-block view. The public headers
carry the new status values, the frame-level entry point and the raw offset_ts
description; the internal ABI versions go to 6 (joc_core), 2 (frame params and
EMDF info) and 4 (eac3joc).

ctest covers the frame-level core (clipgain formula and LFE ramp, offset_ts
validation, frame statuses, the 8-plane passthrough, the seq state machine and
the no-previous-state interpolation), the OAMD parser state, the compiled-in
ISF tables and the binaural timeline. The READMEs and the mathematical notes
describe the 6.0 layout, the frame state machine, the metadata application and
the ISF lookup tables.
2026-11-08 14:04:21 +08:00

192 lines
9.6 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 来源:杜比官方软件个性化扫描导出的
Rosella `.personalized_headphone`(JSON 解析由本项目自行实现,不调用杜比软件),以及
离线编译好的 `.jochrtf` 方向场缓存。`.jochrtf` 是可删除、可重建的 JOC compiled HRTF
cache,不是交换格式。
```text
.jochrtf
-> 77 带方向场 + 延迟模型
-> 64-QMF / 77-hybrid analysis
-> 逐对象 direct + 可选 early reflections
-> 可选 shared unitary-FDN late room
-> stereo float64
```
## 输入接口
双耳后端消费两种输入:已编译的方向场(JOC compiled HRTF cache,`.jochrtf`)配共享滤波器组表,
或者是 Rosella `.personalized_headphone` 模型。两者都是只读输入,本库不做测量数据格式的解析:
```powershell
joc_cli input.m4a --binaural `
--compiled-hrtf-cache path\to\subject.jochrtf `
--kernels path\to\rosella_kernels.npz `
--jochrtf-room on `
--binaural-mode mid --binaural-tail-seconds 5.0
joc_cli input.m4a --binaural --personalized-headphone HRTF\binaural.personalized_headphone
```
库接口使用同一组字段:文件任务用 `joc_task_config`,流式用 `joc_stream_config`,
其中 `hrtf_path`、`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` 用于显式
关闭双耳元数据提示。
## 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。
## 公开 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。
固定表按公开标准化的滤波器组实现并编译进源码,各表可由如下
公式计算。
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\}$$
固定表在编译期确定,运行时不加载外部 archive,也不参与缓存键。标准可公开
获取不等于获准实施相关专利;来源与权利边界见
[`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 不会命中,而是直接报错。
删除磁盘 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`(与 Rosella 路径共用) | 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_jochrtf_*` 内核),对外只消费编译好的方向场与
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)。