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

172 lines
9.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# JustOneCacophony — C++ Core
[English](README.en.md) · [数学说明](docs/math.md) · [双耳渲染](docs/binaural.md) · [SIMD 派发](docs/simd.md)
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 解码器。它只覆盖已实现的码流形态,遇到未知
变体时明确报错,而不是假装一切都很和谐。
## 构建
```powershell
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 与运行时派发](docs/simd.md))。`JOC_ENABLE_AVX2` /
`JOC_ENABLE_AVX512`(默认都 ON)只决定是否把这些单元编进二进制:带上 AVX2 单元让 SOFA 双耳
内核快 12.4%、Rosella 快 1.8%,而没有 AVX2 的 CPU 仍走基线(SSE2)路径。要产出只带基线 ISA
的二进制:
```powershell
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/`。
```powershell
# 默认: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;分块粒度任意,输出与文件任务逐字节一致。
```c
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` 负责排空双耳房间尾音。
## 目录
```text
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](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](LICENSE);第三方来源与专利边界见
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。