Files
mpv-joc/fork/README.md
T

231 lines
11 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.
# mpv + ad_joc — 原生轨道的 E-AC-3 JOC 解码器(实验)
这是 [TheM14/JustOneCacophony](https://github.com/TheM14/JustOneCacophony) 渲染内核在 mpv 里的解码器接入(补丁形式)。内核本身
不在这里,构建时链接上游的 `joc_core`;行为基准是上游项目自带的 `joc_cli`。
这是"接管文件"那条路的最小可行实现:给 **mpv 本身**加一个音频解码模块 `ad_joc`,用
`--ad=joc` 启用。mpv 的 AD 层拿到的是 demuxer 给的 **AVPacket**(原始 E-AC-3 访问单元),
所以不需要改 FFmpeg;解码出来的对象音频直接作为 mpv 自己的音频流,走它原本的滤镜链、
重采样、A/V 同步与音频输出。
这和插件方案(`mpv-joc` 的 cplugin + loopback 音频源)是两条路:
| | cplugin + 回环音频源 | `ad_joc`(本目录) |
|---|---|---|
| 改动对象 | 零,stock mpv | mpv 源码,需要自己构建 |
| 轨道 | 额外一条 `pcm_f32le` 外部轨 | 文件自己的轨,codec 显示正确 |
| 片头 | 0.3–0.6 s 准备(静音) | 无 |
| 跳转 | 渲染器可按 64 帧预滚重入 | mpv 不给预滚包,冷启动约 1 s 收敛 |
| 维护 | 跟随 mpv 的 cplugin ABI | 跟随 mpv 的 AD 接口 |
## 基于哪个 mpv
mpv master,提交 `01e2533f3143b8940857ca419b0b367f583e05ca`(2026-10-17,`v0.41.0-UNKNOWN`)。
本目录的 `patches/mpv-ad-joc.patch` 是针对这个提交的 diff,也在 `fffe7a23a8`(2026-10-18)
上无冲突应用并完成构建验证;再新的版本如果碰到上下文变化,需要重新对齐
`filters/f_decoder_wrapper.c` 里的注册位置。
## 组成
```text
files/audio/decode/
ad_joc.c / ad_joc.h 解码器:libavcodec 解 bed + joc_stream 渲染 + 输出 aframe
joc_eac3.c / joc_eac3.h E-AC-3 同步帧/音频帧边界(上游 eac3_scan 的 C 子集)
joc_core.h joc_core 公共头(与 JustOneCacophonyCXX 逐字节一致)
joc_stream.h
joc_version.h
patches/mpv-ad-joc.patch 对 meson.build / meson.options / f_decoder_wrapper / options 的改动
```
注册方式与 mpv-omniphony 的 `ad_orender` 相同:`f_decoder_wrapper.c` 里当 `--ad` 列表包含
`joc` 且编码是 `eac3` 时切换 driver;`meson.build` 里加源码、链接 `joc_core`、定义
`HAVE_JOC`;`options/*` 加 `--ad-joc-*` 选项组。
## 维护方式:文件 + 锚点,而不是行号补丁
仓库里保存的是**新增文件**加**对上游的少量改动**,不是一整份 mpv:
```text
files/audio/decode/ 7 个新文件(ad_joc / joc_eac3 / 三个 joc 头)
tools/apply_edits.py 把 6 处改动按"锚点"写进 mpv 源码树
patches/ 同一改动的 diff,供精确复现
tools/build_fork.ps1 一键:clone 指定 ref → 应用 → 构建 → 打包
```
`apply_edits.py` 不依赖行号:它找 `static bool reinit_decoder`、`if (!driver)`、
`{"ad-lavc", OPT_SUBSTRUCT(...)}` 这类锚点插入代码,并且是幂等的。上游挪了行、改了上下文都不会
影响;只有当锚点本身消失(上游重构了这段)时,它会**在改动任何文件之前**报出文件名退出——那就是
需要人工适配的地方,通常只是换一个新锚点。
适配新 mpv 的流程:
```powershell
.\tools\build_fork.ps1 # clone 最新 master、应用、构建
.\tools\build_fork.ps1 -MpvRef v0.42.0
.\tools\build_fork.ps1 -SkipBuild # 只验证能否应用
```
### 自动化(GitHub Actions)
- 仓库根目录的 `.github/workflows/build.yml`:`workflow_dispatch`(可填 mpv 的 branch/tag/commit)或推 `v*` 标签时,
在 windows-latest 上 clone 最新 mpv、应用改动、用 MSVC 构建 joc_core、用 MSYS2 构建 mpv、
收集 DLL 并上传 `mpv-ad-joc-windows` 产物。
- 仓库根目录的 `.github/workflows/drift.yml`:每天定时 clone 最新 mpv master,只跑 `apply_edits.py`。锚点失效会直接
让这个 job 变红,比发布时才发现要好。
> 这两个 workflow 是在本机准备、按本地验证过的步骤写的;GitHub 上还没实际跑过,第一次运行可能
> 要调依赖路径(尤其 joc_core 的 CMake 产物目录)。
## 跨平台
代码本身是可移植的:`ad_joc.c` 只有取 exe 目录那段在 `_WIN32` 下(其它平台走 mpv 配置目录搜索),
`joc_core` 的 CMake 里本来就有 `if(UNIX)` 分支(ELF/Mach-O 的 rpath),导出宏也区分了 `_WIN32`。
目前只在 Windows 上验证过。移植到 Linux/macOS 需要:
1. `joc_core` 用系统的 CMake 构建成 `libjoc_core.so`/`.dylib`;
2. meson 找到它,并给它加 rpath(或运行时装 `LD_LIBRARY_PATH`);
3. 构建脚本换成 bash(`build_fork.ps1` 是 Windows 版),CI 加一个 ubuntu/macos job。
Android(`libmpv.so`)的可行性调研见 [docs/android.md](docs/android.md)。
## 构建(Windows / MSYS2)
需要 msys2 的 mingw64 环境(本机验证版本:gcc 16.2.0、ffmpeg 9.0.2、meson 1.12.1、ninja 1.13.2):
```bash
pacman -S --needed mingw-w64-x86_64-gcc mingw-w64-x86_64-meson \
mingw-w64-x86_64-ninja mingw-w64-x86_64-pkgconf mingw-w64-x86_64-ffmpeg \
mingw-w64-x86_64-luajit
```
把本目录的 `files/` 覆盖到 mpv 源码树,然后:
```bash
cd mpv-src
git apply /path/to/patches/mpv-ad-joc.patch
export PATH=/mingw64/bin:$PATH
meson setup build --buildtype=release -Dgpl=false -Dlua=luajit \
-Djoc-core-dir=/c/path/to/joc_core_import_lib_dir
ninja -C build
```
`-Dlua=luajit` 是必须的:mpv 的内置 OSC(进度条 / 播放控制)和所有脚本都编译在 Lua 之上,
不带 Lua 时 `--osc` 选项本身都不存在,界面就是空的。
`-Djoc-core-dir` 指向含 `joc_core.lib` 的目录(JustOneCacophonyCXX 的 `joc_core` 构建产物;
本机是 `mpv-joc/build/joc_core/Release`)。运行前把 `joc_core.dll` 放到 `mpv.exe` 旁边。
## 用法
所有设置都是普通 mpv 选项,写进 `mpv.conf` 就对每次播放生效:
```ini
# mpv.conf
ad = joc
ad-joc-binaural = yes # 默认就是 yes(双声道输出)
ad-joc-hrtf = C:/HRTF/binaural.sofa # 可省:会自动找
ad-joc-layout = 7.1 # 仅 binaural=no 时使用
ad-joc-mode = mid
ad-joc-gain-db = 0
```
命令行等价:`mpv --ad=joc movie.mkv`。
| 选项 | 取值 | 默认 |
|---|---|---|
| `--ad-joc-binaural` | yes / no | yes |
| `--ad-joc-hrtf` | SOFA / Rosella / `.jochrtf` 路径 | 空(自动搜索) |
| `--ad-joc-layout` | `2.0` `3.1` `4.0 Surround` `4.0 Quad` `5.1` `7.1` `5.1.2` `5.1.4` `7.1.2` `7.1.4` `9.1.4` `9.1.6`(旧值 `4.0` 仍按 `4.0 Surround`) | 7.1 |
| `--ad-joc-mode` | near / far / mid | mid |
| `--ad-joc-gain-db` | -60 … 12 | 0 |
| `--ad-joc-int24` | yes / no | no |
`--ad-joc-int24` 把输出量化到渲染器的 24-bit 规则(与上游前端的 int24 交付一致):
clip 到 [-1,1]、乘 8388607、向零截断、取低 24 位,再按 `n / 2^23` 读回。默认关闭,
输出就是渲染器的 float32。
本仓库**不附带任何 HRTF 文件**:SOFA、Rosella 模型、编译出的 `.jochrtf` 缓存都不随仓库或发布包
分发,需要自备。
### HRTF 的三种输入与自动判断
`--ad-joc-hrtf` 不需要说明类型,按文件内容判断(扩展名只作兜底):
| 输入 | 判断依据 | 交给渲染器 |
|---|---|---|
| SOFA | HDF5 魔数 `89 48 44 46 0D 0A 1A 0A` | `hrtf_sofa_path` |
| Rosella 个性化模型 | 首字符 `{` 且含 `"personalized_hrtf"` | `personalized_headphone_path` |
| 已编译核 | 扩展名 `.jochrtf` | `hrtf_path` |
SOFA 编译结果会缓存成 `.jochrtf`(本机首帧 320 ms 左右,命中缓存后 110 ms 左右),
缓存目录是 `<config>/cache/joc-hrtf-cache`,没有 config 目录时用 `<mpv.exe>/joc-hrtf-cache`。
### 不写 `--ad-joc-hrtf` 时
按下面的顺序找,找到即用:
1. `<mpv.exe>/HRTF/binaural.sofa`
2. `<mpv.exe>/HRTF/binaural.personalized_headphone`
3. `<mpv.exe>/HRTF/binaural.jochrtf`
4. `<config>/joc-hrtf/binaural.sofa`
5. `<config>/joc-hrtf/binaural.personalized_headphone`
都找不到就打印一行提示,退回扬声器布局渲染(默认 7.1),由 mpv 按输出设备下混——双声道
设备上仍然是双声道输出,不会没声音。
普通 E-AC-3(没有 JOC 元数据)不会失败:解码器先看前 8 个音频帧,渲染器一帧都没输出就判定
这不是 JOC 流,打印一行 `this E-AC-3 stream carries no JOC metadata; decoding it with the
default decoder instead`,然后把已经读掉的包补喂给 mpv 自己的 E-AC-3 解码器,后续照常播放
(`--ad=joc` 因此可以一直开着,混合片库也能用)。
### 便携化(不装 MSYS2 也能双击运行)
MinGW 构建的 `mpv.exe` 依赖 `/mingw64/bin` 下的一批 DLL。把依赖闭包复制到 `mpv.exe` 旁边即可:
```bash
bash tools/bundle_dlls.sh /c/path/to/mpv-src/build # 递归 ldd,把 /mingw64 下的依赖拷到 exe 旁边
```
之后 `mpv.exe` 只靠系统目录就能启动(本机实测:`PATH=C:\Windows\System32` 下 `--version` 与播放均正常)。
`tools/bundle_dlls.sh` 是本目录里的脚本,路径按构建目录改一下即可。
## 验证结果(本机)
用 `--ao=pcm --ao-pcm-file=out.wav` 抓解码器实际输出的 PCM,与 `joc_cli` 的参考 WAV 逐字节比较:
| 模式 | 结果 |
|---|---|
| 双耳 float32(SOFA,自动发现) | 8 s(3,071,992 B)**逐字节一致** |
| 双耳 float32(Rosella,自动识别) | 8 s(3,071,992 B)**逐字节一致** |
| 扬声器 7.1 float32 | 8 s(12,287,968 B)**逐字节一致** |
| 扬声器 7.1.4 float32 | 8 s **逐字节一致** |
| 扬声器 9.1.4 / 9.1.6 float32 | 能播、通道数正确(14 / 16);通道内容与 `joc_cli` 相同,但 mpv 按自己的标准声道顺序排列,所以字节序列不是逐字节相同 |
| 双耳 int24 | 与 24-bit 规则逐样本一致(256,000 样本 0 差异) |
| 非 JOC 的普通 5.1 E-AC-3 | 打印回退提示,按原生 5.1 播放(exit 0) |
| 默认 `--ad=lavc` | 不受影响,仍是原生 8ch downmix 行为 |
## 已知限制
* **跳转时渲染器会重建**,不复用旧状态:重建前渲染器里排队的输出属于旧位置,若沿用会在 seek 后
被当成新位置播放(实测约 1 s,与新旧内容都对不上,RMS ~0.25)。重建后输出就是目标位置的内容,
与“从该位置新建”的渲染在 1 s 窗口内 RMS ~0.005。
* 由于 mpv seek 后只给 1 个(有时 0 个)预滚包,重建后的前 ~1 s 与“从头连续渲染”仍有残差
(末段 ~7e-5):这是缺少历史状态所致,内容本身正确。带文件访问的前端能消除它,是因为
它们可以预滚 64 帧,AD 拿不到这些帧。
* 只注册 `eac3`(`ac3` 没有 JOC)。非 JOC 的 E-AC-3 会自动回退,代价是开头约 0.26 s
(8 帧)的判定窗口。
* 双耳需要 HRTF:给 `--ad-joc-hrtf`,或把 `binaural.sofa` 放在 `mpv.exe` 旁边;都没有时
退回扬声器布局,不再报错退出。
* 每换一个 mpv 版本都要重新对齐 patch(AD 接口和注册点在 mpv 内部,不在稳定 ABI 里)。
## 许可
`ad_joc.c` / `ad_joc.h` / `joc_eac3.*` 都是 MIT(见仓库根的 [LICENSE](../LICENSE)):
`joc_eac3.*` 改写自上游的 `eac3_scan.cpp`,`ad_joc.*` 是新增代码。
它们编译进 mpv,因此最终播放器的分发随 mpv 的许可(LGPL-2.1-or-later,`-Dgpl=true`
时为 GPL-2.0-or-later),全文见 [LICENSE-mpv](../LICENSE-mpv)。
`joc_core.h` / `joc_stream.h` / `joc_version.h` 来自 JustOneCacophonyCXX(MIT),逐字节复制。
`joc_core.dll` 本身仍是 MIT,不在本仓库分发。