> For the complete documentation index, see [llms.txt](https://kazescripts.gitbook.io/kazescripts/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kazescripts.gitbook.io/kazescripts/kaze_sound/surround-and-acoustics.md).

# Surround and acoustics

How kaze\_sound positions, muffles and reverberates sound, and how to tune it.

kaze\_sound recalculates every sound about 30 times per second from the player's camera position and what's around it.

```mermaid
flowchart LR
    S[Audio file or stream] --> V[Volume and fades]
    V --> EQ[Room tone: bass / treble]
    EQ --> O[Occlusion: muffling filter]
    O --> P[Surround panner and distance]
    P --> D[Direct sound]
    P --> R[Room reverb]
    D --> M[Master volume]
    R --> M
```

## Panning

`Config.Panning` chooses how sound is placed between the ears.

| Mode               | How it sounds                                                                                                                                 | Best for                                          |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `stereo` (default) | A sound on your right plays in your right ear only. Sounds behind you are slightly quieter and duller, so you can still tell front from back. | Speakers and headphones. The clearest left/right. |
| `HRTF`             | Binaural head model. Adds up/down cues, but bass reaches both ears as in real life, so left/right is softer.                                  | Good headphones.                                  |

The listener is the game camera by default. Set `Config.ListenerMode = 'ped'` to hear from the character's head instead.

## Distance

Each sound is at full volume inside `refDistance`, then falls off as you move away (controlled by `rolloff`). Over the last 25% of `maxDistance` it fades smoothly to silence.

Beyond `maxDistance`, the sound pauses to save resources. When you come back, it resumes at the correct point in the track.

## Occlusion

Muffling cuts the high frequencies and lowers the volume, so you hear bass through walls, as in real life. Sources add up, up to fully muffled.

| Situation                                | Default amount |
| ---------------------------------------- | -------------- |
| Wall or object between you and the sound | 0.45           |
| You and the sound in different interiors | 0.55           |
| You in a closed car (sound outside)      | 0.70           |
| Sound in a closed car (you outside)      | 0.70           |

### Vehicle doors and windows

A closed cabin muffles by 0.70. Each open door removes 0.18, the trunk 0.09, each open or smashed window 0.10. A lowered convertible roof keeps only a quarter of the muffling. Bikes, bicycles, boats, quads and jetskis have no cabin.

What someone outside a four-door car hears, with default settings:

| Car state    | Muffling | Highest frequency heard    | Volume |
| ------------ | -------- | -------------------------- | ------ |
| All closed   | 0.70     | \~1.1 kHz (bass and thump) | 62%    |
| 1 door open  | 0.52     | \~2.3 kHz                  | 71%    |
| 2 doors open | 0.34     | \~4.9 kHz                  | 81%    |
| 3 doors open | 0.16     | \~10 kHz                   | 91%    |
| 4 doors open | 0.00     | full, clear                | 100%   |

When you sit in the **same** vehicle as the sound, there is no muffling: the radio is clear and centred, with a short car-cabin reverb.

{% hint style="info" %}
The wall check ignores anything within `sourceClearance` (1.5 m) of the source, so a speaker prop, or the wall a speaker is mounted on, doesn't muffle its own sound.
{% endhint %}

## Room presets

Set `reverbPreset` per sound to give it the sound of a room.

| Preset      | Sound                             | Echo               | Tone                      |
| ----------- | --------------------------------- | ------------------ | ------------------------- |
| `auto`      | `room` indoors, `outdoor` outside | —                  | —                         |
| `club`      | Nightclub                         | 1.9 s, dark        | +6 dB bass, softer treble |
| `bar`       | Bar or lounge                     | 1.1 s              | +2.5 dB bass              |
| `hall`      | Concert hall                      | 3.2 s, spacious    | —                         |
| `warehouse` | Warehouse party                   | 2.8 s, hard walls  | +3 dB bass                |
| `garage`    | Garage, concrete                  | 1.6 s, bright      | —                         |
| `room`      | Small room or house               | 0.9 s              | —                         |
| `bathroom`  | Tiles                             | 1.1 s, very bright | —                         |
| `outdoor`   | Open air                          | slight             | —                         |
| `car`       | Inside a car (used automatically) | very short         | +3 dB bass                |
| `dry`       | No reverb                         | none               | —                         |

When you're **outside** the source's room (for example outside the club), reverb is boosted by `outsideBoost`, so you hear the room's boom leaking out along with muffled bass. Reverb also grows as you move further away.

```lua
exports.kaze_sound:Play({
    url = 'https://cdn.example.com/set.mp3',
    coords = vec3(-1388.0, -618.0, 30.8),
    maxDistance = 60.0,
    reverbPreset = 'club',
    reverbAmount = 1.2, -- a bit more echo than the preset
})
```

## Directional speakers

A `cone` makes a speaker loud in front and quieter behind. It faces the attached entity's forward direction, or `dir` for a fixed position.

```lua
exports.kaze_sound:Play({
    url = url,
    entity = speakerProp,
    cone = { inner = 90, outer = 220, outerGain = 0.25 },
})
```

## Doppler

`doppler = true` shifts the pitch as the source moves towards or away from you, like a passing siren. Leave it off for music.