Docs

Getting started

From zero to sound flying around your room. Install it or build it, hear the demo — then point it at your own stuff.

Three pieces, one config file. Here’s how to get them talking:

  • orender — the engine. It decodes a stream and renders objects to your speakers or headphones. It also comes as a library, liborender, which is what the player loads.
  • Omniphony Studio — the desktop control surface: 3D visualization, live control and metering.
  • mpv-omniphony — the mpv media player with the engine built in, for spatial audio during film playback.

Run the engine on its own, drive it with Studio, or throw a whole film at mpv-omniphony — they all read the same config file.

Installing

The quick way: each Omniphony release carries a combined installer that lays down the player, the engine and Studio in one go, each where the others look for it — omniphony-<version>-linux-x86_64.tar.gz (an install.sh, no root, with an uninstaller) and omniphony-<version>-windows-x86_64-setup.exe (per user, no admin rights). Grab them from Download.

Step by step, from an empty machine to a film playing — what to download, where each file goes, how to check each step, and the usual failures: Linux · Windows · macOS.

On Arch, it’s all on the AUR: paru -S mpv-omniphony omniphony-studio.

Studio alone also ships as .deb / AppImage, Windows setup / MSI and a macOS .dmg, each carrying orender and the engine library. Every time it starts, Studio copies that library to where the player looks for it — so updating Studio updates the engine mpv uses.

Hear it work first

Building from source? Prove to yourself it makes sound before anything else. The bundled demo needs no media file and no proprietary decoder — just one command:

cd omniphony-renderer
./scripts/demo.sh            # builds the engine + reference bridge, then plays the demo

This binaurally renders a source sweeping around you straight to your headphones. Other modes:

./scripts/demo.sh speakers   # 7.1.4 speaker render instead of binaural
./scripts/demo.sh file       # no audio device? pipe raw float to ffplay

Building from source

You need Rust 1.89 or newer. From omniphony-renderer/:

cargo build --release

That’s it: the default build has every output for its platform — PipeWire on Linux, ASIO on Windows (falling back to WASAPI shared mode when no ASIO driver is installed), CoreAudio on macOS — plus the file / pipe output and the SOFA reader. Platform specifics live in QUICKSTART.md and BUILDING_WINDOWS.md in the repository.

The bridge model

orender does not decode formats inside the binary. It loads bridge plugins at runtime that turn your input into PCM plus object metadata — typically one per codec family — and routes each stream to the bridge whose probe recognises it. Which bridges it loads:

  1. every --bridge-path <FILE> you pass (repeatable);
  2. otherwise the list in render.bridge_paths in the config file;
  3. otherwise every *_bridge.{so,dll,dylib} in the first of these folders that holds one: next to the executable, $ORENDER_BRIDGE_DIR, the per-user engine folder (~/.local/share/omniphony/lib, %LOCALAPPDATA%\omniphony\lib, ~/Library/Application Support/omniphony/lib), then /usr/lib/orender.

Ask the engine what it found:

orender check-bridges

A bridge loads only in an engine built against the same bridge_api minor version, so take the bridge release the engine’s release notes pair with it — the compatibility table and the install pages above say which.

The repo ships a reference bridge that reads a plain multichannel WAV — it’s what the demo uses and the smallest example for writing your own:

./target/release/orender input.wav \
  --bridge-path target/release/libreference_bridge.so \
  --enable-vbap \
  --speaker-layout ../layouts/7.1.4.yaml

The shared config file

All three — the CLI, Studio and mpv-omniphony — read the same config file, so a single setup serves them all:

  • Linux / macOS: ~/.config/omniphony/config.yaml ($XDG_CONFIG_HOME or $OMNIPHONY_CONFIG_DIR move it)
  • Windows: %ProgramData%\omniphony\config.yaml (machine-wide; shared by user mode and the service)

Save the current effective configuration with --save-config, then edit it in place. Studio changes everything live, but only writes the file when you press Save — and it never overwrites a file it couldn’t read: unknown keys survive a save untouched.

A minimal first run

  1. Start the engine: orender on an input, or a film in mpv-omniphony (--ad=orender). The player turns its OSC control on by itself when no config file exists yet; otherwise set osc: true in the config or pass --ad-orender-osc.
  2. Launch Omniphony Studio. It registers with the engine and starts drawing the live scene. If nothing answers on this machine, it offers to start an engine — and with Auto-start local renderer on, it starts one after a few seconds on its own, so start the player first.
  3. Pick your speakers in Studio’s Speakers section (Presets or Import layout), or switch the output to Headphones, and watch objects render.

From here: