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
2026-10-18 21:31:38 +08:00
2026-10-18 21:31:38 +08:00
2026-10-18 21:31:38 +08:00
2026-10-18 21:31:38 +08:00
2026-10-18 21:31:38 +08:00

mpv-joc — E-AC-3 JOC (Dolby Atmos) playback for mpv

An mpv C plugin (cplugins feature). It takes the object audio out of an E-AC-3 JOC stream, rebuilds it with the JustOneCacophony renderer, and hands the result to mpv as an ordinary audio track. The renderer, the engine and the settings are the same ones the upstream frontends the upstream project's command-line frontend uses, so the samples delivered to the player are bit-identical.

  • Output: binaural (HRTF) or a 2.0 – 9.1.6 speaker layout;
  • Output device: mpv's own audio output, i.e. WASAPI on Windows (optionally forced, optionally exclusive);
  • Configuration: mpv's own configuration file, with one joc-* option namespace;
  • Input: bare .eac3 / .ec3, or the E-AC-3 JOC track of an MP4 / Matroska file (a video track keeps playing normally);
  • Seeking: mpv's seek works; the renderer re-enters the bitstream at the target.

License

This repository (plugin, patch, scripts, documentation) is MIT, see LICENSE.

The code under fork/ is compiled into mpv, so distributing the resulting player is also subject to mpv's own license: LGPL-2.1-or-later (GPL-2.0-or-later when built with -Dgpl=true). mpv's license text ships with this repository as LICENSE-mpv. The joc_core renderer is not distributed here; see THIRD_PARTY_NOTICES.md.

Relationship to the upstream project

This repository contains the mpv-side integration only: the cplugin (src/) and the ad_joc patch (fork/). The object-audio renderer, E-AC-3/EMDF parsing, SOFA and Rosella support come from TheM14/JustOneCacophony; the behaviour reference is the upstream project's joc_cli (the comparison basis). joc_core.dll is not distributed here — it is built from the upstream project, and none of its code is copied or modified in this repository.

Repository layout

One renderer (joc_core.dll), two integration shapes:

Shape Where mpv requirement
cplugin: drop-in for stock mpv src/ config/ tools/ built with cplugins
ad_joc patch: compile the decoder into mpv fork/ build mpv from source (see fork/README.md)

Requirements

  • mpv with cplugins support (official Windows builds have it; check List of enabled features in mpv --msg-level=all=v).
  • An ffmpeg executable (found on PATH by default, joc-ffmpeg overrides).
  • HRTF data for binaural output: a SOFA measurement set or a Rosella .personalized_headphone model. Not bundled; speaker layouts do not need it.

Install

<mpv>\\scripts\\joc_mpv.dll                     the plugin
<mpv>\\joc_core.dll                      the renderer (same binary as JustOneCacophonyCXX)
<mpv>\\HRTF\\binaural.personalized_headphone               default binaural data
<mpv>\\HRTF\\binaural.personalized_headphone   (Rosella model, either one)

joc_core.dll must not go into scripts\\: mpv offers every file in that directory to the script loader. The plugin looks for the renderer at joc-core, then <plugin dir>\\joc_core.dll, then <plugin dir>\\..\\joc_core.dll, then PATH.

Add to mpv.conf:

script-opts=joc-output=binaural

Or load it explicitly:

mpv --script="C:\\path\\to\\joc_mpv.dll" --script-opts=joc-output=speaker,joc-layout=7.1 movie.mkv

Options

All keys live in mpv's --script-opts, prefixed joc-; unknown keys are ignored and reported in joc_decoder.log.

