Files
mpv-joc/fork/README.md
T
TheM14 a2471ce502 Compile the fork decoder against the kernel that takes one HRTF input
ad_joc.c still asked the stream config for hrtf_sofa_path, hrtf_cache_dir and
hrtf_cache_policy, which the kernel no longer has; the same file is compiled by
the Windows and the Android build, so both stopped there.

The decoder now recognises only the Rosella model -- a JSON file containing a
personalized_hrtf object -- and passes its path to personalized_headphone_path.
The SOFA magic sniffing, the .jochrtf extension branch, the default cache
directory and the disk-cache retry path are gone, the default lookup is
HRTF/binaural.personalized_headphone, and the format warning for the frame length
uses %zu. The README, the fork docs and the example configs name the model file
instead of binaural.sofa.
2026-11-01 19:59:08 +08:00

12 KiB
Raw Blame History

mpv + ad_joc — 原生轨道的 E-AC-3 JOC 解码器(实验)

这是 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 里的注册位置。

组成

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:

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 的流程:

.\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。

构建(Windows / MSYS2)

需要 msys2 的 UCRT64 环境(本机验证版本:gcc 16.2.0、ffmpeg 9.0.2、meson 1.12.1、ninja 1.13.2)。 LuaJIT 只发布在 ucrt64 / clang64,MINGW64 环境里已经没有这个包了,而 mpv 的脚本需要 LuaJIT 或 Lua 5.1/5.2:

pacman -S --needed mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-meson \
    mingw-w64-ucrt-x86_64-ninja mingw-w64-ucrt-x86_64-pkgconf mingw-w64-ucrt-x86_64-ffmpeg \
    mingw-w64-ucrt-x86_64-luajit

把本目录的 files/ 覆盖到 mpv 源码树,然后:

cd mpv-src
git apply /path/to/patches/mpv-ad-joc.patch
export PATH="${MINGW_PREFIX:-/ucrt64}/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 就对每次播放生效:

# mpv.conf
ad = joc
ad-joc-binaural = yes          # 默认就是 yes(双声道输出)
ad-joc-hrtf = C:/HRTF/binaural.personalized_headphone   # 可省:会自动找
ad-joc-layout = 7.1            # 仅 binaural=no 时使用
ad-joc-mode = mid
ad-joc-rosella-filterbank = 1  # Rosella 输入:1=公开版(默认),2=捕获版
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 5.1 7.1 5.1.2 5.1.4 7.1.2 7.1.4 9.1.4 9.1.6 7.1
--ad-joc-mode near / far / mid mid
--ad-joc-rosella-filterbank 1 / 2(或 public / captured) 1(公开版)
--ad-joc-gain-db -60 … 12 0
--ad-joc-int24 yes / no no

--ad-joc-rosella-filterbank=2 只在 --ad-joc-hrtf 指向 .personalized_headphone 时生效: 1 是 13 taps / 6 slots 的公开滤波器组,2 是 11 taps / 3 slots 的捕获版(与参考渲染器 一致、延迟 448 samples)。SOFA 与 .jochrtf 输入忽略该选项并给一条 warning。

--ad-joc-int24 把输出量化到渲染器的 24-bit 规则(与上游前端的 int24 交付一致): clip 到 [-1,1]、乘 8388607、向零截断、取低 24 位,再按 n / 2^23 读回。默认关闭, 输出就是渲染器的 float32。

本仓库不附带任何 HRTF 文件:Rosella 模型不随仓库或发布包分发,需要自备。

HRTF 输入

--ad-joc-hrtf 指向 Rosella .personalized_headphone 模型;解码器按文件内容确认 (首字符 { 且含 "personalized_hrtf"),不认识的输入会打印提示并退回扬声器布局渲染。

不写 --ad-joc-hrtf 时

按下面的顺序找,找到即用:

  1. <mpv.exe>/HRTF/binaural.personalized_headphone
  2. <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 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.personalized_headphone 放在 mpv.exe 旁边;都没有时 退回扬声器布局,不再报错退出。
  • 每换一个 mpv 版本都要重新对齐 patch(AD 接口和注册点在 mpv 内部,不在稳定 ABI 里)。

许可

ad_joc.c / ad_joc.h / joc_eac3.* 都是 MIT(见仓库根的 LICENSE): joc_eac3.* 改写自上游的 eac3_scan.cpp,ad_joc.* 是新增代码。 它们编译进 mpv,因此最终播放器的分发随 mpv 的许可(LGPL-2.1-or-later,-Dgpl=true 时为 GPL-2.0-or-later),全文见 LICENSE-mpv。

joc_core.h / joc_stream.h / joc_version.h 来自 JustOneCacophonyCXX(MIT),逐字节复制。 joc_core.dll 本身仍是 MIT,不在本仓库分发。