Docs

Binaural for headphones

No speakers? Fold the whole scene into a stereo pair with HRTFs, room reflections, measured rooms and live head tracking — the room, on your head.

Not everyone has a ceiling full of speakers. Flip Omniphony to headphones and the whole scene collapses into a plain stereo pair — every bed channel and every object filtered through a head-related transfer function (HRTF), with interaural time delay, room reflections and live head tracking so sounds stay put when you turn your head. Or skip the simulation and load a measured room: a set of impulse responses recorded in a real studio, with the speakers it was measured on.

Hear it in ten seconds

The bundled demo is the headphone stage — no media file, no speakers, no proprietary decoder:

cd omniphony-renderer
./scripts/demo.sh            # a source sweeps around your head, in stereo

It renders the rotating 7.1.4 demo bed through the headphone stage to your default output. No audio device? ./scripts/demo.sh file pipes the same raw stereo to ffplay.

Three ways onto your head

Path Config What it does
Headphones (direct) mode: direct (default) Each channel and object goes straight through the HRTF from its own direction. Your speaker layout isn’t used.
Headphones (virtual room) mode: cascaded Objects are panned onto your speaker layout as virtual speakers, then each speaker is binauralised. Hear what your rig would do, on headphones.
Measured room (BRIR) hrir_source: brir The file’s own loudspeakers, in the room it was measured in. No simulation added on top.

In Studio these are the three output-mode cards under Renderer (or Listening in the Essentials view): Speakers, Headphones, Headphones (virtual room). The 3D view follows the path that actually renders — the listener cube, your room with its virtual speakers, or the measured room in metres — and a badge in the corner names the path and the HRTF set (and says so when it fell back to the default).

What happens to each sound

On the direct path, per channel, per block:

position → rotate by your head pose → (azimuth, elevation, distance) → air-absorption low-pass → per-ear time delay (ITD) → HRIR convolution → early room reflections → shared late-reverb tail → mix into [L, R]

There’s no 1/d gain on the direct sound: an object keeps the level it was authored at, and distance comes from the reflections (each one levelled by its own path, with its own ITD and its wall’s low-pass), a reverb send that grows with distance, and air absorption. The LFE skips the whole chain and goes to both ears at −3 dB.

The reflections and reverb aren’t decoration — they’re what pulls the sound out of your head. A bone-dry HRTF render almost always sounds like it’s between your ears; a little room puts it back in the world.

Turning it on

In config, under render.binaural:

render:
  binaural:
    output_mode: binaural      # "speaker" (default) or "binaural"
    mode: direct               # "direct" (default) or "cascaded" (virtual room)
    hrir_source: saf           # which HRTF to use (see below)
    unit_scale_m: 3.0          # metres per scene unit — sets apparent distance (default 1.0)
    reflections:
      enabled: true            # off by default
      level: 0.4
    reverb:
      enabled: true            # off by default
      level: 0.2
      rt60_s: 0.3

(That’s the demo’s setup, not the defaults.) The reverb also has size and per-band decay (rt60_low_ratio, rt60_high_ratio), and the reflection room its own dimensions — a minimum, it grows to hold the scene.

Every one of these is also an orender render flag since 0.7.0: --output-mode binaural, --binaural-mode cascaded, --hrir-source …, --[no-]reflections-enabled, --reverb-rt60-s … and friends (orender render --help lists them all).

In Studio it’s all live; press Save when you want it in config.yaml.

Playing films? In mpv-omniphony the output mode is applied when the player starts — switch modes, then (re)start playback. It’s also worth setting audio-buffer=0.05 in mpv.conf so head movements track tightly.

Choosing an HRTF

The HRTF is the “shape of your ears” filter, set by render.binaural.hrir_source:

Value What it is
saf Embedded measured KEMAR set. The default — the best generic starting point.
synthetic Analytic head-shadow model, no measured data. Lightest; no pinna colouration.
sofa A SOFA file you supply (hrtf_sofa_path, or sofa:<path>).
pinna / prtf Parametric ear models you can tune by hand; the pinna model is fitted to the KEMAR set.
brir A measured room (brir_sofa_path) — see below.

Measured sets are stored as minimum-phase responses and interpolated over their triangulation; a SOFA set loads in milliseconds. Diffuse-field equalisation is a switch (diffuse_field_eq, off by default), and the head radius used for the ITD model is tunable.

