Build guides
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.
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 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) |
| 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 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.
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
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.