Docs

Speaker layout

Tell the engine where your speakers actually are — a few lines of YAML, and VBAP figures out the rest. Stock rigs included, weird ones welcome.

A layout is just a list of where your speakers sit in space. Give the engine that, and VBAP works out how to steer any object onto them — no per-format wiring, no fixed channel map. Standard rigs ship ready to go; if yours is weird, it’s a few lines of YAML away.

What ships

The bundled layouts live in the layouts/ folder. The immersive ones (with height) are loaded as presets:

Layout Channels Notes
5.1.2 8 5.1 bed + 2 height
7.1.2 10 7.1 bed + 2 height
7.1.4 12 7.1 bed + 4 height — the default
9.1.6 16 9.1 bed + 6 height

If you never configure a layout, the engine falls back to 7.1.4. There’s also a layouts/legacy/ folder of flat (no-height) configs — 2.0, 2.1, 4.0, 4.1, 5.0, 5.1, 6.1, 7.1 — which you can import but which don’t show up as presets.

The YAML format

A layout is an optional radius_m scale and a list of speakers. Here’s the top of the default 7.1.4.yaml:

# Omniphony live 7.1.4 layout in normalized Cartesian coordinates.
# LFE remains non-spatialized.
radius_m: 1
speakers:
  - name: "FL"
    coord_mode: "cartesian"
    x: -1.0
    y: 1.0
    z: 0.0
    spatialize: true
    delay_ms: 0
  # ... FR, C, ...
  - name: "LFE"
    coord_mode: "cartesian"
    x: 1.0
    y: 1.0
    z: -1.0
    spatialize: false
    delay_ms: 0

Per-speaker fields:

  • name — the speaker label (FL, TFR, LFE, …).
  • coord_mode — "cartesian" (all shipped layouts) or "polar" (the default when the key is left out).
  • x / y / z — Cartesian position, clamped to [-1, 1] (or azimuth / elevation / distance in polar mode). When all three of x/y/z are present they win, whatever coord_mode says.
  • spatialize — true to pan it with VBAP, false to route straight through (LFE).
  • delay_ms — optional per-speaker output delay.
  • gain_db, freq_low / freq_high — optional trim, and the speaker’s usable frequency range (see Crossover).

There is no channel-index field: output channel order is simply the order speakers appear in the file. (That’s a feature — e.g. 5.1.2 parks its two height speakers in the 7th/8th slots so it drops onto a plain 7.1 sound card.)

And no speaker limit: since 0.7.0 the engine sizes everything for the layout you give it, and layouts are tested up to 128 speakers. Two limits remain outside the engine: mpv carries at most 64 channels, and a layout wider than your output device is refused with a message.

Where things are: the coordinate system

Cartesian coordinates are normalized to [-1, 1] and read like a room seen from above:

  • x — right is positive, left is negative.
  • y — front is positive, rear is negative.
  • z — up is positive, down is negative.

Top-down view of the shipped 7.1.4 layout: bed speakers as solid squares on the walls and corners, height speakers as dashed rings sharing the four corners, LFE as a non-spatialized box at the front right

Prefer angles? Switch coord_mode to "polar" and use azimuth / elevation / distance instead: azimuth 0° is dead ahead, -90° is hard left, +90° hard right, ±180° behind you; elevation 0° is ear-level, +90° straight up. The engine keeps both representations for every speaker, so you can author in whichever feels natural.

Direction is what VBAP cares about: distance doesn’t change a VBAP pan. The volumetric backend does read it — it measures an object’s depth against each speaker’s distance from the listener. The layout-wide radius_m is only the metres-per-unit scale Studio draws with.

Height speakers

Top speakers use a T prefix and positive z: TFL / TFR (top front), TBL / TBR (top back), and TSL / TSR (top side, in 9.1.6). The 9.1.6 layout also adds wide-front FWL / FWR on the bed.

There’s also a 30° height tier, below the ceiling: Lh / Rh / Ch / Lhs / Rhs, each above the floor speaker of the same name — the layer Auro-3D puts its heights on. (Careful: HL / HR still mean the top-front pair, not this tier.)

How VBAP uses it

