Files
JustOneCacophony/README.md
T
TheM14 20f2e77664
ci / ubuntu-latest (push) Failing after 18s
ci / macos-latest (push) Canceled after 0s
ci / windows-latest (push) Canceled after 0s
ci / release (push) Canceled after 0s
Keep only the Rosella and .jochrtf binaural paths
The kernel renders two inputs now: the Rosella .personalized_headphone model and
an already compiled .jochrtf field. The SOFA reader, its compile cache and the
field fit leave the kernel, and the direct SOFA runtime built on them goes with
them: the point-source distance reference, the shoebox image-source model, the
generated FDN tables and the asset archives are all gone. Fitting a SOFA into a
.jochrtf belongs to the offline toolchain.

The compiled-field runtime is the one that predates that work: 64-QMF analysis,
77 hybrid bands, per-object path delays and the project room (image sources plus
the shared unitary FDN) computed in code. It keeps its behaviour and takes the
.jochrtf name throughout: sofa_binaural_renderer.cpp -> jochrtf_renderer.cpp,
binaural_runtime.* -> jochrtf_runtime.*, SofaBinauralRuntime -> JochrtfRuntime,
ejoc_sofa_binaural_* -> ejoc_jochrtf_*.

The room becomes a switch. --jochrtf-room on|off (default on) drives the
enable_early_reflections and enable_late_room flags of the existing room
configuration; off renders the field's direct binaural sound only.
joc_task_config and joc_stream_config drop hrtf_sofa_path, hrtf_cache_dir,
hrtf_cache_policy and hrtf_radius_m, and gain jochrtf_room. The CLI no longer
accepts --sofa-hrtf, --hrtf-cache-policy, --hrtf-cache-dir or --hrtf-radius-m;
without an explicit input the renderer uses HRTF/binaural.personalized_headphone,
and a .jochrtf has to be named through --compiled-hrtf-cache. The SOFA-only unit
tests go with the reader.

Rosella parsing, filterbank, room and timing are untouched. Both .jochrtf modes
reproduce the Python reference sample for sample, and ctest passes.
2026-11-01 19:19:00 +08:00

11 KiB
Raw Blame History

JustOneCacophony — C++ Core

English · 数学说明 · 双耳渲染 · SIMD 派发

JustOneCacophony 的 C++ 实现:E-AC-3 JOC 码流解析、对象重建与渲染的执行内核。它从 E-AC-3 同步帧中提取 EMDF、ID14 JOC 参数与 ID11 OAMD 元数据,结合 FFmpeg 解码出的核心 PCM(N=5 或 7) 重建 LFE 与 15 路对象 PCM,并输出 ADM BWF、指定扬声器布局的 WAV,或用编译好的 HRTF 方向场 直接输出双耳 WAV。

这是研究代码,不是完整、标准兼容或生产级的 JOC 解码器。它只覆盖已实现的码流形态,遇到未知 变体时明确报错,而不是假装一切都很和谐。

构建

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
ctest --test-dir build --output-on-failure

Windows(MSVC / VS 2022,静态 CRT)、Linux 与 macOS 由 .github/workflows/ci.yml 同时构建并跑 单元测试;本地只验证 MSVC。浮点行为是逐字节验收的一部分,因此不启用 fast-math:MSVC 用 /fp:precise,其他编译器用 -fno-fast-math。

最重的双耳循环由运行时派发:同一份二进制里装多套 ISA 代码,启动时按 CPUID/XGETBV 选最宽 的一套,输出逐字节不变(见 SIMD 与运行时派发)。JOC_ENABLE_AVX2 / JOC_ENABLE_AVX512(默认都 ON)只决定是否把这些单元编进二进制:带上 AVX2 单元让 .jochrtf 双耳 内核快 12.4%、Rosella 快 1.8%,而没有 AVX2 的 CPU 仍走基线(SSE2)路径。要产出只带基线 ISA 的二进制:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DJOC_ENABLE_AVX2=OFF

得到基线 ISA(SSE2)、任何 x86-64 都能跑的产物。非 MSVC 构建永远不会带上这个开关。

路径与编码

库内部所有路径都是 UTF-8,只在系统边界转换(src/foundation/fs_utf8.*):Windows 上经 std::filesystem::path(内部 UTF-16)落到 _wfopen/CreateProcessW,其他平台直接是字节。 命令行参数在 Windows 上由 GetCommandLineW + CommandLineToArgvW 重新解析,控制台设为 UTF-8,因此日文/中文等非 ASCII 路径(含 ffmpeg 子进程与输出文件)都能正常工作;单元测试里有 一条非 ASCII 路径的回归用例守在 ctest 里。

产物

产物 说明
joc_core.dll 执行内核:码流解析、JOC/OAMD、DSP、扬声器与双耳渲染、ADM BWF/WAV 落盘、文件任务、流式接口
joc_cli.exe 文件任务命令行前端
include/joc_core.h 引擎、遥测与文件任务接口(纯 C)
include/joc_stream.h 面向嵌入者的流式 push/pull 接口(纯 C,仅包含它即可)

命令行

参数与上游 Python CLI 完全一致:输入是位置参数,默认输出 25 通道 ADM BWF,用 --speaker-layout 或 --binaural 切换到另外两种模式;未指定 -o 时产物落在 output/。

# 默认:ADM BWF(本身就是 24-bit,没有也不需要格式参数)
joc_cli input.m4a
#   -> output/input.adm.wav

joc_cli input.m4a -o out/adm.wav                 # 指定输出

# 扬声器布局
joc_cli input.m4a --speaker-layout 5.1           # -> output/<名称>.5.1.wav
joc_cli input.m4a --speaker-layout 7.1.4 --speaker-output out/714.wav --speaker-format int24

# 双耳(默认取 <exe>/HRTF/binaural.personalized_headphone)
joc_cli input.m4a --binaural
joc_cli input.m4a --binaural --personalized-headphone      # Rosella 个性化模型
joc_cli input.m4a --binaural --compiled-hrtf-cache HRTF/subject.jochrtf   # 离线编译的 .jochrtf
joc_cli input.m4a --binaural --compiled-hrtf-cache HRTF/subject.jochrtf --jochrtf-room off
#   -> output/<名称>.binaural.wav
joc_cli input.m4a --binaural --personalized-headphone --rosella-filterbank 2   # 新版 Rosella 滤波器组

# 其它常用开关
joc_cli input.m4a --duration 30 --gain-db -3 --trajectory-mode dense64
joc_cli input.eac3 --metadata-only --print-metadata summary   # 只解析并打印元数据

--speaker-format / --binaural-format 默认 float32;int24 若会削波按 --clip-action 处理(默认 ask,非交互终端下需显式给出 continue/float32/abort)。--duration 以秒 为单位;--object-delay-samples、--speaker-metadata-offset、--binaural-tail-seconds、 --binaural-tail-threshold(默认 1e-8,双耳尾音裁切阈值)等默认值与上游一致。命令总是写出 <输出>.report.json(--report-json 可改路径)。

--rosella-filterbank 1|2 选择 Rosella 个性化模型使用的滤波器组:1(默认)是 13 taps / 6 slots 的公开滤波器组,2 是 11 taps / 3 slots 的捕获版。两者延迟分别为 961 / 448 samples, 系数、历史缓冲与 flush 容量各自独立;该选项只作用于 .personalized_headphone, .jochrtf 路径给出时直接报错。详见 Rosella 滤波器组。

与上游参数的差异:--backend python 与 metadata sidecar(--metadata-dir/ --metadata-cache/--metadata-backend sidecar)在本构建中不可用,给出时立刻报错并说明原因, 而不是静默忽略。本构建额外提供 --bed(已解码的 6 通道 float32 PCM,给出后不调用 ffmpeg 解码)、--kernels(滤波器组表路径)、--work-dir、--report-json、--dry-run、 --quiet、--rosella-filterbank。

扬声器布局与声道顺序

--speaker-layout 只接受下表 11 个布局,PCM/WAV 的声道顺序就是表里的顺序:

布局 声道顺序
2.0 L, R
3.1 L, R, C, LFE
4.0 L, R, Lrs, Rrs
5.1 L, R, C, LFE, Ls, Rs
7.1 L, R, C, LFE, Ls, Rs, Lrs, Rrs
5.1.2 L, R, C, LFE, Ls, Rs, Ltm, Rtm
5.1.4 L, R, C, LFE, Ls, Rs, Ltf, Rtf, Ltr, Rtr
7.1.2 L, R, C, LFE, Ls, Rs, Lrs, Rrs, Ltm, Rtm
7.1.4 L, R, C, LFE, Ls, Rs, Lrs, Rrs, Ltf, Rtf, Ltr, Rtr
9.1.4 L, R, C, LFE, Ls, Rs, Lrs, Rrs, Lw, Rw, Ltf, Rtf, Ltr, Rtr
9.1.6 L, R, C, LFE, Ls, Rs, Lrs, Rrs, Lw, Rw, Ltf, Rtf, Ltm, Rtm, Ltr, Rtr

4.0 是本项目补充的 Quad 布局(传统 Quad 的 FL FR BL BR),声道为 L R Lrs Rrs,不在杜比 文档的布局列表里;除它以外的布局及声道顺序均依据杜比相关规范定义。

多声道 WAV 使用 WAVE_FORMAT_EXTENSIBLE,dwChannelMask = 0:文件不声明 Windows 扬声器位置, PCM 声道顺序严格按上表,不按掩码位序重排。播放器、ASIO、DAW 或其他设备需要按声道编号自行完成 输出映射;本项目保证各 PCM 声道的内容和编号符合上表,不保证下游播放器自动识别杜比扬声器位置。

--speaker-layout 只接受上表 11 个名字;其它名字按未知布局报错。

库集成

引擎与文件任务使用 joc_core.h:joc_task_validate / joc_task_execute 跑一个文件任务并 通过回调返回状态事件,joc_task_result 给出帧数、峰值、字节数与 SHA-256。

