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 shared-library form of the renderer — for real VBAP object rendering, instead of letting FFmpeg downmix them into mush.
Opting in
Spatial rendering is opt-in per playback:
mpv --ad=orender your-film.mkvPlain 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 CLI and Studio (~/.config/omniphony/config.yaml, or %ProgramData%\omniphony\config.yaml on Windows), so a single setup serves all three.
Output routing
- Linux — output goes through PipeWire.
- Windows — builds ship the Steinberg ASIO output driver (
--ao=asio) alongside the usual WASAPI / DirectSound paths.
The decoder bridge (omniphony-bridge) is packaged separately and loaded at runtime via dlopen.
Channel-render modes (non-object content)
Some streams carry spatial objects (object-based immersive audio), which always render through VBAP. Others are plain channel beds — a 5.1 or 7.1 mix with no objects. How that non-object content is rendered is controlled by one of three modes, applied identically by the CLI and the embedded mpv decoder:
| Mode | What happens |
|---|---|
virtual |
(default) Each input channel becomes a virtual object at its theoretical speaker angle and is rendered through VBAP across your whole layout. The flagship behaviour. |
direct |
Each bed channel is routed straight to the matching speaker of your layout; channels with no matching speaker are dropped. |
host |
No spatialization. In mpv the decoder declines and mpv falls back to its own native decoder / downmix. |
Object-based content is never affected by this setting.
Setting the mode
| Where | How |
|---|---|
| Studio | Renderer panel → Channel content selector. Live, and saved to config. |
| Config | render.channel_render_mode: virtual | direct | host |
| mpv (one invocation) | mpv --ad=orender --ad-orender-channel-mode=host|direct|virtual … |
| OSC (live) | /omniphony/control/channel_render_mode with a string argument |
Output speaker layout
The output layout — how many speakers you have and where they sit — is a separate setting from the modes above. Configure it in Studio (stored as render.current_layout) or point render.speaker_layout at a layout YAML; bundled layouts (5.1.4, 7.1.4, 9.1.6, …) live in the layouts/ folder. In virtual mode every input channel is spread across whatever output layout you configure — e.g. a 5.1 bed virtualized over a 7.1.4 rig.
Troubleshooting
- A non-Atmos bed plays, but you want mpv’s normal downmix → set the mode to
host. - A non-object track won’t start → make sure a speaker layout is configured; without a resolvable output layout the renderer hands the track back to the native decoder rather than stalling.