When you pick a layout, the engine collects every spatialize: true speaker, triangulates their directions on the unit sphere (Delaunay via convex hull), and renders each object through the three surrounding speakers. Notes:

  • You need at least three speakers.
  • If the hull leaves a pole uncovered — a rig with no height speakers, say — the engine adds virtual speakers at the poles and folds their gain back onto the speaker ring (out_of_hull_mode: virtual_poles, the default, after ITU-R BS.2127; blend and fade are the alternatives).
  • Four or more speakers on one flat face — the rear wall of a 7.1.4, a four-speaker ceiling — are closed around a virtual speaker at the face’s centre, downmixed onto them. Before 0.7.0 such a face was split along an arbitrary diagonal, and a sound could lean left or right depending on which way the split went.
  • LFE and other spatialize: false speakers sit out of the triangulation entirely — they’re fed directly.

Changing the layout triggers a topology rebuild on a background thread. Every freshly built topology is smoke-tested on reference positions before it goes live. A layout with too few speakers, or a backend that misbehaves, is rejected with the reason shown in Studio instead of stalling the scene or crashing the audio thread; a layout that can’t be triangulated at all (every speaker on one line, say) falls back to a directional pan, with a loud warning in the log.

Crossover: rendering per band

Give speakers a usable frequency range — freq_low / freq_high, in Hz — and the engine splits every spatialized signal into bands and runs a separate pan per band, each on just the speakers that can actually reproduce it. Small speakers stop carrying the bass; a big speaker can carry everything. It’s entirely opt-in: leave the fields out (no bundled layout sets them) and there is a single full-range band with zero filtering cost.

How bands form

The engine collects every freq_low/freq_high value from spatialize: true speakers, sorts them, and slices the spectrum at those edges: two cutoffs at 120 and 500 make three bands — [0, 120), [120, 500), [500, ∞). A speaker belongs to a band when its own range contains the whole band; a speaker with no freq fields is full-range and belongs to every band. Up to 8 bands (7 distinct cutoffs) are supported.

One consequence worth knowing: if some frequency range is covered by no speaker, that band renders silence (with a warning in the log) — the engine won’t secretly fold it into speakers you declared unable to play it. Make sure the ranges you declare add up.

The filter

Each split is a 4th-order Linkwitz-Riley pair (two cascaded 2nd-order Butterworth sections per side), applied per object, per sample: −6 dB at the cutoff and a symmetric 24 dB/octave slope in both directions. A band-limited sub is genuinely protected from mids and highs, and band-limited mains are just as genuinely relieved of the deep bass — two octaves from the cutoff, out-of-band content is ~48 dB down.

Linkwitz-Riley is the standard speaker-crossover choice for a reason: the two sides stay in phase, so however many bands you create, they recombine flat in magnitude — a benign all-pass phase rotation is the only trace of the split, the same trade every AVR and active crossover makes. With three or more bands the engine also phase-aligns the lower bands at each upper cutoff, so the flat-sum property holds around every crossover point, not just the first.

Panning happens per band

Every band gets its own VBAP topology, triangulated over just that band’s speakers — and this composes with everything else: whichever render backend is active is instantiated per band on the reduced speaker set, so custom backends work under crossover without knowing it exists. An object’s low band might be shared between two woofers while its highs pan across the full ring.

Bands with fewer than three speakers degrade gracefully: two speakers become a pairwise directional pan, and a band with a single speaker sends everything to that speaker, wherever the object is — a property the subwoofer recipe below exploits. Per-speaker gain_db and delay_ms apply after all bands are summed. On headphones, the direct binaural path bypasses the crossover entirely; the virtual-room path goes through it, like real speakers would.

Prefer linear phase? crossover_type: fir swaps the LR4 pairs for linear-phase FIR filters (with their own transition width), at the price of about 0.1 s of latency — bed channels are delayed to match.

Routing object bass to a subwoofer

First, the default, because this trips people up: a spatialize: false LFE receives only the stream’s own LFE channel, routed to it directly by name. Objects never bleed into it, and nothing bass-manages the other channels — declaring an LFE does not mean “bass goes to the sub”. Out of the box there is no bass management at all.

If you want object bass collapsed onto the sub, flip it into the crossover and give it the low band alone:

speakers:
  - name: "LFE"
    spatialize: true      # joins the crossover as a real speaker
    freq_high: 120        # only handles the low band
    # x/y/z: wherever the sub physically sits
  - name: "FL"
    freq_low: 120         # opts *out* of the low band
    # ...same freq_low on every other spatialized speaker

