The app's MPVLib loads libplayer.so before libmpv, and mpv-android builds that bridge with ndk-build over app/src/main/jni, installing it and the prebuilt ffmpeg/mpv objects into app/src/main/libs/<abi>. The workflow only built the mpv target and then ran Gradle, so the APK shipped without libplayer.so and every playback died with UnsatisfiedLinkError. Run ndk-build the way buildscripts/scripts/mpv-android.sh does, and write ndk.properties, which the Gradle build needs to find the NDK for symbol stripping (the previous APK carried 134 MB of unstripped libraries).
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 featuresinmpv --msg-level=all=v). - An
ffmpegexecutable (found onPATHby default,joc-ffmpegoverrides). - HRTF data for binaural output: a SOFA measurement set or a Rosella
.personalized_headphonemodel. 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.sofa 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,joc-hrtf-source=sofa
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-hrtf-source |
sofa / rosella | sofa | binaural HRTF input |
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; only read with joc-hrtf-source=rosella |
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-hrtf-cache |
auto / memory / disk / none | auto | compiled-HRTF cache; auto = <mpv config dir>\\joc-hrtf-cache |
joc-hrtf-cache-dir |
path | empty | explicit cache directory |
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.sofain<mpv>\\HRTF\\or pointjoc-hrtfat it. - Which track is in use? —
joc-verbose=yesand read theprobe:/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.