Using Studio

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 omniphony-renderer over OSC to watch and drive it.

How Studio connects

Studio listens for OSC messages over UDP and announces itself to the engine:

• On startup it sends /omniphony/register [listen_port] to the renderer’s receive port (<host>:9000 by default) to register as a dynamic client.
• While running, it sends /omniphony/heartbeat [listen_port] periodically so the engine keeps it subscribed. The engine replies /omniphony/heartbeat/ack, or /omniphony/heartbeat/unknown if it doesn’t recognise the client (prompting a re-registration).
• Immediately after registration the engine sends a state bundle — the current layout, speakers, and live renderer state — so Studio paints an accurate scene without waiting for the next change.

The renderer’s receive port is the --osc-rx-port it was started with (default 9000).

The 3D scene

Studio draws each audio source as a sphere inside a normalized [-1, 1] volume, with your speaker layout rendered around it. It accepts several OSC position formats, including:

• legacy cartesian positions — /source/position id x y z
• positions with the identifier in the address — /source/<id>/position x y z
• spherical coordinates — /source/<id>/aed azimuth elevation distance
• explicit source removal

Panels at a glance

The controls sit in three regions, and every one of them applies live over OSC — nothing touches disk until you hit Save:

• Left panel — everything feeding into the engine: the OSC connection, audio input, the 2D-source (bed) options, room geometry, loudness / DRC, objects, and the display / scene options.
• Right panel — everything on the way out: audio output, the big Renderer panel (render backend, spatialization, and the binaural / headphone stage), and the speaker layout with its per-speaker editor.
• Bottom bar — a Save / Reload pair plus a row of scene-effect toggles.

Both side panels collapse and drag-resize (double-click the divider to reset).

Choosing a layout

The Layout menu loads a speaker configuration from the suite’s layouts/*.yaml files (5.1, 7.1.4, 9.1.6, and more) and renders it in the scene. The engine recomputes its render topology for the chosen layout; if a layout fails to build, Studio surfaces the error in place rather than leaving the scene stuck. See Speaker layout for the layout format and how to write your own — and the Headphones panel swaps the whole speaker chain for binaural headphone rendering.

The main parameters

Master & gain

• Master — overall output gain, 0–2× (unity at 1).
• Auto-gain (anti-clip) — a safety limiter that reins the master in to hold peaks under a Ceiling (-12…0 dBFS, default -1).
• Loudness — dialog-norm / loudness correction toward a target level, with a live read-out of source vs. corrected.
• DRC — dynamic-range-compression mode plus a weight (0–100%) to dial how hard it’s applied.
• Per-speaker and per-object gain and mute, and a per-channel trim (-24…+12 dB) in the bed Channel Editor.

Render backend & spatialization

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

• Backend — VBAP (default), Barycenter, Hybrid, and the experimental Distance. The list is filled live from whatever the engine registered, so contributor backends (including the example and Lua script ones) show up here too.
• Backend parameters are generated from the backend’s own schema — e.g. Sharpness, Localize, Spread min / max, Spread from distance, and an object-size policy. Whatever a backend declares, Studio renders the matching slider or select.
• Distance model (none / linear / quadratic / inverse-square) and a distance-diffuse stage shape how distance affects level and spread.
• Restore backend reverts a live backend override to the configured one.

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

2D sources (channel beds)

For plain channel content with no objects, the 2D sources panel decides what happens to it:

• Spatialize 2D sources — on renders the bed through VBAP (Spatial); off hands it back to the host untouched (Host).
• Rear channels — for 4.x / 5.x beds with no dedicated back channels, place the surrounds at the Side (≈ ±90°) or Back (≈ ±135°) corners.
• Height objects from 2D — synthesize a top layer from a flat bed: Off, Direct copy, or Ambience (PAD), each with its own tuning.
• Phantom extraction — pull phantom center / side images out of the bed, with extraction strength and relocalize options.

Speakers & room

• Speaker Editor — per-speaker name, position (Cartesian or polar, plus real metres), gain, delay, spatialize flag, and crossover band (Freq. min / max). Layout selection and the file format live in Speaker layout.
• Room geometry — non-cubic room ratios (width / front / rear / height / lower) plus a Y-center blend, so the rendered scene matches an asymmetric room.

Headphones & head tracking

The Renderer panel also holds the binaural output stage — output-mode toggle, HRTF source, room reflections, reverb, and the head-tracking sub-panel. That’s a page of its own: Binaural for headphones.

Input & output

• Audio output — backend (Device or File / Stream), the output device, channel mapping (By index / By name), sample rate, and the destination / named-pipe for file mode.
• Audio input — input mode, the decoder bridge path, live-input backend (PipeWire / ASIO), clock mode (DAC / PipeWire / Upstream), channel count, sample rate, and format.
• Metering — a toggle plus a publish rate (10 / 20 / 50 / 100 / 200 Hz).

Scene & display

The Display panel and the bottom scene-effects bar control visualization only — object appearance and trails, speaker labels and heatmaps, the object energy field, the grid, the mpv overlay, and the UI language. None of it changes the audio.

There are deeper expert panels too — a latency target, adaptive-resampling tuning with a guided auto-tuner, and diagnostics plots — for shaping realtime behaviour. Leave them at defaults unless you’re chasing a specific glitch.

Actions

Beyond the live knobs, Studio’s buttons do things:

• Save / Reload — persist the current config to the shared file, or reload it from disk (bottom bar).
• Recenter — make whichever way you’re facing the new “front” (head-tracking sub-panel).
• Layout — Presets, Import, Export; and in the editor Add / move / delete speakers, 3D Edit (drag them in the scene), Calc delays ↔ Delay → Dist, and Reset channel layout.
• HRTF — Browse… opens the SOFA browser (your local files or the sofacoustics.org database) and uploads the chosen set to the engine.
• Renderer lifecycle (OSC panel) — Connect, Launch / Stop a local renderer, install / start / stop / restart it as a background service, and (Linux) Restart PipeWire. Studio can also auto-start a standby renderer when nothing answers.
• Logs — copy, clear, filter, and set the engine log level.
• About — version, license, repository, and the active config path.

In the 3D scene

• Orbit and zoom the camera around the listener.
• Drag a speaker to reposition it (or arm the editor’s 3D-edit gizmo); the wheel over a selected speaker changes its distance.
• Drag a 2D-source channel to move its virtual position. Real, stream-driven audio objects are display-only — their positions come from the engine, so you watch them move, you don’t push them around.

Everything you change is live at once; hit Save when you want it to stick.

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.