空间可移植性¶

OpenJOC 直接实现空间渲染 DSP，而不是把对象渲染交给平台专用的空间音频引擎。操作系统音频 API 可以用于集成和 I/O，但不会决定 OpenJOC 的空间渲染结果。

所有平台使用同一个渲染器和同一套空间语义。

原生 22.2¶

22.2 是 OpenJOC 对应 ITU-R BS.2051-3 Sound System H（9+10+3）的通用扬声器预设：24 个语义声道、22 个空间扬声器和两个语义 LFE。OpenJOC 的 canonical 顺序是：

FL, FR, FC, LFE1, BL, BR, FLc, FRc, BC, LFE2, SiL, SiR,
TpFL, TpFR, TpFC, TpC, TpBL, TpBR, TpSiL, TpSiR, TpBC,
BtFC, BtFL, BtFR

公开资料在 ITU-R BS.2051-3 的表 10 中列出了 Sound System H 的扬声器，以及允许的方位角/仰角范围。OpenJOC 使用这些公开范围的确定性中点，生成归一化布局数据。底层、中层、上层和顶层是同一通用 SpatialLayout 投影器中的四层；不存在专门针对 22.2 的另一套渲染器。

LFE1 和 LFE2 永远不是空间投影顶点。当前 E-AC-3 输入边界只提供一个 Base LFE 平面；输出为 22.2 物理布局时，会把这个平面复制到两个明确标记的 LFE 目的地。对象不能通过点、Region、Extent、Spread、Pair 或 ChannelLock 投影进入任一 LFE。

WAV 输出是 24 声道 PCM，不会伪造 WAVEFORMATEXTENSIBLE 掩码，因为标准掩码无法准确描述完整的 22.2 声道身份集合。CLI 会报告这一限制。CAF 输出会携带有序的声道描述：能使用标准 CAF 标签的位置使用标准标签，其余 22.2 位置使用明确的坐标描述。

内置通用双耳输出¶

不带 --sofa 的 --binaural 会选择内置的 SADIE II D1 KU100 通用资源。这是一份离线数据资源，不是外部渲染器。内置 SOFA 和用户提供的 SOFA 使用同一套 OpenJOC SOFA 读取、球面插值、延迟处理、因果 FIR 卷积和尾部排空流程。--sofa FILE 仍然是明确的覆盖选项；用户 SOFA 格式错误时仍会拒绝继续处理。

许可检查：HRTF_REDISTRIBUTION_VERIFIED。

内置资源来自官方 SADIE II D1 48 kHz、256 抽头 HRIR 网格，由 HDF5 SOFA 转换为 OpenJOC 已支持的 NetCDF classic CDF-1 子集。它保留 8,802 个实测方向，并增加 15 个精确的 canonical 虚拟扬声器别名；这些别名复制最近实测 HRIR，因此内置库共有 8,817 个条目，大小约为 17.3 MiB。最大别名角度间隔为 2.542 度，由离线生成器检查；运行时不会使用最近邻回退。

离线转换器是 tools/generate-builtin-hrtf.py。只有重新生成仓库中已经检查过的资源时，才需要 HDF5 Python 工具；渲染时不需要 Python、HDF5、网络连接或运行时下载。

本资源使用的授权上游文件，其可复现记录如下：

upstream source: https://sofacoustics.org/data/database/sadie/D1_48K_24bit_256tap_FIR_SOFA.sofa
upstream SHA-256: e6c72a84dd947b5ef75438ab96a9c2a32ed10f033472b9c4c11a49aff00a8a31
generator: tools/generate-builtin-hrtf.py
generated SHA-256: b9bcecd8a07e7eed4474a9b063c47672384339e83605bd245ff0adc098869fab
generated bytes: 18164824

标准默认虚拟布局是 7.1.4。该资源原生采样率为 48 kHz，因此不会额外引入只供内置资源使用的重采样器。这个来源中的 HRIR 延迟为零，但渲染器仍会遵循通用的、能够处理延迟的 SOFA 约定。

API 行为¶

Rust 调用方使用 BinauralConfig::builtin_generic(...) 选择默认资源，或使用 BinauralConfig::from_sofa_bytes(...) 指定用户数据集。原有的 BinauralConfig { sofa_bytes: ... } 构造方式仍然有效：空字节选择内置资源，非空字节选择用户 SOFA。C ABI 调用方为内置资源传递空/零 SOFA 缓冲区，为用户 SOFA 传递非空缓冲区；ABI 结构布局和尺寸兼容规则不变。