播放器或解码组件使用 joc_stream.h:调用方按自己的节奏推入 E-AC-3 字节与对应的核心 PCM (或已重建的 objects16),再拉取渲染后的 PCM;分块粒度任意,输出与文件任务逐字节一致。

joc_stream_config config = {0};
config.struct_size = sizeof(config);
config.input = JOC_STREAM_IN_EAC3;      /* 或 JOC_STREAM_IN_PCM_OBJECTS16 */
config.output = JOC_STREAM_OUT_SPEAKER; /* 或 BINAURAL / PCM_OBJECTS16 */
config.speaker_layout_name = "5.1";
joc_stream* stream = NULL;
joc_stream_create(&config, &stream);
/* 循环:joc_stream_push(...) / joc_stream_pull(...) */
joc_stream_flush(stream);
joc_stream_destroy(stream);

契约:状态实例私有、可并存;同一实例的 push/pull 必须在同一线程;渲染是有状态的, 因此本版本不提供 seek——定位需要从流起点重新解码。扬声器/双耳通路的内核延迟为 961 样本,joc_stream_flush 负责排空双耳房间尾音。

目录

include/     公共 C ABI:joc_core.h(引擎/文件任务)、joc_stream.h(流式)、eac3joc_core.h(上游 ABI)
src/         实现:eac3_transport、emdf、joc_bitstream、joc_core、oamd、timeline、speaker、
             binaural、hrtf、adm、io、telemetry、task、stream、api、cli、simd
tests/       单元测试(CTest,自足,不需要外部素材)
docs/        数学说明、双耳渲染流程与 SIMD 派发

src/ 下 8 个文件是 JustOneCacophony 原生库的逐字节副本,永不修改(见 THIRD_PARTY_NOTICES.md)。

兼容性说明

joc_clipgain 的施加方式

joc_clipgain 在分析端并入分析标量:标量 = 1/16 × g(g = 1 + (y/32)·2^(x−4),8 bit 字段 x:3 | y:5)。出口的 ×16 抵消 1/16,净效果是 ×g,因此 clamp 处在增益之后 (clamp(16·IQMF·g_interp))。标量按帧保存在两个槽里:本帧前 256 个采样从上一帧值线性过渡、之后为 常数,复位后的第一帧直接取新值。g = 1 时插值恒等,且 clamp(x)·1 == clamp(x·1)。

object_delay_samples 默认 1473,与既有实现的行为保持一致;它是可配置字段,改动它会 改变 OAMD/ADM 时间对齐。上游调查认为该值应为 0,本项目为保持逐字节等价暂不改默认值。

joc_dmx_config_idx 0..4

覆盖全部五个档位:$N=5,7,7,5,7$,相位开关 \sigma(k)=(k\in\{3,4\}) 同时门控 Ls/Rs 的 -j 旋转与 band-0 21-tap FIR。N=7 档位必须解出 8 通道床,并按通道码映射:

k 额外那一对 解码器给出 8 通道的顺序 JOC 输入序(床下标)
1 Lb/Rb FL FR FC LFE BL BR SL SR 0 1 2 6 7 4 5
2 / 4 Tfl/Tfr FL FR FC LFE SL SR TFL TFR 0 1 2 4 5 6 7

ffmpeg 侧只在 N=5 档位传 -ac 6;N=7 档位不传 -ac,保留解码器自身的布局 (-ac 6 会把 5.1.2/7.1 下混成 5.1,-ac 8 会把 5.1.2 重映射成 7.1,两者都会丢信息)。

跨层一致性校验(§11.2):子流声明的全频段通道数必须等于 $N$,joc\_ext\_config\_idx 非零 时报未映射变体,对象数超过 15 时截断到 15 并记入 diagnostics——这几项会改变 DSP 输入,不一致就 拒绝。额外那一对的身份只进元数据、不进 DSP(§10.1):依赖子流 chanmap 与 k 不一致、或 OAMD 声明的 bed 布局可以比核心子流实际编码的声道多(例如 9.1.6 bed 只编 5.1 核心),只有核心 声道在 bed 布局里找不到位置才记 diagnostics 并照常解码,床映射按 chanmap 的通道码走。 同一音频帧里出现多个含 ID11/ID14 的 EMDF 容器时,按规格 §8.2 + Table 56 的关联规则打分: OAMD 与 JOC 载荷 groupid 相同且 ID14 能完整解析的优先,其次只看 ID14 能否解析;唯一最高分才用, 其余记入 diagnostics(emdf/extra_container_ignored)。额外那一对在 10 槽 ADM 骨架上的落位 ($k=1\to6/7$、$k\in{2,4}\to8/9$)会被记录,但床通道按现行契约不作为输出通道。

音频帧内完全没有 JOC EMDF 时(例如编码器没写首帧元数据),该帧的对象通道静音, QMF 分析与合成状态照常推进,并在统计里单独计数。

许可

MIT,见 LICENSE;第三方来源与专利边界见 THIRD_PARTY_NOTICES.md。