Docs

Using Studio

Your window into the engine — watch every object move in 3D, then grab the knobs and mess with the mix live.

Studio is your window into the engine: a live 3D scene of everything the renderer is doing, plus the knobs to poke it while it runs. It doesn’t make a sound itself — it talks to a running engine (orender, or the one inside mpv-omniphony) to watch and drive it.

Since 0.7.0 there is one Studio, a native app (Rust, egui/wgpu): no web view, it draws at the display’s rate under a full object load and idles at zero CPU. It’s packaged as .deb and AppImage on Linux, a setup or MSI on Windows and a .dmg on macOS — see Download.

First launch

If no engine is running, Studio says so instead of showing you an empty room: a banner offers Start the audio engine (Studio finds the orender installed next to it, then on your PATH), or a link to get mpv-omniphony. With Auto-start local renderer on (the default), Studio starts a standby renderer by itself when nothing answers on this machine.

Other banners show up when something needs you: no decoder bridge loaded, a bridge that failed to load, a renderer that was rebuilt under its feet (one click restarts it), a config.yaml it can’t read or that comes from a newer Omniphony (it refuses to save over it), or an engine older or newer than this Studio.

How Studio connects

Studio and the engine speak OSC:

  • On startup Studio sends /omniphony/register <listen_port> to the engine’s control port (127.0.0.1:9000 by default; the engine’s --osc-rx-port). Its own listen port is picked by the OS.
  • The engine answers with a state bundle — layout, speakers, live renderer state — so the scene is right straight away, then streams changes.
  • When the engine is on the same machine, Studio talks to it over loopback TCP on that same port number, so big payloads (an HRTF set, a gain table) travel in a few packets. A remote engine is reached over UDP, kept alive with /omniphony/heartbeat every 5 s.

Essentials, or the whole board

Studio opens on an Essentials view: the connection, the output device, your speakers or headphones, the master gain, and a Listening section with the output mode, the HRTF and where your channels are placed. Flip Advanced settings at the top of the left panel to get everything else. That choice — like the camera, the open sections, the panel widths and the language — is remembered the moment you change it.

The 3D scene

Each audio object is drawn inside a normalized [-1, 1] room, warped to your room’s proportions, with your speaker layout around it. Objects can be circles, transparent spheres or diffuse spheres, with labels, trails and an energy field; speakers can show a heatmap of what they’re playing.

  • Orbit with a left-drag, pan with a right-drag, zoom with the wheel or a middle-drag. Click to select; Esc clears.
  • Move a speaker by arming 3D Edit in the speaker editor: a gizmo appears (azimuth ring and elevation arc in polar mode, per-axis handles in cartesian mode). In polar mode, Ctrl or Shift + wheel changes its distance.
  • Move a fixed channel the same way once its family’s placement is Manual (see below).
  • Real, stream-driven objects are display-only: their positions belong to whatever is playing them. You watch them fly, you don’t push them around.
  • Follow the sound (on by default) holds the scene back until each block is actually heard, so what you see is what’s coming out of the speakers, not what was just rendered.
  • Perceived position (Display panel) draws where the rendered sound should be localised — computed from the speaker gains — next to where the object is supposed to be. Handy for catching a backend that pulls objects off target.

On headphones the scene follows the path that actually renders: the listening room the reflections are computed in, or a measured room in metres, with a badge in the corner naming the path and the HRTF set.

The panels float over the scene: folding or resizing one never resizes the 3D view. Drag a panel’s inner edge to resize it, double-click it to reset.

Panels at a glance

  • Left panel — what goes into the engine: profiles and language up top, then (Advanced) OSC Configuration, Audio Input, Fixed-channel sources, Room Geometry, DRC, and always Objects (object list with meters, mute and solo, and the metering switch).
  • Right panel — what comes out: Audio Output, (Advanced) Latency and Diagnostics, Master, Renderer (or Listening in Essentials), the Headphones ear rows on headphones, and Speakers with the layout buttons. The speaker editor pins itself at the foot of the panel when a speaker is selected.
  • Bottom — the scene-effects bar (grid, objects, labels, trails, energy field, speaker heatmap, mpv overlay, and the Display panel), with the Save / Reload footer under it.

What’s kept, and when

Display stuff is kept the moment you touch it. Anything that changes the sound — backend, layout, gains, delays, headphones, placement, input, output, latency — applies live but only reaches config.yaml when you press Save. The footer says Modified (unsaved) until you do, and Studio asks before throwing unsaved edits away on quit, reload or a profile switch.

Profiles (top of the left panel) are named configs on the renderer: create, rename, delete and switch between them.

Choosing a layout

The Speakers section has the layout buttons: Presets opens the bundled layouts folder (5.1.2, 7.1.4, 9.1.6, …), Import layout loads a .yaml from anywhere, and in Advanced view Export layout and + Add (a speaker at the selected one’s position). The engine rebuilds its render topology for the new layout; if the layout can’t build, Studio shows why instead of freezing the scene. See Speaker layout for the file format — and the output-mode cards below swap the speakers for headphones.

The main parameters

Output mode

Three cards under Renderer (or Listening): Speakers, Headphones (direct binaural), and Headphones (virtual room) (your speaker layout rendered as virtual speakers, then folded to binaural). The cards stay visible even with the section folded, and the Renderer section shows only the tabs the chosen path uses. Inside mpv-omniphony the mode applies at the next player start.

Master & gain

  • Master — overall output gain, 0–2× (double-click for unity), read out in dB.
  • Auto-gain (anti-clip) — reins the master in to hold peaks under a Ceiling (-12…0 dB, default -1).
  • DRC — the modes the decoder bridge offers, plus a weight (0–100 %).
  • Loudness — correction toward a target level, with source, target and correction read-outs.
  • Dialogue level (±12 dB) — when the stream carries separate dialogue.
  • Per-speaker gain and mute / solo in the lists, and a per-channel trim (-24…+12 dB) in the Channel Editor.

Render backend & spatialization

The Renderer panel picks the gain model that turns object positions into speaker gains:

  • Backend — VBAP (default), Volumetric (VBAP’s direction plus the object’s depth in the room), Barycenter, the experimental Distance, Hybrid (two backends crossfaded by distance along a curve you draw), and Script (your own law in Lua). The list comes from the engine, so a backend you compile in shows up here too.
  • Backend parameters are generated from the backend’s own schema — Studio renders whatever sliders, switches and selects it declares. For Script, the file row gets an Edit button that opens a Lua editor; saving sends the script to the engine and rebuilds.
  • Distance model (none / linear / quadratic / inverse-square) and a distance-diffuse stage shape how distance affects level and spread. Since 0.7.0, inverse-square is 1/d in amplitude beyond the speakers and unity inside them.
  • Decode on its own thread — for small boxes; off by default.
  • With metering on, a frame-budget bar in the header shows where the render time goes.

Which controls appear is driven by the backend’s declared capabilities — Studio never hard-codes “if VBAP.” A backend that doesn’t do spread shows no spread controls. See Custom render backends.

Fixed-channel sources

For channel beds — the 5.1 / 7.1.4 part of a stream, or plain PCM:

  • Placement — where each format’s channels sit, one tab per source family (generic, PCM, Dolby, DTS, Auro-3D, IAMF): Sphere (the format’s own angles), Room (the corners of the room model), Manual (your own positions), or inherit from Generic. On headphones, a family you didn’t set is placed on the Sphere. Details in Speaker layout.
  • Rear channels (4.x/5.x) — surrounds at the Side (≈ ±90°) or Back (≈ ±135°) for beds with no back channels.
  • Generate height objects — synthesize a top layer from a flat bed: Off, Direct copy, Ambience (PAD) or Diffuse field (DirAC).
  • Phantom extraction — pull phantom center / side images out of the bed (Broadband or Spectral).
  • In the Channel Editor, each channel can be routed Virtual (rendered as an object) or Direct (straight to a speaker).

Speakers & room

  • Speaker Editor — name, spatialize switch, position (cartesian or polar, normalized and in real metres), gain, delay (ms or samples), the Calc delays / Delay → Dist tools, and the speaker’s frequency band (Freq. min / max) for the crossover. A Test tab plays a test signal on it. With a measured BRIR set, the speakers are the file’s and read-only.
  • Room Geometry — the room in metres (width, front, rear, height, lower) and a Y center blend, so the rendered scene matches an asymmetric room.

Headphones & head tracking

The binaural side — HRTF set and SOFA browser, measured rooms (BRIR), distance, reflections, reverb, head tracking with axis calibration — has a page of its own: Binaural for headphones.

Input, output & latency

  • Audio Output — Device or File / Stream, the output device, and in Advanced view channel mapping (By index / By name) and sample rate. The format line shows what the device actually opened (on Windows, ASIO or the WASAPI fallback).
  • Audio Input — the decoder bridges list: add, remove and reorder bridges, see which families each one loaded, and which one is decoding right now. Apply restarts the renderer with the list; Save keeps it. Below it, the input mode (pipe or PipeWire sink).
  • Latency — one number, the target latency: the time from audio reaching the renderer to leaving your speakers. If a stream needs more, Studio says Holding X ms instead of Y ms. Advanced view adds the source clock, loop bandwidth and realign threshold, and a live trace.
  • Metering — a switch and a publish rate (10 / 20 / 50 / 100 / 200 Hz) at the top of Objects.

Actions

  • Save / Reload — write the render settings to config.yaml, or reload them from it.
  • Renderer lifecycle (OSC Configuration) — Connect, Launch / Stop orender, install / restart / uninstall it as a background service, Restart PipeWire and WirePlumber (Linux), and Activate in mpv config.
  • Logs — the log line at the top expands into a viewer: copy, clear, filter, and set the engine’s log level.
  • Updates — Studio can check GitHub for a newer release on startup.
  • About — version, license, the renderer’s ABI and bridge_api series, and which config file is in use.

Studio speaks English, French, German, Spanish, Italian, Japanese, Brazilian Portuguese and Simplified Chinese (pick it at the top of the left panel; Auto follows your system). Japanese and Chinese labels need a CJK font installed on the system.

Where to go next

For the complete set of addresses Studio (or any client) can send and receive, see the OSC protocol guide — and Custom render backends if you want to write your own panner.