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

9.6 KiB
Raw Blame History

双耳渲染

English · 返回 README

JustOneCacophony 的双耳后端支持两种 HRTF 来源:杜比官方软件个性化扫描导出的 Rosella .personalized_headphone(JSON 解析由本项目自行实现,不调用杜比软件),以及 离线编译好的 .jochrtf 方向场缓存。.jochrtf 是可删除、可重建的 JOC compiled HRTF cache,不是交换格式。

.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 模型。两者都是只读输入,本库不做测量数据格式的解析:

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 第 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。

.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。

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 粒度的元数据更新。

技术引用与权利边界

规范、源码或专利文献可公开获取,不等于获准复制其内容、再分发派生产物或实施其中的 专利权利要求。本项目的技术引用本身不授予专利许可,也不作不侵权保证;准备发布或集成 到产品的一方应自行审查适用的数据许可、软件许可、专利许可及 freedom-to-operate。 公开标准来源与权利边界见 THIRD_PARTY_NOTICES.md。