Fix OAMD ramp timing and band-0 DC filter gating

.gitignore

@@ -1,5 +1,6 @@
 __pycache__/
 *.py[cod]
+.pytest_cache/
 
 .venv/
 venv/
@@ -15,3 +16,8 @@ metadata_cache/
 *.variant-error.json
 *.objects16.f32le
 
+HRTF/
+
+*.sofa
+*.personalized_headphone
+*.jochrtf

README.en.md

@@ -4,19 +4,21 @@
 
 > JustOneCacophony is an experimental/test implementation of E-AC-3 JOC for studying JOC parsing, reconstruction, rendering, and the associated mathematics.
 
-The project can extract and parse EMDF, ID14 JOC parameters, and ID11 OAMD metadata from common E-AC-3 JOC streams. It combines those data with the core 5.1 PCM decoded by FFmpeg, reconstructs LFE plus 15 object channels, and writes either ADM BWF or a WAV file for a selected speaker layout.
+The project can extract and parse EMDF, ID14 JOC parameters, and ID11 OAMD metadata from common E-AC-3 JOC streams. It combines those data with the core 5.1 PCM decoded by FFmpeg, reconstructs LFE plus 15 object channels, and writes ADM BWF, a WAV file for a selected speaker layout, or direct binaural stereo using a standard SOFA HRTF.
 
-This is research code, not a complete, standards-compliant, or production-grade Dolby JOC decoder. It covers only the stream forms currently implemented. Unknown variants fail explicitly—because when the math goes wrong, all that may remain is the cacophony.
+This is research code, not a complete, standards-compliant, or production-grade JOC decoder. It covers only the stream forms currently implemented. Unknown variants fail explicitly—because when the math goes wrong, all that may remain is the cacophony.
 
 ## Current features
 
 - Scan common contiguous EMDF containers in E-AC-3 sync frames.
-- Parse ID14 dense JOC parameters, Huffman data, differential matrices, and `joc_clipgain`.
+- Parse ID14 dense / sparse JOC parameters, Huffman data, differential matrices, and `joc_clipgain`.
 - Parse ID11 OAMD position updates and build object trajectories.
 - Reconstruct LFE plus 15 object channels through analysis QMF, parameter interpolation, the object matrix, and inverse QMF.
 - Write a 25-channel ADM BWF: a 10-channel 7.1.2 bed (silent except for LFE) plus 15 objects.
 - Render directly to `2.0`, `3.1`, `5.1`, `7.1`, `5.1.2`, `5.1.4`, `7.1.2`, `7.1.4`, `9.1.4`, or `9.1.6`.
-- Write float32 or PCM24 WAV and require an explicit policy when PCM24 would clip.
+- Run public SOFA binaural rendering directly from `pcm16 + ID11/OAMD`, without a temporary ADM BWF.
+- Keep the binaural DSP in float64/complex128, including 961-sample latency compensation, cross-frame state, and the room tail.
+- Use a shared float32/PCM24 WAV writer and explicit PCM24 clipping policy for direct outputs.
 - Use the NumPy backend or an optional C++20 core through `ctypes`; `auto` falls back to Python when the native library is unavailable.
 - Read or write metadata sidecars and produce metadata, timing, and output reports.
 
@@ -30,16 +32,19 @@ M4A / E-AC-3
   ├─ ID11 OAMD → object positions and timing
   └─ LFE + 15 objects
        ├─ 25ch ADM BWF
-       └─ speaker WAV for the selected layout
+       ├─ speaker WAV for the selected layout
+       └─ direct ID11 timeline + SOFA HRTF → binaural WAV
 ```
 
-The Python and C++ backends follow the same documented mathematics. The native core handles the state-heavy DSP and speaker rendering; high-level bitstream parsing, ADM assembly, and CLI behavior remain in Python.
+The Python and C++ backends follow the same mathematics for JOC object reconstruction and speaker rendering. The public SOFA binaural backend currently runs in Python; bitstream parsing, the OAMD timeline, and CLI behavior also remain in Python.
 
 ## Requirements
 
 - Python 3.10+
 - NumPy 1.24+
-- A standalone FFmpeg executable; `ffmpeg-python` is not required. FFmpeg is discovered through `PATH` by default or selected with `--ffmpeg`
+- h5py 3.8+
+- SciPy 1.10+
+- A standalone FFmpeg executable; `ffmpeg-python` is not required. FFmpeg is discovered through `PATH` by default or selected with `--ffmpeg`. On startup the decoder options are probed with `ffmpeg -h decoder=eac3`: a missing E-AC-3 decoder or `-drc_scale` is a hard error, while a missing `-target_level` only fails when `--eac3-target-level` is used
 - Optional: CMake and a C++20 toolchain to build the native core
 
 Install the Python dependency in a project-specific environment:
@@ -78,12 +83,58 @@ python main.py input.m4a --speaker-layout 5.1 --speaker-format int24
 python main.py input.m4a --speaker-layout 7.1.2 --speaker-output output.7.1.2.wav
 ```
 
-When PCM24 may clip in a non-interactive environment, select a policy explicitly:
+Write binaural stereo directly (ordinary objects are Near/Mid/Far only; Mid is
+the default). The HRTF input accepts three sources:
+
+```powershell
+# 1) SOFA (defaults to HRTF/binaural.sofa, or an explicit path)
+python main.py input.m4a --binaural
+python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa
+
+# 2) Rosella .personalized_headphone (defaults to HRTF/binaural.personalized_headphone)
+python main.py input.m4a --binaural --personalized-headphone
+python main.py input.m4a --binaural --personalized-headphone C:\HRTF\subject.personalized_headphone
+
+# 3) .jochrtf compiled cache
+python main.py input.m4a --binaural --compiled-hrtf-cache C:\HRTF\subject.jochrtf
+
+# Common options
+python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa `
+  --binaural-mode near
+python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa `
+  --hrtf-cache-policy disk
+python main.py input.m4a --binaural --binaural-output output.binaural.wav
+```
+
+With none of the three specified, resolution tries, in order:
+`HRTF/binaural.sofa`, the unique `.jochrtf` under `output/hrtf-cache`, then
+`HRTF/binaural.personalized_headphone`; if none exist, an error asks for an
+explicit path.
+
+- `.sofa` is the portable source of truth; it can hold self-scanned or any
+  generic HRTF data.
+- `.personalized_headphone` is a model produced by Dolby's official
+  personalization scan; its JSON parsing is implemented by this project
+  (`src/rosella_model.py`) and does not invoke any Dolby software.
+- `.jochrtf` is a project-internal cache compiled from SOFA; it is disposable,
+  rebuildable, and written to `output/hrtf-cache` by default.
+
+HRTF data lives under `HRTF/` (git-ignored): the default SOFA
+`HRTF/binaural.sofa` and the default model
+`HRTF/binaural.personalized_headphone`. Because the cache contains transformed
+HRTF data, its use and redistribution remain subject to the source dataset's
+terms. See [Binaural Rendering](docs/binaural.en.md) and
+[Third-party notices](THIRD_PARTY_NOTICES.md) for format boundaries, formulas,
+state, timing, and distribution considerations.
+
+Speaker and binaural output share peak analysis, the WAV writer, and clipping policy. When PCM24 may clip in a non-interactive environment, select a policy explicitly:
 
 ```powershell
 python main.py input.m4a --speaker-layout 5.1 --speaker-format int24 --clip-action abort
 python main.py input.m4a --speaker-layout 5.1 --speaker-format int24 --clip-action float32
 python main.py input.m4a --speaker-layout 5.1 --speaker-format int24 --clip-action continue
+python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa `
+  --binaural-format int24 --clip-action abort
 ```
 
 Metadata and diagnostics:
@@ -95,17 +146,63 @@ python main.py input.m4a --metadata-cache metadata_cache
 python main.py input.m4a --metadata-dir metadata_cache
 ```
 
-### Experimental binaural mode settings for JOC objects
+### E-AC-3 decode-side dynamic range and level
 
-The binaural mode written here is a user-selected, experimental rendering hint for downstream ADM renderers. It is **not original binaural metadata extracted or recovered from the input E-AC-3 JOC bitstream**, nor does it represent the original mix's per-object binaural settings. The selected mode is applied uniformly to all 15 JOC objects; the default `unspecified` is this tool's default, not a mode detected in the source file.
-
-Use `--joc-binaural-mode off|near|far|mid|unspecified` to select a mode, encoded as `0|1|2|3|4` respectively. The default is `unspecified`:
+By default FFmpeg applies the stream `dynrng` dynamic range compression when
+decoding E-AC-3 (`-drc_scale 1`). The core 5.1 PCM is the input of JOC object
+reconstruction, and `dynrng` is playback-time gain, so it is inherited linearly
+by every object and every output (ADM, speaker, binaural). This tool therefore
+decodes at **full dynamic range** by default:
 
 ```powershell
-python main.py input.m4a --joc-binaural-mode mid
+python main.py input.m4a                            # default: -drc_scale 0, full range
+python main.py input.m4a --eac3-drc-scale 1         # reproduce consumer playback
+python main.py input.m4a --eac3-drc-scale 0.5       # apply half of it
+python main.py input.m4a --eac3-target-level -27    # dialnorm-referenced level
 ```
 
-This option only sets the low 3 binaural-render-mode bits of the last 15 JOC object entries in ADM BWF DBMD segment 10, leaving the first 10 bed entries unchanged. It does not change PCM, object trajectories, or direct speaker rendering, and does not itself produce binaural stereo audio. The adjacent `.report.json` records the mode name and value in `joc_binaural_mode` and `joc_binaural_mode_value`; both are `null` for direct speaker output, where the option does not apply.
+- `--eac3-drc-scale` (`0`–`6`, default `0`) maps to FFmpeg `-drc_scale`: the gain
+  of each E-AC-3 block is `dynrng factor ^ value`. `0` disables DRC, `1` is the
+  author's intent, and `>1` is asymmetric (loud parts fully compressed, quiet
+  parts enhanced).
+- `--eac3-target-level` (`-31`–`0`, default `0` = off) maps to FFmpeg
+  `-target_level`: a static per-frame gain of about `target_level - dialnorm` dB,
+  independent of and stackable with `--eac3-drc-scale`. dialnorm is a per-stream
+  property (measured Apple Music Atmos streams are about `-18` to `-19` dB, so
+  `-27` is roughly `8`–`9` dB of attenuation).
+- The level change is expected: compared with the FFmpeg default, measured
+  tracks move by `0` to `-2.15` dB peak and `0` to `-1.69` dB RMS (direction
+  depends on the stream `dynrng`), so `output_clip.peak` and the PCM24 clipping
+  decision in `.report.json` change accordingly.
+- `--gain-db` is a static gain applied **after** reconstruction (float64 on the
+  binaural path) and is not the same thing as decode-side DRC, which is
+  block-varying; do not use `--gain-db` to cancel it.
+- The `ffmpeg` field of `.report.json` records the FFmpeg version and the decode
+  options that were actually passed (`version`, `eac3_decode_options`).
+
+### Binaural render mode
+
+`--binaural-mode off|near|mid|far` selects the binaural render mode; the default
+is `mid`, and both outputs share this single option:
+
+- **Direct binaural rendering** (`--binaural`): `off` is rejected (error);
+  near/mid/far apply, defaulting to `mid`;
+- **ADM BWF**: the low 3 binaural-render-mode bits of the last 15 JOC object
+  entries in DBMD segment 10 carry `off=0/near=1/far=2/mid=3`, leaving the first
+  10 bed entries unchanged; the default is `mid`, and `off` explicitly disables
+  the binaural metadata hint.
+
+```powershell
+python main.py input.m4a --binaural-mode mid
+python main.py input.m4a --binaural-mode off   # ADM BWF only: disable the DBMD hint
+```
+
+**The default `mid` is a human-specified rendering hint**; it is not original
+binaural metadata extracted or recovered from the input E-AC-3 JOC bitstream,
+nor does it represent the original mix's per-object binaural settings. The hint
+does not change PCM, object trajectories, or direct speaker rendering. The
+adjacent `.report.json` records `binaural_mode` (the mode name) and
+`binaural_mode_value` (the ADM code; `null` for direct binaural output).
 
 ### OAMD time alignment
 
@@ -117,6 +214,17 @@ align32(1473) = 1472
 
 Override the two paths with `--object-delay-samples` and `--speaker-metadata-offset`, respectively. The 1473-sample timing offset is distinct from the 640-value inverse-QMF filter/window state; 640 is a QMF state length, not a metadata delay.
 
+The direct binaural path uses `--object-delay-samples`. Each ID11/OAMD event is
+placed on an absolute sample timeline from its frame start, outer-subpayload
+offset, and block offset, then shifted by that delay. Each 1536-sample input
+frame is processed as three consecutive 512-sample blocks; the interpolated
+position, direction, and profile are updated at each block's absolute starting
+sample.
+
+### Binaural calculation
+
+See [Binaural Rendering Mathematics](docs/binaural.en.md) for QMF, hybrid processing, direction fields, distance, ITD, room processing, the 512-sample parameter updates above, and 961-sample latency compensation.
+
 For all options:
 
 ```powershell
@@ -150,8 +258,10 @@ JustOneCacophony/
 ├─ main.py               command-line entry point
 ├─ src/                  Python implementation modules
 ├─ native/               C/C++ acceleration core, C ABI, and required table data
-├─ data/                 runtime table data for Python
+├─ data/                 Python runtime table data
 ├─ lib/                  native runtime drop-in directory (create as needed)
+├─ HRTF/                 user HRTF data directory (create as needed, git-ignored)
+├─ output/               output directory (create as needed; the .jochrtf cache defaults to its hrtf-cache subdirectory)
 ├─ docs/                 math and native-core notes in both languages
 ├─ requirements.txt      Python dependency
 ├─ README.md             Chinese documentation
@@ -170,21 +280,24 @@ The main documented stages are:
 - OAMD Q15 coordinate conversion;
 - equal-power panning over target-layout regions;
 - layout-dependent position compensation and sample-wise gain ramps;
-- float32 and PCM24 output quantization.
+- float32 and PCM24 output quantization;
+- SOFA canonical import, 64-QMF/77-hybrid projection, `36×2×77` fifth-order fields, exactly-once delay/phase, project early/late room behavior, and special LFE.
 
 See the [mathematical notes](docs/math.en.md) for the equations used by the decoding and rendering process.
 
 ## Known limitations
 
 - Only the common contiguous EMDF transport is covered. Fragmented transport across multiple audio-block skip fields is not covered.
-- Dense JOC is the main path. The Sparse JOC branch should not be treated as supported.
-- The speaker path currently covers ordinary point objects; extent, spread, divergence, and similar modes are outside the supported scope.
+- The speaker and SOFA binaural paths currently cover ordinary point objects; extent, spread, diffuse, divergence, channel lock, and similar controls are outside the supported scope.
 - OAMD trim elements are boundary-checked and skipped; warp, balance, and trim parameters are not applied to raw object trajectories or speaker rendering.
 - Multi-data-point streams, uncommon band configurations, and unusual OAMD scheduling have less coverage than common 12-band, single-data-point material.
 - A speaker limiter is outside the current primary formula.
-- ADM output, native binaries, and speaker layouts still need broader interoperability checks across platforms, players, and real material.
+- The SOFA importer currently supports the strict `SimpleFreeFieldHRIR` FIR subset; other SOFA conventions require explicit adapters.
+- The binaural runtime is fixed at 48 kHz, fifth order, and one measurement-radius shell at a time; the public binaural backend defaults to the native accelerator and falls back to Python when the native library is unavailable.
+- ADM output, native binaries, speaker layouts, and binaural models still need broader interoperability checks across platforms, players, and real material.
 
 ## Documentation
 
 - [Mathematical notes](docs/math.en.md) · [中文](docs/math.md)
 - [Native-core notes](docs/native.en.md) · [中文](docs/native.md)
+- [Binaural rendering](docs/binaural.en.md) · [中文](docs/binaural.md)

README.md

@@ -4,19 +4,21 @@
 
 > JustOneCacophony 是一个 E-AC-3 JOC 的实验性 / 测试实现，用于研究 JOC 的解析、重建、渲染以及相关数学过程。
 
-项目可以从常见 E-AC-3 JOC 码流中提取并解析 EMDF、ID14 JOC 参数和 ID11 OAMD 元数据，结合 FFmpeg 解码出的核心 5.1 PCM 重建 LFE 与 15 路对象 PCM，并输出 ADM BWF 或指定扬声器布局的 WAV。
+项目可以从常见 E-AC-3 JOC 码流中提取并解析 EMDF、ID14 JOC 参数和 ID11 OAMD 元数据，结合 FFmpeg 解码出的核心 5.1 PCM 重建 LFE 与 15 路对象 PCM，并输出 ADM BWF、指定扬声器布局的 WAV，或使用标准 SOFA HRTF 直接输出双耳 WAV。
 
-这是研究代码，不是完整、标准兼容或生产级的 Dolby JOC 解码器。它只覆盖当前已实现的码流形态；遇到未知变体时会明确报错，而不是假装一切都很和谐——如果哪里算错了，它可能就真的只剩 cacophony 了。
+这是研究代码，不是完整、标准兼容或生产级的 JOC 解码器。它只覆盖当前已实现的码流形态；遇到未知变体时会明确报错，而不是假装一切都很和谐——如果哪里算错了，它可能就真的只剩 cacophony 了。
 
 ## 当前功能
 
 - 扫描 E-AC-3 同步帧中的常见连续 EMDF 容器；
-- 解析 ID14 dense JOC 参数、Huffman 数据、差分矩阵与 `joc_clipgain`；
+- 解析 ID14 dense / sparse JOC 参数、Huffman 数据、差分矩阵与 `joc_clipgain`；
 - 解析 ID11 OAMD 位置更新并生成对象轨迹；
 - 通过 analysis QMF、参数插值、对象矩阵和 inverse QMF 重建 LFE + 15 路对象 PCM；
 - 输出 25 声道 ADM BWF：10 声道 7.1.2 bed（除 LFE 外静音）+ 15 个对象；
 - 直接渲染 `2.0`、`3.1`、`5.1`、`7.1`、`5.1.2`、`5.1.4`、`7.1.2`、`7.1.4`、`9.1.4`、`9.1.6`；
-- 输出 float32 或 PCM24 WAV，并在 PCM24 削波前提供明确处理策略；
+- 从 `pcm16 + ID11/OAMD` 直接运行公开 SOFA 双耳渲染，不生成临时 ADM BWF；
+- 双耳 DSP 全程使用 float64/complex128，并保留 961-sample latency compensation、跨帧状态和 room 尾声；
+- 直接输出统一支持 float32 或 PCM24 WAV，并在 PCM24 削波前提供明确处理策略；
 - 使用 NumPy 后端，或通过 `ctypes` 调用可选的 C++20 原生核；`auto` 模式在原生库不可用时回退到 Python；
 - 读取或写入 metadata sidecar，并生成元数据、运行时间和输出摘要。
 
@@ -30,16 +32,21 @@ M4A / E-AC-3
   ├─ ID11 OAMD → 对象位置与时间轨迹
   └─ LFE + 15 objects
        ├─ 25ch ADM BWF
-       └─ 指定布局的扬声器 WAV
+       ├─ 指定布局的扬声器 WAV
+       └─ ID11 直接时间轴 + SOFA HRTF → 双耳 WAV
 ```
 
-Python 与 C++ 后端使用同一组已记录的数学过程。原生核只处理状态密集的 DSP 和扬声器渲染，高层位流解析、ADM 组装与命令行逻辑仍在 Python 中。
+Python 与 C++ 后端在 JOC 对象重建、扬声器渲染和公开 SOFA 双耳渲染中使用同一组
+数学过程；native 双耳后端与 Python 参考实现逐值一致（差异 < 1e-9）。位流解析、
+OAMD 时间轴和命令行逻辑在 Python 中。
 
 ## 环境
 
 - Python 3.10+
 - NumPy 1.24+
-- 独立的 FFmpeg 可执行程序；不需要 `ffmpeg-python`。默认从 `PATH` 查找，也可通过 `--ffmpeg` 指定可执行文件路径
+- h5py 3.8+
+- SciPy 1.10+
+- 独立的 FFmpeg 可执行程序；不需要 `ffmpeg-python`。默认从 `PATH` 查找，也可通过 `--ffmpeg` 指定可执行文件路径。启动时会探测 `ffmpeg -h decoder=eac3`：缺 E-AC-3 解码器或 `-drc_scale` 直接报错，缺 `-target_level` 只在使用 `--eac3-target-level` 时报错
 - 可选：支持 C++20 的 CMake 工具链，用于自行构建原生核
 
 建议在项目专用虚拟环境中安装依赖：
@@ -78,12 +85,50 @@ python main.py input.m4a --speaker-layout 5.1 --speaker-format int24
 python main.py input.m4a --speaker-layout 7.1.2 --speaker-output output.7.1.2.wav
 ```
 
-在非交互环境请求 PCM24 且可能削波时，需要显式选择处理方式：
+直接输出双耳渲染 WAV（普通对象仅 Near/Mid/Far，默认 Mid）。HRTF 输入支持三种来源：
+
+```powershell
+# 1) SOFA（缺省取 HRTF/binaural.sofa，也可显式指定）
+python main.py input.m4a --binaural
+python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa
+
+# 2) Rosella .personalized_headphone（缺省取 HRTF/binaural.personalized_headphone）
+python main.py input.m4a --binaural --personalized-headphone
+python main.py input.m4a --binaural --personalized-headphone C:\HRTF\subject.personalized_headphone
+
+# 3) .jochrtf 编译缓存
+python main.py input.m4a --binaural --compiled-hrtf-cache C:\HRTF\subject.jochrtf
+
+# 常用选项
+python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa `
+  --binaural-mode near
+python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa `
+  --hrtf-cache-policy disk
+python main.py input.m4a --binaural --binaural-output output.binaural.wav
+```
+
+三者都不指定时的自动选择顺序：`HRTF/binaural.sofa` → `output/hrtf-cache` 下唯一的
+`.jochrtf` → `HRTF/binaural.personalized_headphone`；都没有则报错并提示显式指定。
+
+- `.sofa` 是可移植的 source of truth；可以是自行扫描或任何来源的通用 HRTF 数据。
+- `.personalized_headphone` 是杜比官方软件个性化扫描得到的模型，其 JSON 解析由
+  本项目自行实现（`src/rosella_model.py`），不调用杜比软件。
+- `.jochrtf` 是从 SOFA 编译出的项目内部 cache，可删除、可从 SOFA 重建，默认写在
+  `output/hrtf-cache`。
+
+HRTF 数据统一放在 `HRTF/`（git 忽略）：默认 SOFA `HRTF/binaural.sofa`、默认模型
+`HRTF/binaural.personalized_headphone`。cache 含有源 HRTF 的变换数据，使用与再分发
+仍受源数据许可约束；格式边界、计算公式、状态、时间轴及发布注意事项见
+[双耳渲染](docs/binaural.md) 和 [第三方通知](THIRD_PARTY_NOTICES.md)。
+
+扬声器和双耳输出共享峰值检查、writer 与削波策略。在非交互环境请求 PCM24 且可能削波时，需要显式选择处理方式：
 
 ```powershell
 python main.py input.m4a --speaker-layout 5.1 --speaker-format int24 --clip-action abort
 python main.py input.m4a --speaker-layout 5.1 --speaker-format int24 --clip-action float32
 python main.py input.m4a --speaker-layout 5.1 --speaker-format int24 --clip-action continue
+python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa `
+  --binaural-format int24 --clip-action abort
 ```
 
 元数据与诊断：
@@ -95,17 +140,41 @@ python main.py input.m4a --metadata-cache metadata_cache
 python main.py input.m4a --metadata-dir metadata_cache
 ```
 
-### 实验性 JOC 对象双耳模式设置
+### E-AC-3 解码级动态范围与电平
 
-这里写入的双耳模式是用户手动指定、供下游 ADM 渲染器使用的实验性渲染提示，**不是从输入 E-AC-3 JOC 码流中提取或还原的原始双耳元数据**，也不代表原始混音中各对象的双耳设置。所选模式会统一应用到 15 个 JOC 对象；默认 `unspecified` 只是本工具的默认值，并非从源文件检测到的模式。
-
-使用 `--joc-binaural-mode off|near|far|mid|unspecified` 选择模式，编码分别为 `0|1|2|3|4`，默认 `unspecified`：
+FFmpeg 解码 E-AC-3 时默认施加码流 `dynrng` 动态范围压缩（`-drc_scale 1`）。核心 5.1 PCM 是 JOC 对象重建的输入，而 `dynrng` 属于回放期增益，会被线性继承到全部对象与成品（ADM／扬声器／双耳），因此本工具默认按**全动态范围**解码：
 
 ```powershell
-python main.py input.m4a --joc-binaural-mode mid
+python main.py input.m4a                            # 默认：-drc_scale 0，全动态范围
+python main.py input.m4a --eac3-drc-scale 1         # 复现消费者回放（码流作者意图）
+python main.py input.m4a --eac3-drc-scale 0.5       # 施加一半
+python main.py input.m4a --eac3-target-level -27    # 按码流 dialnorm 归一化电平
 ```
 
-此选项仅设置 ADM BWF 的 DBMD segment 10 中后 15 个 JOC 对象的 binaural render mode 低 3 bit；前 10 个 bed 保持不变。它不改变 PCM、对象轨迹或直接扬声器渲染，也不直接生成双耳立体声音频。输出旁的 `.report.json` 用 `joc_binaural_mode` 和 `joc_binaural_mode_value` 记录模式名称与数值；直接扬声器输出时两者为 `null`，表示不适用。
+- `--eac3-drc-scale`（`0`～`6`，默认 `0`）对应 FFmpeg 的 `-drc_scale`：每个 E-AC-3 block 的增益为 `dynrng 因子 ^ 该值`。`0` 关闭 DRC；`1` 为码流作者意图；`>1` 非对称（响处全压、轻处增强）。
+- `--eac3-target-level`（`-31`～`0`，默认 `0` 不施加）对应 FFmpeg 的 `-target_level`：按每帧 dialnorm 施加静态增益，约 `target_level - dialnorm` dB，与 `--eac3-drc-scale` 相互独立、可叠加。dialnorm 是逐码流属性（实测 Apple Music Atmos 流约 `-18`～`-19` dB，故 `-27` 约等于衰减 `8`～`9` dB）。
+- 电平变化是预期的：与 FFmpeg 默认值相比，实测曲目峰值变化 `0`～`-2.15` dB、RMS `0`～`-1.69` dB（方向取决于码流 `dynrng`），`.report.json` 的 `output_clip.peak` 与 int24 削波判定会随之变化。
+- `--gain-db` 是**重建之后**的静态增益（双耳路径 float64），与解码级 DRC 不是一回事；解码级 DRC 是按 block 时变的，不要用 `--gain-db` 去抵消它。
+- `.report.json` 的 `ffmpeg` 字段记录 FFmpeg 版本与实际下发的解码选项（`version`、`eac3_decode_options`）。
+
+### 双耳渲染模式
+
+`--binaural-mode off|near|mid|far` 选择双耳渲染模式，默认 `mid`，两种输出共用这一个选项：
+
+- **直接双耳渲染**（`--binaural`）：`off` 不可用（报错），near/mid/far 生效，默认 `mid`；
+- **ADM BWF**：DBMD segment 10 中后 15 个 JOC 对象的 binaural render mode 写
+  `off=0/near=1/far=2/mid=3`，前 10 个 bed 保持不变，默认 `mid`；`off` 用于显式
+  关闭双耳元数据提示。
+
+```powershell
+python main.py input.m4a --binaural-mode mid
+python main.py input.m4a --binaural-mode off   # 仅 ADM BWF：关闭 DBMD 双耳提示
+```
+
+**默认 `mid` 是本工具人为指定的渲染提示**，不是从输入 E-AC-3 JOC 码流中提取或
+还原的原始双耳元数据，也不代表原始混音中各对象的双耳设置。该提示不改变 PCM、
+对象轨迹或直接扬声器渲染。输出旁的 `.report.json` 用 `binaural_mode`（模式名）
+和 `binaural_mode_value`（ADM 编码值，直接双耳输出时为 `null`）记录。
 
 ### OAMD 时间对齐
 
@@ -117,6 +186,15 @@ align32(1473) = 1472
 
 可分别用 `--object-delay-samples` 和 `--speaker-metadata-offset` 覆盖默认值。这里的 1473 不应与 inverse-QMF 的 640 项 filter/window state 混淆；后者是 QMF 状态长度，不是 metadata delay。
 
+直接双耳路径使用 `--object-delay-samples`。每个 ID11/OAMD event 先按 frame start、
+outer subpayload offset 与 block offset 落到绝对 sample timeline，再加该 delay；每个
+1536-sample 输入帧按三个连续 512-sample block 处理，并在每块的绝对起始 sample
+查询插值后的位置、更新方向和 profile。
+
+### 双耳计算
+
+双耳路径的 QMF、hybrid、方向场、距离、ITD、room、上述 512-sample 参数更新和 961-sample 延迟补偿见[双耳渲染数学](docs/binaural.md)。
+
 更多参数可查看：
 
 ```powershell
@@ -152,6 +230,8 @@ JustOneCacophony/
 ├─ native/               C/C++ 加速核、C ABI 与必要表数据
 ├─ data/                 Python 运行时表数据
 ├─ lib/                  原生运行库投放目录（按需创建）
+├─ HRTF/                 用户 HRTF 数据目录（按需创建，git 忽略）
+├─ output/               输出目录（按需创建；.jochrtf 缓存默认在其 hrtf-cache 子目录）
 ├─ docs/                 数学与原生核文档（中英文）
 ├─ requirements.txt      Python 依赖
 ├─ README.md             中文说明
@@ -170,21 +250,24 @@ JustOneCacophony/
 - OAMD Q15 坐标转换；
 - 基于目标布局 region 的等功率声像；
 - 布局位置补偿与逐样本增益斜坡；
-- float32 与 PCM24 输出量化。
+- float32 与 PCM24 输出量化；
+- SOFA canonical importer、64-QMF/77-hybrid 投影、`36×2×77` 五阶方向 field、exactly-once delay/phase、项目 early/late room 与 special LFE。
 
 解码与渲染过程使用的公式见[数学说明](docs/math.md)。
 
 ## 已知限制
 
 - 当前只覆盖常见 continuous EMDF transport；跨多个 audio-block skip field 的碎片化 transport 尚未覆盖。
-- Dense JOC 是当前主要路径；Sparse JOC 分支不应视为受支持能力。
-- 扬声器路径当前只覆盖普通点对象；extent、spread、divergence 等对象模式不在支持范围内。
+- 扬声器与 SOFA 双耳路径当前只覆盖普通点对象；extent、spread、diffuse、divergence、channel lock 等对象控制不在支持范围内。
 - OAMD trim element 会按声明边界校验并跳过；warp、balance 和 trim 参数不应用于当前原始对象轨迹或扬声器渲染。
 - 多数据点、少见参数带配置和特殊 OAMD 调度的覆盖度低于常见 12-band、单数据点素材。
 - 扬声器 limiter 不属于当前实现的主公式。
-- ADM 输出、原生库和扬声器布局仍需在更多平台、播放器与真实素材上确认互操作性。
+- SOFA importer 当前严格支持 `SimpleFreeFieldHRIR` FIR；其它 SOFA convention 需要显式 adapter。
+- 双耳 runtime 固定 48 kHz、五阶和一次选择一个 measurement-radius shell；公开双耳默认走 native 加速，原生库不可用时自动回退 Python。
+- ADM 输出、原生库、扬声器布局和双耳模型仍需在更多平台、播放器与真实素材上确认互操作性。
 
 ## 文档
 
 - [数学说明](docs/math.md) · [English](docs/math.en.md)
 - [原生核说明](docs/native.md) · [English](docs/native.en.md)
+- [双耳渲染](docs/binaural.md) · [English](docs/binaural.en.md)

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,41 @@
+# Third-party notices / 第三方通知
+
+本文件记录 `data/rosella_kernels.npz`（`src/public_filterbank.py` 使用的滤波器组表）
+的公开标准来源，以及 HRTF 数据与专利的边界说明。
+
+## 公开标准来源
+
+64-QMF → 77-hybrid 结构与 13-tap 低带 prototype 定义于
+[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)$$
+
+64-band QMF analysis 即 ISO/IEC 14496-3/AMD1:2003 第 4.B.18.2 节的 MPEG-4
+AAC/SBR 64 complex QMF bank；打包的 $64\times10$ 表是公开 640-tap prototype 的
+多相重排：
+
+$$A_{r,t} = \frac{(-1)^t}{128}\,c_{63-r+64t}$$
+
+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}$，低频带：
+
+$$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\}$$
+
+相同数值可在 FFmpeg（`aacps_tablegen.h`、`aacsbrdata.h`）等公开实现中查到。
+
+## HRTF 数据与 `.jochrtf`
+
+`.jochrtf` 含有特定源 SOFA/HRTF 数据集的变换系数与 delay；其使用、复制与再分发
+仍受源数据集许可约束，权限不明确时应作为私有 cache 保存。
+
+## 专利说明
+
+标准可公开获取不等于获准实施相关专利。

data/README.en.md

@@ -2,7 +2,9 @@
 
 [中文](README.md)
 
-`tables.npz` contains the static table data used by the Python path:
+This directory contains static production tables. It does not contain user HRTFs.
+
+`tables.npz` contains the JOC core decoding tables:
 
 ```text
 analysis_window                         float64[10,64]
@@ -18,3 +20,64 @@ joc_huff_code_7ch_pos_index_sparse      int64[6,2]
 `src/joc_qmf.py` loads the QMF tables, while `src/joc_decode.py` loads the JOC Huffman trees. Python does not read C/C++ headers under `native/`.
 
 The corresponding native data are stored in `native/src/qmf_tables.h` and `native/src/joc_huffman_tables.h`. Changes on either side should update the other and be checked for value-by-value agreement.
+
+## Binaural rendering tables
+
+`rosella_kernels.npz` contains the fixed 64-QMF/77-hybrid tables used by the
+public SOFA binaural path:
+
+```text
+format_version                  little-endian int32[1]
+qmf_analysis_coefficients       float32[64,10]
+hybrid_analysis_low_kernel      float32[3,2,13,16,2]
+hybrid_synthesis_indices        int16[154,4]
+hybrid_synthesis_values         float32[154]
+qmf_synthesis_basis             float64[64,4,128]
+qmf_synthesis_taps              float64[64,10,4]
+```
+
+The float32 table values are promoted to float64 when loaded.
+`src/public_filterbank.py` verifies the archive and every array by SHA-256.
+Those hashes, the table version, and the 77 reference band-center values all
+participate in the `.jochrtf` cache key. The full analysis/synthesis latency is
+961 samples.
+
+The packaged tables implement publicly standardized filter banks, computable
+from the following formulas.
+
+The 64-QMF → 77-hybrid structure, the 13-tap low-band prototypes, and their
+half-bin complex modulation are defined in
+[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),
+Section 5.2.2 (Table 1 $Q=8$/$Q=4$ coefficients, 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$$
+
+The 64-band QMF analysis is the MPEG-4 AAC/SBR 64 complex QMF analysis bank of
+ISO/IEC 14496-3/AMD1:2003, subclause 4.B.18.2; the packaged $64\times10$ table
+is the polyphase reordering of the public 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$$
+
+The QMF synthesis table is the causal left inverse of the analysis polyphase
+matrix $\mathbf{A}$, i.e. the solution of $\mathbf{A}\,\mathbf{W}=\mathbf{P}$
+($\mathbf{P}$ is the 577-sample delay permutation; total latency
+$961 = 577 + 6\times64$), stored as a rank-4 factorization:
+
+$$W_{b,l} = \sum_{r=1}^{4} t_{b,l,r}\,\mathbf{b}_{b,r}^{\top}$$
+
+The hybrid synthesis table is the 77→64 recombination: identity for the high
+bands, $Y_{3+b}=X_{16+b}$, and for the low bands ($C_p$ is the $8+4+4$ child
+partition):
+
+$$Y_p = \sum_{q\in C_p}\Bigl(\operatorname{Re}X_q + j\,s_q\,\operatorname{Im}X_q\Bigr),\qquad s_q\in\{\pm1\}$$
+
+The same values also appear in other public implementations of these standards
+(for example FFmpeg's `aacps_tablegen.h` and `aacsbrdata.h`).
+
+Public availability of a standard does not by itself grant permission to
+practice related patent claims.
+
+SOFA is the user-visible source of truth. A `.jochrtf` file is a disposable JOC
+compiled HRTF cache that can be rebuilt from SOFA. The cache contains
+transformed source-HRTF data and remains subject to the source SOFA/HRTF
+dataset's licence and redistribution restrictions.

data/README.md

@@ -2,7 +2,9 @@
 
 [English](README.en.md)
 
-`tables.npz` 集中保存 Python 路径使用的静态表数据：
+本目录保存 Python 生产路径使用的静态表数据，不保存用户 HRTF。
+
+`tables.npz` 保存 JOC 核心解码表：
 
 ```text
 analysis_window                         float64[10,64]
@@ -18,3 +20,54 @@ joc_huff_code_7ch_pos_index_sparse      int64[6,2]
 `src/joc_qmf.py` 读取 QMF 表，`src/joc_decode.py` 读取 JOC Huffman 树。Python 不读取 `native/` 下的 C/C++ 头文件。
 
 原生侧对应数据分别位于 `native/src/qmf_tables.h` 与 `native/src/joc_huffman_tables.h`。修改任何一侧时，应同步更新另一侧并进行逐值一致性检查。
+
+## 双耳渲染表
+
+`rosella_kernels.npz` 保存公开 SOFA 双耳路径使用的 64-QMF/77-hybrid 固定表：
+
+```text
+format_version                  little-endian int32[1]
+qmf_analysis_coefficients       float32[64,10]
+hybrid_analysis_low_kernel      float32[3,2,13,16,2]
+hybrid_synthesis_indices        int16[154,4]
+hybrid_synthesis_values         float32[154]
+qmf_synthesis_basis             float64[64,4,128]
+qmf_synthesis_taps              float64[64,10,4]
+```
+
+float32 表值载入后提升为 float64。`src/public_filterbank.py` 在读取时校验 archive
+及每个数组的 SHA-256；这些 hash、table version 和 77 个 band-center 参考值共同进入
+`.jochrtf` cache key。analysis/synthesis 全链 latency 为 961 samples。
+
+打包表实现的是公开标准化的滤波器组，各表可由如下公式计算。
+
+64-QMF → 77-hybrid 结构、13-tap 低带 prototype 与半 bin 复调制定义于
+[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$$
+
+64-band QMF analysis 即 ISO/IEC 14496-3/AMD1:2003 第 4.B.18.2 节的 MPEG-4
+AAC/SBR 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(\operatorname{Re}X_q + j\,s_q\,\operatorname{Im}X_q\Bigr),\qquad s_q\in\{\pm1\}$$
+
+相同数值可在 FFmpeg（`aacps_tablegen.h`、`aacsbrdata.h`）等公开实现中查到。
+
+标准可公开获取不等于获准实施相关专利。
+
+`.sofa` 是用户可见的 source of truth；`.jochrtf` 是可删除、可从 SOFA 重建的
+JOC compiled HRTF cache。cache 含有源 HRTF 的变换数据，仍受源 SOFA/HRTF
+数据集的许可与再分发限制约束。

docs/binaural.en.md

@@ -0,0 +1,284 @@
+# Binaural rendering
+
+[中文](binaural.md) · [Back to README](../README.en.md)
+
+JustOneCacophony's binaural backend supports three HRTF sources:
+`SimpleFreeFieldHRIR` SOFA, the Rosella `.personalized_headphone` model exported
+by Dolby's official personalization scan (its JSON parsing is implemented by
+this project and invokes no Dolby software), and the `.jochrtf` cache compiled
+from SOFA. SOFA is compiled into an in-memory directional field when the model
+is loaded. A `.jochrtf` file is only a disposable, reproducible JOC compiled
+HRTF cache; it is neither an interchange format nor a prerequisite for using
+SOFA.
+
+```text
+SOFA FIR
+  -> CanonicalHrtf
+  -> 48 kHz / one radius shell / delay-phase policy
+  -> 64-QMF / 77-hybrid projection
+  -> fifth-order ACN/N3D real-SH field
+  -> per-object direct + early reflections
+  -> shared unitary-FDN late room
+  -> float64 stereo
+```
+
+## Inputs
+
+The CLI has three mutually exclusive HRTF input sources; with none given, a
+default rule resolves the input:
+
+```powershell
+# 1) SOFA: defaults to HRTF/binaural.sofa, or an explicit path
+python main.py input.m4a --binaural
+python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa
+
+# 2) Rosella .personalized_headphone: defaults to HRTF/binaural.personalized_headphone
+python main.py input.m4a --binaural --personalized-headphone
+python main.py input.m4a --binaural --personalized-headphone C:\HRTF\subject.personalized_headphone
+
+# 3) .jochrtf: explicitly load a compiled cache
+python main.py input.m4a --binaural `
+  --compiled-hrtf-cache C:\HRTF\subject.jochrtf
+
+# Optional: create/reuse a transparent disk cache for SOFA
+python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa `
+  --hrtf-cache-policy disk
+```
+
+The default order is `HRTF/binaural.sofa`, then the unique `.jochrtf` under
+`output/hrtf-cache`, then `HRTF/binaural.personalized_headphone`; if none of
+the three exist, an error asks for an explicit path. Multiple `.jochrtf` files
+under `output/hrtf-cache` are also an error requiring an explicit choice.
+
+The `.personalized_headphone` JSON parsing is implemented by this project
+(`src/rosella_model.py`) and does not invoke any Dolby software.
+
+`--hrtf-cache-policy` accepts `none`, `memory`, or `disk`. The default is
+`memory`; neither `none` nor `memory` creates a file. `disk` writes to
+`output/hrtf-cache` by default, or to `--hrtf-cache-dir`. `--hrtf-radius-m`
+selects the nearest measurement-radius shell.
+
+The Python API also uses explicit factories:
+
+```python
+from sofa_binaural_backend import SofaBinauralBackend
+
+renderer = SofaBinauralBackend.from_sofa(
+    "subject.sofa",
+    source_count=16,
+    default_profile="mid",
+    cache_policy="memory",
+)
+
+cached = SofaBinauralBackend.from_compiled_cache(
+    "subject.jochrtf",
+    source_count=16,
+    default_profile="mid",
+)
+```
+
+The factories never guess a format from an unknown suffix: SOFA and `.jochrtf`
+always use distinct loaders.
+
+## Binaural render mode
+
+`--binaural-mode off|near|mid|far` (default `mid`) is a **human-specified
+rendering hint**, not original binaural metadata extracted or recovered from the
+input E-AC-3 JOC bitstream:
+
+- Direct binaural rendering (`--binaural`): near/mid/far apply, default `mid`;
+  `off` is an error;
+- ADM BWF: the low 3 binaural-render-mode bits of the last 15 JOC object entries
+  in DBMD segment 10 carry `off=0/near=1/far=2/mid=3`, leaving the first 10 bed
+  entries unchanged; the default is `mid`, and `off` explicitly disables the
+  binaural metadata hint.
+
+## Canonical SOFA contract
+
+The strict importer currently accepts:
+
+- `Conventions=SOFA`;
+- `SOFAConventions=SimpleFreeFieldHRIR`, version `0.4`, `1.0`, or `1.1`;
+- `DataType=FIR` and `Data.IR[M,2,N]`;
+- one positive finite `Data.SamplingRate` in hertz/Hz;
+- spherical or Cartesian `SourcePosition`;
+- singleton or per-measurement `ListenerPosition/View/Up`;
+- two receivers whose listener-local lateral geometry uniquely identifies L/R;
+- one zero-offset emitter;
+- causal `Data.Delay[I,2]` or `[M,2]`;
+- an explicitly free-field/anechoic `RoomType`.
+
+Receiver order comes from geometry, never from the receiver array index. SOFA
+listener coordinates are $+X$ front,
+$+Y$ left,
+$+Z$ up; ADM coordinates are
+$+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` keeps `Data.IR` and `Data.Delay` separate. Only a time-domain
+baseline calls `materialized_measurement()` to apply delay once; the runtime SH
+path never materializes and then restores the delay. Non-48-kHz HRIRs are
+normalized with float64 `scipy.signal.resample_poly`, and delay samples scale by
+the same ratio.
+
+GeneralFIR, BRIR, TF, multiple emitters, ambiguous receivers, and non-free-field
+data require convention-specific adapters. They cannot enter the core importer
+through a reshape.
+
+## Exactly-once delay and phase
+
+The compiler recognizes three mutually exclusive representations:
+
+1. Nonzero `Data.Delay` is external to `Data.IR`; the FIR is not de-rotated and
+   runtime applies the delay once.
+2. With `Data.Delay=0` and an ordinary positive-onset HRIR, each ear's main peak
+   supplies arrival time. Compilation separates it and runtime restores it once.
+   The current threshold is a peak index greater than two samples.
+3. With `Data.Delay=0` and both FIRs at a shared sample-zero origin, no external
+   delay is invented. The authored complex phase stays in the fifth-order field.
+
+No path may add a second ear delay or phase-group delay.
+
+## Public filterbank and directional field
+
+The runtime is fixed at:
+
+- 48 kHz;
+- a 64-sample QMF hop;
+- 64-QMF / 77 hybrid bands;
+- 961 samples of analysis/synthesis latency;
+- fifth order, 36 terms, ACN/N3D real spherical harmonics;
+- float64 PCM, delay, SH, and room state; complex128 band transfers and spectra.
+
+Real and imaginary unit gains for every hybrid band pass through the same
+analysis/synthesis chain to form a 154-real-parameter impulse dictionary. The
+compiler does not sample 77 FFT bins. Defaults are `1e-3` projection ridge and
+`1e-5` SH ridge. Coincident directions are merged before a spherical-Voronoi
+weighted ridge fit.
+
+The fixed resource is `data/rosella_kernels.npz`, which implements publicly
+standardized filter banks, computable from the following formulas.
+
+The hybrid analysis kernels are defined in [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),
+Section 5.2.2 (Table 1 $Q=8$/
+$Q=4$ coefficients, 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$$
+
+The QMF analysis table is the MPEG-4 AAC/SBR 64 complex QMF bank of
+ISO/IEC 14496-3/AMD1:2003, subclause 4.B.18.2, stored as the polyphase
+reordering of the public 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$$
+
+The QMF synthesis table is the causal left inverse of the analysis polyphase
+matrix $\mathbf{A}$, i.e. the solution of
+$\mathbf{A}\,\mathbf{W}=\mathbf{P}$
+($\mathbf{P}$ is the 577-sample delay permutation; total latency
+$961 = 577 + 6\times64$), stored as a rank-4 factorization:
+
+$$W_{b,l} = \sum_{r=1}^{4} t_{b,l,r}\,\mathbf{b}_{b,r}^{\top}$$
+
+The hybrid synthesis table is the 77→64 recombination: identity for the high
+bands, $Y_{3+b}=X_{16+b}$, and for the low bands(
+$C_p$ is the
+$8+4+4$ child partition):
+
+$$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\}$$
+
+The loader verifies the archive and every array by SHA-256; the table version,
+all array hashes, and the 77 reference band-center values are part of the cache
+key. Public availability of a standard does not by itself grant permission to
+practice related patent claims. See
+[`data/README.en.md`](../data/README.en.md) and
+[`THIRD_PARTY_NOTICES.md`](../THIRD_PARTY_NOTICES.md) for the sources and the
+rights boundary.
+
+## `.jochrtf`
+
+A `.jochrtf` file is a pickle-free compressed NumPy archive with an exact member set:
+
+| key | dtype / shape |
+|---|---|
+| `metadata_json` | NumPy Unicode scalar containing JSON text (`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 uses the `JOC-HRTF-CACHE` magic and records the schema, compiler and
+phase-policy versions, ACN/N3D convention, filterbank hashes, SOFA content
+SHA-256, sample rate, radius, order, both ridge values, payload hash, and fit
+report. Every setting that changes compilation participates in the cache key.
+Metadata never persists an absolute local `source_path`; it may keep a display
+name only.
+
+Before constructing a field, the loader uses `allow_pickle=False` and validates
+ZIP members and expanded sizes, shapes, dtypes, byte order, contiguous layout,
+finite values, delay bounds, band centers, payload hash, and cache key. The
+writer uses a same-directory temporary file, `fsync`, a process-held OS file
+lock, and atomic `os.replace`. Its hidden `.lock` sidecar may remain and does not
+mean that a writer still owns the lock. Outdated, damaged, or mismatched
+caches cannot hit. SOFA input rebuilds an invalid cache; an explicitly selected
+cache reports the error.
+
+Deleting a disk cache must not change the field or render produced from the same
+SOFA and compiler configuration.
+
+A `.jochrtf` file contains directional-field coefficients and delay data
+transformed from the source HRIRs. Its reproducibility therefore does not make
+it licence-free. Creating a cache does not enlarge the rights granted by the
+source SOFA/HRTF dataset: use, copying, and redistribution remain subject to
+that dataset's terms. If those terms are unclear, keep `.jochrtf` as a private
+local cache and do not ship it with the program or another build artifact.
+`source_sha256` is only a content-integrity identifier, not proof of provenance
+or permission.
+
+## JOC objects and room behavior
+
+The production adapter retains the existing JOC schedule:
+
+- `[1536,16]` input per frame;
+- channel 0 is special LFE and channels 1..15 are JOC objects;
+- ID11/OAMD positions use a sample-timed timeline;
+- source parameters update every 512 samples;
+- every object owns independent direct/early history while one late FDN is shared;
+- `finish()` drains early/late tails; output gain is explicit, with no implicit
+  limiter or programme loudness normalization.
+
+Near/Mid/Far, equal-power direct level, six first-order shoebox image sources,
+late sends, the unitary FDN, the 120–180 Hz cosine-squared LFE low-pass, and room
+calibration are JOC project-defined behavior, not constants published by SOFA or
+Dolby.
+
+The public SOFA binaural renderer defaults to the C++20 native core under
+`--backend auto/native` (`ejoc_sofa_binaural_*` in `lib/eac3joc_core.dll`): the
+filterbank, the SH direction-field evaluation, the per-object direct/early
+histories and the shared FDN all run natively, while Python only compiles the
+SOFA source and issues the per-512-sample metadata updates. When the native
+library is unavailable the renderer falls back to the Python/NumPy reference
+implementation; the two agree to better than 1e-9. `--backend python` forces
+the Python backend.
+`--backend` still selects native/Python JOC reconstruction and speaker rendering;
+native acceleration for the public binaural DSP is outside the current API.
+
+## Technical references and rights boundary
+
+- [SOFA SimpleFreeFieldHRIR convention](https://www.sofaconventions.org/mediawiki/index.php/SimpleFreeFieldHRIR)
+- [3GPP TS 26.405 / ETSI TS 126 405 (64-QMF/77-hybrid definition)](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), used only as
+  architectural background for direct/early/late, subbands, and FDNs; it does
+  not establish that any product uses a particular embodiment.
+
+Public availability of a specification, source file, or patent document does
+not by itself authorize copying its contents, redistribution of derivatives,
+or practice of patent claims. These technical references grant no patent
+licence and make no non-infringement representation. Anyone preparing a release
+or product integration must assess the applicable data and software licences,
+patent permissions, and freedom to operate. See
+[`THIRD_PARTY_NOTICES.md`](../THIRD_PARTY_NOTICES.md) for the public-standard
+provenance and rights boundary.

docs/binaural.md

@@ -0,0 +1,245 @@
+# 双耳渲染
+
+[English](binaural.en.md) · [返回 README](../README.md)
+
+JustOneCacophony 的双耳后端支持三种 HRTF 来源：`SimpleFreeFieldHRIR` SOFA、
+杜比官方软件个性化扫描导出的 Rosella `.personalized_headphone`（JSON 解析由本项目
+自行实现，不调用杜比软件），以及从 SOFA 编译出的 `.jochrtf` 缓存。SOFA 在模型加载
+时编译成内存方向场；`.jochrtf` 只是可删除、可重建的 JOC compiled HRTF cache，
+不是交换格式，也不是使用 SOFA 的前置步骤。
+
+```text
+SOFA FIR
+  -> CanonicalHrtf
+  -> 48 kHz / 单 radius shell / delay-phase policy
+  -> 64-QMF / 77-hybrid projection
+  -> 五阶 ACN/N3D 实球谐场
+  -> 逐对象 direct + early reflections
+  -> shared unitary-FDN late room
+  -> stereo float64
+```
+
+## 输入接口
+
+CLI 有三个互斥的 HRTF 输入来源；都不指定时按默认规则自动选择：
+
+```powershell
+# 1) SOFA：缺省取 HRTF/binaural.sofa，也可显式指定
+python main.py input.m4a --binaural
+python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa
+
+# 2) Rosella .personalized_headphone：缺省取 HRTF/binaural.personalized_headphone
+python main.py input.m4a --binaural --personalized-headphone
+python main.py input.m4a --binaural --personalized-headphone C:\HRTF\subject.personalized_headphone
+
+# 3) .jochrtf：显式读取预编译 cache
+python main.py input.m4a --binaural `
+  --compiled-hrtf-cache C:\HRTF\subject.jochrtf
+
+# 可选：SOFA 透明生成/复用磁盘 cache
+python main.py input.m4a --binaural --sofa-hrtf C:\HRTF\subject.sofa `
+  --hrtf-cache-policy disk
+```
+
+默认选择顺序：`HRTF/binaural.sofa` → `output/hrtf-cache` 下唯一的 `.jochrtf` →
+`HRTF/binaural.personalized_headphone`；三者都没有时报错并提示显式指定。
+`output/hrtf-cache` 下有多个 `.jochrtf` 时同样报错，要求显式选择。
+
+`.personalized_headphone` 的 JSON 解析由本项目自行实现（`src/rosella_model.py`），
+不调用任何杜比软件。
+
+`--hrtf-cache-policy` 可取 `none`、`memory`、`disk`。默认是 `memory`；`none` 和
+`memory` 都不会创建磁盘文件。`disk` 默认写入 `output/hrtf-cache`，也可用
+`--hrtf-cache-dir` 指定。`--hrtf-radius-m` 选择距离目标最近的 measurement shell。
+
+Python API 使用显式 factory：
+
+```python
+from sofa_binaural_backend import SofaBinauralBackend
+
+renderer = SofaBinauralBackend.from_sofa(
+    "subject.sofa",
+    source_count=16,
+    default_profile="mid",
+    cache_policy="memory",
+)
+
+cached = SofaBinauralBackend.from_compiled_cache(
+    "subject.jochrtf",
+    source_count=16,
+    default_profile="mid",
+)
+```
+
+文件工厂不会按“未知后缀”猜格式：SOFA 和 `.jochrtf` 始终走不同 loader。
+
+## 双耳渲染模式
+
+`--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。
+
+## 公开 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` 只用于内容一致性校验，不是许可
+或来源证明。
+
+## 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 公布常数。
+
+公开 SOFA 双耳渲染在 `--backend auto/native` 下默认走 C++20 原生核
+（`lib/eac3joc_core.dll` 的 `ejoc_sofa_binaural_*` 接口：filterbank、SH 方向场求值、
+逐对象 early/direct 历史与共享 FDN 全部在原生侧执行，Python 只做 SOFA 编译与每
+512-sample 的元数据更新）；原生库不可用时自动回退 Python/NumPy 参考实现，两者
+逐值一致（差异 < 1e-9）。`--backend python` 强制使用 Python 后端。
+
+## 技术引用与权利边界
+
+- [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)。

docs/math.en.md

@@ -4,7 +4,7 @@
 
 This document covers only the signal model and formulas used in the JustOneCacophony research path: how JOC parameters combine with core PCM to reconstruct object signals, and how OAMD coordinates become speaker gains.
 
-The formulas describe the dense-JOC and ordinary point-object paths studied by the project. They are not a complete definition of every E-AC-3 JOC variant.
+The formulas describe the JOC matrix parameters (both the dense and the sparse differential syntax) and the ordinary point-object paths studied by the project. They are not a complete definition of every E-AC-3 JOC variant.
 
 ## 1. Overall path and notation
 
@@ -52,9 +52,11 @@ $$
 N_f=1536=24\times64.
 $$
 
-## 2. Dense-JOC matrix parameters
+## 2. JOC matrix parameters
 
-### 2.1 Differential reconstruction
+For every object and data point, the quantized matrix `joc_mix_mtx_q` is defined on $N_q$ quantization levels. The `b_joc_sparse` flag selects one of two differential syntaxes: dense sends one MTX difference per core channel, while sparse sends one active channel plus one coefficient difference per parameter band.
+
+### 2.1 Dense differential reconstruction
 
 Let `quant_idx` be $q_i\in\{0,1\}$. The number of quantization levels is
 
@@ -75,38 +77,76 @@ $$
 For object $o$, data point $d$, core channel $c$, and parameter band $p$, the coded difference $\Delta_{o,d,c,p}$ reconstructs to
 
 $$
-Q_{o,d,c,0}
-=
+Q_{o,d,c,0}=
 \left(O_q+\Delta_{o,d,c,0}\right)\bmod N_q,
 $$
 
 $$
-Q_{o,d,c,p}
-=
+Q_{o,d,c,p}=
 \left(Q_{o,d,c,p-1}+\Delta_{o,d,c,p}\right)\bmod N_q,
 \qquad p>0.
 $$
 
-### 2.2 Dequantization
+### 2.2 Sparse differential reconstruction
+
+Let $I_{o,d,p}$ be the `joc_channel_idx` symbol (IDX), $V_{o,d,p}$ the `joc_vec` symbol (VEC), and $N_c\in\lbrace5,7\rbrace$ the number of core channels. Each parameter band has exactly one active channel:
+
+$$
+A_{o,d,p}=
+\begin{cases}
+I_{o,d,0}, & p=0,\\
+\left(A_{o,d,p-1}+I_{o,d,p}\right)\bmod N_c, & p>0,
+\end{cases}
+$$
+
+where $I_{o,d,0}$ is a 3-bit absolute channel index and every later IDX symbol is an increment relative to the previous **active channel**. The coefficient is a single accumulator running across parameter bands:
+
+$$
+\kappa_{o,d,-1}=O^{(s)}_q,\qquad
+\kappa_{o,d,p}=
+\left(\kappa_{o,d,p-1}+V_{o,d,p}\right)\bmod N_q,
+$$
+
+with a sparse starting point two quantization levels above the dense center offset:
+
+$$
+O^{(s)}_q=
+\begin{cases}
+50, & q_i=0,\\
+100, & q_i=1.
+\end{cases}
+$$
+
+The accumulator is **not** reset when the active channel changes. The complete matrix is
+
+$$
+Q_{o,d,c,p}=
+\begin{cases}
+\kappa_{o,d,p}, & c=A_{o,d,p},\\
+\dfrac{N_q}{2}, & c\neq A_{o,d,p}.
+\end{cases}
+$$
+
+Non-active entries take $N_q/2$, which dequantizes to exactly 0.
+
+### 2.3 Dequantization
 
 The dequantized matrix coefficient is
 
 $$
-D_{o,d,c,p}
-=
+D_{o,d,c,p}=
 \left(Q_{o,d,c,p}-\frac{N_q}{2}\right)
 \frac{820}{4096(1+q_i)}.
 $$
 
 The effective denominator is therefore 4096 in coarse mode and 8192 in fine mode.
 
-### 2.3 JOC clipgain
+### 2.4 JOC clipgain
 
 If the clipgain field consists of integer $x$ and mantissa $y$, then
 
 $$
-G_{\mathrm{clip}}
-=
+G_{\mathrm{clip}}=
 1+\frac{y}{32}2^{x-4}.
 $$
 
@@ -152,8 +192,7 @@ $$
 $$
 
 $$
-M_{o,c,b,t}
-=
+M_{o,c,b,t}=
 (1-\alpha_t)P_{o,c,b}
 +\alpha_tD_{o,c,p(b)}.
 $$
@@ -181,9 +220,8 @@ $$
 Let $\mathcal A_b$ denote the 64-band analysis-QMF operator with polyphase history state. Then
 
 $$
-X_{c,b,t}
-=
-\mathcal A_b\!\left(
+X_{c,b,t}=
+\mathcal A_b\left(
 \widetilde x_c[64t],\ldots,\widetilde x_c[64t+63];
 \mathbf s^{\mathrm A}_{c,t}
 \right).
@@ -210,8 +248,7 @@ $$
 Band 0 of each surround channel additionally passes through a 21-tap complex FIR:
 
 $$
-\widehat X_{c,0,t}
-=
+\widehat X_{c,0,t}=
 \sum_{k=0}^{20}h_kX_{c,0,t-k}.
 $$
 
@@ -222,8 +259,7 @@ These delays and filter histories are decoder state and cannot be reset independ
 For each object $o$, subband $b$, and slot $t$, the object's frequency-domain value is a linear combination of the five core channels:
 
 $$
-Z_{o,b,t}
-=
+Z_{o,b,t}=
 \sum_{c=0}^{4}
 M_{o,c,b,t}\widehat X_{c,b,t}.
 $$
@@ -238,21 +274,20 @@ Write the 64 complex subbands as 128 interleaved real values in `src`. For $k=0\
 
 $$
 \begin{aligned}
-\operatorname{zone}[2k] &= \operatorname{src}[4k],\\
-\operatorname{zone}[2k+1] &= -\operatorname{src}[4k+1],\\
-\operatorname{zone}[126-2k] &= \operatorname{src}[4k+2],\\
-\operatorname{zone}[127-2k] &= \operatorname{src}[4k+3].
+\mathrm{zone}[2k] &= \mathrm{src}[4k],\\
+\mathrm{zone}[2k+1] &= -\mathrm{src}[4k+1],\\
+\mathrm{zone}[126-2k] &= \mathrm{src}[4k+2],\\
+\mathrm{zone}[127-2k] &= \mathrm{src}[4k+3].
 \end{aligned}
 $$
 
 Treat `zone` as 64 complex values and apply an unnormalized 64-point FFT:
 
 $$
-F_k
-=
+F_k=
 \sum_{n=0}^{63}
-\operatorname{zone}_n
-\exp\!\left(-j\frac{2\pi kn}{64}\right).
+\mathrm{zone}_n
+\exp\left(-j\frac{2\pi kn}{64}\right).
 $$
 
 ### 7.2 Modulation and synthesis
@@ -260,8 +295,7 @@ $$
 Define the rotation coefficient
 
 $$
-r_k
-=
+r_k=
 \frac12\left(
 \sin\frac{\pi k}{128}
 +j\cos\frac{\pi k}{128}
@@ -277,9 +311,8 @@ $$
 Let $\mathcal S$ denote polyphase synthesis with a 640-value synthesis window and cross-slot state:
 
 $$
-\mathbf y_{o,t}
-=
-\mathcal S\!\left(
+\mathbf y_{o,t}=
+\mathcal S\left(
 \mathbf R_{o,t},W,\mathbf s^{\mathrm S}_{o,t}
 \right).
 $$
@@ -287,9 +320,8 @@ $$
 Object output is
 
 $$
-y_o[64t+r]
-=
-\operatorname{clip}\!\left(
+y_o[64t+r]=
+\mathrm{clip}\left(
 16\,\mathbf y_{o,t}[r],-1,1
 \right)G_{\mathrm{clip}},
 $$
@@ -301,9 +333,8 @@ where $r=0\ldots63$. Synthesis state must advance continuously by slot.
 LFE bypasses the object matrix and inverse QMF and uses a 1217-sample delay. After the input and output scale factors cancel:
 
 $$
-y_{\mathrm{LFE}}[n]
-=
-\operatorname{clip}\!\left(
+y_{\mathrm{LFE}}[n]=
+\mathrm{clip}\left(
 x_{\mathrm{LFE,core}}[n-1217],-1,1
 \right).
 $$
@@ -313,9 +344,8 @@ $$
 The lateral and longitudinal grids use $N=62$; the height grid uses $N=15$. The quantizer is
 
 $$
-q_N(k)
-=
-\min\!\left(
+q_N(k)=
+\min\left(
 32767,
 \left\lfloor\frac{32768k}{N}+\frac12\right\rfloor
 \right).
@@ -336,11 +366,11 @@ Their maximum runtime value is $32767/32768$, not exactly 1.
 For conversion to the ADM grid:
 
 $$
-k_1=\operatorname{round}\!\left(\frac{62q_1}{32767}\right),
+k_1=\mathrm{round}\left(\frac{62q_1}{32767}\right),
 \quad
-k_2=\operatorname{round}\!\left(\frac{62q_2}{32767}\right),
+k_2=\mathrm{round}\left(\frac{62q_2}{32767}\right),
 \quad
-k_3=\operatorname{round}\!\left(\frac{15q_3}{32767}\right),
+k_3=\mathrm{round}\left(\frac{15q_3}{32767}\right),
 $$
 
 $$
@@ -404,17 +434,15 @@ $$
 The two-dimensional point gain is
 
 $$
-\mathbf G_{\mathrm{2D}}(u,v)
-=
+\mathbf G_{\mathrm{2D}}(u,v)=
 \mathbf h(u)\odot\mathbf v(v).
 $$
 
 For 5.1-family layouts with one horizontal surround pair rather than separate side and rear pairs, the longitudinal coordinate is
 
 $$
-v_{\mathrm{floor}}
-=
-\operatorname{clamp}(2v,0,1).
+v_{\mathrm{floor}}=
+\mathrm{clamp}(2v,0,1).
 $$
 
 Other layouts use $v_{\mathrm{floor}}=v$.
@@ -424,8 +452,7 @@ Other layouts use $v_{\mathrm{floor}}=v$.
 Three-dimensional layouts compute floor gain $\mathbf G_f$ and height gain $\mathbf G_h$ separately:
 
 $$
-\mathbf G_{\mathrm{point}}(u,v,w)
-=
+\mathbf G_{\mathrm{point}}(u,v,w)=
 \cos\left(\frac\pi2w\right)\mathbf G_f
 +
 \sin\left(\frac\pi2w\right)\mathbf G_h.
@@ -450,8 +477,7 @@ $$
 Maximum position compensation is
 
 $$
-A_{\max}
-=
+A_{\max}=
 -\max\left(4.5-1.5H-3F,0\right)
 \quad\text{dB}.
 $$
@@ -459,15 +485,15 @@ $$
 Longitudinal and height weights are
 
 $$
-p_v=\operatorname{clamp}\left(\frac v{0.6},0,1\right),
+p_v=\mathrm{clamp}\left(\frac v{0.6},0,1\right),
 $$
 
 $$
-p_w=\operatorname{clamp}\left(\frac{w-0.2}{0.8},0,1\right),
+p_w=\mathrm{clamp}\left(\frac{w-0.2}{0.8},0,1\right),
 $$
 
 $$
-p=\operatorname{clamp}(p_v+p_w,0,1).
+p=\mathrm{clamp}(p_v+p_w,0,1).
 $$
 
 The linear compensation gain is
@@ -479,8 +505,7 @@ $$
 The object's target-gain vector is
 
 $$
-\mathbf G_{\mathrm{target}}
-=
+\mathbf G_{\mathrm{target}}=
 G_{\mathrm{object}}
 G_{\mathrm{pos}}
 \mathbf G_{\mathrm{point}}.
@@ -491,8 +516,7 @@ $$
 The coded position of an OAMD update is
 
 $$
-s_{\mathrm{coded}}
-=
+s_{\mathrm{coded}}=
 s_{\mathrm{frame}}
 +s_{\mathrm{outer}}
 +s_{\mathrm{OAMD}}
@@ -502,16 +526,15 @@ $$
 The theoretical update position on the decoder-output PCM timeline is
 
 $$
-s_{\mathrm{theoretical}}
-=s_{\mathrm{coded}}+d_{\mathrm{decoder}},
+s_{\mathrm{theoretical}}=
+s_{\mathrm{coded}}+d_{\mathrm{decoder}},
 \qquad d_{\mathrm{decoder}}=1473.
 $$
 
 The speaker renderer retains the existing processing-block length $B=32$, so the aligned update point is
 
 $$
-\widehat s
-=
+\widehat s=
 B\left\lfloor
 \frac{s_{\mathrm{theoretical}}+B/2-1}{B}
 \right\rfloor.
@@ -522,8 +545,7 @@ Thus, for frame-aligned updates, `align32(1473)=1472`. The 1473 value is the the
 For ramp duration $D$, the number of blocks is
 
 $$
-K
-=
+K=
 \left\lfloor
 \frac{D+B/2-1}{B}
 \right\rfloor.
@@ -550,8 +572,7 @@ If no new metadata update intervenes, this is equivalent to a sample-wise linear
 For target output channel $c$:
 
 $$
-y_c[n]
-=
+y_c[n]=
 \delta_{c,\mathrm{LFE}}x_{\mathrm{LFE}}[n]
 +
 \sum_{o=1}^{15}x_o[n]g_{o,c}[n].
@@ -560,8 +581,7 @@ $$
 Here
 
 $$
-\delta_{c,\mathrm{LFE}}
-=
+\delta_{c,\mathrm{LFE}}=
 \begin{cases}
 1, & c\text{ is the target layout's LFE channel},\\
 0, & \text{otherwise}.
@@ -573,16 +593,15 @@ A layout without LFE output does not mix input LFE into other channels. After ob
 For PCM24 output, quantization is
 
 $$
-y_{24}[n]
-=
-\operatorname{trunc}\left(
-8388607\,\operatorname{clip}(y[n],-1,1)
+y_{24}[n]=
+\mathrm{trunc}\left(
+8388607\,\mathrm{clip}(y[n],-1,1)
 \right).
 $$
 
 ## 14. Scope of the formulas
 
-- The JOC matrix section describes dense JOC; Sparse JOC uses a different sparse coefficient/index path.
+- The JOC matrix section covers both the dense MTX and the sparse IDX/VEC differential syntax.
 - The speaker-panning section describes ordinary point objects; extent, spread, divergence, and similar modes require additional models.
 - Multiple OAMD position blocks must be scheduled in time order.
 - A limiter is separate post-processing and is not included in the mixing equations above.

docs/math.md

@@ -4,7 +4,7 @@
 
 本文只说明 JustOneCacophony 研究路径中使用的信号模型和公式：JOC 参数如何与核心 PCM 结合并重建对象信号，以及 OAMD 坐标如何转换为扬声器增益。
 
-这些公式描述项目当前研究的 dense JOC 与普通点对象路径，不代表对所有 E-AC-3 JOC 变体的完整定义。
+这些公式描述项目当前研究的 JOC 矩阵参数（dense 与 sparse 两条差分语法）与普通点对象路径，不代表对所有 E-AC-3 JOC 变体的完整定义。
 
 ## 1. 总体路径与记号
 
@@ -52,9 +52,11 @@ $$
 N_f=1536=24\times64.
 $$
 
-## 2. Dense JOC 矩阵参数
+## 2. JOC 矩阵参数
 
-### 2.1 差分还原
+每个对象、每个数据点的量化矩阵 `joc_mix_mtx_q` 都定义在 $N_q$ 个量化级上。标志位 `b_joc_sparse` 选择两条差分语法之一：dense 为每个核心声道各送一路 MTX 差分，sparse 每参数带只送一个 active 声道与一路系数差分。
+
+### 2.1 Dense 差分还原
 
 令 `quant_idx` 为 $q_i\in\{0,1\}$，量化级数为
 
@@ -75,38 +77,76 @@ $$
 对对象 $o$、数据点 $d$、核心声道 $c$ 和参数带 $p$，编码差分 $\Delta_{o,d,c,p}$ 还原为
 
 $$
-Q_{o,d,c,0}
-=
+Q_{o,d,c,0}=
 \left(O_q+\Delta_{o,d,c,0}\right)\bmod N_q,
 $$
 
 $$
-Q_{o,d,c,p}
-=
+Q_{o,d,c,p}=
 \left(Q_{o,d,c,p-1}+\Delta_{o,d,c,p}\right)\bmod N_q,
 \qquad p>0.
 $$
 
-### 2.2 去量化
+### 2.2 Sparse 差分还原
+
+令 $I_{o,d,p}$ 为 `joc_channel_idx` 符号（IDX）， $V_{o,d,p}$ 为 `joc_vec` 符号（VEC）， $N_c\in\lbrace5,7\rbrace$ 为核心声道数。每参数带只有一个 active 声道
+
+$$
+A_{o,d,p}=
+\begin{cases}
+I_{o,d,0}, & p=0,\\
+\left(A_{o,d,p-1}+I_{o,d,p}\right)\bmod N_c, & p>0,
+\end{cases}
+$$
+
+其中 $I_{o,d,0}$ 是 3 bit 绝对声道号，其余 IDX 符号是相对上一个 **active 声道**的增量。系数是一个跨参数带连续的单累加器
+
+$$
+\kappa_{o,d,-1}=O^{(s)}_q,\qquad
+\kappa_{o,d,p}=
+\left(\kappa_{o,d,p-1}+V_{o,d,p}\right)\bmod N_q,
+$$
+
+sparse 起点比 dense 的中心偏移高两个量化级：
+
+$$
+O^{(s)}_q=
+\begin{cases}
+50, & q_i=0,\\
+100, & q_i=1.
+\end{cases}
+$$
+
+active 声道切换时累加器**不**重置。完整矩阵为
+
+$$
+Q_{o,d,c,p}=
+\begin{cases}
+\kappa_{o,d,p}, & c=A_{o,d,p},\\
+\dfrac{N_q}{2}, & c\neq A_{o,d,p}.
+\end{cases}
+$$
+
+非 active 项取 $N_q/2$，即去量化后恰为 0。
+
+### 2.3 去量化
 
 矩阵系数的去量化值为
 
 $$
-D_{o,d,c,p}
-=
+D_{o,d,c,p}=
 \left(Q_{o,d,c,p}-\frac{N_q}{2}\right)
 \frac{820}{4096(1+q_i)}.
 $$
 
 因此 coarse 模式的有效分母为 4096，fine 模式为 8192。
 
-### 2.3 JOC clipgain
+### 2.4 JOC clipgain
 
 若 clipgain 字段由整数 $x$ 和尾数 $y$ 组成，则
 
 $$
-G_{\mathrm{clip}}
-=
+G_{\mathrm{clip}}=
 1+\frac{y}{32}2^{x-4}.
 $$
 
@@ -152,8 +192,7 @@ $$
 $$
 
 $$
-M_{o,c,b,t}
-=
+M_{o,c,b,t}=
 (1-\alpha_t)P_{o,c,b}
 +\alpha_tD_{o,c,p(b)}.
 $$
@@ -181,9 +220,8 @@ $$
 令 $\mathcal A_b$ 表示带 polyphase 历史状态的 64-band analysis-QMF 算子，则
 
 $$
-X_{c,b,t}
-=
-\mathcal A_b\!\left(
+X_{c,b,t}=
+\mathcal A_b\left(
 \widetilde x_c[64t],\ldots,\widetilde x_c[64t+63];
 \mathbf s^{\mathrm A}_{c,t}
 \right).
@@ -210,8 +248,7 @@ $$
 环绕声道的 band 0 还经过 21-tap 复 FIR：
 
 $$
-\widehat X_{c,0,t}
-=
+\widehat X_{c,0,t}=
 \sum_{k=0}^{20}h_kX_{c,0,t-k}.
 $$
 
@@ -222,8 +259,7 @@ $$
 对每个对象 $o$、子带 $b$ 和时槽 $t$，对象频域值为五个核心声道的线性组合：
 
 $$
-Z_{o,b,t}
-=
+Z_{o,b,t}=
 \sum_{c=0}^{4}
 M_{o,c,b,t}\widehat X_{c,b,t}.
 $$
@@ -238,21 +274,20 @@ analysis 输入的 $1/16$ 缩放会在 inverse QMF 输出端由 $\times16$ 抵
 
 $$
 \begin{aligned}
-\operatorname{zone}[2k] &= \operatorname{src}[4k],\\
-\operatorname{zone}[2k+1] &= -\operatorname{src}[4k+1],\\
-\operatorname{zone}[126-2k] &= \operatorname{src}[4k+2],\\
-\operatorname{zone}[127-2k] &= \operatorname{src}[4k+3].
+\mathrm{zone}[2k] &= \mathrm{src}[4k],\\
+\mathrm{zone}[2k+1] &= -\mathrm{src}[4k+1],\\
+\mathrm{zone}[126-2k] &= \mathrm{src}[4k+2],\\
+\mathrm{zone}[127-2k] &= \mathrm{src}[4k+3].
 \end{aligned}
 $$
 
 把 `zone` 重新视为 64 个复数后执行未归一化 64 点 FFT：
 
 $$
-F_k
-=
+F_k=
 \sum_{n=0}^{63}
-\operatorname{zone}_n
-\exp\!\left(-j\frac{2\pi kn}{64}\right).
+\mathrm{zone}_n
+\exp\left(-j\frac{2\pi kn}{64}\right).
 $$
 
 ### 7.2 调制与合成
@@ -260,8 +295,7 @@ $$
 定义旋转系数
 
 $$
-r_k
-=
+r_k=
 \frac12\left(
 \sin\frac{\pi k}{128}
 +j\cos\frac{\pi k}{128}
@@ -277,9 +311,8 @@ $$
 令 $\mathcal S$ 表示带 640 项 synthesis window 和跨时槽状态的 polyphase 合成算子：
 
 $$
-\mathbf y_{o,t}
-=
-\mathcal S\!\left(
+\mathbf y_{o,t}=
+\mathcal S\left(
 \mathbf R_{o,t},W,\mathbf s^{\mathrm S}_{o,t}
 \right).
 $$
@@ -287,9 +320,8 @@ $$
 对象输出为
 
 $$
-y_o[64t+r]
-=
-\operatorname{clip}\!\left(
+y_o[64t+r]=
+\mathrm{clip}\left(
 16\,\mathbf y_{o,t}[r],-1,1
 \right)G_{\mathrm{clip}},
 $$
@@ -301,9 +333,8 @@ $$
 LFE 不经过对象矩阵或 inverse QMF，而是使用 1217-sample 延迟。输入与输出端的比例因子抵消后：
 
 $$
-y_{\mathrm{LFE}}[n]
-=
-\operatorname{clip}\!\left(
+y_{\mathrm{LFE}}[n]=
+\mathrm{clip}\left(
 x_{\mathrm{LFE,core}}[n-1217],-1,1
 \right).
 $$
@@ -313,9 +344,8 @@ $$
 横向和纵向网格使用 $N=62$，高度网格使用 $N=15$。量化函数为
 
 $$
-q_N(k)
-=
-\min\!\left(
+q_N(k)=
+\min\left(
 32767,
 \left\lfloor\frac{32768k}{N}+\frac12\right\rfloor
 \right).
@@ -336,11 +366,11 @@ $$
 转换为 ADM 网格时：
 
 $$
-k_1=\operatorname{round}\!\left(\frac{62q_1}{32767}\right),
+k_1=\mathrm{round}\left(\frac{62q_1}{32767}\right),
 \quad
-k_2=\operatorname{round}\!\left(\frac{62q_2}{32767}\right),
+k_2=\mathrm{round}\left(\frac{62q_2}{32767}\right),
 \quad
-k_3=\operatorname{round}\!\left(\frac{15q_3}{32767}\right),
+k_3=\mathrm{round}\left(\frac{15q_3}{32767}\right),
 $$
 
 $$
@@ -404,17 +434,15 @@ $$
 二维点增益为
 
 $$
-\mathbf G_{\mathrm{2D}}(u,v)
-=
+\mathbf G_{\mathrm{2D}}(u,v)=
 \mathbf h(u)\odot\mathbf v(v).
 $$
 
 对于只有一对水平环绕、没有独立 side/rear 两对的 5.1 系列布局，纵向坐标使用
 
 $$
-v_{\mathrm{floor}}
-=
-\operatorname{clamp}(2v,0,1).
+v_{\mathrm{floor}}=
+\mathrm{clamp}(2v,0,1).
 $$
 
 其他布局使用 $v_{\mathrm{floor}}=v$。
@@ -424,8 +452,7 @@ $$
 三维布局分别计算地面层增益 $\mathbf G_f$ 和高度层增益 $\mathbf G_h$：
 
 $$
-\mathbf G_{\mathrm{point}}(u,v,w)
-=
+\mathbf G_{\mathrm{point}}(u,v,w)=
 \cos\left(\frac\pi2w\right)\mathbf G_f
 +
 \sin\left(\frac\pi2w\right)\mathbf G_h.
@@ -450,8 +477,7 @@ $$
 最大位置补偿为
 
 $$
-A_{\max}
-=
+A_{\max}=
 -\max\left(4.5-1.5H-3F,0\right)
 \quad\text{dB}.
 $$
@@ -459,15 +485,15 @@ $$
 前后与高度位置权重为
 
 $$
-p_v=\operatorname{clamp}\left(\frac v{0.6},0,1\right),
+p_v=\mathrm{clamp}\left(\frac v{0.6},0,1\right),
 $$
 
 $$
-p_w=\operatorname{clamp}\left(\frac{w-0.2}{0.8},0,1\right),
+p_w=\mathrm{clamp}\left(\frac{w-0.2}{0.8},0,1\right),
 $$
 
 $$
-p=\operatorname{clamp}(p_v+p_w,0,1).
+p=\mathrm{clamp}(p_v+p_w,0,1).
 $$
 
 线性补偿增益为
@@ -479,8 +505,7 @@ $$
 对象的目标增益向量为
 
 $$
-\mathbf G_{\mathrm{target}}
-=
+\mathbf G_{\mathrm{target}}=
 G_{\mathrm{object}}
 G_{\mathrm{pos}}
 \mathbf G_{\mathrm{point}}.
@@ -491,8 +516,7 @@ $$
 OAMD 更新的编码位置为
 
 $$
-s_{\mathrm{coded}}
-=
+s_{\mathrm{coded}}=
 s_{\mathrm{frame}}
 +s_{\mathrm{outer}}
 +s_{\mathrm{OAMD}}
@@ -502,16 +526,15 @@ $$
 decoder 输出 PCM timeline 上的理论更新位置为
 
 $$
-s_{\mathrm{theoretical}}
-=s_{\mathrm{coded}}+d_{\mathrm{decoder}},
+s_{\mathrm{theoretical}}=
+s_{\mathrm{coded}}+d_{\mathrm{decoder}},
 \qquad d_{\mathrm{decoder}}=1473.
 $$
 
 扬声器 renderer 保留现有的处理块长度 $B=32$，更新点对齐为
 
 $$
-\widehat s
-=
+\widehat s=
 B\left\lfloor
 \frac{s_{\mathrm{theoretical}}+B/2-1}{B}
 \right\rfloor.
@@ -522,8 +545,7 @@ $$
 给定 ramp duration $D$，block 数为
 
 $$
-K
-=
+K=
 \left\lfloor
 \frac{D+B/2-1}{B}
 \right\rfloor.
@@ -550,8 +572,7 @@ $$
 对目标输出声道 $c$：
 
 $$
-y_c[n]
-=
+y_c[n]=
 \delta_{c,\mathrm{LFE}}x_{\mathrm{LFE}}[n]
 +
 \sum_{o=1}^{15}x_o[n]g_{o,c}[n].
@@ -560,8 +581,7 @@ $$
 其中
 
 $$
-\delta_{c,\mathrm{LFE}}
-=
+\delta_{c,\mathrm{LFE}}=
 \begin{cases}
 1, & c\text{ 为目标布局的 LFE},\\
 0, & \text{其他声道}.
@@ -573,16 +593,15 @@ $$
 若输出 PCM24，量化关系为
 
 $$
-y_{24}[n]
-=
-\operatorname{trunc}\left(
-8388607\,\operatorname{clip}(y[n],-1,1)
+y_{24}[n]=
+\mathrm{trunc}\left(
+8388607\,\mathrm{clip}(y[n],-1,1)
 \right).
 $$
 
 ## 14. 公式适用范围
 
-- JOC 矩阵部分描述 dense JOC；Sparse JOC 使用不同的稀疏系数/索引路径。
+- JOC 矩阵部分同时描述 dense MTX 与 sparse IDX/VEC 两条差分语法。
 - 扬声器声像部分描述普通点对象；extent、spread、divergence 等模式需要额外模型。
 - 多个 OAMD position block 必须按其时间顺序调度。
 - limiter 属于独立后处理，不包含在上述混音公式中。

docs/native.en.md

@@ -42,7 +42,7 @@ int ejoc_renderer_process(
     float* output16_planar);       /* [16][1536] */
 ```
 
-Python performs dense-JOC Huffman decoding, differential reconstruction, and dequantization before the call. Sparse JOC is not silently passed to the dense native path.
+Python performs JOC Huffman decoding, differential reconstruction, and dequantization before the call, with the dense and sparse syntaxes sharing one entry point. The native core consumes the already dequantized `dq` in double precision, and both syntaxes have the same layout at that ABI.
 
 Thread control is exposed as:
 
@@ -116,7 +116,26 @@ Supported layouts:
 2.0  3.1  5.1  7.1  5.1.2  5.1.4  7.1.2  7.1.4  9.1.4  9.1.6
 ```
 
-## 6. Building
+## 6. Binaural-rendering ABI
+
+The shared library provides a 512-sample float64 binaural DSP interface:
+
+```c
+ejoc_binaural_renderer_handle ejoc_binaural_renderer_create(void);
+int ejoc_binaural_renderer_configure_kernels(...);
+int ejoc_binaural_renderer_configure_room(...);
+int ejoc_binaural_renderer_process(
+    ejoc_binaural_renderer_handle handle,
+    const double* input16_interleaved,   /* [512][16] */
+    const double* gains_complex,         /* [16][2][77][2] */
+    const double* room_sends,            /* [16] */
+    double output_gain,
+    double* output_stereo_interleaved);  /* [512][2] */
+```
+
+Python parses the model, evaluates the OAMD timeline, and supplies complex gains and room sends every 512 samples. The C++ handle owns QMF, hybrid, recursive-room, and QMF-synthesis state. Inputs, state, accumulation, and output are double/complex double.
+
+## 7. Building
 
 The CMake definition is `native/CMakeLists.txt`. Run from the repository root:
 
@@ -138,7 +157,7 @@ The MSVC configuration uses the static CRT. Other runtime dependencies depend on
 
 The repository does not include native binaries by default. A prebuilt Release runtime or a locally built runtime can be placed directly under `lib/`.
 
-## 7. Runtime lookup and fallback
+## 8. Runtime lookup and fallback
 
 Lookup order:
 
@@ -148,7 +167,7 @@ Lookup order:
 
 `--backend auto` falls back to NumPy when loading fails, and `--backend python` skips native discovery. The current CLI also prints the failure and falls back for `--backend native`; this existing behavior should not be read as successful native execution.
 
-## 8. Implementation boundaries
+## 9. Implementation boundaries
 
 - The native layer accepts only dense-JOC data already parsed by Python.
 - The ABI fixes a 1536-sample JOC frame, at most 15 objects, at most 23 parameter bands, and at most 2 data points.

docs/native.md

@@ -42,7 +42,7 @@ int ejoc_renderer_process(
     float* output16_planar);       /* [16][1536] */
 ```
 
-Dense JOC 的 Huffman 解码、差分还原和去量化先在 Python 中完成。Sparse JOC 不会被静默送入 dense 原生路径。
+JOC 的 Huffman 解码、差分还原和去量化先在 Python 中完成，dense 与 sparse 两条语法共用同一条入口。原生核心消费已去量化的 `dq`（double），两条语法在该 ABI 上布局一致。
 
 线程接口为：
 
@@ -116,7 +116,39 @@ int ejoc_speaker_renderer_process(
 2.0  3.1  5.1  7.1  5.1.2  5.1.4  7.1.2  7.1.4  9.1.4  9.1.6
 ```
 
-## 6. 构建
+## 6. 双耳渲染 ABI
+
+共享库提供 512-sample float64 双耳 DSP：
+
+```c
+ejoc_binaural_renderer_handle ejoc_binaural_renderer_create(void);
+int ejoc_binaural_renderer_configure_kernels(...);
+int ejoc_binaural_renderer_configure_room(...);
+int ejoc_binaural_renderer_process(
+    ejoc_binaural_renderer_handle handle,
+    const double* input16_interleaved,   /* [512][16] */
+    const double* gains_complex,         /* [16][2][77][2] */
+    const double* room_sends,            /* [16] */
+    double output_gain,
+    double* output_stereo_interleaved);  /* [512][2] */
+```
+
+Python 负责模型解析、OAMD 时间轴和每 512 samples 的 complex gains/room sends。C++ handle 保存 QMF、hybrid、递归 room 和 QMF synthesis 状态。全部输入、状态、乘加和输出均为 double/complex double。
+
+## 6.1 公开 SOFA 双耳渲染 ABI
+
+共享库同时提供完整的原生 SOFA 双耳渲染器（`ejoc_sofa_binaural_*`），它镜像
+Python `SofaBinauralBackend` 的全部数学：64-QMF/77-hybrid analysis/synthesis、
+五阶 ACN/N3D 实球谐方向场求值、whole-QMF-slot 逐对象 delay 历史、六面一阶
+image-source early reflections、共享 unitary FDN late room、LFE 120–180 Hz
+低通与 961-sample latency 语义。kernel 表、编译好的 HRTF 场与房间常数通过
+`configure_kernels/configure_field/configure_room` 一次上传；每 512-sample
+block 先 `set_source` 更新 16 个 source，再 `process` 输入 PCM；`process` 返回
+裁剪后的 stereo 样本数（首个 961 samples 被丢弃）。`finish` 以 64-sample 对齐的
+块排空尾音。Python 桥位于 `src/sofa_native_backend.py`，与 Python 参考实现逐值
+一致（差异 < 1e-9）；原生库缺失时 `main.py` 自动回退 Python。
+
+## 7. 构建
 
 CMake 定义位于 `native/CMakeLists.txt`。从仓库根目录运行：
 
@@ -138,7 +170,7 @@ MSVC 配置使用静态 CRT。其他运行时依赖由平台和工具链决定
 
 仓库默认不附带原生二进制。预构建的 Release 运行库或自行构建的运行库均可直接放入 `lib/`。
 
-## 7. 运行时查找与回退
+## 8. 运行时查找与回退
 
 查找顺序为：
 
@@ -148,7 +180,7 @@ MSVC 配置使用静态 CRT。其他运行时依赖由平台和工具链决定
 
 `--backend auto` 在加载失败时回退到 NumPy；`--backend python` 跳过原生探测。`--backend native` 当前也会打印失败原因后回退，这是现有 CLI 行为，不应理解为原生库已成功使用。
 
-## 8. 实现边界
+## 9. 实现边界
 
 - 原生层只接收 Python 已解析的 dense JOC 数据。
 - ABI 固定了 1536-sample JOC 帧、最多 15 个对象、最多 23 个参数带和最多 2 个数据点。

main.py

@@ -6,6 +6,7 @@ import math
 import os
 from pathlib import Path
 import platform
+import re
 import shutil
 import subprocess
 import sys
@@ -26,30 +27,140 @@ from metadata import DirectPayloadIndex, PayloadIndex, write_summary
 import oamd_tracks
 from renderer import JocRenderer
 from native_renderer import NativeBackendUnavailable, NativeJocRenderer
+from binaural_renderer import (
+    DEFAULT_SOFA_HRTF,
+    SofaBinauralRenderer,
+    resolve_compiled_hrtf_cache,
+    resolve_sofa_hrtf,
+)
+from rosella_binaural_renderer import (
+    DEFAULT_PERSONALIZED_HEADPHONE,
+    ROSSELLA_BLOCK_SAMPLES,
+    ROSSELLA_LATENCY_SAMPLES,
+    RosellaBinauralRenderer,
+    resolve_personalized_headphone,
+)
+from sofa_hrtf_field import DEFAULT_HRTF_CACHE_DIR
 from speaker_backend import create_speaker_renderer
 from speaker_layouts import (SPEAKER_LAYOUT_CHOICES, get_speaker_layout,
                              speaker_layout_display_name)
-from speaker_wav import SpeakerPcmSpool, write_speaker_wav
+from speaker_wav import BinauralPcmSpool, SpeakerPcmSpool, write_pcm_wav
 from variant_error import UnsupportedVariantError, write_variant_report
 
 
 RATE = 48000
 FRAME_SAMPLES = 1536
 DEFAULT_OUTPUT_DIR = PROJECT_DIR / "output"
+EAC3_DRC_SCALE_MAX = 6.0
+EAC3_TARGET_LEVEL_RANGE = (-31, 0)
+EAC3_DECODER_OPTION_RE = re.compile(r"(?m)^\s*-([A-Za-z0-9_]+)\s+<")
 
 
-def resolve_output(source, requested=None, speaker_layout=None):
+def resolve_output(source, requested=None, speaker_layout=None, *, binaural=False):
     """解析成品路径；未指定时使用项目内的 ``output`` 目录。"""
     source = Path(source)
     if requested is not None:
         target = Path(requested)
     elif speaker_layout is not None:
         target = DEFAULT_OUTPUT_DIR / f"{source.stem}.{speaker_layout}.wav"
+    elif binaural:
+        target = DEFAULT_OUTPUT_DIR / f"{source.stem}.binaural.wav"
     else:
         target = DEFAULT_OUTPUT_DIR / (source.stem + ".adm.wav")
     return target.expanduser().resolve()
 
 
+def _find_default_compiled_hrtf_cache():
+    """在默认 cache 目录寻找唯一的 .jochrtf；无文件返回 None，多个则报错。"""
+    directory = DEFAULT_HRTF_CACHE_DIR
+    if not directory.is_dir():
+        return None
+    candidates = sorted(directory.glob("*.jochrtf"))
+    if not candidates:
+        return None
+    if len(candidates) > 1:
+        listing = ", ".join(path.name for path in candidates[:8])
+        raise ValueError(
+            f"{directory} 下有多个 .jochrtf 缓存（{listing}…），无法自动选择；"
+            "请用 --compiled-hrtf-cache PATH 或 --sofa-hrtf PATH 显式指定")
+    return candidates[0]
+
+
+def resolve_binaural_hrtf_input(args, *, required):
+    """解析 binaural 的 HRTF 输入。
+
+    无显式输入时按顺序回退：默认 HRTF/binaural.sofa → 默认 cache 目录下唯一的
+    .jochrtf → 默认 HRTF/binaural.personalized_headphone → 报错。
+    只校验路径，不做编译。
+    """
+    sofa = args.sofa_hrtf
+    compiled = args.compiled_hrtf_cache
+    private = args.personalized_headphone
+    cache_policy = args.hrtf_cache_policy
+    cache_dir = args.hrtf_cache_dir
+    radius = args.hrtf_radius_m
+
+    if compiled is not None and cache_policy is not None:
+        raise ValueError("显式 .jochrtf 输入不能再指定 --hrtf-cache-policy")
+    if compiled is not None and radius != 1.0:
+        raise ValueError("显式 .jochrtf 输入不能再选择 SOFA radius shell")
+    if private is not None and (cache_policy is not None or cache_dir is not None
+                                or radius != 1.0):
+        raise ValueError(
+            "Rosella 模型输入不能使用 "
+            "--hrtf-cache-policy/--hrtf-cache-dir/--hrtf-radius-m")
+
+    if required and sofa is None and compiled is None and private is None:
+        if DEFAULT_SOFA_HRTF.is_file():
+            sofa = DEFAULT_SOFA_HRTF
+        else:
+            compiled = _find_default_compiled_hrtf_cache()
+            if compiled is None and DEFAULT_PERSONALIZED_HEADPHONE.is_file():
+                private = DEFAULT_PERSONALIZED_HEADPHONE
+
+    if sofa is None and compiled is None and private is None:
+        if cache_policy is not None or cache_dir is not None or radius != 1.0:
+            raise ValueError("HRTF cache/radius 选项需要 --sofa-hrtf")
+        if required:
+            raise ValueError(
+                "--binaural 未找到 HRTF 输入：默认 "
+                f"{DEFAULT_SOFA_HRTF}、{DEFAULT_PERSONALIZED_HEADPHONE} 与 "
+                f"{DEFAULT_HRTF_CACHE_DIR} 下的 .jochrtf 缓存都不存在；请用 "
+                "--sofa-hrtf PATH、--compiled-hrtf-cache PATH 或 "
+                "--personalized-headphone PATH 指定")
+        return None
+
+    if sofa is None and (cache_policy is not None or cache_dir is not None
+                         or radius != 1.0):
+        raise ValueError("HRTF cache/radius 选项需要 --sofa-hrtf")
+    effective_policy = "memory" if cache_policy is None else cache_policy
+    if cache_dir is not None and (sofa is None or effective_policy != "disk"):
+        raise ValueError("--hrtf-cache-dir 仅与 SOFA 的 disk cache policy 一起使用")
+    if sofa is not None:
+        return {
+            "kind": "sofa",
+            "path": resolve_sofa_hrtf(sofa),
+            "cache_policy": effective_policy,
+            "cache_dir": (DEFAULT_HRTF_CACHE_DIR if cache_dir is None else
+                          cache_dir.expanduser().resolve()),
+        }
+    if compiled is not None:
+        return {
+            "kind": "compiled_cache",
+            "path": resolve_compiled_hrtf_cache(compiled),
+            "cache_policy": None,
+            "cache_dir": None,
+        }
+    if private is not None:
+        return {
+            "kind": "rosella",
+            "path": resolve_personalized_headphone(private),
+            "cache_policy": None,
+            "cache_dir": None,
+        }
+    return None
+
+
 def executable(value, name):
     path = shutil.which(value) if value else None
     if path is None and value and Path(value).is_file():
@@ -76,6 +187,53 @@ def timed_call(timings, name, function, *args, **kwargs):
         timings[name] = time.perf_counter() - started
 
 
+def probe_eac3_decoder_options(ffmpeg):
+    """读取 ``ffmpeg -h decoder=eac3`` 暴露的 AVOption 名。"""
+    result = subprocess.run(
+        [ffmpeg, "-hide_banner", "-h", "decoder=eac3"],
+        stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+        text=True, encoding="utf-8", errors="replace")
+    options = frozenset(EAC3_DECODER_OPTION_RE.findall(result.stdout or ""))
+    # decoder 名不存在时 ffmpeg 依然返回 0，因此以“解析不到任何选项”为失败。
+    if not options:
+        raise RuntimeError(
+            "无法读取 FFmpeg 的 eac3 解码器选项（ffmpeg -h decoder=eac3）；"
+            "需要带 E-AC-3 解码器的构建")
+    return options
+
+
+def ffmpeg_version(ffmpeg):
+    """FFmpeg 版本字符串；探测失败返回空串，不影响渲染。"""
+    try:
+        result = subprocess.run(
+            [ffmpeg, "-hide_banner", "-version"],
+            stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+            text=True, encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+    lines = (result.stdout or "").splitlines()
+    line = lines[0].strip() if lines else ""
+    prefix = "ffmpeg version "
+    return line[len(prefix):].strip() if line.startswith(prefix) else line
+
+
+def eac3_decode_options(drc_scale, target_level, available):
+    """构造 ``-i`` 之前的 E-AC-3 解码选项，返回 ``(argv, report 片段)``。"""
+    if "drc_scale" not in available:
+        raise RuntimeError(
+            "FFmpeg 的 eac3 解码器缺少 -drc_scale，无法关闭码流 DRC")
+    # -drc_scale 始终显式下发：0（全动态范围）不是 ffmpeg 的默认值。
+    argv = ["-drc_scale", format(float(drc_scale), ".10g")]
+    if target_level:
+        if "target_level" not in available:
+            raise RuntimeError(
+                "FFmpeg 的 eac3 解码器不支持 -target_level；请升级 FFmpeg "
+                "或去掉 --eac3-target-level")
+        argv += ["-target_level", str(int(target_level))]
+    applied = {"drc_scale": float(drc_scale), "target_level": int(target_level)}
+    return argv, applied
+
+
 def extract_eac3(ffmpeg, source, target):
     if source.suffix.lower() in (".eac3", ".ec3"):
         return source
@@ -85,10 +243,10 @@ def extract_eac3(ffmpeg, source, target):
     return target
 
 
-def decode_core(ffmpeg, eac3, target, duration_sec=None):
+def decode_core(ffmpeg, eac3, target, duration_sec=None, *, options=()):
     # 5.1(side) 的 f32le 顺序为 FL FR FC LFE SL SR；JOC 使用其中 0,1,2,4,5。
-    command = [ffmpeg, "-hide_banner", "-loglevel", "error", "-y", "-i", str(eac3),
-               "-map", "0:a:0", "-vn"]
+    command = [ffmpeg, "-hide_banner", "-loglevel", "error", "-y", *options,
+               "-i", str(eac3), "-map", "0:a:0", "-vn"]
     if duration_sec is not None:
         command.extend(["-t", f"{duration_sec:.9f}"])
     command.extend(["-ac", "6", "-ar", str(RATE),
@@ -105,8 +263,8 @@ def sha256(path):
     return digest.hexdigest()
 
 
-def choose_speaker_output_format(requested_format, clip_action, peak, clipped_values,
-                                 *, input_func=input, interactive=None):
+def choose_pcm_output_format(requested_format, clip_action, peak, clipped_values,
+                             *, input_func=input, interactive=None):
     """Resolve int24 clipping interactively or through an explicit policy."""
     if requested_format != "int24" or clipped_values == 0:
         return requested_format
@@ -146,6 +304,10 @@ def choose_speaker_output_format(requested_format, clip_action, peak, clipped_va
     raise ValueError(f"未知 clip action: {action}")
 
 
+# Backward-compatible public name used by existing tests and callers.
+choose_speaker_output_format = choose_pcm_output_format
+
+
 def resolve_metadata(args, eac3, temp_dir):
     if args.metadata_dir:
         directory = Path(args.metadata_dir).resolve()
@@ -198,7 +360,9 @@ def create_renderer(backend, gain, native_library=None, native_threads=None):
 
 def render(index, bed_path, frame_count, raw_path, gain, progress_every,
            backend="auto", native_library=None, native_threads=None, frame_sink=None,
-           speaker_renderer=None, speaker_sink=None, speaker_metadata_offset=1473):
+           speaker_renderer=None, speaker_sink=None, speaker_metadata_offset=1473,
+           binaural_renderer=None, binaural_sink=None, binaural_metadata_offset=1473,
+           raw_scale=1.0):
     values = np.memmap(bed_path, dtype=np.float32, mode="r")
     frame_width = FRAME_SAMPLES * 6
     if values.size % frame_width:
@@ -216,6 +380,9 @@ def render(index, bed_path, frame_count, raw_path, gain, progress_every,
     raw_write_seconds = 0.0
     speaker_render_seconds = 0.0
     speaker_write_seconds = 0.0
+    binaural_render_seconds = 0.0
+    binaural_write_seconds = 0.0
+    elapsed = 0.0
     try:
         for frame_number, row in enumerate(index.rows[:frame_count]):
             bed6 = np.asarray(bed[frame_number], dtype=np.float32)
@@ -226,7 +393,8 @@ def render(index, bed_path, frame_count, raw_path, gain, progress_every,
             dsp_seconds += time.perf_counter() - stage
             if output is not None:
                 stage = time.perf_counter()
-                output[frame_number] = pcm16.T
+                output[frame_number] = np.multiply(
+                    pcm16.T, np.float32(raw_scale), dtype=np.float32)
                 raw_write_seconds += time.perf_counter() - stage
             if frame_sink is not None:
                 stage = time.perf_counter()
@@ -240,6 +408,22 @@ def render(index, bed_path, frame_count, raw_path, gain, progress_every,
                 stage = time.perf_counter()
                 speaker_sink.write_frame(speaker_pcm)
                 speaker_write_seconds += time.perf_counter() - stage
+            if binaural_renderer is not None:
+                payload = subs.get(11)
+                outer_offset = (
+                    index.subpayload_sample_offset(row, 11)
+                    if payload is not None and hasattr(index, "subpayload_sample_offset")
+                    else 0
+                )
+                stage = time.perf_counter()
+                binaural_pcm = binaural_renderer.render_frame(
+                    pcm16.T, payload, binaural_metadata_offset,
+                    outer_sample_offset=outer_offset)
+                binaural_render_seconds += time.perf_counter() - stage
+                if len(binaural_pcm):
+                    stage = time.perf_counter()
+                    binaural_sink.write_frame(binaural_pcm)
+                    binaural_write_seconds += time.perf_counter() - stage
             done = frame_number + 1
             if done % progress_every == 0 or done == frame_count:
                 elapsed = time.perf_counter() - started
@@ -247,6 +431,14 @@ def render(index, bed_path, frame_count, raw_path, gain, progress_every,
                 eta = (frame_count - done) / max(speed, 1e-9)
                 print(f"[JOC:{backend_info['name']}] {done}/{frame_count}  "
                       f"{speed:.1f} frame/s  ETA {eta:.1f}s", flush=True)
+        if binaural_renderer is not None:
+            stage = time.perf_counter()
+            binaural_tail = binaural_renderer.finish()
+            binaural_render_seconds += time.perf_counter() - stage
+            if len(binaural_tail):
+                stage = time.perf_counter()
+                binaural_sink.write_frame(binaural_tail)
+                binaural_write_seconds += time.perf_counter() - stage
         if output is not None:
             output.flush()
         elapsed = time.perf_counter() - started
@@ -257,6 +449,9 @@ def render(index, bed_path, frame_count, raw_path, gain, progress_every,
         close = getattr(speaker_renderer, "close", None)
         if close is not None:
             close()
+        close = getattr(binaural_renderer, "close", None)
+        if close is not None:
+            close()
     breakdown = {
         "pipeline_wall_seconds": elapsed,
         "dsp_and_joc_parse_seconds": dsp_seconds,
@@ -264,41 +459,86 @@ def render(index, bed_path, frame_count, raw_path, gain, progress_every,
         "raw_float_write_seconds": raw_write_seconds,
         "speaker_render_seconds": speaker_render_seconds,
         "speaker_spool_write_seconds": speaker_write_seconds,
+        "binaural_render_seconds": binaural_render_seconds,
+        "binaural_spool_write_seconds": binaural_write_seconds,
     }
     return dsp_seconds, backend_info, breakdown
 
 
 def build_parser():
     parser = argparse.ArgumentParser(
-        description="JustOneCacophony (JOC)：E-AC-3 JOC → 25ch ADM BWF 或扬声器 WAV")
+        description=("JustOneCacophony (JOC)：E-AC-3 JOC → 25ch ADM BWF、"
+                     "扬声器 WAV 或公开 SOFA 双耳 WAV"))
     parser.add_argument("input", type=Path, help="输入 .m4a/.eac3/.ec3")
     parser.add_argument("-o", "--output", type=Path, help="输出文件；默认按模式和布局命名")
     parser.add_argument("--speaker-output", type=Path,
                         help="扬声器 WAV 路径；仅与 --speaker-layout 一起使用")
-    parser.add_argument("--speaker-layout", choices=SPEAKER_LAYOUT_CHOICES,
-                        help="直接扬声器渲染布局，例如 2.0、5.1、7.1.2")
+    parser.add_argument("--binaural-output", type=Path,
+                        help="双耳 WAV 路径；仅与 --binaural 一起使用")
+    direct_mode = parser.add_mutually_exclusive_group()
+    direct_mode.add_argument("--speaker-layout", choices=SPEAKER_LAYOUT_CHOICES,
+                             help="直接扬声器渲染布局，例如 2.0、5.1、7.1.2")
+    direct_mode.add_argument("--binaural", action="store_true",
+                             help="直接 SOFA 双耳渲染；不生成临时 ADM BWF")
     parser.add_argument("--speaker-format", choices=("float32", "int24"), default="float32",
                         help="扬声器 WAV 格式，默认 float32")
+    parser.add_argument("--binaural-format", choices=("float32", "int24"), default="float32",
+                        help="双耳 WAV 格式，默认 float32")
     parser.add_argument("--clip-action", choices=("ask", "continue", "float32", "abort"),
                         default="ask",
                         help="int24 削波处理：交互询问、继续截断、改 float32 或中止")
     parser.add_argument("--speaker-metadata-offset", type=int, default=1473,
                         help="扬声器渲染 metadata 相对帧偏移，默认 1473 samples")
+    parser.add_argument("--binaural-mode", choices=("off", "near", "mid", "far"),
+                        default="mid",
+                        help="双耳渲染模式，默认 mid（人为指定的渲染提示，非码流 "
+                             "原始元数据）；直接双耳渲染与 ADM BWF 的 DBMD 提示共用。"
+                             "off 仅用于 ADM BWF：关闭 DBMD 双耳提示（编码 0）")
+    hrtf_input = parser.add_mutually_exclusive_group()
+    hrtf_input.add_argument(
+        "--sofa-hrtf", type=Path,
+        help="SimpleFreeFieldHRIR SOFA；缺省时依次尝试 HRTF/binaural.sofa、"
+             "output/hrtf-cache 下唯一的 .jochrtf、"
+             "HRTF/binaural.personalized_headphone，均无则报错")
+    hrtf_input.add_argument(
+        "--compiled-hrtf-cache", type=Path,
+        help="高级入口：显式读取 JOC .jochrtf compiled cache")
+    hrtf_input.add_argument(
+        "--personalized-headphone", type=Path, nargs="?",
+        const=DEFAULT_PERSONALIZED_HEADPHONE,
+        help="Rosella .personalized_headphone 模型；不带路径时默认 "
+             "HRTF/binaural.personalized_headphone")
+    parser.add_argument(
+        "--hrtf-cache-policy", choices=("none", "memory", "disk"), default=None,
+        help="SOFA 编译缓存；默认 memory，disk 写入可删除的 .jochrtf")
+    parser.add_argument(
+        "--hrtf-cache-dir", type=Path,
+        help="disk cache 目录；默认 output/hrtf-cache")
+    parser.add_argument(
+        "--hrtf-radius-m", type=float, default=1.0,
+        help="选择最近的 SOFA measurement-radius shell，默认 1.0 m")
+    parser.add_argument("--binaural-tail-seconds", type=float, default=5.0,
+                        help="双耳 room/filterbank flush 上限，默认 5 秒")
+    parser.add_argument("--binaural-tail-threshold", type=float, default=1.0e-8,
+                        help="双耳尾声裁切阈值，默认 1e-8；主体至少保留原时长")
+    parser.add_argument("--binaural-chunk-frames", type=int, default=64,
+                        help="双耳内部批处理 E-AC-3 帧数，默认 64")
     parser.add_argument("--gain-db", type=float, default=0.0,
-                        help="成品增益 dB，默认 0（float32 系数 1.0）")
+                        help="成品增益 dB，默认 0；双耳路径以 float64 应用")
     parser.add_argument("--duration", type=float, help="只处理开头指定秒数")
     parser.add_argument("--object-delay-samples", type=int, default=1473,
-                        help="可选的对象 PCM/OAMD 时间补偿，默认 1473 samples")
-    parser.add_argument(
-        "--joc-binaural-mode", choices=tuple(adm_atmos.JOC_BINAURAL_MODES),
-        default=adm_atmos.JOC_BINAURAL_MODE_DEFAULT,
-        help="实验性 ADM DBMD JOC 对象双耳模式：off=0、near=1、far=2、mid=3、"
-             "unspecified=4（默认）；不改变 PCM 或直接扬声器渲染")
+                        help="对象 PCM/OAMD 时间补偿；ADM 与双耳默认 1473 samples")
     parser.add_argument("--trajectory-mode", choices=("compact", "dense64"), default="compact",
-                        help="对象轨迹表示；compact 用长线性插值压缩 AXML，dense64 保留逐 64-sample 块")
+                        help="ADM 对象轨迹表示；直接双耳路径不序列化 AXML")
     parser.add_argument("--ffmpeg", default=os.environ.get("FFMPEG", "ffmpeg"))
+    parser.add_argument("--eac3-drc-scale", type=float, default=0.0,
+                        help="E-AC-3 解码器 -drc_scale：0=关闭码流 dynrng（全动态范围），"
+                             "1=码流作者意图，>1 非对称；默认 0")
+    parser.add_argument("--eac3-target-level", type=int, default=0,
+                        help="E-AC-3 解码器 -target_level：按码流 dialnorm 归一化电平，"
+                             "增益约 target_level - dialnorm dB；0=不施加，默认 0")
     parser.add_argument("--backend", choices=("auto", "native", "python"), default="auto",
-                        help="DSP 后端；auto 优先 C++，不可用时回退 Python")
+                        help="JOC/扬声器 DSP 后端；SOFA 双耳 DSP 当前使用 Python")
     parser.add_argument("--native-library", type=Path,
                         help="显式指定原生库；默认从单层 lib 目录选择当前平台文件")
     parser.add_argument("--native-threads", type=int,
@@ -332,25 +572,81 @@ def main(argv=None):
     if not source.is_file():
         raise FileNotFoundError(source)
     speaker_mode = args.speaker_layout is not None
+    binaural_mode = bool(args.binaural)
+    binaural_render_mode = args.binaural_mode
+    if binaural_mode and binaural_render_mode == "off":
+        raise ValueError(
+            "--binaural-mode off 仅用于 ADM BWF 输出（关闭 DBMD 双耳提示）；"
+            "直接双耳渲染请使用 near/mid/far")
     if args.speaker_output is not None and not speaker_mode:
         raise ValueError("--speaker-output 必须与 --speaker-layout 一起使用")
-    if args.output is not None and args.speaker_output is not None:
-        raise ValueError("-o/--output 与 --speaker-output 不能同时使用")
+    if args.binaural_output is not None and not binaural_mode:
+        raise ValueError("--binaural-output 必须与 --binaural 一起使用")
+    specific_outputs = [value for value in (args.speaker_output, args.binaural_output)
+                        if value is not None]
+    if args.output is not None and specific_outputs:
+        raise ValueError("-o/--output 与 --speaker-output/--binaural-output 不能同时使用")
+    if len(specific_outputs) > 1:
+        raise ValueError("--speaker-output 与 --binaural-output 不能同时使用")
     if args.speaker_metadata_offset < 0:
         raise ValueError("speaker-metadata-offset 不能为负数")
+    hrtf_options_used = any((
+        args.sofa_hrtf is not None,
+        args.compiled_hrtf_cache is not None,
+        args.personalized_headphone is not None,
+        args.hrtf_cache_policy is not None,
+        args.hrtf_cache_dir is not None,
+        args.hrtf_radius_m != 1.0,
+    ))
+    if hrtf_options_used and not binaural_mode:
+        raise ValueError("SOFA/HRTF 选项仅与 --binaural 一起使用")
+    if (not math.isfinite(args.binaural_tail_seconds)
+            or args.binaural_tail_seconds < 0):
+        raise ValueError("binaural-tail-seconds 必须是非负有限值")
+    if (not math.isfinite(args.binaural_tail_threshold)
+            or args.binaural_tail_threshold < 0):
+        raise ValueError("binaural-tail-threshold 必须是非负有限值")
+    if args.binaural_chunk_frames <= 0:
+        raise ValueError("binaural-chunk-frames 必须大于 0")
+    if not math.isfinite(args.hrtf_radius_m) or args.hrtf_radius_m <= 0.0:
+        raise ValueError("hrtf-radius-m 必须是正有限值")
     requested_output = (args.speaker_output if args.speaker_output is not None
+                        else args.binaural_output if args.binaural_output is not None
                         else args.output)
     output = resolve_output(
-        source, requested_output, args.speaker_layout if speaker_mode else None)
+        source, requested_output, args.speaker_layout if speaker_mode else None,
+        binaural=binaural_mode)
     output.parent.mkdir(parents=True, exist_ok=True)
     if args.duration is not None and args.duration <= 0:
         raise ValueError("duration 必须大于 0")
     if args.object_delay_samples < 0:
         raise ValueError("object-delay-samples 不能为负数")
-    gain = np.float32(10.0 ** (args.gain_db / 20.0))
-    if not np.isfinite(gain):
-        raise ValueError("gain-db 超出 float32 范围")
+    gain_float64 = 10.0 ** (args.gain_db / 20.0)
+    gain = np.float32(gain_float64)
+    if not math.isfinite(gain_float64) or not np.isfinite(gain):
+        raise ValueError("gain-db 超出支持范围")
+    if (not math.isfinite(args.eac3_drc_scale)
+            or not 0.0 <= args.eac3_drc_scale <= EAC3_DRC_SCALE_MAX):
+        raise ValueError(f"eac3-drc-scale 必须在 0..{EAC3_DRC_SCALE_MAX:g} 之间")
+    if not (EAC3_TARGET_LEVEL_RANGE[0] <= args.eac3_target_level
+            <= EAC3_TARGET_LEVEL_RANGE[1]):
+        raise ValueError("eac3-target-level 必须在 -31..0 之间")
+    binaural_hrtf_input = resolve_binaural_hrtf_input(
+        args, required=binaural_mode and not args.metadata_only)
     ffmpeg = executable(args.ffmpeg, "FFmpeg")
+    decode_options = ()
+    decode_option_info = None
+    if not args.metadata_only:
+        available = probe_eac3_decoder_options(ffmpeg)
+        decode_options, applied = eac3_decode_options(
+            args.eac3_drc_scale, args.eac3_target_level, available)
+        decode_option_info = {
+            "version": ffmpeg_version(ffmpeg),
+            "eac3_decode_options": applied,
+        }
+        print(f"[decode] ffmpeg {decode_option_info['version']}  "
+              f"drc_scale={args.eac3_drc_scale:g}  "
+              f"target_level={args.eac3_target_level}", flush=True)
 
     total_started = time.perf_counter()
     timings = {}
@@ -386,7 +682,8 @@ def main(argv=None):
 
         bed_path = timed_call(
             timings, "decode_core", decode_core,
-            ffmpeg, eac3, temp_dir / "core51_f32le.raw", duration_sec)
+            ffmpeg, eac3, temp_dir / "core51_f32le.raw", duration_sec,
+            options=decode_options)
         raw_path = (output.with_name(output.name + ".objects16.f32le")
                     if args.keep_raw else None)
         master = None
@@ -394,7 +691,13 @@ def main(argv=None):
         speaker_wav_info = None
         speaker_clip_info = None
         speaker_actual_format = None
+        binaural_backend_info = None
+        binaural_hrtf_report = None
+        binaural_wav_info = None
+        binaural_clip_info = None
+        binaural_actual_format = None
         if speaker_mode:
+            timings["create_binaural_renderer"] = 0.0
             layout = get_speaker_layout(args.speaker_layout)
             speaker_name = speaker_layout_display_name(layout)
             speaker_decoder, speaker_backend_info = create_speaker_renderer(
@@ -416,11 +719,11 @@ def main(argv=None):
                     args.native_threads, None, speaker_decoder, spool,
                     args.speaker_metadata_offset)
                 spool.finalize()
-                speaker_actual_format = choose_speaker_output_format(
+                speaker_actual_format = choose_pcm_output_format(
                     args.speaker_format, args.clip_action, spool.peak,
                     spool.clipped_values)
                 speaker_wav_info = timed_call(
-                    timings, "write_speaker_wav", write_speaker_wav,
+                    timings, "write_speaker_wav", write_pcm_wav,
                     output, spool.values, speaker_actual_format, rate=RATE)
                 speaker_clip_info = {
                     "peak": spool.peak,
@@ -436,10 +739,158 @@ def main(argv=None):
             timings["validate_adm"] = 0.0
             info = (f"speaker layout={speaker_name}, format={speaker_actual_format}, "
                     f"peak={speaker_clip_info['peak']:.9g}")
+        elif binaural_mode:
+            hrtf_source = binaural_hrtf_input
+            common_options = {
+                "mode": binaural_render_mode,
+                "object_delay_samples": args.object_delay_samples,
+                "tail_seconds": args.binaural_tail_seconds,
+                "output_gain": gain_float64,
+                "chunk_frames": args.binaural_chunk_frames,
+            }
+            if hrtf_source["kind"] == "sofa":
+                binaural_decoder = None
+                if args.backend in ("auto", "native"):
+                    try:
+                        from sofa_native_backend import create_native_sofa_renderer
+                        binaural_decoder = timed_call(
+                            timings, "create_binaural_renderer",
+                            create_native_sofa_renderer,
+                            hrtf_source["path"],
+                            cache_policy=hrtf_source["cache_policy"],
+                            cache_dir=hrtf_source["cache_dir"],
+                            shell_radius_m=args.hrtf_radius_m,
+                            **common_options)
+                    except (ImportError, OSError, RuntimeError, ValueError) as exc:
+                        print(
+                            f"[binaural] native SOFA backend unavailable "
+                            f"({exc.__class__.__name__}: {exc}); "
+                            f"falling back to Python", flush=True)
+                        binaural_decoder = None
+                if binaural_decoder is None:
+                    binaural_decoder = timed_call(
+                        timings, "create_binaural_renderer",
+                        SofaBinauralRenderer.from_sofa,
+                        hrtf_source["path"],
+                        cache_policy=hrtf_source["cache_policy"],
+                        cache_dir=hrtf_source["cache_dir"],
+                        shell_radius_m=args.hrtf_radius_m,
+                        **common_options)
+            elif hrtf_source["kind"] == "rosella":
+                binaural_decoder = timed_call(
+                    timings, "create_binaural_renderer",
+                    RosellaBinauralRenderer,
+                    hrtf_source["path"],
+                    mode=binaural_render_mode,
+                    object_delay_samples=args.object_delay_samples,
+                    tail_seconds=args.binaural_tail_seconds,
+                    output_gain=gain_float64,
+                    chunk_frames=args.binaural_chunk_frames,
+                    backend=args.backend,
+                    native_library=args.native_library)
+            else:
+                binaural_decoder = None
+                if args.backend in ("auto", "native"):
+                    try:
+                        from sofa_native_backend import (
+                            create_native_compiled_cache_renderer)
+                        binaural_decoder = timed_call(
+                            timings, "create_binaural_renderer",
+                            create_native_compiled_cache_renderer,
+                            hrtf_source["path"],
+                            **common_options)
+                    except (ImportError, OSError, RuntimeError, ValueError) as exc:
+                        print(
+                            f"[binaural] native SOFA backend unavailable "
+                            f"({exc.__class__.__name__}: {exc}); "
+                            f"falling back to Python", flush=True)
+                        binaural_decoder = None
+                if binaural_decoder is None:
+                    binaural_decoder = timed_call(
+                        timings, "create_binaural_renderer",
+                        SofaBinauralRenderer.from_compiled_cache,
+                        hrtf_source["path"],
+                        **common_options)
+            print(
+                f"[binaural] mode={binaural_render_mode} "
+                f"backend={binaural_decoder.dsp_backend} "
+                f"precision=float64/complex128 "
+                f"hrtf={hrtf_source['kind']}:{hrtf_source['path']}", flush=True)
+            if hrtf_source["kind"] == "rosella":
+                flush_samples = math.ceil(
+                    (args.binaural_tail_seconds * RATE
+                     + ROSSELLA_LATENCY_SAMPLES + ROSSELLA_BLOCK_SAMPLES)
+                    / ROSSELLA_BLOCK_SAMPLES) * ROSSELLA_BLOCK_SAMPLES
+                spool_capacity = frame_count * FRAME_SAMPLES + flush_samples
+            else:
+                spool_capacity = (
+                    frame_count * FRAME_SAMPLES
+                    + binaural_decoder.finish_capacity_samples)
+            spool = BinauralPcmSpool(
+                temp_dir / "binaural_interleaved_f64.raw",
+                spool_capacity,
+                tail_threshold=args.binaural_tail_threshold)
+            try:
+                render_seconds, renderer_backend, render_breakdown = timed_call(
+                    timings, "render_and_stream", variant_call,
+                    output, source, render, index, bed_path, frame_count, raw_path,
+                    np.float32(1.0), max(1, args.progress_every),
+                    backend=args.backend, native_library=args.native_library,
+                    native_threads=args.native_threads,
+                    binaural_renderer=binaural_decoder, binaural_sink=spool,
+                    binaural_metadata_offset=args.object_delay_samples, raw_scale=gain)
+                spool.finalize(minimum_samples=frame_count * FRAME_SAMPLES)
+                binaural_actual_format = choose_pcm_output_format(
+                    args.binaural_format, args.clip_action, spool.peak,
+                    spool.clipped_values)
+                binaural_wav_info = timed_call(
+                    timings, "write_binaural_wav", write_pcm_wav,
+                    output, spool.values, binaural_actual_format, rate=RATE)
+                binaural_clip_info = {
+                    "peak": spool.peak,
+                    "over_unity_values": spool.clipped_values,
+                    "requested_format": args.binaural_format,
+                    "actual_format": binaural_actual_format,
+                    "clip_action": args.clip_action,
+                    "tail_threshold": args.binaural_tail_threshold,
+                    "source_samples": frame_count * FRAME_SAMPLES,
+                    "kept_samples": spool.sample_count,
+                }
+                binaural_backend_info = binaural_decoder.backend_info
+                if hrtf_source["kind"] == "rosella":
+                    binaural_hrtf_report = {
+                        "input_kind": "rosella",
+                        "input_path": str(binaural_decoder.model_path.resolve()),
+                        "model_coefficient_sha256": (
+                            binaural_decoder.model.coefficient_sha256),
+                        "cache_policy": None,
+                    }
+                else:
+                    binaural_hrtf_report = {
+                        "input_kind": binaural_backend_info["hrtf_input_kind"],
+                        "input_path": binaural_backend_info["hrtf_input_path"],
+                        "source_sha256": (
+                            binaural_backend_info["field"]["source_sha256"]),
+                        "cache_policy": binaural_backend_info["cache_policy"],
+                        "cache_key": (
+                            binaural_backend_info["field"]["cache_key"]),
+                        "format_version": (
+                            binaural_backend_info["field"]["format_version"]),
+                    }
+            finally:
+                spool.close()
+            timings["build_adm_tracks"] = 0.0
+            timings["finalize_adm"] = 0.0
+            timings["validate_adm"] = 0.0
+            info = (f"binaural mode={binaural_render_mode}, "
+                    f"format={binaural_actual_format}, "
+                    f"peak={binaural_clip_info['peak']:.9g}, "
+                    f"samples={binaural_clip_info['kept_samples']}")
         else:
+            timings["create_binaural_renderer"] = 0.0
             master = adm_assemble.StreamingMaster(
                 output, duration_sec, rate=RATE,
-                joc_binaural_mode=adm_atmos.JOC_BINAURAL_MODES[args.joc_binaural_mode])
+                joc_binaural_mode=adm_atmos.JOC_BINAURAL_MODES[args.binaural_mode])
             try:
                 render_seconds, renderer_backend, render_breakdown = timed_call(
                     timings, "render_and_stream", variant_call,
@@ -469,10 +920,11 @@ def main(argv=None):
     else:
         output_sha = timed_call(timings, "sha256", sha256, output)
     total_seconds = time.perf_counter() - total_started
+    mode_name = "speaker" if speaker_mode else "binaural" if binaural_mode else "adm"
     report = {
         "input": str(source),
         "output": str(output),
-        "mode": "speaker" if speaker_mode else "adm",
+        "mode": mode_name,
         "metadata": str(metadata_json) if metadata_json is not None else None,
         "metadata_backend": metadata_backend,
         "metadata_cache": str(metadata_cache_dir) if metadata_cache_dir is not None else None,
@@ -480,11 +932,12 @@ def main(argv=None):
         "duration_sec": duration_sec,
         "gain_db": args.gain_db,
         "gain_float32": float(gain),
-        "object_delay_samples": None if speaker_mode else args.object_delay_samples,
-        "trajectory_mode": None if speaker_mode else args.trajectory_mode,
-        "joc_binaural_mode": None if speaker_mode else args.joc_binaural_mode,
-        "joc_binaural_mode_value": (None if speaker_mode else
-                                    adm_atmos.JOC_BINAURAL_MODES[args.joc_binaural_mode]),
+        "gain_float64": float(gain_float64),
+        "object_delay_samples": (None if speaker_mode else args.object_delay_samples),
+        "trajectory_mode": args.trajectory_mode if mode_name == "adm" else None,
+        "binaural_mode_value": (
+            adm_atmos.JOC_BINAURAL_MODES[args.binaural_mode]
+            if mode_name == "adm" else None),
         "render_seconds": render_seconds,
         "render_breakdown": render_breakdown,
         "renderer_backend": renderer_backend,
@@ -493,15 +946,25 @@ def main(argv=None):
         "speaker_metadata_offset": args.speaker_metadata_offset if speaker_mode else None,
         "speaker_clip": speaker_clip_info,
         "speaker_wav": speaker_wav_info,
-        "streaming_adm": not speaker_mode,
+        "binaural_renderer_backend": binaural_backend_info,
+        "binaural_mode": (
+            args.binaural_mode if (binaural_mode or mode_name == "adm") else None),
+        "binaural_hrtf": (
+            binaural_hrtf_report if binaural_backend_info else None),
+        "binaural_clip": binaural_clip_info,
+        "binaural_wav": binaural_wav_info,
+        "output_clip": speaker_clip_info if speaker_mode else binaural_clip_info,
+        "output_wav": speaker_wav_info if speaker_mode else binaural_wav_info,
+        "streaming_adm": mode_name == "adm",
         "kept_raw": str(raw_path) if raw_path is not None else None,
         "timings": timings,
         "total_seconds": total_seconds,
-        "adm_validation": None if speaker_mode else info,
+        "adm_validation": info if mode_name == "adm" else None,
         "adm_metadata": getattr(master, "metadata_info", None) if master is not None else None,
         "sha256": output_sha,
         "python": platform.python_version(),
         "numpy": np.__version__,
+        "ffmpeg": decode_option_info,
     }
     report_path = Path(str(output) + ".report.json")
     report_path.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
@@ -515,6 +978,11 @@ def main(argv=None):
               f"speaker={render_breakdown['speaker_render_seconds']:.2f}s "
               f"pipeline={render_breakdown['pipeline_wall_seconds']:.2f}s "
               f"total={report['total_seconds']:.2f}s")
+    elif binaural_mode:
+        print(f"[time] JOC-DSP={render_seconds:.2f}s ({renderer_backend['name']}) "
+              f"binaural={render_breakdown['binaural_render_seconds']:.2f}s "
+              f"pipeline={render_breakdown['pipeline_wall_seconds']:.2f}s "
+              f"total={report['total_seconds']:.2f}s")
     else:
         print(f"[time] DSP={render_seconds:.2f}s ({renderer_backend['name']}) "
               f"render+ADM-stream={render_breakdown['pipeline_wall_seconds']:.2f}s "

native/CMakeLists.txt

@@ -8,6 +8,8 @@ find_package(Threads REQUIRED)
 add_library(eac3joc_core SHARED
     src/eac3joc_core.cpp
     src/speaker_renderer.cpp
+    src/binaural_renderer.cpp
+    src/sofa_binaural_renderer.cpp
     src/joc_huffman_tables.h
     src/qmf_tables.h
     src/speaker_layouts.h

native/include/eac3joc_core.h

@@ -29,11 +29,17 @@ enum {
     EJOC_MAX_DPOINTS = 2,
     EJOC_MAX_PARAMETER_BANDS = 23,
     EJOC_SPEAKER_BLOCK_SAMPLES = 32,
-    EJOC_SPEAKER_COORDINATES = 3
+    EJOC_SPEAKER_COORDINATES = 3,
+    EJOC_BINAURAL_BLOCK_SAMPLES = 512,
+    EJOC_BINAURAL_INPUT_CHANNELS = 16,
+    EJOC_BINAURAL_OUTPUT_CHANNELS = 2,
+    EJOC_BINAURAL_QMF_BANDS = 64,
+    EJOC_BINAURAL_HYBRID_BANDS = 77
 };
 
 typedef void* ejoc_renderer_handle;
 typedef void* ejoc_speaker_renderer_handle;
+typedef void* ejoc_binaural_renderer_handle;
 
 /*
 Fixed array layouts used by ejoc_renderer_process():
@@ -47,8 +53,9 @@ Fixed array layouts used by ejoc_renderer_process():
   output16     [16][1536]
 
 Only objects selected by object_mask are read from the descriptor arrays.
-Sparse JOC must be rejected by the caller; this ABI accepts already dequantized
-dense matrix coefficients.
+dq carries already dequantized matrix coefficients in double precision; the
+caller performs the JOC bitstream differential decoding for both dense and
+sparse objects, so this ABI is identical for both syntaxes.
 */
 
 EJOC_API uint32_t EJOC_CALL ejoc_abi_version(void);
@@ -57,6 +64,15 @@ EJOC_API ejoc_renderer_handle EJOC_CALL ejoc_renderer_create(void);
 EJOC_API void EJOC_CALL ejoc_renderer_destroy(ejoc_renderer_handle handle);
 EJOC_API int EJOC_CALL ejoc_renderer_reset(ejoc_renderer_handle handle);
 EJOC_API int EJOC_CALL ejoc_renderer_set_threads(ejoc_renderer_handle handle, uint32_t total_threads);
+/*
+Enables or disables the Ls/Rs band-0 21-tap DC compensation. The caller derives
+it from the JOC downmix configuration: only configurations 3 and 4 enable the
+filter. When disabled, band 0 keeps the common per-band processing (surround
+delay plus -j rotation) instead of being overwritten by the FIR. The delay line
+and DC history advance either way, so the flag may change between frames.
+Defaults to enabled when never called.
+*/
+EJOC_API int EJOC_CALL ejoc_renderer_set_dc_filter(ejoc_renderer_handle handle, uint32_t enabled);
 EJOC_API uint32_t EJOC_CALL ejoc_renderer_thread_count(ejoc_renderer_handle handle);
 EJOC_API const char* EJOC_CALL ejoc_renderer_last_error(ejoc_renderer_handle handle);
 
@@ -114,6 +130,115 @@ EJOC_API int EJOC_CALL ejoc_speaker_renderer_process(
     const double* object_gains,
     double* output_interleaved);
 
+EJOC_API ejoc_binaural_renderer_handle EJOC_CALL ejoc_binaural_renderer_create(void);
+EJOC_API void EJOC_CALL ejoc_binaural_renderer_destroy(ejoc_binaural_renderer_handle handle);
+EJOC_API int EJOC_CALL ejoc_binaural_renderer_reset(ejoc_binaural_renderer_handle handle);
+EJOC_API const char* EJOC_CALL ejoc_binaural_renderer_last_error(
+    ejoc_binaural_renderer_handle handle);
+EJOC_API int EJOC_CALL ejoc_binaural_renderer_configure_kernels(
+    ejoc_binaural_renderer_handle handle,
+    const double* qmf_analysis,
+    const double* hybrid_low,
+    const int16_t* hybrid_indices,
+    const double* hybrid_values,
+    uint32_t hybrid_count,
+    const double* qmf_basis,
+    const double* qmf_taps);
+EJOC_API int EJOC_CALL ejoc_binaural_renderer_configure_room(
+    ejoc_binaural_renderer_handle handle,
+    uint32_t bands,
+    uint32_t allpass_count,
+    const uint32_t* allpass_delays,
+    const double* allpass_gains,
+    const uint32_t* fdn_delays,
+    const double* fdn_matrix,
+    uint32_t output_tap_delay,
+    const double* feedback_complex,
+    const double* output_taps,
+    const double* output_complex,
+    uint32_t extra_count,
+    const uint32_t* extra_delays,
+    const double* extra_fields_complex,
+    const double* extra_matrices);
+EJOC_API int EJOC_CALL ejoc_binaural_renderer_process(
+    ejoc_binaural_renderer_handle handle,
+    const double* input16_interleaved,
+    const double* gains_complex,
+    const double* room_sends,
+    double output_gain,
+    double* output_stereo_interleaved);
+
+/*
+Native SOFA binaural renderer.
+
+The handle owns the complete runtime: 64-QMF/77-hybrid analysis and synthesis,
+fifth-order ACN/N3D real spherical-harmonic direction-field evaluation,
+per-object whole-QMF-slot delay histories, six first-order image-source early
+reflections, the shared unitary-FDN late room, the 120-180 Hz LFE low-pass and
+the 961-sample latency compensation.  The caller configures the filterbank
+tables, the compiled HRTF field and the room constants once, then per 512-sample
+block updates every source with ejoc_sofa_binaural_set_source() and calls
+ejoc_sofa_binaural_process().  Process returns the number of trimmed stereo
+samples written; the first 961 processed samples across calls are discarded.
+*/
+typedef void* ejoc_sofa_binaural_handle;
+
+EJOC_API ejoc_sofa_binaural_handle EJOC_CALL ejoc_sofa_binaural_create(void);
+EJOC_API void EJOC_CALL ejoc_sofa_binaural_destroy(ejoc_sofa_binaural_handle handle);
+EJOC_API int EJOC_CALL ejoc_sofa_binaural_reset(ejoc_sofa_binaural_handle handle);
+EJOC_API const char* EJOC_CALL ejoc_sofa_binaural_last_error(
+    ejoc_sofa_binaural_handle handle);
+EJOC_API int EJOC_CALL ejoc_sofa_binaural_configure_kernels(
+    ejoc_sofa_binaural_handle handle,
+    const double* qmf_analysis,
+    const double* hybrid_low,
+    const int16_t* hybrid_indices,
+    const double* hybrid_values,
+    uint32_t hybrid_count,
+    const double* qmf_basis,
+    const double* qmf_taps);
+EJOC_API int EJOC_CALL ejoc_sofa_binaural_configure_field(
+    ejoc_sofa_binaural_handle handle,
+    const double* coefficients,
+    const double* delay_coefficients,
+    const double* delay_bounds,
+    const double* band_centers,
+    double measurement_radius_m);
+EJOC_API int EJOC_CALL ejoc_sofa_binaural_configure_room(
+    ejoc_sofa_binaural_handle handle,
+    const double* room_dims,
+    const double* listener_pos,
+    const double* wall_gains,
+    double speed_of_sound,
+    const uint32_t* fdn_delays,
+    const double* fdn_feedback,
+    double damping,
+    double fdn_output_gain,
+    const uint32_t* allpass_delays,
+    const double* allpass_gains,
+    uint32_t enable_early_reflections,
+    uint32_t enable_late_room);
+EJOC_API int EJOC_CALL ejoc_sofa_binaural_set_source(
+    ejoc_sofa_binaural_handle handle,
+    uint32_t source,
+    const double* position_adm,
+    uint32_t profile,
+    double gain,
+    uint32_t enabled,
+    uint32_t special_lfe,
+    uint32_t fade);
+EJOC_API int EJOC_CALL ejoc_sofa_binaural_process(
+    ejoc_sofa_binaural_handle handle,
+    const double* input16_interleaved,
+    uint32_t sample_count,
+    double output_gain,
+    double* output_stereo_interleaved);
+EJOC_API int EJOC_CALL ejoc_sofa_binaural_finish(
+    ejoc_sofa_binaural_handle handle,
+    uint32_t flush_samples,
+    double* output_stereo_interleaved,
+    uint32_t capacity);
+
 #ifdef __cplusplus
 }
 #endif

native/src/binaural_renderer.cpp

@@ -0,0 +1,664 @@
+#define EJOC_BUILD_DLL
+#include "eac3joc_core.h"
+
+#include <algorithm>
+#include <array>
+#include <cmath>
+#include <cstdint>
+#include <cstdio>
+#include <cstring>
+#include <new>
+#include <vector>
+
+namespace ejoc::binaural {
+
+struct Complex {
+    double re;
+    double im;
+};
+
+inline Complex add(Complex a, Complex b) noexcept {
+    return {a.re + b.re, a.im + b.im};
+}
+
+inline Complex mul(Complex a, Complex b) noexcept {
+    return {a.re * b.re - a.im * b.im, a.re * b.im + a.im * b.re};
+}
+
+inline Complex scale(Complex value, double gain) noexcept {
+    return {value.re * gain, value.im * gain};
+}
+
+constexpr double kPi = 3.141592653589793238462643383279502884;
+constexpr int kChannels = EJOC_BINAURAL_INPUT_CHANNELS;
+constexpr int kEars = EJOC_BINAURAL_OUTPUT_CHANNELS;
+constexpr int kBlock = EJOC_BINAURAL_BLOCK_SAMPLES;
+constexpr int kSlots = kBlock / 64;
+constexpr int kQmf = EJOC_BINAURAL_QMF_BANDS;
+constexpr int kHybrid = EJOC_BINAURAL_HYBRID_BANDS;
+constexpr int kRank = 4;
+
+class Renderer final {
+public:
+    Renderer() noexcept {
+        initialize_fft();
+        reset();
+    }
+
+    int configure_kernels(
+        const double* qmf_analysis,
+        const double* hybrid_low,
+        const int16_t* hybrid_indices,
+        const double* hybrid_values,
+        uint32_t hybrid_count,
+        const double* qmf_basis,
+        const double* qmf_taps) noexcept {
+        if (!qmf_analysis || !hybrid_low || !hybrid_indices || !hybrid_values ||
+            !qmf_basis || !qmf_taps || hybrid_count == 0) {
+            return fail("invalid binaural kernel configuration");
+        }
+        std::memcpy(qmf_analysis_.data(), qmf_analysis,
+                    qmf_analysis_.size() * sizeof(double));
+        hybrid_low_.assign(hybrid_low, hybrid_low + 3 * 2 * 13 * 16 * 2);
+        hybrid_indices_.assign(hybrid_indices, hybrid_indices + hybrid_count * 4);
+        hybrid_values_.assign(hybrid_values, hybrid_values + hybrid_count);
+        std::memcpy(qmf_basis_.data(), qmf_basis,
+                    qmf_basis_.size() * sizeof(double));
+        std::memcpy(qmf_taps_.data(), qmf_taps,
+                    qmf_taps_.size() * sizeof(double));
+        kernels_ready_ = true;
+        reset();
+        return 0;
+    }
+
+    int configure_room(
+        uint32_t bands,
+        uint32_t allpass_count,
+        const uint32_t* allpass_delays,
+        const double* allpass_gains,
+        const uint32_t* fdn_delays,
+        const double* fdn_matrix,
+        uint32_t output_tap_delay,
+        const double* feedback_complex,
+        const double* output_taps,
+        const double* output_complex,
+        uint32_t extra_count,
+        const uint32_t* extra_delays,
+        const double* extra_fields_complex,
+        const double* extra_matrices) noexcept {
+        if (bands != 64 || !fdn_delays || !fdn_matrix || !feedback_complex ||
+            !output_taps || !output_complex ||
+            (allpass_count && (!allpass_delays || !allpass_gains)) ||
+            (extra_count && (!extra_delays || !extra_fields_complex || !extra_matrices))) {
+            return fail("invalid binaural room configuration");
+        }
+        room_bands_ = bands;
+        if (allpass_count) {
+            allpass_delays_.assign(allpass_delays, allpass_delays + allpass_count);
+            allpass_gains_.assign(allpass_gains, allpass_gains + allpass_count);
+        } else {
+            allpass_delays_.clear();
+            allpass_gains_.clear();
+        }
+        allpass_offsets_.resize(allpass_count);
+        allpass_positions_.assign(allpass_count, 0);
+        size_t allpass_size = 0;
+        for (uint32_t index = 0; index < allpass_count; ++index) {
+            if (allpass_delays_[index] == 0) {
+                return fail("binaural allpass delay must be positive");
+            }
+            allpass_offsets_[index] = allpass_size;
+            allpass_size += static_cast<size_t>(allpass_delays_[index]) * bands;
+        }
+        allpass_memory_.assign(allpass_size, {});
+
+        room_capacity_ = 0;
+        for (int branch = 0; branch < 4; ++branch) {
+            fdn_delays_[branch] = fdn_delays[branch];
+            room_capacity_ = std::max(room_capacity_, fdn_delays_[branch]);
+        }
+        if (room_capacity_ == 0) {
+            return fail("binaural room delay must be positive");
+        }
+        std::copy(fdn_matrix, fdn_matrix + 16, fdn_matrix_.begin());
+        output_tap_delay_ = output_tap_delay;
+        for (int band = 0; band < 64; ++band) {
+            for (int branch = 0; branch < 4; ++branch) {
+                const size_t complex_index = (static_cast<size_t>(band) * 4 + branch) * 2;
+                feedback_[band][branch] = {
+                    feedback_complex[complex_index], feedback_complex[complex_index + 1]};
+                output_taps_[band][branch] = output_taps[band * 4 + branch];
+                for (int ear = 0; ear < 2; ++ear) {
+                    const size_t output_index =
+                        ((static_cast<size_t>(ear) * 64 + band) * 4 + branch) * 2;
+                    output_matrix_[ear][band][branch] = {
+                        output_complex[output_index], output_complex[output_index + 1]};
+                }
+            }
+        }
+        room_memory_.assign(static_cast<size_t>(room_capacity_) * 64 * 4, {});
+        if (extra_count) {
+            extra_delays_.assign(extra_delays, extra_delays + extra_count);
+        } else {
+            extra_delays_.clear();
+        }
+        extra_fields_.resize(static_cast<size_t>(extra_count) * 64);
+        extra_matrices_.resize(static_cast<size_t>(extra_count) * 16);
+        for (uint32_t extra = 0; extra < extra_count; ++extra) {
+            for (int band = 0; band < 64; ++band) {
+                const size_t source = (static_cast<size_t>(extra) * 64 + band) * 2;
+                extra_fields_[static_cast<size_t>(extra) * 64 + band] = {
+                    extra_fields_complex[source], extra_fields_complex[source + 1]};
+            }
+            std::copy(extra_matrices + static_cast<size_t>(extra) * 16,
+                      extra_matrices + static_cast<size_t>(extra + 1) * 16,
+                      extra_matrices_.begin() + static_cast<size_t>(extra) * 16);
+        }
+        room_ready_ = true;
+        reset();
+        return 0;
+    }
+
+    int reset() noexcept {
+        qmf_history_.fill(0.0);
+        hybrid_low_history_.fill({});
+        hybrid_high_history_.fill({});
+        synthesis_history_.fill(0.0);
+        std::fill(allpass_memory_.begin(), allpass_memory_.end(), Complex{});
+        std::fill(allpass_positions_.begin(), allpass_positions_.end(), 0u);
+        std::fill(room_memory_.begin(), room_memory_.end(), Complex{});
+        room_position_ = 0;
+        error_[0] = '\0';
+        return 0;
+    }
+
+    const char* error() const noexcept {
+        return error_[0] ? error_ : "";
+    }
+
+    int process(
+        const double* input,
+        const double* gains,
+        const double* room_sends,
+        double output_gain,
+        double* output) noexcept {
+        if (!kernels_ready_ || !room_ready_) {
+            return fail("binaural renderer is not configured");
+        }
+        if (!input || !gains || !room_sends || !output || !std::isfinite(output_gain)) {
+            return fail("invalid binaural process arguments");
+        }
+        for (int slot = 0; slot < kSlots; ++slot) {
+            std::array<Complex, kChannels * kQmf> qmf{};
+            std::array<Complex, kChannels * kHybrid> hybrid{};
+            analyze_qmf(input + static_cast<size_t>(slot) * 64 * kChannels, qmf);
+            analyze_hybrid(qmf, hybrid);
+
+            std::array<Complex, kEars * kHybrid> rendered{};
+            std::array<Complex, kHybrid> room_input{};
+            for (int source = kChannels - 1; source >= 0; --source) {
+                for (int band = 0; band < kHybrid; ++band) {
+                    const Complex value = hybrid[source * kHybrid + band];
+                    room_input[band] = add(room_input[band], scale(value, room_sends[source]));
+                    for (int ear = 0; ear < kEars; ++ear) {
+                        const size_t gain_index =
+                            (((static_cast<size_t>(source) * kEars + ear) * kHybrid + band) * 2);
+                        const Complex gain{gains[gain_index], gains[gain_index + 1]};
+                        rendered[ear * kHybrid + band] = add(
+                            rendered[ear * kHybrid + band], mul(value, gain));
+                    }
+                }
+            }
+            const auto room = process_room(room_input);
+            for (size_t index = 0; index < rendered.size(); ++index) {
+                rendered[index] = add(rendered[index], room[index]);
+            }
+
+            std::array<Complex, kEars * kQmf> qmf_output{};
+            synthesize_hybrid(rendered, qmf_output);
+            for (int ear = 0; ear < kEars; ++ear) {
+                std::array<double, 64> samples{};
+                synthesize_qmf(qmf_output.data() + ear * kQmf, ear, samples);
+                for (int sample = 0; sample < 64; ++sample) {
+                    output[(static_cast<size_t>(slot) * 64 + sample) * 2 + ear] =
+                        samples[sample] * output_gain;
+                }
+            }
+        }
+        return 0;
+    }
+
+private:
+    int fail(const char* message) noexcept {
+        std::snprintf(error_, sizeof(error_), "%s", message);
+        return -1;
+    }
+
+    void initialize_fft() noexcept {
+        for (int index = 0; index < 128; ++index) {
+            int value = index;
+            int reversed = 0;
+            for (int bit = 0; bit < 7; ++bit) {
+                reversed = (reversed << 1) | (value & 1);
+                value >>= 1;
+            }
+            bit_reverse_[index] = static_cast<uint8_t>(reversed);
+        }
+        for (int phase = 0; phase < 64; ++phase) {
+            const double angle = -kPi * static_cast<double>(phase) / 128.0;
+            premod_[phase] = {std::cos(angle), std::sin(angle)};
+            const double post_angle =
+                -3.0 * (static_cast<double>(phase) + 0.5) * kPi / 128.0;
+            post_[phase] = {std::cos(post_angle), std::sin(post_angle)};
+            even_post_[phase] = {0.0, (phase & 1) ? -1.0 : 1.0};
+        }
+    }
+
+    void fft128(std::array<Complex, 128>& values) const noexcept {
+        for (int index = 0; index < 128; ++index) {
+            const int reversed = bit_reverse_[index];
+            if (reversed > index) {
+                std::swap(values[index], values[reversed]);
+            }
+        }
+        for (int length = 2; length <= 128; length <<= 1) {
+            const double angle = -2.0 * kPi / static_cast<double>(length);
+            const Complex step{std::cos(angle), std::sin(angle)};
+            for (int start = 0; start < 128; start += length) {
+                Complex rotation{1.0, 0.0};
+                for (int offset = 0; offset < length / 2; ++offset) {
+                    const Complex even = values[start + offset];
+                    const Complex odd = mul(values[start + offset + length / 2], rotation);
+                    values[start + offset] = {even.re + odd.re, even.im + odd.im};
+                    values[start + offset + length / 2] = {
+                        even.re - odd.re, even.im - odd.im};
+                    rotation = mul(rotation, step);
+                }
+            }
+        }
+    }
+
+    void qmf_transform(const std::array<double, 64>& source,
+                       std::array<Complex, 64>& target) const noexcept {
+        std::array<Complex, 128> work{};
+        for (int phase = 0; phase < 64; ++phase) {
+            work[phase] = scale(premod_[phase], source[phase]);
+        }
+        fft128(work);
+        for (int band = 0; band < 64; ++band) {
+            target[band] = mul(work[band], post_[band]);
+        }
+    }
+
+    void analyze_qmf(const double* input,
+                     std::array<Complex, kChannels * kQmf>& output) noexcept {
+        for (int channel = 0; channel < kChannels; ++channel) {
+            for (int lag = 9; lag > 0; --lag) {
+                for (int phase = 0; phase < 64; ++phase) {
+                    qmf_history_[qmf_history_index(lag, channel, phase)] =
+                        qmf_history_[qmf_history_index(lag - 1, channel, phase)];
+                }
+            }
+            for (int phase = 0; phase < 64; ++phase) {
+                qmf_history_[qmf_history_index(0, channel, phase)] =
+                    input[phase * kChannels + channel];
+            }
+            std::array<double, 64> even{};
+            std::array<double, 64> odd{};
+            for (int phase = 0; phase < 64; ++phase) {
+                for (int lag = 0; lag < 10; ++lag) {
+                    const double value =
+                        qmf_history_[qmf_history_index(lag, channel, phase)] *
+                        qmf_analysis_[phase * 10 + lag];
+                    (lag & 1 ? odd[phase] : even[phase]) += value;
+                }
+            }
+            std::array<Complex, 64> even_fft{};
+            std::array<Complex, 64> odd_fft{};
+            qmf_transform(even, even_fft);
+            qmf_transform(odd, odd_fft);
+            for (int band = 0; band < 64; ++band) {
+                output[channel * 64 + band] = add(
+                    odd_fft[band], mul(even_fft[band], even_post_[band]));
+            }
+        }
+    }
+
+    void analyze_hybrid(
+        const std::array<Complex, kChannels * kQmf>& qmf,
+        std::array<Complex, kChannels * kHybrid>& output) noexcept {
+        for (int channel = 0; channel < kChannels; ++channel) {
+            for (int lag = 12; lag > 0; --lag) {
+                for (int band = 0; band < 3; ++band) {
+                    hybrid_low_history_[hybrid_low_history_index(lag, channel, band)] =
+                        hybrid_low_history_[hybrid_low_history_index(lag - 1, channel, band)];
+                }
+            }
+            for (int band = 0; band < 3; ++band) {
+                hybrid_low_history_[hybrid_low_history_index(0, channel, band)] =
+                    qmf[channel * 64 + band];
+            }
+            for (int output_band = 0; output_band < 16; ++output_band) {
+                Complex value{};
+                for (int lag = 0; lag < 13; ++lag) {
+                    for (int input_band = 0; input_band < 3; ++input_band) {
+                        const Complex source = hybrid_low_history_[
+                            hybrid_low_history_index(lag, channel, input_band)];
+                        const double components[2]{source.re, source.im};
+                        for (int input_component = 0; input_component < 2; ++input_component) {
+                            value.re += components[input_component] * hybrid_low_[
+                                hybrid_low_kernel_index(input_band, input_component, lag,
+                                                        output_band, 0)];
+                            value.im += components[input_component] * hybrid_low_[
+                                hybrid_low_kernel_index(input_band, input_component, lag,
+                                                        output_band, 1)];
+                        }
+                    }
+                }
+                output[channel * kHybrid + output_band] = value;
+            }
+            for (int band = 0; band < 61; ++band) {
+                output[channel * kHybrid + 16 + band] =
+                    hybrid_high_history_[hybrid_high_history_index(0, channel, band)];
+                for (int delay = 0; delay < 5; ++delay) {
+                    hybrid_high_history_[hybrid_high_history_index(delay, channel, band)] =
+                        hybrid_high_history_[hybrid_high_history_index(delay + 1, channel, band)];
+                }
+                hybrid_high_history_[hybrid_high_history_index(5, channel, band)] =
+                    qmf[channel * 64 + 3 + band];
+            }
+        }
+    }
+
+    std::array<Complex, kEars * kHybrid> process_room(
+        const std::array<Complex, kHybrid>& input) noexcept {
+        std::array<Complex, 64> filtered{};
+        for (int band = 0; band < 64; ++band) {
+            filtered[band] = scale(input[band], 0.70710677);
+        }
+        for (size_t stage = 0; stage < allpass_delays_.size(); ++stage) {
+            const uint32_t position = allpass_positions_[stage];
+            const double gain = allpass_gains_[stage];
+            for (int band = 0; band < 64; ++band) {
+                Complex& memory = allpass_memory_[
+                    allpass_offsets_[stage] + static_cast<size_t>(position) * 64 + band];
+                const Complex residual = add(filtered[band], scale(memory, -gain));
+                filtered[band] = add(scale(residual, gain), memory);
+                memory = residual;
+            }
+            allpass_positions_[stage] = (position + 1) % allpass_delays_[stage];
+        }
+
+        std::array<Complex, 64 * 4> branches{};
+        std::array<Complex, 64 * 4> taps{};
+        for (int band = 0; band < 64; ++band) {
+            for (int branch = 0; branch < 4; ++branch) {
+                Complex value = filtered[band];
+                for (int source = 0; source < 4; ++source) {
+                    const uint32_t position =
+                        (room_position_ + room_capacity_ - fdn_delays_[source]) % room_capacity_;
+                    value = add(value, scale(room_memory_[
+                        room_memory_index(position, band, source)],
+                        fdn_matrix_[branch * 4 + source]));
+                }
+                branches[band * 4 + branch] = value;
+                const uint32_t tap_position =
+                    (room_position_ + room_capacity_ -
+                     (output_tap_delay_ % room_capacity_)) % room_capacity_;
+                taps[band * 4 + branch] =
+                    room_memory_[room_memory_index(tap_position, band, branch)];
+            }
+        }
+        for (int band = 0; band < 64; ++band) {
+            for (int branch = 0; branch < 4; ++branch) {
+                room_memory_[room_memory_index(room_position_, band, branch)] =
+                    mul(branches[band * 4 + branch], feedback_[band][branch]);
+            }
+        }
+        room_position_ = (room_position_ + 1) % room_capacity_;
+
+        std::array<Complex, 64 * 4> extra{};
+        for (size_t index = 0; index < extra_delays_.size(); ++index) {
+            const uint32_t position =
+                (room_position_ + room_capacity_ -
+                 ((extra_delays_[index] + 1) % room_capacity_)) % room_capacity_;
+            for (int band = 0; band < 64; ++band) {
+                for (int target = 0; target < 4; ++target) {
+                    Complex mixed{};
+                    for (int source = 0; source < 4; ++source) {
+                        mixed = add(mixed, scale(room_memory_[
+                            room_memory_index(position, band, source)],
+                            extra_matrices_[index * 16 + target * 4 + source]));
+                    }
+                    extra[band * 4 + target] = add(
+                        extra[band * 4 + target],
+                        mul(mixed, extra_fields_[index * 64 + band]));
+                }
+            }
+        }
+
+        std::array<Complex, kEars * kHybrid> output{};
+        for (int ear = 0; ear < 2; ++ear) {
+            for (int band = 0; band < 64; ++band) {
+                Complex value{};
+                for (int branch = 0; branch < 4; ++branch) {
+                    const Complex signal = add(
+                        scale(taps[band * 4 + branch], output_taps_[band][branch]),
+                        extra[band * 4 + branch]);
+                    value = add(value, mul(
+                        signal, output_matrix_[ear][band][branch]));
+                }
+                output[ear * kHybrid + band] = value;
+            }
+        }
+        return output;
+    }
+
+    void synthesize_hybrid(
+        const std::array<Complex, kEars * kHybrid>& input,
+        std::array<Complex, kEars * kQmf>& output) const noexcept {
+        for (size_t mapping = 0; mapping < hybrid_values_.size(); ++mapping) {
+            const int16_t* index = hybrid_indices_.data() + mapping * 4;
+            const int input_band = index[0];
+            const int input_component = index[1];
+            const int output_band = index[2];
+            const int output_component = index[3];
+            const double gain = hybrid_values_[mapping];
+            for (int ear = 0; ear < 2; ++ear) {
+                const Complex source = input[ear * kHybrid + input_band];
+                Complex& target = output[ear * kQmf + output_band];
+                const double component = input_component == 0 ? source.re : source.im;
+                (output_component == 0 ? target.re : target.im) += component * gain;
+            }
+        }
+    }
+
+    void synthesize_qmf(const Complex* input, int ear,
+                        std::array<double, 64>& output) noexcept {
+        std::array<double, 64 * kRank> features{};
+        std::array<double, 128> flat{};
+        for (int band = 0; band < 64; ++band) {
+            flat[band * 2] = input[band].re;
+            flat[band * 2 + 1] = input[band].im;
+        }
+        for (int phase = 0; phase < 64; ++phase) {
+            for (int rank = 0; rank < kRank; ++rank) {
+                double value = 0.0;
+                const size_t base = (static_cast<size_t>(phase) * kRank + rank) * 128;
+                for (int component = 0; component < 128; ++component) {
+                    value += flat[component] * qmf_basis_[base + component];
+                }
+                features[phase * kRank + rank] = value;
+            }
+        }
+        for (int phase = 0; phase < 64; ++phase) {
+            double value = 0.0;
+            for (int lag = 0; lag < 10; ++lag) {
+                for (int rank = 0; rank < kRank; ++rank) {
+                    const double feature = lag == 0
+                        ? features[phase * kRank + rank]
+                        : synthesis_history_[synthesis_history_index(
+                            ear, lag - 1, phase, rank)];
+                    value += feature * qmf_taps_[
+                        ((static_cast<size_t>(phase) * 10 + lag) * kRank + rank)];
+                }
+            }
+            output[phase] = value;
+        }
+        for (int lag = 8; lag > 0; --lag) {
+            for (int phase = 0; phase < 64; ++phase) {
+                for (int rank = 0; rank < kRank; ++rank) {
+                    synthesis_history_[synthesis_history_index(ear, lag, phase, rank)] =
+                        synthesis_history_[synthesis_history_index(
+                            ear, lag - 1, phase, rank)];
+                }
+            }
+        }
+        for (int phase = 0; phase < 64; ++phase) {
+            for (int rank = 0; rank < kRank; ++rank) {
+                synthesis_history_[synthesis_history_index(ear, 0, phase, rank)] =
+                    features[phase * kRank + rank];
+            }
+        }
+    }
+
+    static size_t qmf_history_index(int lag, int channel, int phase) noexcept {
+        return (static_cast<size_t>(lag) * kChannels + channel) * 64 + phase;
+    }
+
+    static size_t hybrid_low_history_index(int lag, int channel, int band) noexcept {
+        return (static_cast<size_t>(lag) * kChannels + channel) * 3 + band;
+    }
+
+    static size_t hybrid_high_history_index(int delay, int channel, int band) noexcept {
+        return (static_cast<size_t>(delay) * kChannels + channel) * 61 + band;
+    }
+
+    static size_t hybrid_low_kernel_index(
+        int input_band, int input_component, int lag,
+        int output_band, int output_component) noexcept {
+        return (((static_cast<size_t>(input_band) * 2 + input_component) * 13 + lag) *
+                16 + output_band) * 2 + output_component;
+    }
+
+    size_t room_memory_index(uint32_t position, int band, int branch) const noexcept {
+        return (static_cast<size_t>(position) * 64 + band) * 4 + branch;
+    }
+
+    static size_t synthesis_history_index(
+        int ear, int lag, int phase, int rank) noexcept {
+        return (((static_cast<size_t>(ear) * 9 + lag) * 64 + phase) * kRank + rank);
+    }
+
+    bool kernels_ready_ = false;
+    bool room_ready_ = false;
+    std::array<double, 64 * 10> qmf_analysis_{};
+    std::vector<double> hybrid_low_;
+    std::vector<int16_t> hybrid_indices_;
+    std::vector<double> hybrid_values_;
+    std::array<double, 64 * kRank * 128> qmf_basis_{};
+    std::array<double, 64 * 10 * kRank> qmf_taps_{};
+
+    std::array<double, 10 * kChannels * 64> qmf_history_{};
+    std::array<Complex, 13 * kChannels * 3> hybrid_low_history_{};
+    std::array<Complex, 6 * kChannels * 61> hybrid_high_history_{};
+    std::array<double, kEars * 9 * 64 * kRank> synthesis_history_{};
+
+    uint32_t room_bands_ = 0;
+    std::vector<uint32_t> allpass_delays_;
+    std::vector<double> allpass_gains_;
+    std::vector<size_t> allpass_offsets_;
+    std::vector<uint32_t> allpass_positions_;
+    std::vector<Complex> allpass_memory_;
+    std::array<uint32_t, 4> fdn_delays_{};
+    std::array<double, 16> fdn_matrix_{};
+    uint32_t room_capacity_ = 0;
+    uint32_t output_tap_delay_ = 0;
+    std::array<std::array<Complex, 4>, 64> feedback_{};
+    std::array<std::array<double, 4>, 64> output_taps_{};
+    std::array<std::array<std::array<Complex, 4>, 64>, 2> output_matrix_{};
+    std::vector<Complex> room_memory_;
+    uint32_t room_position_ = 0;
+    std::vector<uint32_t> extra_delays_;
+    std::vector<Complex> extra_fields_;
+    std::vector<double> extra_matrices_;
+
+    std::array<uint8_t, 128> bit_reverse_{};
+    std::array<Complex, 64> premod_{};
+    std::array<Complex, 64> post_{};
+    std::array<Complex, 64> even_post_{};
+    char error_[256]{};
+};
+
+}  // namespace ejoc::binaural
+
+extern "C" {
+
+ejoc_binaural_renderer_handle EJOC_CALL ejoc_binaural_renderer_create(void) {
+    return new (std::nothrow) ejoc::binaural::Renderer();
+}
+
+void EJOC_CALL ejoc_binaural_renderer_destroy(ejoc_binaural_renderer_handle handle) {
+    delete static_cast<ejoc::binaural::Renderer*>(handle);
+}
+
+int EJOC_CALL ejoc_binaural_renderer_reset(ejoc_binaural_renderer_handle handle) {
+    return handle ? static_cast<ejoc::binaural::Renderer*>(handle)->reset() : -1;
+}
+
+const char* EJOC_CALL ejoc_binaural_renderer_last_error(
+    ejoc_binaural_renderer_handle handle) {
+    return handle ? static_cast<ejoc::binaural::Renderer*>(handle)->error()
+                  : "null binaural renderer handle";
+}
+
+int EJOC_CALL ejoc_binaural_renderer_configure_kernels(
+    ejoc_binaural_renderer_handle handle,
+    const double* qmf_analysis,
+    const double* hybrid_low,
+    const int16_t* hybrid_indices,
+    const double* hybrid_values,
+    uint32_t hybrid_count,
+    const double* qmf_basis,
+    const double* qmf_taps) {
+    return handle ? static_cast<ejoc::binaural::Renderer*>(handle)->configure_kernels(
+        qmf_analysis, hybrid_low, hybrid_indices, hybrid_values,
+        hybrid_count, qmf_basis, qmf_taps) : -1;
+}
+
+int EJOC_CALL ejoc_binaural_renderer_configure_room(
+    ejoc_binaural_renderer_handle handle,
+    uint32_t bands,
+    uint32_t allpass_count,
+    const uint32_t* allpass_delays,
+    const double* allpass_gains,
+    const uint32_t* fdn_delays,
+    const double* fdn_matrix,
+    uint32_t output_tap_delay,
+    const double* feedback_complex,
+    const double* output_taps,
+    const double* output_complex,
+    uint32_t extra_count,
+    const uint32_t* extra_delays,
+    const double* extra_fields_complex,
+    const double* extra_matrices) {
+    return handle ? static_cast<ejoc::binaural::Renderer*>(handle)->configure_room(
+        bands, allpass_count, allpass_delays, allpass_gains,
+        fdn_delays, fdn_matrix, output_tap_delay,
+        feedback_complex, output_taps, output_complex,
+        extra_count, extra_delays, extra_fields_complex, extra_matrices) : -1;
+}
+
+int EJOC_CALL ejoc_binaural_renderer_process(
+    ejoc_binaural_renderer_handle handle,
+    const double* input16_interleaved,
+    const double* gains_complex,
+    const double* room_sends,
+    double output_gain,
+    double* output_stereo_interleaved) {
+    return handle ? static_cast<ejoc::binaural::Renderer*>(handle)->process(
+        input16_interleaved, gains_complex, room_sends,
+        output_gain, output_stereo_interleaved) : -1;
+}
+
+}  // extern "C"

native/src/eac3joc_core.cpp

@@ -125,6 +125,10 @@ public:
         return error_[0] ? error_ : "";
     }
 
+    void set_dc_filter(const bool enabled) noexcept {
+        dc_filter_enabled_ = enabled;
+    }
+
     int process(
         const float* bed5,
         const float* lfe,
@@ -305,16 +309,18 @@ private:
                 for (int i = 0; i < 4; ++i) {
                     dc_buffer[20 + i] = current[i][0];
                 }
-                for (int slot = 0; slot < 4; ++slot) {
-                    Complex sum{0.0, 0.0};
-                    for (int tap = 0; tap < 21; ++tap) {
-                        const Complex sample = dc_buffer[slot + tap];
-                        const double cr = kDcB[tap];
-                        const double ci = kDcA[tap];
-                        sum.re += sample.re * cr - sample.im * ci;
-                        sum.im += sample.re * ci + sample.im * cr;
+                if (dc_filter_enabled_) {
+                    for (int slot = 0; slot < 4; ++slot) {
+                        Complex sum{0.0, 0.0};
+                        for (int tap = 0; tap < 21; ++tap) {
+                            const Complex sample = dc_buffer[slot + tap];
+                            const double cr = kDcB[tap];
+                            const double ci = kDcA[tap];
+                            sum.re += sample.re * cr - sample.im * ci;
+                            sum.im += sample.re * ci + sample.im * cr;
+                        }
+                        x_[channel][0][group + slot] = {2.0 * sum.re, 2.0 * sum.im};
                     }
-                    x_[channel][0][group + slot] = {2.0 * sum.re, 2.0 * sum.im};
                 }
                 for (int i = 0; i < 20; ++i) {
                     surround_history_[surround][i] = dc_buffer[i + 4];
@@ -641,6 +647,8 @@ private:
     float analysis_phase_;
     alignas(64) Complex surround_delay_[2][10][64];
     alignas(64) Complex surround_history_[2][20];
+    // band-0 的 21-tap DC 补偿开关；仅 downmix 配置 3/4 由调用方置位。
+    bool dc_filter_enabled_ = true;
     alignas(64) double lfe_delay_[kLfeDelay];
     alignas(64) double matrix_previous_[15][5][64];
     alignas(64) double synthesis_state_[15][640];
@@ -664,13 +672,13 @@ uint32_t EJOC_CALL ejoc_abi_version(void) {
 
 const char* EJOC_CALL ejoc_build_info(void) {
 #if defined(_MSC_VER)
-    return "eac3joc-core abi=1 compiler=MSVC fft=fixed64 speaker=double crt=static-by-build";
+    return "eac3joc-core abi=1 compiler=MSVC fft=fixed64 speaker=double binaural=double crt=static-by-build";
 #elif defined(__clang__)
-    return "eac3joc-core abi=1 compiler=Clang fft=fixed64 speaker=double";
+    return "eac3joc-core abi=1 compiler=Clang fft=fixed64 speaker=double binaural=double";
 #elif defined(__GNUC__)
-    return "eac3joc-core abi=1 compiler=GCC fft=fixed64 speaker=double";
+    return "eac3joc-core abi=1 compiler=GCC fft=fixed64 speaker=double binaural=double";
 #else
-    return "eac3joc-core abi=1 compiler=unknown fft=fixed64 speaker=double";
+    return "eac3joc-core abi=1 compiler=unknown fft=fixed64 speaker=double binaural=double";
 #endif
 }
 
@@ -696,6 +704,14 @@ int EJOC_CALL ejoc_renderer_set_threads(ejoc_renderer_handle handle, uint32_t to
     return static_cast<ejoc::Renderer*>(handle)->set_threads(total_threads);
 }
 
+int EJOC_CALL ejoc_renderer_set_dc_filter(ejoc_renderer_handle handle, uint32_t enabled) {
+    if (!handle) {
+        return -1;
+    }
+    static_cast<ejoc::Renderer*>(handle)->set_dc_filter(enabled != 0);
+    return 0;
+}
+
 uint32_t EJOC_CALL ejoc_renderer_thread_count(ejoc_renderer_handle handle) {
     if (!handle) {
         return 0;

requirements.txt

@@ -1 +1,3 @@
 numpy>=1.24
+scipy>=1.10
+h5py>=3.8

src/adm_atmos.py

@@ -234,11 +234,21 @@ def build_dbmd(object_count=25, joc_binaural_mode=4):
     return bytes(out)
 
 class Sink25:
+    """RF64 ADM BWF writer.
+
+    Header layout is fixed so that sizes can be patched without rereading the
+    file: RF64+size+WAVE (12) + ds64 chunk (8+28) + fmt chunk (8+16) + data
+    chunk header (8).  Sizes beyond 32 bits follow the RF64 convention: the
+    chunk size field holds 0xFFFFFFFF and the true value lives in ds64.
+    """
+    _DS64_BODY_OFFSET = 20
+    _DATA_SIZE_OFFSET = 76
+
     def __init__(self, path, channels, rate):
         self.ch = channels; self.rate = rate; self.frames = 0
         self.fp = open(path, "wb+")
         self.fp.write(b"RF64" + struct.pack("<I", 0xFFFFFFFF) + b"WAVE")
-        self._chunk(b"ds64", b"\x00" * 64)
+        self._chunk(b"ds64", b"\x00" * 28)
         self._chunk(b"fmt ", self._fmt())
         self._chunk(b"data", b"")
     def _chunk(self, cid, body):
@@ -259,14 +269,12 @@ class Sink25:
         self._chunk(b"chna", chna_bytes)
         self._chunk(b"dbmd", dbmd_bytes)
         self.fp.seek(0, 2); total = self.fp.tell()
-        self.fp.seek(0); head = self.fp.read()
-        m = head.find(b"data")
-        if m >= 0:
-            self.fp.seek(m + 4); self.fp.write(struct.pack("<I", data_len))
-        m = head.find(b"ds64")
-        if m >= 0:
-            self.fp.seek(m + 8)
-            self.fp.write(struct.pack("<QQQI", total - 8, data_len, self.frames, 0))
+        # RF64: 超过 32-bit 的 chunk size 字段写 0xFFFFFFFF，真实大小回填 ds64。
+        self.fp.seek(self._DATA_SIZE_OFFSET)
+        self.fp.write(struct.pack(
+            "<I", data_len if data_len <= 0xFFFFFFFF else 0xFFFFFFFF))
+        self.fp.seek(self._DS64_BODY_OFFSET)
+        self.fp.write(struct.pack("<QQQI", total - 8, data_len, self.frames, 0))
         self.fp.flush()
         self.fp.close()
 

src/binaural_metadata.py

@@ -0,0 +1,184 @@
+"""Direct ID11/OAMD position scheduling for the binaural render path."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from adm_atmos import q_to_adm_xyz
+from oamd_bits import JocFieldState, frame_update
+from oamd_tracks import align_metadata_sample
+from variant_error import UnsupportedVariantError
+
+
+@dataclass(frozen=True)
+class PositionTransition:
+    start_sample: int
+    duration_samples: int
+    origin: np.ndarray
+    target: np.ndarray
+
+    @property
+    def end_sample(self) -> int:
+        return self.start_sample + self.duration_samples
+
+
+class _ObjectPositionTrack:
+    def __init__(self):
+        self.initial = np.zeros(3, dtype=np.float64)
+        self.last_target = self.initial.copy()
+        self.transitions: list[PositionTransition] = []
+        self.cursor = 0
+        self.last_query_sample = -1
+
+    def set_initial(self, position):
+        target = np.asarray(position, dtype=np.float64)
+        self.initial = target.copy()
+        self.last_target = target.copy()
+
+    def append(self, start_sample: int, duration_samples: int, target,
+               object_index: int):
+        start = int(start_sample)
+        duration = int(duration_samples)
+        if start < 0 or duration < 0:
+            raise ValueError("position transition timing must be non-negative")
+        target = np.asarray(target, dtype=np.float64)
+        if self.transitions:
+            previous = self.transitions[-1]
+            if start < previous.end_sample:
+                raise UnsupportedVariantError(
+                    "oamd", "overlapping_binaural_position_ramps",
+                    "同一对象的新位置更新在上一双耳 ramp 完成前到达",
+                    details={
+                        "object": object_index,
+                        "ramp_start_sample": previous.start_sample,
+                        "ramp_end_sample": previous.end_sample,
+                        "next_update_sample": start,
+                    })
+            if start == previous.start_sample and previous.duration_samples == 0:
+                self.transitions[-1] = PositionTransition(
+                    start, duration, previous.origin.copy(), target.copy())
+                self.last_target = target.copy()
+                return
+        self.transitions.append(PositionTransition(
+            start, duration, self.last_target.copy(), target.copy()))
+        self.last_target = target.copy()
+
+    def position_at(self, sample: int) -> np.ndarray:
+        sample = int(sample)
+        if sample < self.last_query_sample:
+            raise ValueError("binaural metadata positions must be queried monotonically")
+        self.last_query_sample = sample
+        while self.cursor < len(self.transitions):
+            transition = self.transitions[self.cursor]
+            if sample < transition.end_sample:
+                break
+            self.initial = transition.target.copy()
+            self.cursor += 1
+        if self.cursor >= len(self.transitions):
+            return self.initial
+        transition = self.transitions[self.cursor]
+        if sample < transition.start_sample:
+            return self.initial
+        if transition.duration_samples == 0:
+            return transition.target
+        amount = (sample - transition.start_sample) / float(transition.duration_samples)
+        return transition.origin + (transition.target - transition.origin) * amount
+
+
+class OamdPositionTimeline:
+    """Convert OAMD state updates into a sample-timed Cartesian trajectory."""
+
+    def __init__(self, object_count: int = 15):
+        if object_count != 15:
+            raise ValueError("JOC OAMD currently requires 15 object slots")
+        self.object_count = int(object_count)
+        self.state = JocFieldState()
+        self.tracks = [_ObjectPositionTrack() for _ in range(self.object_count)]
+        self.initialized = False
+        self.previous_targets: list[tuple[float, float, float] | None] = [
+            None] * self.object_count
+        self.payload_count = 0
+        self.transition_count = 0
+        self.last_coded_event_sample = -1
+
+    def _targets(self) -> list[tuple[float, float, float]]:
+        q = self.state.q
+        return [
+            q_to_adm_xyz(
+                q[(object_index, "q1")],
+                q[(object_index, "q2")],
+                q[(object_index, "q3")],
+            )
+            for object_index in range(1, self.object_count + 1)
+        ]
+
+    def submit_update(self, update: dict, *, frame_start_sample: int,
+                      outer_sample_offset: int = 0,
+                      object_delay_samples: int = 1473,
+                      processed_sample: int = 0):
+        """Schedule one already-parsed :func:`oamd_bits.frame_update` result."""
+        frame_start = int(frame_start_sample)
+        outer_offset = int(outer_sample_offset)
+        object_delay = int(object_delay_samples)
+        if min(frame_start, outer_offset, object_delay) < 0:
+            raise ValueError("OAMD frame, outer offset, and object delay must be non-negative")
+        self.state.apply(update["values"])
+        targets = self._targets()
+        coded_event = (
+            frame_start + outer_offset + int(update["block_offset_samples"]))
+        if coded_event < self.last_coded_event_sample:
+            raise UnsupportedVariantError(
+                "oamd", "non_monotonic_binaural_updates",
+                "双耳 OAMD 更新时间倒退",
+                details={
+                    "event_sample": coded_event,
+                    "previous_event_sample": self.last_coded_event_sample,
+                })
+        self.last_coded_event_sample = coded_event
+
+        if not self.initialized:
+            if int(processed_sample) > 0:
+                raise UnsupportedVariantError(
+                    "oamd", "late_initial_binaural_state",
+                    "首个 OAMD 状态在双耳 PCM 已处理后才出现，无法回填 sample 0",
+                    details={
+                        "processed_sample": int(processed_sample),
+                        "first_event_sample": coded_event,
+                    })
+            for index, target in enumerate(targets):
+                self.tracks[index].set_initial(target)
+                self.previous_targets[index] = target
+            self.initialized = True
+            self.payload_count += 1
+            return
+
+        effective_ramp = max(0, int(update["ramp_duration_samples"]))
+        transition_start = align_metadata_sample(coded_event + object_delay)
+        for index, target in enumerate(targets):
+            if self.previous_targets[index] == target:
+                continue
+            self.tracks[index].append(
+                transition_start, effective_ramp, target, index + 1)
+            self.previous_targets[index] = target
+            self.transition_count += 1
+        self.payload_count += 1
+
+    def submit_payload(self, payload, *, frame_start_sample: int,
+                       outer_sample_offset: int = 0,
+                       object_delay_samples: int = 1473,
+                       processed_sample: int = 0):
+        update = frame_update(payload)
+        self.submit_update(
+            update,
+            frame_start_sample=frame_start_sample,
+            outer_sample_offset=outer_sample_offset,
+            object_delay_samples=object_delay_samples,
+            processed_sample=processed_sample,
+        )
+        return update
+
+    def positions_at(self, sample: int) -> np.ndarray:
+        return np.stack(
+            [track.position_at(sample) for track in self.tracks], axis=0
+        ).astype(np.float64, copy=False)

src/binaural_native_renderer.py

@@ -0,0 +1,214 @@
+"""ctypes bridge for the native float64 binaural DSP."""
+from __future__ import annotations
+
+import ctypes
+from pathlib import Path
+
+import numpy as np
+
+from native_renderer import ABI_VERSION, find_native_library
+from rosella_filterbank import DEFAULT_KERNEL_DATA, load_kernel_tables
+from rosella_model import RosellaModel
+
+BLOCK_SAMPLES = 512
+INPUT_CHANNELS = 16
+OUTPUT_CHANNELS = 2
+HYBRID_BANDS = 77
+
+
+class NativeBinauralDsp:
+    def __init__(self, model: RosellaModel, *, library_path=None,
+                 kernel_data: str | Path = DEFAULT_KERNEL_DATA):
+        self.library_path = find_native_library(library_path)
+        self._lib = ctypes.CDLL(str(self.library_path))
+        self._bind()
+        version = int(self._lib.ejoc_abi_version())
+        if version != ABI_VERSION:
+            raise RuntimeError(
+                f"native ABI mismatch: expected {ABI_VERSION}, got {version}")
+        self._handle = self._lib.ejoc_binaural_renderer_create()
+        if not self._handle:
+            raise RuntimeError("native binaural renderer creation failed")
+        try:
+            self._configure_kernels(kernel_data)
+            self._configure_room(model)
+        except Exception:
+            self.close()
+            raise
+
+    def _bind(self):
+        void_p = ctypes.c_void_p
+        f64_p = ctypes.POINTER(ctypes.c_double)
+        i16_p = ctypes.POINTER(ctypes.c_int16)
+        u32_p = ctypes.POINTER(ctypes.c_uint32)
+        self._lib.ejoc_abi_version.argtypes = []
+        self._lib.ejoc_abi_version.restype = ctypes.c_uint32
+        self._lib.ejoc_binaural_renderer_create.argtypes = []
+        self._lib.ejoc_binaural_renderer_create.restype = void_p
+        self._lib.ejoc_binaural_renderer_destroy.argtypes = [void_p]
+        self._lib.ejoc_binaural_renderer_destroy.restype = None
+        self._lib.ejoc_binaural_renderer_reset.argtypes = [void_p]
+        self._lib.ejoc_binaural_renderer_reset.restype = ctypes.c_int
+        self._lib.ejoc_binaural_renderer_last_error.argtypes = [void_p]
+        self._lib.ejoc_binaural_renderer_last_error.restype = ctypes.c_char_p
+        self._lib.ejoc_binaural_renderer_configure_kernels.argtypes = [
+            void_p, f64_p, f64_p, i16_p, f64_p, ctypes.c_uint32, f64_p, f64_p]
+        self._lib.ejoc_binaural_renderer_configure_kernels.restype = ctypes.c_int
+        self._lib.ejoc_binaural_renderer_configure_room.argtypes = [
+            void_p, ctypes.c_uint32, ctypes.c_uint32, u32_p, f64_p,
+            u32_p, f64_p, ctypes.c_uint32, f64_p, f64_p, f64_p,
+            ctypes.c_uint32, u32_p, f64_p, f64_p]
+        self._lib.ejoc_binaural_renderer_configure_room.restype = ctypes.c_int
+        self._lib.ejoc_binaural_renderer_process.argtypes = [
+            void_p, f64_p, f64_p, f64_p, ctypes.c_double, f64_p]
+        self._lib.ejoc_binaural_renderer_process.restype = ctypes.c_int
+
+    def _raise(self, operation, status):
+        message = self._lib.ejoc_binaural_renderer_last_error(self._handle)
+        detail = (message or b"").decode("utf-8", "replace")
+        raise RuntimeError(
+            f"native binaural renderer {operation} failed ({status}): {detail}")
+
+    @staticmethod
+    def _f64_pointer(values):
+        return values.ctypes.data_as(ctypes.POINTER(ctypes.c_double))
+
+    def _configure_kernels(self, kernel_data):
+        tables = load_kernel_tables(kernel_data)
+        qmf_analysis = np.ascontiguousarray(
+            tables["qmf_analysis_coefficients"], dtype=np.float64)
+        hybrid_low = np.ascontiguousarray(
+            tables["hybrid_analysis_low_kernel"], dtype=np.float64)
+        hybrid_indices = np.ascontiguousarray(
+            tables["hybrid_synthesis_indices"], dtype=np.int16)
+        hybrid_values = np.ascontiguousarray(
+            tables["hybrid_synthesis_values"], dtype=np.float64)
+        qmf_basis = np.ascontiguousarray(
+            tables["qmf_synthesis_basis"], dtype=np.float64)
+        qmf_taps = np.ascontiguousarray(
+            tables["qmf_synthesis_taps"], dtype=np.float64)
+        status = self._lib.ejoc_binaural_renderer_configure_kernels(
+            self._handle,
+            self._f64_pointer(qmf_analysis),
+            self._f64_pointer(hybrid_low),
+            hybrid_indices.ctypes.data_as(ctypes.POINTER(ctypes.c_int16)),
+            self._f64_pointer(hybrid_values),
+            len(hybrid_values),
+            self._f64_pointer(qmf_basis),
+            self._f64_pointer(qmf_taps),
+        )
+        if status:
+            self._raise("configure_kernels", status)
+
+    def _configure_room(self, model: RosellaModel):
+        if float(model.table_a_scalar) >= 0.5:
+            raise NotImplementedError("alternate table-A room mode")
+        bands = min(64, model.table_a_dimension)
+        allpass_delays = np.ascontiguousarray(
+            model.table_a_option_ids, dtype=np.uint32)
+        allpass_gains = np.ascontiguousarray(
+            model.table_a_option_values, dtype=np.float64)
+        fdn_delays = np.ascontiguousarray(
+            model.table_a_four_integers, dtype=np.uint32)
+        fdn_matrix = np.ascontiguousarray(
+            np.asarray(model.table_a_vector16, dtype=np.float64).reshape(
+                4, 4, order="F"))
+
+        filter8 = np.asarray(
+            model.table_a_filter_8x64_padded, dtype=np.float64).reshape(20, 4, 2, 4)
+        filter4 = np.asarray(
+            model.table_a_filter_4x64_padded, dtype=np.float64).reshape(20, 4, 4)
+        filter16 = np.asarray(
+            model.table_a_filter_16x64_padded, dtype=np.float64).reshape(20, 4, 4, 4)
+        feedback = np.empty((64, 4, 2), dtype=np.float64)
+        output_taps = np.empty((64, 4), dtype=np.float64)
+        output_matrix = np.empty((2, 64, 4, 2), dtype=np.float64)
+        for band in range(64):
+            group, lane = divmod(band, 4)
+            feedback[band, :, 0] = filter8[group, :, 0, lane]
+            feedback[band, :, 1] = filter8[group, :, 1, lane]
+            output_taps[band] = filter4[group, :, lane]
+            output_matrix[0, band, :, 0] = filter16[group, :, 0, lane]
+            output_matrix[0, band, :, 1] = filter16[group, :, 1, lane]
+            output_matrix[1, band, :, 0] = filter16[group, :, 2, lane]
+            output_matrix[1, band, :, 1] = filter16[group, :, 3, lane]
+
+        extra_count = int(model.table_a_extra)
+        extra_delays = np.ascontiguousarray(
+            model.table_a_extra_indices, dtype=np.uint32)
+        extra_fields = np.empty((extra_count, 64, 2), dtype=np.float64)
+        extra_source = np.asarray(
+            model.table_a_extra_fields_padded, dtype=np.float64).reshape(
+                extra_count, 20, 2, 4)
+        for extra in range(extra_count):
+            for band in range(64):
+                group, lane = divmod(band, 4)
+                extra_fields[extra, band] = extra_source[extra, group, :, lane]
+        extra_matrices = np.empty((extra_count, 4, 4), dtype=np.float64)
+        for extra in range(extra_count):
+            extra_matrices[extra] = np.asarray(
+                model.table_a_extra_vectors[extra], dtype=np.float64).reshape(
+                    4, 4, order="F")
+
+        null_u32 = ctypes.POINTER(ctypes.c_uint32)()
+        null_f64 = ctypes.POINTER(ctypes.c_double)()
+        status = self._lib.ejoc_binaural_renderer_configure_room(
+            self._handle,
+            bands,
+            len(allpass_delays),
+            allpass_delays.ctypes.data_as(ctypes.POINTER(ctypes.c_uint32)),
+            self._f64_pointer(allpass_gains),
+            fdn_delays.ctypes.data_as(ctypes.POINTER(ctypes.c_uint32)),
+            self._f64_pointer(fdn_matrix),
+            int(model.table_a_integer),
+            self._f64_pointer(feedback),
+            self._f64_pointer(output_taps),
+            self._f64_pointer(output_matrix),
+            extra_count,
+            (extra_delays.ctypes.data_as(ctypes.POINTER(ctypes.c_uint32))
+             if extra_count else null_u32),
+            self._f64_pointer(extra_fields) if extra_count else null_f64,
+            self._f64_pointer(extra_matrices) if extra_count else null_f64,
+        )
+        if status:
+            self._raise("configure_room", status)
+
+    def reset(self):
+        if not self._handle:
+            raise RuntimeError("native binaural renderer is closed")
+        status = self._lib.ejoc_binaural_renderer_reset(self._handle)
+        if status:
+            self._raise("reset", status)
+
+    def process_block(self, pcm16, gains, room_sends, output_gain=1.0):
+        if not self._handle:
+            raise RuntimeError("native binaural renderer is closed")
+        source = np.ascontiguousarray(pcm16, dtype=np.float64)
+        gain_values = np.asarray(gains)
+        sends = np.ascontiguousarray(room_sends, dtype=np.float64)
+        if source.shape != (BLOCK_SAMPLES, INPUT_CHANNELS):
+            raise ValueError(f"pcm16 block must be (512,16), got {source.shape}")
+        if gain_values.shape != (INPUT_CHANNELS, OUTPUT_CHANNELS, HYBRID_BANDS):
+            raise ValueError(f"gains must be (16,2,77), got {gain_values.shape}")
+        direct = np.ascontiguousarray(
+            gain_values, dtype=np.complex128).view(np.float64)
+        if sends.shape != (INPUT_CHANNELS,):
+            raise ValueError(f"room_sends must be (16,), got {sends.shape}")
+        output = np.empty((BLOCK_SAMPLES, OUTPUT_CHANNELS), dtype=np.float64)
+        status = self._lib.ejoc_binaural_renderer_process(
+            self._handle,
+            self._f64_pointer(source),
+            self._f64_pointer(direct),
+            self._f64_pointer(sends),
+            float(output_gain),
+            self._f64_pointer(output),
+        )
+        if status:
+            self._raise("process", status)
+        return output
+
+    def close(self):
+        handle = getattr(self, "_handle", None)
+        if handle:
+            self._lib.ejoc_binaural_renderer_destroy(handle)
+            self._handle = None

src/binaural_renderer.py

@@ -0,0 +1,272 @@
+"""JOC frame adapter for the public SOFA binaural backend."""
+from __future__ import annotations
+
+import math
+from pathlib import Path
+
+import numpy as np
+
+from binaural_metadata import OamdPositionTimeline
+from public_filterbank import ANALYSIS_SYNTHESIS_LATENCY_SAMPLES
+from sofa_binaural_backend import SofaBinauralBackend
+from sofa_hrtf_field import (
+    DEFAULT_HRTF_CACHE_DIR,
+    DEFAULT_PROJECTION_RIDGE,
+    DEFAULT_SH_RIDGE,
+)
+
+
+SAMPLE_RATE = 48000
+FRAME_SAMPLES = 1536
+BINAURAL_BLOCK_SAMPLES = 512
+QMF_HOP_SAMPLES = 64
+BINAURAL_LATENCY_SAMPLES = ANALYSIS_SYNTHESIS_LATENCY_SAMPLES
+SOURCE_CHANNELS = 16
+OUTPUT_CHANNELS = 2
+PROJECT_DIR = Path(__file__).resolve().parent.parent
+DEFAULT_HRTF_DIR = PROJECT_DIR / "HRTF"
+DEFAULT_SOFA_HRTF = DEFAULT_HRTF_DIR / "binaural.sofa"
+
+
+def _resolve_hrtf_file(path: str | Path, suffix: str, label: str) -> Path:
+    target = Path(path).expanduser().resolve()
+    if target.suffix.lower() != suffix:
+        raise ValueError(f"{label} must use the {suffix} extension: {target}")
+    if not target.is_file():
+        raise FileNotFoundError(f"{label} not found: {target}")
+    return target
+
+
+def resolve_sofa_hrtf(path: str | Path) -> Path:
+    """Resolve an explicitly selected public SOFA source."""
+    return _resolve_hrtf_file(path, ".sofa", "SOFA HRTF")
+
+
+def resolve_compiled_hrtf_cache(path: str | Path) -> Path:
+    """Resolve an explicitly selected JOC compiled HRTF cache."""
+    return _resolve_hrtf_file(path, ".jochrtf", "compiled HRTF cache")
+
+
+class SofaBinauralRenderer:
+    """Render interleaved LFE plus fifteen JOC objects to stereo.
+
+    The adapter owns frame buffering and sample-timed OAMD updates.  The
+    backend owns the 64-QMF/77-hybrid state, the 961-sample latency policy,
+    per-object direct/early state, and the shared late room.
+    """
+
+    def __init__(
+            self, backend, *,
+            mode: str = "mid",
+            object_delay_samples: int = 1473,
+            tail_seconds: float = 5.0,
+            chunk_frames: int = 64):
+        required_interface = (
+            "source_count", "default_profile", "set_source", "process",
+            "finish", "finish_output_capacity", "info")
+        missing = [name for name in required_interface if not hasattr(backend, name)]
+        if missing:
+            raise TypeError(
+                f"backend must implement the binaural backend interface; "
+                f"missing: {', '.join(missing)}")
+        if backend.source_count != SOURCE_CHANNELS:
+            raise ValueError(f"JOC binaural backend must have {SOURCE_CHANNELS} sources")
+        if backend.default_profile != str(mode).lower():
+            raise ValueError("backend default profile does not match renderer mode")
+        if int(object_delay_samples) < 0:
+            raise ValueError("object_delay_samples must be non-negative")
+        if not math.isfinite(float(tail_seconds)) or float(tail_seconds) < 0.0:
+            raise ValueError("tail_seconds must be finite and non-negative")
+        if int(chunk_frames) <= 0:
+            raise ValueError("chunk_frames must be positive")
+
+        self.backend = backend
+        self.mode = str(mode).lower()
+        self.object_delay_samples = int(object_delay_samples)
+        self.tail_seconds = float(tail_seconds)
+        self.chunk_frames = int(chunk_frames)
+        self.chunk_samples = self.chunk_frames * FRAME_SAMPLES
+        self.dsp_backend = getattr(backend, "dsp_backend", "python-sofa")
+        self.timeline = OamdPositionTimeline(15)
+
+        self._input_buffer = np.empty(
+            (self.chunk_samples, SOURCE_CHANNELS), dtype=np.float64)
+        self._buffer_used = 0
+        self.input_samples = 0
+        self.processed_input_samples = 0
+        self.output_samples = 0
+        self.finished = False
+        self.metadata_block_updates = 0
+
+    @classmethod
+    def from_sofa(
+            cls, sofa: str | Path, *,
+            mode: str = "mid",
+            cache_policy: str = "memory",
+            cache_dir: str | Path | None = DEFAULT_HRTF_CACHE_DIR,
+            shell_radius_m: float = 1.0,
+            projection_ridge: float = DEFAULT_PROJECTION_RIDGE,
+            sh_ridge: float = DEFAULT_SH_RIDGE,
+            object_delay_samples: int = 1473,
+            tail_seconds: float = 5.0,
+            output_gain: float = 1.0,
+            chunk_frames: int = 64) -> "SofaBinauralRenderer":
+        source = resolve_sofa_hrtf(sofa)
+        backend = SofaBinauralBackend.from_sofa(
+            source,
+            source_count=SOURCE_CHANNELS,
+            default_profile=mode,
+            output_gain=output_gain,
+            cache_policy=cache_policy,
+            cache_dir=cache_dir,
+            shell_radius_m=shell_radius_m,
+            projection_ridge=projection_ridge,
+            sh_ridge=sh_ridge)
+        return cls(
+            backend,
+            mode=mode,
+            object_delay_samples=object_delay_samples,
+            tail_seconds=tail_seconds,
+            chunk_frames=chunk_frames)
+
+    @classmethod
+    def from_compiled_cache(
+            cls, cache: str | Path, *,
+            mode: str = "mid",
+            object_delay_samples: int = 1473,
+            tail_seconds: float = 5.0,
+            output_gain: float = 1.0,
+            chunk_frames: int = 64) -> "SofaBinauralRenderer":
+        source = resolve_compiled_hrtf_cache(cache)
+        backend = SofaBinauralBackend.from_compiled_cache(
+            source,
+            source_count=SOURCE_CHANNELS,
+            default_profile=mode,
+            output_gain=output_gain)
+        return cls(
+            backend,
+            mode=mode,
+            object_delay_samples=object_delay_samples,
+            tail_seconds=tail_seconds,
+            chunk_frames=chunk_frames)
+
+    @property
+    def finish_capacity_samples(self) -> int:
+        return self.backend.finish_output_capacity(self.tail_seconds)
+
+    def _append_input(self, samples: np.ndarray) -> list[np.ndarray]:
+        outputs = []
+        source = np.asarray(samples, dtype=np.float64)
+        position = 0
+        while position < len(source):
+            count = min(self.chunk_samples - self._buffer_used, len(source) - position)
+            self._input_buffer[self._buffer_used:self._buffer_used + count] = (
+                source[position:position + count])
+            self._buffer_used += count
+            position += count
+            if self._buffer_used == self.chunk_samples:
+                outputs.append(self._process_samples(self._input_buffer))
+                self._buffer_used = 0
+        return outputs
+
+    def render_frame(self, objects16, payload=None, metadata_offset=None,
+                     *, outer_sample_offset=0) -> np.ndarray:
+        """Submit one 1536-sample reconstructed frame and its ID11 payload."""
+        if self.finished:
+            raise RuntimeError("binaural renderer is already finished")
+        source = np.asarray(objects16)
+        if source.shape != (FRAME_SAMPLES, SOURCE_CHANNELS):
+            raise ValueError(
+                f"binaural frame must have shape ({FRAME_SAMPLES},{SOURCE_CHANNELS}), "
+                f"got {source.shape}")
+        frame_start = self.input_samples
+        metadata_delay = (self.object_delay_samples if metadata_offset is None
+                          else int(metadata_offset))
+        if metadata_delay < 0:
+            raise ValueError("metadata_offset must be non-negative")
+        if payload is not None:
+            self.timeline.submit_payload(
+                payload,
+                frame_start_sample=frame_start,
+                outer_sample_offset=int(outer_sample_offset),
+                object_delay_samples=metadata_delay,
+                processed_sample=self.processed_input_samples,
+            )
+            self.metadata_block_updates += 1
+        self.input_samples += FRAME_SAMPLES
+        chunks = self._append_input(source)
+        if not chunks:
+            return np.empty((0, OUTPUT_CHANNELS), dtype=np.float64)
+        return np.concatenate(chunks, axis=0) if len(chunks) > 1 else chunks[0]
+
+    def _set_block_parameters(self, sample: int) -> None:
+        positions = self.timeline.positions_at(sample)
+        self.backend.set_source(
+            0, (0.0, 1.0, 0.0), profile=self.mode,
+            special_lfe=True)
+        for object_index in range(15):
+            self.backend.set_source(
+                object_index + 1,
+                positions[object_index],
+                profile=self.mode)
+
+    def _process_samples(self, source: np.ndarray) -> np.ndarray:
+        values = np.asarray(source, dtype=np.float64)
+        if values.ndim != 2 or values.shape[1] != SOURCE_CHANNELS:
+            raise ValueError(f"expected [samples,{SOURCE_CHANNELS}], got {values.shape}")
+        if len(values) % BINAURAL_BLOCK_SAMPLES:
+            raise ValueError("binaural input must be divisible by 512 samples")
+        outputs = []
+        block_base = self.processed_input_samples
+        for start in range(0, len(values), BINAURAL_BLOCK_SAMPLES):
+            sample = block_base + start
+            self._set_block_parameters(sample)
+            outputs.append(self.backend.process(
+                values[start:start + BINAURAL_BLOCK_SAMPLES]))
+        self.processed_input_samples += len(values)
+        nonempty = [value for value in outputs if len(value)]
+        if not nonempty:
+            return np.empty((0, OUTPUT_CHANNELS), dtype=np.float64)
+        output = np.concatenate(nonempty, axis=0)
+        self.output_samples += len(output)
+        return output
+
+    def finish(self) -> np.ndarray:
+        """Process pending source samples and drain early/late room state once."""
+        if self.finished:
+            return np.empty((0, OUTPUT_CHANNELS), dtype=np.float64)
+        outputs: list[np.ndarray] = []
+        if self._buffer_used:
+            outputs.append(self._process_samples(
+                self._input_buffer[:self._buffer_used]))
+            self._buffer_used = 0
+        outputs.append(self.backend.finish(tail_seconds=self.tail_seconds))
+        self.finished = True
+        nonempty = [value for value in outputs if len(value)]
+        if not nonempty:
+            return np.empty((0, OUTPUT_CHANNELS), dtype=np.float64)
+        output = np.concatenate(nonempty, axis=0)
+        self.output_samples += len(outputs[-1])
+        return output
+
+    def close(self) -> None:
+        self.finished = True
+
+    @property
+    def backend_info(self) -> dict:
+        info = self.backend.info()
+        info.update({
+            "adapter": "JOC 1536-frame / 512-sample metadata",
+            "dsp_backend": self.dsp_backend,
+            "mode": self.mode,
+            "latency_compensated_samples": BINAURAL_LATENCY_SAMPLES,
+            "object_delay_samples": self.object_delay_samples,
+            "tail_seconds": self.tail_seconds,
+            "metadata_payloads": self.timeline.payload_count,
+            "metadata_position_transitions": self.timeline.transition_count,
+            "input_samples": self.input_samples,
+            "source_samples_processed": self.processed_input_samples,
+            "output_samples_before_tail_trim": self.output_samples,
+            "thread_safe": False,
+        })
+        return info

src/joc_decode.py

@@ -2,11 +2,11 @@
 
 范围：
   - EMDF ID14 的 joc_header、joc_info 和 Huffman joc_data；
-  - 差分解码得到 joc_mix_mtx_q；
+  - 差分还原得到 joc_mix_mtx_q（dense MTX 与 sparse IDX/VEC 两条语法）；
   - 去量化得到 joc_mix_mtx_dq；
   - 位流自洽验证（joc_data 后剩余 = padding_bits 0..7 + 可能 joc_ext_data）
 后续的时间插值、QMF/时域重建和 ``joc_clipgain`` 位于 ``renderer.py``。
-Sparse 分支仍缺少实际样本验证。
+公式与符号定义见 ``docs/math.md`` 第 2 节。
 """
 from pathlib import Path
 
@@ -23,6 +23,7 @@ _HUFF_NAMES = (
     "joc_huff_code_7ch_pos_index_sparse",
 )
 
+
 def _load_huff_tables():
     with np.load(_TABLES_PATH) as tables:
         return {
@@ -30,18 +31,26 @@ def _load_huff_tables():
             for name in _HUFF_NAMES
         }
 
+
 H = _load_huff_tables()
 
 JOC_NUM_CHANNELS = {0: 5, 1: 7, 2: 7, 3: 5, 4: 7}          # Table 33
+# band-0 的 21-tap DC 补偿只在 downmix 配置 3/4 下启用。
+DC_FILTER_DMX_CONFIGS = (3, 4)
 JOC_NUM_BANDS = {0: 1, 1: 3, 2: 5, 3: 7, 4: 9, 5: 12, 6: 15, 7: 23}  # Table 35
-_PUBLIC_TABLE39_EXCERPT_UNUSED = {  # 仅保留作表格差异说明；渲染映射在 joc_qmf.py。
-    23: [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22,22],
-}
+JOC_NUM_QUANT = {0: 96, 1: 192}                            # Table 51
+# dense 的量化零点就是 nquant/2；sparse 的递推起点比它高 2 个量化步。
+JOC_DENSE_OFFSET = {0: 48, 1: 96}
+JOC_SPARSE_OFFSET = {0: 50, 1: 100}
+
 
 class BR:
+    """MSB-first 位读取器；位置以载荷内的 bit offset 表示。"""
+
     def __init__(self, data, pos=0):
         self.d = data
         self.p = pos
+
     def bits(self, n):
         v = 0
         for _ in range(n):
@@ -53,18 +62,19 @@ class BR:
 def huff_decode(tree, br):
     node = 0
     while node >= 0:
-        b = br.bits(1)
-        node = tree[node][b]
+        node = tree[node][br.bits(1)]
     return -node - 1
 
 
 def get_huff_code(mode, typ, nch):
     if typ == "IDX":
-        return H["joc_huff_code_5ch_pos_index_sparse" if nch == 5 else "joc_huff_code_7ch_pos_index_sparse"]
+        return H["joc_huff_code_5ch_pos_index_sparse" if nch == 5
+                 else "joc_huff_code_7ch_pos_index_sparse"]
     if typ == "VEC":
-        return H["joc_huff_code_coarse_coeff_sparse" if mode == 0 else "joc_huff_code_fine_coeff_sparse"]
-    # MTX
-    return H["joc_huff_code_coarse_generic" if mode == 0 else "joc_huff_code_fine_generic"]
+        return H["joc_huff_code_coarse_coeff_sparse" if mode == 0
+                 else "joc_huff_code_fine_coeff_sparse"]
+    return H["joc_huff_code_coarse_generic" if mode == 0
+             else "joc_huff_code_fine_generic"]           # MTX
 
 
 def parse_joc(payload):
@@ -76,6 +86,8 @@ def parse_joc(payload):
     out["ext_config_idx"] = br.bits(3)
     n_objects = out["num_objects_bits"] + 1
     n_channels = JOC_NUM_CHANNELS.get(out["dmx_config_idx"])
+    if n_channels is None:
+        raise ValueError(f"未知的 JOC downmix 配置 {out['dmx_config_idx']}")
     out["n_objects"], out["n_channels"] = n_objects, n_channels
     out["clipgain_x_bits"] = br.bits(3)
     out["clipgain_y_bits"] = br.bits(5)
@@ -98,78 +110,120 @@ def parse_joc(payload):
                 o["offset_ts"] = [br.bits(5) + 1 for _ in range(o["n_dpoints"])]
         objs.append(o)
     out["objs"] = objs
-    # joc_data（Huffman）
+    # joc_data（Huffman）：dense 逐声道逐带读 MTX；sparse 读 IDX 后读 VEC。
     for obj, o in enumerate(objs):
         if not o["present"]:
             continue
-        nquant = 96 if o["quant_idx"] == 0 else 192
         o["channel_idx"] = []
         o["vec"] = []
         o["mtx"] = []
         for dp in range(o["n_dpoints"]):
             if o["sparse"] == 1:
-                # Sparse JOC 使用 VEC/IDX Huffman 树；此分支尚无真实码流验证。
-                ci0 = br.bits(3)
-                tree = get_huff_code(n_channels, "IDX", n_channels)
-                ci = [ci0] + [huff_decode(tree, br) for _ in range(o["n_bands"] - 1)]
-                o["channel_idx"].append(ci)
+                tree = get_huff_code(o["quant_idx"], "IDX", n_channels)
+                idx = [br.bits(3)]
+                idx += [huff_decode(tree, br) for _ in range(o["n_bands"] - 1)]
                 tree = get_huff_code(o["quant_idx"], "VEC", n_channels)
-                vec = [huff_decode(tree, br) for _ in range(o["n_bands"])]
-                o["vec"].append(vec)
+                o["channel_idx"].append(idx)
+                o["vec"].append([huff_decode(tree, br) for _ in range(o["n_bands"])])
+                o["mtx"].append(None)
             else:
                 tree = get_huff_code(o["quant_idx"], "MTX", n_channels)
                 mtx = [[huff_decode(tree, br) for _ in range(o["n_bands"])]
                        for _ in range(n_channels)]
                 o["mtx"].append(mtx)
+                o["channel_idx"].append(None)
+                o["vec"].append(None)
     out["data_end_bits"] = br.p
     out["remaining_bits"] = len(payload) * 8 - br.p
     out["tail_bytes"] = payload[br.p // 8:]
     return out
 
 
+def reconstruct_dense(o, dp, n_ch):
+    """Dense 差分还原 → 量化矩阵 ``[ch][pb]``。
+
+    每个核心声道各自从 ``nquant/2``（去量化 0）出发，沿参数带累加 MTX 符号。
+    """
+    nquant = JOC_NUM_QUANT[o["quant_idx"]]
+    offset = JOC_DENSE_OFFSET[o["quant_idx"]]
+    mtx = o["mtx"][dp]
+    if mtx is None:
+        raise ValueError("Dense JOC 对象缺少 MTX 符号")
+    q = np.zeros((n_ch, o["n_bands"]), dtype=np.int64)
+    for ch in range(n_ch):
+        q[ch][0] = (offset + mtx[ch][0]) % nquant
+        for pb in range(1, o["n_bands"]):
+            q[ch][pb] = (q[ch][pb - 1] + mtx[ch][pb]) % nquant
+    return q
+
+
+def reconstruct_sparse(o, dp, n_ch):
+    """Sparse 差分还原 → 量化矩阵 ``[ch][pb]``。
+
+    每个参数带只有一个 active 声道：
+      - ``active[0]`` 是 3 bit 绝对声道号，其后由 IDX 符号累加得到，
+        因此递推锚点是**已重建**的 active 声道，而不是编码器送的符号本身；
+      - 系数是一个跨参数带连续的单累加器（active 声道切换时**不**重置），
+        起点为 sparse offset，增量为 VEC 符号；
+      - 非 active 项取 ``nquant/2``，即去量化后的 0。
+
+    IDX 符号取值恒为 ``0..n_ch-1``（Huffman 叶数即声道数），
+    故 ``(active + idx) % n_ch`` 与单次条件减等价。
+    """
+    if n_ch not in (5, 7):
+        raise ValueError(f"Sparse JOC 需要 5 或 7 个核心声道，实际 {n_ch}")
+    nquant = JOC_NUM_QUANT[o["quant_idx"]]
+    offset = JOC_SPARSE_OFFSET[o["quant_idx"]]
+    n_bands = o["n_bands"]
+    idx = o["channel_idx"][dp]
+    vec = o["vec"][dp]
+    if idx is None or vec is None:
+        raise ValueError("Sparse JOC 对象缺少 channel_idx/vec 符号")
+    if len(idx) != n_bands or len(vec) != n_bands:
+        raise ValueError(
+            f"Sparse JOC 维度不符: bands={n_bands}, idx={len(idx)}, vec={len(vec)}")
+    if not 0 <= idx[0] < n_ch:
+        raise ValueError(f"Sparse JOC 初始声道 {idx[0]} 超出 {n_ch} 个声道")
+
+    q = np.full((n_ch, n_bands), nquant // 2, dtype=np.int64)
+    active = idx[0]
+    coefficient = offset
+    for pb in range(n_bands):
+        if pb:
+            active = (active + idx[pb]) % n_ch
+        coefficient = (coefficient + vec[pb]) % nquant
+        q[active][pb] = coefficient
+    return q
+
+
 def diff_decode(out):
-    """6.6.2：差分解码 → joc_mix_mtx_q[obj][dp][ch][pb]。"""
+    """差分还原 → joc_mix_mtx_q[obj][dp][ch][pb]。"""
     mix_q = {}
     n_ch = out["n_channels"]
     for obj, o in enumerate(out["objs"]):
         if not o["present"]:
             continue
-        nquant = 96 if o["quant_idx"] == 0 else 192
         q = np.zeros((o["n_dpoints"], n_ch, o["n_bands"]), dtype=np.int64)
         for dp in range(o["n_dpoints"]):
             if o["sparse"] == 1:
-                # Sparse 差分路径尚无真实码流验证。
-                offset = 50 if o["quant_idx"] == 0 else 100
-                ci = o["channel_idx"][dp]
-                vec = o["vec"][dp]
-                for pb in range(o["n_bands"]):
-                    ci_mod = ci[0] if pb == 0 else (ci[pb - 1] + ci[pb]) % n_ch
-                    for ch in range(n_ch):
-                        if ch == ci_mod:
-                            if pb == 0:
-                                q[dp][ch][pb] = (offset + vec[pb]) % nquant
-                            else:
-                                q[dp][ch][pb] = (q[dp][ch][pb - 1] + vec[pb]) % nquant
-                        else:
-                            q[dp][ch][pb] = offset
+                q[dp] = reconstruct_sparse(o, dp, n_ch)
             else:
-                offset = 48 if o["quant_idx"] == 0 else 96
-                mtx = o["mtx"][dp]
-                for ch in range(n_ch):
-                    q[dp][ch][0] = (offset + mtx[ch][0]) % nquant
-                    for pb in range(1, o["n_bands"]):
-                        q[dp][ch][pb] = (q[dp][ch][pb - 1] + mtx[ch][pb]) % nquant
+                q[dp] = reconstruct_dense(o, dp, n_ch)
         mix_q[obj] = q
     return mix_q
 
 
 def dequantize(out, mix_q):
-    """6.6.4：去量化 → joc_mix_mtx_dq。"""
+    """去量化 → joc_mix_mtx_dq。
+
+    Sparse 的非 active 项在 ``joc_mix_mtx_q`` 中取 ``nquant/2``，
+    因此与 dense 共用同一条去量化公式即得到 0。
+    """
     mix_dq = {}
     for obj, o in enumerate(out["objs"]):
         if not o["present"]:
             continue
-        nquant = 96 if o["quant_idx"] == 0 else 192
+        nquant = JOC_NUM_QUANT[o["quant_idx"]]
         q = mix_q[obj]
         dq = (q.astype(np.float64) - nquant / 2) * 820 / (4096 * (1 + o["quant_idx"]))
         mix_dq[obj] = dq

src/joc_qmf.py

@@ -130,8 +130,12 @@ _SURROUND_DC_B = np.array([
 _SURROUND_DC_C = _SURROUND_DC_B + 1j * _SURROUND_DC_A
 
 
-def surround_post_frame(x, delay, dc_hist):
-    """处理 Ls/Rs 的 10 槽延迟、-j 旋转和 band-0 FIR。"""
+def surround_post_frame(x, delay, dc_hist, apply_dc_filter=True):
+    """处理 Ls/Rs 的 10 槽延迟、-j 旋转和 band-0 FIR。
+
+    ``apply_dc_filter=False`` 时跳过 band-0 的 21-tap DC 补偿，只做延迟与
+    -j 旋转；延迟线与 DC 历史仍照常推进，便于逐帧切换。
+    """
     src = np.asarray(x, dtype=np.complex128)
     qdelay = np.asarray(delay, dtype=np.complex128).copy()
     hist = np.asarray(dc_hist, dtype=np.complex128).copy()
@@ -144,8 +148,9 @@ def surround_post_frame(x, delay, dc_hist):
         block = -1j * queued[:, :4, :]
         qdelay = queued[:, 4:, :]
         dc_buf = np.concatenate((hist, current[:, :, 0]), axis=1)
-        windows = np.lib.stride_tricks.sliding_window_view(dc_buf, 21, axis=1)
-        block[:, :, 0] = 2.0 * np.sum(windows * _SURROUND_DC_C[None, None, :], axis=2)
+        if apply_dc_filter:
+            windows = np.lib.stride_tricks.sliding_window_view(dc_buf, 21, axis=1)
+            block[:, :, 0] = 2.0 * np.sum(windows * _SURROUND_DC_C[None, None, :], axis=2)
         hist = dc_buf[:, 4:]
         out[:, :, group:group + 4] = block.transpose(0, 2, 1)
     return out, qdelay, hist

src/metadata.py

@@ -246,20 +246,6 @@ def inspect(index, limit=None, print_frames=False):
                     "parser_error": str(exc),
                     "repair_hint": "检查 JOC header、对象数、参数带、Huffman 或扩展字段",
                 }) from exc
-        sparse = [i for i, obj in enumerate(parsed["objs"]) if obj["present"] and obj["sparse"]]
-        if sparse:
-            raise UnsupportedVariantError(
-                "joc", "sparse_joc",
-                "发现尚未验证的 Sparse JOC 帧",
-                frame=frame_number,
-                details={
-                    "sparse_objects": sparse,
-                    "downmix_config": parsed["dmx_config_idx"],
-                    "extension_config": parsed["ext_config_idx"],
-                    "objects": parsed["n_objects"],
-                    "payload": bytes_descriptor(subs[14]),
-                    "repair_hint": "需要 Sparse JOC 实际样本及对应输出建立回归后再启用",
-                })
         if parsed["n_channels"] != 5 or parsed["n_objects"] > 15:
             raise UnsupportedVariantError(
                 "joc", "unsupported_configuration",

src/native_renderer.py

@@ -14,7 +14,7 @@ import sys
 import numpy as np
 
 from evo_unpack import unpack_evolution
-from joc_decode import dequantize, diff_decode, parse_joc
+from joc_decode import DC_FILTER_DMX_CONFIGS, dequantize, diff_decode, parse_joc
 
 FRAME_SAMPLES = 1536
 MAX_OBJECTS = 15
@@ -88,6 +88,9 @@ def _load_library(path):
     lib.ejoc_renderer_reset.restype = ctypes.c_int
     lib.ejoc_renderer_set_threads.argtypes = [ctypes.c_void_p, ctypes.c_uint32]
     lib.ejoc_renderer_set_threads.restype = ctypes.c_int
+    if hasattr(lib, "ejoc_renderer_set_dc_filter"):
+        lib.ejoc_renderer_set_dc_filter.argtypes = [ctypes.c_void_p, ctypes.c_uint32]
+        lib.ejoc_renderer_set_dc_filter.restype = ctypes.c_int
     lib.ejoc_renderer_thread_count.argtypes = [ctypes.c_void_p]
     lib.ejoc_renderer_thread_count.restype = ctypes.c_uint32
     lib.ejoc_renderer_last_error.argtypes = [ctypes.c_void_p]
@@ -208,8 +211,6 @@ class NativeJocRenderer:
         for object_index, info in enumerate(out["objs"]):
             if not info["present"]:
                 continue
-            if info["sparse"]:
-                raise ValueError("native core does not accept unvalidated Sparse JOC")
             bands = int(info["n_bands"])
             points = int(info["n_dpoints"])
             if bands > MAX_BANDS or points > MAX_DPOINTS:
@@ -227,6 +228,21 @@ class NativeJocRenderer:
             self._dq[object_index, :points, :, :bands] = values
         return mask
 
+    def _set_dc_filter(self, dmx_config_idx):
+        """band-0 的 21-tap DC 补偿只在 downmix 配置 3/4 下启用。"""
+        enabled = dmx_config_idx in DC_FILTER_DMX_CONFIGS
+        setter = getattr(self._lib, "ejoc_renderer_set_dc_filter", None)
+        if setter is None:
+            if not enabled:
+                raise RuntimeError(
+                    "native library has no ejoc_renderer_set_dc_filter; rebuild "
+                    "eac3joc_core to disable the band-0 DC filter for "
+                    f"dmx_config_idx={dmx_config_idx}")
+            return
+        result = setter(self._handle, 1 if enabled else 0)
+        if result != 0:
+            self._raise_native("set_dc_filter", result)
+
     def render_frame(self, payload_bytes, bed5_pcm, lfe_pcm=None):
         subs, _ = unpack_evolution(payload_bytes, loose=True)
         return self.render_subpayloads(subs, bed5_pcm, lfe_pcm)
@@ -235,6 +251,7 @@ class NativeJocRenderer:
         self._require_open()
         out, _, mix_dq = self.decode_subpayloads(subs)
         object_mask = self._pack_frame(out, mix_dq)
+        self._set_dc_filter(out["dmx_config_idx"])
         bed5 = np.ascontiguousarray(bed5_pcm, dtype=np.float32)
         if bed5.shape != (CORE_CHANNELS, FRAME_SAMPLES):
             raise ValueError(f"core PCM shape must be (5,1536), got {bed5.shape}")

src/oamd_bits.py

@@ -1,12 +1,14 @@
 """OAMD 位载荷 → 16 个对象槽的 q1/q2/q3 增量状态。
 
-槽 0 是 bed/LFE；槽 1..15 对应输出 ch1..15 的对象元数据。
+依据 ETSI TS 103 420 V1.2.1 clause 5。槽 0 为 bed/LFE，槽 1..15 为输出
+ch1..15；bed/ISF/未激活对象没有位置字段，保持上一帧位置。element 目录按声明长度
+驱动，未知 element 按边界跳过；个别编码器的 ``oa_element_size`` 比实际内容短时以
+结构解析为准，差异记入 ``diagnostics``，不算变体错误。
 """
 import numpy as np
 
 from variant_error import UnsupportedVariantError, bytes_descriptor
 
-Q1_OFF = 192
 N_Q12 = 62
 N_Q3 = 15
 SAMPLE_OFFSET_INDEX = (8, 16, 18, 24)
@@ -16,9 +18,20 @@ RAMP_DURATION_INDEX = (
     1024, 1600, 1601, 1602, 1920, 2000, 2002, 2048,
 )
 OBJECT_ELEMENT_ID = 1
-TRIM_ELEMENT_ID = 2
-EXTENDED_OBJECT_ELEMENT_ID = 5
-POSITION_WINDOW_END_BIT = 112 + 31 * (15 - 3) + 24
+# 5.6.0.11 Table 11b：ISF 类型 → 对象数。
+ISF_OBJECT_COUNTS = (4, 8, 10, 14, 15, 30)
+# 5.6.1.1.4 Table 12：10 bit 标准 bed 掩码按位对应的声道（LSB = RC_L/RC_R）。
+BED_CHANNEL_LABELS = (
+    "RC_L/RC_R", "RC_C", "RC_LFE", "RC_LS/RC_RS", "RC_LB/RC_RB",
+    "RC_TFL/RC_TFR", "RC_TSL/RC_TSR", "RC_TBL/RC_TBR", "RC_LW/RC_RW", "RC_LFE2",
+)
+# 5.6.1.1.5 Table 13：17 bit 非标准 bed 掩码按位对应的声道标签。
+NONSTD_BED_LABELS = (
+    "RC_LFE2", "RC_RW", "RC_LW", "RC_TBR", "RC_TBL", "RC_TSR", "RC_TSL",
+    "RC_TFR", "RC_TFL", "RC_RB", "RC_LB", "RC_RS", "RC_LS", "RC_LFE", "RC_C",
+    "RC_R", "RC_L",
+)
+MAX_SLOTS = 16
 
 
 def q_of(k, n):
@@ -91,14 +104,23 @@ class _BitReader:
         self.read(count)
 
 
-def _variable_bits(reader, width, max_groups=5):
-    value = 0
-    for _ in range(max_groups + 1):
-        value += reader.read(width)
-        if not reader.read(1):
-            return value
-        value = (value + 1) << width
-    raise ValueError(f"OAMD variable_bits({width}) 延伸组过多")
+def _variable_bits_max(reader, width, max_groups):
+    """5.5.1 ``variable_bits_max(n, max_num_groups)``。"""
+    value = reader.read(width)
+    more = reader.read(1)
+    num_group = 1
+    if max_groups > num_group:
+        if more:
+            value = (value + 1) << width
+        while more:
+            value += reader.read(width)
+            more = reader.read(1)
+            if num_group >= max_groups:
+                break
+            if more:
+                value = (value + 1) << width
+                num_group += 1
+    return value
 
 
 def _element_details(elements):
@@ -109,166 +131,185 @@ def _element_details(elements):
         "header_start_bit": element["header_start_bit"],
         "body_start_bit": element["body_start_bit"],
         "body_end_bit": element["body_end_bit"],
+        "parsed_end_bit": element.get("parsed_end_bit"),
         "discard_unknown": element["discard_unknown"],
+        "alternate_data_id": element["alternate_data_id"],
     } for element in elements]
 
 
-def _parse_elements(bits, header, header_end, raw_payload):
-    """建立 OAMD element 目录；element size 表示其后 body 的字节数。"""
-    reader = _BitReader(bits, header_end)
-    elements = []
-    for ordinal in range(header["element_count"]):
-        header_start = reader.position
-        try:
-            element_id = reader.read(4)
-            size_bytes = _variable_bits(reader, 4) + 1
-        except ValueError as exc:
-            raise UnsupportedVariantError(
-                "oamd", "element_header_truncated",
-                "OAMD element header 不完整",
-                details={
-                    "element_ordinal": ordinal,
-                    "header_start_bit": header_start,
-                    "payload": bytes_descriptor(raw_payload),
-                    "parser_error": str(exc),
-                }) from exc
+def _syntax_error(variant, message, raw_payload, exc=None, **details):
+    payload = {"payload": bytes_descriptor(raw_payload)}
+    if exc is not None:
+        payload["parser_error"] = str(exc)
+    payload.update(details)
+    return UnsupportedVariantError("oamd", variant, message, details=payload)
 
-        body_start = reader.position
-        body_end = body_start + size_bytes * 8
-        if body_end > len(bits):
-            raise UnsupportedVariantError(
-                "oamd", "element_bounds",
-                "OAMD element 声明长度超过 payload 边界",
-                details={
-                    "element_ordinal": ordinal,
-                    "element_id": element_id,
-                    "size_bytes": size_bytes,
-                    "body_start_bit": body_start,
-                    "body_end_bit": body_end,
-                    "payload_bits": len(bits),
-                    "payload": bytes_descriptor(raw_payload),
+
+def _parse_program_assignment(reader, raw_payload):
+    """5.5.3 ``program_assignment()``：bed / ISF / dynamic 对象数量。"""
+    program = {
+        "dynamic_object_only": bool(reader.read(1)),
+        "lfe_present": False,
+        "content_description": None,
+        "bed_assignments": [],
+        "num_bed_objects": 0,
+        "isf_idx": None,
+        "num_isf_objects": 0,
+        "num_dynamic_objects": None,
+    }
+    if program["dynamic_object_only"]:
+        program["lfe_present"] = bool(reader.read(1))
+        # 5.6.4.8：对象顺序为 bed → ISF → dynamic，LFE 属于 bed，排在最前。
+        program["num_bed_objects"] = 1 if program["lfe_present"] else 0
+        return program
+
+    mask = reader.read(4)
+    program["content_description"] = {
+        "reserved": bool(mask & 0x8),
+        "dynamic": bool(mask & 0x4),
+        "isf": bool(mask & 0x2),
+        "bed": bool(mask & 0x1),
+    }
+    if mask & 0x1:
+        program["b_bed_chan_distribute"] = bool(reader.read(1))
+        num_instances = (reader.read(3) + 2) if reader.read(1) else 1
+        for instance in range(num_instances):
+            if reader.read(1):                      # b_lfe_only
+                program["bed_assignments"].append({
+                    "instance": instance, "lfe_only": True, "channels": ["RC_LFE"],
                 })
-
-        control_bits = 5 if header["alternate_object_present"] else 1
-        if body_start + control_bits > body_end:
-            raise UnsupportedVariantError(
-                "oamd", "element_control_bounds",
-                "OAMD element 太短，无法容纳控制字段",
-                details={
-                    "element_ordinal": ordinal,
-                    "element_id": element_id,
-                    "size_bytes": size_bytes,
-                    "control_bits": control_bits,
-                    "payload": bytes_descriptor(raw_payload),
+                continue
+            if reader.read(1):                      # b_standard_chan_assign
+                bed_mask = reader.read(10)
+                channels = []
+                for bit in range(10):
+                    if (bed_mask >> bit) & 1:
+                        channels.extend(BED_CHANNEL_LABELS[bit].split("/"))
+                program["bed_assignments"].append({
+                    "instance": instance, "lfe_only": False, "standard": True,
+                    "mask": bed_mask, "channels": channels,
                 })
-        control = _BitReader(bits, body_start, body_end)
-        alternate_data_id = (control.read(4)
-                             if header["alternate_object_present"] else None)
-        discard_unknown = bool(control.read(1))
-        elements.append({
-            "ordinal": ordinal,
-            "element_id": element_id,
-            "size_bytes": size_bytes,
-            "header_start_bit": header_start,
-            "body_start_bit": body_start,
-            "data_start_bit": control.position,
-            "body_end_bit": body_end,
-            "alternate_data_id": alternate_data_id,
-            "discard_unknown": discard_unknown,
-        })
-        reader.position = body_end
-
-    padding = bits[reader.position:]
-    if len(padding) > 7:
-        raise UnsupportedVariantError(
-            "oamd", "trailing_payload_data",
-            "OAMD element 结束后仍有超过一个字节的未声明数据",
-            details={
-                "elements": _element_details(elements),
-                "trailing_bits": len(padding),
-                "payload": bytes_descriptor(raw_payload),
-            })
-    if np.any(padding):
-        raise UnsupportedVariantError(
-            "oamd", "nonzero_padding",
-            "OAMD payload 尾部 padding 含非零位",
-            details={
-                "elements": _element_details(elements),
-                "padding_start_bit": reader.position,
-                "padding_bits": "".join(str(int(bit)) for bit in padding),
-                "payload": bytes_descriptor(raw_payload),
-            })
-
-    object_elements = [element for element in elements
-                       if element["element_id"] == OBJECT_ELEMENT_ID]
-    if len(object_elements) != 1:
-        raise UnsupportedVariantError(
-            "oamd", "object_element_count",
-            "OAMD 必须包含且只能包含一个 object element",
-            details={
-                "object_element_count": len(object_elements),
-                "elements": _element_details(elements),
-                "payload": bytes_descriptor(raw_payload),
-            })
-    object_element = object_elements[0]
-    if object_element["ordinal"] != 0 or object_element["header_start_bit"] != header_end:
-        raise UnsupportedVariantError(
-            "oamd", "object_element_order",
-            "object element 不在当前固定位置窗口支持的首个 element 位置",
-            details={
-                "elements": _element_details(elements),
-                "payload": bytes_descriptor(raw_payload),
-                "repair_hint": "以 object element 的实际位置为基准重新定位对象窗口",
-            })
-
-    for element in elements:
-        element_id = element["element_id"]
-        if element_id in (OBJECT_ELEMENT_ID, TRIM_ELEMENT_ID):
-            continue
-        if element_id == EXTENDED_OBJECT_ELEMENT_ID:
-            raise UnsupportedVariantError(
-                "oamd", "extended_object_element",
-                "OAMD 含可能改变坐标语义的 extended object element",
-                details={
-                    "element": _element_details([element])[0],
-                    "elements": _element_details(elements),
-                    "payload": bytes_descriptor(raw_payload),
-                    "repair_hint": "解析 divergence/extended-precision position 后再应用轨迹",
+            else:
+                bed_mask = reader.read(17)
+                channels = [NONSTD_BED_LABELS[bit]
+                            for bit in range(17) if (bed_mask >> bit) & 1]
+                program["bed_assignments"].append({
+                    "instance": instance, "lfe_only": False, "standard": False,
+                    "mask": bed_mask, "channels": channels,
                 })
-        raise UnsupportedVariantError(
-            "oamd", f"unsupported_element_{element_id}",
-            f"OAMD 含当前未覆盖的 element id {element_id}",
-            details={
-                "element": _element_details([element])[0],
-                "elements": _element_details(elements),
-                "payload": bytes_descriptor(raw_payload),
-            })
-    return object_element, elements
+        program["num_bed_objects"] = sum(
+            len(assignment["channels"]) for assignment in program["bed_assignments"])
+    if mask & 0x2:
+        isf_idx = reader.read(3)
+        program["isf_idx"] = isf_idx
+        program["num_isf_objects"] = (ISF_OBJECT_COUNTS[isf_idx]
+                                      if isf_idx < len(ISF_OBJECT_COUNTS) else 0)
+    if mask & 0x4:
+        count = reader.read(5)
+        if count == 0x1F:
+            count += reader.read(7)
+        program["num_dynamic_objects"] = count + 1
+    if mask & 0x8:
+        # 5.6.4.1：reserved_data_size = reserved_data_size_bits + 1（字节）。
+        reader.skip((reader.read(4) + 1) * 8)
+    return program
 
 
-def _update_timing(bits, object_element, raw_payload):
-    """从已定位的 object element 读取位置块开始偏移和 ramp 时长。"""
-    reader = _BitReader(
-        bits, object_element["data_start_bit"], object_element["body_end_bit"])
+def _parse_object_info_block(reader, object_index, in_bed_or_isf, raw_payload):
+    """5.5.9 ``object_info_block(0)``：一个对象的属性更新。"""
+    info = {
+        "object": object_index,
+        "in_bed_or_isf": bool(in_bed_or_isf),
+        "not_active": bool(reader.read(1)),
+    }
+    # blk == 0 且对象激活时 basic info 恒为 full update（status 0b01）。
+    basic_status = 0 if info["not_active"] else 1
+    info["basic_status"] = basic_status
+    if basic_status in (1, 3):
+        if basic_status == 1:
+            # 5.5.10：object_basic_info[] = {true, true}；
+            # 5.6.4.12：array[1] = object_gain_idx，array[0] = b_default_object_priority。
+            gain_present = priority_present = True
+        else:
+            flags = reader.read(2)
+            gain_present = bool(flags & 1)
+            priority_present = bool(flags & 2)
+        if gain_present:
+            gain_idx = reader.read(2)
+            info["gain_idx"] = gain_idx
+            if gain_idx == 2:
+                info["gain_bits"] = reader.read(6)
+        if priority_present:
+            default_priority = bool(reader.read(1))
+            info["default_priority"] = default_priority
+            if not default_priority:
+                info["priority_bits"] = reader.read(5)
+    render_status = 0 if (info["not_active"] or info["in_bed_or_isf"]) else 1
+    info["render_status"] = render_status
+    if render_status in (1, 3):
+        if render_status == 1:
+            # 5.5.11：obj_render_info[] = {true, true, true, true}。
+            position_present = zone_present = size_present = screen_present = True
+        else:
+            flags = reader.read(4)
+            position_present = bool(flags & 0x1)
+            zone_present = bool(flags & 0x2)
+            size_present = bool(flags & 0x4)
+            screen_present = bool(flags & 0x8)
+        if position_present:
+            # blk == 0 时 b_differential_position_specified 恒为 FALSE。
+            x = reader.read(6)
+            y = reader.read(6)
+            z_sign = reader.read(1)
+            z = reader.read(4)
+            info["position"] = (x, y, z if z_sign else -z)
+            if reader.read(1):                      # b_object_distance_specified
+                if not reader.read(1):              # b_object_at_infinity
+                    reader.read(4)                  # distance_factor_idx
+        if zone_present:
+            info["zone_constraints_idx"] = reader.read(3)
+            info["enable_elevation"] = bool(reader.read(1))
+        if size_present:
+            size_idx = reader.read(2)
+            info["object_size_idx"] = size_idx
+            if size_idx == 1:
+                reader.read(5)
+            elif size_idx == 2:
+                reader.read(15)
+        if screen_present:
+            if reader.read(1):                      # b_object_use_screen_ref
+                reader.read(3)                      # screen_factor_bits
+                reader.read(2)                      # depth_factor_idx
+        info["snap"] = bool(reader.read(1))
+    if reader.read(1):                              # b_additional_table_data_exists
+        info["additional_table_bytes"] = reader.read(4) + 1
+        reader.skip(info["additional_table_bytes"] * 8)
+    return info
+
+
+def _parse_object_element(reader, element, raw_payload):
+    """5.5.5 ``object_element()``：时间信息 + 每个对象一条 object_info_block。"""
+    object_count = element["object_count"]
     try:
-        offset_code = reader.read(2)
-        if offset_code == 0:
+        sample_offset_code = reader.read(2)
+        if sample_offset_code == 0:
             sample_offset = 0
-        elif offset_code == 1:
+        elif sample_offset_code == 1:
             sample_offset = SAMPLE_OFFSET_INDEX[reader.read(2)]
-        elif offset_code == 2:
+        elif sample_offset_code == 2:
             sample_offset = reader.read(5)
         else:
             raise UnsupportedVariantError(
                 "oamd", "md_sample_offset_mode",
                 "OAMD 使用了当前未覆盖的 MD sample-offset 模式",
-                details={"payload": bytes_descriptor(raw_payload)})
-
+                details={
+                    "sample_offset_code": sample_offset_code,
+                    "payload": bytes_descriptor(raw_payload),
+                })
         block_count = reader.read(3) + 1
         blocks = []
         for _block in range(block_count):
             block_offset_factor = reader.read(6)
-            block_offset = sample_offset + block_offset_factor * 32
             ramp_code = reader.read(2)
             if ramp_code == 3:
                 if reader.read(1):
@@ -277,107 +318,253 @@ def _update_timing(bits, object_element, raw_payload):
                     ramp_duration = reader.read(11)
             else:
                 ramp_duration = RAMP_DURATIONS[ramp_code]
-            blocks.append((block_offset, ramp_duration))
+            blocks.append({
+                "block_offset_samples": sample_offset + block_offset_factor * 32,
+                "ramp_duration_samples": ramp_duration,
+            })
+        reserved_data_not_present = bool(reader.read(1))
+        if not reserved_data_not_present:
+            reader.read(5)
+        objects = [
+            _parse_object_info_block(
+                reader, index, index < element["bed_isf_objects"], raw_payload)
+            for index in range(object_count)
+        ]
     except UnsupportedVariantError:
         raise
     except ValueError as exc:
-        raise UnsupportedVariantError(
-            "oamd", "object_element_syntax",
-            "OAMD object element 的 timing 字段越界或不完整",
-            details={
-                "element": _element_details([object_element])[0],
-                "payload": bytes_descriptor(raw_payload),
-                "parser_error": str(exc),
-            }) from exc
+        raise _syntax_error(
+            "object_element_syntax",
+            "OAMD object element 字段越界或不完整",
+            raw_payload, exc,
+            element=_element_details([element])[0],
+            object_count=object_count,
+        ) from exc
+    return {
+        "sample_offset": sample_offset,
+        "blocks": blocks,
+        "reserved_data_not_present": reserved_data_not_present,
+        "objects": objects,
+    }
 
+
+def _parse_elements(reader, alternate_present, object_count, program, raw_payload):
+    """5.5.4 ``oa_element_md()`` 目录；对象 element 按结构解析，其余按声明长度跳过。"""
+    try:
+        element_count = reader.read(4)
+        if element_count == 0xF:
+            element_count += reader.read(5)
+    except ValueError as exc:
+        raise _syntax_error(
+            "element_count_truncated", "OAMD element 数量字段不完整",
+            raw_payload, exc) from exc
+    if element_count == 0:
+        raise UnsupportedVariantError(
+            "oamd", "missing_object_element",
+            "OAMD 没有声明任何 element",
+            details={"payload": bytes_descriptor(raw_payload)})
+
+    bed_isf_objects = program["num_bed_objects"] + program["num_isf_objects"]
+    elements = []
+    object_element = None
+    for ordinal in range(element_count):
+        header_start = reader.position
+        try:
+            element_id = reader.read(4)
+            size_bytes = _variable_bits_max(reader, 4, 4) + 1
+        except ValueError as exc:
+            raise _syntax_error(
+                "element_header_truncated", "OAMD element header 不完整",
+                raw_payload, exc,
+                element_ordinal=ordinal, header_start_bit=header_start) from exc
+        region_start = reader.position
+        region_end = region_start + size_bytes * 8
+        if region_end > reader.limit:
+            raise UnsupportedVariantError(
+                "oamd", "element_bounds",
+                "OAMD element 声明长度超过 payload 边界",
+                details={
+                    "element_ordinal": ordinal,
+                    "element_id": element_id,
+                    "size_bytes": size_bytes,
+                    "body_start_bit": region_start,
+                    "body_end_bit": region_end,
+                    "payload_bits": reader.limit,
+                    "payload": bytes_descriptor(raw_payload),
+                })
+        try:
+            alternate_data_id = (reader.read(4)
+                                 if alternate_present else None)
+            discard_unknown = bool(reader.read(1))
+        except ValueError as exc:
+            raise _syntax_error(
+                "element_control_bounds", "OAMD element 太短，无法容纳控制字段",
+                raw_payload, exc,
+                element_ordinal=ordinal, element_id=element_id,
+                size_bytes=size_bytes) from exc
+        element = {
+            "ordinal": ordinal,
+            "element_id": element_id,
+            "size_bytes": size_bytes,
+            "header_start_bit": header_start,
+            "body_start_bit": region_start,
+            "body_end_bit": region_end,
+            "data_start_bit": reader.position,
+            "alternate_data_id": alternate_data_id,
+            "discard_unknown": discard_unknown,
+            "object_count": object_count,
+            "bed_isf_objects": bed_isf_objects,
+        }
+        if element_id == OBJECT_ELEMENT_ID:
+            if object_element is not None:
+                raise UnsupportedVariantError(
+                    "oamd", "multiple_object_elements",
+                    "OAMD 含多个 object element",
+                    details={
+                        "elements": _element_details(elements + [element]),
+                        "payload": bytes_descriptor(raw_payload),
+                    })
+            object_element = _parse_object_element(
+                reader, element, raw_payload)
+            element["parsed_end_bit"] = reader.position
+            element["object_element"] = object_element
+            # 个别编码器声明的 oa_element_size 比实际内容短；以结构解析结果为准。
+            reader.position = max(region_end, reader.position)
+        else:
+            # trim / extended / 未知 element：按声明长度整体跳过（5.5.4）。
+            element["parsed_end_bit"] = region_end
+            reader.position = region_end
+        elements.append(element)
+
+    if object_element is None:
+        raise UnsupportedVariantError(
+            "oamd", "missing_object_element",
+            "OAMD 缺少 object element",
+            details={
+                "elements": _element_details(elements),
+                "payload": bytes_descriptor(raw_payload),
+            })
+    padding = reader.bits[reader.position:]
+    if np.any(padding):
+        raise UnsupportedVariantError(
+            "oamd", "nonzero_padding",
+            "OAMD payload 尾部 padding 含非零位",
+            details={
+                "elements": _element_details(elements),
+                "padding_start_bit": reader.position,
+                "padding_bits": "".join(str(int(bit)) for bit in padding[:64]),
+                "payload": bytes_descriptor(raw_payload),
+            })
+    return object_element, elements
+
+
+def frame_update(bits_one):
+    """单帧 OAMD → 位置字段增量及其 sample offset/ramp duration。"""
+    bits, raw_payload = _payload_bits(bits_one)
+    try:
+        version = bits[0] << 1 | bits[1]
+    except IndexError:
+        raise UnsupportedVariantError(
+            "oamd", "header_truncated",
+            "OAMD payload 不足以容纳 header",
+            details={"payload_bits": len(bits),
+                     "payload": bytes_descriptor(raw_payload)}) from None
+    reader = _BitReader(bits, 2)
+    try:
+        if version == 3:
+            version += reader.read(3)
+        object_count_bits = reader.read(5)
+        if object_count_bits == 0x1F:
+            object_count_bits += reader.read(7)
+        object_count = object_count_bits + 1
+        program = _parse_program_assignment(reader, raw_payload)
+        alternate_present = bool(reader.read(1))
+        object_element, elements = _parse_elements(
+            reader, alternate_present, object_count, program, raw_payload)
+    except UnsupportedVariantError:
+        raise
+    except ValueError as exc:
+        raise _syntax_error(
+            "header_truncated", "OAMD header 字段越界或不完整",
+            raw_payload, exc, payload_bits=len(bits)) from exc
+
+    if version != 0:
+        raise UnsupportedVariantError(
+            "oamd", "oamd_version",
+            "OAMD 使用了当前未覆盖的 syntax version",
+            details={
+                "version": version,
+                "payload": bytes_descriptor(raw_payload),
+            })
+    if object_count > MAX_SLOTS:
+        raise UnsupportedVariantError(
+            "oamd", "object_count",
+            "OAMD 对象数超过当前 16 槽对象模型",
+            details={
+                "object_count": object_count,
+                "max_slots": MAX_SLOTS,
+                "payload": bytes_descriptor(raw_payload),
+            })
+    blocks = object_element["blocks"]
     if len(blocks) != 1:
         raise UnsupportedVariantError(
             "oamd", "multiple_position_blocks",
-            "OAMD 一帧含多个对象位置更新块，固定位置窗口不能安全套用",
+            "OAMD 一帧含多个对象位置更新块，单次 frame_update 无法表达",
             details={
                 "block_count": len(blocks),
                 "blocks": blocks,
                 "payload": bytes_descriptor(raw_payload),
                 "repair_hint": "按 ObjectInfoBlock 顺序逐块解析坐标，再生成分段 ADM ramp",
             })
-    return blocks[0]
 
+    # 对外契约：始终给出 16 个槽；本帧没有覆盖到的槽保持上一帧位置。
+    out = {(slot, field): None for slot in range(MAX_SLOTS)
+           for field in ("q1", "q2", "q3")}
+    for info in object_element["objects"]:
+        slot = info["object"]
+        position = info.get("position")
+        if position is None:
+            # bed/ISF 对象与未激活对象没有位置字段：保持上一帧位置。
+            out[(slot, "q1")] = None
+            out[(slot, "q2")] = None
+            out[(slot, "q3")] = None
+            continue
+        x, y, z = position
+        out[(slot, "q1")] = q_of(x, N_Q12) if 0 <= x <= N_Q12 else None
+        out[(slot, "q2")] = q_of(y, N_Q12) if 0 <= y <= N_Q12 else None
+        # 5.6.1.1.10/5.6.1.1.11：pos3D_Z 带符号；当前 16 槽模型只表达非负高度。
+        out[(slot, "q3")] = q_of(z, N_Q3) if 0 <= z <= N_Q3 else (
+            0 if z < 0 else None)
 
-def frame_update(bits_one):
-    """单帧 OAMD → 位置字段增量及其 sample offset/ramp duration。"""
-    bits, raw_payload = _payload_bits(bits_one)
-    if len(bits) < 14:
-        raise UnsupportedVariantError(
-            "oamd", "header_truncated",
-            "OAMD payload 不足以容纳受支持的 header",
-            details={"payload_bits": len(bits), "payload": bytes_descriptor(raw_payload)})
-    header = {
-        "version": int((bits[0] << 1) | bits[1]),
-        "objects_minus_one": int(sum(int(bits[2 + i]) << (4 - i) for i in range(5))),
-        "dynamic_object_only": int(bits[7]),
-        "lfe_present": int(bits[8]),
-        "alternate_object_present": int(bits[9]),
-        "element_count": int(sum(int(bits[10 + i]) << (3 - i) for i in range(4))),
-    }
-    if raw_payload[:2] != b"\x1f\x88":
-        raise UnsupportedVariantError(
-            "oamd", f"header_signature_{raw_payload[:2].hex()}",
-            "OAMD header 与当前位置字段布局不一致",
-            details={
-                "supported_header_prefix_hex": "1f88",
-                "header_probe": header,
-                "payload": bytes_descriptor(raw_payload),
-                "repair_hint": "按新 header 的 program assignment 和 element 布局重新定位对象位置字段",
-            })
-    object_element, elements = _parse_elements(bits, header, 14, raw_payload)
-    if object_element["body_end_bit"] < POSITION_WINDOW_END_BIT:
-        raise UnsupportedVariantError(
-            "oamd", "object_element_too_short",
-            "OAMD object element 无法容纳当前固定位置窗口",
-            details={
-                "element": _element_details([object_element])[0],
-                "required_position_end_bit": POSITION_WINDOW_END_BIT,
-                "elements": _element_details(elements),
-                "payload": bytes_descriptor(raw_payload),
-            })
-    block_offset, ramp_duration = _update_timing(bits, object_element, raw_payload)
-    weights = 1 << np.arange(7, -1, -1)
-    out = {}
-    for obj in range(16):
-        start = 112 + 31 * (obj - 3)
-        wq1 = int((bits[start:start + 8] * weights).sum())
-        wq2 = int((bits[start + 8:start + 16] * weights).sum())
-        wq3 = int((bits[start + 16:start + 24] * weights).sum())
-        if obj and (wq1 >> 6 != 3 or wq2 & 2 != 2 or wq3 & 0x1F != 1):
-            raise UnsupportedVariantError(
-                "oamd", "position_layout_signature",
-                "OAMD 对象位置字段标记或位偏移发生变化",
-                details={
-                    "object_slot": obj,
-                    "position_start_bit": start,
-                    "q1_window_hex": f"{wq1:02x}",
-                    "q2_window_hex": f"{wq2:02x}",
-                    "q3_window_hex": f"{wq3:02x}",
-                    "header_probe": header,
-                    "elements": _element_details(elements),
-                    "payload": bytes_descriptor(raw_payload),
-                    "repair_hint": "解析 OAMD element 可选字段并更新每个对象的位置窗口偏移",
-                })
-        k1 = wq1 - Q1_OFF
-        if obj == 0:
-            out[(0, "q1")] = None
-            out[(0, "q2")] = None
-        else:
-            out[(obj, "q1")] = q_of(k1, N_Q12) if 0 <= k1 <= N_Q12 else None
-        k2 = wq2 >> 2
-        if obj != 0:
-            out[(obj, "q2")] = q_of(k2, N_Q12) if 0 <= k2 <= N_Q12 else None
-        k3 = (wq2 & 1) * 8 + (wq3 >> 5)
-        out[(obj, "q3")] = q_of(k3, N_Q3) if 0 <= k3 <= N_Q3 else None
+    size_mismatch = [
+        {
+            "element_ordinal": element["ordinal"],
+            "element_id": element["element_id"],
+            "declared_size_bytes": element["size_bytes"],
+            "declared_end_bit": element["body_end_bit"],
+            "parsed_end_bit": element["parsed_end_bit"],
+        }
+        for element in elements
+        if element["parsed_end_bit"] > element["body_end_bit"]
+    ]
     return {
         "values": out,
-        "block_offset_samples": block_offset,
-        "ramp_duration_samples": ramp_duration,
+        "block_offset_samples": blocks[0]["block_offset_samples"],
+        "ramp_duration_samples": blocks[0]["ramp_duration_samples"],
+        "object_count": object_count,
+        "program": {
+            "dynamic_object_only": program["dynamic_object_only"],
+            "lfe_present": program["lfe_present"],
+            "content_description": program["content_description"],
+            "num_bed_objects": program["num_bed_objects"],
+            "num_isf_objects": program["num_isf_objects"],
+            "num_dynamic_objects": program["num_dynamic_objects"],
+            "bed_channels": [list(assignment["channels"])
+                             for assignment in program["bed_assignments"]],
+        },
+        "elements": _element_details(elements),
+        "objects": object_element["objects"],
+        "size_mismatch": size_mismatch,
     }
 
 

src/oamd_tracks.py

@@ -5,6 +5,18 @@ from adm_atmos import q_to_adm_xyz
 from oamd_bits import JocFieldState, frame_update
 from variant_error import UnsupportedVariantError
 
+# 元数据更新时刻按渲染器处理块对齐，与 Dolby 的 processing_block_size 及
+# speaker_renderer 的 block_size 落在同一网格。
+METADATA_BLOCK_SAMPLES = 32
+
+
+def align_metadata_sample(sample, block_samples=METADATA_BLOCK_SAMPLES):
+    """把更新时刻量化到处理块边界。"""
+    block = int(block_samples)
+    if block <= 0:
+        raise ValueError("block_samples must be positive")
+    return block * ((int(sample) + block // 2 - 1) // block)
+
 
 def _lerp_xyz(start, target, amount):
     return tuple(a + (b - a) * amount for a, b in zip(start, target))
@@ -18,18 +30,19 @@ def _append_point(points, sample, xyz, interpolation_samples):
         points.append(item)
 
 
-def _expand_events_dense64(events, total_samples, rate, update_quantum_samples,
+def _expand_events_dense64(events, total_samples, rate, update_block_samples,
                            object_delay_samples, object_index):
     if not events:
         return [(0.0, 0.0, 0.0, 0.0, total_samples / float(rate), 0.0)]
 
+    block = int(update_block_samples)
     # 初始位置从成品 sample 0 起有效；合成延迟只作用于后续位置变化。
     current = events[0][1]
     points = []
     _append_point(points, 0, current, 0)
 
     for event_index, (coded_start, target, ramp_samples) in enumerate(events[1:], 1):
-        start = coded_start + object_delay_samples
+        start = align_metadata_sample(coded_start + object_delay_samples, block)
         if start >= total_samples:
             break
         if start < points[-1][0]:
@@ -43,15 +56,16 @@ def _expand_events_dense64(events, total_samples, rate, update_quantum_samples,
         if start > points[-1][0]:
             _append_point(points, start, current, 0)
 
-        effective_ramp = max(0, int(ramp_samples) - update_quantum_samples)
-        if effective_ramp == 0:
+        ramp = max(0, int(ramp_samples))
+        if ramp == 0:
             _append_point(points, start, target, 0)
             current = target
             continue
 
-        end = start + math.ceil(effective_ramp / update_quantum_samples) * update_quantum_samples
+        end = start + math.ceil(ramp / block) * block
         if event_index + 1 < len(events):
-            next_start = events[event_index + 1][0] + object_delay_samples
+            next_start = align_metadata_sample(
+                events[event_index + 1][0] + object_delay_samples, block)
             if next_start < end:
                 raise UnsupportedVariantError(
                     "oamd", "overlapping_position_ramps",
@@ -61,23 +75,23 @@ def _expand_events_dense64(events, total_samples, rate, update_quantum_samples,
                         "ramp_start_sample": start,
                         "ramp_end_sample": end,
                         "next_update_sample": next_start,
-                        "repair_hint": "按 64-sample 状态机截断旧 ramp，再从当前插值位置启动新 ramp",
+                        "repair_hint": "按 32-sample 状态机截断旧 ramp，再从当前插值位置启动新 ramp",
                     })
 
-        # 逐位置更新节拍复现状态机。1536-sample ramp 在首次 64-sample
-        # 更新后剩余 1472 samples，因此共有 23 个中间/终点坐标。
-        future = effective_ramp
+        # 从对齐后的更新点起按处理块推进，整条 ramp 覆盖 ramp_samples 个样本；
+        # 几何式逼近望远镜化简为精确线性，每个中间点都落在真实 ramp 上。
+        future = ramp
         elapsed = 0
         position = current
         while future > 0:
-            amount = min(update_quantum_samples / float(future), 1.0)
+            amount = min(block / float(future), 1.0)
             position = _lerp_xyz(position, target, amount)
-            elapsed += update_quantum_samples
+            elapsed += block
             sample = start + elapsed
             if sample >= total_samples:
                 break
-            _append_point(points, sample, position, update_quantum_samples)
-            future -= update_quantum_samples
+            _append_point(points, sample, position, block)
+            future -= block
         current = target
 
     blocks = []
@@ -94,16 +108,14 @@ def _expand_events_dense64(events, total_samples, rate, update_quantum_samples,
 
 
 
-def _compact_events(events, total_samples, rate, update_quantum_samples,
+def _compact_events(events, total_samples, rate, update_block_samples,
                     object_delay_samples, object_index):
     """Represent each linear OAMD ramp with one ADM interpolation block.
 
-    The existing dense64 representation keeps the old position at ``start``,
-    writes its first interpolated target at ``start + quantum``, and lets ADM
-    interpolate that block over one quantum. Consequently, the interpreted
-    motion begins at ``start + quantum`` and reaches the final target at
-    ``start + ramp_duration``. This compact form preserves that timing with one
-    target block whose interpolationLength is ``ramp_duration - quantum``.
+    The update instant is quantized to the processing block boundary, the motion
+    starts there immediately, and ``interpolationLength`` spans the full
+    ``ramp_duration``. The interpreted motion therefore covers
+    ``[align(start), align(start) + ramp_duration]``.
     """
     if not events:
         return [(0.0, 0.0, 0.0, 0.0, total_samples / float(rate), 0.0)]
@@ -112,15 +124,16 @@ def _compact_events(events, total_samples, rate, update_quantum_samples,
     current = events[0][1]
     _append_point(points, 0, current, 0)
 
+    block = int(update_block_samples)
     for event_index, (coded_start, target, ramp_samples) in enumerate(events[1:], 1):
-        event_start = coded_start + object_delay_samples
+        event_start = align_metadata_sample(coded_start + object_delay_samples, block)
         if event_start >= total_samples:
             break
-        effective_ramp = max(0, int(ramp_samples) - update_quantum_samples)
-        block_start = event_start + (update_quantum_samples if effective_ramp else 0)
+        ramp = max(0, int(ramp_samples))
+        block_start = event_start
         if block_start >= total_samples:
             break
-        ramp_end = block_start + effective_ramp
+        ramp_end = block_start + ramp
 
         if block_start < points[-1][0]:
             raise UnsupportedVariantError(
@@ -131,9 +144,9 @@ def _compact_events(events, total_samples, rate, update_quantum_samples,
 
         if event_index + 1 < len(events):
             next_coded_start, _, next_ramp_samples = events[event_index + 1]
-            next_event_start = next_coded_start + object_delay_samples
-            next_effective = max(0, int(next_ramp_samples) - update_quantum_samples)
-            next_block_start = next_event_start + (update_quantum_samples if next_effective else 0)
+            next_event_start = align_metadata_sample(
+                next_coded_start + object_delay_samples, block)
+            next_block_start = next_event_start
             if next_block_start < ramp_end:
                 raise UnsupportedVariantError(
                     "oamd", "overlapping_compact_position_ramps",
@@ -147,10 +160,10 @@ def _compact_events(events, total_samples, rate, update_quantum_samples,
                     })
 
         block_target = target
-        block_interpolation = effective_ramp
+        block_interpolation = ramp
         available = total_samples - block_start
-        if effective_ramp > available:
-            block_target = _lerp_xyz(current, target, available / float(effective_ramp))
+        if ramp > available:
+            block_target = _lerp_xyz(current, target, available / float(ramp))
             block_interpolation = available
         _append_point(points, block_start, block_target, block_interpolation)
         current = target
@@ -168,25 +181,26 @@ def _compact_events(events, total_samples, rate, update_quantum_samples,
     return blocks
 
 
-def _expand_events(events, total_samples, rate, update_quantum_samples,
+def _expand_events(events, total_samples, rate, update_block_samples,
                    object_delay_samples, object_index, trajectory_mode):
     if trajectory_mode == "compact":
-        return _compact_events(events, total_samples, rate, update_quantum_samples,
+        return _compact_events(events, total_samples, rate, update_block_samples,
                                object_delay_samples, object_index)
     if trajectory_mode == "dense64":
-        return _expand_events_dense64(events, total_samples, rate, update_quantum_samples,
+        return _expand_events_dense64(events, total_samples, rate, update_block_samples,
                                       object_delay_samples, object_index)
     raise ValueError(f"未知 trajectory_mode: {trajectory_mode}")
 
 def build_adm_tracks(index, frames=None, rate=48000, frame_samples=1536,
-                     update_quantum_samples=64, object_delay_samples=1473,
-                     trajectory_mode="compact"):
+                     update_block_samples=METADATA_BLOCK_SAMPLES,
+                     object_delay_samples=1473, trajectory_mode="compact"):
     """从统一 metadata index 构造 15 条 ADM 轨迹。
 
     返回 ``[(name, [(rtime,x,y,z,duration,interpolation), ...]), ...]``。
-    OAMD 的内外层 sample offset、block offset 和 ramp 均保留。
+    OAMD 的内外层 sample offset、block offset 和 ramp 均保留；更新时刻量化到
+    ``update_block_samples`` 的块边界，ramp 覆盖完整的 ramp_duration。
     ``trajectory_mode="compact"`` 用一个长 ADM interpolation block 表示每条
-    线性 ramp；``dense64`` 保留逐 64-sample 展开作为兼容回退。
+    线性 ramp；``dense64`` 保留逐块展开作为兼容回退。
     ``object_delay_samples`` 将位置更新与对象 PCM 的 decoder 输出时刻对齐。
     slot1..15 与对象 PCM ch1..15 一一对应。
     """
@@ -221,7 +235,7 @@ def build_adm_tracks(index, frames=None, rate=48000, frame_samples=1536,
     return [
         (f"JOC_Object_{obj}",
          _expand_events(events[obj - 1], total_samples, rate,
-                        update_quantum_samples, object_delay_samples, obj,
+                        update_block_samples, object_delay_samples, obj,
                         trajectory_mode))
         for obj in range(1, 16)
     ]

src/public_filterbank.py

@@ -0,0 +1,692 @@
+"""Public 64-QMF and 77-band hybrid filterbank for binaural rendering.
+
+The fixed resource is ``data/rosella_kernels.npz``: the fixed 64-QMF /
+``3 -> 8+4+4`` 77-hybrid analysis tables and the causal synthesis tables
+computed from that analysis bank.  The filter bank is publicly standardized:
+the 64-QMF → 77-hybrid structure, the 13-tap low-band prototypes and their
+half-bin complex modulation follow 3GPP TS 26.405 / ETSI TS 126 405 (Section
+5.2.2, Table 1, ``Q=8``/``Q=4``); the 64-band QMF analysis is the MPEG-4
+AAC/SBR 64 complex QMF analysis bank (ISO/IEC 14496-3/AMD1:2003, subclause
+4.B.18.2), stored here as the polyphase form
+``A[r,t] = ((-1)**t / 128) * c[63 - r + 64*t]`` of the public 640-tap SBR
+prototype.  The QMF synthesis table is the causal left inverse of that
+analysis polyphase matrix (``A @ W = P`` with the 577-sample delay
+permutation; total latency ``961 = 577 + 6*64``), stored as the rank-4
+factorization ``W[b,l] = sum_r taps[b,l,r] * basis[b,r,:]``; the hybrid
+synthesis table is the 77->64 recombination (identity for the high bands,
+signed summation of each 8+4+4 child group for the low bands), stored as a
+154-entry sparse map.  The archive and every array inside it are
+hash-validated before use, and those hashes participate in every
+compiled-HRTF cache key.  Provenance and rights boundaries are documented in
+``data/README.md`` and ``THIRD_PARTY_NOTICES.md``.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+import hashlib
+import os
+from pathlib import Path
+import zipfile
+
+import numpy as np
+
+
+PROJECT_DIR = Path(__file__).resolve().parent.parent
+DEFAULT_FILTERBANK_DATA = PROJECT_DIR / "data" / "rosella_kernels.npz"
+FILTERBANK_TABLE_VERSION = "joc-public-64qmf-77hybrid-v1"
+SAMPLE_RATE = 48000
+QMF_HOP = 64
+QMF_BANDS = 64
+HYBRID_BANDS = 77
+ANALYSIS_SYNTHESIS_LATENCY_SAMPLES = 961
+
+_ARCHIVE_SHA256 = "C05BEF4D26E96ECBD4694E2572F05DA400255C777BA5047300B9D3B1F81081CD"
+_TABLE_SPECS = {
+    "format_version": (np.dtype("<i4"), (1,),
+                       "67ABDD721024F0FF4E0B3F4C2FC13BC5BAD42D0B7851D456D88D203D15AAA450",
+                       False, False),
+    "qmf_analysis_coefficients": (
+        np.dtype("<f4"), (64, 10),
+        "AEFF6C7117D41664B9C4BF03BBF563F5319EC1B8C551F171ADBB90CF19D9D306",
+        False, False),
+    "hybrid_analysis_low_kernel": (
+        np.dtype("<f4"), (3, 2, 13, 16, 2),
+        "D00D36133B81BA699A7630C4DF1BE203FA1B7E371E595EAAEBBE8957DB322627",
+        False, False),
+    "hybrid_synthesis_indices": (
+        np.dtype("<i2"), (154, 4),
+        "F5BEB3220E4530FCF28E7F4DA7F07E821074265D118C911D61A590E00753A573",
+        True, False),
+    "hybrid_synthesis_values": (
+        np.dtype("<f4"), (154,),
+        "99409FDD9D20D1D7C2BE16BBC1E2159C8042487227C72160850745164C9CEE7F",
+        False, False),
+    "qmf_synthesis_basis": (
+        np.dtype("<f8"), (64, 4, 128),
+        "A0C4A55385F6D6C7C92D7615C83AD5FBDA51046D9EF785CAC0B9AC9A760DC527",
+        False, False),
+    "qmf_synthesis_taps": (
+        np.dtype("<f8"), (64, 10, 4),
+        "CD7756D060D51FBF02F44C1CE53CB6225B221099505C94C3F58D3BEE6F428150",
+        False, False),
+}
+
+# Hybrid-band center frequencies measured from the public analysis bank at
+# 48 kHz (positive-frequency response peaks).  They are part of the validated
+# reference behavior: the runtime uses them only for the fractional-delay band
+# phase and the project LFE low-pass, never as filterbank coefficients.
+_BAND_CENTER_FREQUENCIES_HZ = np.asarray([
+    53.19564095937407,
+    26.3876219849709,
+    140.9074183269806,
+    98.55238901464415,
+    234.09258166297573,
+    344.8745321543293,
+    321.80435900819805,
+    401.38762185365727,
+    476.19239745597804,
+    473.552388917001,
+    648.8076026837931,
+    719.8745321201852,
+    780.1254679168173,
+    851.1923973714038,
+    1023.8076024849751,
+    1155.125467695814,
+    1293.0325067063661,
+    1668.032511377253,
+    2043.0325074138086,
+    2456.967490229666,
+    2831.96748495363,
+    3206.967488172826,
+    3581.9675052705525,
+    3918.0325089666067,
+    4331.967500201844,
+    4706.967500350216,
+    5043.032510771545,
+    5456.9674914391635,
+    5831.967490225267,
+    6168.0324885741875,
+    6543.032508972284,
+    6956.96748844665,
+    7293.032503259869,
+    7668.032503551393,
+    8043.032504806491,
+    8418.032498852166,
+    8793.032502508235,
+    9206.967488589786,
+    9543.032511549152,
+    9956.967486913867,
+    10293.032513008677,
+    10668.032507835102,
+    11043.032513641429,
+    11456.967482937946,
+    11793.032513984212,
+    12206.967486015788,
+    12543.032517062376,
+    12956.96748635822,
+    13331.967492165066,
+    13706.967486991198,
+    14043.032513086031,
+    14456.967488451,
+    14793.032511410214,
+    15206.967497492202,
+    15581.967501147887,
+    15956.967495193188,
+    16331.96749644876,
+    16706.967496740173,
+    17043.03251155318,
+    17456.96749102773,
+    17831.967511425748,
+    18168.032509774734,
+    18543.032508560515,
+    18956.967489228293,
+    19293.032499649784,
+    19668.032499798002,
+    20081.967491033392,
+    20418.0324947296,
+    20793.032511827063,
+    21168.032515046092,
+    21543.032509770488,
+    21956.967492586176,
+    22331.96748862257,
+    22706.967493293465,
+    23043.03251375972,
+    23418.03251061199,
+    23831.96749768645,
+], dtype=np.float64)
+
+
+def _sha256_bytes(values: bytes) -> str:
+    return hashlib.sha256(values).hexdigest().upper()
+
+
+def _validate_npy_member_header(
+        archive: zipfile.ZipFile, member: zipfile.ZipInfo,
+        *, name: str, dtype: np.dtype, shape: tuple[int, ...],
+        allow_fortran: bool) -> None:
+    try:
+        with archive.open(member, "r") as payload:
+            version = np.lib.format.read_magic(payload)
+            if version == (1, 0):
+                actual_shape, actual_fortran_order, actual_dtype = (
+                    np.lib.format.read_array_header_1_0(
+                        payload, max_header_size=4096))
+            elif version == (2, 0):
+                actual_shape, actual_fortran_order, actual_dtype = (
+                    np.lib.format.read_array_header_2_0(
+                        payload, max_header_size=4096))
+            else:
+                raise ValueError(f"unsupported .npy version {version!r}")
+            header_size = payload.tell()
+    except (EOFError, OSError, ValueError) as exc:
+        raise ValueError(
+            f"invalid public filterbank table .npy header: {member.filename}: "
+            f"{exc}") from exc
+
+    actual_shape = tuple(actual_shape)
+    actual_dtype = np.dtype(actual_dtype)
+    if (actual_shape != shape or actual_dtype != dtype
+            or (bool(actual_fortran_order) and not allow_fortran)):
+        expected_order = "C-order" if not allow_fortran else "C- or Fortran-order"
+        actual_order = "Fortran-order" if actual_fortran_order else "C-order"
+        raise ValueError(
+            f"invalid public filterbank table .npy header for {name}: expected "
+            f"{dtype}{shape} {expected_order}, got "
+            f"{actual_dtype}{actual_shape} {actual_order}")
+    expected_size = header_size + dtype.itemsize * int(np.prod(shape))
+    if member.file_size != expected_size:
+        raise ValueError(
+            f"invalid public filterbank table .npy payload size for {name}: "
+            f"expected {expected_size} bytes including the header, "
+            f"got {member.file_size}")
+
+
+def _validate_table_members(stream) -> None:
+    expected = {name + ".npy" for name in _TABLE_SPECS}
+    limits = {
+        name + ".npy": dtype.itemsize * int(np.prod(shape)) + 4096
+        for name, (dtype, shape, _, _, _) in _TABLE_SPECS.items()
+    }
+    try:
+        stream.seek(0)
+        with zipfile.ZipFile(stream, "r") as archive:
+            members = archive.infolist()
+            if (len(members) != len(expected)
+                    or {member.filename for member in members} != expected):
+                raise ValueError(
+                    "public filterbank table archive has an invalid member set")
+            for member in members:
+                if member.flag_bits & 0x1:
+                    raise ValueError("encrypted public filterbank tables are unsupported")
+                if member.compress_type not in (
+                        zipfile.ZIP_STORED, zipfile.ZIP_DEFLATED):
+                    raise ValueError("unsupported public filterbank table compression")
+                if member.file_size > limits[member.filename]:
+                    raise ValueError(
+                        f"public filterbank table member is unexpectedly large: "
+                        f"{member.filename}")
+            if sum(member.file_size for member in members) > sum(limits.values()):
+                raise ValueError("public filterbank tables expand beyond their size limit")
+            for member in members:
+                name = member.filename[:-4]
+                dtype, shape, _, allow_fortran, _ = _TABLE_SPECS[name]
+                _validate_npy_member_header(
+                    archive, member, name=name, dtype=dtype, shape=shape,
+                    allow_fortran=allow_fortran)
+    except zipfile.BadZipFile as exc:
+        raise ValueError(f"invalid public filterbank table archive: {exc}") from exc
+
+
+@lru_cache(maxsize=2)
+def _load_tables(path_string: str) -> dict[str, np.ndarray]:
+    path = Path(path_string)
+    if not path.is_file():
+        raise FileNotFoundError(f"public filterbank table resource not found: {path}")
+    with path.open("rb") as stream:
+        archive_size = os.fstat(stream.fileno()).st_size
+        if archive_size <= 0 or archive_size > 8 << 20:
+            raise ValueError(
+                f"public filterbank table resource is unexpectedly large: {path}")
+        if path.resolve() == DEFAULT_FILTERBANK_DATA.resolve():
+            digest = hashlib.sha256()
+            for block in iter(lambda: stream.read(4 << 20), b""):
+                digest.update(block)
+            actual_archive_hash = digest.hexdigest().upper()
+            if actual_archive_hash != _ARCHIVE_SHA256:
+                raise ValueError(
+                    "public filterbank table archive hash mismatch: "
+                    f"expected {_ARCHIVE_SHA256}, got {actual_archive_hash}")
+        _validate_table_members(stream)
+        stream.seek(0)
+        with np.load(stream, allow_pickle=False) as archive:
+            if set(archive.files) != set(_TABLE_SPECS):
+                raise ValueError("public filterbank table archive has an invalid key set")
+            result: dict[str, np.ndarray] = {}
+            for name, (dtype, shape, expected_hash, _, _) in _TABLE_SPECS.items():
+                value = np.asarray(archive[name])
+                if value.dtype != dtype or value.shape != shape:
+                    raise ValueError(
+                        f"invalid public filterbank table {name}: "
+                        f"expected {dtype}{shape}, got {value.dtype}{value.shape}")
+                actual_hash = _sha256_bytes(value.tobytes(order="C"))
+                if actual_hash != expected_hash:
+                    raise ValueError(f"public filterbank table hash mismatch: {name}")
+                result[name] = np.ascontiguousarray(value)
+                result[name].setflags(write=False)
+    if int(result["format_version"][0]) != 1:
+        raise ValueError("unsupported public filterbank table format version")
+    return result
+
+
+def load_filterbank_tables(
+        path: str | Path = DEFAULT_FILTERBANK_DATA) -> dict[str, np.ndarray]:
+    """Load the validated project resource used by the public filterbank."""
+    cached = _load_tables(str(Path(path).expanduser().resolve()))
+    result = {name: value.copy() for name, value in cached.items()}
+    for value in result.values():
+        value.setflags(write=False)
+    return result
+
+
+def filterbank_fingerprint() -> dict:
+    """Return stable identifiers used in compiled-HRTF cache keys."""
+    centers = np.ascontiguousarray(_BAND_CENTER_FREQUENCIES_HZ, dtype="<f8")
+    return {
+        "table_version": FILTERBANK_TABLE_VERSION,
+        "archive_sha256": _ARCHIVE_SHA256,
+        "band_centers_sha256": _sha256_bytes(centers.tobytes(order="C")),
+        "array_sha256": {
+            name: spec[2] for name, spec in _TABLE_SPECS.items()
+        },
+    }
+
+
+class QmfAnalysis:
+    """Batchable 64-band analysis with float64 state and complex128 FFTs."""
+
+    def __init__(self, channels: int,
+                 table_data: str | Path = DEFAULT_FILTERBANK_DATA):
+        if channels <= 0:
+            raise ValueError("channels must be positive")
+        tables = load_filterbank_tables(table_data)
+        self.coefficients = np.asarray(
+            tables["qmf_analysis_coefficients"], dtype=np.float64)
+        self.channels = int(channels)
+        self.history = np.zeros((9, self.channels, 64), dtype=np.float64)
+        phase = np.arange(64, dtype=np.float64)
+        self.premod = np.exp(-1j * np.pi * phase / 128.0).astype(np.complex128)
+        self.post = np.exp(
+            -1j * 3.0 * (np.arange(64, dtype=np.float64) + 0.5) * np.pi / 128.0
+        ).astype(np.complex128)
+        self.even_post = (
+            1j * ((-1.0) ** np.arange(64, dtype=np.float64))
+        ).astype(np.complex128)
+
+    def reset(self) -> None:
+        self.history.fill(0.0)
+
+    def process_chunk(self, hops) -> np.ndarray:
+        values = np.asarray(hops, dtype=np.float64)
+        if values.ndim != 3 or values.shape[1:] != (self.channels, 64):
+            raise ValueError(f"expected [slots,{self.channels},64], got {values.shape}")
+        if not np.isfinite(values).all():
+            raise ValueError("QMF input contains non-finite values")
+        count = values.shape[0]
+        joined = np.concatenate((self.history, values), axis=0)
+        even = np.zeros_like(values)
+        odd = np.zeros_like(values)
+        for lag in range(10):
+            source = joined[9 - lag:9 - lag + count]
+            target = even if lag % 2 == 0 else odd
+            target += source * self.coefficients[:, lag][None, None, :]
+        self.history[:] = joined[-9:]
+
+        def transform(block):
+            prepared = block.astype(np.complex128, copy=False) * self.premod
+            transformed = np.fft.fft(prepared, n=128, axis=-1)[..., :64]
+            return transformed * self.post
+
+        return np.asarray(transform(odd) + transform(even) * self.even_post,
+                          dtype=np.complex128)
+
+
+class HybridAnalysis:
+    """Sparse 64-QMF to 77-hybrid analysis in float64/complex128."""
+
+    def __init__(self, channels: int,
+                 table_data: str | Path = DEFAULT_FILTERBANK_DATA):
+        if channels <= 0:
+            raise ValueError("channels must be positive")
+        tables = load_filterbank_tables(table_data)
+        self.low_kernel = np.asarray(
+            tables["hybrid_analysis_low_kernel"], dtype=np.float64)
+        self.channels = int(channels)
+        self.history = np.zeros((12, self.channels, 3, 2), dtype=np.float64)
+        self.high_history = np.zeros(
+            (6, self.channels, 61), dtype=np.complex128)
+
+    def reset(self) -> None:
+        self.history.fill(0.0)
+        self.high_history.fill(0.0)
+
+    def process_chunk(self, qmf) -> np.ndarray:
+        values = np.asarray(qmf, dtype=np.complex128)
+        if values.ndim != 3 or values.shape[1:] != (self.channels, 64):
+            raise ValueError(f"expected [slots,{self.channels},64], got {values.shape}")
+        if not np.isfinite(values).all():
+            raise ValueError("hybrid-analysis input contains non-finite values")
+        count = values.shape[0]
+        low = np.stack((values[:, :, :3].real, values[:, :, :3].imag), axis=-1)
+        joined = np.concatenate((self.history, low), axis=0)
+        output = np.zeros((count, self.channels, 77, 2), dtype=np.float64)
+        for lag in range(13):
+            source = joined[12 - lag:12 - lag + count]
+            output[:, :, :16] += np.einsum(
+                "tcpi,pibo->tcbo", source, self.low_kernel[:, :, lag],
+                dtype=np.float64, optimize=False)
+        self.history[:] = joined[-12:]
+
+        high_joined = np.concatenate((self.high_history, values[:, :, 3:]), axis=0)
+        high = high_joined[:count]
+        output[:, :, 16:, 0] = high.real
+        output[:, :, 16:, 1] = high.imag
+        self.high_history[:] = high_joined[-6:]
+        return np.asarray(output[..., 0] + 1j * output[..., 1], dtype=np.complex128)
+
+
+class HybridSynthesis:
+    """Instantaneous sparse 77-hybrid to 64-QMF synthesis map."""
+
+    def __init__(self, channels: int,
+                 table_data: str | Path = DEFAULT_FILTERBANK_DATA):
+        if channels <= 0:
+            raise ValueError("channels must be positive")
+        tables = load_filterbank_tables(table_data)
+        indices = np.asarray(tables["hybrid_synthesis_indices"], dtype=np.int64)
+        values = np.asarray(tables["hybrid_synthesis_values"], dtype=np.float64)
+        if indices.ndim != 2 or indices.shape[1] != 4 or len(indices) != len(values):
+            raise ValueError("invalid hybrid synthesis sparse table")
+        self.mapping = [
+            (int(index[0]), int(index[1]), int(index[2]), int(index[3]), float(value))
+            for index, value in zip(indices, values)
+        ]
+        self.channels = int(channels)
+
+    def reset(self) -> None:
+        return None
+
+    def process_chunk(self, hybrid) -> np.ndarray:
+        values = np.asarray(hybrid, dtype=np.complex128)
+        if values.ndim != 3 or values.shape[1:] != (self.channels, 77):
+            raise ValueError(f"expected [slots,{self.channels},77], got {values.shape}")
+        if not np.isfinite(values).all():
+            raise ValueError("hybrid-synthesis input contains non-finite values")
+        source = np.stack((values.real, values.imag), axis=-1)
+        output = np.zeros((values.shape[0], self.channels, 64, 2), dtype=np.float64)
+        for input_band, input_component, output_band, output_component, gain in self.mapping:
+            output[:, :, output_band, output_component] += (
+                source[:, :, input_band, input_component] * gain)
+        return np.asarray(output[..., 0] + 1j * output[..., 1], dtype=np.complex128)
+
+
+class QmfSynthesis:
+    """Rank-4 64-band synthesis with float64 state and accumulation."""
+
+    def __init__(self, channels: int,
+                 table_data: str | Path = DEFAULT_FILTERBANK_DATA):
+        if channels <= 0:
+            raise ValueError("channels must be positive")
+        tables = load_filterbank_tables(table_data)
+        self.basis = np.asarray(tables["qmf_synthesis_basis"], dtype=np.float64)
+        self.taps = np.asarray(tables["qmf_synthesis_taps"], dtype=np.float64)
+        if self.basis.shape != (64, 4, 128) or self.taps.shape != (64, 10, 4):
+            raise ValueError("invalid QMF synthesis factorization")
+        self.channels = int(channels)
+        self.rank = 4
+        self.history = np.zeros(
+            (9, self.channels, 64, self.rank), dtype=np.float64)
+
+    def reset(self) -> None:
+        self.history.fill(0.0)
+
+    def process_chunk(self, qmf) -> np.ndarray:
+        values = np.asarray(qmf, dtype=np.complex128)
+        if values.ndim != 3 or values.shape[1:] != (self.channels, 64):
+            raise ValueError(f"expected [slots,{self.channels},64], got {values.shape}")
+        if not np.isfinite(values).all():
+            raise ValueError("QMF-synthesis input contains non-finite values")
+        count = values.shape[0]
+        flat = np.stack((values.real, values.imag), axis=-1).reshape(
+            count * self.channels, 128)
+        modulation = self.basis.reshape(64 * self.rank, 128)
+        features = (flat @ modulation.T).reshape(
+            count, self.channels, 64, self.rank)
+        joined = np.concatenate((self.history, features), axis=0)
+        output = np.zeros((count, self.channels, 64), dtype=np.float64)
+        for lag in range(10):
+            output += np.sum(
+                joined[9 - lag:9 - lag + count]
+                * self.taps[:, lag, :][None, None, :, :],
+                axis=-1, dtype=np.float64)
+        self.history[:] = joined[-9:]
+        return output
+
+
+class PublicAnalysis77:
+    """Full-rate PCM to the public 77-band hybrid representation."""
+
+    def __init__(self, channels: int):
+        self.channels = int(channels)
+        if self.channels <= 0:
+            raise ValueError("channels must be positive")
+        self.qmf = QmfAnalysis(self.channels)
+        self.hybrid = HybridAnalysis(self.channels)
+
+    def reset(self) -> None:
+        self.qmf.reset()
+        self.hybrid.reset()
+
+    def process(self, samples) -> np.ndarray:
+        values = np.asarray(samples, dtype=np.float64)
+        if values.ndim == 1 and self.channels == 1:
+            values = values[:, None]
+        if values.ndim != 2 or values.shape[1] != self.channels:
+            raise ValueError(f"samples must have shape [N,{self.channels}]")
+        if len(values) % QMF_HOP:
+            raise ValueError("sample count must be divisible by the 64-sample QMF hop")
+        if not np.isfinite(values).all():
+            raise ValueError("samples contain non-finite values")
+        hops = values.reshape(-1, QMF_HOP, self.channels).transpose(0, 2, 1)
+        return np.asarray(
+            self.hybrid.process_chunk(self.qmf.process_chunk(hops)),
+            dtype=np.complex128)
+
+
+class PublicSynthesis77:
+    """Public 77-band hybrid representation to full-rate PCM."""
+
+    def __init__(self, channels: int):
+        self.channels = int(channels)
+        if self.channels <= 0:
+            raise ValueError("channels must be positive")
+        self.hybrid = HybridSynthesis(self.channels)
+        self.qmf = QmfSynthesis(self.channels)
+
+    def reset(self) -> None:
+        self.hybrid.reset()
+        self.qmf.reset()
+
+    def process(self, hybrid) -> np.ndarray:
+        values = np.asarray(hybrid, dtype=np.complex128)
+        if values.ndim != 3 or values.shape[1:] != (self.channels, HYBRID_BANDS):
+            raise ValueError(
+                f"hybrid must have shape [slots,{self.channels},{HYBRID_BANDS}]")
+        if not np.isfinite(values).all():
+            raise ValueError("hybrid input contains non-finite values")
+        qmf = self.hybrid.process_chunk(values)
+        time = self.qmf.process_chunk(qmf)
+        return np.asarray(time.transpose(0, 2, 1).reshape(-1, self.channels),
+                          dtype=np.float64)
+
+
+def identity_impulse_response(sample_count: int = 4096) -> np.ndarray:
+    sample_count = int(sample_count)
+    if sample_count <= 0:
+        raise ValueError("sample_count must be positive")
+    total = ((sample_count + QMF_HOP - 1) // QMF_HOP) * QMF_HOP
+    impulse = np.zeros((total, 1), dtype=np.float64)
+    impulse[0, 0] = 1.0
+    analysis = PublicAnalysis77(1)
+    synthesis = PublicSynthesis77(1)
+    return synthesis.process(analysis.process(impulse))[:, 0]
+
+
+@lru_cache(maxsize=2)
+def _hybrid_band_center_frequencies_hz_cached(rate: float) -> np.ndarray:
+    centers = np.asarray(
+        _BAND_CENTER_FREQUENCIES_HZ * (rate / SAMPLE_RATE), dtype=np.float64)
+    centers.setflags(write=False)
+    return centers
+
+
+def hybrid_band_center_frequencies_hz(
+        sample_rate_hz: float = SAMPLE_RATE) -> np.ndarray:
+    """Return the 77 hybrid-band reference center frequencies."""
+    rate = float(sample_rate_hz)
+    if not np.isfinite(rate) or rate <= 0.0:
+        raise ValueError("sample rate must be positive and finite")
+    centers = _hybrid_band_center_frequencies_hz_cached(rate).copy()
+    centers.setflags(write=False)
+    return centers
+
+
+def table_info() -> dict:
+    return {
+        "resource": DEFAULT_FILTERBANK_DATA.name,
+        "sample_rate_hz": SAMPLE_RATE,
+        "qmf_bands": QMF_BANDS,
+        "hybrid_bands": HYBRID_BANDS,
+        "hop_samples": QMF_HOP,
+        "analysis_synthesis_latency_samples": ANALYSIS_SYNTHESIS_LATENCY_SAMPLES,
+        "precision": "float64/complex128",
+        "fingerprint": filterbank_fingerprint(),
+        "provenance": {
+            "qmf": (
+                "MPEG-4 AAC/SBR 64 complex QMF analysis (ISO/IEC "
+                "14496-3/AMD1:2003 4.B.18.2), polyphase form of the public "
+                "640-tap SBR prototype"),
+            "hybrid": (
+                "3GPP TS 26.405 / ETSI TS 126 405 5.2.2 Table 1 (Q=8/Q=4) "
+                "with standard half-bin complex modulation"),
+            "synthesis": (
+                "causal left inverse of the public analysis bank "
+                "(A·W = P, 577-sample QMF delay); 77→64 sparse recombination"),
+            "resource": "data/rosella_kernels.npz",
+        },
+    }
+
+
+@lru_cache(maxsize=8)
+def _hybrid_gain_synthesis_dictionary_cached(count: int) -> np.ndarray:
+    total = int(np.ceil(
+        (ANALYSIS_SYNTHESIS_LATENCY_SAMPLES + count + 512) / QMF_HOP) * QMF_HOP)
+    impulse = np.zeros((total, 1), dtype=np.float64)
+    impulse[0, 0] = 1.0
+    base = PublicAnalysis77(1).process(impulse)[:, 0, :]
+    parameter_count = 2 * HYBRID_BANDS
+    hybrid = np.zeros(
+        (len(base), parameter_count, HYBRID_BANDS), dtype=np.complex128)
+    for band in range(HYBRID_BANDS):
+        hybrid[:, 2 * band, band] = base[:, band]
+        hybrid[:, 2 * band + 1, band] = 1j * base[:, band]
+    rendered = PublicSynthesis77(parameter_count).process(hybrid)
+    start = ANALYSIS_SYNTHESIS_LATENCY_SAMPLES
+    dictionary = np.asarray(
+        rendered[start:start + count], dtype=np.float64).copy()
+    dictionary.setflags(write=False)
+    return dictionary
+
+
+def hybrid_gain_synthesis_dictionary(sample_count: int) -> np.ndarray:
+    """Return the 154-real-parameter analysis/gain/synthesis dictionary.
+
+    Each hybrid band contributes one real-gain and one imaginary-gain column.
+    The common 961-sample filterbank latency is removed from every column.
+    """
+    count = int(sample_count)
+    if count <= 0:
+        raise ValueError("sample_count must be positive")
+    dictionary = _hybrid_gain_synthesis_dictionary_cached(count).copy()
+    dictionary.setflags(write=False)
+    return dictionary
+
+
+def project_hrir_to_hybrid_gains(
+        hrir, *, embedded_delay_samples=None,
+        sample_rate_hz: float = SAMPLE_RATE, ridge: float = 1.0e-3,
+        ) -> tuple[np.ndarray, dict]:
+    """Project FIRs and remove only a known embedded arrival delay.
+
+    Non-zero SOFA ``Data.Delay`` is external and must be passed as zero here.
+    A positive onset separated from ``Data.IR`` is de-rotated once, then restored
+    once by the runtime field.  A zero-origin FIR keeps its authored complex
+    phase and therefore also passes zero.
+    """
+    values = np.asarray(hrir, dtype=np.float64)
+    if values.ndim != 3 or values.shape[1] != 2 or values.shape[2] <= 0:
+        raise ValueError("hrir must have shape [M,2,N]")
+    if not np.isfinite(values).all():
+        raise ValueError("hrir contains non-finite values")
+    regularization = float(ridge)
+    if not np.isfinite(regularization) or regularization < 0.0:
+        raise ValueError("projection ridge must be finite and non-negative")
+    if embedded_delay_samples is None:
+        delay = np.zeros(values.shape[:2], dtype=np.float64)
+    else:
+        delay = np.asarray(embedded_delay_samples, dtype=np.float64)
+        if delay.shape != values.shape[:2] or not np.isfinite(delay).all():
+            raise ValueError("embedded_delay_samples must have finite shape [M,2]")
+    rate = float(sample_rate_hz)
+    if not np.isfinite(rate) or rate <= 0.0:
+        raise ValueError("sample_rate_hz must be positive and finite")
+
+    dictionary = _hybrid_gain_synthesis_dictionary_cached(values.shape[2])
+    gram = dictionary.T @ dictionary
+    scale = float(np.trace(gram)) / gram.shape[0]
+    system = gram + regularization * scale * np.eye(gram.shape[0], dtype=np.float64)
+    target = values.reshape(-1, values.shape[2]).T
+    parameters = np.linalg.solve(system, dictionary.T @ target).T
+    parts = parameters.reshape(values.shape[0], 2, 2 * HYBRID_BANDS)
+    transfer = np.asarray(parts[..., 0::2] + 1j * parts[..., 1::2],
+                          dtype=np.complex128)
+    centers = hybrid_band_center_frequencies_hz(rate)
+    removal_phase = np.exp(
+        2j * np.pi * delay[..., None] * centers[None, None, :] / rate)
+    aligned = np.asarray(transfer * removal_phase, dtype=np.complex128)
+
+    reconstructed = dictionary @ parameters.T
+    error = target - reconstructed
+    reference_energy = np.sum(target * target, axis=0, dtype=np.float64)
+    error_energy = np.sum(error * error, axis=0, dtype=np.float64)
+    snr = 10.0 * np.log10(
+        np.maximum(reference_energy, 1.0e-300)
+        / np.maximum(error_energy, 1.0e-300))
+    report = {
+        "method": "regularized public analysis/gain/synthesis dictionary",
+        "dictionary_shape": list(dictionary.shape),
+        "real_parameters": 2 * HYBRID_BANDS,
+        "ridge": regularization,
+        "embedded_delay_samples_min": float(np.min(delay)),
+        "embedded_delay_samples_max": float(np.max(delay)),
+        "fir_reconstruction_snr_db_median": float(np.median(snr)),
+        "fir_reconstruction_snr_db_p05": float(np.percentile(snr, 5.0)),
+        "fir_reconstruction_snr_db_min": float(np.min(snr)),
+        "maximum_absolute_hybrid_gain": float(np.max(np.abs(aligned))),
+        "precision": "float64/complex128",
+    }
+    return aligned, report
+
+
+def project_aligned_hrir_to_hybrid_gains(
+        aligned_hrir, *, ridge: float = 1.0e-3) -> tuple[np.ndarray, dict]:
+    return project_hrir_to_hybrid_gains(aligned_hrir, ridge=ridge)

src/public_room.py

@@ -0,0 +1,253 @@
+"""Project-owned image-source early reflections and shared unitary FDN."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+import numpy as np
+
+
+@dataclass(frozen=True)
+class ShoeboxRoomConfig:
+    dimensions_m: tuple[float, float, float] = (18.0, 18.0, 14.0)
+    listener_position_m: tuple[float, float, float] = (9.0, 9.0, 7.0)
+    wall_reflection_gain: tuple[float, float, float, float, float, float] = (
+        0.62, 0.60, 0.58, 0.61, 0.52, 0.56)
+    speed_of_sound_m_s: float = 343.3
+
+    def validate(self) -> None:
+        dimensions = np.asarray(self.dimensions_m, dtype=np.float64)
+        listener = np.asarray(self.listener_position_m, dtype=np.float64)
+        gains = np.asarray(self.wall_reflection_gain, dtype=np.float64)
+        if (dimensions.shape != (3,) or not np.isfinite(dimensions).all()
+                or np.any(dimensions <= 0.0)):
+            raise ValueError("room dimensions must be three positive finite values")
+        if (listener.shape != (3,) or not np.isfinite(listener).all()
+                or np.any(listener <= 0.0) or np.any(listener >= dimensions)):
+            raise ValueError("listener must be strictly inside the shoebox")
+        if (gains.shape != (6,) or not np.isfinite(gains).all()
+                or np.any(np.abs(gains) >= 1.0)):
+            raise ValueError("six finite wall gains must have magnitude below one")
+        if not math.isfinite(self.speed_of_sound_m_s) or self.speed_of_sound_m_s <= 0.0:
+            raise ValueError("speed of sound must be positive")
+
+
+@dataclass(frozen=True)
+class EarlyReflection:
+    wall: str
+    direction_adm: np.ndarray
+    path_distance_m: float
+    extra_delay_samples: float
+    reflection_gain: float
+
+
+_WALL_NAMES = ("left", "right", "back", "front", "floor", "ceiling")
+
+
+def first_order_image_sources(direction_adm, source_distance_m: float,
+                              sample_rate_hz: float,
+                              config: ShoeboxRoomConfig = ShoeboxRoomConfig()
+                              ) -> tuple[EarlyReflection, ...]:
+    """Return six first-order image-source paths for one object."""
+    config.validate()
+    direction = np.asarray(direction_adm, dtype=np.float64)
+    if direction.shape != (3,) or not np.isfinite(direction).all():
+        raise ValueError("reflection direction must contain three finite ADM values")
+    norm = float(np.linalg.norm(direction))
+    if norm <= 1.0e-15:
+        direction = np.asarray([0.0, 1.0, 0.0], dtype=np.float64)
+    else:
+        direction = direction / norm
+    distance = float(source_distance_m)
+    rate = float(sample_rate_hz)
+    if not math.isfinite(distance) or distance <= 0.0 or not math.isfinite(rate) or rate <= 0.0:
+        raise ValueError("source distance and sample rate must be positive")
+    dimensions = np.asarray(config.dimensions_m, dtype=np.float64)
+    listener = np.asarray(config.listener_position_m, dtype=np.float64)
+    source = listener + direction * distance
+    if np.any(source <= 0.0) or np.any(source >= dimensions):
+        raise ValueError(
+            "source lies outside the configured public shoebox; enlarge the room")
+    images = []
+    for axis in range(3):
+        low = source.copy()
+        low[axis] = -source[axis]
+        high = source.copy()
+        high[axis] = 2.0 * dimensions[axis] - source[axis]
+        images.extend((low, high))
+    result = []
+    for wall, image, gain in zip(_WALL_NAMES, images, config.wall_reflection_gain):
+        vector = image - listener
+        path_distance = float(np.linalg.norm(vector))
+        path_direction = vector / path_distance
+        extra = max(0.0, (path_distance - distance)
+                    * rate / config.speed_of_sound_m_s)
+        air = math.exp(-0.002 * max(path_distance - distance, 0.0))
+        result.append(EarlyReflection(
+            wall=wall,
+            direction_adm=np.asarray(path_direction, dtype=np.float64),
+            path_distance_m=path_distance,
+            extra_delay_samples=extra,
+            reflection_gain=float(gain) * air,
+        ))
+    return tuple(result)
+
+
+def normalized_hadamard4() -> np.ndarray:
+    return 0.5 * np.asarray([
+        [1.0, 1.0, 1.0, 1.0],
+        [1.0, -1.0, 1.0, -1.0],
+        [1.0, 1.0, -1.0, -1.0],
+        [1.0, -1.0, -1.0, 1.0],
+    ], dtype=np.float64)
+
+
+def _is_prime(value: int) -> bool:
+    if value < 2:
+        return False
+    if value % 2 == 0:
+        return value == 2
+    limit = int(math.sqrt(value))
+    return all(value % divisor for divisor in range(3, limit + 1, 2))
+
+
+def _next_prime(value: int) -> int:
+    candidate = max(2, int(value))
+    while not _is_prime(candidate):
+        candidate += 1
+    return candidate
+
+
+class SchroederAllpass:
+    def __init__(self, delay_samples: int, gain: float):
+        self.delay_samples = int(delay_samples)
+        self.gain = float(gain)
+        if self.delay_samples <= 0 or not 0.0 <= abs(self.gain) < 1.0:
+            raise ValueError("all-pass delay must be positive and |gain| < 1")
+        self.buffer = np.zeros(self.delay_samples, dtype=np.float64)
+        self.position = 0
+
+    def reset(self) -> None:
+        self.buffer.fill(0.0)
+        self.position = 0
+
+    def process(self, values) -> np.ndarray:
+        source = np.asarray(values, dtype=np.float64)
+        output = np.empty_like(source)
+        for index, value in enumerate(source):
+            delayed = self.buffer[self.position]
+            result = delayed - self.gain * value
+            self.buffer[self.position] = value + self.gain * result
+            self.position = (self.position + 1) % self.delay_samples
+            output[index] = result
+        return output
+
+
+@dataclass(frozen=True)
+class LateFdnConfig:
+    sample_rate_hz: float = 48000.0
+    rt60_seconds: float = 0.85
+    damping: float = 0.32
+    output_gain: float = 0.22
+    delay_seconds: tuple[float, float, float, float] = (
+        0.0297, 0.0371, 0.0411, 0.0437)
+    allpass_seconds: tuple[float, float] = (0.0023, 0.0067)
+    allpass_gain: tuple[float, float] = (0.63, 0.51)
+
+
+class SharedUnitaryFdn:
+    """One shared late room driven by the sum of all object room sends."""
+
+    def __init__(self, config: LateFdnConfig = LateFdnConfig()):
+        self.config = config
+        self.sample_rate_hz = float(config.sample_rate_hz)
+        self.rt60_seconds = float(config.rt60_seconds)
+        self.damping = float(config.damping)
+        self.output_gain = float(config.output_gain)
+        if (not math.isfinite(self.sample_rate_hz) or self.sample_rate_hz <= 0.0
+                or not math.isfinite(self.rt60_seconds) or self.rt60_seconds <= 0.0):
+            raise ValueError("FDN sample rate and RT60 must be positive and finite")
+        if (not math.isfinite(self.damping) or not 0.0 <= self.damping < 1.0
+                or not math.isfinite(self.output_gain)):
+            raise ValueError("invalid FDN damping/output gain")
+        delay_seconds = np.asarray(config.delay_seconds, dtype=np.float64)
+        allpass_seconds = np.asarray(config.allpass_seconds, dtype=np.float64)
+        allpass_gain = np.asarray(config.allpass_gain, dtype=np.float64)
+        if (delay_seconds.shape != (4,) or not np.isfinite(delay_seconds).all()
+                or np.any(delay_seconds <= 0.0)):
+            raise ValueError("FDN requires four positive finite delay times")
+        if (allpass_seconds.shape != (2,) or not np.isfinite(allpass_seconds).all()
+                or np.any(allpass_seconds <= 0.0)):
+            raise ValueError("FDN requires two positive finite all-pass delay times")
+        if (allpass_gain.shape != (2,) or not np.isfinite(allpass_gain).all()
+                or np.any(np.abs(allpass_gain) >= 1.0)):
+            raise ValueError("FDN requires two finite all-pass gains with magnitude below one")
+        self.matrix = normalized_hadamard4()
+        self.delays = np.asarray([
+            _next_prime(round(seconds * self.sample_rate_hz))
+            for seconds in delay_seconds
+        ], dtype=np.int32)
+        self.feedback_gain = np.power(
+            10.0, -3.0 * self.delays / (self.rt60_seconds * self.sample_rate_hz)
+        ).astype(np.float64)
+        self.buffers = [np.zeros(int(delay), dtype=np.float64) for delay in self.delays]
+        self.positions = np.zeros(4, dtype=np.int32)
+        self.damping_state = np.zeros(4, dtype=np.float64)
+        self.input_vector = 0.5 * np.asarray([1.0, -1.0, 1.0, 1.0], dtype=np.float64)
+        self.output_matrix = 0.5 * np.asarray([
+            [1.0, 1.0, -1.0, -1.0],
+            [1.0, -1.0, 1.0, -1.0],
+        ], dtype=np.float64)
+        self.diffusers = [
+            SchroederAllpass(
+                _next_prime(round(seconds * self.sample_rate_hz)), gain)
+            for seconds, gain in zip(allpass_seconds, allpass_gain)
+        ]
+
+    @property
+    def tail_samples(self) -> int:
+        return int(math.ceil(1.5 * self.rt60_seconds * self.sample_rate_hz))
+
+    def reset(self) -> None:
+        for buffer in self.buffers:
+            buffer.fill(0.0)
+        self.positions.fill(0)
+        self.damping_state.fill(0.0)
+        for diffuser in self.diffusers:
+            diffuser.reset()
+
+    def process(self, mono) -> np.ndarray:
+        values = np.asarray(mono, dtype=np.float64)
+        if values.ndim != 1 or not np.isfinite(values).all():
+            raise ValueError("FDN input must be one finite mono vector")
+        diffused = values
+        for diffuser in self.diffusers:
+            diffused = diffuser.process(diffused)
+        output = np.empty((len(values), 2), dtype=np.float64)
+        for sample, value in enumerate(diffused):
+            delayed = np.asarray([
+                self.buffers[line][int(self.positions[line])]
+                for line in range(4)
+            ], dtype=np.float64)
+            self.damping_state = (
+                self.damping * self.damping_state + (1.0 - self.damping) * delayed)
+            output[sample] = self.output_gain * (self.output_matrix @ self.damping_state)
+            feedback = self.matrix @ (self.damping_state * self.feedback_gain)
+            write = self.input_vector * value + feedback
+            for line in range(4):
+                position = int(self.positions[line])
+                self.buffers[line][position] = write[line]
+                self.positions[line] = (position + 1) % int(self.delays[line])
+        return output
+
+    def info(self) -> dict:
+        return {
+            "name": "SharedUnitaryFdn",
+            "sample_rate_hz": self.sample_rate_hz,
+            "rt60_seconds": self.rt60_seconds,
+            "delay_samples": [int(value) for value in self.delays],
+            "feedback_gain": [float(value) for value in self.feedback_gain],
+            "matrix_unitarity_max_error": float(
+                np.max(np.abs(self.matrix.T @ self.matrix - np.eye(4)))),
+            "allpass_delay_samples": [value.delay_samples for value in self.diffusers],
+            "precision": "float64",
+        }

src/reference_distance.py

@@ -0,0 +1,115 @@
+"""Project-owned distance policy for the public SOFA renderer."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+import numpy as np
+
+
+@dataclass(frozen=True)
+class DistanceState:
+    profile: str
+    normalized_radius: float
+    reference_distance_m: float
+    physical_distance_m: float
+    direction_adm: np.ndarray
+
+
+class ReferenceDistanceProfileV1:
+    """Reference behavior, not a claim about any external public standard."""
+
+    DISTANCE_M = {
+        "near": 1.00000465,
+        "mid": 2.19327927,
+        "far": 6.40177584,
+    }
+    MINIMUM_DISTANCE_M = 0.10
+    # Distance profiles in the reference renderer are presentation presets,
+    # not an instruction to attenuate already-authored programme PCM by 1/r.
+    # Use an energy-normalized dry/room crossfade instead.  The coefficient is
+    # an explicit project calibration target.
+    ROOM_ENERGY_COUPLING_PER_M2 = 0.01318359375
+    PUBLIC_ROOM_CALIBRATION_GAIN = 1.4
+    # Public, project-owned room coupling; it is not a SOFA or Dolby constant.
+    LATE_SEND = {
+        "near": 0.06,
+        "mid": 0.16,
+        "far": 0.28,
+    }
+
+    @classmethod
+    def validate_profile(cls, profile: str) -> str:
+        value = str(profile).strip().lower()
+        if value not in cls.DISTANCE_M:
+            raise ValueError("distance profile must be near, mid, or far")
+        return value
+
+    @classmethod
+    def map_adm_position(cls, position, profile: str) -> DistanceState:
+        name = cls.validate_profile(profile)
+        values = np.asarray(position, dtype=np.float64)
+        if values.shape != (3,) or not np.isfinite(values).all():
+            raise ValueError("ADM position must contain three finite Cartesian values")
+        radius = float(np.linalg.norm(values))
+        direction = (values / radius if radius > 1.0e-15
+                     else np.asarray([0.0, 1.0, 0.0], dtype=np.float64))
+        reference = float(cls.DISTANCE_M[name])
+        distance = max(float(cls.MINIMUM_DISTANCE_M), radius * reference)
+        return DistanceState(
+            profile=name,
+            normalized_radius=radius,
+            reference_distance_m=reference,
+            physical_distance_m=distance,
+            direction_adm=np.asarray(direction, dtype=np.float64),
+        )
+
+    @staticmethod
+    def inverse_distance_gain(measurement_radius_m: float,
+                              path_distance_m: float) -> float:
+        radius = float(measurement_radius_m)
+        distance = float(path_distance_m)
+        if not (math.isfinite(radius) and math.isfinite(distance)):
+            raise ValueError("measurement and path distances must be finite")
+        if radius <= 0.0 or distance <= 0.0:
+            raise ValueError("measurement and path distances must be positive")
+        return radius / distance
+
+    @classmethod
+    def direct_level_gain(cls, state: DistanceState) -> float:
+        """Programme-normalized direct level for a distance presentation.
+
+        Near is the SOFA reference response.  Mid/Far use an equal-power dry
+        coefficient rather than a physical free-field 1/r attenuation.  Room
+        distance still changes through image-path lengths and late send.
+        """
+        if state.profile == "near":
+            return 1.0
+        distance = float(state.physical_distance_m)
+        return 1.0 / math.sqrt(
+            1.0 + cls.ROOM_ENERGY_COUPLING_PER_M2 * distance * distance)
+
+    @classmethod
+    def room_calibration_gain(cls, state: DistanceState) -> float:
+        del state
+        return float(cls.PUBLIC_ROOM_CALIBRATION_GAIN)
+
+    @classmethod
+    def late_send(cls, state: DistanceState) -> float:
+        base = float(cls.LATE_SEND[state.profile])
+        radial = math.sqrt(max(state.normalized_radius, 0.0))
+        return base * min(max(radial, 0.25), 1.5)
+
+    @classmethod
+    def info(cls) -> dict:
+        return {
+            "name": "ReferenceDistanceProfileV1",
+            "reference_distance_m": dict(cls.DISTANCE_M),
+            "minimum_distance_m": cls.MINIMUM_DISTANCE_M,
+            "direct_level_policy": (
+                "Near unity; Mid/Far equal-power dry coefficient, never raw 1/r "
+                "programme attenuation"),
+            "room_energy_coupling_per_m2": cls.ROOM_ENERGY_COUPLING_PER_M2,
+            "public_room_calibration_gain": cls.PUBLIC_ROOM_CALIBRATION_GAIN,
+            "late_send": dict(cls.LATE_SEND),
+            "standard_claim": False,
+        }

src/renderer.py

@@ -13,7 +13,7 @@ output_scale:
 """
 import numpy as np
 
-from joc_decode import parse_joc, diff_decode, dequantize
+from joc_decode import DC_FILTER_DMX_CONFIGS, parse_joc, diff_decode, dequantize
 from joc_qmf import (N, QMF5_WINDOW, qmf_analysis_frame,
                      surround_post_frame, interp_matrix)
 from evo_unpack import unpack_evolution
@@ -60,11 +60,12 @@ class JocRenderer:
         mix_dq = dequantize(out, mix_q)
         return out, mix_q, mix_dq
 
-    def qmf_x(self, bed5, phase_new=0.0625):
+    def qmf_x(self, bed5, phase_new=0.0625, apply_dc_filter=True):
         """核心 5ch PCM → 对象矩阵使用的复数 QMF ``x``。
 
         先以 float32 对当前帧应用 phase；phase 变化时仅前 256 个样本从旧值
         线性过渡。缩放后的 L/R/C 延迟 10 槽，Ls/Rs 不延迟，再进入分析 QMF。
+        ``apply_dc_filter`` 控制 Ls/Rs band-0 的 21-tap DC 补偿。
         """
         pcm = np.asarray(bed5, dtype=np.float32)
         if pcm.shape != (5, 1536):
@@ -87,7 +88,8 @@ class JocRenderer:
         x, self._analysis_fifo = qmf_analysis_frame(self._analysis_fifo, blocks)
         self._analysis_phase = new_phase
         x[3:], self._surround_qmf_delay, self._surround_dc_hist = surround_post_frame(
-            x[3:], self._surround_qmf_delay, self._surround_dc_hist)
+            x[3:], self._surround_qmf_delay, self._surround_dc_hist,
+            apply_dc_filter=apply_dc_filter)
         return x
 
     def object_z(self, out, mix_dq, x):
@@ -244,7 +246,9 @@ class JocRenderer:
     def render_subpayloads(self, subs, bed5_pcm, lfe_pcm=None):
         """以已拆出的 EMDF payload 字典渲染一帧，避免绑定 transport 容器。"""
         out, mix_q, mix_dq = self.decode_subpayloads(subs)
-        x = self.qmf_x(bed5_pcm)
+        x = self.qmf_x(
+            bed5_pcm,
+            apply_dc_filter=out["dmx_config_idx"] in DC_FILTER_DMX_CONFIGS)
         self._last_x = x.copy()
         z_all = self.object_z(out, mix_dq, x)
         # joc_clipgain 在对象逆 QMF 后应用，并与用户 output_scale 分离。

src/rosella_binaural_renderer.py

@@ -0,0 +1,308 @@
+"""Rosella .personalized_headphone binaural renderer.
+
+Rosella JSON 解析由本项目自行实现（src/rosella_model.py），不调用任何 Dolby
+软件；.personalized_headphone 是用户经官方软件个性化扫描得到的模型文件。
+该路径与 SOFA 路径各自独立完成 HRTF/room 参数求值，只在最外层的 JOC 调度
+（1536-sample 帧缓冲、sample-timed OAMD timeline、512-sample 参数更新、输出
+包装）处汇合。
+"""
+from __future__ import annotations
+
+import hashlib
+import math
+from pathlib import Path
+
+import numpy as np
+
+from binaural_metadata import OamdPositionTimeline
+from binaural_native_renderer import NativeBinauralDsp
+from rosella_core import RosellaRenderer
+from rosella_direct import BINAURAL_PROFILE_NAMES
+from rosella_filterbank import (
+    DEFAULT_KERNEL_DATA,
+    HybridAnalysis,
+    HybridSynthesis,
+    QmfAnalysis,
+    QmfSynthesis,
+)
+from rosella_model import RosellaModel, load_personalized_headphone
+
+SAMPLE_RATE = 48000
+FRAME_SAMPLES = 1536
+ROSSELLA_BLOCK_SAMPLES = 512
+QMF_HOP_SAMPLES = 64
+ROSSELLA_LATENCY_SAMPLES = 961
+SOURCE_CHANNELS = 16
+OUTPUT_CHANNELS = 2
+PROJECT_DIR = Path(__file__).resolve().parent.parent
+DEFAULT_PERSONALIZED_HEADPHONE = (
+    PROJECT_DIR / "HRTF" / "binaural.personalized_headphone")
+
+
+def _sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for block in iter(lambda: stream.read(1 << 20), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def resolve_personalized_headphone(path: str | Path | None = None) -> Path:
+    target = (DEFAULT_PERSONALIZED_HEADPHONE if path is None
+              else Path(path).expanduser().resolve())
+    if not target.is_file():
+        raise FileNotFoundError(
+            f"未找到双耳模型：{target}\n"
+            "请将兼容模型保存为 HRTF/binaural.personalized_headphone，"
+            "或通过参数指定文件。"
+        )
+    return target
+
+
+class RosellaBinauralRenderer:
+    """Render interleaved LFE plus fifteen objects to stereo."""
+
+    def __init__(
+            self,
+            personalized_headphone: str | Path | RosellaModel,
+            *,
+            mode: str = "mid",
+            kernel_data: str | Path = DEFAULT_KERNEL_DATA,
+            object_delay_samples: int = 1473,
+            tail_seconds: float = 5.0,
+            output_gain: float = 1.0,
+            chunk_frames: int = 64,
+            room_impulse_slots: int = 4096,
+            backend: str = "python",
+            native_library=None):
+        if mode not in BINAURAL_PROFILE_NAMES:
+            raise ValueError("binaural mode must be near, mid, or far")
+        if int(object_delay_samples) < 0:
+            raise ValueError("object_delay_samples must be non-negative")
+        if float(tail_seconds) < 0.0:
+            raise ValueError("tail_seconds must be non-negative")
+        if int(chunk_frames) <= 0:
+            raise ValueError("chunk_frames must be positive")
+        if not math.isfinite(float(output_gain)):
+            raise ValueError("output_gain must be finite")
+        if backend not in ("auto", "native", "python"):
+            raise ValueError("backend must be auto, native, or python")
+
+        if isinstance(personalized_headphone, RosellaModel):
+            self.model = personalized_headphone
+            self.model_path = Path(self.model.source_path)
+        else:
+            self.model_path = resolve_personalized_headphone(personalized_headphone)
+            self.model = load_personalized_headphone(self.model_path)
+        if self.model.sample_rate != SAMPLE_RATE:
+            raise ValueError(
+                f"Rosella model sample rate must be {SAMPLE_RATE}, got {self.model.sample_rate}")
+
+        self.mode = mode
+        self.profile_index = BINAURAL_PROFILE_NAMES[mode]
+        self.kernel_data = Path(kernel_data).expanduser().resolve()
+        self.kernel_data_sha256 = _sha256_file(self.kernel_data)
+        self.object_delay_samples = int(object_delay_samples)
+        self.tail_seconds = float(tail_seconds)
+        self.output_gain = np.float64(output_gain)
+        self.chunk_frames = int(chunk_frames)
+        self.chunk_samples = self.chunk_frames * FRAME_SAMPLES
+
+        self.native_dsp = None
+        self.backend_fallback = None
+        if backend in ("auto", "native"):
+            try:
+                self.native_dsp = NativeBinauralDsp(
+                    self.model, library_path=native_library,
+                    kernel_data=self.kernel_data)
+            except (AttributeError, OSError, RuntimeError) as exc:
+                if backend == "native":
+                    raise RuntimeError(f"native binaural backend unavailable: {exc}") from exc
+                self.backend_fallback = str(exc)
+        if self.native_dsp is not None:
+            self.dsp_backend = "native"
+            self.qmf_analysis = None
+            self.hybrid_analysis = None
+            self.hybrid_synthesis = None
+            self.qmf_synthesis = None
+            self.core = RosellaRenderer(
+                self.model, SOURCE_CHANNELS, create_room=False)
+        else:
+            self.dsp_backend = "python"
+            self.qmf_analysis = QmfAnalysis(SOURCE_CHANNELS, self.kernel_data)
+            self.hybrid_analysis = HybridAnalysis(SOURCE_CHANNELS, self.kernel_data)
+            self.core = RosellaRenderer(
+                self.model, SOURCE_CHANNELS,
+                room_impulse_slots=room_impulse_slots)
+            self.hybrid_synthesis = HybridSynthesis(OUTPUT_CHANNELS, self.kernel_data)
+            self.qmf_synthesis = QmfSynthesis(OUTPUT_CHANNELS, self.kernel_data)
+        self.timeline = OamdPositionTimeline(15)
+
+        self._input_buffer = np.empty(
+            (self.chunk_samples, SOURCE_CHANNELS), dtype=np.float64)
+        self._buffer_used = 0
+        self.input_samples = 0
+        self.processed_input_samples = 0
+        self.raw_output_samples = 0
+        self.output_samples = 0
+        self.finished = False
+        self.metadata_block_updates = 0
+
+    def _append_input(self, samples: np.ndarray) -> list[np.ndarray]:
+        outputs = []
+        source = np.asarray(samples, dtype=np.float64)
+        position = 0
+        while position < len(source):
+            count = min(self.chunk_samples - self._buffer_used,
+                        len(source) - position)
+            self._input_buffer[self._buffer_used:self._buffer_used + count] = (
+                source[position:position + count])
+            self._buffer_used += count
+            position += count
+            if self._buffer_used == self.chunk_samples:
+                outputs.append(self._process_samples(self._input_buffer))
+                self._buffer_used = 0
+        return outputs
+
+    def render_frame(self, objects16, payload=None, metadata_offset=None,
+                     *, outer_sample_offset=0) -> np.ndarray:
+        """Submit one 1536-sample reconstructed frame and its ID11 payload."""
+        if self.finished:
+            raise RuntimeError("binaural renderer is already finished")
+        source = np.asarray(objects16)
+        if source.shape != (FRAME_SAMPLES, SOURCE_CHANNELS):
+            raise ValueError(
+                f"binaural frame must have shape ({FRAME_SAMPLES},{SOURCE_CHANNELS}), "
+                f"got {source.shape}")
+        frame_start = self.input_samples
+        metadata_delay = (self.object_delay_samples if metadata_offset is None
+                          else int(metadata_offset))
+        if metadata_delay < 0:
+            raise ValueError("metadata_offset must be non-negative")
+        if payload is not None:
+            self.timeline.submit_payload(
+                payload,
+                frame_start_sample=frame_start,
+                outer_sample_offset=int(outer_sample_offset),
+                object_delay_samples=metadata_delay,
+                processed_sample=self.processed_input_samples,
+            )
+            self.metadata_block_updates += 1
+        self.input_samples += FRAME_SAMPLES
+        chunks = self._append_input(source)
+        if not chunks:
+            return np.empty((0, OUTPUT_CHANNELS), dtype=np.float64)
+        return np.concatenate(chunks, axis=0) if len(chunks) > 1 else chunks[0]
+
+    def _set_block_parameters(self, sample: int):
+        positions = self.timeline.positions_at(sample)
+        self.core.set_source(0, (0.0, 1.0, 0.0), special_lfe=True)
+        for object_index in range(15):
+            self.core.set_source(
+                object_index + 1, positions[object_index], self.profile_index)
+
+    def _process_samples(self, source: np.ndarray) -> np.ndarray:
+        values = np.asarray(source, dtype=np.float64)
+        if values.ndim != 2 or values.shape[1] != SOURCE_CHANNELS:
+            raise ValueError(f"expected [samples,{SOURCE_CHANNELS}], got {values.shape}")
+        if len(values) % ROSSELLA_BLOCK_SAMPLES:
+            raise ValueError("binaural input must be divisible by 512 samples")
+        blocks = len(values) // ROSSELLA_BLOCK_SAMPLES
+        block_base = self.processed_input_samples
+
+        if self.native_dsp is not None:
+            stereo = np.empty((len(values), OUTPUT_CHANNELS), dtype=np.float64)
+            for block in range(blocks):
+                sample = block_base + block * ROSSELLA_BLOCK_SAMPLES
+                self._set_block_parameters(sample)
+                start = block * ROSSELLA_BLOCK_SAMPLES
+                stop = start + ROSSELLA_BLOCK_SAMPLES
+                stereo[start:stop] = self.native_dsp.process_block(
+                    values[start:stop], self.core.gains, self.core.room_sends,
+                    self.output_gain)
+        else:
+            hops = values.reshape(
+                blocks, ROSSELLA_BLOCK_SAMPLES // QMF_HOP_SAMPLES,
+                QMF_HOP_SAMPLES, SOURCE_CHANNELS,
+            ).transpose(0, 1, 3, 2).reshape(
+                blocks * (ROSSELLA_BLOCK_SAMPLES // QMF_HOP_SAMPLES),
+                SOURCE_CHANNELS, QMF_HOP_SAMPLES)
+            hybrid = self.hybrid_analysis.process_chunk(
+                self.qmf_analysis.process_chunk(hops))
+            direct = np.empty((blocks * 8, OUTPUT_CHANNELS, 77), dtype=np.complex128)
+            room_send = np.empty((blocks * 8, 77), dtype=np.complex128)
+            for block in range(blocks):
+                sample = block_base + block * ROSSELLA_BLOCK_SAMPLES
+                self._set_block_parameters(sample)
+                start = block * 8
+                stop = start + 8
+                direct[start:stop], room_send[start:stop] = (
+                    self.core.direct_and_send_static(hybrid[start:stop]))
+            rendered = direct + self.core.room.process_chunk(room_send)
+            time_bands = self.qmf_synthesis.process_chunk(
+                self.hybrid_synthesis.process_chunk(rendered))
+            stereo = time_bands.transpose(0, 2, 1).reshape(
+                blocks * ROSSELLA_BLOCK_SAMPLES, OUTPUT_CHANNELS)
+            stereo *= self.output_gain
+
+        skip = max(0, min(
+            len(stereo), ROSSELLA_LATENCY_SAMPLES - self.raw_output_samples))
+        self.raw_output_samples += len(stereo)
+        self.processed_input_samples += len(values)
+        output = stereo[skip:]
+        self.output_samples += len(output)
+        return output
+
+    def finish(self) -> np.ndarray:
+        """Process pending source samples and preserve the configured room tail."""
+        if self.finished:
+            return np.empty((0, OUTPUT_CHANNELS), dtype=np.float64)
+        outputs: list[np.ndarray] = []
+        if self._buffer_used:
+            outputs.append(self._process_samples(
+                self._input_buffer[:self._buffer_used]))
+            self._buffer_used = 0
+        flush_samples = math.ceil(
+            (self.tail_seconds * SAMPLE_RATE
+             + ROSSELLA_LATENCY_SAMPLES + ROSSELLA_BLOCK_SAMPLES)
+            / ROSSELLA_BLOCK_SAMPLES) * ROSSELLA_BLOCK_SAMPLES
+        while flush_samples:
+            count = min(flush_samples, self.chunk_samples)
+            zero = np.zeros((count, SOURCE_CHANNELS), dtype=np.float64)
+            outputs.append(self._process_samples(zero))
+            flush_samples -= count
+        self.finished = True
+        nonempty = [value for value in outputs if len(value)]
+        if not nonempty:
+            return np.empty((0, OUTPUT_CHANNELS), dtype=np.float64)
+        return np.concatenate(nonempty, axis=0)
+
+    def close(self):
+        if self.native_dsp is not None:
+            self.native_dsp.close()
+        self.finished = True
+
+    @property
+    def backend_info(self) -> dict:
+        return {
+            "name": self.dsp_backend,
+            "precision": "float64/complex128",
+            "fallback_reason": self.backend_fallback,
+            "library": (str(self.native_dsp.library_path)
+                        if self.native_dsp is not None else None),
+            "model": str(self.model_path.resolve()),
+            "model_coefficients": int(len(self.model.coefficients)),
+            "model_coefficient_sha256": self.model.coefficient_sha256,
+            "model_version": self.model.coefficient_version,
+            "kernel_data": str(self.kernel_data),
+            "kernel_data_sha256": self.kernel_data_sha256,
+            "mode": self.mode,
+            "latency_compensated_samples": ROSSELLA_LATENCY_SAMPLES,
+            "object_delay_samples": self.object_delay_samples,
+            "tail_seconds": self.tail_seconds,
+            "metadata_payloads": self.timeline.payload_count,
+            "metadata_position_transitions": self.timeline.transition_count,
+            "input_samples": self.input_samples,
+            "processed_samples_including_flush": self.processed_input_samples,
+            "output_samples_before_tail_trim": self.output_samples,
+        }

src/rosella_core.py

@@ -0,0 +1,81 @@
+"""Stateful float64/complex128 Rosella hybrid-band renderer."""
+from __future__ import annotations
+
+import numpy as np
+
+from rosella_direct import (
+    PROFILE_MID,
+    direct_and_room_send,
+    special_lfe_direct,
+)
+from rosella_model import RosellaModel
+from rosella_room import RosellaRoomFir
+
+
+class RosellaRenderer:
+    """Hold per-source direct parameters and the cross-block room state."""
+
+    def __init__(self, model: RosellaModel, source_count: int,
+                 room_impulse_slots: int = 4096, *, create_room: bool = True):
+        if source_count <= 0:
+            raise ValueError("source_count must be positive")
+        self.model = model
+        self.source_count = int(source_count)
+        self.room = (RosellaRoomFir(model, impulse_slots=room_impulse_slots)
+                     if create_room else None)
+        self.positions = np.zeros((self.source_count, 3), dtype=np.float64)
+        self.positions[:, 1] = 1.0
+        self.profiles = np.full(self.source_count, PROFILE_MID, dtype=np.int32)
+        self.special_lfe = np.zeros(self.source_count, dtype=bool)
+        self.gains = np.empty(
+            (self.source_count, 2, 77), dtype=np.complex128)
+        self.room_sends = np.empty(self.source_count, dtype=np.float64)
+        self._parameter_keys = [None] * self.source_count
+        for source in range(self.source_count):
+            self.set_source(source, self.positions[source], PROFILE_MID)
+
+    def reset(self):
+        if self.room is not None:
+            self.room.reset()
+
+    def set_source(self, source: int, position, profile: int = PROFILE_MID,
+                   *, special_lfe: bool = False):
+        source = int(source)
+        if not 0 <= source < self.source_count:
+            raise IndexError(source)
+        coordinates = np.asarray(position, dtype=np.float64)
+        if coordinates.shape != (3,) or not np.all(np.isfinite(coordinates)):
+            raise ValueError(f"source position must be three finite values, got {position!r}")
+        effective_profile = 0 if special_lfe else int(profile)
+        key = ((bool(special_lfe), effective_profile)
+               + tuple(float(value) for value in coordinates))
+        if self._parameter_keys[source] == key:
+            return
+        self.positions[source] = coordinates
+        self.profiles[source] = effective_profile
+        self.special_lfe[source] = bool(special_lfe)
+        parameters = (special_lfe_direct() if special_lfe else
+                      direct_and_room_send(self.model, coordinates, effective_profile))
+        self.gains[source] = parameters.gains
+        self.room_sends[source] = parameters.room_send
+        self._parameter_keys[source] = key
+
+    def direct_and_send_static(self, sources):
+        """Mix one static-parameter slot chunk without advancing room state."""
+        values = np.asarray(sources, dtype=np.complex128)
+        if values.ndim != 3 or values.shape[1:] != (self.source_count, 77):
+            raise ValueError(
+                f"expected [slots,{self.source_count},77], got {values.shape}")
+        direct = np.zeros((values.shape[0], 2, 77), dtype=np.complex128)
+        room_send = np.zeros((values.shape[0], 77), dtype=np.complex128)
+        for source in range(self.source_count - 1, -1, -1):
+            direct += values[:, source, None, :] * self.gains[source][None, :, :]
+            room_send += values[:, source, :] * self.room_sends[source]
+        return direct, room_send
+
+    def process_static_chunk(self, sources) -> np.ndarray:
+        direct, room_send = self.direct_and_send_static(sources)
+        if self.room is None:
+            raise RuntimeError("room renderer is not configured")
+        direct += self.room.process_chunk(room_send)
+        return direct

src/rosella_direct.py

@@ -0,0 +1,302 @@
+"""Float64 Rosella direction, distance, HRTF, and room-send calculations."""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import numpy as np
+
+from rosella_model import RosellaModel, direction_basis
+
+PROFILE_NEAR = 1
+PROFILE_FAR = 2
+PROFILE_MID = 3
+BINAURAL_PROFILE_NAMES = {
+    "near": PROFILE_NEAR,
+    "far": PROFILE_FAR,
+    "mid": PROFILE_MID,
+}
+
+_SPECIAL_LFE_LOW_16 = np.asarray([
+    0x402695EA, 0x3FE75979, 0x3F28CAAA, 0xBCE1FB2E,
+    0xBDD8AF65, 0xBD8F426E, 0x3D996821, 0xBC16B3A0,
+    0x3B64BAF1, 0xBC81ECFD, 0xBA3D892F, 0x3AF6A9F0,
+    0xB9DD1C5F, 0x380A193F, 0x38052059, 0x351BCB34,
+], dtype=np.uint32).view(np.float32).astype(np.float64)
+_CENTRE_EQUAL = 0.9998489618301392
+_CENTRE_ALTERNATE = 0.7070000171661377
+
+_FIELD_CACHE: dict[int, tuple[np.ndarray, np.ndarray]] = {}
+
+
+@dataclass(frozen=True)
+class DirectResult:
+    gains: np.ndarray                 # complex128 [ear=2, hybrid_band=77]
+    room_send: np.float64
+    physical_radius_m: np.float64
+    normalized_radius: np.float64
+    clamped_radius: np.float64
+    delay_samples: np.float64
+    delayed_ear: int | None
+
+
+def special_lfe_direct() -> DirectResult:
+    """Return the fixed 16-band low-pass used by a special/LFE source."""
+    mono = np.zeros(77, dtype=np.complex128)
+    mono[:16] = _SPECIAL_LFE_LOW_16
+    return DirectResult(
+        gains=np.repeat(mono[None, :], 2, axis=0),
+        room_send=np.float64(0.0),
+        physical_radius_m=np.float64(0.0),
+        normalized_radius=np.float64(0.0),
+        clamped_radius=np.float64(0.0),
+        delay_samples=np.float64(0.0),
+        delayed_ear=None,
+    )
+
+
+def _round_away_from_zero(value: float) -> int:
+    return math.floor(value + 0.5) if value >= 0.0 else math.ceil(value - 0.5)
+
+
+def _q15_position(position) -> np.ndarray:
+    """Quantize ADM Cartesian coordinates to the Rosella metadata grid.
+
+    Quantization is metadata decoding.  The returned integer lanes are promoted
+    to float64 before any geometry is evaluated.
+    """
+    x, y, z = (float(value) for value in position)
+    encoded = (
+        min(max((x + 1.0) * 0.5, 0.0), 1.0),
+        min(max((1.0 - y) * 0.5, 0.0), 1.0),
+        min(max(z, -1.0), 1.0),
+    )
+    return np.asarray([
+        min(_round_away_from_zero(value * 32768.0), 32767)
+        for value in encoded
+    ], dtype=np.int32)
+
+
+def _profile_geometry(model: RosellaModel, position, profile_index: int):
+    if profile_index not in (PROFILE_NEAR, PROFILE_FAR, PROFILE_MID):
+        raise ValueError("binaural object profile must be near, mid, or far")
+    profile = model.profiles[profile_index]
+    encoded = _q15_position(position)
+    q_front = 1.0 - 2.0 * float(encoded[1]) / 32768.0
+    q_x = 2.0 * float(encoded[0]) / 32768.0 - 1.0
+    q_vertical = float(encoded[2]) / 32768.0
+
+    if int(model.header_integer_fields[0]) != 0:
+        if q_x == 0.0 and q_front == 0.0:
+            mapped_front = 0.0
+            mapped_lateral = 0.0
+            mapped_vertical = q_vertical
+        else:
+            horizontal_max = max(abs(q_x), abs(q_front))
+            horizontal_norm = ((q_x / horizontal_max) ** 2
+                               + (q_front / horizontal_max) ** 2)
+            if q_vertical == 0.0:
+                vertical_norm = 1.0
+            else:
+                smaller = min(abs(q_vertical), horizontal_max)
+                larger = max(abs(q_vertical), horizontal_max)
+                vertical_norm = 1.0 + (smaller / larger) ** 2
+            horizontal_factor = 1.0 / math.sqrt(horizontal_norm * vertical_norm)
+            vertical_factor = 1.0 / math.sqrt(vertical_norm)
+            mapped_front = q_front * horizontal_factor
+            mapped_lateral = -q_x * horizontal_factor
+            mapped_vertical = q_vertical * vertical_factor
+    else:
+        mapped_front = q_front
+        mapped_lateral = -q_x
+        mapped_vertical = q_vertical
+
+    scales = np.asarray(profile.axis_scales_internal, dtype=np.float64)
+    scaled = np.asarray([
+        mapped_front * scales[2],
+        mapped_lateral * scales[0],
+        mapped_vertical * scales[1],
+    ], dtype=np.float64)
+    bounds = np.asarray(profile.bounds, dtype=np.float64)
+    ray = 1.0
+    for axis in range(3):
+        value = scaled[axis]
+        lower, upper = bounds[axis * 2:axis * 2 + 2]
+        if value < lower:
+            ray = min(ray, lower / value)
+        elif value > upper:
+            ray = min(ray, upper / value)
+    if ray < 1.0:
+        scaled *= ray
+
+    radius = float(np.linalg.norm(scaled))
+    clamped = max(radius, float(profile.minimum_normalized_radius))
+    alpha = radius / clamped
+    direction = (scaled / radius if radius > 1.0e-30
+                 else np.asarray([1.0, 0.0, 0.0], dtype=np.float64))
+    return profile, direction, radius, clamped, alpha
+
+
+def _logical_field(padded: np.ndarray) -> np.ndarray:
+    result = np.empty((77, 36, 2), dtype=np.float64)
+    source = np.asarray(padded, dtype=np.float64)
+    for band in range(77):
+        block, lane = divmod(band, 4)
+        for term in range(36):
+            for component in range(2):
+                result[band, term, component] = source[
+                    lane + 4 * (term * 2 + component + 72 * block)]
+    return result
+
+
+def _model_fields(model: RosellaModel) -> tuple[np.ndarray, np.ndarray]:
+    key = id(model)
+    fields = _FIELD_CACHE.get(key)
+    if fields is None:
+        fields = (_logical_field(model.field_left_padded),
+                  _logical_field(model.field_right_padded))
+        _FIELD_CACHE[key] = fields
+    return fields
+
+
+def _ear_geometry(model: RosellaModel, profile, direction, clamped: float,
+                  offset: float, correction: float):
+    x, y, z = (float(value) for value in direction)
+    inverse_distance = float(profile.inverse_distance_per_m)
+    ear = float(offset) * inverse_distance / clamped
+    y_minus = y - ear
+    y_plus = y + ear
+    common = x * x + z * z
+    length_minus = math.sqrt(y_minus * y_minus + common)
+    length_plus = math.sqrt(y_plus * y_plus + common)
+    basis_minus = direction_basis(
+        x / length_minus, y_minus / length_minus, z / length_minus,
+        dtype=np.float64)
+    basis_plus = direction_basis(
+        x / length_plus, y_plus / length_plus, z / length_plus,
+        dtype=np.float64)
+    path_minus = length_minus * clamped
+    path_plus = length_plus * clamped
+    if correction != 0.0:
+        multiplier = 2.0 * float(correction) * inverse_distance
+        path_minus += max(float(np.dot(
+            np.asarray(model.vector_left, dtype=np.float64), basis_minus)), 0.0) * multiplier
+        path_plus += max(float(np.dot(
+            np.asarray(model.vector_right, dtype=np.float64), basis_plus)), 0.0) * multiplier
+    return basis_minus, basis_plus, path_minus, path_plus
+
+
+def _phase_groups(model: RosellaModel, delay_samples: float) -> np.ndarray:
+    result = np.ones(77, dtype=np.complex128)
+    current = 1.0 + 0.0j
+    step = 1.0 + 0.0j
+    value_index = 0
+    for band, flag in enumerate(model.hybrid_flags):
+        if flag != 2:
+            if flag == 1:
+                angle = float(model.hybrid_values[value_index]) * delay_samples
+                value_index += 1
+                step = complex(math.cos(angle), math.sin(angle))
+            current *= step
+        result[band] = current
+    return result
+
+
+def direct_and_room_send(model: RosellaModel, position,
+                         profile_index: int) -> DirectResult:
+    """Evaluate one ordinary source using float64/complex128 throughout."""
+    profile, direction, radius, clamped, alpha = _profile_geometry(
+        model, position, profile_index)
+
+    _, _, path_minus, path_plus = _ear_geometry(
+        model, profile, direction, clamped,
+        float(model.model_scalars[1]), float(model.model_scalars[2]))
+    delay = (abs(path_plus - path_minus)
+             * float(profile.distance_scale_m)
+             * (float(model.sample_rate) / 343.3) * alpha)
+    delayed_ear = 0 if path_minus > path_plus else (
+        1 if path_plus > path_minus else None)
+
+    _, _, weight_minus_path, weight_plus_path = _ear_geometry(
+        model, profile, direction, clamped,
+        float(model.model_scalars[3]), float(model.model_scalars[4]))
+    weight_norm = math.sqrt(
+        weight_minus_path * weight_minus_path
+        + weight_plus_path * weight_plus_path)
+    weight_left = weight_plus_path / weight_norm
+    weight_right = weight_minus_path / weight_norm
+
+    final_offset = float(model.model_scalars[0])
+    if final_offset == 0.0:
+        basis_minus = direction_basis(*direction, dtype=np.float64)
+        basis_plus = basis_minus.copy()
+    else:
+        x, y, z = (float(value) for value in direction)
+        ear = final_offset * float(profile.inverse_distance_per_m) / clamped
+        y_minus = y - ear
+        y_plus = y + ear
+        common_length = x * x + z * z
+        length_minus = math.sqrt(y_minus * y_minus + common_length)
+        length_plus = math.sqrt(y_plus * y_plus + common_length)
+        basis_minus = direction_basis(
+            x / length_minus, y_minus / length_minus, z / length_minus,
+            dtype=np.float64)
+        basis_plus = direction_basis(
+            x / length_plus, y_plus / length_plus, z / length_plus,
+            dtype=np.float64)
+
+    field_left, field_right = _model_fields(model)
+    left_components = np.einsum(
+        "bjc,j->bc", field_left, basis_minus,
+        dtype=np.float64, optimize=False)
+    right_components = np.einsum(
+        "bjc,j->bc", field_right, basis_plus,
+        dtype=np.float64, optimize=False)
+    left = left_components[:, 0] + 1j * left_components[:, 1]
+    right = right_components[:, 0] + 1j * right_components[:, 1]
+    if delayed_ear is not None:
+        phase = _phase_groups(model, delay)
+        if delayed_ear == 0:
+            left *= phase
+        else:
+            right *= phase
+
+    effective_radius = (radius * float(model.header_float_scalars[0])
+                        * float(profile.distance_scale_m))
+    if profile_index in (PROFILE_FAR, PROFILE_MID):
+        common = 1.0 / math.sqrt(
+            1.0 + float(model.header_float_scalars[1])
+            * effective_radius * effective_radius)
+        room_send = effective_radius * common
+    else:
+        common = 1.0
+        room_send = 0.0
+
+    left_term0 = field_left[:, 0, 0] + 1j * field_left[:, 0, 1]
+    right_term0 = field_right[:, 0, 0] + 1j * field_right[:, 0, 1]
+    weights_are_default_equal = (
+        float(model.model_scalars[3]) == 0.0
+        and float(model.model_scalars[4]) == 0.0)
+    if weights_are_default_equal:
+        centre_left = weight_left * (1.0 - alpha) * _CENTRE_EQUAL
+        centre_right = centre_left
+        right_direction_weight = weight_left
+    else:
+        centre_left = (1.0 - alpha) * _CENTRE_ALTERNATE
+        centre_right = centre_left
+        right_direction_weight = weight_right
+
+    gains = np.empty((2, 77), dtype=np.complex128)
+    gains[0] = common * (
+        left * (weight_left * alpha) + left_term0 * centre_left)
+    gains[1] = common * (
+        right * (right_direction_weight * alpha) + right_term0 * centre_right)
+    return DirectResult(
+        gains=gains,
+        room_send=np.float64(room_send),
+        physical_radius_m=np.float64(float(profile.distance_scale_m) * radius),
+        normalized_radius=np.float64(radius),
+        clamped_radius=np.float64(clamped),
+        delay_samples=np.float64(delay),
+        delayed_ear=delayed_ear,
+    )

src/rosella_filterbank.py

@@ -0,0 +1,190 @@
+"""Float64/complex128 Rosella QMF and hybrid filterbanks."""
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+
+import numpy as np
+
+PROJECT_DIR = Path(__file__).resolve().parent.parent
+DEFAULT_KERNEL_DATA = PROJECT_DIR / "data" / "rosella_kernels.npz"
+
+
+@lru_cache(maxsize=4)
+def _load_tables(path_string: str) -> dict[str, np.ndarray]:
+    path = Path(path_string)
+    if not path.is_file():
+        raise FileNotFoundError(f"Rosella kernel data not found: {path}")
+    with np.load(path, allow_pickle=False) as archive:
+        version = archive["format_version"]
+        if version.shape != (1,) or int(version[0]) != 1:
+            raise ValueError(f"unsupported Rosella kernel data version in {path}")
+        return {name: archive[name].copy() for name in archive.files}
+
+
+def load_kernel_tables(path: str | Path = DEFAULT_KERNEL_DATA) -> dict[str, np.ndarray]:
+    """Load and cache the compact, production Rosella kernel tables."""
+    return _load_tables(str(Path(path).expanduser().resolve()))
+
+
+class QmfAnalysis:
+    """Batchable 64-band analysis with float64 state and complex128 FFTs."""
+
+    def __init__(self, channels: int, kernel_data: str | Path = DEFAULT_KERNEL_DATA):
+        if channels <= 0:
+            raise ValueError("channels must be positive")
+        tables = load_kernel_tables(kernel_data)
+        self.coefficients = np.asarray(
+            tables["qmf_analysis_coefficients"], dtype=np.float64)
+        if self.coefficients.shape != (64, 10):
+            raise ValueError("invalid qmf_analysis_coefficients shape")
+        self.channels = int(channels)
+        self.history = np.zeros((9, self.channels, 64), dtype=np.float64)
+        phase = np.arange(64, dtype=np.float64)
+        self.premod = np.exp(-1j * np.pi * phase / 128.0).astype(np.complex128)
+        self.post = np.exp(
+            -1j * 3.0 * (np.arange(64, dtype=np.float64) + 0.5) * np.pi / 128.0
+        ).astype(np.complex128)
+        self.even_post = (
+            1j * ((-1.0) ** np.arange(64, dtype=np.float64))
+        ).astype(np.complex128)
+
+    def reset(self):
+        self.history.fill(0.0)
+
+    def process_chunk(self, hops) -> np.ndarray:
+        values = np.asarray(hops, dtype=np.float64)
+        if values.ndim != 3 or values.shape[1:] != (self.channels, 64):
+            raise ValueError(f"expected [slots,{self.channels},64], got {values.shape}")
+        count = values.shape[0]
+        joined = np.concatenate((self.history, values), axis=0)
+        even = np.zeros_like(values)
+        odd = np.zeros_like(values)
+        for lag in range(10):
+            source = joined[9 - lag:9 - lag + count]
+            target = even if lag % 2 == 0 else odd
+            target += source * self.coefficients[:, lag][None, None, :]
+        self.history[:] = joined[-9:]
+
+        def transform(block):
+            prepared = block.astype(np.complex128, copy=False) * self.premod
+            transformed = np.fft.fft(prepared, n=128, axis=-1)[..., :64]
+            return transformed * self.post
+
+        return np.asarray(transform(odd) + transform(even) * self.even_post,
+                          dtype=np.complex128)
+
+
+class HybridAnalysis:
+    """Sparse 64-QMF to 77-hybrid analysis in float64/complex128."""
+
+    def __init__(self, channels: int, kernel_data: str | Path = DEFAULT_KERNEL_DATA):
+        if channels <= 0:
+            raise ValueError("channels must be positive")
+        tables = load_kernel_tables(kernel_data)
+        self.low_kernel = np.asarray(
+            tables["hybrid_analysis_low_kernel"], dtype=np.float64)
+        if self.low_kernel.shape != (3, 2, 13, 16, 2):
+            raise ValueError("invalid hybrid_analysis_low_kernel shape")
+        self.channels = int(channels)
+        self.history = np.zeros((12, self.channels, 3, 2), dtype=np.float64)
+        self.high_history = np.zeros(
+            (6, self.channels, 61), dtype=np.complex128)
+
+    def reset(self):
+        self.history.fill(0.0)
+        self.high_history.fill(0.0)
+
+    def process_chunk(self, qmf) -> np.ndarray:
+        values = np.asarray(qmf, dtype=np.complex128)
+        if values.ndim != 3 or values.shape[1:] != (self.channels, 64):
+            raise ValueError(f"expected [slots,{self.channels},64], got {values.shape}")
+        count = values.shape[0]
+        low = np.stack((values[:, :, :3].real, values[:, :, :3].imag), axis=-1)
+        joined = np.concatenate((self.history, low), axis=0)
+        output = np.zeros((count, self.channels, 77, 2), dtype=np.float64)
+        for lag in range(13):
+            source = joined[12 - lag:12 - lag + count]
+            output[:, :, :16] += np.einsum(
+                "tcpi,pibo->tcbo", source, self.low_kernel[:, :, lag],
+                dtype=np.float64, optimize=False)
+        self.history[:] = joined[-12:]
+
+        high_joined = np.concatenate((self.high_history, values[:, :, 3:]), axis=0)
+        high = high_joined[:count]
+        output[:, :, 16:, 0] = high.real
+        output[:, :, 16:, 1] = high.imag
+        self.high_history[:] = high_joined[-6:]
+        return np.asarray(output[..., 0] + 1j * output[..., 1], dtype=np.complex128)
+
+
+class HybridSynthesis:
+    """Instantaneous sparse 77-hybrid to 64-QMF synthesis map."""
+
+    def __init__(self, channels: int, kernel_data: str | Path = DEFAULT_KERNEL_DATA):
+        if channels <= 0:
+            raise ValueError("channels must be positive")
+        tables = load_kernel_tables(kernel_data)
+        indices = np.asarray(tables["hybrid_synthesis_indices"], dtype=np.int64)
+        values = np.asarray(tables["hybrid_synthesis_values"], dtype=np.float64)
+        if indices.ndim != 2 or indices.shape[1] != 4 or len(indices) != len(values):
+            raise ValueError("invalid hybrid synthesis sparse table")
+        self.mapping = [
+            (int(index[0]), int(index[1]), int(index[2]), int(index[3]), float(value))
+            for index, value in zip(indices, values)
+        ]
+        self.channels = int(channels)
+
+    def reset(self):
+        return None
+
+    def process_chunk(self, hybrid) -> np.ndarray:
+        values = np.asarray(hybrid, dtype=np.complex128)
+        if values.ndim != 3 or values.shape[1:] != (self.channels, 77):
+            raise ValueError(f"expected [slots,{self.channels},77], got {values.shape}")
+        source = np.stack((values.real, values.imag), axis=-1)
+        output = np.zeros((values.shape[0], self.channels, 64, 2), dtype=np.float64)
+        for input_band, input_component, output_band, output_component, gain in self.mapping:
+            output[:, :, output_band, output_component] += (
+                source[:, :, input_band, input_component] * gain)
+        return np.asarray(output[..., 0] + 1j * output[..., 1], dtype=np.complex128)
+
+
+class QmfSynthesis:
+    """Rank-4 64-band synthesis with float64 state and accumulation."""
+
+    def __init__(self, channels: int, kernel_data: str | Path = DEFAULT_KERNEL_DATA):
+        if channels <= 0:
+            raise ValueError("channels must be positive")
+        tables = load_kernel_tables(kernel_data)
+        self.basis = np.asarray(tables["qmf_synthesis_basis"], dtype=np.float64)
+        self.taps = np.asarray(tables["qmf_synthesis_taps"], dtype=np.float64)
+        if self.basis.shape != (64, 4, 128) or self.taps.shape != (64, 10, 4):
+            raise ValueError("invalid QMF synthesis factorization")
+        self.channels = int(channels)
+        self.rank = 4
+        self.history = np.zeros(
+            (9, self.channels, 64, self.rank), dtype=np.float64)
+
+    def reset(self):
+        self.history.fill(0.0)
+
+    def process_chunk(self, qmf) -> np.ndarray:
+        values = np.asarray(qmf, dtype=np.complex128)
+        if values.ndim != 3 or values.shape[1:] != (self.channels, 64):
+            raise ValueError(f"expected [slots,{self.channels},64], got {values.shape}")
+        count = values.shape[0]
+        flat = np.stack((values.real, values.imag), axis=-1).reshape(
+            count * self.channels, 128)
+        modulation = self.basis.reshape(64 * self.rank, 128)
+        features = (flat @ modulation.T).reshape(
+            count, self.channels, 64, self.rank)
+        joined = np.concatenate((self.history, features), axis=0)
+        output = np.zeros((count, self.channels, 64), dtype=np.float64)
+        for lag in range(10):
+            output += np.sum(
+                joined[9 - lag:9 - lag + count]
+                * self.taps[:, lag, :][None, None, :, :],
+                axis=-1, dtype=np.float64)
+        self.history[:] = joined[-9:]
+        return output

src/rosella_model.py

@@ -0,0 +1,517 @@
+"""Parser for ``.personalized_headphone`` and raw ``rp`` models."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from numbers import Real
+import struct
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+
+
+Q15 = np.float32(1.0 / 32768.0)
+
+
+def _f32(value) -> np.float32:
+    return np.float32(value)
+
+
+def _q15(value: int) -> np.float32:
+    return _f32(_f32(value) * Q15)
+
+
+def _q15_exp(value: int, exponent: int) -> np.float32:
+    return _f32(_q15(value) * _f32(np.ldexp(1.0, exponent)))
+
+
+@dataclass(frozen=True)
+class DistanceProfile:
+    bounds: np.ndarray
+    distance_scale_m: np.float32
+    inverse_distance_per_m: np.float32
+    axis_scales_internal: np.ndarray
+    minimum_normalized_radius: np.float32
+
+    @property
+    def floats(self) -> np.ndarray:
+        return np.concatenate((
+            self.bounds,
+            np.asarray([self.distance_scale_m,
+                        self.inverse_distance_per_m], dtype=np.float32),
+            self.axis_scales_internal,
+            np.asarray([self.minimum_normalized_radius], dtype=np.float32),
+        ))
+
+
+@dataclass(frozen=True)
+class RosellaModel:
+    source_path: str
+    coefficients: np.ndarray
+    coefficient_sha256: str
+    coefficient_version: str | None
+    room_model: str | None
+    table_a_dimension: int
+    table_a_option: int
+    table_a_extra: int
+    table_a_header_field: int
+    table_a_header_25: int
+    table_a_control: int
+    table_a_option_ids: np.ndarray
+    table_a_option_values: np.ndarray
+    table_a_scalar: np.float32
+    table_a_filter_16x64_padded: np.ndarray
+    table_a_four_integers: np.ndarray
+    table_a_integer: int
+    table_a_filter_8x64_padded: np.ndarray
+    table_a_vector16: np.ndarray
+    table_a_filter_4x64_padded: np.ndarray
+    table_a_extra_indices: np.ndarray
+    table_a_extra_fields_padded: np.ndarray
+    table_a_extra_vectors: np.ndarray
+    sample_rate: int
+    matrix_exponent: int
+    field_exponent: int
+    matrix_left: np.ndarray
+    matrix_right: np.ndarray
+    vector_left: np.ndarray
+    vector_right: np.ndarray
+    field_left_padded: np.ndarray
+    field_right_padded: np.ndarray
+    field_left_odd_serialized_zero: bool
+    hybrid_flags: np.ndarray
+    hybrid_values: np.ndarray
+    model_scalars: np.ndarray
+    header_float_scalars: np.ndarray
+    header_integer_fields: np.ndarray
+    profiles: tuple[DistanceProfile, ...]
+    profile_tail: np.ndarray
+    post_fields: np.ndarray
+    table_a_main_serialized: np.ndarray
+
+
+def _lane(data: bytes, index: int) -> int:
+    if (index + 1) * 4 > len(data):
+        raise ValueError(f"Rosella rp truncated before int32 lane {index}")
+    return struct.unpack_from("<I", data, index * 4)[0]
+
+
+def inspect_rp(data: bytes) -> dict:
+    """Return the active-lane layout and checksum status for one raw rp image."""
+    if len(data) < 20 or len(data) % 4:
+        raise ValueError("Rosella rp must contain whole little-endian int32 lanes")
+    if _lane(data, 0) != 0x7072:
+        raise ValueError(f"bad Rosella rp magic: 0x{_lane(data, 0):08X}")
+
+    low16 = lambda value: value & 0xFFFF
+    checksum = low16(_lane(data, 1))
+    table_a_present = low16(_lane(data, 2))
+    table_b_present = low16(_lane(data, 3))
+    table_c_present = low16(_lane(data, 4))
+    index = 5
+    if table_a_present:
+        table_a_dimension = low16(_lane(data, index))
+        table_a_option = low16(_lane(data, index + 1))
+        table_a_extra = low16(_lane(data, index + 2))
+        index += 5
+    else:
+        table_a_dimension, table_a_option, table_a_extra = 77, 0, 0
+    if table_b_present:
+        if not table_a_present:
+            raise ValueError("Rosella rp table B cannot be present without table A")
+        table_b_dimension = low16(_lane(data, index))
+        table_b_extra = low16(_lane(data, index + 1))
+        table_b_groups = low16(_lane(data, index + 2))
+        index += 3
+    else:
+        table_b_dimension = table_b_extra = table_b_groups = 0
+    if table_c_present:
+        table_c_dimension = low16(_lane(data, index))
+        index += 1
+    else:
+        table_c_dimension = 0
+
+    payload_words = (
+        (index - 2)
+        + table_b_present * (
+            table_b_dimension + 380 * table_b_groups + table_b_extra + 79)
+        + table_a_present * (
+            171 * table_a_extra + 79 + 2 * (table_a_option + 14 * table_a_dimension))
+        + 11
+        + table_c_present * (314 * table_c_dimension + 1)
+    )
+    total_lanes = 2 + payload_words
+    if len(data) < total_lanes * 4:
+        raise ValueError(
+            f"Rosella rp truncated: need {total_lanes * 4} bytes, have {len(data)}")
+    computed = 0xA569
+    for lane_index in range(2, total_lanes):
+        computed ^= low16(_lane(data, lane_index))
+    computed &= 0xFFFF
+    return {
+        "stored_checksum": checksum,
+        "computed_checksum": computed,
+        "checksum_valid": computed == checksum,
+        "table_a_present": table_a_present,
+        "table_b_present": table_b_present,
+        "table_c_present": table_c_present,
+        "table_a_dimension": table_a_dimension,
+        "table_a_option": table_a_option,
+        "table_a_extra": table_a_extra,
+        "table_b_dimension": table_b_dimension,
+        "table_b_extra": table_b_extra,
+        "table_b_groups": table_b_groups,
+        "table_c_dimension": table_c_dimension,
+        "active_int32_lanes": total_lanes,
+    }
+
+
+def _json_int32(values) -> np.ndarray:
+    if not isinstance(values, list):
+        raise ValueError("rosella_coefficients must be a JSON array")
+    result = np.empty(len(values), dtype=np.int32)
+    for index, value in enumerate(values):
+        if isinstance(value, bool) or not isinstance(value, Real):
+            raise ValueError(f"rosella_coefficients[{index}] is not a number")
+        numeric = float(value)
+        if not math.isfinite(numeric) or numeric != math.trunc(numeric):
+            raise ValueError(
+                f"rosella_coefficients[{index}] is not an exact integer: {value!r}")
+        integer = int(value)
+        if integer < -(1 << 31) or integer > (1 << 31) - 1:
+            raise ValueError(
+                f"rosella_coefficients[{index}] is outside signed int32: {integer}")
+        result[index] = integer
+    return result
+
+
+def _load_coefficients(path: Path) -> tuple[np.ndarray, str | None, str | None]:
+    if not path.is_file():
+        raise FileNotFoundError(path)
+    source = path.read_bytes()
+    stripped = source.lstrip()
+    if stripped.startswith(b"{"):
+        try:
+            document = json.loads(source.decode("utf-8"))
+            virtualizer = document["personalized_hrtf"]["virtualizer_parameters"]
+            coefficients = _json_int32(virtualizer["rosella_coefficients"])
+        except (UnicodeDecodeError, json.JSONDecodeError, KeyError, TypeError) as exc:
+            raise ValueError(f"invalid personalized_headphone JSON: {exc}") from exc
+        version = virtualizer.get("rosella_coefficients_version")
+        room = virtualizer.get("room_model")
+    else:
+        if len(source) % 4:
+            raise ValueError("raw rp payload must contain complete int32 lanes")
+        coefficients = np.frombuffer(source, dtype="<i4").copy()
+        version = room = None
+    return coefficients, version, room
+
+
+def _unpack_field(serialized: np.ndarray, directions: int,
+                  exponent: int) -> np.ndarray:
+    expected = 154 * directions
+    if serialized.size != expected:
+        raise ValueError(f"expected {expected} field lanes, got {serialized.size}")
+    padded = np.zeros(160 * directions, dtype=np.float32)
+    stride8 = 8 * directions
+    stride2 = 2 * directions
+    for source_index, value in enumerate(serialized):
+        group4 = (source_index % stride8) // stride2
+        destination = ((group4 & 3) + 4 * (
+            source_index % stride2 +
+            2 * directions * (source_index // stride8 + (group4 >> 2))))
+        padded[destination] = _q15_exp(int(value), exponent)
+    return padded
+
+
+def _unpack_table_a_grid(serialized: np.ndarray, dimension: int,
+                         serialized_rows: int, padded_rows: int,
+                         lane_group: int) -> np.ndarray:
+    if serialized.size != serialized_rows * dimension:
+        raise ValueError("unexpected table-A grid size")
+    padded = np.zeros(padded_rows * dimension, dtype=np.float32)
+    group_width = lane_group * 4
+    for source_index, value in enumerate(serialized):
+        remainder = source_index % group_width
+        destination = ((remainder // lane_group) + 4 * (
+            remainder % lane_group +
+            group_width // 4 * (source_index // group_width)))
+        padded[destination] = _q15(int(value))
+    return padded
+
+
+def _unpack_table_a_extra(serialized: np.ndarray) -> np.ndarray:
+    if serialized.size != 154:
+        raise ValueError("table-A extra field must contain 154 serialized values")
+    padded = np.zeros(160, dtype=np.float32)
+    for source_index, value in enumerate(serialized):
+        remainder = source_index & 7
+        destination = ((remainder >> 1) + 4 * (
+            (source_index & 1) + 2 * (source_index >> 3)))
+        padded[destination] = _q15(int(value))
+    return padded
+
+
+def _parse_profile(values: np.ndarray, position: int) -> tuple[DistanceProfile, int]:
+    bounds = np.asarray([_q15(int(value)) for value in values[position:position + 6]],
+                        dtype=np.float32)
+    position += 6
+    distance = _q15_exp(int(values[position]), int(values[position + 1]))
+    position += 2
+    remaining = np.asarray(
+        [_q15(int(value)) for value in values[position:position + 5]],
+        dtype=np.float32)
+    position += 5
+    return DistanceProfile(
+        bounds=bounds,
+        distance_scale_m=distance,
+        inverse_distance_per_m=remaining[0],
+        axis_scales_internal=remaining[1:4],
+        minimum_normalized_radius=remaining[4],
+    ), position
+
+
+def load_personalized_headphone(path: str | Path) -> RosellaModel:
+    path = Path(path).resolve()
+    coefficients, version, room = _load_coefficients(path)
+    raw = coefficients.astype("<i4", copy=False).tobytes()
+    header = inspect_rp(raw)
+    if not header["checksum_valid"] or header["active_int32_lanes"] != coefficients.size:
+        raise ValueError("invalid or non-active Rosella rp coefficient sequence")
+    if not header["table_a_present"] or not header["table_b_present"] or header["table_c_present"]:
+        raise NotImplementedError("current local renderer requires table A+B and no table C")
+    if header["table_a_dimension"] != 64 or header["table_a_option"] != 3:
+        raise NotImplementedError("current local renderer requires the observed 64-channel HQMF layout")
+    if header["table_b_dimension"] != 20 or header["table_b_groups"] != 36:
+        raise NotImplementedError("current local renderer requires 20 hybrid groups and 36 direction terms")
+
+    values = coefficients
+    extra = header["table_a_extra"]
+    table_a_main_start = 13
+    position = table_a_main_start
+    table_a_control = int(values[position]) & 0xFFFF
+    field_exponent = int(values[position])
+    position += 1
+    option_count = header["table_a_option"]
+    option_ids = (values[position:position + option_count].astype(np.int64) &
+                  0xFFFF).astype(np.int32)
+    position += option_count
+    option_values = np.asarray(
+        [_q15(int(value)) for value in values[position:position + option_count]],
+        dtype=np.float32)
+    position += option_count
+    table_a_scalar = _q15(int(values[position]))
+    position += 1
+    dimension = header["table_a_dimension"]
+    table_a_filter_16x64 = _unpack_table_a_grid(
+        values[position:position + 16 * dimension], dimension, 16, 20, 16)
+    position += 16 * dimension
+    table_a_four_integers = (values[position:position + 4].astype(np.int64) &
+                             0xFFFF).astype(np.int32)
+    position += 4
+    table_a_integer = int(values[position]) & 0xFFFF
+    position += 1
+    table_a_filter_8x64 = _unpack_table_a_grid(
+        values[position:position + 8 * dimension], dimension, 8, 10, 8)
+    position += 8 * dimension
+    table_a_vector16 = np.asarray(
+        [_q15(int(value)) for value in values[position:position + 16]],
+        dtype=np.float32)
+    position += 16
+    table_a_filter_4x64 = _unpack_table_a_grid(
+        values[position:position + 4 * dimension], dimension, 4, 5, 4)
+    position += 4 * dimension
+    extra_indices = (values[position:position + extra].astype(np.int64) &
+                     0xFFFF).astype(np.int32)
+    position += extra
+    extra_fields = np.empty((extra, 160), dtype=np.float32)
+    for index in range(extra):
+        extra_fields[index] = _unpack_table_a_extra(values[position:position + 154])
+        position += 154
+    extra_vectors = np.empty((extra, 16), dtype=np.float32)
+    for index in range(extra):
+        extra_vectors[index] = np.asarray(
+            [_q15(int(value)) for value in values[position:position + 16]],
+            dtype=np.float32)
+        position += 16
+    table_b_start = position
+    expected_table_b_start = table_a_main_start + 1821 + 171 * extra
+    if table_b_start != expected_table_b_start:
+        raise AssertionError(
+            f"table-A parser ended at {table_b_start}, expected {expected_table_b_start}")
+    table_a_main = values[table_a_main_start:table_b_start].copy()
+
+    sample_rate = 2 * (int(values[position]) & 0xFFFF)
+    position += 1
+    matrix_exponent = int(values[position])
+    position += 1
+    matrix_count = 36 * 36
+    scale_matrix = lambda block: np.asarray(
+        [_q15_exp(int(value), matrix_exponent) for value in block],
+        dtype=np.float32).reshape(36, 36)
+    matrix_left = scale_matrix(values[position:position + matrix_count])
+    position += matrix_count
+    matrix_right = scale_matrix(values[position:position + matrix_count])
+    position += matrix_count
+    vector_left = np.asarray(
+        [_q15_exp(int(value), matrix_exponent)
+         for value in values[position:position + 36]], dtype=np.float32)
+    position += 36
+    vector_right = np.asarray(
+        [_q15_exp(int(value), matrix_exponent)
+         for value in values[position:position + 36]], dtype=np.float32)
+    position += 36
+
+    serialized_count = 154 * 36
+    field_left_serialized = values[position:position + serialized_count]
+    field_left = _unpack_field(field_left_serialized, 36, field_exponent)
+    field_left_odd_zero = not np.any(
+        np.abs(np.asarray([_q15_exp(int(value), field_exponent)
+                           for value in field_left_serialized[1::2]],
+                          dtype=np.float32)) > np.float32(1e-6))
+    position += serialized_count
+    field_right = _unpack_field(
+        values[position:position + serialized_count], 36, field_exponent)
+    position += serialized_count
+
+    hybrid_flags = (values[position:position + 20].astype(np.int64) & 0xFFFF).astype(np.int32)
+    position += 20
+    active_hybrid_values = int(np.count_nonzero(hybrid_flags == 1))
+    if active_hybrid_values != header["table_b_extra"]:
+        raise ValueError(
+            f"hybrid value count {active_hybrid_values} != header {header['table_b_extra']}")
+    hybrid_values = np.asarray(
+        [_q15(int(value)) for value in values[position:position + active_hybrid_values]],
+        dtype=np.float32)
+    position += active_hybrid_values
+    model_scalars = np.asarray(
+        [_q15(int(value)) for value in values[position:position + 5]],
+        dtype=np.float32)
+    position += 5
+
+    expected_table_a_tail = table_b_start + (
+        header["table_b_dimension"] +
+        380 * header["table_b_groups"] +
+        header["table_b_extra"] + 79)
+    if position != expected_table_a_tail:
+        raise AssertionError(f"table-B parser ended at {position}, expected {expected_table_a_tail}")
+
+    header_float_scalars = np.asarray([
+        _q15(int(values[position])),
+        _f32(_q15(int(values[position + 1])) * _f32(16.0)),
+    ], dtype=np.float32)
+    header_integer_fields = np.asarray([
+        int(values[position + 2]),
+        int(values[position + 3]) & 0xFFFF,
+    ], dtype=np.int32)
+    position += 4
+    profiles = []
+    for _ in range(4):
+        profile, position = _parse_profile(values, position)
+        profiles.append(profile)
+    profile_tail = np.asarray(
+        [_q15(int(value)) for value in values[position:position + 8]],
+        dtype=np.float32)
+    position += 8
+    post_fields = values[position:position + 3].astype(np.int32, copy=True)
+    position += 3
+    if position != values.size:
+        raise AssertionError(f"unparsed coefficient lanes: {values.size - position}")
+
+    return RosellaModel(
+        source_path=str(path),
+        coefficients=coefficients,
+        coefficient_sha256=hashlib.sha256(raw).hexdigest(),
+        coefficient_version=version,
+        room_model=room,
+        table_a_dimension=header["table_a_dimension"],
+        table_a_option=header["table_a_option"],
+        table_a_extra=extra,
+        table_a_header_field=int(values[8]) & 0xFFFF,
+        table_a_header_25=int(values[9]) & 0xFFFF,
+        table_a_control=table_a_control,
+        table_a_option_ids=option_ids,
+        table_a_option_values=option_values,
+        table_a_scalar=table_a_scalar,
+        table_a_filter_16x64_padded=table_a_filter_16x64,
+        table_a_four_integers=table_a_four_integers,
+        table_a_integer=table_a_integer,
+        table_a_filter_8x64_padded=table_a_filter_8x64,
+        table_a_vector16=table_a_vector16,
+        table_a_filter_4x64_padded=table_a_filter_4x64,
+        table_a_extra_indices=extra_indices,
+        table_a_extra_fields_padded=extra_fields,
+        table_a_extra_vectors=extra_vectors,
+        sample_rate=sample_rate,
+        matrix_exponent=matrix_exponent,
+        field_exponent=field_exponent,
+        matrix_left=matrix_left,
+        matrix_right=matrix_right,
+        vector_left=vector_left,
+        vector_right=vector_right,
+        field_left_padded=field_left,
+        field_right_padded=field_right,
+        field_left_odd_serialized_zero=field_left_odd_zero,
+        hybrid_flags=hybrid_flags,
+        hybrid_values=hybrid_values,
+        model_scalars=model_scalars,
+        header_float_scalars=header_float_scalars,
+        header_integer_fields=header_integer_fields,
+        profiles=tuple(profiles),
+        profile_tail=profile_tail,
+        post_fields=post_fields,
+        table_a_main_serialized=table_a_main,
+    )
+
+
+def direction_basis(x: float, y: float, z: float,
+                    dtype=np.float64) -> np.ndarray:
+    """Return the observed 36-term Rosella direction basis."""
+    f = dtype
+    x, y, z = f(x), f(y), f(z)
+    out = np.empty(36, dtype=dtype)
+    yz = f(y * z)
+    x2 = f(x * x)
+    y2 = f(y * y)
+    x2m02 = f(x2 - f(0.2))
+    xy = f(x * y)
+    out[0:4] = (f(1.0), x, y, z)
+    out[4] = f(x2 - f(1.0 / 3.0))
+    out[5] = xy
+    out[6] = f(x * z)
+    out[7] = f(y2 - f(1.0 / 3.0))
+    out[8] = yz
+    out[9] = f(f(x2 - f(0.6)) * x)
+    out[10] = f(x2m02 * y)
+    out[11] = f(x2m02 * z)
+    out[12] = f(f(y2 - f(0.2)) * x)
+    out[13] = f(yz * x)
+    out[14] = f(f(y2 - f(0.6)) * y)
+    out[15] = f(f(y2 - f(0.2)) * z)
+    out[16] = f(f(x2 * x2) - f(0.2))
+    out[17] = f(xy * x2)
+    out[18] = f(f(x * z) * x2)
+    out[19] = f(f(y2 * x2) - f(1.0 / 15.0))
+    out[20] = f(yz * x2)
+    out[21] = f(x * y2 * y)
+    out[22] = f(x * y2 * z)
+    out[23] = f(f(y2 * y2) - f(0.2))
+    x4 = f(x2 * x2)
+    x2y2 = f(y2 * x2)
+    y4 = f(y2 * y2)
+    out[24] = f(yz * y2)
+    out[25] = f(f(x4 - f(3.0 / 7.0)) * x)
+    out[26] = f(f(x4 - f(3.0 / 35.0)) * y)
+    out[27] = f(f(x4 - f(3.0 / 35.0)) * z)
+    out[28] = f(f(x2y2 - f(3.0 / 35.0)) * x)
+    out[29] = f(f(x2 * z) * xy)
+    out[30] = f(f(x2y2 - f(3.0 / 35.0)) * y)
+    out[31] = f(f(x2y2 - f(1.0 / 35.0)) * z)
+    out[32] = f(f(y4 - f(3.0 / 35.0)) * x)
+    out[33] = f(f(y2 * z) * xy)
+    out[34] = f(f(y4 - f(3.0 / 7.0)) * y)
+    out[35] = f(f(y4 - f(3.0 / 35.0)) * z)
+    return out

src/rosella_room.py

@@ -0,0 +1,198 @@
+"""Float64 Rosella table-A room model and overlap-add realization."""
+from __future__ import annotations
+
+import numpy as np
+
+from rosella_model import RosellaModel
+
+
+class _RosellaRoomState:
+    """Recursive table-A state used to generate the stable FIR realization."""
+
+    def __init__(self, model: RosellaModel):
+        self.model = model
+        self.bands = min(64, model.table_a_dimension)
+        self.delays = model.table_a_four_integers.astype(np.int32)
+        self.capacity = int(np.max(self.delays))
+        self.matrix = np.asarray(model.table_a_vector16, dtype=np.float64).reshape(
+            4, 4, order="F")
+        f8 = np.asarray(model.table_a_filter_8x64_padded, dtype=np.float64).reshape(
+            20, 4, 2, 4)
+        f4 = np.asarray(model.table_a_filter_4x64_padded, dtype=np.float64).reshape(
+            20, 4, 4)
+        f16 = np.asarray(model.table_a_filter_16x64_padded, dtype=np.float64).reshape(
+            20, 4, 4, 4)
+        self.feedback_real = np.empty((self.bands, 4), dtype=np.float64)
+        self.feedback_imag = np.empty_like(self.feedback_real)
+        self.output_tap = np.empty_like(self.feedback_real)
+        self.left_real = np.empty_like(self.feedback_real)
+        self.left_imag = np.empty_like(self.feedback_real)
+        self.right_real = np.empty_like(self.feedback_real)
+        self.right_imag = np.empty_like(self.feedback_real)
+        for band in range(self.bands):
+            group, lane = divmod(band, 4)
+            self.feedback_real[band] = f8[group, :, 0, lane]
+            self.feedback_imag[band] = f8[group, :, 1, lane]
+            self.output_tap[band] = f4[group, :, lane]
+            self.left_real[band] = f16[group, :, 0, lane]
+            self.left_imag[band] = f16[group, :, 1, lane]
+            self.right_real[band] = f16[group, :, 2, lane]
+            self.right_imag[band] = f16[group, :, 3, lane]
+
+        self.allpass_gain = np.asarray(model.table_a_option_values, dtype=np.float64)
+        self.allpass_delay = model.table_a_option_ids.astype(np.int32)
+        self.allpass_real = [
+            np.zeros((int(delay), self.bands), dtype=np.float64)
+            for delay in self.allpass_delay
+        ]
+        self.allpass_imag = [np.zeros_like(value) for value in self.allpass_real]
+        self.allpass_position = np.zeros(len(self.allpass_real), dtype=np.int32)
+        self.memory_real = np.zeros(
+            (self.capacity, self.bands, 4), dtype=np.float64)
+        self.memory_imag = np.zeros_like(self.memory_real)
+        self.position = 0
+        self.extra_fields = np.asarray(
+            model.table_a_extra_fields_padded, dtype=np.float64).reshape(-1, 20, 2, 4)
+        self.extra_matrices = [
+            np.asarray(value, dtype=np.float64).reshape(4, 4, order="F")
+            for value in model.table_a_extra_vectors
+        ]
+
+    def reset(self):
+        for value in self.allpass_real + self.allpass_imag:
+            value.fill(0.0)
+        self.allpass_position.fill(0)
+        self.memory_real.fill(0.0)
+        self.memory_imag.fill(0.0)
+        self.position = 0
+
+    def process_slot(self, room_send) -> np.ndarray:
+        values = np.asarray(room_send, dtype=np.complex128)
+        input_real = values[:self.bands].real * 0.70710677
+        input_imag = values[:self.bands].imag * 0.70710677
+        if float(self.model.table_a_scalar) >= 0.5:
+            raise NotImplementedError("alternate Rosella table-A room mode")
+
+        for index, gain in enumerate(self.allpass_gain):
+            position = int(self.allpass_position[index])
+            previous_real = self.allpass_real[index][position].copy()
+            previous_imag = self.allpass_imag[index][position].copy()
+            residual_real = input_real - previous_real * gain
+            residual_imag = input_imag - previous_imag * gain
+            input_real = residual_real * gain + previous_real
+            input_imag = residual_imag * gain + previous_imag
+            self.allpass_real[index][position] = residual_real
+            self.allpass_imag[index][position] = residual_imag
+            self.allpass_position[index] = (
+                position + 1) % len(self.allpass_real[index])
+
+        branch_real = np.repeat(input_real[:, None], 4, axis=1)
+        branch_imag = np.repeat(input_imag[:, None], 4, axis=1)
+        delayed_real = np.empty_like(branch_real)
+        delayed_imag = np.empty_like(branch_imag)
+        for branch, delay in enumerate(self.delays):
+            delayed_real[:, branch] = self.memory_real[
+                (self.position - int(delay)) % self.capacity, :, branch]
+            delayed_imag[:, branch] = self.memory_imag[
+                (self.position - int(delay)) % self.capacity, :, branch]
+        branch_real += np.einsum(
+            "bj,ij->bi", delayed_real, self.matrix,
+            dtype=np.float64, optimize=False)
+        branch_imag += np.einsum(
+            "bj,ij->bi", delayed_imag, self.matrix,
+            dtype=np.float64, optimize=False)
+
+        tap_index = (self.position - self.model.table_a_integer) % self.capacity
+        tap_real = self.memory_real[tap_index].copy()
+        tap_imag = self.memory_imag[tap_index].copy()
+        next_real = branch_real * self.feedback_real - branch_imag * self.feedback_imag
+        next_imag = branch_imag * self.feedback_real + branch_real * self.feedback_imag
+        self.memory_real[self.position] = next_real
+        self.memory_imag[self.position] = next_imag
+        self.position = (self.position + 1) % self.capacity
+
+        extra_real = np.zeros_like(branch_real)
+        extra_imag = np.zeros_like(branch_imag)
+        for index, delay in enumerate(self.model.table_a_extra_indices):
+            source_real = self.memory_real[
+                (self.position - (int(delay) + 1)) % self.capacity]
+            source_imag = self.memory_imag[
+                (self.position - (int(delay) + 1)) % self.capacity]
+            matrix = self.extra_matrices[index]
+            mixed_real = np.einsum(
+                "bj,ij->bi", source_real, matrix,
+                dtype=np.float64, optimize=False)
+            mixed_imag = np.einsum(
+                "bj,ij->bi", source_imag, matrix,
+                dtype=np.float64, optimize=False)
+            coefficient_real = np.empty(self.bands, dtype=np.float64)
+            coefficient_imag = np.empty(self.bands, dtype=np.float64)
+            for band in range(self.bands):
+                group, lane = divmod(band, 4)
+                coefficient_real[band] = self.extra_fields[index, group, 0, lane]
+                coefficient_imag[band] = self.extra_fields[index, group, 1, lane]
+            extra_real += (mixed_real * coefficient_real[:, None]
+                           - mixed_imag * coefficient_imag[:, None])
+            extra_imag += (mixed_imag * coefficient_real[:, None]
+                           + mixed_real * coefficient_imag[:, None])
+
+        output_real = tap_real * self.output_tap + extra_real
+        output_imag = tap_imag * self.output_tap + extra_imag
+        left = np.sum(
+            self.left_real * output_real - self.left_imag * output_imag,
+            axis=1, dtype=np.float64)
+        left_imag = np.sum(
+            self.left_imag * output_real + self.left_real * output_imag,
+            axis=1, dtype=np.float64)
+        right = np.sum(
+            self.right_real * output_real - self.right_imag * output_imag,
+            axis=1, dtype=np.float64)
+        right_imag = np.sum(
+            self.right_imag * output_real + self.right_real * output_imag,
+            axis=1, dtype=np.float64)
+        result = np.zeros((2, 77), dtype=np.complex128)
+        result[0, :self.bands] = left + 1j * left_imag
+        result[1, :self.bands] = right + 1j * right_imag
+        return result
+
+
+class RosellaRoomFir:
+    """Complex128 overlap-add room FIR generated locally from table-A."""
+
+    def __init__(self, model: RosellaModel, impulse_slots: int = 4096):
+        if impulse_slots <= 0:
+            raise ValueError("impulse_slots must be positive")
+        reference = _RosellaRoomState(model)
+        self.length = int(impulse_slots)
+        self.kernel = np.empty((self.length, 2, 64), dtype=np.complex128)
+        for slot in range(self.length):
+            impulse = np.zeros(77, dtype=np.complex128)
+            if slot == 0:
+                impulse[:64] = 1.0
+            self.kernel[slot] = reference.process_slot(impulse)[:, :64]
+        self.tail = np.zeros((self.length - 1, 2, 64), dtype=np.complex128)
+        self._fft_cache: dict[int, np.ndarray] = {}
+
+    def reset(self):
+        self.tail.fill(0.0)
+
+    def process_chunk(self, room_send) -> np.ndarray:
+        values = np.asarray(room_send, dtype=np.complex128)
+        if values.ndim != 2 or values.shape[1] != 77:
+            raise ValueError("room_send must have shape [slots,77]")
+        count = len(values)
+        if count == 0:
+            return np.zeros((0, 2, 77), dtype=np.complex128)
+        needed = count + self.length - 1
+        fft_size = 1 << (needed - 1).bit_length()
+        kernel_fft = self._fft_cache.get(fft_size)
+        if kernel_fft is None:
+            kernel_fft = np.fft.fft(self.kernel, fft_size, axis=0)
+            self._fft_cache[fft_size] = kernel_fft
+        input_fft = np.fft.fft(values[:, :64], fft_size, axis=0)
+        block = np.fft.ifft(input_fft[:, None, :] * kernel_fft, axis=0)[:needed]
+        block[:len(self.tail)] += self.tail
+        result = np.zeros((count, 2, 77), dtype=np.complex128)
+        result[:, :, :64] = block[:count]
+        self.tail = block[count:count + self.length - 1].copy()
+        return result

src/sofa_binaural_backend.py

@@ -0,0 +1,552 @@
+"""Stateful public SOFA binaural renderer.
+
+The runtime topology mirrors the existing multi-object binaural path:
+64-QMF -> 77 hybrid -> per-object directional transfer -> stereo synthesis.
+The HRTF parameter source is a SOFA-derived fifth-order field.  Early
+reflections and the late room use project-owned behavior.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+from pathlib import Path
+
+import numpy as np
+
+from public_filterbank import (
+    ANALYSIS_SYNTHESIS_LATENCY_SAMPLES,
+    HYBRID_BANDS,
+    QMF_HOP,
+    PublicAnalysis77,
+    PublicSynthesis77,
+    table_info as filterbank_table_info,
+)
+from public_room import (
+    LateFdnConfig,
+    SharedUnitaryFdn,
+    ShoeboxRoomConfig,
+    first_order_image_sources,
+)
+from reference_distance import DistanceState, ReferenceDistanceProfileV1
+from sofa_canonical import CanonicalHrtf
+from sofa_hrtf_field import (
+    DEFAULT_ORDER,
+    DEFAULT_PROJECTION_RIDGE,
+    DEFAULT_SH_RIDGE,
+    SofaHrtfField,
+    compile_sofa_hrtf,
+)
+
+
+@dataclass(frozen=True)
+class HybridPath:
+    label: str
+    delay_slots: np.ndarray  # whole-QMF delay per ear, [2]
+    transfer: np.ndarray  # [ear,77], includes residual delay and HRTF delay
+
+    def __post_init__(self):
+        slots = np.asarray(self.delay_slots)
+        if slots.shape == ():
+            slots = np.repeat(slots, 2)
+        if slots.shape != (2,) or slots.dtype.kind not in "iu":
+            raise ValueError("hybrid path delay_slots must contain two integers")
+        slots = np.asarray(slots, dtype=np.int64)
+        transfer = np.asarray(self.transfer, dtype=np.complex128)
+        if transfer.shape != (2, HYBRID_BANDS) or not np.isfinite(transfer).all():
+            raise ValueError("hybrid path transfer must have finite shape [2,77]")
+        if np.any(slots < 0):
+            raise ValueError("hybrid path delay_slots must be non-negative")
+        slots.setflags(write=False)
+        transfer.setflags(write=False)
+        object.__setattr__(self, "delay_slots", slots)
+        object.__setattr__(self, "transfer", transfer)
+
+
+class HybridObjectPathRenderer:
+    """Per-object hybrid histories for direct and image-source paths."""
+
+    def __init__(self, source_count: int, *, history_slots: int = 256,
+                 transition_slots: int = 8):
+        self.source_count = int(source_count)
+        self.history_slots = int(history_slots)
+        self.transition_slots = int(transition_slots)
+        if min(self.source_count, self.history_slots) <= 0 or self.transition_slots < 0:
+            raise ValueError("invalid hybrid path renderer dimensions")
+        self.history = np.zeros(
+            (self.source_count, self.history_slots, HYBRID_BANDS), dtype=np.complex128)
+        self.position = 0
+        self.current: list[tuple[HybridPath, ...]] = [tuple() for _ in range(self.source_count)]
+        self.target: list[tuple[HybridPath, ...] | None] = [None] * self.source_count
+        self.fade_position = np.zeros(self.source_count, dtype=np.int32)
+        self.fade_total = np.zeros(self.source_count, dtype=np.int32)
+        self.processed_slots = 0
+
+    def reset(self) -> None:
+        self.history.fill(0.0)
+        self.position = 0
+        self.target = [None] * self.source_count
+        self.fade_position.fill(0)
+        self.fade_total.fill(0)
+        self.processed_slots = 0
+
+    def set_paths(self, source: int, paths, *, fade_slots: int | None = None) -> None:
+        source = int(source)
+        if not 0 <= source < self.source_count:
+            raise IndexError(source)
+        values = tuple(paths)
+        for path in values:
+            if np.any(path.delay_slots >= self.history_slots):
+                raise ValueError(
+                    f"path {path.label!r} needs {path.delay_slots.tolist()} slots, "
+                    f"history capacity is {self.history_slots}")
+        fade = self.transition_slots if fade_slots is None else int(fade_slots)
+        if fade < 0:
+            raise ValueError("path fade must be non-negative")
+        if self.target[source] is not None:
+            # Normal 512-sample updates complete an 8-slot transition exactly.
+            # If a caller updates faster, use the previous target as the new
+            # stable side rather than resetting signal history.
+            self.current[source] = self.target[source]
+            self.target[source] = None
+        if not self.processed_slots or fade == 0:
+            self.current[source] = values
+            self.target[source] = None
+            self.fade_position[source] = 0
+            self.fade_total[source] = 0
+        else:
+            self.target[source] = values
+            self.fade_position[source] = 0
+            self.fade_total[source] = fade
+
+    def _render_paths(self, source: int, paths: tuple[HybridPath, ...]) -> np.ndarray:
+        result = np.zeros((2, HYBRID_BANDS), dtype=np.complex128)
+        for path in paths:
+            indices = (self.position - path.delay_slots) % self.history_slots
+            delayed = self.history[source, indices, :]
+            result += delayed * path.transfer
+        return result
+
+    def process(self, hybrid) -> np.ndarray:
+        values = np.asarray(hybrid, dtype=np.complex128)
+        if values.ndim != 3 or values.shape[1:] != (self.source_count, HYBRID_BANDS):
+            raise ValueError(
+                f"hybrid input must have shape [slots,{self.source_count},77]")
+        if not np.isfinite(values).all():
+            raise ValueError("hybrid input contains non-finite values")
+        output = np.zeros((len(values), 2, HYBRID_BANDS), dtype=np.complex128)
+        for slot in range(len(values)):
+            self.history[:, self.position, :] = values[slot]
+            for source in range(self.source_count - 1, -1, -1):
+                current = self._render_paths(source, self.current[source])
+                target_paths = self.target[source]
+                if target_paths is None:
+                    output[slot] += current
+                    continue
+                target = self._render_paths(source, target_paths)
+                self.fade_position[source] += 1
+                amount = min(
+                    1.0, self.fade_position[source] / float(self.fade_total[source]))
+                output[slot] += current * (1.0 - amount) + target * amount
+                if self.fade_position[source] >= self.fade_total[source]:
+                    self.current[source] = target_paths
+                    self.target[source] = None
+                    self.fade_position[source] = 0
+                    self.fade_total[source] = 0
+            self.position = (self.position + 1) % self.history_slots
+            self.processed_slots += 1
+        return output
+
+
+class _StereoDelay:
+    def __init__(self, delay_samples: int):
+        self.delay_samples = int(delay_samples)
+        if self.delay_samples < 0:
+            raise ValueError("delay must be non-negative")
+        self.state = np.zeros((self.delay_samples, 2), dtype=np.float64)
+
+    def reset(self) -> None:
+        self.state.fill(0.0)
+
+    def process(self, values) -> np.ndarray:
+        source = np.asarray(values, dtype=np.float64)
+        if source.ndim != 2 or source.shape[1] != 2:
+            raise ValueError("stereo delay input must have shape [samples,2]")
+        if self.delay_samples == 0:
+            return source.copy()
+        joined = np.concatenate((self.state, source), axis=0)
+        output = joined[:len(source)].copy()
+        self.state = joined[len(source):len(source) + self.delay_samples].copy()
+        return output
+
+
+class SofaBinauralBackend:
+    """SOFA-derived public 77-band/SH renderer with public room processing."""
+
+    def __init__(
+            self,
+            field: SofaHrtfField,
+            *,
+            source_count: int = 16,
+            sample_rate_hz: float = 48000.0,
+            default_profile: str = "mid",
+            enable_early_reflections: bool = True,
+            enable_late_room: bool = True,
+            room_config: ShoeboxRoomConfig = ShoeboxRoomConfig(),
+            fdn_config: LateFdnConfig | None = None,
+            transition_slots: int = 8,
+            history_slots: int = 256,
+            output_gain: float = 1.0):
+        self.source_count = int(source_count)
+        self.sample_rate_hz = float(sample_rate_hz)
+        self.default_profile = ReferenceDistanceProfileV1.validate_profile(default_profile)
+        self.enable_early_reflections = bool(enable_early_reflections)
+        self.enable_late_room = bool(enable_late_room)
+        self.room_config = room_config
+        self.room_config.validate()
+        self.output_gain = float(output_gain)
+        if (self.source_count <= 0 or not math.isfinite(self.sample_rate_hz)
+                or self.sample_rate_hz <= 0.0):
+            raise ValueError("source_count and sample rate must be positive")
+        if not math.isfinite(self.output_gain):
+            raise ValueError("output gain must be finite")
+        if abs(self.sample_rate_hz - 48000.0) > 1.0e-9:
+            raise ValueError("the public binaural runtime requires 48 kHz")
+
+        if not isinstance(field, SofaHrtfField):
+            raise TypeError(
+                "field must be SofaHrtfField; use from_sofa() or "
+                "from_compiled_cache() for file inputs")
+        self.field = field
+        self.hrtf_input_kind = "field"
+        self.hrtf_input_path: str | None = None
+        self.cache_policy: str | None = None
+        if abs(self.field.sample_rate_hz - self.sample_rate_hz) > 1.0e-9:
+            raise ValueError("HRTF field sample rate does not match the renderer")
+
+        self.early_history_slots = int(history_slots)
+        if self.early_history_slots <= 0:
+            raise ValueError("history_slots must be positive")
+        maximum_hrtf_delay = float(np.max(self.field.delay_bounds[:, 1], initial=0.0))
+        self.maximum_hrtf_delay_samples = maximum_hrtf_delay
+        self.hrtf_history_slots = int(math.ceil(maximum_hrtf_delay / QMF_HOP))
+        self.analysis = PublicAnalysis77(self.source_count)
+        self.paths = HybridObjectPathRenderer(
+            self.source_count,
+            history_slots=self.early_history_slots + self.hrtf_history_slots,
+            transition_slots=transition_slots)
+        self.synthesis = PublicSynthesis77(2)
+        actual_fdn_config = fdn_config or LateFdnConfig(sample_rate_hz=self.sample_rate_hz)
+        if abs(actual_fdn_config.sample_rate_hz - self.sample_rate_hz) > 1.0e-9:
+            raise ValueError("FDN sample rate does not match the renderer")
+        self.fdn = SharedUnitaryFdn(actual_fdn_config)
+        self.late_delay = _StereoDelay(ANALYSIS_SYNTHESIS_LATENCY_SAMPLES)
+
+        self.positions = np.zeros((self.source_count, 3), dtype=np.float64)
+        self.positions[:, 1] = 1.0
+        self.profiles = [self.default_profile] * self.source_count
+        self.user_gain = np.ones(self.source_count, dtype=np.float64)
+        self.special_lfe = np.zeros(self.source_count, dtype=bool)
+        self.distance_state: list[DistanceState | None] = [None] * self.source_count
+        self.late_current = np.zeros(self.source_count, dtype=np.float64)
+        self.late_start = np.zeros(self.source_count, dtype=np.float64)
+        self.late_target = np.zeros(self.source_count, dtype=np.float64)
+        self.late_fade_position = np.zeros(self.source_count, dtype=np.int64)
+        self.late_fade_total = np.zeros(self.source_count, dtype=np.int64)
+        self.maximum_early_delay_samples = 0.0
+        self.latency_to_discard = ANALYSIS_SYNTHESIS_LATENCY_SAMPLES
+        self.processed_input_samples = 0
+        self.output_samples = 0
+        self.parameter_updates = 0
+        self.finished = False
+        for source in range(self.source_count):
+            self.set_source(
+                source, self.positions[source], profile=self.default_profile,
+                fade=False)
+
+    @classmethod
+    def from_sofa(
+            cls, sofa: str | Path | CanonicalHrtf, *,
+            cache_policy: str = "memory",
+            cache_dir: str | Path | None = None,
+            shell_radius_m: float = 1.0,
+            order: int = DEFAULT_ORDER,
+            projection_ridge: float = DEFAULT_PROJECTION_RIDGE,
+            sh_ridge: float = DEFAULT_SH_RIDGE,
+            **renderer_options) -> "SofaBinauralBackend":
+        """Compile a SOFA source once and construct the runtime renderer."""
+        field = compile_sofa_hrtf(
+            sofa,
+            target_sample_rate_hz=float(
+                renderer_options.get("sample_rate_hz", 48000.0)),
+            shell_radius_m=shell_radius_m,
+            order=order,
+            projection_ridge=projection_ridge,
+            sh_ridge=sh_ridge,
+            cache_policy=cache_policy,
+            cache_dir=cache_dir)
+        result = cls(field, **renderer_options)
+        result.hrtf_input_kind = "sofa"
+        result.hrtf_input_path = (
+            str(Path(sofa).expanduser().resolve())
+            if not isinstance(sofa, CanonicalHrtf) else sofa.source_path)
+        result.cache_policy = str(cache_policy).lower()
+        return result
+
+    @classmethod
+    def from_compiled_cache(
+            cls, cache: str | Path, **renderer_options
+            ) -> "SofaBinauralBackend":
+        """Load an explicitly selected validated JOC compiled HRTF cache."""
+        path = Path(cache).expanduser().resolve()
+        field = SofaHrtfField.load(path)
+        result = cls(field, **renderer_options)
+        result.hrtf_input_kind = "compiled_cache"
+        result.hrtf_input_path = str(path)
+        result.cache_policy = None
+        return result
+
+    def _make_path(self, label: str, direction_adm, path_distance_m: float,
+                   extra_delay_samples: float, amplitude: float) -> HybridPath:
+        del path_distance_m
+        evaluation = self.field.evaluate_adm(direction_adm)
+        extra_delay = float(extra_delay_samples)
+        if not math.isfinite(extra_delay) or extra_delay < 0.0:
+            raise ValueError("path delay must be finite and non-negative")
+        early_delay_slots = int(math.floor(extra_delay / QMF_HOP))
+        if early_delay_slots >= self.early_history_slots:
+            raise ValueError(
+                f"path {label!r} needs {early_delay_slots} early-delay slots, "
+                f"early history capacity is {self.early_history_slots}")
+        total_delay = np.asarray(evaluation.delay_samples, dtype=np.float64) + extra_delay
+        delay_slots = np.floor(total_delay / QMF_HOP).astype(np.int64)
+        residual = total_delay - delay_slots * QMF_HOP
+        propagation_phase = np.exp(
+            -2j * np.pi * self.field.band_center_frequencies_hz[None, :]
+            * residual[:, None]
+            / self.sample_rate_hz)
+        transfer = np.asarray(
+            evaluation.aligned_gains * propagation_phase * float(amplitude),
+            dtype=np.complex128)
+        return HybridPath(label, delay_slots, transfer)
+
+    def _ordinary_paths(self, state: DistanceState, gain: float) -> tuple[HybridPath, ...]:
+        # Object PCM is programme-normalized.  Physical distance controls room
+        # geometry, while the project profile supplies the direct presentation
+        # coefficient instead of applying a second free-field 1/r attenuation.
+        direct_amplitude = gain * ReferenceDistanceProfileV1.direct_level_gain(state)
+        room_gain = ReferenceDistanceProfileV1.room_calibration_gain(state)
+        paths = [self._make_path(
+            "direct", state.direction_adm, state.physical_distance_m, 0.0,
+            direct_amplitude)]
+        if self.enable_early_reflections:
+            reflections = first_order_image_sources(
+                state.direction_adm, state.physical_distance_m,
+                self.sample_rate_hz, self.room_config)
+            for reflection in reflections:
+                amplitude = (
+                    gain * room_gain * reflection.reflection_gain
+                    * ReferenceDistanceProfileV1.inverse_distance_gain(
+                        self.field.measurement_radius_m,
+                        reflection.path_distance_m))
+                paths.append(self._make_path(
+                    f"early:{reflection.wall}", reflection.direction_adm,
+                    reflection.path_distance_m, reflection.extra_delay_samples,
+                    amplitude))
+                self.maximum_early_delay_samples = max(
+                    self.maximum_early_delay_samples,
+                    reflection.extra_delay_samples)
+        return tuple(paths)
+
+    def _lfe_paths(self, gain: float) -> tuple[HybridPath, ...]:
+        frequency = self.field.band_center_frequencies_hz
+        lowpass = np.ones(HYBRID_BANDS, dtype=np.float64)
+        lowpass[frequency >= 180.0] = 0.0
+        transition = (frequency > 120.0) & (frequency < 180.0)
+        amount = (frequency[transition] - 120.0) / 60.0
+        lowpass[transition] = np.cos(0.5 * np.pi * amount) ** 2
+        transfer = np.repeat(
+            (gain * lowpass / math.sqrt(2.0))[None, :], 2, axis=0
+        ).astype(np.complex128)
+        return (HybridPath(
+            "public_lfe_lowpass", np.zeros(2, dtype=np.int64), transfer),)
+
+    def _set_late_target(self, source: int, value: float, fade: bool) -> None:
+        value = float(value)
+        fade_samples = (self.paths.transition_slots * QMF_HOP
+                        if fade and self.processed_input_samples else 0)
+        if fade_samples == 0:
+            self.late_current[source] = value
+            self.late_start[source] = value
+            self.late_target[source] = value
+            self.late_fade_position[source] = 0
+            self.late_fade_total[source] = 0
+        else:
+            self.late_start[source] = self.late_current[source]
+            self.late_target[source] = value
+            self.late_fade_position[source] = 0
+            self.late_fade_total[source] = fade_samples
+
+    def set_source(self, source: int, position_adm, *, profile: str | None = None,
+                   gain: float = 1.0, enabled: bool = True,
+                   special_lfe: bool = False, fade: bool = True) -> None:
+        if self.finished:
+            raise RuntimeError("SOFA renderer is finished")
+        source = int(source)
+        if not 0 <= source < self.source_count:
+            raise IndexError(source)
+        gain = float(gain)
+        if not math.isfinite(gain):
+            raise ValueError("source gain must be finite")
+        effective_gain = gain if enabled else 0.0
+        name = self.default_profile if profile is None else profile
+        state = ReferenceDistanceProfileV1.map_adm_position(position_adm, name)
+        path_set = (self._lfe_paths(effective_gain) if special_lfe
+                    else self._ordinary_paths(state, effective_gain))
+        self.paths.set_paths(
+            source, path_set,
+            fade_slots=(self.paths.transition_slots if fade else 0))
+        late_send = (0.0 if special_lfe or not self.enable_late_room or not enabled
+                     else effective_gain
+                     * ReferenceDistanceProfileV1.room_calibration_gain(state)
+                     * ReferenceDistanceProfileV1.late_send(state))
+        self._set_late_target(source, late_send, fade)
+        self.positions[source] = np.asarray(position_adm, dtype=np.float64)
+        self.profiles[source] = state.profile
+        self.user_gain[source] = gain
+        self.special_lfe[source] = bool(special_lfe)
+        self.distance_state[source] = state
+        self.parameter_updates += 1
+
+    def _late_send_envelope(self, sample_count: int) -> np.ndarray:
+        envelope = np.empty((sample_count, self.source_count), dtype=np.float64)
+        for source in range(self.source_count):
+            total = int(self.late_fade_total[source])
+            if total == 0:
+                envelope[:, source] = self.late_current[source]
+                continue
+            start_position = int(self.late_fade_position[source])
+            position = start_position + np.arange(1, sample_count + 1)
+            amount = np.clip(position / float(total), 0.0, 1.0)
+            envelope[:, source] = (
+                self.late_start[source] * (1.0 - amount)
+                + self.late_target[source] * amount)
+            new_position = start_position + sample_count
+            if new_position >= total:
+                self.late_current[source] = self.late_target[source]
+                self.late_start[source] = self.late_target[source]
+                self.late_fade_position[source] = 0
+                self.late_fade_total[source] = 0
+            else:
+                self.late_current[source] = float(envelope[-1, source])
+                self.late_fade_position[source] = new_position
+        return envelope
+
+    def _process(self, sources) -> np.ndarray:
+        values = np.asarray(sources, dtype=np.float64)
+        if values.ndim != 2 or values.shape[1] != self.source_count:
+            raise ValueError(f"sources must have shape [samples,{self.source_count}]")
+        if len(values) % QMF_HOP:
+            raise ValueError("SOFA backend input must be divisible by 64 samples")
+        if not np.isfinite(values).all():
+            raise ValueError("SOFA backend input contains non-finite values")
+        hybrid = self.analysis.process(values)
+        direct_and_early = self.paths.process(hybrid)
+        direct_pcm = self.synthesis.process(direct_and_early)
+        if self.enable_late_room:
+            sends = self._late_send_envelope(len(values))
+            mono = np.sum(values * sends, axis=1, dtype=np.float64)
+            late_pcm = self.late_delay.process(self.fdn.process(mono))
+        else:
+            # Still advance any pending send fade deterministically.
+            self._late_send_envelope(len(values))
+            late_pcm = np.zeros_like(direct_pcm)
+        mixed = np.asarray((direct_pcm + late_pcm) * self.output_gain, dtype=np.float64)
+        skip = min(self.latency_to_discard, len(mixed))
+        self.latency_to_discard -= skip
+        self.processed_input_samples += len(values)
+        output = mixed[skip:]
+        self.output_samples += len(output)
+        return output
+
+    def process(self, sources) -> np.ndarray:
+        if self.finished:
+            raise RuntimeError("SOFA renderer is finished")
+        return self._process(sources)
+
+    def finish(self, *, tail_seconds: float | None = None) -> np.ndarray:
+        if self.finished:
+            return np.zeros((0, 2), dtype=np.float64)
+        if tail_seconds is not None and (
+                not math.isfinite(float(tail_seconds)) or float(tail_seconds) < 0.0):
+            raise ValueError("tail_seconds must be finite and non-negative")
+        requested = (self.fdn.tail_samples if tail_seconds is None
+                     else int(math.ceil(float(tail_seconds) * self.sample_rate_hz)))
+        drain = max(
+            requested if self.enable_late_room else 0,
+            int(math.ceil(
+                self.maximum_hrtf_delay_samples
+                + self.maximum_early_delay_samples)) + 2048,
+        ) + ANALYSIS_SYNTHESIS_LATENCY_SAMPLES
+        drain = int(math.ceil(drain / QMF_HOP) * QMF_HOP)
+        output = self._process(np.zeros((drain, self.source_count), dtype=np.float64))
+        self.finished = True
+        return output
+
+    def finish_output_capacity(self, tail_seconds: float | None = None) -> int:
+        """Return a conservative bound for one future :meth:`finish` output."""
+        if tail_seconds is not None and (
+                not math.isfinite(float(tail_seconds)) or float(tail_seconds) < 0.0):
+            raise ValueError("tail_seconds must be finite and non-negative")
+        requested = (self.fdn.tail_samples if tail_seconds is None
+                     else int(math.ceil(float(tail_seconds) * self.sample_rate_hz)))
+        hrtf_bound = self.hrtf_history_slots * QMF_HOP
+        early_bound = hrtf_bound + 2048
+        if self.enable_early_reflections:
+            early_bound += self.early_history_slots * QMF_HOP
+        drain = max(requested if self.enable_late_room else 0, early_bound)
+        drain += ANALYSIS_SYNTHESIS_LATENCY_SAMPLES
+        return int(math.ceil(drain / QMF_HOP) * QMF_HOP)
+
+    def reset(self) -> None:
+        self.analysis.reset()
+        self.paths.reset()
+        self.synthesis.reset()
+        self.fdn.reset()
+        self.late_delay.reset()
+        self.latency_to_discard = ANALYSIS_SYNTHESIS_LATENCY_SAMPLES
+        self.processed_input_samples = 0
+        self.output_samples = 0
+        self.finished = False
+        for source in range(self.source_count):
+            self.set_source(
+                source, self.positions[source], profile=self.profiles[source],
+                gain=float(self.user_gain[source]),
+                special_lfe=bool(self.special_lfe[source]), fade=False)
+
+    def info(self) -> dict:
+        return {
+            "name": "SofaBinauralBackend",
+            "source_count": self.source_count,
+            "sample_rate_hz": self.sample_rate_hz,
+            "precision": "float64/complex128",
+            "signal_path": (
+                "public 64-QMF -> public 77-hybrid -> SOFA order-5 real-SH "
+                "direct/early -> public synthesis + shared unitary FDN"),
+            "hrtf_input_kind": self.hrtf_input_kind,
+            "hrtf_input_path": self.hrtf_input_path,
+            "cache_policy": self.cache_policy,
+            "latency_compensated_samples": ANALYSIS_SYNTHESIS_LATENCY_SAMPLES,
+            "enable_early_reflections": self.enable_early_reflections,
+            "enable_late_room": self.enable_late_room,
+            "early_history_slots": self.early_history_slots,
+            "hrtf_history_slots": self.hrtf_history_slots,
+            "maximum_hrtf_delay_samples": self.maximum_hrtf_delay_samples,
+            "maximum_early_delay_samples": self.maximum_early_delay_samples,
+            "parameter_updates": self.parameter_updates,
+            "processed_input_samples_including_flush": self.processed_input_samples,
+            "output_samples_before_trim": self.output_samples,
+            "distance": ReferenceDistanceProfileV1.info(),
+            "filterbank": filterbank_table_info(),
+            "field": self.field.info(),
+            "late_room": self.fdn.info(),
+        }

src/sofa_canonical.py

@@ -0,0 +1,637 @@
+"""Strict SimpleFreeFieldHRIR to canonical HRTF import.
+
+The canonical representation keeps ``Data.IR`` and ``Data.Delay`` separate.
+No importer operation silently bakes the SOFA delay into the stored FIRs.  A
+caller must explicitly request :meth:`CanonicalHrtf.materialized_measurement`
+when a time-domain FIR with ``Data.Delay`` applied exactly once is required.
+"""
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass, replace
+from fractions import Fraction
+import hashlib
+import math
+from pathlib import Path
+from typing import Any
+
+import h5py
+import numpy as np
+from scipy import signal
+from scipy.fft import next_fast_len
+
+
+_SUPPORTED_VERSIONS = {"0.4", "1.0", "1.1"}
+_FREE_FIELD_ROOM_TYPES = {"free field", "free-field", "anechoic", "hemi-anechoic"}
+_LENGTH_UNITS = {
+    "m": 1.0,
+    "metre": 1.0,
+    "metres": 1.0,
+    "meter": 1.0,
+    "meters": 1.0,
+    "cm": 1.0e-2,
+    "centimetre": 1.0e-2,
+    "centimetres": 1.0e-2,
+    "centimeter": 1.0e-2,
+    "centimeters": 1.0e-2,
+    "mm": 1.0e-3,
+    "millimetre": 1.0e-3,
+    "millimetres": 1.0e-3,
+    "millimeter": 1.0e-3,
+    "millimeters": 1.0e-3,
+}
+_ANGLE_UNITS = {
+    "degree": np.deg2rad,
+    "degrees": np.deg2rad,
+    "radian": lambda value: np.asarray(value, dtype=np.float64),
+    "radians": lambda value: np.asarray(value, dtype=np.float64),
+}
+
+
+class SofaImportError(ValueError):
+    """The file is outside the deliberately narrow public SOFA contract."""
+
+
+def _text(value: Any) -> str:
+    if isinstance(value, np.ndarray) and value.shape == ():
+        value = value.item()
+    if isinstance(value, (bytes, np.bytes_)):
+        return value.decode("utf-8", "strict")
+    return str(value)
+
+
+def _sha256_stream(stream) -> str:
+    digest = hashlib.sha256()
+    stream.seek(0)
+    for block in iter(lambda: stream.read(4 << 20), b""):
+        digest.update(block)
+    stream.seek(0)
+    return digest.hexdigest().upper()
+
+
+@contextmanager
+def _stable_hdf5_source(path: Path):
+    """Read arrays and content identity from one stable open-file snapshot."""
+    with path.open("rb") as stream:
+        before = _sha256_stream(stream)
+        with h5py.File(stream, "r") as file:
+            yield file, before
+        after = _sha256_stream(stream)
+        if after != before:
+            raise SofaImportError("SOFA file changed while it was being imported")
+
+
+def _tokens(units: str) -> list[str]:
+    return [token.strip().lower() for token in units.split(",") if token.strip()]
+
+
+def _coordinate_attributes(dataset: h5py.Dataset, *, inherit=None) -> tuple[str, str]:
+    source = dataset.attrs
+    if "Type" not in source or "Units" not in source:
+        if inherit is None or "Type" not in inherit.attrs or "Units" not in inherit.attrs:
+            raise SofaImportError(f"{dataset.name} must declare Type and Units")
+        source = inherit.attrs
+    return _text(source["Type"]).strip().lower(), _text(source["Units"]).strip()
+
+
+def coordinates_to_cartesian_m(values, coordinate_type: str, units: str,
+                               *, variable: str) -> np.ndarray:
+    """Convert a SOFA coordinate array to Cartesian metres without reshaping it."""
+    data = np.asarray(values, dtype=np.float64)
+    if data.shape[-1] != 3 or not np.isfinite(data).all():
+        raise SofaImportError(f"{variable} must contain finite C=3 coordinates")
+    kind = coordinate_type.strip().lower()
+    unit_tokens = _tokens(units)
+    if kind == "cartesian":
+        if len(unit_tokens) == 1:
+            factors = [_LENGTH_UNITS.get(unit_tokens[0])] * 3
+        elif len(unit_tokens) == 3:
+            factors = [_LENGTH_UNITS.get(token) for token in unit_tokens]
+        else:
+            factors = []
+        if len(factors) != 3 or any(value is None for value in factors):
+            raise SofaImportError(f"unsupported Cartesian units for {variable}: {units!r}")
+        return data * np.asarray(factors, dtype=np.float64)
+    if kind != "spherical" or len(unit_tokens) != 3:
+        raise SofaImportError(
+            f"unsupported coordinates for {variable}: Type={coordinate_type!r}, Units={units!r}")
+    if unit_tokens[0] not in _ANGLE_UNITS or unit_tokens[1] not in _ANGLE_UNITS:
+        raise SofaImportError(f"unsupported spherical angle units for {variable}: {units!r}")
+    radius_factor = _LENGTH_UNITS.get(unit_tokens[2])
+    if radius_factor is None:
+        raise SofaImportError(f"unsupported spherical radius unit for {variable}: {units!r}")
+    azimuth = _ANGLE_UNITS[unit_tokens[0]](data[..., 0])
+    elevation = _ANGLE_UNITS[unit_tokens[1]](data[..., 1])
+    radius = data[..., 2] * radius_factor
+    if np.any(radius < 0.0):
+        raise SofaImportError(f"{variable} contains a negative spherical radius")
+    horizontal = np.cos(elevation)
+    return np.stack(
+        (radius * horizontal * np.cos(azimuth),
+         radius * horizontal * np.sin(azimuth),
+         radius * np.sin(elevation)),
+        axis=-1,
+    ).astype(np.float64, copy=False)
+
+
+def _rows(file: h5py.File, name: str, measurements: int, *, inherit=None) -> np.ndarray:
+    if name not in file:
+        raise SofaImportError(f"missing required SOFA variable {name}")
+    dataset = file[name]
+    kind, units = _coordinate_attributes(dataset, inherit=inherit)
+    result = coordinates_to_cartesian_m(dataset[...], kind, units, variable=name)
+    if result.shape not in ((1, 3), (measurements, 3)):
+        raise SofaImportError(
+            f"{name} must have shape [I,C] or [M,C], got {result.shape}")
+    return np.broadcast_to(result, (measurements, 3)).astype(np.float64, copy=True)
+
+
+def _receiver_rows(file: h5py.File, measurements: int) -> np.ndarray:
+    if "ReceiverPosition" not in file:
+        raise SofaImportError("missing required SOFA variable ReceiverPosition")
+    dataset = file["ReceiverPosition"]
+    raw = np.asarray(dataset[...], dtype=np.float64)
+    if raw.shape not in ((2, 3, 1), (2, 3, measurements)):
+        raise SofaImportError(
+            "ReceiverPosition must have shape [R=2,C=3,I=1 or M]")
+    values = np.moveaxis(raw, 1, -1)  # [R,I/M,C]
+    kind, units = _coordinate_attributes(dataset)
+    cartesian = coordinates_to_cartesian_m(
+        values, kind, units, variable="ReceiverPosition")
+    cartesian = np.moveaxis(cartesian, 0, 1)  # [I/M,R,C]
+    return np.broadcast_to(cartesian, (measurements, 2, 3)).astype(
+        np.float64, copy=True)
+
+
+def _emitter_is_origin(file: h5py.File, measurements: int) -> None:
+    if "EmitterPosition" not in file:
+        raise SofaImportError("missing required SOFA variable EmitterPosition")
+    dataset = file["EmitterPosition"]
+    raw = np.asarray(dataset[...], dtype=np.float64)
+    if raw.shape not in ((1, 3, 1), (1, 3, measurements)):
+        raise SofaImportError("SimpleFreeFieldHRIR v1 requires E=1 EmitterPosition[E,C,I/M]")
+    values = np.moveaxis(raw, 1, -1)
+    kind, units = _coordinate_attributes(dataset)
+    cartesian = coordinates_to_cartesian_m(
+        values, kind, units, variable="EmitterPosition")
+    if np.max(np.abs(cartesian), initial=0.0) > 1.0e-9:
+        raise SofaImportError("non-zero EmitterPosition needs a separate source-pose adapter")
+
+
+def _sampling_rate(file: h5py.File) -> float:
+    if "Data.SamplingRate" not in file:
+        raise SofaImportError("missing Data.SamplingRate")
+    dataset = file["Data.SamplingRate"]
+    values = np.asarray(dataset[...], dtype=np.float64).reshape(-1)
+    if values.size != 1 or not math.isfinite(float(values[0])) or values[0] <= 0.0:
+        raise SofaImportError("Data.SamplingRate must contain one positive finite value")
+    units = _text(dataset.attrs.get("Units", "")).strip().lower()
+    if units not in {"hertz", "hz"}:
+        raise SofaImportError(f"Data.SamplingRate Units must be hertz, got {units!r}")
+    return float(values[0])
+
+
+def _processing_label(file: h5py.File) -> str:
+    parts = []
+    for key in ("DatabaseName", "Title", "ListenerShortName", "Comment"):
+        value = _text(file.attrs.get(key, "")).strip()
+        if value and value not in parts:
+            parts.append(value)
+    return " | ".join(parts)
+
+
+def _read_delay(file: h5py.File, measurements: int) -> np.ndarray:
+    if "Data.Delay" not in file:
+        raise SofaImportError("missing Data.Delay")
+    delay = np.asarray(file["Data.Delay"][...], dtype=np.float64)
+    if delay.shape not in ((1, 2), (measurements, 2)) or not np.isfinite(delay).all():
+        raise SofaImportError("Data.Delay must have finite shape [I=1,R=2] or [M,R=2]")
+    delay = np.broadcast_to(delay, (measurements, 2)).astype(np.float64, copy=True)
+    if np.min(delay, initial=0.0) < -1.0e-9:
+        raise SofaImportError("negative Data.Delay is outside the supported causal contract")
+    delay[delay < 0.0] = 0.0
+    return delay
+
+
+def _readonly(array, dtype) -> np.ndarray:
+    result = np.asarray(array, dtype=dtype)
+    result.setflags(write=False)
+    return result
+
+
+@dataclass(frozen=True)
+class CanonicalHrtf:
+    source_path: str
+    source_sha256: str
+    convention: str
+    convention_version: str
+    sofa_version: str
+    source_sample_rate_hz: float
+    sample_rate_hz: float
+    source_position_cartesian_m: np.ndarray  # listener-local [M,3]
+    listener_view: np.ndarray                 # world, normalized [M,3]
+    listener_up: np.ndarray                   # world, orthonormal [M,3]
+    receiver_position_cartesian_m: np.ndarray # listener-local, L/R [M,2,3]
+    left_receiver_index: int
+    right_receiver_index: int
+    hrir: np.ndarray                          # canonical L/R [M,2,N]
+    delay_samples: np.ndarray                 # canonical L/R [M,2], not applied
+    measurement_radius_m: np.ndarray          # [M]
+    processing_label: str
+    resampling_label: str = "none"
+
+    def __post_init__(self):
+        object.__setattr__(self, "source_position_cartesian_m", _readonly(
+            self.source_position_cartesian_m, np.float64))
+        object.__setattr__(self, "listener_view", _readonly(self.listener_view, np.float64))
+        object.__setattr__(self, "listener_up", _readonly(self.listener_up, np.float64))
+        object.__setattr__(self, "receiver_position_cartesian_m", _readonly(
+            self.receiver_position_cartesian_m, np.float64))
+        object.__setattr__(self, "hrir", _readonly(self.hrir, np.float64))
+        object.__setattr__(self, "delay_samples", _readonly(self.delay_samples, np.float64))
+        object.__setattr__(self, "measurement_radius_m", _readonly(
+            self.measurement_radius_m, np.float64))
+
+    @property
+    def measurements(self) -> int:
+        return int(self.hrir.shape[0])
+
+    @property
+    def taps(self) -> int:
+        return int(self.hrir.shape[2])
+
+    @property
+    def unit_directions(self) -> np.ndarray:
+        return self.source_position_cartesian_m / self.measurement_radius_m[:, None]
+
+    @property
+    def shells_m(self) -> np.ndarray:
+        return np.unique(np.round(self.measurement_radius_m, 9))
+
+    def shell_indices(self, radius_m: float) -> np.ndarray:
+        shell = float(self.shells_m[np.argmin(np.abs(self.shells_m - float(radius_m)))])
+        return np.flatnonzero(np.isclose(
+            self.measurement_radius_m, shell, atol=5.0e-7, rtol=0.0))
+
+    def nearest_index(self, direction_sofa, radius_m: float = 1.0) -> tuple[int, float]:
+        direction = np.asarray(direction_sofa, dtype=np.float64)
+        if direction.shape != (3,) or not np.isfinite(direction).all():
+            raise ValueError("direction must contain three finite SOFA Cartesian values")
+        norm = float(np.linalg.norm(direction))
+        if norm <= 1.0e-15:
+            raise ValueError("direction must be non-zero")
+        direction = direction / norm
+        indices = self.shell_indices(radius_m)
+        dots = self.unit_directions[indices] @ direction
+        local = int(np.argmax(dots))
+        error = math.degrees(math.acos(float(np.clip(dots[local], -1.0, 1.0))))
+        return int(indices[local]), float(error)
+
+    def resampled(self, target_sample_rate_hz: float) -> "CanonicalHrtf":
+        target = float(target_sample_rate_hz)
+        if not math.isfinite(target) or target <= 0.0:
+            raise ValueError("target sample rate must be positive and finite")
+        if abs(target - self.sample_rate_hz) <= 1.0e-9:
+            return self
+        ratio = target / self.sample_rate_hz
+        fraction = Fraction(ratio).limit_denominator(100000)
+        if abs(float(fraction) - ratio) > 1.0e-10:
+            raise ValueError("sample-rate ratio cannot be represented safely")
+        converted = signal.resample_poly(
+            np.asarray(self.hrir, dtype=np.float64), fraction.numerator,
+            fraction.denominator, axis=-1, window=("kaiser", 8.6), padtype="constant")
+        converted = np.asarray(converted, dtype=np.float64)
+        return replace(
+            self,
+            sample_rate_hz=target,
+            hrir=converted,
+            delay_samples=np.asarray(self.delay_samples * ratio, dtype=np.float64),
+            resampling_label=(
+                f"scipy.signal.resample_poly {self.sample_rate_hz:g}->{target:g} Hz "
+                f"({fraction.numerator}/{fraction.denominator}, Kaiser beta=8.6)"),
+        )
+
+    def materialized_measurement(self, index: int, *, fractional_half_length: int = 48
+                                 ) -> np.ndarray:
+        """Return [L/R,taps] with SOFA Data.Delay applied exactly once."""
+        index = int(index)
+        if not 0 <= index < self.measurements:
+            raise IndexError(index)
+        ears = []
+        for ear in range(2):
+            ears.append(apply_fractional_delay(
+                self.hrir[index, ear], float(self.delay_samples[index, ear]),
+                half_length=fractional_half_length))
+        length = max(map(len, ears))
+        result = np.zeros((2, length), dtype=np.float64)
+        for ear, value in enumerate(ears):
+            result[ear, :len(value)] = value
+        return result
+
+    def info(self) -> dict:
+        return {
+            "source_path": self.source_path,
+            "source_sha256": self.source_sha256,
+            "convention": self.convention,
+            "convention_version": self.convention_version,
+            "sofa_version": self.sofa_version,
+            "source_sample_rate_hz": self.source_sample_rate_hz,
+            "sample_rate_hz": self.sample_rate_hz,
+            "measurements": self.measurements,
+            "taps": self.taps,
+            "shells_m": [float(value) for value in self.shells_m],
+            "source_receiver_order": [self.left_receiver_index, self.right_receiver_index],
+            "canonical_ear_order": ["left", "right"],
+            "data_delay_samples_min": float(np.min(self.delay_samples)),
+            "data_delay_samples_max": float(np.max(self.delay_samples)),
+            "data_delay_applied": False,
+            "processing_label": self.processing_label,
+            "resampling": self.resampling_label,
+            "precision": "float64",
+        }
+
+
+def load_simple_free_field_hrir(path, *, target_sample_rate_hz: float | None = None
+                                ) -> CanonicalHrtf:
+    """Strictly import the supported SimpleFreeFieldHRIR subset."""
+    source = Path(path).expanduser().resolve()
+    if not source.is_file():
+        raise FileNotFoundError(source)
+    with _stable_hdf5_source(source) as (file, source_sha256):
+        if _text(file.attrs.get("Conventions", "")) != "SOFA":
+            raise SofaImportError("Conventions must be SOFA")
+        convention = _text(file.attrs.get("SOFAConventions", ""))
+        if convention != "SimpleFreeFieldHRIR":
+            raise SofaImportError(
+                f"unsupported SOFAConventions={convention!r}; convert explicitly first")
+        convention_version = _text(file.attrs.get("SOFAConventionsVersion", ""))
+        if convention_version not in _SUPPORTED_VERSIONS:
+            raise SofaImportError(
+                f"unsupported SimpleFreeFieldHRIR version {convention_version!r}; "
+                f"supported={sorted(_SUPPORTED_VERSIONS)}")
+        if _text(file.attrs.get("DataType", "")) != "FIR":
+            raise SofaImportError("DataType must be FIR")
+        room_type = _text(file.attrs.get("RoomType", "")).strip().lower()
+        if room_type not in _FREE_FIELD_ROOM_TYPES:
+            raise SofaImportError(f"RoomType must explicitly be free-field, got {room_type!r}")
+        if "Data.IR" not in file:
+            raise SofaImportError("missing Data.IR")
+        hrir_source = np.asarray(file["Data.IR"][...], dtype=np.float64)
+        if hrir_source.ndim != 3 or hrir_source.shape[1] != 2 or min(hrir_source.shape) <= 0:
+            raise SofaImportError("Data.IR must have shape [M,R=2,N]")
+        if not np.isfinite(hrir_source).all():
+            raise SofaImportError("Data.IR contains non-finite values")
+        measurements = int(hrir_source.shape[0])
+        sample_rate = _sampling_rate(file)
+        delay_source = _read_delay(file, measurements)
+        _emitter_is_origin(file, measurements)
+
+        listener_position = _rows(file, "ListenerPosition", measurements)
+        listener_view = _rows(file, "ListenerView", measurements)
+        listener_up_raw = _rows(
+            file, "ListenerUp", measurements,
+            inherit=file["ListenerView"] if "ListenerView" in file else None)
+        forward_norm = np.linalg.norm(listener_view, axis=1)
+        if np.any(forward_norm <= 1.0e-12):
+            raise SofaImportError("ListenerView must be non-zero")
+        forward = listener_view / forward_norm[:, None]
+        left = np.cross(listener_up_raw, forward)
+        left_norm = np.linalg.norm(left, axis=1)
+        if np.any(left_norm <= 1.0e-12):
+            raise SofaImportError("ListenerUp must not be parallel to ListenerView")
+        left /= left_norm[:, None]
+        up = np.cross(forward, left)
+
+        if "SourcePosition" not in file:
+            raise SofaImportError("missing required SOFA variable SourcePosition")
+        source_dataset = file["SourcePosition"]
+        source_type, source_units = _coordinate_attributes(source_dataset)
+        source_world = coordinates_to_cartesian_m(
+            source_dataset[...], source_type, source_units, variable="SourcePosition")
+        if source_world.shape != (measurements, 3):
+            raise SofaImportError("SourcePosition must have shape [M,C=3]")
+        relative = source_world - listener_position
+        source_local = np.stack(
+            (np.sum(relative * forward, axis=1),
+             np.sum(relative * left, axis=1),
+             np.sum(relative * up, axis=1)), axis=1)
+        radii = np.linalg.norm(source_local, axis=1)
+        if np.any(radii <= 1.0e-8) or not np.isfinite(radii).all():
+            raise SofaImportError("every source measurement must have a positive radius")
+
+        receiver = _receiver_rows(file, measurements)
+        lateral_difference = receiver[:, 0, 1] - receiver[:, 1, 1]
+        if np.all(lateral_difference > 1.0e-5):
+            left_index, right_index = 0, 1
+        elif np.all(lateral_difference < -1.0e-5):
+            left_index, right_index = 1, 0
+        else:
+            raise SofaImportError(
+                "ReceiverPosition does not identify one consistently-left and one "
+                "consistently-right receiver")
+        ear_order = [left_index, right_index]
+        hrir = hrir_source[:, ear_order, :]
+        delay = delay_source[:, ear_order]
+        receiver = receiver[:, ear_order, :]
+        processing_label = _processing_label(file)
+        sofa_version = _text(file.attrs.get("Version", ""))
+
+    canonical = CanonicalHrtf(
+        source_path=str(source),
+        source_sha256=source_sha256,
+        convention=convention,
+        convention_version=convention_version,
+        sofa_version=sofa_version,
+        source_sample_rate_hz=sample_rate,
+        sample_rate_hz=sample_rate,
+        source_position_cartesian_m=source_local,
+        listener_view=forward,
+        listener_up=up,
+        receiver_position_cartesian_m=receiver,
+        left_receiver_index=left_index,
+        right_receiver_index=right_index,
+        hrir=hrir,
+        delay_samples=delay,
+        measurement_radius_m=radii,
+        processing_label=processing_label,
+    )
+    return (canonical if target_sample_rate_hz is None
+            else canonical.resampled(target_sample_rate_hz))
+
+
+def apply_fractional_delay(values, delay_samples: float, *, half_length: int = 48
+                           ) -> np.ndarray:
+    """Apply one causal non-negative delay to a real FIR using windowed sinc."""
+    source = np.asarray(values, dtype=np.float64)
+    delay = float(delay_samples)
+    if source.ndim != 1 or not np.isfinite(source).all():
+        raise ValueError("fractional delay input must be a finite real vector")
+    if not math.isfinite(delay) or delay < -1.0e-12:
+        raise ValueError("fractional delay must be finite and non-negative")
+    if delay < 1.0e-12:
+        return source.copy()
+    integer = int(math.floor(delay))
+    fraction = delay - integer
+    if fraction < 1.0e-12:
+        return np.pad(source, (integer, 0)).astype(np.float64, copy=False)
+    half = int(half_length)
+    if half < 8:
+        raise ValueError("fractional delay half_length must be at least 8")
+    index = np.arange(-half, half + 1, dtype=np.float64)
+    kernel = np.sinc(index - fraction) * np.kaiser(2 * half + 1, 8.6)
+    kernel /= np.sum(kernel, dtype=np.float64)
+    full = signal.fftconvolve(source, kernel, mode="full")
+    causal = np.asarray(full[half:], dtype=np.float64)
+    return np.pad(causal, (integer, 0)).astype(np.float64, copy=False)
+
+
+def shift_signal_fft(values, shift_samples: float) -> np.ndarray:
+    """Band-limited linear shift; positive is delay and negative is advance."""
+    source = np.asarray(values, dtype=np.float64)
+    shift = float(shift_samples)
+    if source.ndim != 1 or not np.isfinite(source).all() or not math.isfinite(shift):
+        raise ValueError("shift input and amount must be finite")
+    if abs(shift) < 1.0e-12:
+        return source.copy()
+    guard = max(128, int(math.ceil(abs(shift))) + 64)
+    needed = len(source) + 2 * guard
+    fft_size = next_fast_len(needed)
+    padded = np.zeros(fft_size, dtype=np.float64)
+    padded[guard:guard + len(source)] = source
+    bins = np.arange(fft_size // 2 + 1, dtype=np.float64)
+    spectrum = np.fft.rfft(padded)
+    spectrum *= np.exp(-2j * np.pi * bins * shift / fft_size)
+    shifted = np.fft.irfft(spectrum, fft_size)
+    return np.asarray(shifted[guard:guard + len(source)], dtype=np.float64)
+
+
+def estimate_interaural_delay_samples(left, right, sample_rate_hz: float,
+                                       *, low_hz: float = 200.0,
+                                       high_hz: float = 1500.0) -> float:
+    """Estimate L-minus-R delay by low-frequency circular phase coherence.
+
+    A coarse-to-fine delay search avoids the phase-unwrapping branch failures
+    that ordinary straight-line regression can exhibit for strongly filtered
+    Far responses.
+    """
+    left = np.asarray(left, dtype=np.float64)
+    right = np.asarray(right, dtype=np.float64)
+    if left.shape != right.shape or left.ndim != 1:
+        raise ValueError("ITD inputs must be equal-length vectors")
+    fft_size = next_fast_len(max(4096, 4 * len(left)))
+    left_spectrum = np.fft.rfft(left, fft_size)
+    right_spectrum = np.fft.rfft(right, fft_size)
+    frequency = np.fft.rfftfreq(fft_size, 1.0 / float(sample_rate_hz))
+    selected = (frequency >= low_hz) & (frequency <= high_hz)
+    if np.count_nonzero(selected) < 8:
+        return 0.0
+    cross = left_spectrum[selected] * np.conj(right_spectrum[selected])
+    magnitude = np.abs(cross)
+    maximum = float(np.max(magnitude, initial=0.0))
+    if maximum <= 1.0e-20:
+        return 0.0
+    weighted_unit = cross / np.maximum(magnitude, 1.0e-30)
+    weight = np.sqrt(magnitude / maximum)
+    weighted_unit *= weight
+    omega = 2.0 * np.pi * frequency[selected] / float(sample_rate_hz)
+    limit = 0.0012 * float(sample_rate_hz)
+
+    def best(candidates: np.ndarray) -> float:
+        steering = np.exp(1j * omega[:, None] * candidates[None, :])
+        score = np.abs(weighted_unit @ steering)
+        return float(candidates[int(np.argmax(score))])
+
+    coarse = np.arange(-limit, limit + 0.25, 0.5, dtype=np.float64)
+    estimate = best(coarse)
+    fine = np.arange(estimate - 0.6, estimate + 0.6001, 0.02, dtype=np.float64)
+    return float(np.clip(best(fine), -limit, limit))
+
+def _subsample_peak(values: np.ndarray) -> float:
+    magnitude = np.abs(np.asarray(values, dtype=np.float64))
+    index = int(np.argmax(magnitude))
+    if index == 0 or index + 1 >= len(magnitude):
+        return float(index)
+    y0, y1, y2 = (float(magnitude[index - 1]), float(magnitude[index]),
+                  float(magnitude[index + 1]))
+    denominator = y0 - 2.0 * y1 + y2
+    correction = 0.0 if abs(denominator) < 1.0e-30 else 0.5 * (y0 - y2) / denominator
+    return float(index + np.clip(correction, -0.5, 0.5))
+
+
+@dataclass(frozen=True)
+class TimeAlignedHrtf:
+    canonical: CanonicalHrtf
+    aligned_hrir: np.ndarray
+    runtime_delay_samples: np.ndarray
+    embedded_delay_removed_samples: np.ndarray
+    delay_source: str
+
+    def __post_init__(self):
+        object.__setattr__(self, "aligned_hrir", _readonly(self.aligned_hrir, np.float64))
+        object.__setattr__(self, "runtime_delay_samples", _readonly(
+            self.runtime_delay_samples, np.float64))
+        object.__setattr__(self, "embedded_delay_removed_samples", _readonly(
+            self.embedded_delay_removed_samples, np.float64))
+
+
+def time_align_hrtf(canonical: CanonicalHrtf) -> TimeAlignedHrtf:
+    """Separate one delay representation before directional interpolation.
+
+    Trusted non-zero ``Data.Delay`` is external to ``Data.IR`` and is therefore
+    retained without de-rotating the FIR.  When ``Data.Delay`` is identically
+    zero, ordinary measured HRIRs with a positive onset use their per-ear main
+    peaks.  A zero-origin effective FIR is already expressed at one common
+    time origin; its interaural phase is therefore retained in ``Data.IR``.
+
+    These representations are mutually exclusive.  Runtime rendering must
+    restore exactly the delay separated here and must not add any second ear
+    delay or phase-group delay.
+    """
+    hrir = np.asarray(canonical.hrir, dtype=np.float64)
+    if np.max(np.abs(canonical.delay_samples), initial=0.0) > 1.0e-12:
+        return TimeAlignedHrtf(
+            canonical=canonical,
+            aligned_hrir=hrir.copy(),
+            runtime_delay_samples=np.asarray(canonical.delay_samples, dtype=np.float64),
+            embedded_delay_removed_samples=np.zeros_like(canonical.delay_samples),
+            delay_source="Data.Delay (external; applied once at render time)",
+        )
+
+    measurements = canonical.measurements
+    runtime = np.zeros((measurements, 2), dtype=np.float64)
+    removed = np.zeros_like(runtime)
+    used_peak = 0
+    retained_embedded_phase = 0
+    for measurement in range(measurements):
+        peaks = np.asarray([
+            _subsample_peak(hrir[measurement, 0]),
+            _subsample_peak(hrir[measurement, 1]),
+        ], dtype=np.float64)
+        if float(np.max(peaks)) > 2.0:
+            delays = peaks
+            used_peak += 1
+        else:
+            # An effective response can have both ear FIRs beginning at sample
+            # zero while still carrying the correct ITD in complex phase.  Do
+            # not invent an external delay which SOFA did not author.
+            delays = np.zeros(2, dtype=np.float64)
+            retained_embedded_phase += 1
+        runtime[measurement] = delays
+        removed[measurement] = delays
+
+    aligned = np.empty_like(hrir)
+    for measurement in range(measurements):
+        for ear in range(2):
+            aligned[measurement, ear] = shift_signal_fft(
+                hrir[measurement, ear], -float(removed[measurement, ear]))
+    source = (
+        f"embedded Data.IR arrival separation: peak={used_peak}, "
+        f"zero-origin embedded phase retained={retained_embedded_phase}; "
+        "positive onset restored once at render time")
+    return TimeAlignedHrtf(
+        canonical=canonical,
+        aligned_hrir=aligned,
+        runtime_delay_samples=runtime,
+        embedded_delay_removed_samples=removed,
+        delay_source=source,
+    )

src/sofa_native_backend.py

@@ -0,0 +1,398 @@
+"""Native float64 SOFA binaural DSP (ctypes bridge to eac3joc_core).
+
+The C++ side mirrors the Python :class:`sofa_binaural_backend.SofaBinauralBackend`
+mathematics: 64-QMF/77-hybrid analysis and synthesis, fifth-order ACN/N3D real
+spherical-harmonic field evaluation, whole-QMF-slot per-object delay histories,
+six image-source early reflections, the shared unitary FDN late room, the LFE
+low-pass and the 961-sample latency policy.  The compiled HRTF field, the
+filterbank tables and the room constants are uploaded once; per 512-sample
+block the adapter updates every source and streams PCM through the DLL.
+"""
+from __future__ import annotations
+
+import ctypes
+import math
+from pathlib import Path
+
+import numpy as np
+
+from native_renderer import ABI_VERSION, find_native_library
+from public_filterbank import DEFAULT_FILTERBANK_DATA, load_filterbank_tables
+from public_room import LateFdnConfig, SharedUnitaryFdn, ShoeboxRoomConfig
+from reference_distance import ReferenceDistanceProfileV1
+from sofa_binaural_backend import SofaBinauralBackend
+from sofa_hrtf_field import (
+    DEFAULT_HRTF_CACHE_DIR,
+    SofaHrtfField,
+    compile_sofa_hrtf,
+)
+
+BLOCK_SAMPLES = 512
+INPUT_CHANNELS = 16
+OUTPUT_CHANNELS = 2
+QMF_HOP = 64
+LATENCY_SAMPLES = 961
+
+_PROFILE_INDEX = {"near": 0, "mid": 1, "far": 2}
+
+
+def _room_numbers(fdn_config: LateFdnConfig) -> dict:
+    """Derive the FDN delays/feedback with the same arithmetic as the Python room."""
+    fdn = SharedUnitaryFdn(fdn_config)
+    return {
+        "fdn_delays": np.asarray(fdn.delays, dtype=np.uint32),
+        "fdn_feedback": np.asarray(fdn.feedback_gain, dtype=np.float64),
+        "damping": fdn.damping,
+        "output_gain": fdn.output_gain,
+        "allpass_delays": np.asarray(
+            [diffuser.delay_samples for diffuser in fdn.diffusers], dtype=np.uint32),
+        "allpass_gains": np.asarray(fdn_config.allpass_gain, dtype=np.float64),
+        "tail_samples": fdn.tail_samples,
+    }
+
+
+class NativeSofaBinauralDsp:
+    """Duck-type compatible with SofaBinauralBackend for the JOC adapter."""
+
+    def __init__(
+            self,
+            field: SofaHrtfField,
+            *,
+            source_count: int = INPUT_CHANNELS,
+            default_profile: str = "mid",
+            enable_early_reflections: bool = True,
+            enable_late_room: bool = True,
+            room_config: ShoeboxRoomConfig = ShoeboxRoomConfig(),
+            fdn_config: LateFdnConfig | None = None,
+            library_path: str | Path | None = None):
+        if not isinstance(field, SofaHrtfField):
+            raise TypeError("field must be SofaHrtfField")
+        self.source_count = int(source_count)
+        self.default_profile = ReferenceDistanceProfileV1.validate_profile(default_profile)
+        self.enable_early_reflections = bool(enable_early_reflections)
+        self.enable_late_room = bool(enable_late_room)
+        self.field = field
+        if self.source_count != INPUT_CHANNELS:
+            raise ValueError(f"native SOFA backend requires {INPUT_CHANNELS} sources")
+        if abs(self.field.sample_rate_hz - 48000.0) > 1.0e-9:
+            raise ValueError("the native SOFA binaural runtime requires 48 kHz")
+        self.room_config = room_config
+        self.room_config.validate()
+        self.dsp_backend = "native-sofa"
+        self.hrtf_input_kind = "field"
+        self.hrtf_input_path = None
+        self.cache_policy = None
+
+        self.library_path = find_native_library(library_path)
+        self._lib = ctypes.CDLL(str(self.library_path))
+        self._bind()
+        version = int(self._lib.ejoc_abi_version())
+        if version != ABI_VERSION:
+            raise RuntimeError(
+                f"native ABI mismatch: expected {ABI_VERSION}, got {version}")
+        self._handle = self._lib.ejoc_sofa_binaural_create()
+        if not self._handle:
+            raise RuntimeError("native SOFA binaural renderer creation failed")
+        try:
+            self._configure_kernels()
+            self._configure_field()
+            self._configure_room(fdn_config)
+        except Exception:
+            self.close()
+            raise
+
+        self.positions = np.zeros((self.source_count, 3), dtype=np.float64)
+        self.positions[:, 1] = 1.0
+        self.profiles = [self.default_profile] * self.source_count
+        self.user_gain = np.ones(self.source_count, dtype=np.float64)
+        self.special_lfe = np.zeros(self.source_count, dtype=bool)
+        self.parameter_updates = 0
+        self.finished = False
+        for source in range(self.source_count):
+            self.set_source(
+                source, self.positions[source], profile=self.default_profile,
+                fade=False)
+
+    def _bind(self):
+        void_p = ctypes.c_void_p
+        f64_p = ctypes.POINTER(ctypes.c_double)
+        i16_p = ctypes.POINTER(ctypes.c_int16)
+        u32_p = ctypes.POINTER(ctypes.c_uint32)
+        self._lib.ejoc_abi_version.argtypes = []
+        self._lib.ejoc_abi_version.restype = ctypes.c_uint32
+        self._lib.ejoc_sofa_binaural_create.argtypes = []
+        self._lib.ejoc_sofa_binaural_create.restype = void_p
+        self._lib.ejoc_sofa_binaural_destroy.argtypes = [void_p]
+        self._lib.ejoc_sofa_binaural_destroy.restype = None
+        self._lib.ejoc_sofa_binaural_reset.argtypes = [void_p]
+        self._lib.ejoc_sofa_binaural_reset.restype = ctypes.c_int
+        self._lib.ejoc_sofa_binaural_last_error.argtypes = [void_p]
+        self._lib.ejoc_sofa_binaural_last_error.restype = ctypes.c_char_p
+        self._lib.ejoc_sofa_binaural_configure_kernels.argtypes = [
+            void_p, f64_p, f64_p, i16_p, f64_p, ctypes.c_uint32, f64_p, f64_p]
+        self._lib.ejoc_sofa_binaural_configure_kernels.restype = ctypes.c_int
+        self._lib.ejoc_sofa_binaural_configure_field.argtypes = [
+            void_p, f64_p, f64_p, f64_p, f64_p, ctypes.c_double]
+        self._lib.ejoc_sofa_binaural_configure_field.restype = ctypes.c_int
+        self._lib.ejoc_sofa_binaural_configure_room.argtypes = [
+            void_p, f64_p, f64_p, f64_p, ctypes.c_double, u32_p, f64_p,
+            ctypes.c_double, ctypes.c_double, u32_p, f64_p,
+            ctypes.c_uint32, ctypes.c_uint32]
+        self._lib.ejoc_sofa_binaural_configure_room.restype = ctypes.c_int
+        self._lib.ejoc_sofa_binaural_set_source.argtypes = [
+            void_p, ctypes.c_uint32, f64_p, ctypes.c_uint32, ctypes.c_double,
+            ctypes.c_uint32, ctypes.c_uint32, ctypes.c_uint32]
+        self._lib.ejoc_sofa_binaural_set_source.restype = ctypes.c_int
+        self._lib.ejoc_sofa_binaural_process.argtypes = [
+            void_p, f64_p, ctypes.c_uint32, ctypes.c_double, f64_p]
+        self._lib.ejoc_sofa_binaural_process.restype = ctypes.c_int
+        self._lib.ejoc_sofa_binaural_finish.argtypes = [
+            void_p, ctypes.c_uint32, f64_p, ctypes.c_uint32]
+        self._lib.ejoc_sofa_binaural_finish.restype = ctypes.c_int
+
+    def _raise(self, operation, status):
+        message = self._lib.ejoc_sofa_binaural_last_error(self._handle)
+        detail = (message or b"").decode("utf-8", "replace")
+        raise RuntimeError(
+            f"native SOFA binaural renderer {operation} failed ({status}): {detail}")
+
+    @staticmethod
+    def _f64_pointer(values):
+        return values.ctypes.data_as(ctypes.POINTER(ctypes.c_double))
+
+    def _configure_kernels(self):
+        tables = load_filterbank_tables(DEFAULT_FILTERBANK_DATA)
+        qmf_analysis = np.ascontiguousarray(
+            tables["qmf_analysis_coefficients"], dtype=np.float64)
+        hybrid_low = np.ascontiguousarray(
+            tables["hybrid_analysis_low_kernel"], dtype=np.float64)
+        hybrid_indices = np.ascontiguousarray(
+            tables["hybrid_synthesis_indices"], dtype=np.int16)
+        hybrid_values = np.ascontiguousarray(
+            tables["hybrid_synthesis_values"], dtype=np.float64)
+        qmf_basis = np.ascontiguousarray(
+            tables["qmf_synthesis_basis"], dtype=np.float64)
+        qmf_taps = np.ascontiguousarray(
+            tables["qmf_synthesis_taps"], dtype=np.float64)
+        status = self._lib.ejoc_sofa_binaural_configure_kernels(
+            self._handle,
+            self._f64_pointer(qmf_analysis),
+            self._f64_pointer(hybrid_low),
+            hybrid_indices.ctypes.data_as(ctypes.POINTER(ctypes.c_int16)),
+            self._f64_pointer(hybrid_values),
+            len(hybrid_indices),
+            self._f64_pointer(qmf_basis),
+            self._f64_pointer(qmf_taps))
+        if status:
+            self._raise("configure_kernels", status)
+        self._keepalive = (qmf_analysis, hybrid_low, hybrid_indices,
+                           hybrid_values, qmf_basis, qmf_taps)
+
+    def _configure_field(self):
+        coefficients = np.ascontiguousarray(
+            self.field.coefficients, dtype=np.complex128).view(np.float64)
+        delay_coefficients = np.ascontiguousarray(
+            self.field.delay_coefficients, dtype=np.float64)
+        delay_bounds = np.ascontiguousarray(
+            self.field.delay_bounds, dtype=np.float64)
+        centers = np.ascontiguousarray(
+            self.field.band_center_frequencies_hz, dtype=np.float64)
+        status = self._lib.ejoc_sofa_binaural_configure_field(
+            self._handle,
+            self._f64_pointer(coefficients),
+            self._f64_pointer(delay_coefficients),
+            self._f64_pointer(delay_bounds),
+            self._f64_pointer(centers),
+            float(self.field.measurement_radius_m))
+        if status:
+            self._raise("configure_field", status)
+
+    def _configure_room(self, fdn_config: LateFdnConfig | None):
+        actual = fdn_config or LateFdnConfig(sample_rate_hz=48000.0)
+        numbers = _room_numbers(actual)
+        dims = np.asarray(self.room_config.dimensions_m, dtype=np.float64)
+        listener = np.asarray(self.room_config.listener_position_m, dtype=np.float64)
+        walls = np.asarray(self.room_config.wall_reflection_gain, dtype=np.float64)
+        status = self._lib.ejoc_sofa_binaural_configure_room(
+            self._handle,
+            self._f64_pointer(dims),
+            self._f64_pointer(listener),
+            self._f64_pointer(walls),
+            float(self.room_config.speed_of_sound_m_s),
+            numbers["fdn_delays"].ctypes.data_as(ctypes.POINTER(ctypes.c_uint32)),
+            self._f64_pointer(numbers["fdn_feedback"]),
+            float(numbers["damping"]),
+            float(numbers["output_gain"]),
+            numbers["allpass_delays"].ctypes.data_as(ctypes.POINTER(ctypes.c_uint32)),
+            self._f64_pointer(numbers["allpass_gains"]),
+            1 if self.enable_early_reflections else 0,
+            1 if self.enable_late_room else 0)
+        if status:
+            self._raise("configure_room", status)
+        self._fdn = SharedUnitaryFdn(actual)
+        self._fdn_tail_samples = numbers["tail_samples"]
+
+    def set_source(self, source: int, position_adm, *, profile: str | None = None,
+                   gain: float = 1.0, enabled: bool = True,
+                   special_lfe: bool = False, fade: bool = True) -> None:
+        if self.finished:
+            raise RuntimeError("SOFA renderer is finished")
+        source = int(source)
+        if not 0 <= source < self.source_count:
+            raise IndexError(source)
+        name = self.default_profile if profile is None else profile
+        position = np.asarray(position_adm, dtype=np.float64)
+        if position.shape != (3,):
+            raise ValueError("ADM position must contain three Cartesian values")
+        status = self._lib.ejoc_sofa_binaural_set_source(
+            self._handle, source,
+            self._f64_pointer(np.ascontiguousarray(position)),
+            _PROFILE_INDEX[ReferenceDistanceProfileV1.validate_profile(name)],
+            float(gain), 1 if enabled else 0, 1 if special_lfe else 0,
+            1 if fade else 0)
+        if status:
+            self._raise("set_source", status)
+        self.positions[source] = position
+        self.profiles[source] = name
+        self.user_gain[source] = float(gain)
+        self.special_lfe[source] = bool(special_lfe)
+        self.parameter_updates += 1
+
+    def process(self, sources) -> np.ndarray:
+        if self.finished:
+            raise RuntimeError("SOFA renderer is finished")
+        values = np.ascontiguousarray(sources, dtype=np.float64)
+        if values.ndim != 2 or values.shape[1] != self.source_count:
+            raise ValueError(f"sources must have shape [samples,{self.source_count}]")
+        if len(values) % QMF_HOP or len(values) > BLOCK_SAMPLES:
+            raise ValueError("native SOFA backend input must be a 64-aligned block")
+        output = np.empty((len(values), OUTPUT_CHANNELS), dtype=np.float64)
+        count = self._lib.ejoc_sofa_binaural_process(
+            self._handle, self._f64_pointer(values), len(values), 1.0,
+            self._f64_pointer(output))
+        if count < 0:
+            self._raise("process", count)
+        return output[:count]
+
+    def finish(self, *, tail_seconds: float | None = None) -> np.ndarray:
+        if self.finished:
+            return np.zeros((0, OUTPUT_CHANNELS), dtype=np.float64)
+        if tail_seconds is not None and (
+                not math.isfinite(float(tail_seconds)) or float(tail_seconds) < 0.0):
+            raise ValueError("tail_seconds must be finite and non-negative")
+        flush = self.finish_output_capacity(tail_seconds)
+        pieces = []
+        remaining = flush
+        while remaining > 0:
+            chunk = min(BLOCK_SAMPLES, remaining)
+            output = np.empty((chunk, OUTPUT_CHANNELS), dtype=np.float64)
+            count = self._lib.ejoc_sofa_binaural_finish(
+                self._handle, chunk, self._f64_pointer(output), chunk)
+            if count < 0:
+                self._raise("finish", count)
+            pieces.append(output[:count])
+            remaining -= chunk
+        self.finished = True
+        nonempty = [piece for piece in pieces if len(piece)]
+        if not nonempty:
+            return np.zeros((0, OUTPUT_CHANNELS), dtype=np.float64)
+        return np.concatenate(nonempty, axis=0)
+
+    def finish_output_capacity(self, tail_seconds: float | None = None) -> int:
+        if tail_seconds is not None and (
+                not math.isfinite(float(tail_seconds)) or float(tail_seconds) < 0.0):
+            raise ValueError("tail_seconds must be finite and non-negative")
+        requested = (self._fdn_tail_samples if tail_seconds is None
+                     else int(math.ceil(float(tail_seconds) * 48000.0)))
+        maximum_hrtf = float(np.max(self.field.delay_bounds[:, 1], initial=0.0))
+        hrtf_slots = int(math.ceil(maximum_hrtf / QMF_HOP))
+        hrtf_bound = hrtf_slots * QMF_HOP
+        early_bound = hrtf_bound + 2048
+        if self.enable_early_reflections:
+            early_bound += 256 * QMF_HOP
+        drain = max(requested if self.enable_late_room else 0, early_bound)
+        drain += LATENCY_SAMPLES
+        return int(math.ceil(drain / QMF_HOP) * QMF_HOP)
+
+    def reset(self) -> None:
+        if self._lib.ejoc_sofa_binaural_reset(self._handle):
+            self._raise("reset", -1)
+        self.finished = False
+        for source in range(self.source_count):
+            self.set_source(
+                source, self.positions[source], profile=self.profiles[source],
+                gain=float(self.user_gain[source]),
+                special_lfe=bool(self.special_lfe[source]), fade=False)
+
+    def info(self) -> dict:
+        return {
+            "name": "NativeSofaBinauralDsp",
+            "source_count": self.source_count,
+            "sample_rate_hz": 48000.0,
+            "precision": "float64/complex128",
+            "signal_path": (
+                "native 64-QMF -> native 77-hybrid -> SOFA order-5 real-SH "
+                "direct/early -> native synthesis + shared unitary FDN"),
+            "hrtf_input_kind": self.hrtf_input_kind,
+            "hrtf_input_path": self.hrtf_input_path,
+            "cache_policy": self.cache_policy,
+            "latency_compensated_samples": LATENCY_SAMPLES,
+            "enable_early_reflections": self.enable_early_reflections,
+            "enable_late_room": self.enable_late_room,
+            "early_history_slots": 256,
+            "hrtf_history_slots": int(math.ceil(
+                float(np.max(self.field.delay_bounds[:, 1], initial=0.0)) / QMF_HOP)),
+            "maximum_hrtf_delay_samples": float(
+                np.max(self.field.delay_bounds[:, 1], initial=0.0)),
+            "parameter_updates": self.parameter_updates,
+            "distance": ReferenceDistanceProfileV1.info(),
+            "field": self.field.info(),
+            "library_path": str(self.library_path),
+            "native_backend": True,
+        }
+
+    def close(self) -> None:
+        handle = getattr(self, "_handle", None)
+        if handle:
+            self._lib.ejoc_sofa_binaural_destroy(handle)
+            self._handle = None
+        self.finished = True
+
+
+def create_native_sofa_renderer(
+        sofa, *, mode="mid", cache_policy="memory", cache_dir=None,
+        shell_radius_m=1.0, object_delay_samples=1473, tail_seconds=5.0,
+        output_gain=1.0, chunk_frames=64):
+    """Compile a SOFA source and build a JOC adapter over the native DSP."""
+    from binaural_renderer import SofaBinauralRenderer, resolve_sofa_hrtf
+
+    source = resolve_sofa_hrtf(sofa)
+    field = compile_sofa_hrtf(
+        source,
+        shell_radius_m=shell_radius_m,
+        cache_policy=cache_policy,
+        cache_dir=cache_dir)
+    backend = NativeSofaBinauralDsp(field, default_profile=mode)
+    backend.hrtf_input_kind = "sofa"
+    backend.hrtf_input_path = str(source)
+    backend.cache_policy = str(cache_policy).lower()
+    return SofaBinauralRenderer(
+        backend, mode=mode, object_delay_samples=object_delay_samples,
+        tail_seconds=tail_seconds, chunk_frames=chunk_frames)
+
+
+def create_native_compiled_cache_renderer(
+        cache, *, mode="mid", object_delay_samples=1473, tail_seconds=5.0,
+        output_gain=1.0, chunk_frames=64):
+    """Load a compiled cache and build a JOC adapter over the native DSP."""
+    from binaural_renderer import SofaBinauralRenderer, resolve_compiled_hrtf_cache
+
+    source = resolve_compiled_hrtf_cache(cache)
+    field = SofaHrtfField.load(source)
+    backend = NativeSofaBinauralDsp(field, default_profile=mode)
+    backend.hrtf_input_kind = "compiled_cache"
+    backend.hrtf_input_path = str(source)
+    backend.cache_policy = None
+    return SofaBinauralRenderer(
+        backend, mode=mode, object_delay_samples=object_delay_samples,
+        tail_seconds=tail_seconds, chunk_frames=chunk_frames)

src/speaker_wav.py

@@ -1,6 +1,7 @@
-"""Streaming spool and WAV writer for direct speaker-layout output."""
+"""Shared PCM spool, peak analysis, and WAV writer for direct outputs."""
 from __future__ import annotations
 
+import math
 import struct
 from pathlib import Path
 
@@ -13,48 +14,115 @@ _PCM_GUID = bytes.fromhex("0100000000001000800000aa00389b71")
 _FLOAT_GUID = bytes.fromhex("0300000000001000800000aa00389b71")
 
 
-class SpeakerPcmSpool:
-    """Temporary interleaved float32 store with float64 peak analysis."""
+class PcmSpool:
+    """Temporary interleaved PCM store with float64 peak and clipping analysis.
 
-    def __init__(self, path, sample_count, channel_count):
+    ``storage_dtype`` controls only the temporary representation.  Speaker
+    output keeps its historical float32 spool, while binaural uses float64 so
+    precision is reduced only by the selected final WAV format.
+    """
+
+    def __init__(self, path, sample_capacity, channel_count, *,
+                 expected_samples=None, storage_dtype="<f4",
+                 tail_threshold=None):
         self.path = Path(path)
-        self.sample_count = int(sample_count)
+        self.sample_capacity = int(sample_capacity)
+        self.sample_count = int(
+            self.sample_capacity if expected_samples is None else expected_samples)
+        self.expected_samples = (
+            None if expected_samples is None else int(expected_samples))
         self.channel_count = int(channel_count)
+        self.storage_dtype = np.dtype(storage_dtype)
+        self.tail_threshold = (
+            None if tail_threshold is None else float(tail_threshold))
+        if self.sample_capacity < 0 or self.channel_count <= 0:
+            raise ValueError("invalid PCM spool dimensions")
+        if self.expected_samples is not None and not (
+                0 <= self.expected_samples <= self.sample_capacity):
+            raise ValueError("expected_samples exceeds sample_capacity")
+        if self.tail_threshold is not None and (
+                not math.isfinite(self.tail_threshold) or self.tail_threshold < 0.0):
+            raise ValueError("tail_threshold must be finite and non-negative")
         self.position = 0
         self.peak = 0.0
         self.clipped_values = 0
-        self.values = np.memmap(
-            self.path, dtype="<f4", mode="w+",
-            shape=(self.sample_count, self.channel_count),
+        self.last_above_threshold = -1
+        self.kept_samples = None
+        self._values = np.memmap(
+            self.path, dtype=self.storage_dtype, mode="w+",
+            shape=(self.sample_capacity, self.channel_count),
         )
 
+    @property
+    def values(self):
+        if self._values is None:
+            raise RuntimeError("PCM spool is closed")
+        length = (self.position if self.kept_samples is None
+                  else self.kept_samples)
+        return self._values[:length]
+
     def write_frame(self, pcm):
         values = np.asarray(pcm, dtype=np.float64)
         if values.ndim != 2 or values.shape[1] != self.channel_count:
             raise ValueError(
-                f"speaker frame must have shape [samples,{self.channel_count}], got {values.shape}")
-        if self.position + len(values) > self.sample_count:
-            raise ValueError("speaker spool received more samples than allocated")
+                f"PCM frame must have shape [samples,{self.channel_count}], got {values.shape}")
+        if self.position + len(values) > self.sample_capacity:
+            raise ValueError("PCM spool received more samples than allocated")
         if not np.all(np.isfinite(values)):
-            raise ValueError("speaker renderer produced NaN or infinity")
+            raise ValueError("renderer produced NaN or infinity")
         absolute = np.abs(values)
         if absolute.size:
             self.peak = max(self.peak, float(np.max(absolute)))
             self.clipped_values += int(np.count_nonzero(absolute > 1.0))
-        self.values[self.position:self.position + len(values)] = values.astype(np.float32)
+            if self.tail_threshold is not None:
+                per_sample = np.max(absolute, axis=1)
+                above = np.flatnonzero(per_sample > self.tail_threshold)
+                if above.size:
+                    self.last_above_threshold = self.position + int(above[-1])
+        self._values[self.position:self.position + len(values)] = values.astype(
+            self.storage_dtype, copy=False)
         self.position += len(values)
 
-    def finalize(self):
-        if self.position != self.sample_count:
+    def finalize(self, *, minimum_samples=0):
+        if (self.expected_samples is not None
+                and self.position != self.expected_samples):
             raise ValueError(
-                f"speaker spool has {self.position} samples, expected {self.sample_count}")
-        self.values.flush()
+                f"PCM spool has {self.position} samples, expected {self.expected_samples}")
+        keep = self.position
+        if self.tail_threshold is not None:
+            keep = min(
+                self.position,
+                max(int(minimum_samples), self.last_above_threshold + 1),
+            )
+        self.kept_samples = keep
+        self.sample_count = keep
+        self._values.flush()
         return self
 
     def close(self):
-        values = self.values
-        self.values = None
-        del values
+        values = self._values
+        self._values = None
+        if values is not None:
+            del values
+
+
+class SpeakerPcmSpool(PcmSpool):
+    """Backward-compatible fixed-length float32 speaker spool."""
+
+    def __init__(self, path, sample_count, channel_count):
+        super().__init__(
+            path, sample_count, channel_count,
+            expected_samples=sample_count, storage_dtype="<f4")
+
+
+class BinauralPcmSpool(PcmSpool):
+    """Float64 variable-tail spool for the binaural renderer."""
+
+    def __init__(self, path, sample_capacity, *, tail_threshold=1.0e-8):
+        super().__init__(
+            path, sample_capacity, 2,
+            expected_samples=None, storage_dtype="<f8",
+            tail_threshold=tail_threshold)
 
 
 def _fmt_chunk(channel_count, rate, sample_format):
@@ -69,7 +137,7 @@ def _fmt_chunk(channel_count, rate, sample_format):
         simple_tag = WAVE_FORMAT_PCM
         guid = _PCM_GUID
     else:
-        raise ValueError(f"unsupported speaker WAV format: {sample_format}")
+        raise ValueError(f"unsupported WAV format: {sample_format}")
     block_align = channel_count * bytes_per_sample
     byte_rate = rate * block_align
     if channel_count <= 2:
@@ -94,13 +162,13 @@ def _write_header(stream, channel_count, sample_count, rate, sample_format):
     riff_file_size = 12 + 8 + len(fmt) + 8 + data_size
     use_rf64 = riff_file_size - 8 > 0xFFFFFFFF
     if use_rf64:
-        # RF64 + ds64 + fmt + data.
         file_size = 12 + 36 + 8 + len(fmt) + 8 + data_size
         stream.write(b"RF64")
         stream.write(struct.pack("<I", 0xFFFFFFFF))
         stream.write(b"WAVE")
         stream.write(b"ds64")
-        stream.write(struct.pack("<IQQQI", 28, file_size - 8, data_size, sample_count, 0))
+        stream.write(struct.pack(
+            "<IQQQI", 28, file_size - 8, data_size, sample_count, 0))
     else:
         stream.write(b"RIFF")
         stream.write(struct.pack("<I", riff_file_size - 8))
@@ -121,7 +189,8 @@ def _write_header(stream, channel_count, sample_count, rate, sample_format):
 
 
 def _pack_int24(values):
-    scaled = (np.clip(values, -1.0, 1.0) * np.float32(8388607.0)).astype(np.int32)
+    source = np.asarray(values)
+    scaled = (np.clip(source, -1.0, 1.0) * np.float32(8388607.0)).astype(np.int32)
     unsigned = scaled.reshape(-1).view(np.uint32)
     packed = np.empty((unsigned.size, 3), dtype=np.uint8)
     packed[:, 0] = unsigned & 0xFF
@@ -130,21 +199,22 @@ def _pack_int24(values):
     return packed.tobytes()
 
 
-def write_speaker_wav(path, pcm, sample_format, *, rate=48000, chunk_samples=262144):
-    """Write an interleaved float32 array/memmap as float32 or PCM24 WAV."""
+def write_pcm_wav(path, pcm, sample_format, *, rate=48000,
+                  chunk_samples=262144):
+    """Write an interleaved array/memmap as float32 or PCM24 WAV."""
     target = Path(path)
     values = np.asarray(pcm)
     if values.ndim != 2:
-        raise ValueError(f"speaker PCM must be 2D, got {values.shape}")
+        raise ValueError(f"PCM must be 2D, got {values.shape}")
     sample_count, channel_count = values.shape
     target.parent.mkdir(parents=True, exist_ok=True)
     with target.open("wb") as stream:
         info = _write_header(
             stream, channel_count, sample_count, int(rate), sample_format)
         for start in range(0, sample_count, int(chunk_samples)):
-            block = np.asarray(values[start:start + chunk_samples], dtype="<f4")
+            block = np.asarray(values[start:start + chunk_samples])
             if sample_format == "float32":
-                stream.write(block.tobytes(order="C"))
+                stream.write(block.astype("<f4", copy=False).tobytes(order="C"))
             else:
                 stream.write(_pack_int24(block))
     info.update({
@@ -155,3 +225,7 @@ def write_speaker_wav(path, pcm, sample_format, *, rate=48000, chunk_samples=262
         "file_bytes": target.stat().st_size,
     })
     return info
+
+
+# Existing imports remain valid.
+write_speaker_wav = write_pcm_wav

src/spherical_harmonics.py

@@ -0,0 +1,144 @@
+"""Orthonormal real spherical harmonics in ACN order, through fifth order."""
+from __future__ import annotations
+
+import math
+import numpy as np
+from scipy.spatial import SphericalVoronoi
+
+
+def _associated_legendre(order: int, degree: int, x: np.ndarray) -> np.ndarray:
+    """P_degree^order(x), including the Condon-Shortley phase."""
+    m = int(order)
+    l = int(degree)
+    if not 0 <= m <= l:
+        raise ValueError("associated Legendre indices require 0 <= m <= l")
+    x = np.asarray(x, dtype=np.float64)
+    p_mm = np.ones_like(x)
+    if m:
+        double_factorial = 1.0
+        for value in range(1, 2 * m, 2):
+            double_factorial *= value
+        p_mm = ((-1.0) ** m) * double_factorial * np.power(
+            np.maximum(0.0, 1.0 - x * x), 0.5 * m)
+    if l == m:
+        return p_mm
+    p_m1 = x * (2 * m + 1) * p_mm
+    if l == m + 1:
+        return p_m1
+    previous_previous = p_mm
+    previous = p_m1
+    for current_degree in range(m + 2, l + 1):
+        current = (
+            (2 * current_degree - 1) * x * previous
+            - (current_degree + m - 1) * previous_previous
+        ) / float(current_degree - m)
+        previous_previous, previous = previous, current
+    return previous
+
+
+def real_spherical_harmonics(directions, order: int = 5) -> np.ndarray:
+    """Return [directions,(order+1)^2] ACN/N3D real harmonics.
+
+    Coordinates use SOFA listener axes: +X front, +Y left, +Z up.  The basis is
+    orthonormal over the sphere and includes the Condon-Shortley phase.
+    """
+    maximum_order = int(order)
+    if not 0 <= maximum_order <= 12:
+        raise ValueError("supported spherical-harmonic orders are 0..12")
+    vectors = np.asarray(directions, dtype=np.float64)
+    one = vectors.ndim == 1
+    if one:
+        vectors = vectors[None, :]
+    if vectors.ndim != 2 or vectors.shape[1] != 3 or not np.isfinite(vectors).all():
+        raise ValueError("directions must have finite shape [M,3]")
+    length = np.linalg.norm(vectors, axis=1)
+    if np.any(length <= 1.0e-15):
+        raise ValueError("spherical-harmonic directions must be non-zero")
+    unit = vectors / length[:, None]
+    azimuth = np.arctan2(unit[:, 1], unit[:, 0])
+    cos_colatitude = np.clip(unit[:, 2], -1.0, 1.0)
+    result = np.empty((len(unit), (maximum_order + 1) ** 2), dtype=np.float64)
+    column = 0
+    for degree in range(maximum_order + 1):
+        for m in range(-degree, degree + 1):
+            absolute = abs(m)
+            normalization = math.sqrt(
+                (2 * degree + 1) / (4.0 * math.pi)
+                * math.factorial(degree - absolute)
+                / math.factorial(degree + absolute))
+            legendre = _associated_legendre(absolute, degree, cos_colatitude)
+            if m < 0:
+                value = math.sqrt(2.0) * normalization * legendre * np.sin(
+                    absolute * azimuth)
+            elif m > 0:
+                value = math.sqrt(2.0) * normalization * legendre * np.cos(
+                    m * azimuth)
+            else:
+                value = normalization * legendre
+            result[:, column] = value
+            column += 1
+    return result[0] if one else result
+
+
+def spherical_voronoi_weights(directions) -> np.ndarray:
+    """Area weights for an irregular full-sphere grid, with uniform fallback."""
+    vectors = np.asarray(directions, dtype=np.float64)
+    if vectors.ndim != 2 or vectors.shape[1] != 3:
+        raise ValueError("directions must have shape [M,3]")
+    unit = vectors / np.linalg.norm(vectors, axis=1)[:, None]
+    if len(unit) < 4:
+        return np.full(len(unit), 1.0 / len(unit), dtype=np.float64)
+    try:
+        voronoi = SphericalVoronoi(unit, radius=1.0, center=np.zeros(3))
+        areas = np.asarray(voronoi.calculate_areas(), dtype=np.float64)
+        if not np.isfinite(areas).all() or np.any(areas <= 0.0):
+            raise ValueError("invalid spherical Voronoi areas")
+        return areas / np.sum(areas, dtype=np.float64)
+    except (ValueError, RuntimeError, np.linalg.LinAlgError):
+        return np.full(len(unit), 1.0 / len(unit), dtype=np.float64)
+
+
+def fit_real_spherical_harmonics(directions, values, *, order: int = 5,
+                                 ridge: float = 1.0e-6,
+                                 weights=None) -> np.ndarray:
+    """Weighted ridge fit.  Output shape is [terms,...value trailing axes]."""
+    basis = real_spherical_harmonics(directions, order=order)
+    target = np.asarray(values)
+    if target.shape[0] != basis.shape[0]:
+        raise ValueError("spherical-harmonic target count does not match directions")
+    if target.dtype.kind == "c":
+        target = np.asarray(target, dtype=np.complex128)
+        solve_dtype = np.complex128
+    else:
+        target = np.asarray(target, dtype=np.float64)
+        solve_dtype = np.float64
+    if weights is None:
+        weight = spherical_voronoi_weights(directions)
+    else:
+        weight = np.asarray(weights, dtype=np.float64)
+        if weight.shape != (len(basis),) or np.any(weight < 0.0) or not np.isfinite(weight).all():
+            raise ValueError("weights must be finite non-negative [M]")
+        total = float(np.sum(weight))
+        if total <= 0.0:
+            raise ValueError("weights must have positive sum")
+        weight = weight / total
+    flat = target.reshape(len(target), -1)
+    weighted_basis = basis * weight[:, None]
+    gram = basis.T @ weighted_basis
+    regularization = float(ridge)
+    if not math.isfinite(regularization) or regularization < 0.0:
+        raise ValueError("ridge must be finite and non-negative")
+    scale = float(np.trace(gram)) / gram.shape[0]
+    system = gram + np.eye(gram.shape[0], dtype=np.float64) * regularization * scale
+    right = basis.T @ (weight[:, None] * flat)
+    coefficients = np.linalg.solve(system.astype(solve_dtype), right.astype(solve_dtype))
+    return coefficients.reshape((basis.shape[1],) + target.shape[1:])
+
+
+def evaluate_real_spherical_harmonics(coefficients, directions,
+                                      *, order: int = 5) -> np.ndarray:
+    basis = real_spherical_harmonics(directions, order=order)
+    coeff = np.asarray(coefficients)
+    if coeff.shape[0] != (int(order) + 1) ** 2:
+        raise ValueError("coefficient term count does not match order")
+    return np.tensordot(basis, coeff, axes=([-1], [0]))