Key Values Default Meaning
joc-enabled yes / no yes disable the plugin entirely
joc-output binaural / speaker binaural output form
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 speaker layout; used only with speaker
joc-rosella-filterbank 1 / 2 (or public / captured) 1 Rosella filterbank: 1 = the public 13-tap / 6-slot bank, 2 = the captured 11-tap / 3-slot bank that matches the reference renderer
joc-hrtf path empty empty: default name under <plugin>\\HRTF\\ or <plugin>\\..\\HRTF\\
joc-mode near / mid / far mid binaural mode
joc-gain-db float (dB) 0 render gain (binaural can exceed full scale)
joc-tail seconds 5.0 binaural room tail cap (never delivered as playback time)
joc-int24 yes / no no deliver 24-bit fixed point instead of float32
joc-object-delay samples 1473 OAMD object delay, matching the existing implementation
joc-threads integer 0 kernel threads, 0 = automatic
joc-ffmpeg path ffmpeg ffmpeg used for the core PCM
joc-core path empty explicit joc_core.dll
joc-wasapi auto / yes / no auto yes sets ao=wasapi
joc-exclusive yes / no no sets audio-exclusive=yes
joc-chunk seconds 2.0 audio bytes written per HTTP chunk
joc-mute-until-ready yes / no yes silence the file's own track until the rendered one is selected
joc-attach yes / no yes no: serve the stream without adding the track (capture/verification)
joc-verbose yes / no no log every HTTP request and reposition
joc-log path empty log file; empty: <mpv config dir>\\joc_decoder.log

Speaker layouts and channel order

joc-layout accepts the eleven layouts below, and the PCM the plugin hands to mpv follows the order in the table:

Layout Channel order
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 is the quad layout this project adds (the traditional FL FR BL BR, here L R Lrs Rrs); it is not part of the Dolby layout set. Every other layout and channel order follows the Dolby specifications.

The plugin serves the renderer's output to mpv as an ordinary WAV track over loopback HTTP. That WAV uses WAVE_FORMAT_EXTENSIBLE with dwChannelMask = 0: it declares no Windows speaker positions, and the PCM order is exactly the table above, never rearranged into mask-bit order. The plugin changes none of mpv's channel-layout settings, and it does not affect mpv's native layout support for any other audio format.

With no mask, FFmpeg gives the stream a default layout for its channel count (4 channels become fl-fr-fc-bc, 8 become fl-fr-fc-lfe-bl-br-sl-sr, wider counts stay unspecified), and mpv reads the channels from that. In other words, the loopback WAV only guarantees that the PCM matches the table above channel for channel; the speaker positions follow mpv's own default layout.

To have mpv play the real layout, use the ad_joc decoder: it sets the channel map per frame (in the order of the table above), so mpv's filter chain, remixing and the WASAPI mask all use the right positions. An ao=pcm capture is byte-identical to joc_cli's WAV.

Mapping the channels to a device (WASAPI shared/exclusive, ASIO, HDMI) is up to the user; this project guarantees the content and numbering of each PCM channel, not that a downstream player or device recognises Dolby speaker positions on its own. A WASAPI endpoint takes at most eight channels, so 9.1.4 / 9.1.6 normally need ASIO or an external renderer.

joc-layout accepts only the eleven names in the table; anything else is reported and the default 7.1 is kept.

How it works

mpv — video and subtitles as usual
 │
 └─ file-loaded ─► probe (bare stream walked directly; container: ask ffmpeg which
                    track is E-AC-3 and whether it carries JOC)
                     │
                     ▼
             joc_core.dll (joc_stream.h)
                     ▲ E-AC-3 syncframes + core PCM from ffmpeg
                     │
         ┌───────────┴────────────┐
         │  rendered as WAV (float32 / int24, dwChannelMask = 0)
         │  served by an in-process loopback HTTP endpoint with Range support
         └───────────┬────────────┘
                     ▼
        mpv: audio-add http://127.0.0.1:<port>/joc.wav select

mpv reads the track as a seekable WAV file, so its demuxer, cache, A/V sync, WASAPI output and seeking all work unmodified.