Here’s the thing about generic HRTFs: they rarely give you good up/down. Elevation cues are spectral notches carved by your pinna, and a stranger’s ears won’t match. If height feels flat or the image sits too high, go HRTF shopping — pick SOFA file as the source in Studio and hit Browse…: it pulls measurements straight from sofacoustics.org (after asking once per session) so you can audition subjects until one clicks, and keeps a local cache of the ones you tried. Studio tells you which set is actually playing, and why when a file didn’t load. (Omniphony never redistributes HRTF data; it ships only the openly-licensed KEMAR set.)

Measured rooms (BRIR)

A binaural room impulse response set is a room in a file: someone sat a dummy head in a studio, played each loudspeaker, and recorded what reached each ear — often for several head orientations. Load one and Omniphony renders onto those loudspeakers, in that room:

render:
  binaural:
    output_mode: binaural
    hrir_source: brir
    brir_sofa_path: /path/to/room.sofa
  • It always takes the virtual-room path (in Studio, BRIR is offered under Headphones (virtual room), and Browse… opens a file picker).
  • Your speaker layout is kept but not used; the speakers are the file’s, read-only, without per-speaker gain, delay or bands. The 3D view draws the measured room in metres.
  • Nothing is simulated on top — no ITD, air absorption, reflections or reverb: the room is in the recording.
  • With head tracking, the nearest measured orientation is used (brir_head_tracking); brir_max_length_s and brir_tail_floor_db trim long tails.
  • While the file loads, or if it fails, you hear KEMAR.

Good places to start: the BBC’s bbcrd-brirs (there’s a 7.1.4 system), the IoSR sets, or what the ASH Toolset produces.

Where channels land on headphones

  • Fixed channels by angle. On headphones, a source family you haven’t set a placement for is placed on the Sphere — each channel at its format’s nominal angle — rather than at the corners of the room model. A mode you chose is kept.
  • Objects on a sphere. render.binaural.sphere_coordinates: true (Studio: Read positions on a sphere, direct path only) reads object coordinates on the listener’s sphere, so a place a speaker takes in the room is heard at that speaker’s nominal angle: front left/right at ±30° instead of ±45°, the top layer 45° up instead of 35°.

Head tracking

Static binaural is fine; tracked binaural is the magic — the scene stays fixed in the room while your head turns. Omniphony takes head orientation over OSC from any source you point at it.

Set an address and format under render.binaural.head_tracking (an empty address disables tracking):

render:
  binaural:
    head_tracking:
      osc_address: /gamerotationvector
      format: auto        # auto | quat | rotvec | euler
      smoothing: 0.2      # 0–0.99
  • auto figures it out: 4 floats → quaternion [x, y, z, w], 3 floats → rotation vector.
  • quat [x, y, z, w], rotvec [x, y, z], euler [yaw, pitch, roll] in degrees.

Pose arrives on the renderer’s OSC port (UDP 9000 by default), so make sure your firewall lets that in. In Studio, the Head tracking group has Recenter (whatever way you’re facing becomes “front”), Calibrate axes (a three-pose calibration — face front, turn left, look up — for a sensor mounted at any angle), smoothing, an invert switch and a live pose readout; the 3D head in the scene turns with you. Recenter and calibration are kept right away, no Save needed.

Where the orientation comes from

  • A phone — Sensors2OSC on Android. Enable its Game Rotation Vector sensor (gyro + accelerometer, no magnetometer drift) and aim it at your-machine:9000.

  • A dedicated tracker — the nx-tracker-osc CLI reads a Waves Nx head tracker over Bluetooth (Linux) and emits the same /gamerotationvector feed:

    nxosc run --profile omniphony --osc-address /gamerotationvector --osc-target 127.0.0.1:9000

    (Its default profile drives an IEM SceneRotator instead, hence --profile omniphony.)

Under the hood, over OSC

Everything above is reachable from any OSC client — /omniphony/control/output_mode, /omniphony/control/binaural/hrir_source, /omniphony/control/binaural/sphere_coordinates, /omniphony/control/head/tracking/{address,format,smoothing,invert}, /omniphony/control/head/recenter and /omniphony/control/head/calibrate — or any option through the generic /omniphony/control/option [key, value]. Going the other way, the engine streams head pose back on /omniphony/state/head_pose (w x y z, ~30 Hz) so a visualizer can follow along with low latency, plus a fuller binaural block inside /omniphony/state/renderer. See the OSC protocol guide for the shape of that contract.