Files
JustOneCacophony/README.md
T
TheM14 6f6b5db6c2
ci / ubuntu-latest (push) Failing after 15s
ci / macos-latest (push) Has been cancelled
ci / windows-latest (push) Has been cancelled
Add JOC downmix configurations 0..4, cross-layer notes, and the analysis-side clipgain
2026-10-16 19:52:04 +08:00

9.3 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 单元让 SOFA 双耳 内核快 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

# 双耳(HRTF 默认取 <exe>/HRTF/binaural.sofa,其次 <exe>/HRTF/binaural.personalized_headphone)
joc_cli input.m4a --binaural
joc_cli input.m4a --binaural --sofa-hrtf HRTF/other.sofa   # 换一个 SOFA
joc_cli input.m4a --binaural --personalized-headphone      # Rosella 个性化模型
#   -> output/<名称>.binaural.wav

# 其它常用开关
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 可改路径)。

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

库集成

引擎与文件任务使用 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 掩码与 k 不一致时,只记 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。