Docs

Getting started

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

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

  • omniphony-renderer — the engine. Its CLI binary is orender: it decodes a stream and renders objects to your speakers.
  • omniphony-studio — the desktop control surface: 3D visualization, live control, and metering.
  • mpv-omniphony — an optional patched build of mpv that renders spatial audio during film playback.

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

Hear it work first

Before anything else, prove to yourself it makes sound. 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

Installing

Prebuilt Linux, Windows, and macOS bundles are published from the project’s release CI — start there if you just want to run Omniphony. The renderer’s format-decoder bridge is packaged separately and loaded at runtime.

To build from source you need a recent stable Rust toolchain. From omniphony-renderer/:

cargo build --release                     # minimal
cargo build --release --features pipewire  # Linux realtime output
cargo build --release --features asio       # Windows ASIO output

For the full build matrix (feature flags, runtime VBAP generation, Windows specifics) see the renderer’s BUILD.md, BUILDING_WINDOWS.md, and QUICKSTART.md in the repository.

The bridge model

orender does not decode formats inside the binary. It loads a bridge plugin at runtime that turns your input into PCM plus object metadata. Bridge lookup order:

  1. --bridge-path <FILE>
  2. render.bridge_path in the config file
  3. the first lib*_bridge.{so,dll,dylib} next to the executable

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. Point --bridge-path at a different bridge to decode other formats.

./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 consumers — the CLI, Studio, and mpv-omniphony — read the same per-user config, so a single setup serves them all:

  • Linux: ~/.config/omniphony/config.yaml
  • Windows: %ProgramData%\omniphony\config.yaml (machine-wide; shared by user-mode and the service)

Save the current effective configuration to a file with --save-config, then edit it in place. Studio writes the same file when you change settings live.

A minimal first run

  1. Start orender on an input with OSC enabled (--osc --osc-port 9000), or launch mpv-omniphony with --ad=orender.
  2. Launch Omniphony Studio. On startup it registers itself with the renderer over OSC and begins drawing the live scene.
  3. Pick a speaker layout in Studio’s Layout menu and watch objects render into it.

From here: