# Build a spatial audio effect

> Place sounds around a listener, near or far, moving or still: which spatial cues to build, the Maru building blocks for each, how to approach headphone 3D, and what is not available yet.

Canonical: https://maru.audio/help/build-a-spatial-audio-effect
Documentation index: https://maru.audio/help/llms.txt

Spatial audio decides where a sound seems to be: left or right, close or far,
in front, behind, or moving past. It powers wide mixes, auto-panners, game and
installation soundscapes, and immersive headphone effects. This guide shows how
to build those effects from cues you can combine, and where Maru's building
blocks stop today. [Stereo and spatial processing](https://maru.audio/learn/stereo-and-spatial-processing.md)
in Learn explains how hearing locates a sound.

## Pick the cues your product needs

You rarely need full 3D. Most products are convincing with two or three cues:

| Cue | What it tells the ear | Build it with |
| --- | --- | --- |
| **Level difference** | Left or right | `stereo/pan` (equal-power) |
| **Time difference** | Left or right, more naturally on headphones | A fractional delay of up to about 0.7 ms on the far ear (`delays/fractional`) |
| **Width** | How big the source is | `stereo/width` (mid/side) |
| **Distance** | Near or far | Lower level, less high end (`acoustics/physics` air absorption), more reverb relative to the direct sound, a longer predelay gap closing up |
| **Room position** | Where in a real room | A simulated room with a placed source and microphones ([Room Acoustics](https://maru.audio/modules/room-acoustics)) |
| **Motion** | Moving past | Glide the cues over time; a modulated delay adds Doppler pitch shift |

Combine level and time difference for panning that sounds less like a mixer and
more like a sound in the room. Add distance to put sounds at different depths.

## Products you can build

- **A natural panner.** Level plus a small time difference, with a
  high-frequency shadow on the far side. Better on headphones than a plain pan.
- **Auto-panner and orbit effects.** Drive position from an LFO or a tempo
  clock; add Doppler for a sound that flies around the listener.
- **A depth control.** One "distance" knob that moves level, brightness, reverb
  send and predelay together, so a mix engineer can push a part back.
- **A recording-room simulator.** Place a source and a stereo microphone pair
  (spaced, XY or ORTF) in a room. Room Acoustics does exactly this.
- **Game and installation soundscapes.** Position several sources relative to a
  moving listener. The Evolving Environment experiment drives the level, pan
  and distance of three ambience sources from a 3D scene; see
  [Game audio and creative tools](https://maru.audio/help/game-audio-and-creative-tools.md)
  for what Maru offers game projects.
- **Camera-driven space.** Map a performer's hand position to a sound's position;
  see [Play with your camera](https://maru.audio/help/play-with-your-camera.md).

## Headphone 3D (binaural)

True front, back and height on headphones come from **head-related transfer
functions** (HRTFs): measurements of how a head and ears filter sound from each
direction. A binaural renderer convolves each source with the left and right
responses for its direction and blends between measured directions as it moves.

Maru does not include a binaural renderer or an HRTF set yet. You can build a
limited version from what exists: ship a small, redistributable set of
head-related impulse responses as factory resources, choose the nearest
direction, and convolve with `filters/convolution` (HRIRs are short enough).
Crossfade between directions as the source moves to avoid clicks. Check the
licence of any HRTF dataset before you ship it; many research sets are for
non-commercial use. A shared binaural building block is planned.

## Limits to plan for

- **Stereo out.** Every catalog module has mono or stereo ports; plan for
  stereo. Surround, ambisonics and object-audio output are not available.
- **No head tracking.** Headphone effects stay fixed to the head when the
  listener turns.
- **Rooms are rectangular and static per rebuild.** A moving source in Room
  Acoustics triggers a rebuild and a crossfade rather than continuous motion.
- **Mono compatibility.** Time-difference panning can comb-filter when summed
  to mono. Check your effect in mono.

## Ask your agent

```text
Read the Maru Help article "Build a spatial audio effect". Then read Room
Acoustics with `maru module files room-acoustics` for how it places sources and
microphones, and the @maruaudio/dsp stereo, fractional delay and acoustics
physics building blocks. Build a "depth" effect with one Distance knob that
moves level, high-frequency loss from air absorption, reverb send and predelay
together, plus a natural panner that combines level and time difference.
```

Developers can find the building blocks in the [DSP library](https://maru.audio/docs/dsp.md).