Docs

Playback via mpv-omniphony

Point a real film at your speaker rig — mpv hands the audio to Omniphony instead of letting FFmpeg flatten it.

Want your films to actually use that speaker rig? mpv-omniphony is plain mpv with one extra trick: ad_orender, an opt-in decoder that hands raw access units to liborender — the library form of the engine — for real object rendering, instead of letting FFmpeg downmix them into mush. It’s built from our mpv fork (on mpv 0.41); mpv-omniphony builds and packages it, and attaches the fork’s delta as a patch set for anyone who’d rather patch upstream mpv.

Getting it

The step-by-step install pages cover it end to end, and the combined installer on Download puts it in place for you. In short:

  • Linux — an AppImage that runs on most distributions, or a zip built for Ubuntu 24.04 only. On Arch: paru -S mpv-omniphony.
  • Windows — a zip with mpv.exe, the Steinberg ASIO output built in; no Visual C++ redistributable needed.
  • macOS (Apple silicon) — mpv-omniphony.app, ad-hoc signed but not notarized: clear the quarantine once with xattr -dr com.apple.quarantine /path/to/mpv-omniphony.app.

The player doesn’t decode any format by itself: it needs the decoder bridges the engine loads, installed apart (see the bridge model). Without one, mpv plays the track through its own decoders, as usual.

Opting in

Spatial rendering is opt-in per playback:

mpv --ad=orender your-film.mkv

Plain streams keep playing through mpv’s standard decoders; only when you pass --ad=orender does the spatial path engage. mpv-omniphony reads the same shared config as the standalone orender and Studio (~/.config/omniphony/config.yaml on Linux and macOS, %ProgramData%\omniphony\config.yaml on Windows), so a single setup serves all three. Without a config file it renders 7.1.4 speakers and turns its OSC control on, so Studio finds it.

Which engine it loads

mpv loads liborender at runtime, with an ABI check, from the first of:

  1. --ad-orender-library=<path> or $ORENDER_LIBRARY;
  2. the engine Omniphony Studio deploys in your per-user folder (~/.local/share/omniphony/lib, %LOCALAPPDATA%\omniphony\lib, ~/Library/Application Support/omniphony/lib);
  3. the copy bundled next to mpv;
  4. the system library path.

So updating Studio updates the engine mpv uses — no new mpv build needed. An older player keeps loading a newer engine: the library’s ABI only grows within a major version.

Useful options

Option What it does
--ad-orender-bridge-path=<path>[:<path>…] the decoder bridges to load (; between paths on Windows), instead of render.bridge_paths and discovery
--ad-orender-config=<path> another config file
--ad-orender-osc force OSC on, for Studio (otherwise render.osc decides)
--ad-orender-osc-rx-port=<n> the port Studio registers on (default 9000)
--ad-orender-channel-mode=host leave channel-based tracks to mpv’s own decoder (auto follows the config, spatial renders them)
--ad-orender-host-decoder=spdif in host mode, pass the bitstream through to an AV receiver instead of decoding it (lavc, the default)

Output routing

  • Linux — mpv’s usual outputs, PipeWire included.
  • Windows — the Steinberg ASIO output (--ao=asio) alongside WASAPI.
  • macOS — CoreAudio.

For tight head tracking on headphones, set audio-buffer=0.05 in mpv.conf. The output mode (speakers or headphones) is applied when the player starts: switch it in Studio, then restart playback.

Channel beds (non-object content)

Some streams carry spatial objects, which always go through the render backend. Others are plain channel beds — a 5.1 or 7.1.4 mix with no objects. Since 0.6.0, how a bed lands on your rig is decided per source family and per channel, not by one global mode:

  • each family (generic, PCM, Dolby, DTS, Auro-3D, IAMF) places its channels on the Sphere (the format’s own angles), in the Room (the corners of the room model) or where you put them (Manual);
  • each channel entry is either virtualised (spatialize: true, rendered as a fixed object across your whole layout) or routed directly to the speaker with the same label (spatialize: false — the LFE, by default).

Set it in Studio’s Fixed-channel sources panel (and the Channel Editor), or in config under render.placement — see Speaker layout. The old global render.channel_render_mode (virtual / direct / host) is gone; --ad-orender-channel-mode=host remains for handing a bed back to mpv.

Output speaker layout

The output layout — how many speakers you have and where they sit — is configured in Studio (stored as render.current_layout), or point render.speaker_layout at a layout YAML; bundled layouts (5.1.2, 7.1.2, 7.1.4, 9.1.6) live in the layouts/ folder.

Through mpv, a layout can have at most 64 speakers — the width of mpv’s channel maps. The engine itself has no limit (tested to 128): for a wider rig, play through the standalone orender, which writes to its own audio output.

Also in there

  • IAMF in Matroska (A_IAMF tracks) plays through the engine, with a bridge that handles IAMF. The track definition is our own draft, not a standard: read IAMF / Eclipsa Audio before you rely on it.
  • Studio follows the sound: mpv tells the engine which point of the stream is being heard, so Studio’s scene shows what you’re hearing, not what was just rendered.
  • A bad packet doesn’t freeze playback: it’s dropped, and playback goes on.
  • --ao=pcm --ao-pcm-timed feeds a pipe at the player’s pace, for sending a stream to a standalone orender.

Troubleshooting

  • No spatial rendering at all → check mpv’s log for the liborender it loaded, and run orender check-bridges: no bridge for the format means mpv decodes natively.
  • Studio doesn’t see the player → a config file exists without osc: true: add it, or pass --ad-orender-osc. Start the player before Studio, or Studio’s auto-started renderer takes the port first (the player’s engine asks it to step aside, but only one player can hold it).
  • A bed plays, but you want mpv’s normal downmix → --ad-orender-channel-mode=host.
  • A layout wider than 64 speakers → mpv logs it and decodes natively; use orender.