# 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](https://github.com/TheM14/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](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](LICENSE-mpv). The `joc_core` renderer is not distributed here; see [THIRD_PARTY_NOTICES.md](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](https://github.com/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](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 ```text \\scripts\\joc_mpv.dll the plugin \\joc_core.dll the renderer (same binary as JustOneCacophonyCXX) \\HRTF\\binaural.sofa default binaural data \\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 `\\joc_core.dll`, then `\\..\\joc_core.dll`, then `PATH`. Add to `mpv.conf`: ```ini script-opts=joc-output=binaural,joc-hrtf-source=sofa ``` Or load it explicitly: ```powershell 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-hrtf` | path | empty | empty: default name under `\\HRTF\\` or `\\..\\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 = `\\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: `\\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 ```text 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:/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 ... select`s 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/`](fork/README.md); 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): ```powershell 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`: ```powershell 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.sofa` in `\\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`.