# Unity Audio

Unity plays audio through `AudioSource` components that reference an
`AudioClip` asset. A single `AudioListener` in the scene is required
(usually on the Main Camera).

## AudioClip

An `AudioClip` is the audio data. Supported formats: WAV (uncompressed,
fastest), MP3/Ogg Vorbis (compressed, smaller). Unity imports them and
lets you choose compression per-platform in the import settings.

## AudioSource

```csharp
var src = gameObject.AddComponent<AudioSource>();
src.clip = jumpClip;
src.volume = 0.7f;
src.pitch = 1.0f;
src.loop = false;
src.playOnAwake = false;
src.spatialBlend = 0.0f; // 0=2D, 1=3D
src.Play();
```

Important properties:

| Property        | Meaning                                                   |
|-----------------|-----------------------------------------------------------|
| `clip`          | The AudioClip to play                                     |
| `volume`        | 0..1                                                      |
| `pitch`         | Default 1; >1 = higher pitch, <1 = lower                  |
| `loop`          | Repeat when the clip ends                                 |
| `playOnAwake`   | Play automatically when the AudioSource is enabled        |
| `spatialBlend`  | 0=fully 2D, 1=fully 3D (position-based)                   |
| `minDistance`   | Within this distance the sound is at full volume (3D)     |
| `maxDistance`   | Beyond this distance the sound is inaudible (3D)          |
| `rolloffMode`   | Logarithmic, Linear, or custom curve (3D falloff)         |

## 3D audio

For positional sounds (footsteps, gunfire, engines), set
`spatialBlend = 1.0f`. The volume then depends on the distance between the
AudioSource and the AudioListener.

```csharp
src.spatialBlend = 1.0f;
src.rolloffMode = AudioRolloffMode.Logarithmic;
src.minDistance = 1f;
src.maxDistance = 50f;
```

> Default `maxDistance` is 500 -- way too large for most gameplay. Lower
> it to 30-50 for SFX.

## One-shot SFX

For short sound effects (pickups, gunshots, impacts) use `PlayOneShot`:

```csharp
audioSource.PlayOneShot(clip, volumeScale);
```

`PlayOneShot` can layer multiple clips on the same AudioSource without
cutting each other off.

## AudioMixer

For volume control and grouping, create an **AudioMixer** asset
(`Assets > Create > Audio Mixer`). Expose parameters and control them at
runtime:

```csharp
[SerializeField] private AudioMixer mixer;

public void SetMasterVolume(float dB) => mixer.SetFloat("MasterVolume", dB);
public void SetMusicVolume(float dB)  => mixer.SetFloat("MusicVolume", dB);
public void SetSfxVolume(float dB)    => mixer.SetFloat("SfxVolume", dB);
```

Convert linear 0..1 to dB:

```csharp
public static float LinearToDB(float linear) =>
    linear <= 0.0001f ? -80f : Mathf.Log10(linear) * 20f;
```

## The AudioManager pattern

The generated `AudioManager.cs` is a singleton with two channels
(`sfxSource`, `musicSource`). It exposes:

```csharp
AudioManager.Instance.PlaySfx(pickupClip, 1.0f);
AudioManager.Instance.PlayMusic(menuMusic);
AudioManager.Instance.StopMusic();
AudioManager.Instance.ApplyVolumes();
```

`DontDestroyOnLoad` keeps the manager alive across scene loads so music
does not restart.

## AudioListener

* Exactly one `AudioListener` per scene. The Main Camera has one by
  default; remove it if you add another.
* The listener's transform defines "where the player's ears are" for 3D
  audio panning.

## Performance

* Pool AudioSources for sounds that play many times per second (machine
  guns, rain). Reusing one AudioSource and calling `PlayOneShot` is fine
  up to ~20 simultaneous clips.
* Use compressed formats (Vorbis) for music; uncompressed (WAV) for
  frequent short SFX.
* Set `AudioClip.preloadAudioData = true` for short clips and `false` for
  music that should stream from disk.
* Lower `maxDistance` aggressively; large falloff radii cost CPU on 3D
  sounds.