Both halves of that recipe matter. freq_high: 120 on the sub puts it in [0, 120); freq_low: 120 on every other spatialized speaker takes them out of it. The sub is then the only speaker in the low band, and the single-speaker rule above does the rest: the sub receives the below-120 Hz content of every object, summed to mono, while the bands above 120 ignore it completely. It still receives the stream’s LFE channel as before — that direct feed is keyed on the speaker’s name and doesn’t care about spatialize.

Two precisions:

  • Only spatialized content is bass-managed. Bed channels routed directly to their named speakers bypass the crossover, full-range. If your 2D sources are set to spatialized, they render as objects and their bass follows the recipe like everything else.
  • If you skip the freq_low on the other speakers, they stay full-range and share the low band with the sub — object bass is then panned across sub + mains instead of collapsing onto the sub (a sub sitting at the listener position takes a fixed share rather than being panned). That’s a legitimate setup too; just know which of the two you’ve built.

Choosing a layout

In Studio — the buttons in the Speakers section: Presets opens the bundled layouts folder, Import layout loads a .yaml from anywhere (this is how you pull in a legacy/ config or your own). It applies live; press Save to keep it in your config.

On the CLI — point --speaker-layout at a file and turn VBAP on:

orender render --enable-vbap --speaker-layout layouts/7.1.4.yaml input.bin

In the config — two keys under render::

  • render.current_layout — a full layout embedded inline. This is what Studio writes.
  • render.speaker_layout — a path to a YAML file. When one is set, orender loads it instead of the embedded copy.

Saving a config after --speaker-layout embeds that file into current_layout and clears the path, so keep one or the other. With neither, the engine renders 7.1.4.

Two layout-adjacent knobs

Both of these change how the layout is driven, and both live in Studio, the config, and OSC:

Surround placement (render.surround_placement, default side) — for older 4.x/5.x sources that don’t carry dedicated back channels, this decides whether their surrounds sit at the side corners (≈ ±90°) or the back corners (≈ ±135°). It moves the room-model corners only (the Room placement below), never a Sphere angle or a Manual entry; sources that already have back channels ignore it.

Output channel mapping (render.output_channel_mapping, default by_index) — how the finished speaker feeds are handed to the OS:

  • by_index — positionless: output port N carries layout speaker N, in file order. Right for a DAC / ASIO / CoreAudio device wired to your layout’s channel order.
  • by_name — positional: each channel is tagged with its speaker position so a position-aware sink (PipeWire, a standard AVR) routes by name.

Where fixed channels go

Objects carry their own positions. A channel bed — the 5.1 or 7.1.4 part of a stream, or plain PCM — only carries labels (L, Ls, TFL, …), so something has to decide where each label sits. Since 0.6.0 that’s decided per source family: generic, pcm, and the families the decoder bridge reports (dolby, dts, auro, iamf). Each family picks a mode:

Mode Where a channel lands
sphere At the angle the format declares for it, or the ITU-R BS.2051 nominal angle when it declares none.
room At the corner of the room model its label names — the cube Dolby beds live in.
manual Wherever you put it: your own entries, edited in Studio (drag the channel in the 3D scene) or in config.

A family can also inherit Generic’s setting. Defaults: Auro-3D and IAMF on the Sphere, everything else in the Room — and on headphones, every family you haven’t set goes on the Sphere.

render:
  placement:
    dts:
      mode: sphere
    generic:
      mode: manual
      layout: { ... }   # your entries

Each entry also says whether the channel is virtualised (spatialize: true: rendered as a fixed object across your whole layout, from the position above) or routed directly to the speaker with the same label (spatialize: false — the LFE by default). Both can coexist in one bed. In Studio it’s the Placement group of Fixed-channel sources, one tab per family with the playing one marked, and the per-channel Channel Editor; over OSC, /omniphony/control/placement/{mode,layout}.

Rolling your own

Copy the closest bundled layout, move the speakers to where yours physically are (normalized x/y/z, or polar angles), mark any subwoofer spatialize: false, and import it in Studio. If the geometry is valid you’ll see it render immediately; if it isn’t, Studio tells you why. That’s the whole loop — go put speakers in strange places.