Startup: at start-file the plugin probes and creates the renderer while mpv is still opening the file, and silences the file's own track; at file-loaded it audio-add ... selects the rendered track and restores the previous mute state. Inputs the probe rejects are unmuted immediately (a container whose E-AC-3 track turns out not to be JOC spends the ~100 ms ffmpeg probe muted; set joc-mute-until-ready=no to disable the behaviour). Measured on a 30 s 7.1.4 clip: about 0.6 s cold, about 0.37 s once the compiled HRTF is cached. That window is silence rather than the plain bed, and mpv pauses the audio clock across the switch, so no content is skipped. The plugin only repositions the renderer when the requested byte offset differs from the current position, using the component's seek policy (target frame minus 64 pre-roll frames, then the output before the target is dropped).

A seek differs from a from-start render only by a very low noise floor (below −65 dBFS in measurement); the position itself does not drift.

Relationship to the fork approach

The established solution in this space takes the other path: mpv-omniphony is a fork of mpv that adds a --ad=orender module, handing demuxed access units to liborender; the codec decoding itself lives in dynamically loaded bridge DLLs (harletty_dolby_bridge.dll and friends, E-AC-3 JOC included). That gives a native track: no extra track, no startup switch, correct codec information.

This plugin deliberately stays on stock mpv (cplugins) and pays for it with a 0.3–0.6 s preparation window at startup and an external PCM track (shown as pcm_f32le). When the native behaviour is required, the right move is an ad_joc module in mpv, built the way mpv-omniphony does it: mpv's AD layer receives AVPackets, so FFmpeg does not have to change and the renderer stays joc_core.dll. A working prototype of that route — patch against mpv master (2026-10-17), new sources and build instructions — lives in fork/; its --ad=joc output was measured bit-identical to joc_cli for both binaural and 7.1. The cost is maintaining your own mpv build (MSYS2/MinGW on Windows).

Verification

tools/verify_parity.ps1 renders a reference WAV with joc_cli, fetches what the plugin actually delivers, and compares the bytes. On this machine (mpv v0.41.0, FFmpeg 8.0, a 30 s 7.1.4 JOC clip):

Case Result
binaural float32 (SOFA) bit-identical
binaural int24 (Rosella) bit-identical
speaker 7.1 float32 bit-identical

The reference is longer only by the binaural room tail: the component and this plugin cut the delivered stream at the file's duration, joc_cli's --binaural-output does not.

Build

Needs a JustOneCacophonyCXX checkout (for its joc_core target):

pwsh -File tools/build.ps1 -JocCoreSource C:\\path\\to\\JustOneCacophonyCXX

The plugin lands in build\\Release\\joc_mpv.dll with joc_core.dll beside it. Plugin only, against an existing joc_core.dll:

cmake -S . -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Release

/fp:precise and a static CRT are fixed: the floating-point behaviour is part of the byte-exact acceptance.

Troubleshooting

joc_decoder.log is written to mpv's configuration directory (next to mpv.conf), together with joc_ffmpeg_*.log; it cannot live in scripts\\ because mpv would try to load it as a script. --msg-level=all=info shows the JOC: ... status line.

  • No JOC message, just plain E-AC-3 — the file has no JOC metadata, or the container's audio track is not E-AC-3; mpv keeps playing the original track.
  • "cannot find the HRTF file" — put binaural.personalized_headphone in <mpv>\\HRTF\\ or point joc-hrtf at it.
  • Which track is in use? — joc-verbose=yes and read the probe: / start: lines.

License

MIT, see LICENSE. The renderer comes from JustOneCacophonyCXX and the decode engine from the upstream project's frontend code; see THIRD_PARTY_NOTICES.md.

S
Description
基于JustOneCacophony C++内核支持解码E-AC-3 JOC的mpv补丁
Readme MIT
259 KiB
0 Stars 1 Watchers 0 Forks
Languages
C++ 67.2%
C 25.2%
PowerShell 3.8%
Python 3%
CMake 0.5%
Other 0.3%