# Pepper.SFX: Audio middleware for Unity

> Pepper.SFX is audio middleware for Unity. Build your game’s sound as assets (events, containers, buses, states and parameters) and play any of it with one line of code.

Unity 6000.0.48f1 or newer. Package `com.pepper.sfx`, namespace `AudioSystem`. Free version: https://github.com/IamAmirPepper/Pepper.SFX_System. Full version: coming to the Unity Asset Store. Docs version: 3.1. Site: https://peppersfx.com/

# Features

## Events and containers

Source: https://peppersfx.com/features/events-and-containers/

Without middleware, every sound in a Unity game is an AudioSource and a clip wired up in code, and picking variations, stopping spam, fading and routing are all yours to write. Pepper.SFX moves that work into assets. You build an **Audio Event** and the containers under it, and your code plays it with one call that returns a handle.

### How it works

- **Audio Event** is what your code posts. It holds a list of **actions** that run in order, each with an optional Delay: Play, Stop, Pause, Resume, SetSwitch, SetRTPC, SetState, TriggerDucking and CrossFade. One post can start a sound, change a state and duck the music.
- **Voice Settings** keep an event in check: Priority, **Max Instances** with a Steal Behavior (Oldest, Quietest, Furthest, Lowest Priority), **Cooldown**, and the same limits per Audio Emitter. Tick **Persistent** for sounds that must never be stolen, such as an engine. **Time** picks game or real time, so pause-menu sounds work at time scale 0.
- **`Post`** returns an `AudioHandle`. Stop it with a fade, pause it, change its volume or pitch, or wait for `OnFinished`.
- **Containers** decide which clips play, and they nest inside each other:
  - **Random Container**: one clip per post, with weights and Avoid Repeat Last, remembered per Audio Emitter. Footsteps, gunshots, clicks.
  - **Sequence Container**: clips in order (Forward, Reverse, Ping Pong or Random), with Auto Advance, Loop Sequence and a Delay After per entry.
  - **Switch Container**: plays the child that matches a switch value, such as the surface under a foot.
  - **Blend Container**: layers that crossfade along a parameter, such as engine RPM or combat intensity.
  - **Routing Container**: plays all its clips at once, for layered sounds like an explosion's blast and debris.
- Every container also has volume and pitch randomisation, 3D settings, a Mixer Group and Parameter Curves.

### Example

```csharp
using UnityEngine;
using AudioSystem;

public class Generator : MonoBehaviour
{
    [SerializeField] private AudioEvent switchOn;   // Random Container: three clunks
    [SerializeField] private AudioEvent hum;        // Routing Container with Loop ticked

    private AudioHandle humHandle;

    public void TurnOn()
    {
        switchOn.Post(gameObject, transform.position);              // fire and forget
        if (humHandle == null)
            humHandle = hum.Post(gameObject, transform.position);   // keep the loop's handle
    }

    public void SetLoad(float load01)
    {
        humHandle?.SetPitchOffset(load01 * 2f);   // up to two semitones higher under load
    }

    public void TurnOff()
    {
        humHandle?.Stop(0.5f);                    // fade out over half a second
        humHandle = null;
    }
}
```

The clunk is posted and forgotten. The hum loops, so the script keeps its handle to bend its pitch and fade it out. Posting by name (`AudioManager.Instance.PostEvent("Generator_Hum")`) needs the event in an Audio Event Registry or `Resources/Audio/Events`.

### Setting it up

1. Add the `AudioManager` component to a GameObject in your first scene.
2. Create a container with **Assets > Create > Audio System > Random Container** (or Sequence, Switch, Blend or Routing Container) and add your clips.
3. Create the event with **Assets > Create > Audio System > Audio Event**. Add a Play action and set its Container and Target Bus.
4. Set Priority, Max Instances and Cooldown under Voice Settings.
5. Drag the event into an `AudioEvent` field on your script and call `Post`.

**Window > Audio System > Sound Builder (Simple)** makes a bus, container and event in one step, and **Window > Audio System > Audition** plays a container outside Play mode.

### Good to know

- A Stop action only stops sounds that its own event started. To stop music started by another event, keep the handle from `Post` and call `Stop` on it.
- Calling `Stop()` on a container stops every sound playing from that container asset. To stop one of them, stop its handle.
- Each Sequence Container asset keeps a single position, so two objects playing the same one share it. Duplicate the asset if you need two independent sequences.
- Posting a Blend Container event again plays a second copy alongside the first. Set the event's Max Instances to 1 if you want it to restart instead.
- A post blocked by Cooldown returns a handle that has already finished, so `OnFinished` still fires.

## Parameters, states and switches

Source: https://peppersfx.com/features/parameters-states-switches/

A car's engine follows its RPM, footsteps change with the ground, and the mix shifts when the player dives underwater. Pepper.SFX gives each a home: parameters for numbers, switches for choices and states for game modes, set from code or from an event's actions.

### How it works

- **Parameter assets** (RTPCs) are named numbers with a range, a unit label, a default and **Smoothing**: None, Rate or Ease, with separate rise and fall. The string API (`SetRTPC("CombatIntensity", 0.7f)`) and an asset with that Parameter Name are the same parameter.
- **Three scopes.** A value can be set on one sound's handle, on an **Audio Emitter** (every sound on one car), or globally. A sound reads the closest one that has a value, so two cars can play the same engine Blend at different RPMs.
- **Built-in values.** Set a parameter's **Value From** to Distance, Approach Speed or Angle and Pepper works it out for each sound, from the listening point.
- **Parameter Curves** on any container drive its volume (dB), pitch (cents), low-pass or high-pass (Hz) from a parameter, with no code. A Blend Container crossfades its layers along one.
- **Values at post.** `PostValues` carries up to four parameter values and two switch values, so a one-shot's first sample hears them.
- **Switch Group assets** list a switch's values (Asphalt, Gravel, Grass). Set them globally, per emitter or per handle, and a Switch Container plays the matching child. **When Switch Changes** (Next Play Only, Crossfade, Restart) decides what a playing loop does. A group can also be **Driven By** a parameter through ranges, with hysteresis.
- **Audio State assets** belong to a **State Group**, and one state per group is active. A state sets bus volumes, switches, RTPCs and exposed mixer effect values, easing the levels over a transition time.

### Example

```csharp
using UnityEngine;
using AudioSystem;

[RequireComponent(typeof(AudioEmitter))]
public class CarAudio : MonoBehaviour
{
    [SerializeField] private AudioEvent engineEvent;        // a Blend Container on RPM
    [SerializeField] private AudioEvent impactEvent;
    [SerializeField] private AudioParameter rpm;            // 800-7000, Smoothing: Ease
    [SerializeField] private AudioParameter impactStrength; // 0-1
    [SerializeField] private AudioSwitchGroup surface;      // Asphalt, Gravel, Grass

    private AudioEmitter emitter;

    void Start()
    {
        emitter = GetComponent<AudioEmitter>();
        emitter.Post(engineEvent);
    }

    public void UpdateEngine(float engineRpm) => emitter.SetParameter(rpm, engineRpm);  // this car only

    public void OnSurfaceChanged(string value) => emitter.SetSwitch(surface, value);

    void OnCollisionEnter(Collision collision)
    {
        float strength = Mathf.Clamp01(collision.relativeVelocity.magnitude / 20f);
        emitter.Post(impactEvent, PostValues.Of(impactStrength, strength));
    }
}
```

Each car keeps its RPM and surface on its Audio Emitter, so many cars share one engine event, and the impact's strength travels with the post. A game mode is one global call: `AudioManager.Instance.SetState("Underwater", 1.5f)`.

### Setting it up

1. **Assets > Create > Audio System > Parameter**. Set Unit Label, Min Value, Max Value, Default Value and Smoothing.
2. **Assets > Create > Audio System > Switch Group**. List its Values and set a Default Value.
3. On a container, add a Parameter Curve, set a Blend Container's Blend Parameter, or set a Switch Container's Switch Group.
4. Add **Add Component > Audio System > Audio Emitter** to each object that needs its own values, and post its sounds on it.
5. **Assets > Create > Audio System > Audio State**. Set its State Name and State Group, then the bus volumes, switches and RTPCs it changes. Keep states in `Resources/Audio/States`, or list them in an Audio Event Registry.

### Good to know

- Values set by name (`SetRTPC`, `TransitionRTPC`) are never smoothed. Smoothing applies to writes through the asset (`SetParameter`, `RampParameter`).
- Code can't set a built-in value: `SetParameter` on one is ignored with a warning.
- A value that isn't a number (NaN or infinity) is refused with a warning, and sounds keep the last good value.
- Setting a state applies only its own values: nothing from the previous state is undone, so give each state in a group a value for everything its siblings change. The exception is Bus Volume Mode Offset: its offsets go back when the state ends.
- Parameters update once a frame, after every LateUpdate, so a value written anywhere this frame is heard this frame.
- In Play mode, **Window > Audio System > Live View** shows every Audio Emitter's values and sounds.

## Buses and mixing

Source: https://peppersfx.com/features/buses-and-mixing/

Players expect a music slider, dialogue they can hear over explosions, and a pause menu that stops the world but not its own clicks. In Pepper.SFX each of those is a setting on an **Audio Bus** asset. Set it once, and every event routed to that bus follows it.

### How it works

- **Hierarchy.** Each bus has a Parent Bus. Its level (Volume, plus any state's offset, plus the player's volume, in dB) is multiplied by its ducking, its curves and its parents' levels, so muting a bus mutes its children. A bus can also feed a Unity Audio Mixer Group for Unity's effects.
- **Ducking.** A trigger bus lists Ducking Targets, each with a Duck Amount in dB, plus attack and release times. A TriggerDucking action or `bus.TriggerDucking(holdSeconds)` starts it. When ducks overlap, the deepest wins, so a short UI duck can't cut a dialogue duck short.
- **Parameter Curves on a bus.** A bus's volume, and a low- or high-pass on its Mixer Group, can follow a parameter, such as nitro sweeping the other cars' low-pass.
- **Pausing a bus.** `Pause()` fades the bus and its child buses out over about 25 ms and holds their place without keeping real voices. `Resume()` carries on, every layer in phase. **While Paused** decides whether one-shots posted meanwhile are dropped or held.
- **Player volume.** `PlayerVolumeDb` is a separate level for a settings menu. It is never saved into the asset, and no state undoes it.
- **Voice caps.** **Max Real Voices** caps a bus's real voices. Over it, the least important sounds go virtual, never ended, and come back in step.
- **States.** An Audio State can move bus levels: **Set Level** writes the bus's Volume, **Offset** moves it and puts it back when the state ends.
- **Mixer window** (full version only): **Window > Audio System > Mixer** shows every bus as a fader with mute and solo; changes are saved and can be undone.

### Example

```csharp
using UnityEngine;
using AudioSystem;

public class MixControls : MonoBehaviour
{
    [SerializeField] private AudioBus musicBus;
    [SerializeField] private AudioBus worldBus;     // parent of Vehicles, Ambience...
    [SerializeField] private AudioBus dialogueBus;  // ducks Music when triggered

    // Settings sliders, 0 to 1.
    public void SetMasterVolume(float slider) => AudioManager.Instance.SetMasterVolume(slider);
    public void SetMusicVolume(float slider) =>
        musicBus.PlayerVolumeDb = AudioSystem.AudioExtensions.LinearToDb(slider);

    public void OpenPauseMenu()
    {
        Time.timeScale = 0f;
        worldBus.Pause();       // the world holds; the menu's own buses play on
    }

    public void ClosePauseMenu()
    {
        worldBus.Resume();
        Time.timeScale = 1f;
    }

    // Duck the music while a voice line plays.
    public void OnLineStarted(float lineSeconds) => dialogueBus.TriggerDucking(lineSeconds);
}
```

Sliders set the player's volume, so a mix state never fights the settings menu. Pausing the World bus holds the game while the UI and menu-music buses outside it keep playing.

### Setting it up

1. **Assets > Create > Audio System > Audio Bus** for Master, then Music, SFX, Dialogue and so on, each with its Parent Bus set.
2. On the `AudioManager`, assign the Master Bus and add every bus to Buses, so lookups by name find them.
3. Set the Target Bus on each event's Play action.
4. For ducking, tick Enable Ducking on the Dialogue bus, add Music to its Ducking Targets, and give the dialogue event a TriggerDucking action (Target Bus: Dialogue, Fade Duration: the hold time).
5. For a filter curve, give the bus a Mixer Group, add a Low Pass Parameter Curve, and click **Add Low Pass to Mixer Group** in the bus inspector.

### Good to know

- Ducking is triggered, not detected from what the bus plays. A duck runs on the target bus's Ducking Time Mode: Scaled, the default, freezes at time scale 0, so set Unscaled on buses ducked during a pause.
- A raise can't take a sound past its AudioSource's full volume, so mix with headroom.
- Bus curves read only a parameter's global value, and pitch curves are ignored on a bus. If the inspector button can't edit the mixer in your Unity version, it logs the manual steps.
- Unity's Web audio has no mixer effects, so bus filter curves don't work in Web builds.
- On Unity 6.3, write `AudioSystem.AudioExtensions` in full: Unity added its own `AudioExtensions`.

## Occlusion

Source: https://peppersfx.com/features/occlusion/

A gunshot on the other side of a wall should sound dull and distant, not as if it went off beside the player. Pepper.SFX muffles 3D sounds when walls, cover or props stand between them and the listener. You tick **Use Occlusion** on a sound's container, and Pepper casts the rays and drives the filter.

### How it works

- Every **Occlusion Update Interval** (0.2 s by default), the Audio Manager casts rays from the listening point to each occluded sound, against the layers in **Occlusion Mask**. Trigger colliders are ignored, and so are the sound's own object and the player.
- **Occlusion Ray Count** (3 by default) fans the rays across the source, **Occlusion Ray Spread Meters** wide. A partly hidden sound is partly muffled, so walking past the edge of a wall gives a gradient rather than a jump. Set it to 1 for a hard edge.
- Fully blocked, a sound drops by about 10 dB and a low-pass filter takes off its top end. Level and cutoff glide to their targets every frame, so nothing steps.
- The filter doesn't sit on the AudioSource: a filter component resets each time the voice pool reuses a source, and that clicks. Instead Pepper builds an **occlusion mixer slot pool**, a set of mixer groups under each bus (six by default), each with a Lowpass effect. A voice borrows a slot before it starts and returns it when it ends, and Pepper writes the cutoff to the slot's exposed mixer parameter.
- The same slots carry per-zone reverb sends (**Allow Reverb Send**) and muffling through doors (**Use Propagation**), so this setup is the groundwork for both.

### Example

Occlusion needs no code. This turret posts its shot as usual, and shows how many of the Weapons bus's slots are in use, to help you size **Slots Per Bus**.

```csharp
using UnityEngine;
using UnityEngine.Audio;
using AudioSystem;

public class Turret : MonoBehaviour
{
    [SerializeField] private AudioEvent fireEvent;        // its container has Use Occlusion ticked
    [SerializeField] private AudioMixerGroup weaponsBus;  // the Mixer Group that container plays through

    public void Fire()
    {
        // Nothing occlusion-specific: if a wall is in the way, the shot comes out muffled.
        fireEvent.Post(gameObject, transform.position);
    }

    void OnGUI()
    {
        var manager = AudioManager.Instance;
        if (manager == null || !manager.OcclusionSlotPoolsReady)
        {
            GUILayout.Label("Occlusion slots aren't set up");
            return;
        }
        int used = manager.GetOcclusionSlotsInUse(weaponsBus);
        int total = manager.GetOcclusionSlotCapacity(weaponsBus);   // -1 if the bus isn't in the layout
        GUILayout.Label($"Weapons occlusion slots: {used} / {total}");
    }
}
```

### Setting it up

1. In your container, under **Mixer Settings**, set a **Mixer Group** and tick **Use Occlusion**. Under **3D Settings**, tick **Is 3D**.
2. **Create > Audio System > Occlusion Layout**. One per project.
3. Open **Window > Audio System > Occlusion Layout** (or **Open Occlusion Layout Builder** on the Audio Manager). Assign your **Voice Mixer** and the layout asset, leave **Slots Per Bus** at 6 (8 to 12 for weapon-heavy scenes) and click **Scan, Auto-Create, Refresh**. Under each bus your occluded containers use, it builds a `<Bus>_OcclusionLayer` group holding `<Bus>_Slot_00`, `<Bus>_Slot_01` and so on.
4. On the Audio Manager, assign the same **Voice Mixer** and **Occlusion Layout**.
5. Press Play. The Console reports "Occlusion slot pools ready" with the number of buses and slots.
6. Tune **Occlusion Ray Count**, **Occlusion Ray Spread Meters**, **Occlusion Update Interval** and **Occlusion Mask** on the Audio Manager.

Run step 3 again when an occluded container plays through a bus that isn't in the layout yet.

### Good to know

- **Web builds:** sounds get quieter behind walls but aren't muffled, because Unity's Web audio has no mixer effects.
- **Automatic mixer setup** has only been tested on Unity 6000.0.48f1. If it fails on a newer version, click **Diagnose Reflection** in the window and send us the Console output.
- **No slot, no filter.** A voice that gets no slot still gets quieter behind walls but isn't filtered. If the bus's pool ran out, the Console warns; raise Slots Per Bus and run the window again. A bus missing from the layout gives no warning. Occluded, reverb-sending and propagation voices share the same slots.
- In a Blend or Switch Container, each child's own Use Occlusion applies, not the parent's.
- **Mobile:** raycasts cost more on phones. If the Profiler shows it, raise Occlusion Update Interval or lower Occlusion Ray Count.
- It isn't a diffraction model. Sound doesn't bend round corners; the fan of rays only softens edges.

## Ambient propagation

Source: https://peppersfx.com/features/ambient-propagation/

Rain outside a house shouldn't sound the same in the hallway as on the porch. Indoors you hear it through the open window, quieter, duller and from the window's direction; shut the door to that room and it fades further. Pepper.SFX models this with zones and portals, and routes long-running ambient loops through them.

### How it works

- An **Audio Zone** is a room: a GameObject with one or more trigger BoxColliders. An L-shaped room is one zone with two boxes.
- An **Audio Portal** is an opening between two zones: a doorway, a window, a vent. It sets how much gets through open (**Base Transmission**, **Open Low Pass Hz**) and closed (**Closed Transmission**, **Closed Low Pass Hz**).
- A portal can follow a door. Any MonoBehaviour that implements `IPortalDoorSource` (an `OpenProgress` from 0 to 1 and an `OnChanged` event) drives it, so Pepper doesn't need to know how your doors work. Half open gives values halfway between.
- An **Ambient Source** declares a looping clip in a zone. The **Propagation Manager** finds the best path from that zone to the listener's, adding up the loss at each portal and keeping the lowest cutoff, and plays the loop from a pooled emitter at the portal you hear it through. Walk along the wall and the rain slides along the window.
- In a doorway you hear a blend of both sides, so there's no snap at the threshold.
- The manager creates itself in Play mode, solves 15 times a second (**Solve Rate Hz**) and smooths volume, cutoff and position every frame.
- One-shot sounds can use the same rooms: tick **Use Propagation** on a container and a knock behind a closed door is muffled through the portals. This needs the occlusion slots.

### Example

A door that swings open and shut and tells its portal as it moves.

```csharp
using System;
using UnityEngine;
using AudioSystem.Propagation;

public class AudioDoor : MonoBehaviour, IPortalDoorSource
{
    [SerializeField] private float swingSeconds = 0.8f;
    [SerializeField] private float openAngle = 90f;

    private float progress;   // 0 = closed, 1 = open
    private bool wantOpen;

    public float OpenProgress => progress;
    public event Action OnChanged;

    public void Open()  => wantOpen = true;
    public void Close() => wantOpen = false;

    void Update()
    {
        float target = wantOpen ? 1f : 0f;
        if (Mathf.Approximately(progress, target)) return;

        progress = Mathf.MoveTowards(progress, target, Time.deltaTime / swingSeconds);
        transform.localRotation = Quaternion.Euler(0f, progress * openAngle, 0f);
        OnChanged?.Invoke();   // the portal re-solves now, not on the next tick
    }
}
```

Without `OnChanged`, the portal still picks up the change on the next solve, up to about 67 ms later.

### Setting it up

1. For each room, make a GameObject and add **Audio > Propagation > Audio Zone**. It adds a trigger BoxCollider; size it to the room. For the outdoors, set **Activation Radius** to Infinity so it's never culled.
2. At each opening, add **Audio > Propagation > Audio Portal** to a GameObject. Size its box to span the opening and overlap both rooms' boxes by at least 5 cm. Set **Zone A** and **Zone B** (or tick **Auto Detect Zones**), and point the object's +Z through the opening.
3. For a door, drag a component that implements `IPortalDoorSource` into the field under the portal's **Door Source** heading. Leave it empty for openings that are always open.
4. Add **Audio > Propagation > Ambient Source** to an object in the zone the sound comes from. Set **Source Zone**, **Looping Clip** and **Ambience Mixer Group**.
5. Add **Audio > Propagation > Audio Listener Zone Tracker** to the player object that has the Collider, not to the camera with the AudioListener.
6. Press Play and walk through. Select the Propagation Manager in the Hierarchy to see the listener's zone and the active emitters.

### Good to know

- **Web builds:** beds still route through zones, portals and doors, but aren't muffled and get no reverb: the emitters use Unity's Low Pass and Reverb filter components, which Web audio doesn't support.
- Ambient emitters sit outside Pepper's voice pool, capped by **Max Ambient Emitters** (16); past the cap, the farthest goes silent.
- A source is heard through its single best path unless you raise **Max Paths Per Source** (up to 6), at one emitter per path.
- Clutter inside a room doesn't block ambient beds unless you tick **Enable Obstruction** on the Propagation Manager.
- Beds take on the reverb of the room you're in, from that zone's Reverb Send Bus.
- A bad loop point in the clip clicks every time round. Sound doesn't bend round corners, so split large open spaces into more zones.

## Reverb

Source: https://peppersfx.com/features/reverb/

A gunshot in a tiled bathroom should ring like a bathroom, even when you hear it from the hallway. One global reverb makes every room sound alike; a reverb that follows the listener makes that shot sound like the hallway. Pepper.SFX splits the two: a sound sends to the reverb of the room it's played in, and each room's reverb keeps its own character wherever you stand.

### How it works

- A **Reverb Send Bus** asset is one acoustic space: a small room, a hall, a cave. It owns a mixer group with a reverb on it and holds the character: **Room**, **Decay Time**, **Reverb Level** and Unity's other SFX Reverb settings, or an impulse response.
- An **Audio Zone** (from ambient propagation) routes: its **Reverb Bus** field says which bus the sounds inside it send to. Zones can share a bus; for two rooms that sound different, use two bus assets.
- A container opts in with **Allow Reverb Send** and sets **Reverb Send Level Db**: around 0 dB for a gunshot, nearer −12 dB for footsteps. The send is full when you're in the same room, lower through an open door, lower again through a closed one, and right from the first frame.
- **Explicit Reverb Bus** ties a sound to one bus wherever it plays: a choir that always sounds like a cathedral, or a narrator.
- Ambient beds take the reverb of the room you're standing in, through a Reverb filter on each ambient emitter. Its six values (an `AudioReverbProfile`) come from that zone's bus asset and crossfade through doorways.

**Convolution reverb.** Tick **Use Convolution** on a bus and it convolves the send with a real impulse response, a recording of an actual space, instead of using Unity's parametric SFX Reverb. It runs in a native plugin built for 64-bit Windows only.

### Example

A probe for checking your setup: which bus a spot sends to, and how long it rings.

```csharp
using UnityEngine;
using AudioSystem;
using AudioSystem.Propagation;

public class ReverbProbe : MonoBehaviour
{
    private readonly AudioReverbProfile character = new AudioReverbProfile();

    [ContextMenu("Which reverb is here?")]
    void Report()
    {
        var registry = AudioManager.Instance != null ? AudioManager.Instance.ReverbSendBusRegistry : null;
        var zone = PropagationManager.HasInstance
            ? PropagationManager.Instance.GetZoneContainingPoint(transform.position) : null;
        if (registry == null || zone == null || zone.ReverbBus == null) { Debug.Log("No reverb zone here"); return; }

        ReverbSendBus bus = registry.FindByReverbBus(zone.ReverbBus);
        if (bus == null) { Debug.Log($"{zone.name}'s bus isn't in the registry"); return; }
        if (bus.UseConvolution) { Debug.Log($"{zone.name} sends to {bus.name} (convolution)"); return; }

        bus.GetDefaultProfile(character);   // the six values Pepper writes to the mixer
        Debug.Log($"{zone.name} sends to {bus.name}: decay {character.DecayTime:0.0} s");
    }
}
```

In Play mode, run it from the component's menu in the Inspector.

### Setting it up

Set up occlusion first: reverb sends use the same slots.

1. **Create > Audio System > Reverb Send Bus**, named after the room (`Reverb_Bathroom`). Assign **Reverb Mixer** (your voice mixer) and set **Decay Time** and **Room**.
2. In its Inspector, click **Generate Mixer Group**, then **Validate Wiring**, which should say "Wiring OK."
3. **Create > Audio System > Reverb Send Bus Registry** and assign it to the Audio Manager's **Reverb Send Bus Registry**. In **Window > Audio System > Reverb Send Buses**, click **Refresh** to fill it.
4. In **Window > Audio System > Occlusion Layout**, assign the registry and click **Scan, Auto-Create, Refresh** so every slot gets a Send to each bus. Repeat after adding a bus.
5. On each Audio Zone, drag the bus asset's **Reverb Bus** mixer group into the zone's **Reverb Bus** field.
6. On each container, tick **Allow Reverb Send**, set its level, and tick **Static Emitter** if the sound doesn't move.

For convolution, tick **Use Convolution**, assign an **Impulse Response** clip with Load Type set to Decompress On Load or PCM, and generate again. To tune by ear, **Apply Params → Mixer** pushes the asset's values to the mixer and **Pull Params ← Mixer** reads them back.

### Good to know

- **Convolution is 64-bit Windows only:** the Windows editor and Windows x64 players. Everywhere else, including macOS, Linux, mobile and consoles, a convolution bus is silent and Unity may log an error at startup. Unless you only ship on 64-bit Windows, use parametric buses.
- **Web builds have no reverb at all**, parametric or convolution: Unity's Web audio has no mixer effects or sends.
- Convolution in this version: the impulse response is fixed once loaded, a stereo one is mixed to mono, and ambient beds use the bus's parametric values instead.
- A container's bus needs slots in the Occlusion Layout, and the layout window only builds them for a bus with at least one **Use Occlusion** container.
- **Automatic mixer setup** has only been tested on Unity 6000.0.48f1.

## Multi-position audio

Source: https://peppersfx.com/features/multi-position-audio/

A river isn't one point. Nor is a row of torches down a corridor, or the speakers round a dance floor. A separate sound at every spot costs a voice each, and identical loops playing side by side comb-filter into a hollow, phasey mess. Pepper.SFX plays one event from many positions with one call, `PostMultiPosition`, and lets you choose how those positions are voiced.

### How it works

Any event can be posted at several positions; there's nothing to switch on in the event. Pepper uses up to 16 positions. You pass either an array of positions or transforms, or an **Audio Multi-Position Emitter Parent**: a component whose children, each with an **Audio Multi-Position Emitter Child**, mark the points. The parent's **Multi Position Type** (the `MultiPositionType` enum) has two values:

- **SingleEmitter** (the default): one voice, placed at the point nearest the listener. As you move, it glides to the new nearest point (**Position Lerp Time**). With **Use Spread Curve**, it gets less directional when you stand among the points, down to **Min Spatial Blend**. One voice covers the whole river. Best for sound you don't hear as separate points: rivers, wind, rain across a courtyard.
- **Decorrelated**: a voice at every active point. Each starts at a random place in the loop (up to **Max Random Offset**, 2 s by default) and is nudged in pitch by a few cents (**Max Pitch Variation Cents**, 3 by default), so the copies don't line up and comb-filter. Best for sources you can see: torches, speakers, machines.

Posting with a `Vector3[]` or `Transform[]` array plays a third way, synchronised: every copy starts on the same audio sample, scheduled 100 ms ahead. Use it when the copies must stay in step, such as a stadium announcer over a PA.

`PostMultiPosition` returns an `AudioMultiHandle`. It stops, pauses or changes the volume and pitch of every copy at once, or of one emitter by its index (`SetVoiceVolumeScale`, `StopVoice` and the others). The index is the point's place in the array, or among the parent's active children when you posted.

### Example

```csharp
using UnityEngine;
using AudioSystem;

public class CourtyardAmbience : MonoBehaviour
{
    [SerializeField] private AudioEvent riverLoop;                      // a looping 3D event
    [SerializeField] private AudioMultiPositionEmitterParent riverBank; // Multi Position Type: SingleEmitter
    [SerializeField] private AudioEvent torchLoop;
    [SerializeField] private AudioMultiPositionEmitterParent torches;   // Multi Position Type: Decorrelated

    private AudioMultiHandle river;
    private AudioMultiHandle flames;

    void Start()
    {
        river  = riverLoop.PostMultiPosition(riverBank);  // one voice that follows the nearest point
        flames = torchLoop.PostMultiPosition(torches);    // a voice per torch, offset in time and pitch
    }

    // The index is the torch's place among the parent's active children when it was posted.
    public void DouseTorch(int index) => flames?.StopVoice(index, 0.5f);

    void OnDestroy()
    {
        river?.Stop(2f);
        flames?.Stop(1f);
    }
}
```

The river plays as one voice that follows you along the bank; each torch crackles on its own voice, out of step with the others, and `DouseTorch` fades one of them out.

### Setting it up

1. Make a container with **Is 3D** and **Loop** ticked (a Random or Routing Container), and an event that plays it.
2. Make an empty GameObject and choose **Add Component > SFX System > Audio Multi-Position Emitter Parent**.
3. Add child GameObjects with **Audio Multi-Position Emitter Child** at each point, or use the parent component's menu: **Create 8 Child Emitters (Circle Pattern)** or **Create 4 Child Emitters (Square Pattern)**. Each child has **Is Active** and **Volume Multiplier**.
4. On the parent, set **Multi Position Type** and **Max Emitters** (1 to 16), then tune the SingleEmitter or Decorrelated settings for that mode.
5. From a script, call `PostMultiPosition` with the parent.

### Good to know

- **Decorrelated playback may click on sharp sounds** such as gunshots. It's meant for loops.
- Voice cost: SingleEmitter plays one copy however many points there are. Decorrelated and synchronised play one copy per point, and each counts towards **Max Real Voices**.
- The event's **Max Instances** is multiplied by the number of positions, and its cooldown is checked once per post.
- Pass a source GameObject as the second argument and each 3D copy plays at its own position, attached to the source, so they all move with it.
- SingleEmitter follows points that move. In the other modes, call `RefreshPositions` on the handle each frame to follow moving transforms.
- A point that isn't active when you post isn't played.

## Voices and performance

Source: https://peppersfx.com/features/voices-and-performance/

A busy scene can ask for more sounds than the hardware can play: a dozen cars, rain, gunfire and the UI at once. Pepper.SFX plays everything from a fixed pool of voices, ranks each sound by how much it matters, and keeps the important ones audible without clicks or engines losing a layer.

### How it works

- **A fixed pool.** The Audio Manager builds its AudioSources once, at start: Max Real Voices + Max Virtual Voices + Steal Headroom (32 + 64 + 4 by default).
- **Importance** is how loud a sound is where it is heard, times its event's Priority weight: Low 1/8, Medium 1/4, High 1/2, Critical 1. A loud Low sound beside you can outrank a faint Medium one far away.
- **Virtual voices.** Over Max Real Voices, the least important sounds go virtual: silent, using no real voice, but still counting their place in the clip at their pitch. When there is room they come back exactly where they would have been, faded in over about 25 ms. A whole sound goes virtual at once, so an engine's layers stay together.
- **Stealing ends whole sounds.** When the pool is full, a new sound makes room by ending whole sounds, silent virtual ones first, then the least important: every layer of a Blend together, never one layer. If there still isn't room, the new sound is skipped with a warning.
- **Persistent events are never stolen.** Tick Persistent on an engine's event. It can still go virtual. Critical is the strongest weight, not an exemption.
- **Steals fade.** A stolen sound fades out over Steal Fade Seconds (0.025 s, at least three frames) instead of clicking.
- **Per-bus caps.** A bus's Max Real Voices limits the real voices its sounds use, so other players' cars can't crowd out yours. Over the cap, sounds go virtual; it never ends one.
- **Dedicated servers.** With `AudioManager.Inert = true` set at boot, every post is silent and free: no voices, no allocation, no logging.

### Example

```csharp
using AudioSystem;
using UnityEngine;

public class VoiceBudgetReadout : MonoBehaviour
{
    [SerializeField] private AudioBus otherCarsBus;   // Max Real Voices set on the bus asset

    private void OnGUI()
    {
        if (AudioManager.Instance == null) return;
        var stats = AudioManager.Instance.GetStatistics();
        GUILayout.Label($"Real voices: {stats.activeVoices} / {stats.realVoiceBudget}");
        GUILayout.Label($"Free in the pool: {stats.availableVoices} of {stats.poolSize}");
        GUILayout.Label($"Other cars: {otherCarsBus.RealVoiceCount} / {otherCarsBus.MaxRealVoices}");
    }

#if UNITY_SERVER
    // A dedicated server build plays nothing and builds no voices.
    [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
    private static void SilenceServer() => AudioManager.Inert = true;
#endif
}
```

The readout shows real voices against the budget, free voices in the pool and a capped bus's live count. In a dedicated server build, Pepper goes inert before the first scene loads.

### Setting it up

1. Select the Audio Manager and set **Max Real Voices** and **Max Virtual Voices**. The guide suggests 32–64 real voices on desktop, 16–24 on mobile.
2. On each Audio Event, set **Priority**, and tick **Persistent** on events that must never drop out.
3. On a bus that groups many similar sounds, set **Max Real Voices** in its Voices section (0 = no cap).
4. In Play mode, open **Window > Audio System > Voice Pool Debug** for the real and virtual voices, or **Window > Audio System > Live View** to see why a voice is virtual.

### Good to know

- If a very large number of sounds start in the same frame, some can be skipped when the pool can't free voices fast enough. Raise Steal Headroom if it happens often.
- If a full pool holds only persistent sounds, a new sound is skipped. Raise Max Virtual Voices: 8 cars of 14 layers need 112 voices.
- A virtual voice can't follow Unity's own Doppler. On engine layers that must come back in step, set Doppler to Pepper or Doppler Level to 0.
- Pepper warns at startup if its voice counts exceed Unity's (Project Settings > Audio).
- Pepper doesn't detect a server by itself, and `Inert` can't change while an Audio Manager runs: your boot code decides.

## Spatial audio and listeners

Source: https://peppersfx.com/features/spatial-audio-and-listeners/

A car's engine should fade, dull and narrow as it drives away, come from its exhaust rather than its centre, and still sound right when two players share one screen. Pepper.SFX gives you shared distance assets, listening points you register yourself, and its own panning and Doppler for what one AudioListener can't do.

### How it works

- **Attenuation assets.** Curves over metres, shared between sounds: Volume in dB, and optional Low Pass, High Pass and Spread. Set in a container's 3D Settings, one replaces its Min Distance, Max Distance and Rolloff. Past Max Distance a sound goes virtual (silent, keeping its place). `handle.SetAttenuation` gives one sound a different asset.
- **Listening points.** `AddListeningPoint(cameraTransform)` tells Pepper where you listen from, so it never searches the scene. Voice importance, occlusion, Doppler and the Distance, Approach Speed and Angle values all read the points. `DriveUnityListener` keeps Unity's AudioListener on the primary one.
- **Split screen: Spatial Mode = Pepper.** Pepper then pans and attenuates 3D sounds itself, from every point. A sound's level is the loudest of its attenuation at each point times that point's Weight (0–1); its pan blends the points, narrowed by each one's Pan Width (0 = mono). At one point of Weight 1 and Pan Width 1 it sounds the same as Unity's 3D. `SetPrimaryListeningPoint` picks the primary point, and changes glide over about 100 ms.
- **Pepper's Doppler.** Set a container's Doppler to Pepper and pitch follows the closing speed on the listening point, scaled by Doppler Exaggeration (×1 to ×3) and capped by Doppler Max Cents. Virtual voices come back in step with it. `AudioEmitter.Teleport()` and `AudioListeningPoint.ClearVelocity()` stop a respawn or camera cut reading as speed.
- **Named points and offsets.** An Audio Emitter lists named Points (Exhaust, Intake, RearAxle). `car.Post(exhaustEvent, "Exhaust")` attaches the sound there. `car.Post(impactEvent, localOffset)` plays anywhere on the object with the emitter's values, and `handle.SetLocalOffset` moves a playing sound, such as a scrape following the contact.

### Example

```csharp
using AudioSystem;
using UnityEngine;

public class SplitScreenCar : MonoBehaviour
{
    [SerializeField] private Transform player1Camera;
    [SerializeField] private Transform player2Camera;
    [SerializeField] private AudioEmitter car;
    [SerializeField] private AudioEvent exhaustEvent;
    [SerializeField] private AudioEvent impactEvent;

    private void Start()
    {
        var manager = AudioManager.Instance;
        manager.SpatialMode = AudioSpatialMode.Pepper;   // before the sounds start

        AudioListeningPoint p1 = manager.AddListeningPoint(player1Camera);
        AudioListeningPoint p2 = manager.AddListeningPoint(player2Camera);
        p1.PanWidth = 0f;   // top and bottom halves: no left and right
        p2.PanWidth = 0f;

        car.Post(exhaustEvent, "Exhaust");   // attached at the car's Exhaust point
    }

    private void OnCollisionEnter(Collision hit)
    {
        Vector3 local = car.transform.InverseTransformPoint(hit.GetContact(0).point);
        car.Post(impactEvent, local);        // at the contact, with the car's values
    }
}
```

Both cameras become listening points, so a car near either player sounds near. The exhaust rides on the car's Exhaust point, and each impact plays where the car was hit.

### Setting it up

1. **Create > Audio System > Attenuation**, shape its curves and set Max Distance.
2. In a container's **3D Settings**, assign the asset and set **Doppler** to Pepper if wanted.
3. **Add Component > Audio System > Audio Emitter** on the moving object. Add Points and drag them in the Scene view.
4. For split screen, set the Audio Manager's **Spatial Mode** to Pepper.
5. Register listening points from code at start. In Play mode the Audio Manager inspector lists them.

### Good to know

- Spatial Mode = Pepper has no spatializer plugins (HRTF) and ignores the project's Doppler Factor. It balances a stereo clip rather than placing it, so give 3D sounds mono clips.
- Unity's own AudioSources, such as the ambient system's, still hear from the AudioListener: keep it on the primary point with `DriveUnityListener`.
- Changing Spatial Mode affects sounds started after the change.
- With no listening point registered, Pepper searches for an AudioListener and warns once.
- With Spatial Mode = Unity, Attenuation curves are handed to Unity when a sound starts, so Play-mode edits reach a playing sound only when it is posted again.

## Vehicle engines

Source: https://peppersfx.com/features/vehicle-engines/

The engine is the sound a racing game plays most. It has to follow the RPM without steps or warble, change on and off the throttle, and every car on the track needs its own. Pepper.SFX builds an engine from loops recorded at known RPMs, keeps them in tune with each other at every RPM, and lets each car drive its own copy.

### How it works

An engine is a **Blend Container** whose layers are your loops.

- **Regions.** Give each layer its **Root Value** (the RPM it was recorded at) and press **Auto Layout**. Each loop plays in its own band of RPM and crossfades with its neighbours at equal power.
- **Pitch Follow.** Each layer plays at RPM ÷ its Root Value: a loop recorded at 4000 RPM plays 1.25 times faster at 5000. The layers stay in tune with each other.
- **A Parameter asset for RPM** with **Smoothing** (separate rise and fall), the same at any frame rate. Your code writes the raw value; the engine hears the smoothed one.
- **One engine per car.** Each car posts its engine on its own **Audio Emitter** and sets RPM and load there. Ten cars share one engine asset.
- **On load and off load.** A Blend on load crossfades an on-load set of loops with an off-load set.
- **Silent Layers = Virtualize.** A layer below −60 dB (the default threshold) gives up its real voice, keeps its place in the clip and comes back in step. An engine of 14 loops with 2–4 heard at a time uses 2–4 real voices.
- **Persistent events** are never stolen to make room for other sounds.

Two windows do the setup:

- **Engine Builder** (full version) reads each selected loop's set and RPM from its name (`Eng_OffLoad_2510`) and builds the whole tree: a looping container per loop, on-load and off-load Regions Blends with Pitch Follow and Virtualize, a load Blend over them, and one Persistent event. It never overwrites an asset.
- **Loop Analysis** (Window > Audio System > Loop Analysis) measures each loop's root pitch and the RPM it means, whether it clicks at the loop point, the level jump across it, and its loudness in LUFS. **Seam ▶** plays the join on its own. It reads **Decompress On Load** clips only.

### Example

```csharp
using AudioSystem;
using UnityEngine;

[RequireComponent(typeof(AudioEmitter))]
public class CarEngineAudio : MonoBehaviour
{
    [SerializeField] private AudioEvent engineEvent;  // the Persistent event the Engine Builder made
    [SerializeField] private AudioParameter rpm;      // EngineRpm, 0–9000, with Smoothing
    [SerializeField] private AudioParameter load;     // EngineLoad01, 0–1

    public float engineRpm = 900f;  // written by your drivetrain
    public float throttle;          // 0–1
    private AudioEmitter emitter;
    private AudioHandle engine;

    void Start()
    {
        emitter = GetComponent<AudioEmitter>();
        engine = emitter.Post(engineEvent);  // reads this car's values
    }

    void Update()
    {
        emitter.SetParameter(rpm, engineRpm);  // raw: Smoothing eases it
        emitter.SetParameter(load, throttle);
    }

    public void OnCarReset() => emitter.SnapAllParameters();  // no glide after a teleport
    public void StopEngine() => engine?.Stop(0.5f);
}
```

### Setting it up

1. Import your loops with the RPM in each file name.
2. Open **Window > Audio System > Engine Builder** (full version), select the loops and press **Use Selection**. In the free version, build the same Blends by hand as the cookbook's engine recipe describes.
3. Check each row's set and RPM, or press **Detect** to measure it.
4. Pick the RPM and Load parameters, or leave them empty to have EngineRpm and EngineLoad01 made. Pick the **Target Bus** and press **Build**.
5. Open **Window > Audio System > Audition**, select the new event, press **Play** and add a sweep on RPM. Tune regions and Root Values by ear.
6. Add an **Audio Emitter** to the car, set **On Disable** to Stop, and add a script like the one above.

### Generated engines (full version, experimental, Unity 6000.3 or later)

The **Granular Engine** plays an engine from sweeps instead of loops. **Window > Audio System > Engine Grains** cuts an on-load and an off-load sweep into a **Grain Table**: one grain per engine cycle, tagged with its RPM and cut to join in phase. A fast rev passes through every RPM with no band crossfade, and your code doesn't change. The **Additive Engine** adds the engine's firing orders as sine tones under another engine, for weight.

Both use Unity 6.3's audio generators. They are new: not yet measured on a Steam Deck (about 0.4% of a CPU core each on a desktop PC), and they hear the RPM about 25–75 ms late. They are in the full version only, like the Engine Builder. Everything else on this page, Loop Analysis included, is in both.

### Good to know

- A virtual layer fades back in over at least three frames. If an off-load set must answer a fast rev-limiter cut, set that Blend's Silent Layers to **Keep Playing**.
- Engine layers that go virtual need **Doppler Level 0** or Pepper's own Doppler to come back in step. The Engine Builder sets 0.
- With loops from one set only there is no load Blend, so the engine sounds the same on and off the throttle.

## Multiplayer

Source: https://peppersfx.com/features/multiplayer/ (full version only)

A door one player opens should be heard by everyone, a footstep should pick the same variation on every machine, and an alarm already sounding should reach whoever joins later. Pepper.SFX's netcode layer sends a short description of each sound, never the audio, and every machine plays it through its own Audio Manager.

### How it works

- **A core that needs no netcode package.** `SFXSystem.Netcode` references only Pepper's runtime. A small adapter per networking package (`FishNetAudioTransport`, `NgoAudioTransport`) is the only code that touches it, and compiles only when that package is installed.
- **Intent, not audio.** A post sends about 36 bytes: the event, the position, an object to follow and a random seed. Each machine plays it locally, so occlusion, reverb and voice management work as in single player.
- **Local echo.** `PostNetworkedEvent` plays at once for the player who caused it; the server relays it to the others. With no session it is a plain local post.
- **Stable event IDs.** Each Audio Event has a Stable ID worked out from its asset GUID, so every machine resolves it to the same event.
- **Seed parity.** By default a networked post makes the same random picks everywhere: the clip, the pitch and volume randomisation, a Sequence's later clips. Pass `independentVariation: true` for sounds such as a crowd.
- **Late join.** `PostNetworkedLoop` returns a handle, and `StopNetworked` stops the loop everywhere. The server replays running loops to a player who joins later. The event's Loop Sync Tier sets the joiner's phase: 0 from the start, 1 aligned at join, 2 phase-locked (experimental).
- **Server-authored sounds.** `PostServerEvent` and `PostServerLoop` for sounds the server decides, such as a round start.
- **Proximity culling.** With culling on, the server sends a 3D sound only to clients within its audible range, which also closes an audio wallhack. 2D sounds are never culled.
- **Leaving it out.** The `SFXSYSTEM_DISABLE_NETCODE` define leaves every multiplayer assembly out of your build.

### Example

```csharp
using AudioSystem;
using AudioSystem.Netcode;
using UnityEngine;

// On a door that has a NetworkObject.
public class DoorAudio : MonoBehaviour
{
    private NetworkedSoundHandle alarm;

    public void Open()
    {
        // Plays here now; the server relays it to the other players, attached to this door.
        NetworkedAudioManager.PostNetworkedEvent("door_open", transform.position, gameObject);
    }

    public void StartAlarm()
    {
        // A shared loop: players who join later hear it too.
        alarm = NetworkedAudioManager.PostNetworkedLoop("alarm_loop", transform.position, gameObject);
    }

    public void StopAlarm()
    {
        NetworkedAudioManager.StopNetworked(alarm);   // stops it on every machine
        alarm = null;
    }
}
```

The door sound plays at once for the player who opened it and follows the door on the other machines. Passing the alarm's handle to `StopNetworked` ends the loop for everyone.

### Setting it up

1. Install one networking package: FishNet v4 or Netcode for GameObjects 2.x. The matching adapter compiles by itself.
2. Open **Window > Audio System > Audio Event IDs** and click **Capture All Missing IDs**.
3. Make one persistent networked GameObject with a NetworkObject and `FishNetAudioTransport` or `NgoAudioTransport`: one per session, active in the scene, not on player objects.
4. Optionally add a `NetworkAudioSettings` component for proximity culling, and assign its `ListenerPositionProvider` from code.
5. Set Unreliable Delivery, Independent Variation and Loop Sync Tier in each Audio Event's **Multiplayer** foldout.
6. In Play mode, **Window > Audio System > Network Audio Debug** shows the session, clock and loops.

### Good to know

- **Support:** FishNet v4 is the tested backend, on one PC and on two over a real network. Netcode for GameObjects 2.x compiles but is only lightly tested. NGO 1.x and FishNet v3 cause compile errors. Mirror is not supported.
- Loop Sync Tier 2 is experimental: a late joiner may hear the loop out of sync for a cycle or two before it locks in.
- Proximity culling can use the wrong range for events that play a Switch or Blend container, so a nearby player might miss the sound.
- RTPCs, switches, states and ducking aren't replicated; each client's game logic drives them.
- Built for co-op and competitive sessions of up to tens of players.
- On a dedicated server, set `AudioManager.Inert = true` at boot so it plays nothing but can still relay.

## Addressables loading

Source: https://peppersfx.com/features/addressables-loading/ (full version only)

In a large game, keeping every zone's audio in memory wastes RAM on sounds the player can't hear. Pepper.SFX can load a zone's clips through Unity's Addressables when the listener walks in and release them when it leaves, without unloading a clip a voice is still playing.

### How it works

- **The clip-source layer.** Containers ask the active clip source for each clip. By default it returns the clip you assigned; the Addressables backend swaps in one that loads by address. Each entry holds a direct clip or an address, never both. Random, Sequence and Routing container entries and Ambient Source loops can be addressable.
- **The warmer.** `WarmContainer`, `WarmClip` and `WarmClips` on the Audio Manager load the audio data of directly referenced clips before their first play, so it doesn't hitch. No extra package needed.
- **Banks per zone.** A bank is an Addressables label, named by a Zone Audio Bank component on an Audio Zone. The bank preloads when the listener enters and is released after a linger (5 s by default) when it leaves, so a border doesn't cause churn.
- **Nothing unloads under a playing voice.** A clip stays loaded while a bank, a playing voice or a pin holds it. A loop started in one zone plays on in the next, keeping only its own clip loaded.
- **Zones really unload.** Proved in a Windows player build with three zones: standing in one held 7.4–11.3 MB of audio against 26.1 MB for all three, 57–72% less.
- **Addressable Audio Authoring window.** Select containers, pick a Bank Label and Address Style, and click Convert to Addressable. Each bank gets its own group with one bundle per clip; Revert to Direct undoes it. The Groups tab marks clips used or unused, adds clips that aren't in a container, and removes unused ones.
- **Loading Validator window.** Flags an address with no backend, a mistyped address, or an entry with both a clip and an address, even without Addressables installed.

### Example

```csharp
using AudioSystem;
using AudioSystem.Propagation;
using UnityEngine;

public class LevelAudioLoading : MonoBehaviour
{
    [SerializeField] private AudioContainer bossMusic;   // direct clips, not addressable

    // Before the boss fight: load the music's audio data so its first play doesn't hitch.
    public void OnBossDoorOpened()
    {
        AudioManager.Instance.WarmContainer(bossMusic);
    }

    // After moving the player in one jump (a respawn or fast travel):
    // the zones left behind release their banks, and the zones landed in load theirs.
    public void OnPlayerTeleported()
    {
        if (PropagationManager.HasInstance)
            PropagationManager.Instance.ResyncListenerAfterTeleport();
    }
}
```

Zone banks need no code. The example shows the two jobs that do: a jump in position, and warming direct clips.

### Setting it up

1. Install **Addressables** (`com.unity.addressables`) from the Package Manager. Pepper's backend compiles by itself.
2. Select a zone's containers, open **Window > Audio System > Addressable Audio Authoring**, set a **Bank Label**, leave Group on **Bank's own group**, and click **Convert to Addressable**.
3. On the Audio Zone's GameObject, **Add Component > Audio > Loading > Zone Audio Bank**, with the same Bank Label.
4. In your first scene, **Add Component > Audio > Loading > Addressable Audio Runtime**. One is enough; it persists across scene loads.
5. Run **Window > Audio System > Loading Validator** and click **Validate**.
6. Check memory in a Development Build with Unity's Memory Profiler.

### Good to know

- The clip-source layer and the warmer are in every version. The Addressables backend, the Addressable Audio Authoring window and the Loading Validator are full version only.
- One group for every zone saves no memory: Unity unloads a bundle only as a whole. The Groups tab flags such a group and offers Pack Each Clip Separately.
- A clip that isn't loaded yet is skipped, not played late. Keep a zone's bank loaded before its sounds are needed.
- With the editor's default Play Mode Script (Use Asset Database), clips never really unload: measure in a player build.
- A group left out of builds plays in the editor but not in a build. The Groups tab's Include in Builds button fixes it.
- Banks follow Audio Zones, one label per zone. Events and containers still load up front; only clips load on demand.

## Music and timing

Source: https://peppersfx.com/features/music-and-timing/

Game music needs an intro that runs into a loop, a clean change of track when combat starts, and hits that land on the beat. Pepper.SFX has no separate music engine: it does these with the same events and containers as every other sound, plus a few timing tools.

### How it works

- **Intro and loop.** Either give an event two Play actions, with the loop's Delay set to the intro's length, or use a **Sequence Container** with an intro entry and a looping entry and Auto Advance on: it plays the intro once, then stays on the loop. Stop it with a fade on the handle `Post` returns.
- **Handle crossfade.** `AudioManager.Instance.CrossFade(handle, nextEvent, 2f)` fades out everything that handle plays, cancels what it was still going to start (the loop waiting behind an intro), posts the next event, fades it in and returns its handle, on an Equal Power curve by default.
- **CrossFade action.** An event's CrossFade action fades its Fade From Container out while its Container fades in, over its Fade Duration, through its Target Bus.
- **Timed posts.** `Post(source, position, dspTime)` starts a sound on an exact `AudioSettings.dspTime`. `Post(emitter, startDsp, startOffsetSeconds)` makes a chosen moment inside the sound land on that time: a whoosh peaking on a pass-by.
- **Lengths.** `evt.EstimateDuration()` returns an `AudioDuration` (Shortest, Longest, Loops, IsKnown) before you post.
- **BeatScheduler.** A component that posts a one-shot event every `60 / Bpm` seconds, each beat on its DSP grid time. Changing `Bpm` at runtime changes the tempo, not the pitch: heartbeats, metronomes, sonar pings. `OnBeat` fires on the main thread for game logic.

### Example

```csharp
using UnityEngine;
using AudioSystem;

public class LevelMusic : MonoBehaviour
{
    [SerializeField] private AudioEvent explorationMusic;  // a loop at 120 BPM, whole bars long
    [SerializeField] private AudioEvent combatMusic;
    [SerializeField] private AudioEvent stinger;           // a short one-shot hit
    [SerializeField] private float bpm = 120f;

    private AudioHandle music;
    private double musicStart;

    void Start()
    {
        musicStart = AudioSettings.dspTime + 0.1;          // slightly ahead, to start exactly then
        music = explorationMusic.Post(gameObject, transform.position, musicStart);
    }

    public void PlayStingerOnNextBar()
    {
        double bar = 4 * 60.0 / bpm;
        double barsDone = System.Math.Ceiling((AudioSettings.dspTime - musicStart) / bar);
        stinger.Post(gameObject, transform.position, musicStart + barsDone * bar);
    }

    public void EnterCombat() => music = AudioManager.Instance.CrossFade(music, combatMusic, 2f);
}
```

Starting the track on a known DSP time lets a stinger land on its next bar, and entering combat swaps tracks with a two-second crossfade.

### Setting it up

1. Make a Routing Container with Loop ticked, or a Sequence Container for intro and loop, and an event that plays it through a Music bus.
2. Set Max Instances to 1 on music events.
3. For a designer-driven change, add a CrossFade action, or use **Window > Audio System > Sound Builder (Simple)**, which asks for the Fade From Container.
4. For beats, **Add Component > Audio > Beat Scheduler**, assign its Audio Event (a one-shot) and set Bpm.

### Good to know

- A delayed Play action and a Sequence's next clip start in Pepper's per-frame step, not on a DSP time, so the join can land up to about a frame late. For a sample-exact join, post the next part on a DSP time.
- Delays, Sequence gaps and crossfades run on the event's Time. Scaled (the default) slows with the time scale and stops at 0; Unscaled keeps them running in slow motion or a pause.
- Each Sequence Container asset keeps one position, shared by everyone playing it; duplicate it for independent sequences.
- A Stop action only reaches its own event's sounds, so stop music with its handle.
- A container crossfade, including the CrossFade action, fades only the voices playing then: a delayed loop or a Sequence's next clip still comes in. The action's handle finishes at once, so stop that music with `container.Stop()` (every play of that asset) or another crossfade.
- BeatScheduler posts at most once per frame and drops beats missed during a hitch (`OnBeat` still catches up). Two schedulers at the same Bpm aren't phase-aligned, and there are no bars or song structure.
- Full version only: a Networked Beat Scheduler puts every player's beats on one shared grid.

## Editor tools

Source: https://peppersfx.com/features/editor-tools/

Audio problems are hard to find by ear: a sound that never plays, a layer that should be silent, a voice that went quiet for no clear reason. Pepper.SFX comes with editor windows for building sounds, hearing them while you edit, seeing what plays while the game runs, and checking the project for mistakes.

### How it works

#### Building sounds

- **Sound Builder (Simple)** creates a bus, a container and an event in one step, with the references filled in. Its five modes are Complete Setup, Container Only, Event Only, Bus Only and Batch Import (one sound per clip), for all five container types.
- **Sound Builder (Advanced)** (full version only) has the same modes but shows every setting of the event, container and bus, with tooltips, before anything is written. It is brand new.
- **Audio Explorer** shows your events, containers and buses as three tabs over one searchable tree, with the selected asset's Inspector and a preview beside it.
- **Import Manager** applies import settings to clips in batches by category (UI, SFX, Music, Ambience, Dialogue). **Folder Rules** give clips first imported into a folder that folder's settings, so engine loops arrive mono and Decompress On Load. Existing clips keep theirs until you press **Apply to Existing Clips**.

#### Hearing and tuning

- **Audition** plays a container or an event outside Play mode. Every parameter the sound reads gets a slider in its own unit, passed through its Smoothing as in the game, and every switch gets a dropdown. **Add Sweep** moves a parameter across a range (Once, Repeat or Back And Forth), several at once. The **Layers** table shows each voice's level, pitch, low-pass and whether it is real or virtual. Inspector changes are heard straight away.
- **Live View** shows, in Play mode, every Audio Emitter: its values as written and as heard after smoothing, its switches, and each sound on it, with a row per voice for level, pitch and Blend region. A virtual voice says why: over the cap, silent layer, past Max Distance, held by code, bus or emitter paused, or stopping. **Record** captures what the game wrote to one emitter during a drive, and the Audition replays it, so you can tune a mix against a real lap.

#### Checking and debugging

- **Container Validator** checks every container and event: empty or null entries, zero weights, gaps in a Regions Blend, layers pitched too far, stereo clips on 3D layers, a Play action with no Target Bus, a looping event that isn't Persistent. **Fix** and **Auto-Fix All** can be undone.
- **Voice Pool Debug** lists real and virtual voices in Play mode, with a "Why virtual" column and a stop button per voice. It compares the pool's objects with its size; a number that keeps rising means voices are leaking.
- **Mixer** (full version only) shows strips for buses, containers and events, each with a fader, mute, solo, peak meter and a small spectrum. Bus fader, mute and solo changes can be undone and are saved with the project, in Play mode too.
- **Audio Profiler** (full version only) shows every voice with its priority, level and distance, every bus with fader, mute, solo, meter and ducking, and real voices against Max Real Voices.
- **EQ Spectrum Visualizer** (full version only) draws the spectrum of up to two sources at once: a clip, event, container, bus or Audio Mixer Group. Only clips play outside Play mode.
- **Loading Validator** (full version only) finds Addressables setups that would fail silently: an address with no backend or not registered, an entry with both a clip and an address, or addressable content in a scene with no AddressableAudioRuntime.

### Where to find them

Every window is under **Window > Audio System**:

- Sound Builder (Simple), also at Assets > Create > Audio System > Sound Builder (Simple)
- Sound Builder (Advanced), full version
- Audio Explorer
- Import Manager
- Audition
- Live View
- Container Validator
- Voice Pool Debug
- Mixer, full version
- Audio Profiler, full version
- EQ Spectrum Visualizer, full version
- Loading Validator, full version

Folder Rules live on an Audio Import Settings asset: **Create > Audio System > Import Settings**.

### Setting it up

1. Add an **Audio Manager** to your first scene.
2. Open **Sound Builder (Simple)**, drop in your clips, choose Complete Setup and create the sound.
3. Select the new container or event and open **Audition** to tune it.
4. Run **Container Validator** before you build.
5. Press Play and open **Live View** or **Voice Pool Debug** to see what is playing and why.

### Good to know

- Outside Play mode the Audition plays 3D sounds as 2D, at full level, and a Sequence plays only its first clip. It runs on its own hidden Audio Manager and adds nothing to your scene.
- Sound Builder (Simple) always warns that events must be in a Resources folder. Ignore it if you use an Audio Event Registry. Its preview button may do nothing.
- The Audio Profiler's "Est. CPU" is estimated from the voice count, and "Managed heap" is your whole game's memory. Use Unity's Profiler for real figures.
- More windows cover engines (Loop Analysis, and in the full version Engine Builder and Engine Grains: see [Vehicle engines](https://peppersfx.com/features/vehicle-engines/)), mixer setup (Occlusion Layout, Reverb Send Buses) and, in the full version, Addressable Audio Authoring and Network Audio Debug.

# Frequently asked questions

## What is Pepper.SFX?

Pepper.SFX is audio middleware for Unity. You author sounds as assets (events, containers, buses, states and parameters) and play them from code with one call, such as footstepEvent.Post(gameObject, transform.position). Its code is in the AudioSystem namespace. See Features for what it covers.

## Which Unity versions does Pepper.SFX support?

Unity 6000.0.48f1 or newer. Package Manager will install it on older 6000.0 versions, but those aren't supported. The automated tests pass on 6000.0.48f1 and 6000.3.19f1. The experimental generated engines need Unity 6000.3 or later.

## What is the difference between the free and full versions?

The free version is compiled DLLs, installed as a package from GitHub. The full version is the complete source, with every editor window, multiplayer, Addressables loading and the example scripts; it is coming soon to the Unity Asset Store but isn't out yet. The windows left out of the free version are the Mixer, Audio Profiler, EQ Spectrum Visualizer, Loading Validator, Sound Builder (Advanced) and Engine Builder, and the experimental generated engines are full only too. See how to get it.

## Can I move from the free version to the full version without losing my work?

Yes. The two versions can't be in the same project, and swapping the free DLLs for source would break every script reference to them. A separate upgrade tool, released together with the full version, rewrites those references once, so your events, containers, buses, scenes and prefabs carry over. Back up your project before you run it.

## Which platforms does Pepper.SFX run on?

Pepper.SFX is C# on top of Unity's own audio, so it runs wherever Unity's audio does: Windows, macOS, Linux, mobile, Meta Quest and consoles. There are two exceptions. Convolution reverb works only on 64-bit Windows (x64), and Web builds play sound without occlusion muffling or reverb, because Unity's Web audio has no mixer effects. See Build Compatibility.

## Does Pepper.SFX replace Unity's audio system?

No. It plays through Unity's own audio: every sound is played by a pooled AudioSource, and buses route to your AudioMixer groups. Pepper decides what plays, at what level and pitch, and through which bus; Unity mixes it and sends it to the speakers. Your settings in Project Settings > Audio still apply.

## Will my existing AudioSources keep working?

Yes. Pepper.SFX keeps its own pool of AudioSources and doesn't change yours, so you can move a project over one sound at a time. Both share Unity's voice limits (Project Settings > Audio), and Pepper warns at startup if its own limits are higher than Unity's.

## Does Pepper.SFX support multiplayer?

Yes, in the full version: a networked sound sends a small message saying which event to play and where, never audio, and each machine plays it locally. FishNet v4 is tested, on one PC and on two over a real network. Netcode for GameObjects 2.x has had light testing only, and NGO 1.x and FishNet v3 aren't supported. See Multiplayer.

## Does it work in split-screen games?

Yes. Register each player's camera as a listening point with AudioManager.Instance.AddListeningPoint(cameraTransform) and set the Audio Manager's Spatial Mode to Pepper. Pepper then pans and attenuates 3D sounds from every listening point, weighted by each point's Weight and Pan Width. In that mode spatializer (HRTF) plugins aren't used and stereo clips are balanced rather than placed, so give 3D sounds mono clips (more in Spatial audio and listeners).

## Can I use Pepper.SFX on a dedicated server?

Yes. Set AudioManager.Inert = true at boot, before any Audio Manager starts. Every post then returns an already-finished handle without allocating or logging, and an Audio Manager that starts builds no voices or per-frame work. The server can run the same scenes and prefabs as the clients.

## How does Pepper.SFX perform?

Sounds play from a pool of AudioSources made when the Audio Manager starts, so playing a sound doesn't create GameObjects. By default 32 voices are heard at once and up to 64 more are tracked as virtual: silent, keeping their place, and brought back when they matter again. Parameter writes allocate nothing after their first use. The Voice Pool Debug and Live View windows show what is playing and why; see Voices and performance.

## Can Pepper.SFX play car engines?

Yes. A Blend Container with Regions and Pitch Follow keeps loops recorded at different RPMs in tune at every RPM, and in the full version the Engine Builder window builds a whole engine from your loops. Each car posts its engine on its own Audio Emitter, so every car follows its own RPM. See Vehicle engines.

## How do I get started?

Add an Audio Manager component to a GameObject in your first scene, then open Window > Audio System > Sound Builder (Simple) to make a bus, a container and an event from your clips. Drag the event into a field on your script and call Post on it. The Quick Start walks through it.

## Where is the documentation?

On this site, under Docs: a Quick Start, a cookbook of recipes, the full manual and the API reference. Problems we already know about are listed under Known issues.

## How do I report a bug?

Email amir.pepper.work@gmail.com with your Unity version, your platform, whether you use the free or full version, the steps that cause the problem, and any console errors. Check Known issues first, in case it's already listed. Other ways to get in touch are on the Contact page.

# Documentation

## Introduction

Source: https://peppersfx.com/docs/introduction/

### What is Pepper.SFX?

Pepper.SFX is professional audio middleware for Unity. Instead of manually managing AudioSources and juggling clips, you work with high-level concepts: **Events**, **Containers**, and **Buses**.

**In one sentence:** Play sounds through events, not AudioSources.

### The Problem It Solves

**Before (Standard Unity):**
```csharp
public AudioClip footstepClip;
public AudioSource audioSource;

void PlayFootstep()
{
    audioSource.clip = footstepClip;
    audioSource.Play();
}
```

❌ No variations • ❌ Manual management • ❌ No pooling • ❌ No volume control structure

**After (Pepper.SFX):**
```csharp
public AudioEvent footstepEvent;

void PlayFootstep()
{
    footstepEvent.Post(gameObject, transform.position);
}
```

✅ Built-in variations • ✅ Automatic pooling • ✅ Professional mixing • ✅ Easy to organize

> 🛠️ **Building for anything other than 64-bit Windows?** Read [6. Build Compatibility](https://peppersfx.com/docs/build-compatibility/) first. Convolution reverb is 64-bit Windows only, and Web builds have no occlusion muffling or reverb.

## Quick Start

Source: https://peppersfx.com/docs/quick-start/

### Choose Your Path

Pick the setup method that fits your workflow:

#### Method 1: Quick Wizard ⭐ (2 minutes)
**Best for:** Beginners, rapid prototyping
**Time:** 2 minutes
**Skill:** Easy

[Jump to Quick Wizard](#method-1-quick-wizard)

#### Method 2: Manual Setup (10 minutes)
**Best for:** Learning the system, custom control
**Time:** 10 minutes
**Skill:** Medium

[Jump to Manual Setup](#method-2-manual-setup)

#### Method 3: Registry System (Advanced)
**Best for:** Large projects, eliminating Resources folder
**Time:** Setup + migration
**Skill:** Advanced

[See Migration](https://peppersfx.com/docs/migration/) for full details.

---

### Method 1: Quick Wizard

**The absolute fastest way to add sounds - perfect for beginners!**

#### Step 1: Add AudioManager to Scene (30 seconds)
1. Create empty GameObject in your scene
2. Add `AudioManager` component
3. Done! (Auto-configures itself)

#### Step 2: Create Sound Assets (1 minute)
1. In Unity menu: `Window > Audio System > Sound Builder (Simple)`
2. **Choose Creation Mode:**
   - **Complete Setup** - Creates Bus + Container + Event all at once (recommended)
   - **Container Only** - Just create a container
   - **Event Only** - Just create an event (with existing container or blank)
   - **Bus Only** - Just create a bus
   - **Batch Import** - Import multiple clips at once
3. Enter sound name (e.g., "ButtonClick")
4. **Select Container Type:**
   - **Routing** - Direct playback (plays all clips simultaneously if multiple added)
   - **Random** - Random selection with weights
   - **Sequence** - Sequential playback (Forward/Reverse/PingPong)
   - **Switch** - Switch-based selection
   - **Blend** - RTPC-driven real-time blending
5. Add one or more AudioClips
6. Configure advanced options if needed (pitch/volume randomization, 3D settings)
7. Click **"Create Complete Sound Setup"**

There are no presets: you set each option yourself, and the defaults suit a simple 2D sound effect.

✅ Done! The wizard creates:
- AudioBus (with custom name)
- Container (any type: Routing, Random, Sequence, Switch, or Blend)
- AudioEvent (with selectable action type)
- All references pre-filled

💡 **Pro Tips:**
- The wizard auto-detects selected audio clips and suggests batch import for multiple selections
- Use "Auto-Create Standard Folder Structure" to set up all required folders
- Routing containers can layer multiple clips for complex sounds (e.g., gunshot with shell eject)

#### Step 3: Play in Code (30 seconds)
```csharp
using AudioSystem;

public class MyScript : MonoBehaviour
{
    public AudioEvent buttonClickSound;

    void OnButtonPressed()
    {
        buttonClickSound.Post(gameObject, transform.position);
    }
}
```

Drag the created AudioEvent into the script field, and you're done!

**What's Next?** See the [Cookbook](https://peppersfx.com/docs/cookbook/overview/) chapter for more recipes or jump to [Troubleshooting](#troubleshooting).

---

### Method 2: Manual Setup

**Traditional workflow - full control over every step**

#### Step 1: Add AudioManager (2 minutes)

1. In your scene, create a new empty GameObject
2. Name it "AudioManager"
3. Add the `AudioManager` component
4. **Leave all default settings** - they're optimized for most games

**Inspector Settings (defaults are fine):**
- Master Volume: 1.0
- Max Real Voices: 32
- Max Virtual Voices: 64
- Enable LOD: ✓

Occlusion is opted into per-container via the `Use Occlusion` toggle on AudioContainer assets, not via a global AudioManager switch — see the Occlusion chapter in the Manual.

**Important:** AudioManager persists between scenes automatically via `DontDestroyOnLoad`, as long as **Persist Across Scenes** is on (the default) and its GameObject is at the top of the hierarchy: Unity keeps only root objects. To keep it under another object (a scene that is never unloaded, a client-only root), turn Persist Across Scenes off; it then belongs to its own scene.

---

#### Step 2: Create Folder Structure (1 minute)

Right-click in Project window → `Create > Audio System > Sound Builder (Simple)` → Click **"Auto-Create Standard Folder Structure"**

Or manually create:

```
Assets/Audio/
├── Resources/
│   └── Audio/
│       ├── Events/    ← AudioEvents MUST go here
│       └── States/    ← AudioStates MUST go here
├── Containers/        ← Container assets
├── Buses/             ← Bus assets
└── AudioClips/        ← Your .wav/.mp3 files
    ├── SFX/
    ├── Music/
    └── Ambience/
```

**Why Resources folder?** AudioManager auto-loads Events and States from `Resources/Audio/Events` and `Resources/Audio/States` at startup. (See the [Migration](https://peppersfx.com/docs/migration/) chapter to skip this requirement via `AudioEventRegistry`.)

---

#### Step 3: Create Your First Bus (2 minutes)

1. Right-click in `Assets/Audio/Buses/`
2. Select `Create > Audio System > Audio Bus`
3. Name the file: "SFX_Bus"
4. Select it and configure in the Inspector:
   - **Bus Name:** "SFX"
   - **Volume Db:** 0
   - **Parent Bus:** (leave empty for now)
   - **Mixer Group:** (optional)

**What just happened?** You created a volume control group for sound effects. Later you can adjust all SFX together.

💡 **Tip:** The Quick Wizard creates this automatically in its Complete Setup mode.

---

#### Step 4: Create Your First Container (2 minutes)

1. Right-click in `Assets/Audio/Containers/`
2. Select `Create > Audio System > Routing Container`
3. Name it: "TestSound_RC"
4. Select it and configure in the Inspector:
   - **Container Name:** "TestSound"
   - **Audio Clips:** Drag in 1-3 AudioClips from your project
   - **Volume:** 1.0
   - **Loop:** ☐ (unchecked)

**Optional - Add Variation:**
- **Enable Volume Randomization:** ☑
  - Min: -1, Max: 1
- **Enable Pitch Randomization:** ☑
  - Min: -50, Max: 50

**What just happened?** You created a simple container that plays your clip(s) with optional randomization.

---

#### Step 5: Create Your First Event (2 minutes)

1. Right-click in `Assets/Audio/Resources/Audio/Events/`
2. Select `Create > Audio System > Audio Event`
3. Name it: "Play_TestSound"
4. Select it and configure in the Inspector:

**Event Configuration:**
- **Event Name:** "Play_TestSound"

**Voice Settings:**
- **Priority:** Medium
- **Max Instances:** 5
- **Cooldown:** 0

**Actions → Size: 1**

**Action [0]:**
- **Type:** Play
- **Container:** TestSound_RC (drag from Containers folder)
- **Target Bus:** SFX_Bus (drag from Buses folder)
- **Delay:** 0
- **Fade Duration:** 0

**What just happened?** You created an event that plays your container through the SFX bus when triggered.

⚠️ **Important:** The Inspector will show a warning if the event is not in the Resources folder. Click the "Move to Resources" button if you see this warning.

---

#### Step 6: Play It From Code (1 minute)

Create a new C# script called `TestAudio.cs`:

```csharp
using UnityEngine;
using AudioSystem;

public class TestAudio : MonoBehaviour
{
    [SerializeField] private AudioEvent testEvent;

    void Update()
    {
        if (Input.GetKeyDown(KeyCode.Space))
        {
            testEvent.Post(gameObject, transform.position);
            Debug.Log("Playing test sound!");
        }
    }
}
```

**Setup:**
1. Create a new GameObject in your scene (or use an existing one)
2. Attach the `TestAudio` script to it
3. In the Inspector, drag `Play_TestSound` event into the `Test Event` field
4. Press **Play** in Unity
5. Press **Spacebar** to hear your sound!

---

### 🎉 Congratulations!

You've successfully set up the complete audio pipeline:

**Your Code** → **AudioEvent** → **Container** → **Voice** → **Bus** → **Speaker**

---

### Troubleshooting

#### "AudioEvent not playing!"
**Check Inspector warnings:**
- Open your AudioEvent asset
- Look for red/yellow warning boxes
- If it says "NOT in Resources folder" → Click "Move to Resources/Audio/Events/"

#### "AudioManager not found!"
- Ensure AudioManager is in scene
- Check it persists: with Persist Across Scenes on (the default) it is kept across scenes, but only if its GameObject is a root (Unity warns otherwise). Under a parent, turn Persist Across Scenes off and keep it in a scene that stays loaded.

#### "No AudioEvents found in Resources/Audio/Events"
- Events MUST be in `Assets/Audio/Resources/Audio/Events/` folder
- OR use the [AudioEventRegistry system](https://peppersfx.com/docs/migration/)

#### Sound Too Quiet/Loud?
**Check:**
1. Container volume (0-1)
2. Bus volume (in dB, 0 = no change)
3. Master volume on AudioManager
4. Unity's AudioListener volume

---

### Quick Reference

#### Minimal Code Example
```csharp
using AudioSystem;

public AudioEvent mySound;

void Start()
{
    mySound.Post(gameObject, transform.position);
}
```

#### Common Methods

**Play a sound:**
```csharp
AudioHandle handle = myEvent.Post();
AudioHandle handle = myEvent.Post(gameObject, transform.position);
```

**Control playback:**
```csharp
handle.Stop(fadeTime: 0.5f);
handle.Pause();
handle.Resume();
handle.SetVolumeScale(0.75f);   // relative to the authored volume
handle.SetPitchOffset(2f);      // semitones, on top of the authored pitch
```

**Global controls:**
```csharp
AudioManager.Instance.StopAllSounds();
AudioManager.Instance.PauseAll();
AudioManager.Instance.UnpauseAll();
AudioManager.Instance.MuteAll(true);   // mute
AudioManager.Instance.MuteAll(false);  // unmute
worldBus.Pause();                      // a game's pause: this bus and its children hold, a pause menu's buses play
worldBus.Resume();
```

**Bus control:**
```csharp
AudioManager.Instance.SetBusVolume("Music", volumeDb: -6f, transitionTime: 1f);
```

**State changes:**
```csharp
AudioManager.Instance.SetState("Underwater", transitionTime: 1.5f);
```

**RTPC with transitions:**
```csharp
AudioManager.Instance.SetRTPC("CombatIntensity", 0.75f);
AudioManager.Instance.TransitionRTPC("CombatIntensity", 1.0f, duration: 2f);
```

---

### What's Next?

#### Level 1 - You are here! ✓
- Basic sound playback
- Simple events and containers
- Bus volume control

#### Level 2 - [Cookbook](https://peppersfx.com/docs/cookbook/overview/)
- Footsteps with variations
- UI sound systems
- Weapon audio
- Music systems
- 3D spatial audio

#### Level 3 - [Manual](https://peppersfx.com/docs/manual/overview/)
- Deep system understanding
- Advanced features
- Performance optimization
- Registry system

#### Level 4 - [API Reference](https://peppersfx.com/docs/#api)
- Complete API documentation
- All classes and methods
- Advanced use cases

---

### Comparison: Which Method Should I Use?

| Method | Best For | Setup Time | Flexibility | Learning |
|--------|----------|------------|-------------|----------|
| **Quick Wizard** | Beginners, rapid prototyping | 2 min | Low | Easy |
| **Manual Setup** | Learning system, custom control | 10 min | Medium | Best |
| **Registry System** | Large projects, no Resources | 15 min | High | Advanced |

**Recommendation:**
- **New users:** Start with Quick Wizard
- **Learning the system:** Use Manual Setup
- **After 10+ sounds:** Consider Registry System (see [Migration](https://peppersfx.com/docs/migration/))

---

### Key Concepts to Remember

1. **Events are in Resources** - Must be in `Assets/Audio/Resources/Audio/Events/` to auto-load (or use registry)
2. **States are in Resources** - Must be in `Assets/Audio/Resources/Audio/States/` to auto-load (or use registry)
3. **One AudioManager per project** - It persists between scenes
4. **Buses use dB** - 0 dB = no change, -6 dB ≈ half as loud, -80 dB = silence
5. **Voice limit** - 32 real voices by default (configurable)

---

### 🆕 Ambient Propagation (v2.3.0)

Pepper.SFX now ships with an **optional** zone/portal-based ambient propagation subsystem. Use it when you want ambient beds (rain, wind, machinery) to route *through geometry* — muffled through a closed door, swelling as it opens, heard *from the window* when the listener is in another room.

Propagation is **additive** — it doesn't touch the SFX event pipeline you just learned. Skip this section if your project only plays discrete SFX.

#### 2-Minute Setup

```
1. Create empty GameObject → BoxCollider (isTrigger forced on) → Add "Audio/Propagation/Audio Zone"
   → Size collider to fit the room. Repeat for each acoustic space.

2. Create empty GameObject at a doorway → BoxCollider → Add "Audio/Propagation/Audio Portal"
   → Drag the two adjacent AudioZones into ZoneA and ZoneB.

3. Create empty GameObject inside the source zone → Add "Audio/Propagation/Ambient Source"
   → Assign Source Zone, Looping Clip, and Ambience Mixer Group.

4. On your player object, the one with the Collider (e.g. the player root's Capsule Collider)
   → Add "Audio/Propagation/Audio Listener Zone Tracker". Not on the camera that holds the
   AudioListener: trigger events only reach a GameObject that has a Collider.
   (A kinematic Rigidbody is auto-added if needed for trigger events.)
```

That's it. The `PropagationManager` auto-instantiates on first reference. Walk through the doorway and you'll hear the bed transition smoothly between zones.

#### Door-Driven Transmission

To let a door swing affect audio, implement `IPortalDoorSource` on any MonoBehaviour:

```csharp
using AudioSystem.Propagation;

public class MyDoor : MonoBehaviour, IPortalDoorSource
{
    public float OpenProgress => animator.GetFloat("openAmount"); // 0..1
    public event System.Action OnChanged;
}
```

Drag it into the portal's `Door Source` field. Closed → `closedTransmission` amplitude + `closedLowPassHz` filtering; open → the base values. Interpolation is continuous — no discrete snap.

#### Where to Learn More

- **Cookbook** → [Ambient Propagation recipes](https://peppersfx.com/docs/cookbook/ambient-propagation/)
- **Manual** → [Chapter 13: Ambient Propagation Subsystem](https://peppersfx.com/docs/manual/ambient-propagation-subsystem/)
- **API Reference** → [Propagation](https://peppersfx.com/docs/api/propagation/)

## Build Compatibility

Source: https://peppersfx.com/docs/build-compatibility/

What works on which platform. Pepper.SFX is C# on top of Unity's own audio (AudioSource and AudioMixer) and physics raycasts. Apart from the convolution reverb plugin it has no platform-specific code, so it behaves the same wherever Unity's audio does. The two exceptions are **convolution reverb** and **Web builds**.

### At a Glance

| Platform | What works |
|---|---|
| Windows, 64-bit (x64) | Everything, including convolution reverb |
| macOS, Linux | Everything except convolution reverb |
| iOS, Android, Meta Quest | Everything except convolution reverb |
| Consoles | Everything except convolution reverb |
| Windows on ARM, 32-bit Windows | Everything except convolution reverb |
| Web | Sound plays, but without occlusion muffling, reverb, or propagation filtering. See [Web Builds](#web-builds). |

The free version has the same platform support as the full version.

### Convolution Reverb: 64-bit Windows Only

Convolution reverb ("Use Convolution" on a Reverb Send Bus) runs in a native plugin, `SFXConvolutionReverb.dll`, built for 64-bit Windows only: the Windows editor and Windows x64 player builds.

Everywhere else (macOS, Linux, mobile, consoles, Web, Windows on ARM and 32-bit Windows):

- **A convolution bus is silent.** The dry sound still plays; only that bus's reverb is missing.
- **Unity may log an error** about the missing mixer effect when the game starts.
- **The impulse response isn't uploaded**, and a warning says so.
- **The macOS and Linux editor** don't load the plugin either, so convolution buses are silent there while you work.

Parametric reverb (a Reverb Send Bus without "Use Convolution") works on every platform except Web. If your game ships anywhere other than 64-bit Windows, use parametric buses.

### Web Builds

Unity's Web platform uses its own, smaller audio engine built on the browser's audio. On the AudioMixer it supports groups and their volume, and nothing else: no mixer effects and no sends. Audio filter components (Low Pass, Reverb) aren't on its supported list either. Unity's manual lists the details on its "Audio in Web" page.

What that means for Pepper.SFX:

| Feature | On Web |
|---|---|
| Events, containers, switches, states, RTPCs | Work |
| Buses: volume, mute, solo, ducking | Work |
| Voice pool, virtual voices, priorities, steals | Work |
| Scheduled and beat-synced playback | Work |
| Occlusion | Sounds get quieter behind walls, but aren't muffled. The muffling is a low-pass on mixer effects. |
| Reverb Send Buses, parametric and convolution | No reverb. Sends and reverb are mixer effects. |
| Ambient propagation | Beds still route through zones and portals and follow doors and distance, but aren't muffled and get no reverb. The emitters use Low Pass and Reverb filter components. |
| Multiplayer | Works if your netcode library's transport runs in a browser (WebSockets or WebRTC). The SFX netcode layer sends through that transport and has no network code of its own. |

The browser adds its own rules:

- **No sound until the player interacts.** Browsers block audio until the first click, tap or key press on the page. Sounds posted before that, such as menu music started at scene load, can start late or be missed. Start audio after the first input, or open with a "click to start" screen.
- **No streaming.** Browsers can't stream audio from disk. The Music and Ambience import presets use the Streaming load type, so give those clips a Web override in their import settings (Compressed In Memory).
- **iPhone and iPad.** In Safari on iOS, clips set to Decompress On Load can be silent when the device is in Silent Mode. Use Compressed In Memory for Web.

If Web is a main target, design the mix so it doesn't depend on muffling or reverb, and test in a Web build early.

### Mobile

Every feature works. Occlusion raycasts and the per-voice mixer effects cost more CPU on phones than on desktop. If Unity's Profiler shows audio or physics time climbing, lower **Max Real Voices**, raise **Occlusion Update Interval**, or lower **Occlusion Ray Count** on the AudioManager.

### Requirements

- Unity 6000.0.48f1 or newer.

---

*For API signatures and full type listings, see [API_REFERENCE.md](https://peppersfx.com/docs/#api).*

*Pepper.SFX v3.0.0 — Professional Audio Middleware for Unity*

## Cookbook: overview

Source: https://peppersfx.com/docs/cookbook/overview/

This section is organized around tasks, not features. Each recipe walks one outcome from asset creation through code.

**Three ways to read this section — every recipe serves all three:**
- 🏃 **Skimmer:** Read the recipe titles and the bolded step labels. Skip the prose. The ordered lists at the top of each topic are the map.
- 📖 **Learner:** Read each recipe top to bottom. Each one is self-contained and explains *why* alongside *how*.
- 🔍 **Reference reader:** Jump to the recipe whose title matches your task. Use the Table of Contents.

> ## ⚠️ Read this before doing anything spatial
>
> **Occlusion, Per-Zone Reverb, and container-level Ambient Propagation all share one piece of infrastructure: the Occlusion Slot Pool.**
>
> On every play, the system checks:
>
> ```
> wantsSlot = container.UseOcclusion || container.AllowReverbSend || container.UsePropagation
> ```
>
> If *any* of those three flags is on and the slot pool has not been authored, the voice silently falls back to direct-to-bus routing. No low-pass muffling. No reverb sends. **No error.** Only the volume part works without a slot: an occluded or propagated sound still gets quieter behind walls and doors, it just keeps its treble, so the setup can sound half right.
>
> **You must author the Occlusion Slot Pool first**, before touching reverb buses, zones, or container flags. Do it here: [Occluding SFX Through Geometry → One-Time Project Setup](https://peppersfx.com/docs/cookbook/occluding-sfx-through-geometry/#recipe-one-time-project-setup-5-minutes).
>
> Exception: the `AmbientSource` propagation path (rain, wind, ambient beds) uses a separate emitter pool and does *not* require slots. Only container-level `UsePropagation` does.

## Setup & Organization

Source: https://peppersfx.com/docs/cookbook/setup-organization/

### Recipe: First-Time Project Setup (10 minutes)

📋 **What:** Complete setup from scratch to playing first sound

#### Step 1: Create AudioManager (2 min)

1. Create empty GameObject in scene: "AudioManager"
2. Add component: `AudioManager` (Component → Audio System → Audio Manager)
3. Configure Inspector:
   - Master Volume: 1.0
   - Max Real Voices: 32
   - Max Virtual Voices: 64
   - Enable LOD: ✓

   Occlusion is opted into per-container (see the `Use Occlusion` toggle on AudioContainer assets), not via a global AudioManager switch.

#### Step 2: Create Folder Structure (2 min)

Right-click in Project, create folders:

```
Assets/
├── Resources/
│   └── Audio/
│       ├── Events/  ← AudioEvents MUST go here
│       └── States/  ← AudioStates MUST go here
└── Audio/
    ├── Containers/  ← Container assets
    ├── Buses/       ← Bus assets
    └── AudioClips/  ← Your .wav/.mp3 files
        ├── SFX/
        ├── Music/
        └── Ambience/
```

#### Step 3: Create Master Bus (1 min)

1. Right-click `Buses/` → Create → Audio System → Audio Bus
2. Name: "Master_Bus"
3. Inspector:
   - Bus Name: "Master"
   - Volume Db: -3
   - Parent Bus: (none)

#### Step 4: Create SFX Bus (1 min)

1. Right-click `Buses/` → Create → Audio System → Audio Bus
2. Name: "SFX_Bus"
3. Inspector:
   - Bus Name: "SFX"
   - Volume Db: 0
   - Parent Bus: Master_Bus

#### Step 5: Create First Container (2 min)

1. Right-click `Containers/` → Create → Audio System → Routing Container
2. Name: "Test_Click_RC"
3. Inspector:
   - Container Name: "TestClick"
   - Audio Clips: Drag in a sound
   - Volume: 1.0
   - Enable Volume Randomization: ✓ (Min: -1, Max: 1)
   - Enable Pitch Randomization: ✓ (Min: -50, Max: 50)

#### Step 6: Create First Event (2 min)

1. Right-click `Assets/Resources/Audio/Events/` → Create → Audio System → Audio Event
2. Name: "Play_TestClick"
3. Inspector:
   - Event Name: "Play_TestClick"
   - Priority: High
   - Max Instances: 3
   - Actions → Size: 1
   - Action [0]:
     - Type: Play
     - Container: Test_Click_RC
     - Target Bus: SFX_Bus

✅ **Result:** Complete audio pipeline ready to use!

---

### Recipe: Recommended Bus Hierarchy

📋 **What:** Professional bus structure for games

⚙️ **Setup:**

**Create Master Bus:**
- Name: Master_Bus
- Bus Name: "Master"
- Volume Db: -3
- Parent: (none)

**Create SFX Bus:**
- Name: SFX_Bus
- Bus Name: "SFX"
- Volume Db: 0
- Parent: Master_Bus

**Create SFX Sub-Buses:**

1. **Player_Bus**
   - Bus Name: "Player"
   - Parent: SFX_Bus
   - Volume Db: 0

2. **Weapons_Bus**
   - Bus Name: "Weapons"
   - Parent: Player_Bus
   - Volume Db: 0

3. **Footsteps_Bus**
   - Bus Name: "Footsteps"
   - Parent: Player_Bus
   - Volume Db: -6

4. **Enemies_Bus**
   - Bus Name: "Enemies"
   - Parent: SFX_Bus
   - Volume Db: -3

5. **UI_Bus**
   - Bus Name: "UI"
   - Parent: SFX_Bus
   - Volume Db: 0

6. **Ambience_Bus**
   - Bus Name: "Ambience"
   - Parent: SFX_Bus
   - Volume Db: -6

**Create Music Bus:**
- Name: Music_Bus
- Bus Name: "Music"
- Parent: Master_Bus
- Volume Db: -6

**Create Dialogue Bus:**
- Name: Dialogue_Bus
- Bus Name: "Dialogue"
- Parent: Master_Bus
- Volume Db: 0
- Enable Ducking: ✓
- Ducking Targets:
  - Music_Bus, Amount: 0.7
  - SFX_Bus, Amount: 0.5

**Final Hierarchy:**
```
Master (-3dB)
├── SFX (0dB)
│   ├── Player (0dB)
│   │   ├── Weapons (0dB)
│   │   └── Footsteps (-6dB)
│   ├── Enemies (-3dB)
│   ├── UI (0dB)
│   └── Ambience (-6dB)
├── Music (-6dB)
└── Dialogue (0dB) [Ducks Music & SFX]
```

✅ **Result:** Professional mixing structure with ducking!

## UI Sounds

Source: https://peppersfx.com/docs/cookbook/ui-sounds/

### Recipe: Button Click Sound

📋 **What:** Button with click sound and subtle variations

🎯 **Use Case:** UI buttons, menu navigation

#### Asset Setup

**1. Create Container:**
- Right-click `Containers/UI/` → Create → Random Container
- Name: "UI_ButtonClick_RnC"
- Inspector:
  - Audio Clips: Add 2-3 click sound variations
  - Avoid Repeat Last: 1
  - Use Weighting: ✓ (all weights = 1.0)
  - Volume: 0.8
  - Enable Volume Randomization: ✓ (Min: -1, Max: 1)
  - Enable Pitch Randomization: ✓ (Min: -50, Max: 50)

**2. Create Event:**
- Right-click `Assets/Resources/Audio/Events/UI/` → Create → Audio Event
- Name: "Play_UI_ButtonClick"
- Inspector:
  - Event Name: "Play_UI_ButtonClick"
  - Priority: Critical
  - Max Instances: 2
  - Steal Behavior: Oldest
  - Cooldown: 0.05
  - Actions → Size: 1
  - Action [0]:
    - Type: Play
    - Container: UI_ButtonClick_RnC
    - Target Bus: UI_Bus

#### Code

```csharp
using UnityEngine;
using UnityEngine.UI;
using AudioSystem;

public class UIButtonSound : MonoBehaviour
{
    [SerializeField] private AudioEvent clickEvent;

    private Button button;

    void Awake()
    {
        button = GetComponent<Button>();
        if (button != null)
        {
            button.onClick.AddListener(OnButtonClick);
        }
    }

    void OnDestroy()
    {
        if (button != null)
        {
            button.onClick.RemoveListener(OnButtonClick);
        }
    }

    void OnButtonClick()
    {
        if (clickEvent != null)
        {
            clickEvent.Post();
        }
    }
}
```

**Usage:**
1. Attach to Button GameObject
2. Drag "Play_UI_ButtonClick" into Click Event field
3. Click button to hear sound

✅ **Result:** Button clicks with subtle variation, no spam!

---

### Recipe: Settings Menu with Volume Sliders

📋 **What:** Complete audio settings menu with persistence

🎯 **Use Case:** Options menu, settings screen

💻 **Code:**

```csharp
using UnityEngine;
using UnityEngine.UI;
using AudioSystem;

public class AudioSettingsMenu : MonoBehaviour
{
    [Header("UI References")]
    [SerializeField] private Slider masterSlider;
    [SerializeField] private Slider sfxSlider;
    [SerializeField] private Slider musicSlider;
    [SerializeField] private Slider dialogueSlider;

    [Header("Audio Events")]
    [SerializeField] private AudioEvent testSFXEvent;

    private const string MASTER_KEY = "Audio_MasterVolume";
    private const string SFX_KEY = "Audio_SFXVolume";
    private const string MUSIC_KEY = "Audio_MusicVolume";
    private const string DIALOGUE_KEY = "Audio_DialogueVolume";

    void Start()
    {
        LoadSettings();
        SetupListeners();
        ApplySettings();
    }

    void LoadSettings()
    {
        masterSlider.value = PlayerPrefs.GetFloat(MASTER_KEY, 1f);
        sfxSlider.value = PlayerPrefs.GetFloat(SFX_KEY, 1f);
        musicSlider.value = PlayerPrefs.GetFloat(MUSIC_KEY, 1f);
        dialogueSlider.value = PlayerPrefs.GetFloat(DIALOGUE_KEY, 1f);
    }

    void SetupListeners()
    {
        masterSlider.onValueChanged.AddListener(OnMasterVolumeChanged);
        sfxSlider.onValueChanged.AddListener(OnSFXVolumeChanged);
        musicSlider.onValueChanged.AddListener(OnMusicVolumeChanged);
        dialogueSlider.onValueChanged.AddListener(OnDialogueVolumeChanged);
    }

    void ApplySettings()
    {
        OnMasterVolumeChanged(masterSlider.value);
        OnSFXVolumeChanged(sfxSlider.value);
        OnMusicVolumeChanged(musicSlider.value);
        OnDialogueVolumeChanged(dialogueSlider.value);
    }

    void OnMasterVolumeChanged(float value)
    {
        AudioManager.Instance.SetMasterVolume(value);
        PlayerPrefs.SetFloat(MASTER_KEY, value);
        PlayerPrefs.Save();
    }

    void OnSFXVolumeChanged(float value)
    {
        SetPlayerVolume("SFX", value);
        PlayerPrefs.SetFloat(SFX_KEY, value);
        PlayerPrefs.Save();
    }

    void OnMusicVolumeChanged(float value)
    {
        SetPlayerVolume("Music", value);
        PlayerPrefs.SetFloat(MUSIC_KEY, value);
        PlayerPrefs.Save();
    }

    void OnDialogueVolumeChanged(float value)
    {
        SetPlayerVolume("Dialogue", value);
        PlayerPrefs.SetFloat(DIALOGUE_KEY, value);
        PlayerPrefs.Save();
    }

    // The player's volume on a bus (Manual §6.8): on top of the mix, never saved into the bus asset,
    // and a mix state can't undo it. Not SetBusVolume, which changes the bus's own Volume.
    void SetPlayerVolume(string busName, float linear)
    {
        var bus = AudioManager.Instance.GetBus(busName);   // an unknown name warns once
        if (bus != null)
            bus.PlayerVolumeDb = AudioSystem.AudioExtensions.LinearToDb(linear);  // qualified: Unity 6.3 has its own AudioExtensions
    }

    // Call this from a "Test" button
    public void PlayTestSound()
    {
        if (testSFXEvent != null)
        {
            testSFXEvent.Post();
        }
    }
}
```

**UI Setup:**
1. Create 4 Sliders (Master, SFX, Music, Dialogue)
2. Set slider range: 0 to 1
3. Create "Test Sound" button
4. Attach script to settings panel
5. Assign references

✅ **Result:** Full audio settings with persistence and test button!

💡 **Why `PlayerVolumeDb` and not `SetBusVolume`:** `SetBusVolume` changes the bus's own Volume, the mix you authored. In the editor a Play-mode change stays in the asset, and a state that sets the bus's level overwrites the player's choice. The player's volume is a separate level on top. `Example08_AudioSettingsUI` is the full version.

## Footsteps & Movement

Source: https://peppersfx.com/docs/cookbook/footsteps-movement/

### Recipe: Basic Footsteps with Variations

📋 **What:** Player footsteps with natural variation

🎯 **Use Case:** Character locomotion

#### Asset Setup

**1. Create Container:**
- Create → Random Container
- Name: "Player_Footsteps_RnC"
- Inspector:
  - Audio Clips: Add 6-8 footstep sounds
  - Avoid Repeat Last: 2
  - Use Weighting: ✓ (equal weights)
  - Volume: 0.6
  - Enable Volume Randomization: ✓ (Min: -2, Max: 2)
  - Enable Pitch Randomization: ✓ (Min: -100, Max: 100)
  - Is3D: ✓
  - Min Distance: 1
  - Max Distance: 15

**2. Create Event:**
- Create → Audio Event
- Name: "Play_Player_Footstep"
- Inspector:
  - Priority: High
  - Max Instances: 4
  - Actions → Play Player_Footsteps_RnC → Footsteps_Bus

#### Code (Animation Events)

```csharp
using UnityEngine;
using AudioSystem;

public class PlayerFootsteps : MonoBehaviour
{
    [SerializeField] private AudioEvent footstepEvent;

    // Called from animation event on footfall frames
    public void PlayFootstep()
    {
        if (footstepEvent != null)
        {
            footstepEvent.Post(gameObject, transform.position);
        }
    }
}
```

**Setup:**
1. Attach to player GameObject
2. Assign footstep event
3. In Animation window, add Animation Event at each footfall
4. Set Function: "PlayFootstep"

✅ **Result:** Natural-sounding footsteps synced to animation!

---

### Recipe: Surface-Dependent Footsteps

📋 **What:** Different footstep sounds per surface type

🎯 **Use Case:** Realistic environmental feedback

#### Asset Setup

**1. Create Surface Containers:**

**Grass:**
- Random Container: "Footsteps_Grass_RnC"
- 6 grass footstep clips
- Avoid Repeat Last: 2

**Metal:**
- Random Container: "Footsteps_Metal_RnC"
- 5 metal footstep clips
- Volume: 0.8 (louder)

**Wood:**
- Random Container: "Footsteps_Wood_RnC"
- 6 wood footstep clips
- Volume: 0.7

**Water:**
- Random Container: "Footsteps_Water_RnC"
- 5 water splash clips
- Volume: 0.65

**2. Create Switch Container:**
- Create → Switch Container
- Name: "Player_Footsteps_Switch_SwC"
- Inspector:
  - Switch Group Name: "Surface_Type"
  - Switch Entries:
    - [0] "Grass" → Footsteps_Grass_RnC
    - [1] "Metal" → Footsteps_Metal_RnC
    - [2] "Wood" → Footsteps_Wood_RnC
    - [3] "Water" → Footsteps_Water_RnC
  - Default Container: Footsteps_Grass_RnC
  - Is3D: ✓
  - Min Distance: 1
  - Max Distance: 15

**3. Create Event:**
- Event: "Play_Player_Footstep"
- Action: Play Player_Footsteps_Switch_SwC → Footsteps_Bus

#### Code

```csharp
using UnityEngine;
using AudioSystem;

public class SurfaceFootsteps : MonoBehaviour
{
    [SerializeField] private AudioEvent footstepEvent;
    [SerializeField] private LayerMask groundLayers;
    [SerializeField] private float raycastDistance = 2f;

    // Called from animation event
    public void PlayFootstep()
    {
        string surface = DetectSurface();
        AudioManager.Instance.SetSwitch("Surface_Type", surface);

        if (footstepEvent != null)
        {
            footstepEvent.Post(gameObject, transform.position);
        }
    }

    private string DetectSurface()
    {
        RaycastHit hit;
        Vector3 origin = transform.position + Vector3.up * 0.1f;

        if (Physics.Raycast(origin, Vector3.down, out hit, raycastDistance, groundLayers))
        {
            // Method 1: By tag
            if (hit.collider.CompareTag("Metal")) return "Metal";
            if (hit.collider.CompareTag("Wood")) return "Wood";
            if (hit.collider.CompareTag("Water")) return "Water";

            // Method 2: By material name
            Renderer renderer = hit.collider.GetComponent<Renderer>();
            if (renderer != null && renderer.sharedMaterial != null)
            {
                string matName = renderer.sharedMaterial.name.ToLower();

                if (matName.Contains("metal")) return "Metal";
                if (matName.Contains("wood")) return "Wood";
                if (matName.Contains("water")) return "Water";
            }

            // Method 3: By layer
            int hitLayer = hit.collider.gameObject.layer;
            if (hitLayer == LayerMask.NameToLayer("Metal")) return "Metal";
            if (hitLayer == LayerMask.NameToLayer("Wood")) return "Wood";
        }

        return "Grass"; // Default
    }

    void OnDrawGizmos()
    {
        Gizmos.color = Color.yellow;
        Vector3 origin = transform.position + Vector3.up * 0.1f;
        Gizmos.DrawLine(origin, origin + Vector3.down * raycastDistance);
    }
}
```

**Surface Tagging Methods:**

**Option 1 - Tags:**
```
Tag ground objects: "Metal", "Wood", "Grass", "Water"
Pro: Simple
Con: Limited to small number of tags
```

**Option 2 - Material Names:**
```
Name materials: "Floor_Metal", "Terrain_Grass", etc.
Pro: Unlimited surfaces
Con: Requires naming convention
```

**Option 3 - Layers:**
```
Create layers: Metal, Wood, Grass
Pro: Clean, performant
Con: Limited layer count
```

✅ **Result:** Realistic surface-dependent footsteps!

---

### Recipe: Footstep Timer (No Animation Events)

📋 **What:** Timer-based footsteps for procedural animation or simple movement

🎯 **Use Case:** Games without foot animation events, procedural animation

💻 **Code:**

```csharp
using UnityEngine;
using AudioSystem;

[RequireComponent(typeof(CharacterController))]
public class FootstepTimer : MonoBehaviour
{
    [Header("Audio")]
    [SerializeField] private AudioEvent footstepEvent;

    [Header("Timing")]
    [SerializeField] private float walkStepInterval = 0.5f;
    [SerializeField] private float runStepInterval = 0.3f;
    [SerializeField] private float minSpeedForFootsteps = 0.5f;

    private CharacterController controller;
    private float stepTimer = 0f;
    private bool wasGroundedLastFrame = false;

    void Start()
    {
        controller = GetComponent<CharacterController>();
    }

    void Update()
    {
        HandleFootsteps();
    }

    void HandleFootsteps()
    {
        // Check if moving and grounded
        float speed = new Vector3(controller.velocity.x, 0, controller.velocity.z).magnitude;
        bool isGrounded = controller.isGrounded;

        if (isGrounded && speed > minSpeedForFootsteps)
        {
            // Determine interval based on speed
            bool isRunning = speed > 5f; // Adjust threshold as needed
            float interval = isRunning ? runStepInterval : walkStepInterval;

            stepTimer -= Time.deltaTime;

            if (stepTimer <= 0f)
            {
                PlayFootstep();
                stepTimer = interval;
            }
        }
        else
        {
            // Reset timer when not moving or airborne
            stepTimer = 0f;
        }

        // Landing sound
        if (isGrounded && !wasGroundedLastFrame && speed > 1f)
        {
            PlayFootstep();
            stepTimer = (speed > 5f ? runStepInterval : walkStepInterval);
        }

        wasGroundedLastFrame = isGrounded;
    }

    void PlayFootstep()
    {
        if (footstepEvent != null)
        {
            footstepEvent.Post(gameObject, transform.position);
        }
    }
}
```

**Tuning Tips:**
```
Walk Interval: 0.4-0.6s
Run Interval: 0.25-0.35s
Min Speed: 0.3-0.8 units/sec
```

✅ **Result:** Automatic footsteps based on movement speed!

## Weapons & Combat

Source: https://peppersfx.com/docs/cookbook/weapons-combat/

### Recipe: Weapon Fire Sound

📋 **What:** Weapon shot with variations and instance limiting

🎯 **Use Case:** Guns, projectile weapons

#### Asset Setup

**1. Create Container:**
- Random Container: "Weapon_RifleShot_RnC"
- Audio Clips: 3-5 firing variations
- Avoid Repeat Last: 1
- Volume: 1.0
- Volume Randomization: ±1 dB
- Pitch Randomization: ±75 cents
- Is3D: ✓
- Min Distance: 5
- Max Distance: 50

**2. Create Event:**
- Event: "Play_Weapon_RifleShot"
- Priority: High
- Max Instances: 8
- Steal Behavior: Oldest
- Actions: Play Weapon_RifleShot_RnC → Weapons_Bus

#### Code

```csharp
using UnityEngine;
using AudioSystem;

public class WeaponAudio : MonoBehaviour
{
    [Header("Audio Events")]
    [SerializeField] private AudioEvent fireEvent;
    [SerializeField] private AudioEvent reloadEvent;
    [SerializeField] private AudioEvent emptyEvent;
    [SerializeField] private AudioEvent equipEvent;

    public void OnFire()
    {
        if (fireEvent != null)
        {
            fireEvent.Post(gameObject, transform.position);
        }
    }

    public void OnReload()
    {
        if (reloadEvent != null)
        {
            reloadEvent.Post(gameObject, transform.position);
        }
    }

    public void OnEmpty()
    {
        if (emptyEvent != null)
        {
            emptyEvent.Post(gameObject, transform.position);
        }
    }

    public void OnEquip()
    {
        if (equipEvent != null)
        {
            equipEvent.Post(gameObject, transform.position);
        }
    }
}
```

**Integration:**
```csharp
// In your weapon controller
public class WeaponController : MonoBehaviour
{
    private WeaponAudio weaponAudio;

    void Start()
    {
        weaponAudio = GetComponent<WeaponAudio>();
    }

    void Fire()
    {
        if (HasAmmo())
        {
            // Fire logic...
            weaponAudio?.OnFire();
        }
        else
        {
            weaponAudio?.OnEmpty();
        }
    }

    void Reload()
    {
        // Reload logic...
        weaponAudio?.OnReload();
    }
}
```

✅ **Result:** Professional weapon audio with variations!

---

### Recipe: Impact Sounds by Material

📋 **What:** Different impact sounds based on hit material

🎯 **Use Case:** Bullet impacts, melee hits, projectile collisions

#### Asset Setup

**1. Create Material Containers:**

- "Impact_Metal_RnC" (5-6 metal impact clips)
- "Impact_Wood_RnC" (5-6 wood impact clips)
- "Impact_Concrete_RnC" (5-6 concrete clips)
- "Impact_Flesh_RnC" (4-5 flesh/organic clips)
- "Impact_Default_RnC" (generic impacts)

**2. Create Switch Container:**
- Switch Container: "Impact_Switch_SwC"
- Switch Group Name: "ImpactMaterial"
- Entries:
  - "Metal" → Impact_Metal_RnC
  - "Wood" → Impact_Wood_RnC
  - "Concrete" → Impact_Concrete_RnC
  - "Flesh" → Impact_Flesh_RnC
- Default: Impact_Default_RnC

**3. Create Event:**
- Event: "Play_Impact"
- Priority: Medium
- Max Instances: 12
- Actions: Play Impact_Switch_SwC → SFX_Bus

#### Code

```csharp
using UnityEngine;
using AudioSystem;

public class ProjectileImpact : MonoBehaviour
{
    [SerializeField] private AudioEvent impactEvent;
    [SerializeField] private GameObject impactVFXPrefab;

    void OnCollisionEnter(Collision collision)
    {
        HandleImpact(collision);
    }

    void HandleImpact(Collision collision)
    {
        // Determine material
        string material = GetMaterialType(collision.collider);

        // Set switch
        AudioManager.Instance.SetSwitch("ImpactMaterial", material);

        // Play impact sound at contact point
        if (impactEvent != null && collision.contacts.Length > 0)
        {
            Vector3 impactPoint = collision.contacts[0].point;
            impactEvent.Post(gameObject, impactPoint);
        }

        // Spawn VFX
        if (impactVFXPrefab != null && collision.contacts.Length > 0)
        {
            Instantiate(impactVFXPrefab, collision.contacts[0].point,
                       Quaternion.LookRotation(collision.contacts[0].normal));
        }

        // Destroy projectile
        Destroy(gameObject);
    }

    string GetMaterialType(Collider hitCollider)
    {
        // Method 1: Check tag
        if (hitCollider.CompareTag("Metal")) return "Metal";
        if (hitCollider.CompareTag("Wood")) return "Wood";
        if (hitCollider.CompareTag("Enemy") || hitCollider.CompareTag("Player"))
            return "Flesh";

        // Method 2: Check layer
        int layer = hitCollider.gameObject.layer;
        if (layer == LayerMask.NameToLayer("Metal")) return "Metal";
        if (layer == LayerMask.NameToLayer("Wood")) return "Wood";

        // Method 3: Custom component
        var surfaceID = hitCollider.GetComponent<SurfaceIdentifier>();
        if (surfaceID != null)
            return surfaceID.MaterialType;

        return "Default";
    }
}

// Optional: Attach to surfaces for explicit material identification
public class SurfaceIdentifier : MonoBehaviour
{
    public string MaterialType = "Concrete";
}
```

✅ **Result:** Dynamic impact sounds matching hit materials!

## Music Systems

Source: https://peppersfx.com/docs/cookbook/music-systems/

### Recipe: Background Music (Intro + Loop)

📋 **What:** Music with intro that transitions to seamless loop

🎯 **Use Case:** Level music, menu music

#### Asset Setup

**1. Create Containers:**

**Intro:**
- Routing Container: "Music_MainTheme_Intro_RC"
- Audio Clips: [Intro clip]
- Loop: ☐ (no loop)
- Volume: 1.0
- Is3D: ☐ (2D)

**Loop:**
- Routing Container: "Music_MainTheme_Loop_RC"
- Audio Clips: [Loop clip]
- Loop: ✓ (loop enabled)
- Volume: 1.0
- Is3D: ☐ (2D)

**2. Create Event:**
- Event: "Music_Start_MainTheme"
- Priority: Medium
- Max Instances: 1
- Actions → Size: 2

**Action [0]:**
- Type: Play
- Container: Music_MainTheme_Intro_RC
- Target Bus: Music_Bus
- Delay: 0

**Action [1]:**
- Type: Play
- Container: Music_MainTheme_Loop_RC
- Target Bus: Music_Bus
- Delay: 8.5 ← **SET TO YOUR INTRO LENGTH IN SECONDS**

**3. Stopping it:** keep the handle `Post` returns and call `Stop` on it (see the code below). Don't make a separate "Music_Stop" event with a Stop action: a Stop action only stops sounds its own event started, so it can't stop this music.

#### Code

```csharp
using UnityEngine;
using AudioSystem;

public class MusicManager : MonoBehaviour
{
    [SerializeField] private AudioEvent startMusicEvent;
    [SerializeField] private bool playOnStart = true;

    private AudioHandle musicHandle;

    void Start()
    {
        if (playOnStart)
        {
            StartMusic();
        }
    }

    public void StartMusic()
    {
        if (startMusicEvent != null)
        {
            musicHandle = startMusicEvent.Post();
        }
    }

    public void StopMusic(float fadeTime = 2f)
    {
        if (musicHandle != null)
        {
            // Also cancels the loop if the intro is still playing.
            musicHandle.Stop(fadeTime);
            musicHandle = null;
        }
    }

    void OnDestroy()
    {
        StopMusic(1f);
    }
}
```

**Setup:**
1. Create empty GameObject: "MusicManager"
2. Attach MusicManager script
3. Assign the start event
4. Mark as DontDestroyOnLoad if needed

✅ **Result:** Intro plays once, then the loop takes over and repeats.

💡 **How close is the join?** A delayed action waits on a frame timer, so the loop starts within about one frame after the intro ends (≈16 ms at 60 fps; more if that frame is slow). With the event's Time on Scaled (the default), slow motion or a pause also stretches the wait, so set Time = Unscaled (§5.4) for music. On a hard musical cut that small gap can be heard. For a sample-accurate join, make two events (intro and loop, each with Delay 0) and start both on the audio clock yourself:

```csharp
[SerializeField] private AudioEvent introEvent, loopEvent;
[SerializeField] private AudioClip introClip;   // the intro's clip, for its exact length
private AudioHandle introHandle, loopHandle;

public void StartMusic()
{
    double start = AudioSettings.dspTime + 0.1;                           // a little ahead, so both are scheduled in time
    double introLength = (double)introClip.samples / introClip.frequency;  // exact, in seconds
    introHandle = introEvent.Post(gameObject, transform.position, start);
    loopHandle  = loopEvent.Post(gameObject, transform.position, start + introLength);
}
// To stop, Stop both handles.
```

This needs the intro's container to have no pitch randomization (a pitch change changes its length).

💡 **Switching tracks:** keep the handle `Post` returns and crossfade from it: `musicHandle = AudioManager.Instance.CrossFade(musicHandle, nextTrackEvent, 2f);`. That also cancels the delayed loop if the intro is still playing. A container crossfade from the intro would let the loop start anyway (see §10.3).

---

### Recipe: Dynamic Combat Music (3 Layers)

📋 **What:** Music that responds to combat intensity with layered crossfading

🎯 **Use Case:** Action games, dynamic gameplay music

#### Asset Setup

**1. Create Layer Containers:**

**Ambient Layer:**
- Routing Container: "Music_Ambient_RC"
- Clip: Calm ambient music loop
- Loop: ✓
- Volume: 1.0

**Tension Layer:**
- Routing Container: "Music_Tension_RC"
- Clip: Tense percussion/strings loop
- Loop: ✓
- Volume: 1.0

**Combat Layer:**
- Routing Container: "Music_Combat_RC"
- Clip: Full combat music loop
- Loop: ✓
- Volume: 1.0

**2. Create Blend Container:**
- Blend Container: "Music_Dynamic_Combat_BC"
- Blend Parameter Name: "CombatIntensity"
- Volume: 1.0
- Loop: ✓

**Blend Entries:**

**Entry [0] - Ambient:**
- Container: Music_Ambient_RC
- Volume Curve:
  - Key (0.0, 1.0) ← Full volume at calm
  - Key (1.0, 0.0) ← Silent at combat

**Entry [1] - Tension:**
- Container: Music_Tension_RC
- Volume Curve:
  - Key (0.0, 0.0) ← Silent at calm
  - Key (0.5, 1.0) ← Peak at medium intensity
  - Key (1.0, 0.0) ← Silent at full combat

**Entry [2] - Combat:**
- Container: Music_Combat_RC
- Volume Curve:
  - Key (0.0, 0.0) ← Silent at calm
  - Key (1.0, 1.0) ← Full at combat

**3. Create Event:**
- Event: "Music_Start_DynamicCombat"
- Actions: Play Music_Dynamic_Combat_BC → Music_Bus

#### Code

```csharp
using UnityEngine;
using AudioSystem;

public class DynamicCombatMusic : MonoBehaviour
{
    [Header("Audio")]
    [SerializeField] private AudioEvent startMusicEvent;

    [Header("Settings")]
    [SerializeField] private float transitionSpeed = 0.5f;
    [SerializeField] private float enemyDetectionRadius = 20f;
    [SerializeField] private LayerMask enemyLayer;

    [Header("Intensity Thresholds")]
    [SerializeField] private int calmEnemyCount = 0;
    [SerializeField] private int tensionEnemyCount = 2;
    [SerializeField] private int combatEnemyCount = 4;

    private float currentIntensity = 0f;
    private float targetIntensity = 0f;

    void Start()
    {
        StartMusic();
    }

    void StartMusic()
    {
        if (startMusicEvent != null)
        {
            startMusicEvent.Post();
        }
        AudioManager.Instance.SetRTPC("CombatIntensity", 0f);
    }

    void Update()
    {
        UpdateMusicIntensity();
    }

    void UpdateMusicIntensity()
    {
        // Calculate target intensity based on enemy count
        int enemyCount = CountNearbyEnemies();
        targetIntensity = CalculateIntensity(enemyCount);

        // Smooth transition
        if (Mathf.Abs(currentIntensity - targetIntensity) > 0.01f)
        {
            currentIntensity = Mathf.MoveTowards(
                currentIntensity,
                targetIntensity,
                transitionSpeed * Time.deltaTime
            );

            AudioManager.Instance.SetRTPC("CombatIntensity", currentIntensity);
        }
    }

    int CountNearbyEnemies()
    {
        Collider[] enemies = Physics.OverlapSphere(
            transform.position,
            enemyDetectionRadius,
            enemyLayer
        );
        return enemies.Length;
    }

    float CalculateIntensity(int enemyCount)
    {
        if (enemyCount <= calmEnemyCount)
            return 0f; // Ambient only

        if (enemyCount <= tensionEnemyCount)
            return 0.5f; // Tension layer

        if (enemyCount <= combatEnemyCount)
            return 0.75f; // Ramping up

        return 1f; // Full combat
    }

    void OnDrawGizmos()
    {
        Gizmos.color = Color.red;
        Gizmos.DrawWireSphere(transform.position, enemyDetectionRadius);

        // Show intensity
        #if UNITY_EDITOR
        UnityEditor.Handles.Label(transform.position + Vector3.up * 2f,
            $"Music Intensity: {currentIntensity:F2}");
        #endif
    }
}
```

**Setup:**
1. Attach to player or game manager
2. Configure detection radius and thresholds
3. Set enemy layer mask
4. Tune transition speed (0.3-0.8 recommended)

✅ **Result:** Music dynamically responds to combat!

## Rhythmic SFX

Source: https://peppersfx.com/docs/cookbook/rhythmic-sfx/

Use `BeatScheduler` (`AudioSystem.BeatScheduler`, MonoBehaviour in `RunTime/Utilities/`) for any SFX whose **rate must vary at runtime without changing pitch**: heartbeats, metronomes, clocks, sonar pings, reactor pulses. Instead of time-stretching one long clip (which shifts pitch), it re-posts a one-shot AudioEvent on a `60 / BPM` interval, anchored to `AudioSettings.dspTime` for stable cadence.

### Recipe: Stress-Driven Heartbeat

📋 **What:** Heartbeat whose BPM rises as the player sees an enemy or takes damage, with no pitch artefacts.

🎯 **Use Case:** Horror / survival / stealth — "I just saw something". Same pattern works for clock tension, reactor meltdown, alert pulse.

#### Asset Setup

**1. Create Container:**
- Random Container: "SFX_Heartbeat_Thump_RnC"
- Audio Clips: 2–3 thump variations (`heartbeat_01.wav`, `heartbeat_02.wav`, …) — each a single short thump, **not** a looping heartbeat loop
- Avoid Repeat Last: 1
- Loop: ☐
- Volume: 0.8
- Is3D: ☐ (2D — it's in the player's head)

> **Why one-shots, not a loop?** BPM is controlled by firing rate, not playback speed. If you use a loop, `source.pitch` is your only speed knob and it will rise in pitch alongside the tempo.

**2. Create Event:**
- Event: "Heartbeat_Thump"
- Priority: Medium-High (don't let combat SFX starve it)
- Max Instances: 4 (lets overlap at panic BPM without voice-stealing the ongoing thump)
- Actions: Play SFX_Heartbeat_Thump_RnC → Player_SFX_Bus

#### Scene Setup

1. On the player (or a dedicated child GameObject), add a `BeatScheduler` component
2. Drag the `Heartbeat_Thump` event asset into `Audio Event`
3. Set `Bpm` = 60 (calm baseline)
4. Leave `Play On Enable` = ✓, `Fire Immediately On Start` = ✓

#### Code

```csharp
using UnityEngine;
using AudioSystem;

public class StressHeartbeat : MonoBehaviour
{
    [Header("References")]
    [SerializeField] private BeatScheduler heartbeat;

    [Header("Tempo Range")]
    [SerializeField] private float calmBpm = 60f;
    [SerializeField] private float panicBpm = 160f;
    [SerializeField] private float smoothing = 2f; // BPM ramp rate

    [Header("Stress Inputs")]
    [SerializeField] private float sightRadius = 15f;
    [SerializeField] private LayerMask enemyMask;

    private float currentStress;  // 0..1, internal
    private float targetStress;

    private void Update()
    {
        // 1. Compute target stress from game state.
        targetStress = ComputeStress();

        // 2. Smooth it so BPM ramps instead of snapping.
        currentStress = Mathf.MoveTowards(currentStress, targetStress, smoothing * Time.deltaTime);

        // 3. Drive the scheduler. The NEXT beat uses this BPM; the one already queued fires at the old rate — this is musically natural.
        heartbeat.Bpm = Mathf.Lerp(calmBpm, panicBpm, currentStress);
    }

    private float ComputeStress()
    {
        // Example: closest enemy inside sight radius => stress 0..1.
        var hits = Physics.OverlapSphere(transform.position, sightRadius, enemyMask);
        if (hits.Length == 0) return 0f;

        float closest = sightRadius;
        foreach (var h in hits)
            closest = Mathf.Min(closest, Vector3.Distance(transform.position, h.transform.position));

        return 1f - Mathf.Clamp01(closest / sightRadius);
    }

    // Call these from your damage / sanity / stealth systems.
    public void Spike(float amount)    => targetStress = Mathf.Clamp01(targetStress + amount);
    public void ForceCalm()            => targetStress = 0f;
}
```

#### Variations

**Volume swell with BPM.** The thumps should also get a bit louder as you panic. BeatScheduler doesn't own an AudioSource, so drive the volume from the same stress value through a parameter. Make a global parameter asset `Stress` (0–1), write it each frame, and give it a **Volume** curve on the thump's container (§4.1) or on `Player_SFX_Bus` (bus Parameter Curves, §6.6), for example 0 → -6 dB, 1 → 0 dB:
```csharp
[SerializeField] private AudioParameter stressParam;   // the Stress parameter asset

// In Update, after computing currentStress. A bus curve reads the global value.
AudioManager.Instance.SetParameter(stressParam, currentStress);
```
Stay at or below 0 dB: a voice can't go louder than its authored level. A curve on the container affects only the thumps; one on the bus moves everything on that bus.

**Pause the heartbeat cleanly.** Disable the component (`heartbeat.enabled = false`) or `heartbeat.StopScheduling()`. Already-posted thumps finish naturally; no new ones fire.

**React on-beat with gameplay.** Subscribe to the scheduler's event to pulse a vignette, camera shake, or UI indicator in perfect sync with the thump:
```csharp
void OnEnable()  => heartbeat.OnBeat += PulseVignette;
void OnDisable() => heartbeat.OnBeat -= PulseVignette;
void PulseVignette() { /* flash post-processing, etc. */ }
```

✅ **Result:** Heartbeat cadence scales smoothly from 60 → 160 BPM. The thump itself always sounds like a thump — no chipmunk pitch-up, no CPU cost from real-time time-stretching.

---

### Recipe: Metronome / Rhythm Tick

📋 **What:** Fixed or adjustable tempo tick for rhythm games, timing tutorials, or in-engine practice tools.

#### Setup

- `BeatScheduler` component, `Audio Event` = the `Metronome_Tick` event asset
- For an accented downbeat (every 4th tick louder), subscribe to `OnBeat` and post a second event every 4 beats:

```csharp
public class Metronome : MonoBehaviour
{
    [SerializeField] private BeatScheduler beat;
    [SerializeField] private AudioEvent accentEvent; // e.g. Metronome_Accent
    [SerializeField, Range(1, 16)] private int beatsPerMeasure = 4;

    private int beatCount;

    private void OnEnable()  => beat.OnBeat += HandleBeat;
    private void OnDisable() => beat.OnBeat -= HandleBeat;

    private void HandleBeat()
    {
        if (beatCount % beatsPerMeasure == 0 && accentEvent != null)
            accentEvent.Post(gameObject, transform.position);
        beatCount++;
    }
}
```

✅ **Result:** Standard tick on every beat, accented thump on the 1.

## 3D Spatial Audio

Source: https://peppersfx.com/docs/cookbook/3d-spatial-audio/

### Recipe: Looping Campfire Sound

📋 **What:** 3D looping ambient sound attached to object

🎯 **Use Case:** Fire, machines, environmental loops

#### Asset Setup

**1. Create Container:**
- Random Container: "Ambience_Campfire_RnC"
- Audio Clips: 2-3 fire crackling loops
- Avoid Repeat Last: 1
- Loop: ✓
- Volume: 0.7
- Is3D: ✓
- Min Distance: 2
- Max Distance: 20
- Rolloff: Logarithmic

**2. Create Event:**
- Event: "Play_Ambience_Campfire"
- Priority: Low
- Max Instances: 10
- Actions: Play Ambience_Campfire_RnC → Ambience_Bus

#### Code

```csharp
using UnityEngine;
using AudioSystem;

public class CampfireAudio : MonoBehaviour
{
    [SerializeField] private AudioEvent fireEvent;
    [SerializeField] private bool playOnStart = true;

    private AudioHandle fireHandle;

    void Start()
    {
        if (playOnStart)
        {
            StartFire();
        }
    }

    void StartFire()
    {
        if (fireEvent != null)
        {
            fireHandle = fireEvent.Post(gameObject, transform.position);
        }
    }

    void StopFire(float fadeTime = 1f)
    {
        if (fireHandle != null)
        {
            fireHandle.Stop(fadeTime);
            fireHandle = null;
        }
    }

    // Optional: Adjust volume based on fire intensity
    public void SetIntensity(float intensity)
    {
        if (fireHandle != null)
        {
            fireHandle.SetVolumeScale(intensity);
        }
    }

    void OnDisable()
    {
        StopFire(0.5f);
    }

    void OnDestroy()
    {
        StopFire(0.2f);
    }

    void OnDrawGizmos()
    {
        Gizmos.color = Color.red;
        Gizmos.DrawWireSphere(transform.position, 2f);   // Min distance
        Gizmos.color = new Color(1, 0, 0, 0.3f);
        Gizmos.DrawWireSphere(transform.position, 20f);  // Max distance
    }
}
```

**Setup:**
1. Attach to campfire GameObject
2. Assign event
3. Sound follows object if it moves

✅ **Result:** Realistic 3D ambient loop!

## States & RTPCs

Source: https://peppersfx.com/docs/cookbook/states-rtpcs/

### Recipe: Underwater State

📋 **What:** Complete underwater audio effect

🎯 **Use Case:** Swimming, diving, underwater sections

#### Asset Setup

**1. Create States:**

**Normal State:**
- Audio State: "State_Normal"
- Save to: Assets/Resources/Audio/States/
- Inspector:
  - State Name: "Normal"
  - State Group: "Location"
  - (Leave all properties empty/default)

**Underwater State:**
- Audio State: "State_Underwater"
- Save to: Assets/Resources/Audio/States/
- Inspector:
  - State Name: "Underwater"
  - State Group: "Location"

**Bus Volumes:**
- [0] Bus: SFX_Bus, Volume Db: -9
- [1] Bus: Music_Bus, Volume Db: -12
- [2] Bus: Dialogue_Bus, Volume Db: -6

**Switch Values:**
- [0] Switch Group: "Location", Value: "Underwater"

**RTPC Values:**
- [0] Parameter: "Underwater", Value: 1.0

> A state sets the **global** value of a parameter, by name. To give it a range and a default, create a Parameter asset whose Parameter Name is "Underwater": the state and the asset share one value. Underwater is the same for every sound, so a global value is right here; per-object values go on an Audio Emitter (Manual §3.4).

**2. Create Underwater Ambience:**
- Routing Container: "Ambience_Underwater_RC"
- Clip: Underwater bubbles/muffled sound
- Loop: ✓
- Volume: 0.8
- Is3D: ☐ (2D)

**3. Create Event:**
- Event: "Play_Ambience_Underwater"
- Actions: Play Ambience_Underwater_RC → Ambience_Bus

#### Code

```csharp
using UnityEngine;
using AudioSystem;

public class UnderwaterVolume : MonoBehaviour
{
    [Header("Audio")]
    [SerializeField] private AudioEvent underwaterAmbienceEvent;
    [SerializeField] private float transitionTime = 1.5f;

    [Header("Optional VFX")]
    [SerializeField] private GameObject underwaterVFX;

    private AudioHandle ambienceHandle;
    private bool isUnderwater = false;

    void OnTriggerEnter(Collider other)
    {
        if (!other.CompareTag("Player")) return;

        if (!isUnderwater)
        {
            EnterUnderwater();
        }
    }

    void OnTriggerExit(Collider other)
    {
        if (!other.CompareTag("Player")) return;

        if (isUnderwater)
        {
            ExitUnderwater();
        }
    }

    void EnterUnderwater()
    {
        isUnderwater = true;

        // Activate underwater state
        AudioManager.Instance.SetState("Underwater", transitionTime);

        // Set location switch
        AudioManager.Instance.SetSwitch("Location", "Underwater");

        // Play underwater ambience
        if (underwaterAmbienceEvent != null)
        {
            ambienceHandle = underwaterAmbienceEvent.Post();
        }

        // Enable VFX
        if (underwaterVFX != null)
        {
            underwaterVFX.SetActive(true);
        }

        Debug.Log("Entered underwater");
    }

    void ExitUnderwater()
    {
        isUnderwater = false;

        // Return to normal state
        AudioManager.Instance.SetState("Normal", transitionTime);

        // Reset location switch
        AudioManager.Instance.SetSwitch("Location", "Normal");

        // Stop underwater ambience
        if (ambienceHandle != null)
        {
            ambienceHandle.Stop(transitionTime);
            ambienceHandle = null;
        }

        // Disable VFX
        if (underwaterVFX != null)
        {
            underwaterVFX.SetActive(false);
        }

        Debug.Log("Exited underwater");
    }

    void OnDrawGizmos()
    {
        Gizmos.color = new Color(0, 0, 1, 0.3f);
        Gizmos.DrawCube(transform.position, transform.localScale);
    }
}
```

**Setup:**
1. Create BoxCollider trigger volume for water
2. Attach UnderwaterVolume script
3. Assign underwater ambience event
4. Tag player as "Player"

✅ **Result:** Smooth transition to muffled underwater audio!

---

### Recipe: Vehicle Engine RPM

📋 **What:** Engine sound that changes with speed/RPM

🎯 **Use Case:** Cars, motorcycles, aircraft

#### Asset Setup

**1. Create Layer Containers:**

- "Engine_Idle_RC" (idle loop)
- "Engine_Load_RC" (medium RPM loop)
- "Engine_Redline_RC" (high RPM loop)
- Tick **Loop** on each of these, or set the Blend's **Loop Mode** to **Force Loop** (step 3).
- For a 3D engine, set **Doppler** to **Pepper** on the Blend (its 3D Settings; or Doppler Level 0 for none) and tick **Uses Parent Positioning** on each layer. Layers that go virtual then come back in step with the others; Unity's Doppler is the one pitch change Pepper can't follow (Manual §3.2, Voice Virtualization; §4.1 Doppler).

**2. Create a Parameter:**
- Parameter: "EngineRPM" (Create > Audio System > Parameter)
- Unit Label: "0-1", Min: 0, Max: 1, Default: 0.2 (idle)
- Smoothing: Ease, Rise 0.3 s, Fall 0.5 s. The engine follows the car's speed gently, the same at any frame rate, so the script below doesn't smooth anything itself.

**3. Create Blend Container:**
- Blend Container: "Vehicle_Engine_BC"
- Blend Parameter: the EngineRPM asset
- Loop Mode: Force Loop
- Silent Layers: Virtualize. Layers that are silent at the current RPM go virtual and free their real voices, coming back in step when the RPM reaches them (Manual §4.6).
- 3D Settings: **Is 3D** ticked and **Doppler** Pepper (or Doppler Level 0). The layers take both through Uses Parent Positioning (step 1); without Is 3D on the Blend the engine plays 2D, in the listener's head.

> **Each car has its own RPM.** The car posts its engine on its own **Audio Emitter** and sets the value there, so two cars playing this Blend each follow their own RPM. A value set globally (`SetRTPC("EngineRPM", ...)` or `AudioManager.SetParameter`) reaches only engines whose emitter has no value of its own. See Manual §3.4.

> **Engine loops recorded at known RPMs?** Use the parameter in real RPM (Min 0, Max 8000, Unit "RPM"), set each layer's **Root Value** to the RPM it was recorded at, switch the Blend's **Layout** to **Regions**, press **Auto Layout**, and set **Pitch Follow Parameter** to the same parameter. Every layer then crossfades at the right RPM and is pitched by RPM ÷ its recording, so the layers stay in tune with each other. In the script below, write the car's real RPM instead of the 0–1 value (`targetRPM` from the engine model, `idleRPM` in RPM, say 900) and untick **Modulate Pitch**: Pitch Follow does the pitching. See Manual §4.6. The **Engine Builder** (Manual §10.8) builds this whole tree, with on-load and off-load sets, from the selected loops, and **Detect Root Values** (§10.7) measures each loop's RPM.

**Entry [0] - Idle:**
- Container: Engine_Idle_RC
- Curve: (0.0, 1.0), (0.3, 0.5), (1.0, 0.0)

**Entry [1] - Load:**
- Container: Engine_Load_RC
- Curve: (0.0, 0.0), (0.5, 1.0), (1.0, 0.3)

**Entry [2] - Redline:**
- Container: Engine_Redline_RC
- Curve: (0.0, 0.0), (0.7, 0.2), (1.0, 1.0)

**4. Create Event:**
- Event: "Start_Vehicle_Engine"
- Actions: Play Vehicle_Engine_BC → SFX_Bus
- Persistent: ticked. The engine is never stolen to make room for other sounds (Manual §5.3).

**5. On the car:** add an **Audio Emitter** component (Add Component > Audio System > Audio Emitter) next to the script below, and set its **On Disable** to **Stop**: when the car is destroyed or switched off, its engine fades out over **Stop Fade Seconds** where it is and its voices go back to the pool (Manual §3.4). Left at Keep, the engine's voices sit under the car and are cut with it.

#### Code

```csharp
using UnityEngine;
using AudioSystem;

[RequireComponent(typeof(Rigidbody), typeof(AudioEmitter))]
public class VehicleEngineAudio : MonoBehaviour
{
    [Header("Audio")]
    [SerializeField] private AudioEvent engineStartEvent;
    [SerializeField] private AudioParameter engineRpm;   // the EngineRPM asset

    [Header("RPM Settings")]
    [SerializeField] private float maxSpeed = 30f;
    [SerializeField] private float idleRPM = 0.2f;

    [Header("Pitch Modulation")]
    [SerializeField] private bool modulatePitch = true;
    [SerializeField] private float minPitch = 0.8f;
    [SerializeField] private float maxPitch = 1.4f;

    private Rigidbody rb;
    private AudioEmitter emitter;
    private AudioHandle engineHandle;

    void Start()
    {
        rb = GetComponent<Rigidbody>();
        emitter = GetComponent<AudioEmitter>();
        StartEngine();
    }

    // Call this when the car is reset or teleported, so the engine doesn't glide across it.
    public void OnCarReset() => emitter.SnapAllParameters();

    void StartEngine()
    {
        if (engineStartEvent != null)
        {
            // Posted on this car's emitter: the engine reads this car's RPM.
            engineHandle = emitter.Post(engineStartEvent);
        }
    }

    void Update()
    {
        UpdateEngineRPM();
    }

    void UpdateEngineRPM()
    {
        // Calculate target RPM from speed
        float speed = rb.linearVelocity.magnitude;
        float targetRPM = Mathf.Clamp01(speed / maxSpeed);

        // Keep minimum idle RPM when not moving
        if (targetRPM < idleRPM)
            targetRPM = idleRPM;

        // This car's RPM, raw. The parameter's Smoothing eases what the engine hears; the Blend
        // picks it up after LateUpdate, before the frame's audio.
        emitter.SetParameter(engineRpm, targetRPM);

        // Optional: Modulate pitch by the smoothed RPM the engine is playing at
        float currentRPM = emitter.GetEffectiveParameter(engineRpm);
        if (modulatePitch && engineHandle != null)
        {
            // SetPitchOffset takes semitones. A playback-rate ratio r is 12 * log2(r) semitones:
            // 0.8 -> -3.9 st, 1.4 -> +5.8 st. It shifts on top of the layers' own pitch
            // randomization, if any, rather than replacing it.
            float pitchSemitones = Mathf.Lerp(
                12f * Mathf.Log(minPitch, 2f),
                12f * Mathf.Log(maxPitch, 2f),
                currentRPM
            );
            engineHandle.SetPitchOffset(pitchSemitones);
        }
    }

    // Engine off while the car stays (a stall, the key turned). Removing the car needs nothing here: its Audio
    // Emitter, set to On Disable = Stop, fades the engine out where it is.
    public void StopEngine()
    {
        engineHandle?.Stop(0.5f);
        engineHandle = null;
    }
}
```

✅ **Result:** Realistic engine sound that responds to speed!

> **Why no `OnDestroy`:** an earlier version posted a stop event there. A Stop action only stops its own event's sounds, so a separate stop event never reached the engine, and a `Stop(0.5f)` from `OnDestroy` can't fade voices that are destroyed with the car on the same frame. The emitter's On Disable = Stop does both jobs.

**Tuning by ear:** open **Window > Audio System > Audition** with the engine Blend selected, press Play and **Sweep** the RPM (say 900 → 7000 over 4 s, back and forth) while you adjust regions and root values in the Inspector; the Layers table shows each band's level and pitch (§10.5).

## Multi-Position Audio

Source: https://peppersfx.com/docs/cookbook/multi-position-audio/

### Recipe: Nightclub Speaker Setup

📋 **What:** 8 speakers playing synchronized music

🎯 **Use Case:** Nightclubs, concerts, speaker arrays

#### Asset Setup

**1. Create Container:**
- Routing Container: "Music_Nightclub_RC"
- Clip: Club music loop
- Loop: ✓
- Volume: 1.0
- Is3D: ✓
- Min Distance: 3
- Max Distance: 40

**2. Create Event:**
- Event: "Music_Start_Nightclub"
- Priority: Medium
- Max Instances: 1
- Actions: Play Music_Nightclub_RC → Music_Bus

There's no multi-position setting on the event. Posting it with `PostMultiPosition` is what plays it from every speaker.

#### Scene Setup

**1. Create Parent:**
- GameObject: "NightclubSpeakers"
- Add Component: AudioMultiPositionEmitterParent
- Inspector:
  - Max Emitters: 8
  - Auto Find Children: ✓
  - Auto Update Children: ✓

**2. Create Speakers (Manual or Auto):**

**Auto (Recommended):**
- Select NightclubSpeakers
- Inspector → Context Menu → "Create 8 Child Emitters (Circle Pattern)"
- Adjust radius and positions as needed

**Manual:**
- Create 8 child GameObjects
- Position in circle around dance floor
- Add AudioMultiPositionEmitterChild to each
- Configure:
  - Is Active: ✓
  - Volume Multiplier: 1.0
  - (Optional) Use Directionality ✓ and Cone Angle 90, then rotate to face inward: this only draws a cone in the Scene view to help you aim the speakers. It doesn't change what you hear.

#### Code

```csharp
using UnityEngine;
using AudioSystem;

public class NightclubAudio : MonoBehaviour
{
    [SerializeField] private AudioEvent musicEvent;
    [SerializeField] private bool playOnStart = true;

    private AudioMultiHandle musicHandle;
    private AudioMultiPositionEmitterParent emitterParent;

    void Start()
    {
        emitterParent = GetComponent<AudioMultiPositionEmitterParent>();

        if (playOnStart)
        {
            StartMusic();
        }
    }

    void StartMusic()
    {
        if (musicEvent != null && emitterParent != null)
        {
            musicHandle = musicEvent.PostMultiPosition(emitterParent);

            Debug.Log($"Playing music on {musicHandle.VoiceCount} speakers");
        }
    }

    public void StopMusic(float fadeTime = 2f)
    {
        if (musicHandle != null)
        {
            musicHandle.Stop(fadeTime);
            musicHandle = null;
        }
    }

    // Optional: Control individual speakers
    public void SetSpeakerVolume(int index, float volume)
    {
        var emitters = emitterParent.AllEmitters;
        if (index >= 0 && index < emitters.Count)
        {
            emitters[index].VolumeMultiplier = volume;
        }
    }

    public void ToggleSpeaker(int index, bool active)
    {
        var emitters = emitterParent.AllEmitters;
        if (index >= 0 && index < emitters.Count)
        {
            emitters[index].IsActive = active;
        }
    }

    void OnDestroy()
    {
        StopMusic(1f);
    }
}
```

✅ **Result:** 8 speakers playing perfectly synchronized music!

## Performance & Debugging

Source: https://peppersfx.com/docs/cookbook/performance-debugging/

### Recipe: Voice Count Display

📋 **What:** Real-time voice statistics HUD

🎯 **Use Case:** Development, profiling, debugging

💻 **Code:**

```csharp
using UnityEngine;
using AudioSystem;

public class AudioDebugHUD : MonoBehaviour
{
    [SerializeField] private bool showDebug = true;
    [SerializeField] private KeyCode toggleKey = KeyCode.F1;

    private GUIStyle style;

    void Start()
    {
        style = new GUIStyle();
        style.normal.textColor = Color.white;
        style.fontSize = 14;
        style.padding = new RectOffset(10, 10, 10, 10);
    }

    void Update()
    {
        if (Input.GetKeyDown(toggleKey))
        {
            showDebug = !showDebug;
        }
    }

    void OnGUI()
    {
        if (!showDebug || AudioManager.Instance == null) return;

        var stats = AudioManager.Instance.GetStatistics();

        int y = 10;
        int lineHeight = 20;

        GUI.Label(new Rect(10, y, 500, lineHeight),
            $"<color=yellow>AUDIO SYSTEM DEBUG (F1 to toggle)</color>",
            style);
        y += lineHeight + 5;

        GUI.Label(new Rect(10, y, 500, lineHeight),
            $"Active Voices: {stats.activeVoices} / {stats.totalVoices}",
            style);
        y += lineHeight;

        GUI.Label(new Rect(10, y, 500, lineHeight),
            $"Available Voices: {stats.availableVoices}",
            style);
        y += lineHeight;

        GUI.Label(new Rect(10, y, 500, lineHeight),
            $"Active Loops: {stats.activeLoops}",
            style);
        y += lineHeight;

        // Voice usage bar
        float usagePercent = (float)stats.activeVoices / stats.totalVoices;
        DrawUsageBar(new Rect(10, y, 300, 20), usagePercent);
    }

    void DrawUsageBar(Rect rect, float percent)
    {
        // Background
        GUI.color = Color.black;
        GUI.DrawTexture(rect, Texture2D.whiteTexture);

        // Fill
        Rect fillRect = new Rect(rect.x, rect.y, rect.width * percent, rect.height);

        if (percent < 0.7f)
            GUI.color = Color.green;
        else if (percent < 0.9f)
            GUI.color = Color.yellow;
        else
            GUI.color = Color.red;

        GUI.DrawTexture(fillRect, Texture2D.whiteTexture);

        GUI.color = Color.white;
    }
}
```

**Setup:**
1. Attach to any GameObject
2. Press F1 to toggle
3. Monitor voice usage in real-time

✅ **Result:** Development HUD showing audio system stats!

---

### Recipe: Event Callbacks for Debugging

📋 **What:** Log when sounds start/finish

🎯 **Use Case:** Debugging event flow, testing

💻 **Code:**

```csharp
using UnityEngine;
using AudioSystem;

public class AudioEventLogger : MonoBehaviour
{
    [SerializeField] private AudioEvent eventToMonitor;
    [SerializeField] private bool logToConsole = true;
    [SerializeField] private bool logToScreen = false;

    private string lastLog = "";
    private float logDisplayTime = 0f;

    void Start()
    {
        TestEvent();
    }

    void TestEvent()
    {
        if (eventToMonitor == null) return;

        AudioHandle handle = eventToMonitor.Post(gameObject, transform.position);

        if (handle != null)
        {
            handle.OnStarted += () => Log($"[{handle.EventName}] STARTED");
            // (OnLoop exists but isn't raised in this version, so it's left out here.)
            handle.OnFinished += () => Log($"[{handle.EventName}] FINISHED");
        }
    }

    void Log(string message)
    {
        if (logToConsole)
        {
            Debug.Log($"<color=cyan>{message}</color>");
        }

        if (logToScreen)
        {
            lastLog = message;
            logDisplayTime = Time.time;
        }
    }

    void OnGUI()
    {
        if (logToScreen && Time.time - logDisplayTime < 3f)
        {
            GUI.Label(new Rect(10, Screen.height - 30, 500, 20), lastLog);
        }
    }
}
```

✅ **Result:** Detailed event lifecycle logging!

## Occluding SFX Through Geometry

Source: https://peppersfx.com/docs/cookbook/occluding-sfx-through-geometry/

SFX voices can be muffled when walls or props stand between the listener and the emitter. The mechanism is the occlusion mixer slot pool (see Manual chapter 14 for the architecture). This section walks the authoring once, then shows how to opt individual containers into the system.

> 🧱 **This is the foundation for two other features too.** Per-Zone Reverb (`AllowReverbSend`) and container-level Ambient Propagation (`UsePropagation`) both acquire the **same Occlusion Slot** at play time. If you skip the slot-pool authoring in *One-Time Project Setup* below, none of the three features works fully — voices silently fall back to direct-to-bus routing with no low-pass and no sends, and no error message. Only occlusion's and propagation's volume drop still applies, because it doesn't need a slot. Author the layout once; opt individual containers in afterward.

> ⚠️ **Silent failures to know up front**
> - No `OcclusionLayout` authored → containers with `Use Occlusion` or `Use Propagation` only get quieter behind walls and doors (no low-pass), and `Allow Reverb Send` does nothing. No error.
> - Container's `Mixer Group` not in the layout's bus list → slot acquisition skipped silently, with the same result. Re-run the builder after adding new buses.
> - Occlusion doesn't check Is3D: a 2D voice is still tested from the listener to wherever its AudioSource sits, and muffled if that line is blocked. The flag also costs a slot — turn it off for UI/2D containers.
> - Slot pool exhausted → new voices route direct-to-bus (no low-pass, no sends; the volume drop still applies) and a console warning fires. Bump *Slots Per Bus* if you see it.

### Setup Path

Follow these in order. Steps 1–2 are required; the rest are per-container or per-feature opt-ins.

1. **One-Time Project Setup** — author the slot pool. *Do this once per project.*
2. **Occlude a Container** — flip `Use Occlusion` on each container that should be muffled.
3. *(Optional)* **Soften the Edge with Multi-Ray** — multi-ray smoothing.
4. *(Optional)* **Compose with Propagation** — let one container respect both walls and doors.

---

### Recipe: One-Time Project Setup (5 minutes)

📋 **What:** Author the slot layout so any container with `Use Occlusion = true` can be muffled at runtime.

🎯 **Use Case:** You're shipping SFX that should sound muffled behind cover, walls, or interior geometry. This is the prerequisite for every occluded sound in your project — author it once.

#### Asset Setup

**1. Create an OcclusionLayout asset:**
- Right-click in your Audio assets folder → Create → Audio System → Occlusion Layout
- Name it `OcclusionLayout` (one per project)

**2. Open the builder window:**
- Menu: Window → Audio System → Occlusion Layout

**3. Configure:**
- **Voice Mixer**: your project's voice mixer (where SFX are routed)
- **Occlusion Layout**: drag in the asset you just created
- **Slots Per Bus**: leave at 6 (the default sizes well for most SFX-heavy scenes; bump to 8–12 for weapon-dense gameplay)
- (Optional) **Reverb Send Bus Registry**: assign if you also use per-zone reverb sends — covered in the Per-Zone Reverb recipes below

**4. Click "Scan, Auto-Create, Refresh":**
- The builder walks the project for containers with `Use Occlusion`, `Allow Reverb Send` or `Use Propagation` turned on (each of the three takes a slot at play time), and for Ambient Sources with `Use Occlusion` in the open scenes. It collects the unique buses they play through (a layer with `Uses Parent Output` counts its Blend's or Switch's bus) and authors:
  - One `<BusName>_OcclusionLayer` child group per bus
  - Six slot groups under each (`<BusName>_Slot_00` through `<BusName>_Slot_05`)
  - A Lowpass effect with exposed cutoff parameter on each slot
- The results panel shows which buses got authored and any that failed (typically because the bus doesn't exist yet on the mixer)

**5. Wire AudioManager:**
- On your scene's AudioManager GameObject:
  - **Voice Mixer**: the same mixer asset
  - **Occlusion Layout**: the `OcclusionLayout` asset
  - **Default Occlusion Slots Per Bus**: 6 (matches the builder)
- Press Play. The Console should print `Occlusion slot pools ready — N bus(es), M slot(s) total.`

✅ **Result:** The infrastructure is live. Any container with `Use Occlusion = true` will now acquire a slot on Play, get its cutoff modulated by the raycast occlusion path every frame, and release the slot on completion.

---

### Recipe: Occlude a Weapon Fire Sound

📋 **What:** Turn on occlusion for a single container.

🎯 **Use Case:** Bullet impacts, weapon shots, footsteps — any SFX whose perceived loudness and brightness should drop when the listener can't see the emitter.

#### Asset Setup

**1. Open your container** (Random / Routing / Sequence — any type):
- Find the **"Use Occlusion"** toggle (under Mixer Settings)
- Set it to ✓ (true)

**2. Make sure the container is 3D:**
- Is3D: ✓
- Min Distance / Max Distance / Rolloff: set as appropriate
- Occlusion only modulates 3D-positioned sounds; 2D voices ignore the raycast

**3. Verify the container's Mixer Group is one of the buses the layout authored.** If not, re-run the Occlusion Layout Builder.

#### What Happens at Runtime

```csharp
weaponEvent.Post(gameObject, transform.position);
```

On Play:
1. `AudioManager.GetVoice(container)` acquires a free slot from the container's bus pool.
2. The voice's `outputAudioMixerGroup` is set to the slot's mixer group.
3. The OcclusionUpdate coroutine fires raycasts from listener → source every ~200 ms.
4. `LateUpdate` smooths the resulting cutoff target into the slot's exposed mixer parameter every frame.

When the listener walks behind a wall:
- The linecast hits geometry → blocked fraction climbs from 0 toward 1
- Gain target lerps from 1.0 → 0.3 (linear amplitude, ≈ -10 dB)
- Cutoff target lerps from 22 kHz → about 7 kHz (6.95 kHz when every ray is blocked). Propagation (`Use Propagation`) can take it lower: the most-muffled value wins
- Both axes settle in ~60 ms (configurable via `Occlusion Gain/Cutoff Smoothing Seconds` on AudioManager)

✅ **Result:** The weapon sound muffles when the listener is behind cover. No code changes — just the `Use Occlusion` toggle.

---

### Recipe: Soften the Occlusion Edge with Multi-Ray

📋 **What:** Fan 3–5 rays at the source to produce a continuous gradient instead of a binary in/out step.

🎯 **Use Case:** You want occlusion to feel natural as the listener walks past a wall edge, not "snap" the moment line-of-sight breaks.

#### Setup

On the AudioManager component:

- **Occlusion Ray Count**: 3 (default) or 5
- **Occlusion Ray Spread Meters**: 0.5 (default), 1–2 for larger emitters

With `RayCount = 3` and `Spread = 0.5 m`, the system fires a center ray plus two side rays at ±0.25 m perpendicular to the listener-source axis. The blocked fraction (0/3, 1/3, 2/3, or 3/3) lerps the gain and cutoff targets accordingly; the per-frame smoother rides over the discrete levels for continuous perception.

#### Tuning Notes

- **Ray Count = 1**: identical to the original binary occlusion path. Use when you want hard edges (cover-shooter rooms with tight corner-peeking).
- **Ray Count = 3**: four-level gradient. Best balance for most outdoor and large-interior scenes.
- **Ray Count = 5**: six-level gradient. Smoothest, but the cost is 5× raycasts — usually unnecessary above 3.
- **Spread Meters**: scale with emitter size. A door-sized emitter (1 m) wants 0.5 m spread; a vehicle-sized emitter (3 m) wants 1.5 m.

✅ **Result:** Walking past a wall edge produces a smooth gradient of muffling and uncovering, not a step at the exact moment line-of-sight breaks.

---

### Recipe: Compose Occlusion with Propagation

📋 **What:** Make an SFX container respect both raycast occlusion (walls) AND propagation routing (doors).

🎯 **Use Case:** A door-knock sound that should be both muffled by the door (propagation) and additionally muffled by any clutter between the listener and the door (raycast).

#### Setup

On the container:

- **Use Occlusion**: ✓ (raycast path)
- **Use Propagation**: ✓ (propagation path)

#### What Happens

Both paths feed `LateUpdate` independently. The composition is **most-muffled-wins**:

```
gainTarget   = raycastGain × propagationGain          (multiplicative)
cutoffTarget = min(raycastCutoff, propagationCutoff)  (min-wins for cutoff)
```

- If line-of-sight to the emitter is clear but the door is closed → propagation dominates (the cutoff comes from the door).
- If line-of-sight is blocked but the door is open → raycast dominates.
- If both are partly blocked → both contribute; the tightest cutoff wins.

When the listener is outside every registered AudioZone, propagation has no opinion. Default behavior keeps the SFX audible (`propGain = 1, propCutoff = 22kHz`); flip `PropagationManager.Silence Outside Graph` if you want a strict "outside means silent" coverage model instead.

✅ **Result:** A single SFX container that handles both routing-based muffling (doors, openings) and clutter-based occlusion (walls, props) in one place.

---

### Troubleshooting

**"My container has Use Occlusion = true but the sound doesn't muffle."**
- Does it get quieter behind a wall but keep its treble? Then occlusion runs but the voice has no slot: the volume drop doesn't need one, the low-pass does. Check the next three points.
- Did you assign `Voice Mixer` AND `Occlusion Layout` on AudioManager?
- Did you re-run the Occlusion Layout Builder after adding this container?
- Is the container's `Mixer Group` one of the buses in the layout? If you check the OcclusionLayout asset's `Buses` list and the container's bus isn't there, the layout is stale.
- Is the container 3D? Occlusion casts from the listener to the voice's AudioSource. It doesn't skip 2D voices, but their position rarely means anything, so use it on 3D sounds.

**"Console warns 'Occlusion slot pool exhausted on bus X'."**
- More concurrent occluded voices on that bus than slots configured. Bump `Slots Per Bus` on the Occlusion Layout asset, re-run Generate, and verify the warning stops.

**"Console warns '... on bus X, which has no slots in the Occlusion Layout'."**
- A container with `Use Occlusion`, `Allow Reverb Send` or `Use Propagation` played through a bus the layout has no slots for, so its sounds there get no low-pass and no reverb send. The layout was made before that bus needed slots. Click **Scan, Auto-Create, Refresh** in the Occlusion Layout window again. The warning comes once per bus, and only when an Occlusion Layout is assigned.

**"The first frame of audio clicks."**
- Almost never the slot system — slots are acquired before `Play()` precisely to avoid this. Suspect the clip itself: leading sample boundary, encoder pre-roll, or a Stop→Play on a non-pooled AudioSource elsewhere in the project.

**"My slot has a Lowpass on it but the cutoff parameter never changes."**
- Check `voiceMixer.GetFloat(slot.CutoffParam, …)` in a debug script. If it stays at 22000, the voice never opted in (container's `Use Occlusion` is off, container has no slot, or `OcclusionPerf` is skipping it due to a null container reference).
- The exposed-parameter name on the mixer must match `slot.CutoffParam` exactly. Re-run the layout builder if you've manually renamed mixer groups.

## Per-Zone Reverb

Source: https://peppersfx.com/docs/cookbook/per-zone-reverb/

The "wet path" sibling of the occlusion section. SFX voices send a copy of their dry signal to a per-zone reverb bus; each bus's character is defined by its `ReverbSendBus` asset, which is the single source of truth (the zone only decides *which* bus a voice sends to). See Manual chapter 15 for the architecture.

> 🧱 **Prerequisite: the Occlusion Slot Pool must already be authored.** Reverb sends are written into the voice's occlusion slot — no slot, no sends. If you haven't done it yet, jump to [Occluding SFX Through Geometry → One-Time Project Setup](https://peppersfx.com/docs/cookbook/occluding-sfx-through-geometry/#recipe-one-time-project-setup-5-minutes) first. Come back here once the layout exists.

> ⚠️ **Silent failures to know up front**
> - A bus's character lives on its `ReverbSendBus` asset, **not** the zone. A new bus's `Room` is `0` mB (millibels; full level), so it's audible once generated. A bus whose `Room` has been turned down to `-10000` mB is silent until you raise it. Tagging a zone and pointing its `Reverb Bus` at that asset routes voices there, but the *sound* comes from the asset.
> - The `Reverb Bus` field on `AudioZone` wants the **mixer group reference** inside the SendBus asset — not the SendBus asset itself. Drag from the SendBus's `ReverbBus` field, not from the Project window.
> - `AudioManager.Reverb Send Bus Registry` must be assigned. Without it, the registry is empty and nothing routes.
> - After adding a new bus, **re-run the Occlusion Layout Builder** so existing slots get the new bus's Send parameter authored. Skipping this means existing containers can't send to the new bus.

### Setup Path

Follow these in order. Each recipe assumes the previous one is done.

1. **Author a Reverb Send Bus** — once per acoustic archetype (small room, large hall, outdoors).
2. **Tag a Zone to Use This Bus** — for each physical room in your scene.
3. **Send an SFX Container Into the Reverb** — flip the per-sound `Allow Reverb Send` flag.
4. *(Optional)* **Override Routing for Music or Narration** — for sounds with authored, non-zone-driven character.
5. *(Optional)* **Tune a Bus's Character While Editing** — iteration workflow.

---

### Recipe: Author a Reverb Send Bus

📋 **What:** Create a single reverb bus and wire it up so voices physically in a tagged zone send to it.

🎯 **Use Case:** First step for any per-zone reverb in the project. Authoring is one-time per acoustic space.

#### Asset Setup

**1. Create the SendBus asset:**
- Project ▸ Create ▸ Audio System ▸ Reverb Send Bus
- Name it after the room: `Reverb_Bathroom` (the asset name becomes the bus id and the basis for exposed parameter names)

**2. Configure the SendBus:**
- **Reverb Mixer**: drag in your voice mixer asset (the same one assigned to AudioManager ▸ Voice Mixer)
- Leave **Reverb Bus** blank — it auto-fills on Generate
- Leave **Output Destination** blank for single-mixer setups (the wet tail flows up the group hierarchy naturally)
- (Optional) **Parent Group**: assign a `ReverbsWet` return-bus group if you use the DAW-style convention — Generate will nest this SendBus under it
- **Parametric reverb — Basic**:
  - Dry Level: -10000 (the default; SendBus groups are wet-only by design)
  - Room: 0 (overall wet gain; lower to attenuate)
  - Decay Time: tune for the space — bathroom ≈ 0.8 s, cathedral ≈ 5 s, cave ≈ 4 s
  - Reverb Level: 200 (Unity's SFX Reverb default)

**3. Generate:**
- Select the SendBus asset
- In the inspector, click **Generate Mixer Group**
- Console should log success: "Generated 'Bathroom': groups +1, effects +1, exposed params +6, values applied 14/14, output set: no"
- The mixer now has a `Bathroom` mixer group with an SFX Reverb effect; `Reverb_Bathroom_Wet`, `_Decay`, `_Room`, `_RoomHF`, `_DecayHFRatio`, `_Reflections` are exposed for the runtime driver

**4. Register the bus in the project registry:**
- Open Window ▸ Audio System ▸ Reverb Send Buses
- If no registry exists yet, create one: Project ▸ Create ▸ Audio System ▸ Reverb Send Bus Registry
- Drop the registry into AudioManager ▸ Reverb Send Bus Registry
- Click Refresh in the window — your new SendBus appears in the list

**5. Sanity-check:**
- Click Validate Wiring on the SendBus asset. It should say "Wiring OK."

✅ **Result:** The reverb bus exists on the mixer, exposes the right runtime parameters, and is registered. Voices won't send to it yet — that requires tagging an `AudioZone` (next recipe).

---

### Recipe: Tag a Zone to Use This Bus

📋 **What:** Tell an `AudioZone` "voices in here send to this reverb bus."

🎯 **Use Case:** After authoring a SendBus, every zone that should produce that bus's reverb needs to be tagged.

#### Asset Setup

**1. Select the AudioZone GameObject in your scene.**

**2. In the AudioZone component:**
- **Reverb Bus**: drag in the `Reverb_Bathroom` SendBus's `ReverbBus` field (open the SendBus inspector and drag from there — it's the mixer group reference). This is the only reverb setting on the zone.

The zone has no reverb character of its own. How the room sounds (Room, Room HF, Decay Time, Decay HF Ratio, Reflections, Reverb Level) is set on the `Reverb_Bathroom` SendBus asset from the previous recipe. To make two rooms sound different, give them separate SendBus assets.

#### What Happens at Runtime

- **Source-side**: voices in this zone whose container has `Allow Reverb Send = ✓` send a copy of their signal to `Reverb_Bathroom` at their authored level. The send level scales by the listener's audibility to the zone (1.0 same-zone, <1 through portals).
- **Listener-side**: the bus's six runtime-driven parameters are written from the SendBus asset every reverb-sends tick. They don't change with where the listener stands; only the send level does.

✅ **Result:** The bathroom zone is now acoustically alive. Voices in the bathroom contribute to the bathroom bus, which sounds the way its SendBus asset is authored.

---

### Recipe: Send an SFX Container Into the Reverb

📋 **What:** Flip an existing SFX container into the per-zone reverb path.

🎯 **Use Case:** Take a gunshot / footstep / impact container and have its voices contribute to the reverb of the room they're fired in.

#### Asset Setup

On the AudioContainer:

- **Allow Reverb Send**: ✓
- **Reverb Send Level Db**: per-sound tuning
  - 0 dB — full wet contribution. Right for big impacts (gunshots, explosions) that should ring out the room.
  - -6 dB — half-loud wet contribution. Good baseline for most SFX.
  - -12 dB — quiet wet contribution. Right for small detail sounds (footstep grain, weapon foley) that should colour the mix but not dominate the reverb.
  - -80 dB — effectively silent. Use `Allow Reverb Send = off` instead if you want zero contribution.
- **Static Emitter**: ✓ if the voice doesn't move during its lifetime (impacts, stingers, fixed-prop ambiences). Off for vehicle sounds, footsteps parented to a character, etc.

#### What Happens at Runtime

1. The container's `Use Occlusion` and `Allow Reverb Send` flags both feed the same slot decision: the voice acquires an OcclusionSlot on play (see chapter 14 §14.4).
2. `WriteReverbSendsImmediate` runs synchronously when the voice is configured, so its very first audio frame already has the correct send level.
3. The reverb-sends driver re-evaluates every ~50 ms while the voice is playing — sends respond to listener motion (audibility changes) even on static emitters.

✅ **Result:** This sound, fired anywhere in the world, contributes to whichever zone's reverb bus its source position is in — without any code changes.

---

### Recipe: Override Routing for Music or Narration

📋 **What:** Make a specific container *always* send to a fixed reverb bus, regardless of where the listener stands or what zone the source is in.

🎯 **Use Case:** Music that should always carry a "cathedral choir" reverb. Narrator VO that should always have a tight studio reverb. UI tails that should bypass per-zone routing. Anything whose acoustic character should be authored, not derived.

#### Asset Setup

On the AudioContainer:

- **Allow Reverb Send**: ✓
- **Explicit Reverb Bus**: drag in the target `ReverbSendBus` asset
- **Reverb Send Level Db**: as desired

#### What Happens at Runtime

Per-tick, the reverb-sends driver sees the explicit bus reference and takes the **explicit-bus short-circuit**:

- The named bus gets the container's `ReverbSendLevelDb` at all times (no audibility or membership scaling).
- Every other registered bus is silenced for this voice.
- Source zone resolution is bypassed entirely.

The voice's character is now authored, not zone-derived. Listener motion changes nothing about the routing.

✅ **Result:** A music container that always plays with cathedral reverb, regardless of whether the player is inside a cathedral or outdoors.

---

### Recipe: Tune a Bus's Character While Editing

📋 **What:** Iterate on a reverb's sound by tweaking values on the SendBus asset and pushing them to the mixer without re-running the full Generate.

🎯 **Use Case:** Dialing in a room's character during gameplay-tuning sessions.

#### Workflow

**Option A — Edit the SO, push to mixer:**
1. Select the `ReverbSendBus` asset
2. Tweak Decay Time, Room HF, Reflections Level, etc. on the SO
3. Click **Apply Params → Mixer**
4. Enter play mode and listen

Use when the SO is your source of truth. Apply Params skips the group/effect/expose work and only writes the parametric values — fast iteration.

**Option B — Edit the mixer window, pull back to SO:**
1. Open the Audio Mixer window, select the SendBus's group
2. Edit the SFX Reverb effect's parameters directly (snapshot must be the target snapshot, which is the default for fresh mixers)
3. Back on the SendBus asset inspector, click **Pull Params ← Mixer**
4. The SO now reflects your mixer-window tweaks

Use when the mixer window's UI is more convenient (it has the per-parameter sliders right there). Pull ensures the SO catches up so re-running Generate later doesn't undo your work.

⚠️ **Caveat:** Generate always overwrites the mixer effect's parameter values from the SO. If you've been tuning in the mixer window without pulling, Generate will wipe your tweaks. The safe workflow is Edit-mixer → Pull → Generate, or just stay on Option A.

✅ **Result:** Live iteration on reverb character without breaking the schema or losing changes.

---

### Troubleshooting

**"My voice has `Allow Reverb Send = ✓` but I hear no wet tail."**
- Confirm `AudioManager.ReverbSendBusRegistry` is assigned and contains at least one bus.
- Confirm the source's zone has its `ReverbBus` field set to a bus that's in the registry.
- Confirm the bus's `ReverbSendBus` asset isn't silent: a parametric bus with `Room` at -10000 mB produces no tail — raise it toward 0 (the default). A convolution bus with no `Impulse Response` assigned is likewise silent.
- Confirm the listener can reach the source's zone (unreachable zones produce audibility = 0).
- Confirm the container's `Mixer Group` is a bus that appears in the Occlusion Layout's bus list — without a slot, there are no Send level params to write to.

**"Several zones share one bus and they all sound identical."**
- This is **by design** as of the source-of-truth unification: a bus has one acoustic identity, defined by its `ReverbSendBus` asset, regardless of which zone routed the voice to it. Per-zone variation on a *shared* bus is no longer supported.
- If you need Cathedral and Cathedral_Crypt to sound different, give them **separate** `ReverbSendBus` assets and point each zone's `ReverbBus` at its own.

**"I added a new ReverbSendBus but it doesn't appear in the dropdowns."**
- Open Window ▸ Audio System ▸ Reverb Send Buses and click Refresh. The registry only updates when refreshed.
- After refreshing, re-run the Occlusion Layout Builder so existing occlusion slots get the new bus's Send param authored.

**"Voices on this bus sound dry on the first frame, then reverb kicks in."**
- This was a previous bug — voices used to play dry for up to one driver tick (50 ms) before sends were written. The fix is `WriteReverbSendsImmediate`, which is called synchronously by `AudioContainer.ConfigureAudioSource`. If you're seeing this on a custom playback path that bypasses `ConfigureAudioSource`, call `WriteReverbSendsImmediate(voice, container)` yourself right after setting `voice.OcclusionSlot`.

**"My mixer-window tweaks vanish whenever I re-Generate."**
- Generate is non-destructive *only if the SO already matches the mixer*. Click Pull Params ← Mixer first to sync the SO to your live tweaks, then Generate becomes a no-op on those values. Or stay in the SO-first workflow and use Apply Params → Mixer for iteration.

## Ambient Propagation

Source: https://peppersfx.com/docs/cookbook/ambient-propagation/

**New in v2.3.0.** Zone/portal routing for long-running ambient beds (rain, wind, machinery, river). The propagation subsystem ships *alongside* the SFX event pipeline — both systems coexist on the same AudioManager and mixer. Use SFX events for discrete sounds, propagation for persistent environmental beds that need to route through geometry.

> 🧱 **Two propagation paths, only one needs slots.**
> - **`AmbientSource` path** (the recipes in this section: rain, doors, weather) uses its own `AmbientEmitter` pool. **No occlusion slots required.** Author zones, portals, and ambient sources and you're done.
> - **Container `Use Propagation` path** (an `AudioContainer` with the `Use Propagation` flag — see [Compose Occlusion with Propagation](https://peppersfx.com/docs/cookbook/occluding-sfx-through-geometry/#recipe-compose-occlusion-with-propagation) in the Occlusion topic) acquires an Occlusion Slot exactly like reverb sends do. **That path needs the Occlusion Slot Pool authored first.**

> ⚠️ **Silent failures to know up front**
> - No `Audio Listener Zone Tracker` on the player object (the one with the Collider), or it's on the camera that holds the AudioListener instead → listener's zone is always null, all propagation is silent.
> - Portal collider doesn't overlap both zone colliders by ≥ 5 cm → portal is rejected in `OnValidate`. Check the inspector for the red error.
> - Portal +Z not pointing through the opening → blend axis is wrong, sound doesn't pan toward the gap.
> - Loop boundary click in your clip → the emitter loops as-authored, Unity won't fix a bad seam. Crossfade the WAV.
> - Outdoor source zone with finite `activationRadius` → source culls when the listener walks deep indoors. Use `float.PositiveInfinity` for sky/world sources.

### Setup Path

For each ambient bed you want, follow these in order:

1. **Define Zones** — author one `AudioZone` per acoustic space.
2. **Connect with Portals** — one `AudioPortal` per doorway/window between zones.
3. **Add an Ambient Source** — looping clip + source zone.
4. *(Optional)* **Door Source** — drive a portal's open/closed state from a game system.
5. *(Optional)* **Intensity Driver** — script-control the source's base volume.

**Scene prerequisites** (one-time): `AudioManager` + `AudioListener` in the scene; an `Ambience` mixer group (or any group of your choice); the player object (the one with the Collider, not the camera) has the `Audio Listener Zone Tracker` component. Recipes below assume these are in place.

---

### Recipe: Rain That Leaks Through a Window

📋 **What:** Outdoor rain audible inside a room only through an open window — quieter, dull, and panned toward the window as the listener walks along the opposite wall.

🎯 **Use Case:** Any ambient bed originating outside a closed interior — weather, traffic, a distant waterfall.

#### Scene Setup

**1. Two AudioZones:**
- `Zone_Outdoors` — huge BoxCollider enveloping the outdoor space
- `Zone_LivingRoom` — BoxCollider filling the room interior
- On each: Add → `Audio/Propagation/Audio Zone`
- For the outdoor zone, set `activationRadius = Infinity` (so the source doesn't get culled when the player is deep inside the house)

**2. One AudioPortal at the window:**
- Empty GameObject at the window frame
- BoxCollider sized ~1m × 1.2m × 0.4m spanning the opening
- Add → `Audio/Propagation/Audio Portal`
- Drag `Zone_Outdoors` into `ZoneA`, `Zone_LivingRoom` into `ZoneB`
- Orient the GameObject so its **+Z points through the opening**
- Inspector settings:
  - `Base Transmission = 0.6` (open window ≈ -4 dB)
  - `Closed Transmission = 0.1` (≈ -20 dB; doesn't matter if Door Source is null)
  - `Open Low Pass Hz = 12000`
  - `Closed Low Pass Hz = 600`
  - Leave `Door Source` **null** — windows don't swing

**3. The rain source:**
- Empty GameObject anywhere outside (say, above the house roof)
- Add → `Audio/Propagation/Ambient Source`
- Inspector:
  - `Source Zone = Zone_Outdoors`
  - `Looping Clip = Rain_Heavy_Loop.wav` (must be loop-authored!)
  - `Ambience Mixer Group = Ambience` (any mixer group you like)
  - `Source Base Volume Db = 0`

#### Code

None needed. The subsystem self-boots:
- `PropagationManager` auto-instantiates on the first `AudioZone.OnEnable`
- The listener tracker enters/exits zones on trigger crossings
- The solver runs at 15 Hz and drives the pooled `AmbientEmitter`

✅ **Result:**
- Standing outside → rain plays flat at 0 dB, no filtering
- Walking indoors → rain muffles down to ~-20 dB, high-frequency content rolled off by the window
- As you walk past the window wall, the virtual emitter slides along the frame so the rain pans naturally

---

### Recipe: Door That Swings Between Muffled and Clear

📋 **What:** A bedroom door connecting a hallway to the street. As the door animates open/closed, propagation parameters interpolate smoothly in real time.

🎯 **Use Case:** Any door (physical or magical) that can change state during gameplay.

#### Scene Setup

**1. Three zones** (same pattern as above): `Zone_Street`, `Zone_Hallway`, `Zone_Bedroom`.

**2. Two portals:**
- Portal at the bedroom door → connects `Zone_Hallway` ↔ `Zone_Bedroom`, **has a Door Source**
- Portal at the front entrance → connects `Zone_Street` ↔ `Zone_Hallway`, can have its own Door Source or be null

**3. The door adapter:** Propagation doesn't know about your door system. Write a thin adapter that exposes `OpenProgress` and fires `OnChanged` when the state changes:

```csharp
using System;
using UnityEngine;
using AudioSystem.Propagation;

[RequireComponent(typeof(Animator))]
public class AnimatorDoorToPortal : MonoBehaviour, IPortalDoorSource
{
    [SerializeField] private string openParameterName = "openAmount";

    private Animator animator;
    private float lastReported = -1f;

    public float OpenProgress => animator != null
        ? Mathf.Clamp01(animator.GetFloat(openParameterName))
        : 0f;

    public event Action OnChanged;

    void Awake() => animator = GetComponent<Animator>();

    void Update()
    {
        // Only fire OnChanged on meaningful deltas — the portal re-solves
        // immediately whenever we raise this event, so don't spam every frame.
        float now = OpenProgress;
        if (Mathf.Abs(now - lastReported) >= 0.02f)
        {
            lastReported = now;
            OnChanged?.Invoke();
        }
    }
}
```

**4. Hook it up:** Drop the `AnimatorDoorToPortal` component on whatever GameObject drives your door (usually the door model root). Drag it into the bedroom `AudioPortal`'s `Door Source` field.

#### Code

```csharp
// Nothing — the door animation alone drives audio.
// If you want to script-toggle the door:
void OpenDoor()  => GetComponent<Animator>().SetBool("open", true);
void CloseDoor() => GetComponent<Animator>().SetBool("open", false);
```

✅ **Result:**
- Door closed → bedroom sits at near-silent muffled roar (~-26 dB + 600 Hz low-pass applied to the already-filtered path)
- Door animates open → transmission and cutoff interpolate every frame the animator changes `openAmount`
- Door slams closed mid-step → smooth attenuation, no pops

**Gotcha:** If your animator parameter is stepped (0/1 only), the portal transitions will still be smooth on the audio side thanks to per-frame emitter smoothing — but they'll be less perceptually natural than an animation that ramps. Prefer a continuous float parameter on the animator when possible.

---

### Recipe: L-Shaped Room with Multiple Colliders

📋 **What:** A corridor that bends at a right angle, or a room with an alcove. Single BoxCollider won't cover the shape cleanly.

🎯 **Use Case:** Any non-rectangular acoustic space.

#### Scene Setup

1. On the AudioZone GameObject, **add multiple BoxCollider components** (one for each leg of the L, each with `isTrigger = true`)
2. Size them to cover the real interior. A small overlap at the corner is fine — `ContainsPoint` is OR-across all colliders
3. Do NOT add multiple `AudioZone` components; just more colliders on the same GameObject

```
GameObject "Zone_LShapedCorridor"
  ├─ AudioZone               (single component)
  ├─ BoxCollider (horizontal leg)
  └─ BoxCollider (vertical leg)
```

✅ **Result:** The zone behaves as one logical room. Authoring error detection (`OnValidate`) treats all triggers uniformly. Portals that overlap *any* of the zone's colliders are accepted.

**Future-proofing:** `AudioZone.ContainsPoint` and `ClosestSurfacePoint` are `virtual` — if you later need sphere or mesh shapes, subclass `AudioZone` and override those two methods. No changes to the solver or manager required.

---

### Recipe: Weather Intensity Drives Rain Volume

📋 **What:** A `Weather_RainIntensity` global value (0..1) smoothly crossfades the rain bed from silent to 0 dB.

🎯 **Use Case:** Dynamic weather systems, seasonal changes, gameplay intensity scaling.

#### Code

```csharp
using UnityEngine;
using AudioSystem.Propagation;

public class RainIntensityDriver : MonoBehaviour
{
    [SerializeField] private AmbientSource rainSource;
    [Range(-60f, 0f)] [SerializeField] private float quietDb = -40f;
    [Range(-60f, 0f)] [SerializeField] private float loudDb  = 0f;

    /// <summary>Call this from your weather / gameplay system. 0..1.</summary>
    public void SetRainIntensity(float t)
    {
        if (rainSource == null) return;
        float db = Mathf.Lerp(quietDb, loudDb, Mathf.Clamp01(t));
        rainSource.SetBaseVolumeDb(db);
    }
}
```

The base volume is picked up on the next solve tick (15 Hz default ≈ 67 ms). Propagation attenuation is subtracted from it, so lowering base volume during a lull will still produce the correct filtered-and-quieter result through doorways.

✅ **Result:** One knob → rain swells or fades globally, while all of the per-portal routing, blending, and filtering stays correct.

---

### Troubleshooting

**"Rain sounds full-volume indoors."**
- Check the portal's `+Z` points through the opening. If the portal's forward is parallel to the wall, the blend axis is wrong.
- Inspector error on the portal GameObject? Zone colliders must overlap the portal collider by ≥ 5 cm.

**"I hear a pop when crossing a doorway."**
- Clip isn't loop-authored. The emitter is set to `loop = true` — Unity won't fix a boundary click in the clip itself. Edit the clip, crossfade the seams.

**"No sound at all — AudioZones are registered but silent."**
- Is the `Audio Listener Zone Tracker` on your player object, the one with the Collider? On the camera that holds the AudioListener it gets no trigger events, so the listener's zone is always null.
- Confirm the `Ambience Mixer Group` isn't muted or at -∞ dB.
- Check the `activationRadius` on your source zone. Outdoor source zones should usually use `float.PositiveInfinity`.

**"Opening the door doesn't change anything."**
- Your `IPortalDoorSource` implementation needs to fire `OnChanged`. Without it, portals poll via the solve tick (~67 ms max latency at the default 15 Hz); with it, solves run immediately on state change.

**"The listener spawns inside a room and hears nothing until they walk out and back in."**
- Make sure the listener GameObject has a Rigidbody (the tracker auto-adds a kinematic one) and the zone collider's `isTrigger = true` (the zone's `OnValidate` enforces this).
- Propagation scans for listener membership on first frame — if that still misses, it's likely a layer/collision-matrix issue.

## Appendix: Quick Reference

Source: https://peppersfx.com/docs/cookbook/appendix-quick-reference/

### Common Tasks Cheat Sheet

**Play Sound:**
```csharp
myEvent.Post();
myEvent.Post(gameObject, transform.position);
```

**Control Playback:**
```csharp
AudioHandle h = myEvent.Post();
h.SetVolumeScale(0.5f);
h.SetPitchOffset(2f);
h.Stop(1f);
h.Pause();
h.Resume();
```

**Bus Volume:**
```csharp
AudioManager.Instance.SetBusVolume("Music", -6f, 1f);
```

**State:**
```csharp
AudioManager.Instance.SetState("Underwater", 1.5f);
```

**Switch:**
```csharp
AudioManager.Instance.SetSwitch("Surface_Type", "Metal");
```

**RTPC:**
```csharp
AudioManager.Instance.SetRTPC("CombatIntensity", 0.75f);
```

**Multi-Position:**
```csharp
AudioMultiHandle mh = myEvent.PostMultiPosition(emitterParent);
mh.SetVolumeScale(0.8f);
mh.SetVoiceVolumeScale(0, 0.5f);  // Per-emitter control
mh.Stop(2f);
```

## Manual: overview

Source: https://peppersfx.com/docs/manual/overview/

The Manual is the system's deep reference — architecture, design rationale, and chapter-by-chapter coverage of every subsystem. Read it once front-to-back to build a mental model, or jump straight to the chapter you need.

#### Manual Chapters

1. [Introduction](https://peppersfx.com/docs/manual/introduction/) — what this manual covers, prerequisites, how to read it
2. [System Architecture](https://peppersfx.com/docs/manual/system-architecture/) — design philosophy, the audio pipeline, component hierarchy
3. [Core Components](https://peppersfx.com/docs/manual/core-components/) — AudioManager, voice pool, GainStack, scheduling, parameters and scopes, emitters (offsets, moving sounds, teleports)
4. [Audio Containers](https://peppersfx.com/docs/manual/audio-containers/) — Routing / Random / Sequence / Switch / Blend, and engines generated live (Unity 6.3+)
5. [Events System](https://peppersfx.com/docs/manual/events-system/) — AudioEvent, EventAction, posting (timed posts, length estimates) and lifecycle
6. [Bus & Mixing](https://peppersfx.com/docs/manual/bus-mixing/) — bus hierarchy, ducking (the deepest wins), effect sends, pausing a bus, the player's volume
7. [State System](https://peppersfx.com/docs/manual/state-system/) — states, state groups, transitions, offset states for mixes
8. [Multi-Position Audio](https://peppersfx.com/docs/manual/multi-position-audio/) — synchronized playback across multiple positions
9. [Performance & Optimization](https://peppersfx.com/docs/manual/performance-optimization/) — voice budgets, virtualization, LOD
10. [Advanced Features](https://peppersfx.com/docs/manual/advanced-features/) — occlusion, ducking, crossfading, beat scheduling, and the sound tools: Audition, Live View and recording, Loop Analysis, Engine Builder, the validator, Engine Grains
11. [Best Practices](https://peppersfx.com/docs/manual/best-practices/) — recommended patterns for production projects
12. [Troubleshooting](https://peppersfx.com/docs/manual/troubleshooting/) — common failure modes and diagnosis
13. [Ambient Propagation Subsystem](https://peppersfx.com/docs/manual/ambient-propagation-subsystem/) — zone/portal graph routing for long-running beds
14. [Occlusion Mixer Slot Pool](https://peppersfx.com/docs/manual/occlusion-mixer-slot-pool/) — per-bus slot pools, multi-ray occlusion, propagation composition
15. [Reverb Send Buses & Per-Zone Reverb](https://peppersfx.com/docs/manual/reverb-send-buses-per-zone-reverb/) — source-side routing and listener-side bus-character driver
16. [Audio Loading & Memory](https://peppersfx.com/docs/manual/audio-loading-memory/) — import policy, clip warming, and the optional Addressables backend
17. [Multiplayer (Netcode)](https://peppersfx.com/docs/manual/multiplayer-netcode/) — backend-agnostic networked audio (NGO / FishNet); dedicated servers (Inert)

Appendices: [Glossary](https://peppersfx.com/docs/manual/appendix-a-glossary/), [Quick Reference](https://peppersfx.com/docs/manual/appendix-b-quick-reference/).

## Introduction

Source: https://peppersfx.com/docs/manual/introduction/

### 1.1 What This Manual Covers

This manual provides complete technical documentation of Pepper.SFX. By the end, you'll understand:

- **System Architecture** - How everything fits together
- **Component Deep-Dives** - Every class, method, and property explained
- **Design Patterns** - Industry-standard audio middleware concepts
- **Performance Optimization** - Voice management, LOD, virtualization
- **Best Practices** - Proven patterns from professional audio design
- **Troubleshooting** - Solutions to common problems

### 1.2 Prerequisites

Before reading this manual, you should:

- Have basic Unity knowledge (GameObjects, Components, Scripts)
- Understand audio concepts (dB, Hz, spatialization)
- Have read **QUICK_START.md** and successfully played a sound
- Know basic C# programming

### 1.3 How to Use This Manual

This manual is dense by design — every chapter has to serve three different readers:

- 🏃 **Skimmer:** Read each chapter's intro paragraph and the §X.1 ("Why...") subsection. That builds a map. Come back for details when you actually need them.
- 📖 **Learner:** Read chapters 1–6 in order to build a complete mental model, then read the subsystem chapters (13, 14, 15) as you adopt those features.
- 🔍 **Reference reader:** Jump to the section whose title matches your question. Use the Table of Contents at the top.

**For Troubleshooting:** Skip to Section 12 for common issues and diagnoses.

> ⚠️ **Spatial audio (Occlusion, Reverb Sends, container Propagation) shares one piece of infrastructure: the Occlusion Slot Pool (Chapter 14).** If you plan to use any of these features, author the slot pool first or none of them will work. The Cookbook's [spatial-audio prerequisite callout](https://peppersfx.com/docs/cookbook/overview/) explains why.

### 1.4 Companion Documents

- **QUICK_START.md** - Get running in 10 minutes
- **COOKBOOK.md** - Step-by-step recipes for common tasks
- **API_REFERENCE.md** - Complete API documentation

## System Architecture

Source: https://peppersfx.com/docs/manual/system-architecture/

### 2.1 Design Philosophy

Pepper.SFX follows three core principles:

#### Principle 1: Data-Driven Design

**Traditional Approach:**
```csharp
// Hard-coded, tightly coupled
AudioSource.PlayClipAtPoint(explosionClip, transform.position);
```

**Pepper.SFX Approach:**
```csharp
// Data-driven, decoupled
explosionEvent.Post(gameObject, transform.position);
```

**Why It Matters:**
- Audio designers work independently in Unity Editor
- No code changes to modify sounds
- ScriptableObjects enable version control and team collaboration
- Iteration is instant (no recompile)

#### Principle 2: Event-Based Triggering

**What:** Code triggers events, not direct audio playback.

**Benefits:**
- **Decoupling:** Game logic doesn't know about audio implementation
- **Flexibility:** Same event can trigger different sounds based on game state
- **Organization:** Events are named, searchable assets
- **Power:** Events can execute multiple actions (play, stop, set RTPC, etc.)

**Example:**
```csharp
// One event, multiple outcomes based on state
footstepEvent.Post();
// → Plays grass sound if on grass
// → Plays metal sound if on metal
// → Controlled by switch system
```

#### Principle 3: Hierarchical Organization

**Buses:** Tree structure for mixing
**States:** Grouped for mutual exclusivity
**Containers:** Composable playback behaviors

**Example Hierarchy:**
```
Master Bus (-3dB)
├── SFX Bus (0dB)
│   ├── Player (0dB)
│   ├── Enemies (-3dB)
│   └── Ambience (-6dB)
├── Music Bus (-6dB)
└── Dialogue Bus (0dB)
```

### 2.2 The Audio Pipeline

Understanding the complete flow from code to speaker:

```
1. Game Code
   ↓ myEvent.Post(gameObject, position)

2. AudioEvent (ScriptableObject)
   ↓ Execute Actions (Play, SetRTPC, SetState, etc.)

3. Container Selection
   ↓ Via Switch/State/Direct reference

4. AudioContainer (ScriptableObject)
   ↓ container.Play(position, parent)

5. AudioManager
   ↓ GetVoice() from pool

6. AudioVoiceEnhanced
   ↓ Configure AudioSource, apply GainStack

7. AudioBus
   ↓ Route through bus hierarchy
   ↓ Apply volume, ducking, effects

8. Unity AudioSource
   ↓ Play AudioClip

9. AudioMixer (optional)
   ↓ Effects, routing

10. Speaker
    ↓ Final audio output
```

**Key Insight:** No direct AudioSource manipulation. The system manages the entire pipeline automatically.

### 2.3 Component Hierarchy

**ScriptableObject Assets (Design-Time):**
- AudioEvent
- AudioContainer (5 types)
- AudioBus
- AudioState

**Runtime Components:**
- AudioManager (MonoBehaviour singleton)
- AudioVoiceEnhanced (pooled instances)
- AudioHandle / AudioMultiHandle (playback control)

**Static Utilities:**
- AudioExtensions (helper methods)
- ListenerUtil (the listener's position: the registered listening point, or a scene AudioListener)

### 2.4 Memory & Lifecycle

**Startup (Scene Load):**
1. AudioManager.Awake()
   - Singleton registration (a second manager removes itself: its whole GameObject with Persist Across Scenes on, only
     its component with it off)
   - DontDestroyOnLoad, with Persist Across Scenes on (the default; the manager must then be a root object)
   - Voice pool creation: Max Real + Max Virtual + Steal Headroom AudioSources (32 + 64 + 4 by default), under
     "AudioVoices", a root object of Pepper's own
   - Bus initialization
   - Load events and states from the Audio Event Registry, else from Resources/Audio/Events and Resources/Audio/States
   - Start coroutines (voice management, occlusion), on "AudioVoices"

**The manager's own GameObject switched off** (or a parent of it): nothing changes. The voices and every coroutine
(fades, delays, ducks, the voice pass) live on "AudioVoices", so they carry on; Unity would otherwise end the coroutines
and stop the voices for good. To silence the game, use `PauseAll`, pause buses (§6.7) or `StopAllSounds`.

**A dedicated server:** set `AudioManager.Inert = true` at boot, before any AudioManager starts. Then every post returns
one shared, already-finished handle without allocating or logging, with an AudioManager or without one, and an
AudioManager that starts builds no voices, coroutines or per-frame step. See §17.11.

**Runtime (Playing):**
1. Event.Post() → Allocate voice from pool
2. Configure voice (clip, bus, position, gain stack)
3. Play AudioSource
4. Monitor (voice management coroutine)
5. Return to pool when finished

**Cleanup:**
- Voices return to pool automatically
- No runtime allocation/deallocation
- Predictable garbage collection

## Core Components

Source: https://peppersfx.com/docs/manual/core-components/

### 3.1 AudioManager

**Location:** `Core/AudioManager.cs` (partial class across multiple files)

**Purpose:** Central singleton managing all audio operations.

#### Responsibilities

1. **Voice Lifecycle**
   - Create voice pool on startup
   - Allocate voices on demand
   - Track active/virtual voices
   - Return voices to pool when finished

2. **Bus Management**
   - Hierarchical volume control
   - Ducking automation
   - Mixer integration

3. **Event Processing**
   - Load events from the Audio Event Registry (falls back to Resources when there is none)
   - Dispatch event actions
   - Instance limiting
   - Cooldown tracking

4. **State Management**
   - Load states the same way (registry first, then Resources)
   - Track active state per group
   - Apply state transitions

5. **RTPC System**
   - Store parameter values
   - Notify listeners on changes
   - Drive blend containers

6. **Performance Systems**
   - Voice virtualization (only when more than Max Real Voices are live)
   - Voice stealing
   - Occlusion raycasting

#### Singleton Pattern

```csharp
public partial class AudioManager : MonoBehaviour
{
    // Set in Awake, cleared in OnDestroy. There is no lazy lookup and no auto-creation:
    // if no AudioManager is in a loaded scene, Instance is null.
    public static AudioManager Instance { get; private set; }

    private void Awake()
    {
        // A second manager: its whole GameObject with Persist Across Scenes on, only this component with it off.
        if (Instance != null && Instance != this) { RemoveDuplicate(); return; }
        Instance = this;
        if (persistAcrossScenes) DontDestroyOnLoad(gameObject);
        if (Inert) { /* a server: load the event registry, build nothing else */ return; }

        InitializeCore();   // the voice pool, under Pepper's own "AudioVoices" root
        // ...
    }
}
```

**Key Points:**
- Only one AudioManager exists; a second one destroys itself
- Persists between scene loads
- Accessible globally via `AudioManager.Instance`, once its `Awake` has run. Put it in your first (bootstrap) scene.

#### Holding a reference instead of `Instance`

Your game never needs `AudioManager.Instance`. Everything a game calls is on the manager itself or on an asset (events, buses, parameters, emitters), so you can hand the manager to the scripts that use it, the way you'd wire any other dependency:

```csharp
public class CarAudio : MonoBehaviour
{
    [SerializeField] private AudioManager audioManager;   // assigned in the inspector, or by your bootstrap
    [SerializeField] private AudioEvent engine;
    [SerializeField] private AudioParameter rpm;
    [SerializeField] private AudioEmitter emitter;
    [SerializeField] private Transform cameraTransform;

    public float CurrentRpm { get; set; }                  // your car code writes this

    private void Start()
    {
        audioManager.AddListeningPoint(cameraTransform);   // instead of ListenerUtil, or a scene search
        audioManager.Post(engine, emitter);                // instead of AudioManager.Instance.Post
    }

    private void Update() => emitter.SetParameter(rpm, CurrentRpm);
}
```

The samples in this guide write `AudioManager.Instance.X(...)` to stay short; every one of them works the same as `audioManager.X(...)` on a reference you hold. Pepper itself still uses its one manager internally (containers and events reach it), which is why there can only be one. Register a listening point (§9.3, Listening Points) and neither Pepper nor its ambient system (§13) ever searches the scene or uses `Camera.main`. To leave the multiplayer code out of a game that doesn't use it, see §17.2.

#### Inspector Configuration

| Property | Description | Default | When to Change |
|----------|-------------|---------|----------------|
| `masterVolume` | Global volume multiplier (0-1) | 1.0 | User settings menu |
| `muteAll` | Mute all audio | false | Debug/testing |
| `maxRealVoices` | Max physically playing voices | 32 | Mobile (16-24), High-end (48-64) |
| `maxVirtualVoices` | Max virtualized voices | 64 | Complex scenes with many sounds |
| `voiceUpdateInterval` | Voice management update rate (seconds) | 0.1 | Performance tuning |
| `occlusionMask` | Layers that block sound | Everything | Ignore player, small objects |
| `occlusionUpdateInterval` | Occlusion raycast rate (seconds) | 0.2 | Performance tuning |
| `enableLOD` | Virtualize the least important voices once more than `maxRealVoices` are live | true | Always leave enabled |
| `lodDistances` | Not used in this version (hidden in the inspector) | [10, 25, 50, 100] | — |

#### Public API Overview

**Events:**
```csharp
AudioHandle PostEvent(string eventName)
AudioHandle PostEvent(string eventName, GameObject parent, Vector3 position)
```

**Parameters** (global scope; per-emitter and per-play values are in §3.4):
```csharp
void SetParameter(AudioParameter parameter, float value)
float GetParameter(AudioParameter parameter)
void SetRTPC(string parameter, float value)     // the same global values, by name
float GetRTPC(string parameter)
```

**Switches:**
```csharp
void SetSwitch(string group, string value)
string GetSwitch(string group)
```

**States:**
```csharp
void SetState(string stateName, float transitionTime = 0.5f)
AudioState GetActiveState(string stateGroup)
```

**Buses:**
```csharp
void SetBusVolume(string busName, float volumeDb, float transitionTime = 0f)
AudioBus GetBus(string busName)
```

**Crossfading:**
```csharp
void CrossFade(AudioContainer from, AudioContainer to, float duration,
    AudioEvent.CrossfadeType type = AudioEvent.CrossfadeType.EqualPower)
```

### 3.2 AudioVoice & AudioVoiceEnhanced

**Location:** `Events/AudioVoiceEnhanced.cs`

**Purpose:** Represents a single playing audio instance with advanced features.

#### Class Hierarchy

```csharp
public class AudioVoice
{
    public AudioSource source;
    public GameObject parent;
    public bool isPlaying;
    public float volumeMultiplier;
    // Basic voice functionality
}

public class AudioVoiceEnhanced : AudioVoice
{
    public GainStack GainStack;              // Layered volume control
    public AudioEvent SourceEvent;           // Originating event
    public AudioContainer Container;         // Source container
    public AudioBus Bus;                     // Assigned bus
    public int Priority;                     // Voice stealing priority
    public bool IsVirtual;                   // Virtualization state
    public float VirtualTime;                // Where a virtual voice is in its clip, in seconds
    public double VirtualSamples;            // The same, in the clip's samples
    public double ScheduledStartTime;        // DSP scheduled start
    public double ScheduledEndTime;          // DSP scheduled end
    public OcclusionSlot OcclusionSlot;      // Mixer-side occlusion slot (null when not held)
}
```

#### The GainStack System

**Concept:** Multiple volume layers multiply together for final volume.

```csharp
public class GainStack
{
    public float BaseGain = 1f;       // Container/Event base volume
    public float BusGain = 1f;        // Bus hierarchy contribution
    public float OcclusionGain = 1f;  // Raycast-based attenuation
    public float RtpcGain = 1f;       // Blend curves. RESERVED: sole writer is the Blend's
                                      // per-frame step (the product of every enclosing Blend's
                                      // layer curve). No generic parameter->volume driver writes it.
    public float CurveGain = 1f;      // Volume curves (Parameter Curves, §4.1) on the containers
                                      // above the voice, summed in dB. Sole writer: the same step.
    public float SchedulerGain = 1f;  // Crossfade/transition gain
    public float FadeGain = 1f;       // Stop(fadeTime) ramp, 1 → 0. RESERVED: sole writer is the
                                      // voice's fade-out — see note below.
    public float MultiplierGain = 1f; // Per-voice multiplicative — volume randomization,
                                      // Switch/Blend container outer Volume, PlayWithVolume scale.
    public float UserGain = 1f;       // AudioHandle.SetVolumeScale — idempotent runtime scale.
    public float SwitchGain = 1f;     // A playing Switch's crossfade between its choices (§4.5, When Switch Changes).
    public float EmitterGain = 1f;    // The emitter's and the handle's volume offsets (dB), kept on later voices.
    public float SpatialGain = 1f;    // Spatial Mode = Pepper: the level from the listening points; 1 in Unity mode.
    public float RealizeGain = 1f;    // The short fade around a voice going virtual and coming back.
    public float DuckingGain = 1f;    // (Deprecated) ducking is applied at the bus, not the voice.
                                      // Settable for back-compat but NOT in GetFinalGain.

    public float GetFinalGain() => GetGainWithoutRealize() * RealizeGain;

    // How loud the voice is meant to be, real or virtual: what importance and stealing read.
    public float GetGainWithoutRealize()
    {
        return BaseGain * BusGain * OcclusionGain * RtpcGain * CurveGain * SchedulerGain * FadeGain * MultiplierGain * UserGain *
               SwitchGain * EmitterGain * SpatialGain;
    }

    public void ApplyToSource(AudioSource source) { ... }
    public void Reset() { ... }
}
```

**Why Layers?**
Each system can independently control volume without knowing about others:
- Container sets BaseGain
- Bus hierarchy sets BusGain
- Occlusion system sets OcclusionGain
- RtpcGain is **reserved for Blend curves**: each frame, a Blend layer's voice gets the product of the curves of every Blend it plays under (§4.6). It is the slot's only writer — there is no generic parameter→volume driver, and a future one must not write this slot for blend voices (it would fight the blend frame-by-frame). See the reservation note on `GainStack.RtpcGain` in `GainStack.cs`.
- Volume curves (Parameter Curves) set CurveGain, separately from the Blend crossfade in RtpcGain
- Crossfade/scheduler sets SchedulerGain
- `Stop(fadeTime)` ramps FadeGain from 1 to 0. Because the fade is a slot like any other, a recompute mid-fade (the occlusion LateUpdate, a bus or master volume change, a duck) keeps the ramp instead of snapping the voice back to full level. It is separate from SchedulerGain so a crossfade and a stop fade on the same voice don't fight.
- Volume randomization, SwitchContainer/BlendContainer outer Volume, and `PlayWithVolume` write MultiplierGain
- `AudioHandle.SetVolumeScale` writes UserGain
- Ducking is applied at the bus (the voice-level `DuckingGain` field is deprecated and not part of the final gain calculation)

**Example:**
```
BaseGain:        1.0   (container volume)
BusGain:         0.707 (bus at -3dB)
OcclusionGain:   0.5   (partially occluded)
RtpcGain:        0.8   (RTPC lowering volume)
SchedulerGain:   0.9   (fading in)
MultiplierGain:  0.9   (volume randomization -1 dB)

FinalGain = 1.0 * 0.707 * 0.5 * 0.8 * 0.9 * 0.9 = 0.229
```

#### The PitchStack System

**Concept:** Pitch works like the gain stack. Each thing that changes a voice's playback rate owns one slot, the slots multiply, and only `AudioVoice.UpdateFinalPitch()` writes `AudioSource.pitch`. A handle's pitch offset therefore no longer wipes out the container's pitch randomization.

| Slot | Written by |
|---|---|
| `Randomization` | Container pitch randomization, when the voice starts |
| `Decorrelation` | The Decorrelated multi-position mode's per-emitter nudge |
| `User` | `AudioHandle.SetPitchOffset` / `AudioMultiHandle.SetPitchOffset` and `SetVoicePitchOffset` |
| `Emitter` | The Audio Emitter's **Pitch Offset** (§3.4) |
| `Follow` | A Blend's **Pitch Follow** (§4.6): the parameter ÷ the layer's Root Value, every frame |
| `Curve` | **Pitch curves** (§4.1 Parameter Curves) on the containers above the voice, every frame |
| `Doppler` | Pepper's **Doppler** (§4.1, a container set to Doppler: Pepper), every frame |
| `TimeScale` | Reserved for slow motion (planned) |

Every slot is a ratio: 1 = unchanged, 2 = an octave up. The result is clamped to Unity's maximum of 3, and the slots other than Doppler to the container's **Pitch Limit** when one is set. Doppler comes after the limit, which is for the authored pitch; the container's **Doppler Max Cents** clamps it instead.

`SetPitchAbsolute` (and the obsolete `SetPitch`, which always did this) sets an override that ignores every slot, so the voice plays at exactly that pitch, randomization (and Doppler) included.

**Example:**
```
Randomization: +1 st  (container randomization)
User:          +2 st  (handle.SetPitchOffset(2f))

Final pitch = 2^(1/12) × 2^(2/12) = 2^(3/12): 3 semitones up
```

Don't write `voice.source.pitch` yourself: the next pitch-stack update overwrites it. Use the handle methods, or a slot.

#### Voice Priority System

**Enum Values:**
```csharp
public enum VoicePriority
{
    Low = 0,       // Background ambience, least important
    Medium = 64,   // Standard gameplay sounds
    High = 128,    // Important feedback (damage, pickups)
    Critical = 255 // UI, dialogue: the strongest weight
}
```

**What a priority weighs.** A sound's importance is how loud it is where it is heard (distance × volume) times its priority's weight:

| Priority | Weight |
|---|---|
| Low | 1/8 |
| Medium | 1/4 |
| High | 1/2 |
| Critical | 1 |

Each step doubles, which is worth about 6 dB of loudness: a Medium sound counts as much as a Low one twice as loud. Low used to weigh 0, so a Low sound right beside you went before a Medium one you could hardly hear; since 3.1 it weighs 1/8, and the other three are as before.

**Voice Stealing:**
A steal ends a whole **play**, never one voice of it. A play is everything one start of a container produced: all of a Blend's layers, all of a Routing container's clips, a footstep's one voice. So an engine never loses a layer mid-race; it plays on whole or ends whole.

Before an event plays, it makes room for every voice the play will need (`AudioContainer.EstimateVoiceCount()`: a Blend adds up its layers, a Switch takes its largest choice, a Routing container counts its clips). When the pool (Max Real + Max Virtual) is too full, it ends whole plays until there is room:
1. A play that is entirely virtual and silent first. Ending it frees its voices at once.
2. Otherwise the least important play. A play's importance is its loudest voice's (see the weights above).

If even that can't make enough room (too many sounds started in the same frame, or only persistent sounds are left), **nothing is stolen** and the new sound is skipped, with a warning. A sound from an event marked **Persistent** (§5.3) is never stolen.

**A stolen sound fades out.** A stolen sound that can be heard fades out over the Audio Manager's **Steal Fade Seconds** (0.025 by default, and never fewer than three frames: 50 ms at 60 fps), then its voice goes back to the pool. The same fade ends a play an event's Max Instances takes (§5.3) and a Switch set to Restart's old choice. Its handle hears at once that the sound is gone (`OnFinished`). A sound that can't be heard yet (one posted this frame, which starts a buffer ahead) ends at once and frees its voice the same frame. Steal Fade Seconds 0 brings back the old cut, a few ms ahead on the audio clock (Steal Declick Seconds), which can click. While it fades, a stolen sound keeps its AudioSource for three or four frames; the **Steal Headroom** covers that. A handle's `Stop(0)` is still a cut: you asked for it.

`VoiceStealBehavior` (Oldest, Quietest, Furthest, LowestPriority) is not used here. It decides which of an event's own plays to end when that event reaches its Max Instances (§5.3).

**Critical Voices:**
Critical is the strongest priority: it weighs most in a voice's importance, so a Critical sound is among the last to go virtual or be stolen. It can still be stolen when the pool has nothing less important left; "never stolen" would let the pool jam when many sounds are Critical. For a sound that must never drop out (an engine), tick **Persistent** on its event (§5.3): that is the one exemption.

#### Voice Virtualization

**What Is It?**
A virtual voice is still tracked, and keeps its place in the clip, but isn't heard: its AudioSource is paused, so it doesn't use one of Unity's real voices.

**When Does It Happen?**
Only when more than `maxRealVoices` voices would be heard (and `enableLOD` is on), or more than a bus's own **Max Real Voices** (§6.9). It happens a whole **play** at a time: a play's audible voices are all real, or all virtual. Importance is distance × volume × the priority's weight, taken from a play's loudest voice, so far, quiet, low-priority sounds go before near, loud, important ones (for a sound with an Attenuation asset, "distance" is how loud its curve says it is there, §4.1; with Spatial Mode = Pepper, how loud it is heard from the listening points, §9.3). Nothing is virtualized for distance alone while you are under `maxRealVoices`, except a sound past its Attenuation asset's Max Distance.
- **When a sound starts**, once all its voices are set up, the least important plays go virtual until the audible count fits, the new sound included. So a Low sound posted while the real voices are full can start virtual instead of pushing out a more important one.
- **About 10 times a second** (`voiceUpdateInterval`), every play is ranked by importance and given real voices while they fit; the rest are virtual. A real play counts as 1.25 times as important, and a play stays at least half a second in a state, so a sound that only matters slightly more doesn't swap in and out. That is also what brings an important virtual sound back while the real voices are all taken.
- A single play with more audible voices than `maxRealVoices` keeps its most important ones real.
- A Blend with **Silent Layers = Virtualize** (§4.6) also makes its near-silent layers virtual while the rest of its play stays real.

**Keeping its place.**
While a voice is virtual, Pepper keeps the position it would have reached had it kept playing, in the clip's samples (`AudioVoice.VirtualSamples`; `VirtualTime` is the same in seconds). Every frame, in Pepper's per-frame step, the position moves on by the time Unity's audio clock has advanced × the voice's pitch, and wraps for a loop. That clock counts the audio Unity has actually mixed, so it is exactly what real voices move by: it keeps running through a frame-rate hitch and stops when audio stops. So a voice at pitch 1.5 virtual for 2 s moves on 3 s of clip. When it becomes real it starts from that position, within one audio buffer of a twin that stayed real.

- A paused voice (`Pause`, `PauseAll`) holds its position, so a pause menu can't make a virtual one-shot "finish" while the game is paused.
- A virtual one-shot ends when its position passes the end of its clip.
- A start still scheduled ahead doesn't advance until that time.
- `AudioHandle.SeekTo` on a virtual voice moves the position it comes back at.

**No clicks.**
Unity's Pause and UnPause are hard cuts. So a voice that can be heard fades out over about 25 ms (in at least three steps, at most one per audio buffer) before it pauses, and a voice that becomes real fades back in the same way. While it fades out, Unity is still playing it, so for those few frames one more voice than `maxRealVoices` can be heard. A voice that is already silent, paused or not yet started pauses at once. The fade has its own gain slot, `GainStack.RealizeGain`, which isn't counted in a voice's importance, so a virtual voice competes at the level it would play at.

**Unity's Doppler.**
Unity's own Doppler effect changes a moving 3D voice's speed without Pepper seeing it, so a virtual voice can't follow it. For looping layers that must stay in step with each other (engine layers), set the container's **Doppler** to **Pepper** (§4.1): Pepper's Doppler is in the pitch a virtual voice keeps its place at. Or set **Doppler Level** to 0 for no Doppler at all (in its 3D Settings; a layer with Uses Parent Positioning takes its Blend's). The default, Unity at Doppler Level 1, is Unity's.

#### DSP Scheduling

**Purpose:** Sample-accurate synchronization for multi-position audio.

```csharp
double dspTime = AudioSettings.dspTime;
ScheduledStartTime = dspTime + 0.1; // Start in 0.1 seconds
source.PlayScheduled(ScheduledStartTime);
```

**Use Cases:**
- Multi-position audio (all emitters start at exact same sample)
- Music layer synchronization
- Rhythmic audio sequences

### 3.3 AudioHandle & AudioMultiHandle

**Purpose:** Provide playback control after posting an event.

#### AudioHandle (Single Voice)

```csharp
public class AudioHandle
{
    // Properties
    public string EventName { get; }
    public AudioEvent SourceEvent { get; }
    public bool IsPaused { get; }
    public bool isPlaying { get; }
    public float time { get; }      // Current playback time
    public float duration { get; }  // Total clip length

    // Events
    public event System.Action OnStarted;
    public event System.Action OnLoop;      // declared, but not raised in this version
    public event System.Action OnStopping;  // a fade-out has begun
    public event System.Action OnFinished;

    // Methods
    public void SetVolumeScale(float scale)       // relative to the authored volume
    public void SetVolumeOffset(float db)         // the same, in dB
    public void SetVolumeAbsolute(float linear)   // replaces the authored volume
    public void SetPitchOffset(float semitones)   // on top of the authored pitch (randomization kept)
    public void SetPitchAbsolute(float semitones) // replaces the authored pitch
    public void SetPitch(float semitones)         // obsolete: same as SetPitchAbsolute
    public void SetLocalOffset(Vector3 offset)    // move it on the object it was posted on (§3.4)
    public void SetWorldPosition(Vector3 position)
    public void Stop(float fadeTime = 0.1f)
    public void Pause()
    public void Resume()
    public void Dispose()  // Clean up event handlers
}
```

**Usage:**
```csharp
AudioHandle handle = musicEvent.Post();
handle.OnStarted += () => Debug.Log("Music started");
handle.OnFinished += () => Debug.Log("Music finished");

// Later...
handle.SetVolumeScale(0.5f);  // Half the authored volume
handle.SetVolumeOffset(-3f);  // Or 3 dB down (the same slot: the last call wins)
handle.SetPitchOffset(2f); // 2 semitones up, on top of any pitch randomization
handle.Stop(1f);         // Fade out over 1 second
```

**The offsets stick.** `SetVolumeScale`, `SetVolumeOffset` and `SetPitchOffset` reach the voices playing now and the ones the sound starts later: a Switch's new choice, a Sequence's next clip, a Play action still waiting out its Delay. A post can set them before the first sample (`PostValues.WithVolumeOffset`, `WithPitchOffset`, §3.4). The absolute setters (`SetVolumeAbsolute`, `SetPitchAbsolute`) still reach only the voices playing now. (Before 3.1.0-dev.7 the offsets didn't reach later voices either.)

#### AudioMultiHandle (Multiple Voices)

**Purpose:** Control multiple voices from multi-position playback.

```csharp
public class AudioMultiHandle
{
    // Properties
    public int VoiceCount { get; }
    public bool HasVoices { get; }
    public bool isPlaying { get; }
    public MultiPositionType PositionType { get; }

    // Global control (all voices)
    public void SetVolumeScale(float scale)       // relative to the authored volume
    public void SetVolumeAbsolute(float linear)   // replaces the authored volume
    public void SetPitchOffset(float semitones)   // on top of the authored pitch
    public void SetPitchAbsolute(float semitones) // replaces the authored pitch (SetPitch is obsolete)
    public void Stop(float fadeTime = 0.1f)
    public void Pause()
    public void Resume()

    // Per-emitter control (index = the position's index in the post's array / emitter list)
    public void SetVoiceVolumeScale(int emitterIndex, float scale)
    public void SetVoicePitchOffset(int emitterIndex, float semitones)
    public void SetVoicePitchAbsolute(int emitterIndex, float semitones)   // SetVoicePitch is obsolete
    public void StopVoice(int emitterIndex, float fadeTime = 0.1f)
    public void PauseVoice(int emitterIndex)
    public void ResumeVoice(int emitterIndex)

    // Position management (one entry per emitter)
    public void UpdatePositions(Vector3[] newPositions)
    public void UpdatePositions(Transform[] newTransforms)
    public void RefreshPositions()
    public Vector3? GetVoicePosition(int emitterIndex)
    public Vector3[] GetAllPositions()      // one entry per voice
}
```

The per-emitter methods act on **every voice that emitter started**. If the event's container starts several voices per play (a multi-clip Routing container, a Blend), all of an emitter's layers are controlled together. The index is stable: it does not shift when other emitters' voices end. `VoiceCount` counts voices, so it equals emitters × voices per play.

**Usage:**
```csharp
AudioMultiHandle multiHandle = myEvent.PostMultiPosition(emitterParent);
Debug.Log($"Playing {multiHandle.VoiceCount} voices");
multiHandle.SetVolumeScale(0.75f);          // All speakers to 75% of authored volume
multiHandle.SetVoiceVolumeScale(0, 0.5f);   // First speaker to 50%
multiHandle.UpdatePositions(newTransforms); // Update positions dynamically
```

### 3.4 Parameters & Scopes

A **parameter** is a number the game sets and sounds read: an engine's RPM, a car's speed, combat intensity. Blend Containers follow one (§4.6).

#### Parameter assets

**Menu:** Create > Audio System > Parameter

| Field | Meaning |
|---|---|
| Parameter Name | The name it answers to in the string API (`SetRTPC`, `GetRTPC`, state and event RTPC actions) and in Blends that name a parameter. Empty = the asset's name. |
| Unit Label | Shown next to the values: RPM, m/s, 0-1. Display only. |
| Min, Max | The range. A value outside it is **read** clamped; what was written is kept, so widening the range while tuning brings it back. Writing outside the range logs one warning per parameter. |
| Default | What sounds read when nothing has been set. |
| Smoothing | How fast sounds follow a new value: None, Rate or Ease (below). |
| Bypass While | Optional on/off parameter that turns the smoothing off while it reads 0.5 or more. |

A name and an asset with that Parameter Name are **one parameter**: `SetRTPC("EngineRPM", v)` and `SetParameter(engineRpmAsset, v)` write the same global value.

#### Three scopes

A value can be set in three places. A sound reads the first one that has a value:

1. **Play**: one sound only, set on its handle. For values that differ between sounds on one object, such as each axle's tyre slide.
2. **Emitter**: every sound posted on one **Audio Emitter** (one car, one machine).
3. **Global**: every sound with no play or emitter value. This is what `SetRTPC` has always set.
4. Otherwise, the parameter's **Default** (0 for a name with no asset).

```csharp
// Global: every sound without a closer value.
AudioManager.Instance.SetParameter(intensity, 0.7f);
AudioManager.Instance.SetRTPC("CombatIntensity", 0.7f);   // the same thing, by name

// Emitter: every sound posted on this car.
AudioEmitter car = GetComponent<AudioEmitter>();
AudioHandle engine = car.Post(engineEvent);                // or engineEvent.Post(car)
car.SetParameter(rpm, 4200f);

// Play: this sound only, here at the car's front axle (a named point, below).
AudioHandle frontAxle = car.Post(tyreEvent, "FrontAxle");
frontAxle.SetParameter(slideSpeed, 3.5f);

// Fall back to the next scope.
car.ClearParameter(rpm);

// What a sound actually reads, after clamping.
float value = engine.GetEffectiveParameter(rpm);
```

**Audio Emitter** (Add Component > Audio System > Audio Emitter) holds the emitter scope. Posting on it places and attaches 3D sounds exactly as posting with its GameObject does. A post on a plain GameObject has no emitter values, as before. In Play mode its inspector lists the values set on it.

Switch values use the same three scopes: `car.SetSwitch(surface, "Kerb")` for one car, `handle.SetSwitch(...)` for one sound (§4.5).

#### Values at post

A value set on a handle after `Post` reaches a sound that has already started. A one-shot that must start right (a heavy impact at a heavy impact's level, a footstep on this foot's surface) carries its values **with the post**: they go on the sound's own scope before any of its voices start, so the first sample hears them.

```csharp
car.Post(impactEvent, PostValues.Of(strength, 0.8f));
car.Post(footstepEvent, "RearAxle", PostValues.Of(surface, "Grass").With(strength, 0.3f));
impactEvent.Post(debrisObject, debrisObject.transform.position, PostValues.Of(strength, 1f));
```

- Up to 4 parameters and 2 switch values per post; `PostValues` is a struct, so building one allocates nothing.
- They are the sound's own values (the play scope, like `handle.SetParameter`), first in line before its emitter's and the global ones, and the handle keeps them for later changes.
- A post can also carry the sound's own **volume and pitch offsets**: `PostValues.VolumeOffset(-3f)`, or `.WithVolumeOffset(dB)` and `.WithPitchOffset(semitones)` on any values. They are the handle's `SetVolumeOffset` and `SetPitchOffset`, set before the first sample: `car.Post(tyreEvent, "RearAxle", PostValues.Of(surface, "Asphalt").WithVolumeOffset(profile.TyresDb))`.

#### Built-in values: Distance, Approach Speed, Angle

A Parameter asset's **Value From** can be a value Pepper works out for each sound instead of one your code sets:

| Value From | Unit | What it is |
|---|---|---|
| **Distance** | m | From the sound to the listening point. |
| **Approach Speed** | m/s | How fast the sound and the listening point close in on each other: positive coming closer, negative moving apart. From the emitter's velocity (measured, or `SetVelocity`), else the sound's own measured motion, minus the listening point's; eased over 50 ms. |
| **Angle** | ° | Around the listening point, on the horizontal plane: 0 ahead, +90 right, -90 left, ±180 behind. |

```csharp
// A pass-by boost: a Parameter asset "ApproachSpeed" (Value From = Approach Speed, -80 to 80 m/s), and on the
// car's engine a volume curve on it rising to +3 dB at 50 m/s.
// A near/far engine: a Blend on a "Distance" asset (0-300 m) crossfading a close and a distant recording.
```

- Use them wherever a parameter goes: Parameter Curves, a Blend's parameter, Pitch Follow, a Switch Group's Driven By (a near/far switch).
- Each sound has its own value, from where its first voice is (before it has one, where it was posted). The asset's range clamps it; its Smoothing doesn't apply.
- Your code can't set them: `SetParameter` on one is ignored, with one warning. `handle.GetEffectiveParameter(distance)` reads a sound's; `emitter.GetEffectiveParameter(distance)` the emitter's own place.

#### Named points

One object often has several sound sources: a car's exhaust at the tailpipe, its intake at the front, a tyre emitter per axle. Give the Audio Emitter **Points**: each a name and an offset in metres in the object's own space (x right, y up, z forward; the object's scale applies). Drag them into place in the Scene view while the object is selected.

```csharp
car.Post(engineExhaustEvent, "Exhaust");     // attached at the exhaust's offset
car.Post(intakeEvent, "Intake");
car.Post(tyreRollEvent, "RearAxle");
car.SetParameter(rpm, 4200f);                // one RPM, read by every sound on the car
```

- A sound posted at a point is attached to the object at that offset, so it moves and turns with it, a Sequence's later clips too. A 2D sound ignores the place.
- Every point shares the emitter's parameter values (and its velocity, below). Values that differ per point, such as each axle's slide speed, go on that sound's handle.
- An unknown name warns once and plays at the object's origin.
- By number is a little faster for sounds posted very often: `int rear = car.FindPoint("RearAxle"); car.Post(skidEvent, rear);`
- `car.SetPoint("Exhaust", offset)` adds or moves a point from code; sounds already playing stay where they were attached.

#### Posting at an offset, and moving a sound

An impact happens where the car hit, not at a named point. Post it at any offset in the object's own space (metres): it is like a point, with the emitter's values, its **Max Instances Per Emitter** and **Cooldown Per Emitter**, and its random numbers.

```csharp
Vector3 local = car.transform.InverseTransformPoint(contact.point);
car.Post(impactEvent, local, PostValues.Of(strength, impactSpeed / 25f));   // or impactEvent.PostAtOffset(car, local, ...)

// A scrape loop that follows the contact along a wall: move it every frame it lasts.
scrape = car.Post(scrapeEvent, local);
// ... each frame:
scrape.SetLocalOffset(car.transform.InverseTransformPoint(contact.point));
```

- `handle.SetLocalOffset(offset)` moves a playing sound to that offset from the object it was posted on (an emitter, or a GameObject); it keeps moving and turning with the object. It takes effect at once, whether the sound is attached (On Disable = Keep) or follows the object (Stop, Pause).
- `handle.SetWorldPosition(position)` puts it at a world position. On a sound posted on an object, that becomes an offset from the object, so it moves with it from there; a sound posted at a world position (no object) just moves there.
- Voices the sound starts later (a Sequence's next clip, a Switch's new choice, a Play action waiting out its Delay) start where it was moved to.
- `SetPoint` still doesn't move sounds already playing at a named point; move them with their handle.

#### Level and pitch per emitter

An Audio Emitter's **Volume Offset** (dB) and **Pitch Offset** (cents) apply to every sound posted on it, the ones playing now and the ones posted or started later: a car's level against the others. They compose with a sound's own offset (`SetVolumeOffset`, `SetPitchOffset`, or at the post).

```csharp
car.VolumeOffsetDb = profile.CarDb;              // this car 2 dB up in the mix
car.Post(engineEvent, PostValues.VolumeOffset(profile.EngineDb));   // and its engine against its tyres
```

- They have gain and pitch slots of their own (`GainStack.EmitterGain`, `PitchStack.Emitter`), set in the inspector or from code, also in Play mode.
- **A raise can't take a sound past full volume:** an AudioSource's volume stops at 1. Author car sounds a few dB below full to leave room for trims up.

**Velocity.** The emitter measures its velocity in Pepper's per-frame step (`car.Velocity`), or you give it with `car.SetVelocity(rigidbody.linearVelocity)` every frame, which is exact for a physics car. Approach Speed (above) and Pepper's Doppler (§4.1) read it.

**Teleports.** When the object jumps (a reset to the track, a respawn, a remote car placed), call `car.Teleport()`: Pepper's next step takes the new position and measures nothing from the jump, so it isn't read as a huge speed (a Doppler shriek). The last velocity stays until a new one is measured, so a car moving on at the same speed has no step in its pitch. A velocity given with `SetVelocity` is kept. Call `SnapAllParameters()` too if its values jump.

#### Switched off or destroyed (On Disable)

What an emitter's sounds do when its GameObject is switched off or destroyed is its **On Disable** setting (`WhenDisabled` from code):

| On Disable | Switched off | Destroyed |
|---|---|---|
| **Keep** (default, as before 3.1) | Its 3D sounds are attached to it, so Unity stops them with it; a loop is never reclaimed. | Its 3D sounds are cut, with a warning, and Pepper rebuilds their voices. |
| **Stop** | Every sound on it fades out over **Stop Fade Seconds** (default 0.1 s) where it is, and goes back to the pool. Delayed parts of its sounds (a Delay action, a Sequence's next clip) are cancelled. | The same: the fade finishes after the object is gone. |
| **Pause** | Its sounds pause (fading out over about 25 ms) and hold their place, keeping no real voice. Switched on again, they carry on from there, every layer of an engine together, in phase. | They stop with the fade. |

- **With Stop or Pause, the sounds aren't attached to the object.** They stay under Pepper's "AudioVoices" root and follow it: Pepper moves each one to its object (and its point) every frame, after every LateUpdate and before Unity mixes, so it sits exactly where an attached one would. That is what lets a fade finish after the object is gone. Unity won't let anything move a child out of an object while it is being switched off.
- **While a Stop or Pause emitter is off, posts on it play nothing** (they return a finished handle, silently): a script on the same object posting in its own `OnDisable` runs either before or after the emitter, so it must not matter.
- **Set On Disable before posting.** It is read when a sound is posted; sounds already playing keep the way they were attached.
- **Use Stop for objects created and removed all the time** (cars on show, cars that leave), and Pause for objects you switch off to bring back.

```csharp
// A car prefab: its sounds fade out over 0.2 s when the car is removed, instead of being cut.
car.WhenDisabled = EmitterDisableMode.Stop;
car.StopFadeSeconds = 0.2f;
```

#### Smoothing

The game usually writes a value every frame (or faster, from physics), and it jumps around. A parameter's **Smoothing** makes what sounds hear follow it gently, the same at 40 fps as at 144 fps:

| Mode | Fields | What it does |
|---|---|---|
| None | | Sounds hear the written value at once. |
| Ease | Rise, Fall (seconds) | Closes 95% of the gap to a new value in that time: a fast start that slows as it arrives. Separate times for rising and falling, for example a quick throttle attack and a slower release. |
| Rate | Rise speed, Fall speed (units per second) | Moves at most that fast, then stops on the value. |

0 in any field means "at once" for that direction.

- **Each scope smooths its own value.** Two cars ease their own RPM; a value on a handle eases separately from its emitter's.
- **The first value a scope gets is heard at once,** so a new engine doesn't glide up from the default.
- **Values set by name are never smoothed.** `SetRTPC` and `TransitionRTPC` behave exactly as before. Smoothing applies to writes through the asset (`SetParameter`, `RampParameter`).
- **Snap** skips the smoothing: sounds hear the written value now, and a running ramp jumps to its end. Use it on a reset or a teleport so nothing glides across it.
- **Per car:** an emitter or a handle can override the smoothing for its own value, for example a different throttle attack per car.
- **Bypass While:** point it at an on/off parameter (a rev limiter). While that reads 0.5 or more in the same scope, the value is heard at once, so the limiter's cuts stay sharp.
- **Clearing a smoothed value** eases it over to the next scope's value before it goes, instead of jumping.

```csharp
// On the asset: Smoothing = Ease, Rise 0.05 s, Fall 0.2 s. Then write the raw value every frame:
car.SetParameter(load, throttle);

// This car only: a sharper attack.
car.SetSlewOverride(load, ParameterSlew.Ease(0.02f, 0.2f));

// The car was reset to the start line: nothing should glide.
car.SnapAllParameters();
```

`GetEffectiveParameter` returns the smoothed value sounds hear now; `TryGetParameter` and `GetRTPC` return what was written. RTPC listeners are told written values, not the smoothed ones.

#### Ramps

`RampParameter(parameter, target, seconds)` exists on the manager (global), an emitter and a handle. It moves the written value in a straight line from what was written before (or, with nothing written, what that scope hears now), on unscaled time; smoothing applies on top. A new ramp, a Set, a Snap or a Clear on the same parameter in the same scope replaces it. `TransitionRTPC(name, value, seconds)` is a global ramp by name: a second call now **replaces** the first instead of the two fighting.

#### When values are heard

Pepper updates parameters (ramps and smoothing) once a frame, **after every LateUpdate** and just before Unity mixes the audio, so a value set anywhere in this frame's game code (Update, LateUpdate, a camera script) is heard this frame. No Script Execution Order setup is needed.

- `SetRTPC` still tells `IRTPCListener`s at once, inside the call. Global writes through an asset tell them too, by the asset's name. Emitter and play values don't.
- A Blend layer picks a change up in that per-frame update, not inside `SetRTPC` as it used to. It is still the same frame.
- **Manual update:** set the Audio Manager's **Update Mode** to Manual and call `AudioManager.Instance.Tick()` once a frame after your last write, if your game runs its own loop.
- The update starts with the frame after the Audio Manager is created. A Blend posted in that very first frame still starts at the right level.

#### Cost

Each parameter gets a small number the first time it is used. After that, a write is an array write: no string lookups and no garbage. One hundred writes and an update allocate nothing.

## Audio Containers

Source: https://peppersfx.com/docs/manual/audio-containers/

Containers define how audio clips are organized and played. All containers inherit from `AudioContainer` base class.

### 4.1 Container Base Class

**Location:** `Containers/audio-container-base.cs`

#### Common Properties

Every container has these properties:

**Identity:**
```csharp
string ContainerName { get; }     // Unique identifier
string Description { get; }       // Designer notes
List<string> Tags { get; }        // Searchable organization tags
```

**Mixer Integration:**
```csharp
AudioMixerGroup MixerGroup { get; set; }  // Optional mixer routing
```

**Randomization:**
```csharp
bool enableVolumeRandomization;           // Add volume variation
float volumeRandomMin;                    // Min offset in dB (-12 to 12)
float volumeRandomMax;                    // Max offset in dB (-12 to 12)

bool enablePitchRandomization;            // Add pitch variation
float pitchRandomMin;                     // Min offset in cents (-1200 to 1200)
float pitchRandomMax;                     // Max offset in cents (-1200 to 1200)
```

**3D Spatialization:**
```csharp
bool Is3D { get; }                        // Enable 3D positioning
float MinDistance { get; }                 // Full volume distance
float MaxDistance { get; set; }            // Zero volume distance (setting it changes the running game only)
AudioRolloffMode RolloffMode { get; }     // Logarithmic/Linear/Custom
AudioAttenuation Attenuation { get; }      // A shared distance asset; replaces the three above when set
float DopplerLevel { get; set; }           // Unity's Doppler strength (Doppler = Unity)
DopplerMode Doppler { get; set; }          // Unity (default) or Pepper
float DopplerExaggeration { get; set; }    // Pepper: ×1 to ×3
float DopplerMaxCents { get; set; }        // Pepper: the largest shift either way, in cents
```

#### Doppler

A container's **Doppler** (3D Settings) says who shifts the pitch of its 3D sounds as they move relative to the listener:

| Doppler | What it does |
|---|---|
| **Unity** (default, as before 3.1) | Unity's Doppler, by **Doppler Level** (0 = none, 1 = Unity's default). Pepper can't see it, so a voice that goes virtual comes back out of step with it. |
| **Pepper** | Pepper's own, in the voice's pitch stack: ratio = c ÷ (c − v), c = 343 m/s, v the sound's closing speed on the listening point (positive coming closer). Then times **Doppler Exaggeration** (×1 physical, up to ×3 for an arcade pass) and kept within ± **Doppler Max Cents** (100 cents = a semitone). Unity's Doppler is off on these voices. |

- A car passing at 50 m/s swings about 5 semitones at ×1 (+2.7 coming, −2.4 going) and about 10 at ×2.
- The closing speed is the sound's **Approach Speed** (§3.4): its emitter's velocity (measured, or `SetVelocity`), else how the sound moves, against the listening point's, eased over 50 ms. One value per sound (from its first voice), as for the built-in values.
- **Teleports:** a car reset or placed elsewhere calls `emitter.Teleport()`, so the jump isn't read as speed; a camera cut calls `point.ClearVelocity()`. Without them, Max Cents keeps the shriek bounded.
- It is outside the container's **Pitch Limit** (which is for the authored pitch); a virtual voice keeps its place at the pitch with Doppler in, so layers come back in step.
- **Uses Parent Positioning** carries it down with the other 3D settings: set it once on an engine's top Blend.
- **When Pepper pans** (the Audio Manager's Spatial Mode = Pepper, §9.3), every 3D sound plays 2D for Unity, which then has no Doppler to give it, so every one gets Pepper's: a container left at Doppler = Unity gets Pepper's at its **Doppler Level** (0 = none) as the exaggeration, within its Max Cents. The closing speed is measured from the sound's own listening point, the one that hears it loudest.

#### Attenuation assets

**Create > Audio System > Attenuation** makes a distance asset you can share between sounds: how they change with distance from the listening point, as curves over **metres**.

| Field | Unit | What it does |
|---|---|---|
| **Max Distance** | m | Where the curves end. Past it the sound plays virtually (silent, keeping its place, no real voice), and it comes back inside 95% of it. |
| **Volume** | dB | The level at each distance (0 = as authored, -6 = half). The default: 0 dB to 2 m, 6 dB less per doubling, nearly silent at 100 m. |
| **Low Pass** (optional) | Hz | Dull the sound with distance (22000 = open). |
| **High Pass** (optional) | Hz | Thin it with distance (10 = open). |
| **Spread** (optional) | 0–1 | How wide it sounds: 0 a point (fully panned), 1 fully wide. Close cars wide, far cars narrowing to a point. |

- Set it in a container's **3D Settings** (Attenuation). It replaces that container's Min Distance, Max Distance and Rolloff, which grey out. A container inside a Blend or Switch takes its parent's with **Uses Parent Positioning**, so set it once on the top of an engine. Containers without one work exactly as before.
- **Volume and Spread** are applied by Unity while it mixes (Pepper hands the curves over as Unity's custom curves), so even a fast pass-by fades smoothly at any frame rate. Unity measures from its AudioListener: keep it on the listening point (`AudioManager.DriveUnityListener`, §9.3).
- **Low Pass and High Pass** are set by Pepper from each voice's distance every frame, eased over about 20 ms, and combine with Parameter Curves: the lowest low-pass and the highest high-pass win.
- **Past Max Distance**, a sound starts or goes virtual while the Audio Manager manages voices (LOD on); a persistent one too. With LOD off it keeps playing at the curve's last level.
- Far sounds lose to near ones: a voice's importance (§3.2) comes from how loud its curve says it is at its distance.
- `handle.SetAttenuation(otherAsset)` plays one sound with another asset (a hero car heard further away), and `ClearAttenuation()` goes back. Neither changes an asset.
- Filter curves go in a straight line in octaves between keys, as Parameter Curves do.
- **Editing the asset in Play mode:** with Spatial Mode = Pepper (§9.3), the volume, filter and spread curves are read every frame, so a change is heard at once. With Spatial Mode = Unity, the volume and spread curves and Max Distance are handed to Unity when a sound starts, so a sound already playing (a persistent engine) keeps the old ones until it is posted again, while Pepper's own Max Distance check reads the new one at once. Re-post the sound after changing them.
- The curves' last key holds past it: with the default volume curve (nearly silent at 100 m) and a Max Distance of 150 m, a sound is nearly silent from 100 m but stays a live voice to 150 m. Move the last keys to Max Distance.

**Parent Settings** (for a container played inside a Blend or Switch):
```csharp
bool UsesParentPositioning { get; set; }  // Take the parent's 3D settings instead of its own
bool UsesParentOutput { get; set; }       // Play through the parent's Mixer Group instead of its own
```
Both are off by default, so a child keeps its own settings, as before. A Blend's or Switch's own 3D settings and Mixer Group never reach its children unless a child asks. If the parent itself asks its own parent, the question goes up until a container answers it. Set the 3D settings once on the top Blend and tick Uses Parent Positioning on the layers.

**Parameter Curves:**
```csharp
List<ParameterCurve> ParameterCurves { get; }   // properties driven by parameters
```
Each curve maps one parameter (X, in the parameter's unit) to one property (Y):

| Property | Y unit | Several curves on one container |
|---|---|---|
| Volume | dB (0 = as authored, -6 = half) | add |
| Pitch | cents (100 = one semitone) | add |
| Low Pass | Hz (22000 = open) | the lowest wins |
| High Pass | Hz (10 = open) | the highest wins |

- The parameter is read in each play's scopes (the handle's value, then the emitter's, then global, §3.4), after smoothing, every frame. Curves apply to every sound below the container in the play's tree, and compose down it: volumes and pitches add, the lowest low-pass and highest high-pass win.
- Filter curves go in a straight line in **octaves** between keys (1 kHz to 4 kHz passes 2 kHz half way), and ignore tangents.
- A **Low Pass** or **High Pass** curve switches on the filter every pooled voice has had, switched off, since the pool was built (so nothing is added mid-game); it eases over about 20 ms, is set before the voice's first sample, and switches off when fully open. These are separate from occlusion, which keeps filtering through mixer slots (§14.1).
- A volume curve can't make a sound louder than full scale (an AudioSource's volume tops out at 1). The inspector warns when a curve goes above 0 dB.
- A container with curves is updated every frame; one without costs nothing.

```
Example: the hero car's engine pulls back as speed rises (a racing game).
Engine Blend → Parameter Curves → Speed (m/s): Volume, (0, 0 dB) to (60, -6 dB)
Wind loop    → Parameter Curves → Speed (m/s): Low Pass, (0, 800 Hz) to (60, 12000 Hz)
```

#### Common Methods

```csharp
public abstract AudioVoice Play(Vector3 position = default, GameObject parent = null);
public abstract void Stop();
public abstract void StopImmediate();
```

#### Randomization Implementation

```csharp
protected void ApplyRandomization(AudioVoice voice)
{
    if (enableVolumeRandomization)
    {
        float dbOffset = AudioRandom.Range(volumeRandomMin, volumeRandomMax);   // Pepper's random numbers, see below
        // MultiplierGain is the gain-stack slot for per-voice variation; it composes with
        // the bus, occlusion, blend and handle slots.
        voice.GainStack.MultiplierGain *= Mathf.Pow(10f, dbOffset / 20f);
    }

    if (enablePitchRandomization)
    {
        float centsOffset = AudioRandom.Range(pitchRandomMin, pitchRandomMax);
        // The pitch stack's Randomization slot, so a handle's SetPitchOffset composes with it.
        voice.PitchStack.Randomization *= Mathf.Pow(2f, centsOffset / 1200f);
        voice.UpdateFinalPitch();
    }
}
```

The volume value is drawn before the pitch value, and both after the clip pick. Networked posts rely on that order to play the same variation on every machine.

#### Random numbers

Every random choice a sound makes (which clip a Random container plays, a Sequence's random order, volume and pitch randomization, multi-position offsets) comes from **Pepper's own random numbers**, not `UnityEngine.Random`, so audio never moves your gameplay's random sequence:

- A sound posted on an **Audio Emitter** draws from that emitter's own sequence. Set the emitter's **Random Seed** (or call `emitter.SetRandomSeed(seed)`) and the same seed replays the same picks, whatever other cars play; 0 (the default) gives a different sequence every run.
- Sounds without an emitter share one Pepper sequence.
- **Networked posts** (§17) still seed `UnityEngine.Random` for the post, so every machine picks the same variation, and put its state back afterwards.
- The Audio Manager's **Random Numbers** setting switches back to `UnityEngine.Random` (Unity), as before 3.1.

**Pitch Limit (semitones):** keeps the container's voices within that many semitones of their recorded pitch, whatever randomization and other pitch changes add up to. 0 (the default) means no limit. `SetPitchAbsolute` ignores it.

**Why Randomization Matters:**
Prevents "machine gun effect" where repeated sounds become obviously repetitive.

**Recommended Values:**
- **Subtle variation:** Volume ±1-2 dB, Pitch ±50-100 cents
- **Dramatic variation:** Volume ±4-6 dB, Pitch ±200-300 cents

### 4.2 RoutingContainer

**Menu:** Create > Audio System > Routing Container

**Purpose:** Simplest container. Plays all assigned clips simultaneously.

#### Properties

```csharp
List<AudioClip> AudioClips { get; }  // Clips to play
float Volume { get; }                 // Base volume (0-1)
bool Loop { get; }                    // Loop all clips
```

#### When to Use

**Single One-Shot Sounds:**
```
Use Case: Button click
Setup: 1 AudioClip, no loop
```

**Multi-Layer Sounds:**
```
Use Case: Explosion
Setup: 3 AudioClips (blast + debris + shockwave)
Result: All play simultaneously for rich sound
```

**Background Loops:**
```
Use Case: Generator hum
Setup: 1-2 AudioClips, loop enabled
```

#### Implementation Details

```csharp
public override AudioVoice Play(Vector3 position = default, GameObject parent = null)
{
    if (AudioClips.Count == 0) return null;

    AudioVoice primaryVoice = null;

    // Play all clips
    foreach (var clip in AudioClips)
    {
        if (clip == null) continue;

        var voice = audioManager.GetVoice();
        if (voice == null) continue;

        voice.source.clip = clip;
        voice.source.loop = Loop;
        voice.source.volume = Volume;

        ConfigureAudioSource(voice.source, position, parent);
        ApplyRandomization(voice);

        voice.source.Play();
        activeVoices.Add(voice);

        if (primaryVoice == null) primaryVoice = voice;
    }

    return primaryVoice;
}
```

**Key Insight:** Returns first voice as "primary" for handle control, but all clips play.

### 4.3 RandomContainer

**Menu:** Create > Audio System > Random Container

**Purpose:** Picks one random clip per trigger, with weighting and repeat avoidance.

#### Properties

```csharp
List<WeightedAudioClip> AudioClips { get; }  // Clips with weights
int AvoidRepeatLast { get; }                  // Don't repeat last N clips (0-10)
bool UseWeighting { get; }                    // Enable weighted selection
float Volume { get; }                          // Base volume
bool Loop { get; }                             // Loop selected clip
```

**Avoid Repeat Last** remembers recent clips **per Audio Emitter**: a car never repeats its own last clips, whatever other cars just played. Sounds posted without an emitter share one memory. `ClearHistory()` forgets them all. A networked post ignores and doesn't change the memory, so the seed alone decides its clip. Keep it below the clip count: at or above it the setting does nothing (any clip can play next), and a container of two or more clips warns about it.

#### WeightedAudioClip Structure

```csharp
[Serializable]
public class WeightedAudioClip
{
    public AudioClip clip;
    public float weight = 1f;           // Selection probability (0-10)
    public float volumeMultiplier = 1f; // Per-clip volume (0-1)
}
```

#### Weighted Selection Algorithm

```csharp
private AudioClip SelectWeightedClip()
{
    // Calculate total weight of available clips
    float totalWeight = 0f;
    foreach (var entry in availableClips)
        totalWeight += entry.weight;

    // Random value in range [0, totalWeight]
    float random = AudioRandom.Range(0f, totalWeight);

    // Find clip at this weighted position
    float cumulative = 0f;
    foreach (var entry in availableClips)
    {
        cumulative += entry.weight;
        if (random <= cumulative)
            return entry.clip;
    }

    return availableClips[0].clip; // Fallback
}
```

**Example Weighting:**
```
Clip A: weight = 5.0  → 50% chance
Clip B: weight = 3.0  → 30% chance
Clip C: weight = 2.0  → 20% chance
Total:  10.0
```

#### Repeat Avoidance

```csharp
private List<AudioClip> recentlyPlayed = new List<AudioClip>();

private void AvoidRepeats()
{
    // Remove recently played clips from selection pool
    var available = AudioClips
        .Where(clip => !recentlyPlayed.Contains(clip.clip))
        .ToList();

    // If too many excluded, reset
    if (available.Count == 0)
    {
        recentlyPlayed.Clear();
        available = AudioClips.ToList();
    }

    return available;
}

private void TrackPlayed(AudioClip clip)
{
    recentlyPlayed.Add(clip);

    // Keep only last N
    while (recentlyPlayed.Count > AvoidRepeatLast)
        recentlyPlayed.RemoveAt(0);
}
```

#### When to Use

**Footsteps:**
```
Setup: 6-8 clips, avoidRepeatLast = 2-3, equal weights
Result: Natural variation, never obvious repetition
```

**Weapon Fire:**
```
Setup: 3-5 clips, avoidRepeatLast = 1, equal weights
Result: Each shot sounds different
```

**Voice Lines:**
```
Setup: 10+ clips, avoidRepeatLast = 3, custom weights
Example: Common phrases weight = 5, rare phrases weight = 1
```

**Best Practice:** Always set `avoidRepeatLast` to at least 1-2 for any repeated sound.

### 4.4 SequenceContainer

**Menu:** Create > Audio System > Sequence Container

**Purpose:** Plays clips in a defined order with various playback modes.

> **Auto Advance and the handle.** With Auto Advance on, one post plays the whole sequence, and
> every clip it plays belongs to that post's handle:
> - the handle stays alive through Delay After gaps;
> - `OnFinished` fires after the **last** clip;
> - `handle.Stop()` ends the sequence, even in the middle of a gap.
>
> A sequence with Loop Sequence off stops after its final entry, and its next post starts from
> the top again. If a clip is stopped by anything (a Stop, a steal, a crossfade, `StopAllSounds`),
> the sequence ends; only a clip that finishes on its own moves it on. Pausing a clip holds the
> sequence.

> ⚠️ **Hard limit — one logical sequence per asset.** The sequence position and the auto-advance
> run live on the container **asset**, so every emitter that plays the same SequenceContainer
> shares one position. Starting it from a second emitter takes the run over: the first emitter
> keeps its current clip, and its handle finishes when that clip ends. `container.Stop()` stops
> *every* play of the asset, on any container type; to stop one play, stop its handle. If you need
> two independent sequences running at once (two alarm panels, two radios), **duplicate the
> asset** — one SequenceContainer per logical sequence. This is by design for 3.0.

#### Properties

```csharp
List<SequenceEntry> Entries { get; }                       // Ordered clip list
SequenceContainer.PlaybackMode SequencePlaybackMode { get; } // Forward/Reverse/PingPong/Random
bool LoopSequence { get; }                                   // Loop entire sequence
bool AutoAdvance { get; set; }                               // Auto-advance after clip finishes
float Volume { get; }                                        // Base volume
```

#### SequenceEntry Structure

```csharp
[Serializable]
public class SequenceEntry
{
    public AudioClip clip;
    public float volumeMultiplier = 1f;  // Per-clip volume
    public bool loop;                     // Loop this specific clip
    public float delayAfter = 0f;        // Delay before next clip (0-5s)
}
```

#### Playback Modes

**Forward:**
```
Sequence: [A, B, C, D]
Playback: A → B → C → D → (loop to A)
```

**Reverse:**
```
Sequence: [A, B, C, D]
Playback: D → C → B → A → (loop to D)
```

**PingPong:**
```
Sequence: [A, B, C, D]
Playback: A → B → C → D → C → B → A → B → ...
```

**Random:**
```
Sequence: [A, B, C, D]
Playback: B → A → D → C → B → ...  (random each time)
```

#### Implementation

```csharp
private int currentIndex = 0;
private bool pingPongDirection = true; // true = forward

public override AudioVoice Play(Vector3 position = default, GameObject parent = null)
{
    if (Entries.Count == 0) return null;

    var entry = Entries[currentIndex];
    var voice = PlayEntry(entry, position, parent);

    AdvanceIndex();

    return voice;
}

private void AdvanceIndex()
{
    switch (Mode)
    {
        case PlaybackMode.Forward:
            currentIndex = (currentIndex + 1) % Entries.Count;
            break;

        case PlaybackMode.Reverse:
            currentIndex--;
            if (currentIndex < 0) currentIndex = Entries.Count - 1;
            break;

        case PlaybackMode.PingPong:
            if (pingPongDirection)
            {
                currentIndex++;
                if (currentIndex >= Entries.Count - 1)
                {
                    pingPongDirection = false;
                    currentIndex = Entries.Count - 1;
                }
            }
            else
            {
                currentIndex--;
                if (currentIndex <= 0)
                {
                    pingPongDirection = true;
                    currentIndex = 0;
                }
            }
            break;

        case PlaybackMode.Random:
            currentIndex = AudioRandom.Range(0, Entries.Count);
            break;
    }
}
```

#### Public Methods

```csharp
public void ResetSequence()
{
    currentIndex = 0;
    pingPongDirection = true;
}

public void SetIndex(int index)
{
    currentIndex = Mathf.Clamp(index, 0, Entries.Count - 1);
}

public AudioVoice PlayNext(Vector3 position = default, GameObject parent = null)
{
    // Advances the sequence and plays the next entry
}
```

#### When to Use

**Alarm Sequences:**
```
Setup: [Beep, Silence, Beep, Silence]
Mode: Forward, Loop
delayAfter: 0.5s on each
```

**Musical Sequences:**
```
Setup: [Note1, Note2, Note3, Note4]
Mode: PingPong or Forward
Use for melodic patterns
```

**Tutorial Steps:**
```
Setup: [Step1VO, Step2VO, Step3VO]
Mode: Forward, No Loop
Called manually for each step
```

### 4.5 SwitchContainer

**Menu:** Create > Audio System > Switch Container

**Purpose:** Selects child container based on game state switch value.

#### Properties

```csharp
AudioSwitchGroup SwitchGroup { get; }        // The Switch Group asset it reads (or null)
string SwitchGroupName { get; }              // Which switch to monitor (the asset's name, or the name field)
List<SwitchEntry> SwitchEntries { get; }     // Value→Container mappings
AudioContainer DefaultContainer { get; }      // Fallback if no match
SwitchChangeMode WhenSwitchChanges { get; }   // Next Play Only, Crossfade or Restart
float CrossfadeTime { get; }                  // Crossfade only, seconds
float Volume { get; }                         // Volume multiplier
```

#### SwitchEntry Structure

```csharp
[Serializable]
public class SwitchEntry
{
    public string switchValue;       // Switch value to match (e.g., "Metal")
    public AudioContainer container; // Container to play
}
```

#### How It Works

- When the Switch plays, it reads its switch group's value in that sound's scopes, the same three as parameters (§3.4): the sound's own (`handle.SetSwitch`), else its emitter's (`emitter.SetSwitch`), else the global one (`AudioManager.SetSwitch`), else the group's Default Value. It picks the matching entry's container, or the Default Container when none matches.
- What happens when the value changes while the sound plays is the Switch's **When Switch Changes** (below). The default, **Next Play Only**, is how Switches always worked: the playing sound keeps its choice and the next play picks the new value.
- The chosen container plays as part of the same play, under its own place in the play's tree. So a Blend under a Switch reads its parameter in that play (the handle's or emitter's value), and a Sequence under it reports the clips it starts later to the same handle.
- Every voice the chosen container starts, later clips included, gets the Switch's **Volume** on top of its own.
- The Switch's own 3D settings and Mixer Group reach the chosen container only if it ticks Uses Parent Positioning / Uses Parent Output (§4.1).

```csharp
// The tyre tree from a racing game: a Switch on surface over Blends on slide speed.
car.SetSwitch(surface, "Asphalt");          // this car's surface (surface: a Switch Group asset)
AudioHandle frontAxle = car.Post(tyreEvent, "FrontAxle");
frontAxle.SetParameter(slideSpeed, 3.5f);   // the asphalt Blend under the Switch reads it
```

#### When Switch Changes

| Setting | What a playing sound does when its value changes | For |
|---|---|---|
| **Next Play Only** (default) | Nothing; the next play picks the new value. | One-shots: footsteps, impacts. |
| **Crossfade** | The new choice starts from its beginning and fades in while the old one fades out, over **Crossfade Time** (seconds, default 0.15), along equal-power curves so the loudness holds steady. | Loops: a tyre's surface bed, an ambience. |
| **Restart** | The old choice fades out as a stolen sound does, over the Audio Manager's **Steal Fade Seconds** (25 ms by default, at least three frames; 0 cuts it in a few ms), and the new one starts at once, at full level. | Loops that must not overlap. |

- The sound keeps its handle: no second `OnStarted`, and `OnFinished` only when it really ends.
- If the value flips back while the old choice is still fading out (a car clipping a kerb), the old one fades back up; no second copy starts.
- When the old choice has faded to silence, its voices stop. A Sequence in it starts no more clips.
- During a crossfade the sound plays both choices, so it uses their voices together for that moment. If the voice pool is too full for that, the old choice is cut at once and the new one takes its voices.
- A sound that is virtual (far away, or less important than the ones playing) changes virtually: the new choice starts silent and takes no other sound's real voice.
- A paused sound doesn't follow; it catches up when resumed.
- A value with no entry and no Default Container fades the sound out to silence. It stays alive, and comes back when the value has an entry again. That holds once the sound plays: when the value has no entry at the post itself, nothing starts and the post ends at once (its handle is finished). A loop posted once and kept (a tyre bed on a car that may start in the air) needs a Default Container.

```csharp
// Each car's rear tyre bed follows the car's surface; the front axle has its own.
car.SetSwitch(surface, "Kerb");             // the rear bed (and everything else on the car) crossfades to kerb
frontAxle.SetSwitch(surface, "Asphalt");    // the front axle stays on asphalt until it crosses
```

#### Switch Group assets

**Create > Audio System > Switch Group** makes a group asset: its **Group Name** (empty = the asset's name), its **Values** (Asphalt, Kerb, Grass) and a **Default Value** read when nothing is set. Give it to the Switch's **Switch Group** field (the Switch inspector's **Create Switch Group Asset From Name** button makes one from the name and the entries' values), and each entry's value becomes a dropdown.

- A group name and an asset with that name are **one switch**: `AudioManager.SetSwitch("Surface", "Grass")`, state and event SetSwitch actions, and a Switch that only names "Surface" all read and write the asset's switch.
- Setting a value that isn't in the asset's Values warns once per value (a typo would otherwise just play the Default Container).
- The emitter and handle calls take the asset: `car.SetSwitch(surface, "Kerb")`, `handle.SetSwitch(surface, "Kerb")`, `ClearSwitch`, `TryGetSwitch`, and `GetEffectiveSwitch` for what a sound reads.
- A Switch that only names its group reads the values set (by name or through an asset) but not an asset's Default Value: with nothing set, it plays its Default Container, as before.

#### Driven by a parameter

A group can take its value from a parameter: set **Driven By** (a Parameter asset) and its **Ranges**, each a value and where it starts, running up to the next one's start. For example a tyre's slide speed picks Grip from 0, Slide from 0.3 and Skid from 0.7.

- The parameter is read in each sound's scopes, so each axle can drive its own (set the slide speed on that axle's handle).
- **Hysteresis** (in the parameter's unit) is how far past a boundary the parameter must go before the value changes, so a value sitting on 0.3 doesn't flicker between Grip and Slide. Each playing sound remembers its own range.
- A driven group follows only its parameter: a value set directly on it (`SetSwitch` on the manager, an emitter or a handle) is ignored, with one warning.

#### Switch Groups Concept

**What:** Organizational concept for related switches.

**Example:**
```
Switch Group: "Surface_Type"
Values: "Grass", "Metal", "Wood", "Water", "Dirt"

Switch Group: "Weather"
Values: "Clear", "Rain", "Snow", "Fog"

Switch Group: "CharacterType"
Values: "PlayerMale", "PlayerFemale", "EnemyA", "EnemyB"
```

**Setting Switches:**
```csharp
// Set before posting event
AudioManager.Instance.SetSwitch("Surface_Type", "Metal");
footstepEvent.Post(gameObject, transform.position);
// → Plays metal footsteps automatically

// Per character: on its Audio Emitter, with the group asset
playerEmitter.SetSwitch(surfaceType, "Metal");
playerEmitter.Post(footstepEvent);
```

#### When to Use

**Surface-Dependent Footsteps:**
```
Switch Group: "Surface_Type"
Entries:
  - "Grass" → GrassFootstepsContainer (RandomContainer with 6 grass clips)
  - "Metal" → MetalFootstepsContainer (RandomContainer with 5 metal clips)
  - "Wood" → WoodFootstepsContainer (RandomContainer with 6 wood clips)
Default: GenericFootstepsContainer
```

**Weather-Dependent Ambience:**
```
Switch Group: "Weather"
Entries:
  - "Clear" → ClearAmbienceContainer
  - "Rain" → RainAmbienceContainer
  - "Snow" → SnowAmbienceContainer
```

**Character-Specific Voice:**
```
Switch Group: "CharacterType"
Entries:
  - "PlayerMale" → MaleVoiceContainer
  - "PlayerFemale" → FemaleVoiceContainer
```

**Best Practice:** Always provide a `DefaultContainer` as fallback for unknown switch values.

### 4.6 BlendContainer

**Menu:** Create > Audio System > Blend Container

**Purpose:** Plays multiple containers simultaneously, crossfading them by a parameter.

> **Every post is a new copy.** Posting a Blend event again starts another copy of the blend
> alongside the one already playing, like any other container (two engines using the same
> blend). **Each copy reads its own value** (§3.4): posted on two Audio Emitters, two engines
> follow two RPMs. Copies with no emitter or handle value follow the global value together. To
> **restart** instead, set the event's **Max Instances to 1**; the inspector offers a one-click
> button. The old copy then stops instantly, without a fade. `handle.Stop()` stops one copy;
> `blend.Stop()` stops them all. Before 3.0, a second post faded the first copy out, so a Blend
> asset could only play once at a time.

#### Properties

```csharp
List<BlendEntry> BlendEntries { get; }          // Layers to blend
AudioParameter BlendParameter { get; }          // The parameter asset, or null
string BlendParameterName { get; }              // The parameter's name (the asset's, when set)
float Volume { get; }                            // Master volume
BlendLoopMode LoopMode { get; set; }             // FromLayers (default), ForceLoop or ForceOneShot
SilentLayerBehaviour SilentLayers { get; set; }  // KeepPlaying (default) or Virtualize
float SilentThresholdDb { get; set; }            // Virtualize: below this a layer goes virtual (-60)
bool Loop { get; }                               // Obsolete and not read: see LoopMode
BlendLayout Layout { get; set; }                 // VolumeCurves (default) or Regions
CrossfadeShape Crossfade { get; set; }           // Regions: Linear, EqualPower (default) or SCurve
AudioParameter PitchFollowParameter { get; set; } // Pitch follow: each layer plays at value ÷ its Root Value
IReadOnlyList<AudioVoice> LayerVoices { get; }  // Layer voices of every live play of this asset
float GetCurrentBlendValue()                     // The value a copy with no emitter or handle value reads
void AutoLayout()                                // Regions from the layers' Root Values
```

**Choosing the parameter.** Set **Blend Parameter** to a Parameter asset: the curves' X axis is then in its unit (RPM, m/s) and values are clamped to its range. Or leave it empty and type a **Blend Parameter Name**: values are clamped to 0–1, as Blends always read them. The inspector's **Create Parameter Asset From Name** button turns a name into an asset with a 0–1 range, so existing curves read the same; code calling `SetRTPC` with that name keeps working.

The Blend's other settings inherited from the container base (3D, distances, mixer group, occlusion, randomization) are not applied to its layers; each layer uses its own. Only **Volume** and the curves always reach the layers. A layer can take the Blend's 3D settings (**Uses Parent Positioning**) or Mixer Group (**Uses Parent Output**), §4.1: set them once on the Blend and tick the box on each layer.

#### BlendEntry Structure

```csharp
[Serializable]
public class BlendEntry
{
    public AudioContainer container;          // Layer container
    public AnimationCurve volumeCurve;        // Volume Curves layout: parameter value → layer level (0-1)
    public float rootValue;                   // The value it was recorded at (an engine loop's RPM)
    public float regionMin, regionMax;        // Regions layout: where it plays
    public float fadeInWidth, fadeOutWidth;   // Regions layout: how far in from each edge it reaches full level
    public bool followPitch = true;           // Pitch follow on for this layer
    public float followRangeSemitones = 12f;  // Pitch follow never moves it further than this
    public List<ParameterCurve> curves;       // Extra curves for this layer only (§4.1)
}
```

#### Two Layouts: Volume Curves or Regions

**Volume Curves** (the default, and every Blend made before 3.1): each layer's level is its own drawn curve against the Blend's parameter, 0 to 1.

**Regions:** each layer plays in a region of the parameter and crossfades with its neighbours, so nothing has to be drawn:
- Give each layer its **Root Value**: for an engine loop, the RPM it was recorded at.
- Press **Auto Layout** in the inspector. It sorts the layers by root and gives each one a region from half way to the lower neighbour's root to half way to the upper one's; each crossfade is centred on that half-way point and covers **Auto Layout Fade** of the gap (0.5 = half). The lowest layer reaches down to the parameter's Min and the highest up to its Max. Edit the numbers afterwards if you like.
- **Crossfade Shape:** **Equal Power** (the default) keeps the loudness steady when the layers are separate recordings, like engine loops at different RPMs: each is at -3 dB at the middle. **Linear** suits layers recorded together (-6 dB at the middle). **S-Curve** eases in and out.

The inspector lists every layer's region.

#### Pitch Follow

Set **Pitch Follow Parameter** (usually the same RPM parameter) and each layer plays at the parameter's value ÷ its **Root Value**: a loop recorded at 4000 RPM plays at 1.25× at 5000 RPM. Every layer stays in tune with the engine, and so with the others, with no pitch curve to draw.
- **Follow Range** (±12 semitones by default) caps how far a layer is pushed; **Follow Pitch** off leaves a layer alone (a whine that shouldn't move, say).
- Pitch follow goes into the pitch stack's `Follow` slot, so a handle's pitch offset and randomization still apply on top (§3.2).
- **Tuning check:** the inspector shows how far each layer is pitched across the part of the range where it can be heard, and warns past **Tuning Warning** semitones (5 by default). Recordings stretched much further start to sound wrong; add a layer in between or narrow the regions.
- Unity changes pitch once per frame, in a step, so a very fast sweep at a low frame rate steps slightly; parameter smoothing (§3.4) keeps each step small.
- Use pitch follow instead of `SetPitchOffset` on the whole handle for engines: one handle pitch can't keep layers recorded at different RPMs in tune.

#### How It Works

**Starting a play:**
- Every entry's container is played, all with the same position and parent. A layer can start more than one voice (a Routing layer with three clips starts three), and every one of them joins the post's handle.
- Each layer voice gets the Blend's **Volume** multiplied into its `GainStack.MultiplierGain`.
- The play reads its parameter (handle, then emitter, then global, then default) and sets each layer's level, so the layers start at the right level.
- Every layer starts on **one DSP time**, the play's: two DSP buffers ahead (one buffer later than a single voice, so a walk through many layers can't straddle a buffer), or the post's explicit DSP time. The layers are sample-aligned and stay so.

**Every frame:**
- Each live play reads its parameter again (after smoothing, §3.4) and, for each layer voice, works out the level of the entry that **started** that voice (its curve, or its region), writing it into `GainStack.RtpcGain`. Pitch follow and any parameter curves are updated in the same pass. This runs after every LateUpdate, before the frame's audio is mixed (§3.4).
- Paused and virtualized layers are updated too, so the level is right when they resume.

**Nesting.** Any container can be a layer, including another Blend or a Switch. Each play keeps a tree of the containers it reached, so every nested Blend reads its own parameter in that play's scopes (the handle's value, then the emitter's, then global), and a layer under several Blends gets the product of their curves. (Before 3.1, whichever value had changed last won.) For example, an engine: a Blend on load over two Blends on RPM (the on-load and off-load sets); load crossfades the sets while RPM moves inside both, per car.

**Things to know:**
- Voices that a layer starts later (an auto-advancing Sequence's next clip) start at their place in the tree, so they get the Blend's Volume and curve like the first clip. (Before 3.1 they started at full level.)
- Only plays with a Blend somewhere in their tree are updated every frame; a play without one costs nothing per frame.
- A steal takes a whole Blend play or none of it, never one layer (§3.2, Voice Stealing). For a sound that must never be stolen, tick **Persistent** on its event (§5.3).
- `UpdateBlend(value)` is obsolete: it sets the parameter's global value. Set the parameter instead.

**Loop Mode.** Whether the layers loop. **From Layers** (the default): each layer loops as its own container's Loop setting says, as Blends always did. **Force Loop**: every layer loops. **Force One Shot**: none does. A Blend inside another one that leaves its Loop Mode at From Layers takes the outer one's. The old **Loop** checkbox was never read and is gone from the inspector; Sound Builder (Simple) now sets Loop Mode (its Loop ticked = Force Loop).

**Silent Layers.** **Keep Playing** (the default): a layer near silence keeps its real voice, sample-locked with the others, which music stems need. **Virtualize**: a layer whose own level is below **Silent Threshold** (−60 dB by default) goes virtual, freeing its real voice, and comes back once it is 6 dB above it. "Its own level" is its volume, the Blend's crossfade and its curves; the bus, occlusion, a stop fade or a crossfade don't count. A virtual layer keeps its place in the clip (§3.2), so it comes back in step with the others, about 54 dB down, where its short fade-in can't be heard on a slow sweep. The fade-in takes at least three frames (75 ms at 40 fps), so a layer that must be back within a few frames is late at low frame rates: an engine's off-load set, parked at full throttle, against a 50 ms rev-limiter cut. Give such a Blend Keep Playing. A layer that is already silent when the sound starts starts virtual and is never heard starting. A silent layer is never stolen on its own; it lives and ends with its sound. For an engine of 14 layers of which 2–4 are heard at a time, this keeps it to 2–4 real voices. A Blend inside another one that leaves this at Keep Playing takes the outer one's.

#### Designing Volume Curves

**Concept:** AnimationCurve maps the parameter's value (X: 0–1 for a named parameter, the asset's unit for a Parameter asset) to layer level (Y: 0–1).

**Example: Combat Intensity Music (3 layers)**

**Layer 0 - Ambient:**
```
Curve:
  (0.0, 1.0) → Full volume at calm
  (1.0, 0.0) → Silent at combat
```

**Layer 1 - Tension:**
```
Curve:
  (0.0, 0.0)  → Silent at calm
  (0.5, 1.0)  → Full volume at medium intensity
  (1.0, 0.0)  → Silent at full combat
```

**Layer 2 - Combat:**
```
Curve:
  (0.0, 0.0) → Silent at calm
  (1.0, 1.0) → Full volume at combat
```

**Result:**
```
RTPC = 0.0:   Ambient: 100%, Tension: 0%,   Combat: 0%    (calm)
RTPC = 0.25:  Ambient: 75%,  Tension: 50%,  Combat: 0%    (alert)
RTPC = 0.5:   Ambient: 50%,  Tension: 100%, Combat: 50%   (tense)
RTPC = 0.75:  Ambient: 25%,  Tension: 50%,  Combat: 75%   (fighting)
RTPC = 1.0:   Ambient: 0%,   Tension: 0%,   Combat: 100%  (intense combat)
```

#### When to Use

**Dynamic Music:**
```
Layers: Ambient, Tension, Combat
RTPC: "CombatIntensity" (driven by enemy count/proximity)
```

**Vehicle Engine:**
```
Layers: Idle, Load, Redline
RTPC: "EngineRPM" (driven by speed/throttle)
```

**Weather Intensity:**
```
Layers: Calm, Moderate, Storm
RTPC: "WeatherIntensity"
```

**Proximity Blending:**
```
Layers: Distant, Medium, Close
RTPC: "DistanceToPlayer"
```

**Best Practice:** Design curves in Unity's Animation Curve editor for visual feedback.

### 4.7 Generated Engines (Unity 6.3 and later)

An engine can be played from sweeps instead of loops: the **Granular Engine** cuts a recorded or synthesised sweep into
engine cycles and plays them at the car's RPM, so a fast rev glides through every RPM with no band crossfade. The
**Additive Engine** adds the engine's firing orders as sine tones, for weight. Both are containers whose sound is
computed while they play (Unity 6.3's audio generators), on Pepper's voices like any other: buses, panning, Doppler,
filters, pause, virtual voices and Blend nesting all apply. They are in the `SFXSystem.Generators` assemblies, which
compile only on **Unity 6000.3 and later**; on earlier versions they don't exist, and the rest of Pepper is unchanged.

**Which engine when:**
- **A loop blend** (the engine recipe, §3; the Engine Builder, §10.8): steady character, predictable, every behaviour a
  layer you control. Its weakness is fast revs, where each loop is stretched until its neighbour takes over.
- **A granular engine:** the best response and transitions, from two sweeps per car. Its weakness is a held RPM, which
  can sound frozen; it varies the grains to avoid that.
- **Both, or either with an additive layer:** a Blend whose layers are the engines, each at full level. This is how
  most current racing games build theirs.

**1. Make the sweeps.** An **on-load sweep** is the engine climbing at full throttle, idle to redline; an **off-load
sweep** is it falling with the throttle closed. Mono (or folded to mono), steady and slow enough to give at least 10
grains per 1000 RPM: 10 s from 1000 to 9000 RPM is plenty. A synthesised sweep is ideal, because its RPM is known
exactly: note its range and whether it moves in a straight line or evenly in pitch (most synthesisers). Set each clip to
**Decompress On Load**: the engine reads its samples.

**2. Cut them into grains** with **Window > Audio System > Engine Grains** (§10.10). Each sweep becomes a **Grain
Table**: one grain per engine cycle (two turns), tagged with its RPM.

**3. Make the engine:** **Create > Audio System > Granular Engine (Unity 6.3+)**.
- **Rpm** and **Load**: the same parameters a loop engine reads (EngineRpm, EngineLoad01). Without Load it plays on
  load only.
- **On Load** and **Off Load**: the two Grain Tables, blended by load at equal power.
- **Idle** and **Idle Rpm** (optional): an idle loop and the RPM it was recorded at. Below Idle Rpm the idle plays
  alone, pitched to the RPM; between it and the sweeps' lowest RPM the two crossfade.
- **Crossfade Ms** (3): how long each grain fades into the next. The grains are cut in phase, so the fade's gains sum to
  1 and a join isn't heard.
- **Variation** (2): at each grain, a random pick among up to this many neighbours within half a semitone of the RPM,
  so a held RPM never repeats one grain.

Each grain is played by the RPM the sweep had at every point of it, not by its average: the sweep climbed while the
grain was recorded, and played at one speed a held RPM would warble once a cycle (fixed after `3.1.0-dev.11`).

**4. Play it** like any engine: an event with **Persistent** on and a **Target Bus**, posted on the car's Audio Emitter
(§3.4). The game writes RPM and load on the emitter as it does for a loop engine; nothing in the game's code changes.
Each car's voice reads its own values. A generated engine moves to each frame's values over the time that frame took,
so a rev climbs at an even pace whatever the frame rate; it hears them about a frame and two audio buffers late
(25–75 ms).

**5. Tune it by ear** in the **Audition** (§10.5): the Rpm and Load parameters get sliders, and a sweep on Rpm plays a
rev. Generators play outside Play mode.

**An additive layer** (optional): **Create > Audio System > Additive Engine (Unity 6.3+)**. Order 1 is the firing
frequency, RPM × **Cylinders** ÷ 120 (Cylinders is a scale, as in Loop Analysis: 6 under loops or sweeps tuned to notes
at RPM ÷ 20 Hz). Each order (0.5, 1, 1.5, 2… up to 16 of them) has a level **Off Load** and **On Load**, and the load
moves between them; a little noise, low-passed at **Noise Brightness** times the firing frequency, takes the edge off.
It isn't a whole engine: on its own it sounds synthetic. Put it under an engine in a Blend:

```
Car_Engine (Blend, 3D, no blend parameter; each layer at full level)
├── Car_Granular   (Granular Engine)            or the Engine Builder's loop tree
└── Car_Weight     (Additive Engine, Volume 0.3)
```

Leave **Follow Pitch** off for a generator layer: it already plays at its RPM (the Container Validator says so).

**What it costs.** Measured on the development PC, without Burst: a granular engine with both sweeps playing takes
about 0.4% of a CPU core, and an additive layer of 16 orders about the same. To measure on the target (a Steam Deck),
switch the measurement on in a build, drive for a while, and log it:

```csharp
using AudioSystem.Generators;

GeneratorCost.Measuring = true;                      // starts a new measurement
// ... drive for 10 seconds ...
Debug.Log(GeneratorCost.Report(enginesPlaying));     // buffers, µs per buffer, share of a core per instance
GeneratorCost.Measuring = false;
```

**Good to know:**
- A Grain Table keeps a reference to its sweep, not a copy: re-analyse after editing the sweep, and the next play
  reads it again.
- Below the sweeps' lowest RPM with no idle loop, and across a gap in the sweep, the nearest grain is stretched.
- A Sequence container can't hold a generator (its entries are clips).
- The Container Validator checks generator containers: nothing to play, no RPM parameter, a table with no grains, a
  sweep that can't be read, an off-load sweep with no Load parameter, a silent additive layer.

## Events System

Source: https://peppersfx.com/docs/manual/events-system/

### 5.1 AudioEvent Overview

**Location:** `Events/AudioEvent.cs`

**Purpose:** Triggers audio with complex behaviors and multiple actions.

#### Core Properties

```csharp
string EventName { get; }                    // Unique identifier
List<EventAction> Actions { get; }           // Actions to execute
VoicePriority Priority { get; }              // Voice stealing priority
int MaxInstances { get; }                    // Concurrent instance limit (0 = unlimited)
VoiceStealBehavior StealBehavior { get; }    // How to steal when max reached
float Cooldown { get; }                      // Minimum time between triggers
```

#### Timed posts: a moment of the sound at a DSP time

A pass-by whoosh must have its peak land on the moment the cars pass. Post it saying which point of the sound (seconds into its clips, at their recorded pitch) is heard at which DSP time (`AudioSettings.dspTime`):

```csharp
// The whoosh peaks 0.5 s into its clip; the pass is predicted 0.3 s from now. Start 0.2 s in, now.
double pass = AudioSettings.dspTime + 0.3;
float startAt = 0.2f;
otherCar.Post(whooshEvent, pass - (0.5 - startAt), startAt, PostValues.Of(closing, speed));
// Also: whooshEvent.Post(emitter, startDsp, startOffset, values), AudioManager.Post(evt, emitter, ...),
// and whooshEvent.Post(source, position, startDsp, startOffset, values) without an emitter.
```

- **If that time has passed** (or is nearer than the next DSP buffer, as "now" always is), the sound starts at the next buffer, that much further into the clip at its pitch, so the moment still lands on time. A one-shot already past its end plays nothing (its handle finishes at once); a loop wraps round.
- Every voice the event's Play actions start with takes the offset, so a Blend's layers stay together. A Sequence's later clips start from their beginning. A Play action with a **Delay** keeps its own timing and starts from the beginning.
- The older `Post(..., scheduledDspTime)` overloads are unchanged: they start the clip from its beginning, at that time or the next buffer.

**How long will it play?** `evt.EstimateDuration(values)` (or `EstimateDuration(emitter, values)`) says before posting, as an `AudioDuration`: `Shortest` and `Longest` seconds (at the recorded pitch), `Loops`, and `IsKnown` (false when nothing would play). A Random container gives its shortest and longest clip; a Switch the choice the values pick (the post's values, then the emitter's, then global); a Blend or Routing container its longest layer; a Sequence the entry it plays next, or with Auto Advance the rest of the run; each Play action counts with its Delay added. It draws no random numbers, so it can't change what a networked post picks.

```csharp
var length = whooshEvent.EstimateDuration(PostValues.Of(closing, speed));
float preRoll = 0.5f;                                       // where the whoosh peaks, from your own authoring
float startAt = Mathf.Max(0f, preRoll - (float)(pass - AudioSettings.dspTime));   // late into the clip when the warning is short
if (length.IsKnown && startAt < length.Shortest) otherCar.Post(whooshEvent, pass - (preRoll - startAt), startAt);
```

### 5.2 Event Actions

**Concept:** One event can execute multiple actions sequentially or with delays.

#### Available Action Types

```csharp
public enum ActionType
{
    Play,              // Play a container
    Stop,              // Stop a container (only plays this event started)
    Pause,             // Pause this event's voices
    Resume,            // Resume this event's paused voices
    SetSwitch,         // Set a switch value
    SetRTPC,           // Set RTPC parameter
    SetState,          // Activate a state
    TriggerDucking,    // Duck target buses
    CrossFade          // Crossfade between containers
}
```

Stop, Pause and Resume only affect sounds started by the same event. They can't reach a sound another event started, such as music. To stop that, keep the handle `Post` returned and call `Stop` on it.

**Scope.** A Stop, Pause or Resume action acts on **All** of the event's sounds that are playing, on every object (the default, as before 3.1), or, with **This Emitter**, only on those posted on the Audio Emitter the event is posted on. With This Emitter, posting a car's "engine restart" event (Stop, then Play) on one car no longer stops every other car's engine. Posted without an Audio Emitter, This Emitter acts on all of them.

#### EventAction Structure

```csharp
[Serializable]
public class EventAction
{
    public ActionType actionType;
    public ActionScope scope;                // Stop/Pause/Resume: All (default) or ThisEmitter
    public AudioContainer container;         // For Play/Stop/CrossFade
    public AudioBus targetBus;               // Play/CrossFade routing; TriggerDucking's trigger bus
    public float delay;                      // Delay before executing (seconds)
    public float fadeDuration;               // Stop fade-out; CrossFade/SetRTPC/SetState transition;
                                             // TriggerDucking hold time. Play ignores it.

    // For SetSwitch
    public string switchGroup;
    public string switchValue;

    // For SetRTPC
    public string rtpcParameter;
    public float rtpcValue;

    // For SetState
    public string stateName;
    public float stateTransitionTime;

    // For CrossFade
    public AudioContainer fromContainer;
    public AudioContainer toContainer;
    public CrossfadeType crossfadeType;
}
```

#### Multi-Action Example

**Use Case:** Music with intro and loop

```
Event: "Start_MainMusic"

Action [0]:
  - Type: Play
  - Container: Music_Intro_RC
  - Target Bus: Music_Bus
  - Delay: 0s

Action [1]:
  - Type: Play
  - Container: Music_Loop_RC
  - Target Bus: Music_Bus
  - Delay: 8.5s  ← Length of intro
```

**Result:** Intro plays immediately, and the loop starts within about a frame of the intro's end (a delayed action waits on a frame timer). For a sample-accurate join, see the Music Systems recipe in the Cookbook.

### 5.3 Instance Limiting

**Purpose:** Prevent event spam (e.g., 100 footsteps playing simultaneously).

#### Configuration

```csharp
[SerializeField] private int maxInstances = 0;  // 0 = unlimited
[SerializeField] private VoiceStealBehavior stealBehavior = VoiceStealBehavior.Oldest;
```

#### What counts as one instance

An instance is one **play**: everything a single Play action starts. Some containers start several voices at once: a Routing container with three clips, a Blend with two layers, a Switch that selects either of those. That is still **one** instance, and it stays live until its **last** voice ends. A steal ends the whole play at once, with every one of its voices stopping together. An event with two Play actions counts two instances per post. A multi-position post counts one instance per emitter, and its limit is `maxInstances × emitter count`.

#### Steal Behaviors

**Oldest:**
```
Behavior: Stop the play that started first, play the new one
Use For: Most sounds (footsteps, weapons)
```
Judged by start time, not playback position. A loop that has run for minutes is the oldest even when it has just wrapped back to the start of its clip. Plays posted in the same frame are tied, and the tie goes to the one posted first.

**Quietest:**
```
Behavior: Stop the quietest play (judged by its loudest voice), play the new one
Use For: Sounds where loudness matters (explosions)
```

**Furthest:**
```
Behavior: Stop the most distant play (judged by its nearest voice), play the new one
Use For: Spatial sounds where proximity matters (ambience, 3D SFX)
```

**LowestPriority:**
```
Behavior: Stop the lowest-priority play
Use For: Mixed priority scenarios
```

The steal is checked when a post arrives and before its actions run: if the event is already at `maxInstances`, one play is stopped immediately to make room.

#### Per Audio Emitter

**Max Instances Per Emitter** limits the plays of the event on **one** Audio Emitter at once, on top of Max Instances for the whole game: every car can crackle, but at most 3 crackles per car. When a car is at its limit, Steal Behavior picks which of **that car's** plays ends; other cars are untouched. The play that ends fades out over the Audio Manager's Steal Fade Seconds, like any steal (§3.2), so a burst of pops doesn't click; it used to stop on the spot. 0 = no limit per emitter. Posts without an Audio Emitter (a GameObject, multi-position) aren't counted per emitter.

```
Event: Car_Afterfire
  Max Instances: 0 (no game-wide limit)
  Max Instances Per Emitter: 3
  Cooldown Per Emitter: 0.08 s

30 posts on one car in one frame → 3 crackles on that car; another car's crackle still plays.
```

#### Persistent

Tick **Persistent** on an event whose sounds must never drop out to make room for others, such as a car's engine. The voice pool never steals its plays (§3.2, Voice Stealing). They can still go **virtual** when other sounds matter more, keeping their place in the clip, so they come back in step. The event's **own** Max Instances can still end one of its persistent plays: that is the event's rule.

If the pool is full and only persistent sounds are left in it, a new sound is skipped with a warning ("the voice pool is full of persistent sounds"). Raise **Max Virtual Voices** on the Audio Manager so the persistent sounds fit with room to spare: 8 cars of 14 layers need 112 voices.

Persistent sounds also get Unity's highest `AudioSource.priority`, so if more voices than Unity's own limit ever play, Unity silences other sounds first (Pepper warns at startup when its counts exceed Unity's, §9.1).

### 5.4 Cooldown System

**Purpose:** Prevent rapid re-triggering of the same event.

Each event asset keeps the time it was last posted. Every public post entry point (`Post` and the `PostMultiPosition` overloads) checks it first:

```csharp
// On AudioEvent. lastPlayTime starts at -infinity, so the first post is always allowed.
// Now is Time.time, or Time.unscaledTime when the event's Time is Unscaled.
private bool IsOnCooldown() => Cooldown > 0f && Now - lastPlayTime < Cooldown;
```

- A post rejected by cooldown returns a handle that has already finished, so `OnFinished` still fires.
- `lastPlayTime` is stamped after the post runs.
- The cooldown runs on the event's **Time** (Voice Settings). **Scaled** (the default) is game time, so it freezes while the game is paused (`timeScale` 0): right for gameplay sounds. **Unscaled** is real time: use it for UI and pause-menu sounds, or a button with a cooldown plays once per pause. The same setting covers the event's Delay actions, its sounds' Sequence gaps and its crossfades (§10.3).
- The cooldown belongs to the event, so it applies across every object that posts it, not per object.
- **Cooldown Per Emitter** is a second one per Audio Emitter: one car's posts stay that far apart while another car's still play. Both apply when both are set; same clock.

**Use Case:**
```
Event: UI_ButtonClick
Cooldown: 0.05s

User clicks rapidly → Only one sound per 50ms
Prevents audio spam and performance issues
```

### 5.5 Multi-Position Mode

**What:** Play the same event from multiple emitters simultaneously, perfectly synchronized.

#### Configuration

There is nothing to switch on in the event. Any event can be posted at several positions by calling one of the `PostMultiPosition` overloads instead of `Post`:

```csharp
public AudioMultiHandle PostMultiPosition(Vector3[] positions, GameObject source = null)
public AudioMultiHandle PostMultiPosition(Transform[] transforms, GameObject source = null)
public AudioMultiHandle PostMultiPosition(AudioMultiPositionEmitterParent emitterParent, GameObject source = null)
```

The array overloads play in **synchronized** mode. The `AudioMultiPositionEmitterParent` overload uses the mode set on that component instead, SingleEmitter or Decorrelated (see §8).

#### How It Works

- At most 16 positions are used; extra ones are ignored with a warning.
- The cooldown is checked once for the whole post.
- **Synchronized mode:** every Play action starts once per position. All of those voices, and all the layers of a multi-voice container, are rescheduled to one shared start time, `AudioSettings.dspTime + 0.1`, so they begin on the same sample.
- **Max Instances** is multiplied by the number of positions.
- **`source`** (optional): on a 3D container, each voice still plays at its own position, attached to `source`. The voices move with it, and stop if it is destroyed. Without a source they stay where they were posted. To follow moving transforms, call `RefreshPositions` on the handle.
- The returned `AudioMultiHandle` controls every voice at once, or one emitter at a time by its index (`SetVoiceVolumeScale`, `StopVoice` and the others).

**Key Insight:** All voices use `PlayScheduled` with one shared DSP time for sample-accurate sync. That adds 100 ms of latency.

## Bus & Mixing

Source: https://peppersfx.com/docs/manual/bus-mixing/

### 6.1 Bus Architecture

**Location:** `Events/AudioBus.cs`

**Purpose:** Hierarchical volume control and mixing.

#### Properties

```csharp
string BusName { get; }                  // Identifier
AudioBus ParentBus { get; }              // Hierarchy
AudioMixerGroup MixerGroup { get; }      // Unity AudioMixer integration
float VolumeDb { get; }                  // Volume in decibels (the asset's; SetVolume(dB) changes it)
float VolumeMultiplier { get; }          // Linear multiplier (0-1)
float StateOffsetDb { get; }             // What Offset states add now (§7), runtime only
float PlayerVolumeDb { get; set; }       // The player's volume (§6.8), runtime only
int MaxRealVoices { get; set; }          // Its voice cap (§6.9), 0 = none
int RealVoiceCount { get; }              // Real voices of its sounds (and its children's) now
bool Mute { get; }                       // Mute this bus (SetMute)
bool IsMuted { get; }                    // Muted by itself or a parent
bool Solo { get; }                       // Solo this bus and its child buses (SetSolo; §6.3)
```

A bus's level is **Volume + state offset + player volume**, in dB, times its multiplier, its ducking and its curves, times its parent's. Only Volume is in the asset.

### 6.2 Decibel System

**Why dB instead of 0-1?**

Decibels match how humans perceive loudness (logarithmic, not linear).

**Conversion Formulas:**
```csharp
// dB to linear
float linear = Mathf.Pow(10f, db / 20f);

// Linear to dB
float db = 20f * Mathf.Log10(linear);
```

**Key dB Values:**
```
 +6 dB = 2x louder
  0 dB = No change (1.0 linear)
 -6 dB = ~0.5x quieter
-12 dB = ~0.25x quieter
-20 dB = ~0.1x quieter
-80 dB = Silence (effective zero)
```

### 6.3 Hierarchical Volume

**Concept:** Child buses inherit parent volume.

```
Master Bus: -3 dB (0.707 linear)
└── SFX Bus: 0 dB (1.0 linear)
    └── Weapons Bus: +3 dB (1.41 linear)

Final Weapons Volume = 0.707 * 1.0 * 1.41 ≈ 1.0
```

**Implementation:**
```csharp
public float GetFinalVolume()
{
    float gain = ChainGain(out bool soloed);   // this bus's level times its parents', one walk up the chain
    return anySoloed && !soloed ? 0f : gain;   // while any bus is soloed: heard only if it or a parent is
}

private float ChainGain(out bool soloed)
{
    soloed = solo;
    if (mute) return 0f;                       // mute wins, here or on any parent

    float parent = 1f;
    if (parentBus != null)
    {
        parent = parentBus.ChainGain(out bool parentSoloed);
        soloed |= parentSoloed;
    }
    // The asset's Volume, the states' offset and the player's volume (§6.8), in dB: all three reach child buses.
    float linearDb = Mathf.Pow(10f, (volumeDb + stateOffsetDb + playerVolumeDb) / 20f);
    return volumeMultiplier * linearDb * duckingValue * curveGain * parent;
}
```

**Mute and solo.** Mute silences a bus and every bus under it. Solo works as on a mixing desk: while any bus is soloed, the soloed buses and their child buses are heard, through their parents, whose volume, mute and ducking still apply; every other bus is silenced. **A parent of a soloed bus only passes the soloed bus through: sounds posted straight to that parent are silenced while the solo is on**, as a desk mutes the other channels into a group. To hear a parent's own sounds, solo the parent. Mute still wins: a muted soloed bus, or a muted parent of one, is silent. With no solo on, the check costs nothing.

```
Master
├── SFX
│   ├── Engines   ← soloed: heard, through SFX and Master
│   │   └── Turbo     heard (a child of a soloed bus)
│   └── Tyres         silenced
└── Music             silenced
Sounds posted straight to SFX or Master: silenced.
```

Solo is for authoring: the Mixer window's and the Audio Profiler's **S** buttons set it (Alt-click in the Mixer solos one bus and clears the rest), and **Clear Solos** turns them all off. A solo change reaches every sound already playing, paused and virtual ones too.

### 6.4 Ducking System

**What:** Lower the volume of target buses for a while when this bus's ducking is triggered.

**Use Case:** Music ducks when dialogue plays.

Ducking is **triggered**, not driven by what the bus is playing: an event's **TriggerDucking** action (its Fade Duration is the hold time) or a call to `bus.TriggerDucking(holdSeconds)` starts it (or `targetBus.ApplyDucking(dB, attack, hold, release)` from code). Each target then fades down over the attack, holds, and fades back up over the release. The duck runs on the **target** bus's **Ducking Time**: Scaled (the default, game time, so a duck freezes part way while the game is paused) or Unscaled (real time, so it completes during a pause).

**Ducks combine: the deepest wins.** Each trigger is a duck of its own, and while several run on one bus it follows the deepest at each moment, so none cuts another short: nitro pressed twice gives one continuous duck released after the second press's hold, and a short UI duck during a dialogue duck leaves the dialogue duck as it was. A new duck starts from the level the bus is at, so re-triggering the same duck sounds exactly as one envelope restarting did. (Before 3.1.0-dev.7 the last trigger replaced the duck in progress, so a short or shallow one could cut a long or deep one short.)

#### Configuration

```csharp
bool EnableDucking { get; }                    // Enable ducking feature
List<DuckingTarget> DuckingTargets { get; }    // Buses to duck
float DuckingAttack { get; }                    // Fade down time (default 0.05s)
float DuckingRelease { get; }                   // Fade up time (default 0.2s)
```

#### DuckingTarget Structure

```csharp
[Serializable]
public class DuckingTarget
{
    public AudioBus targetBus;        // Bus to duck
    public float duckAmount = -6f;    // Attenuation in dB, -80..0 (-6 dB is about half the level)
}
```

#### Example Setup

```
Dialogue Bus:
  - enableDucking: true
  - duckingTargets:
      - Music Bus, duckAmount: -10.5 dB (about 30% of the level)
      - SFX Bus, duckAmount: -6 dB (about 50%)
  - duckingAttack: 0.05s (quick duck)
  - duckingRelease: 0.8s (slow return)
Dialogue event: Play the line, plus a TriggerDucking action with Fade Duration = the line's length (the hold)
```

**Result:** When the dialogue event fires, music quickly drops to about 30% of its level and SFX to about 50%. After the hold they return over 0.8s.

### 6.5 Unity AudioMixer Integration

**Setup:**
1. Create AudioMixerGroup in Unity's AudioMixer window
2. Assign to bus's `mixerGroup` field
3. System routes voices through mixer automatically

**Benefits:**
- Use Unity's built-in effects (reverb, EQ, etc.)
- Visual mixing interface
- Snapshots and ducking (separate from Pepper.SFX ducking)

### 6.6 Parameter Curves on a Bus

A bus's **Parameter Curves** move its mix with a parameter, without code: nitro's punch sweeping the world's low-pass, a split-screen mode taking 3 dB off the hero bus. They are the same curves as a container's (§4.1), with three properties:

| Property | Unit | How it applies |
|---|---|---|
| **Volume** | dB | Multiplies into the bus's level, like ducking: every sound on the bus and on its child buses follows. The bus's own Volume setting is untouched. |
| **Low Pass** | Hz | A Lowpass effect on the bus's Mixer Group: one filter for everything routed through that group (reverb tails and ambience included), however many sounds. |
| **High Pass** | Hz | The same with a Highpass effect. |

- Curves read the parameter's **global** value (`AudioManager.SetParameter`), after its smoothing, every frame. A bus is shared by every listening point, so an emitter's or a sound's own value doesn't move it. A move tied to one car (the hero's engine pulling back as it speeds up) is a curve on that car's sound instead.
- **Filters need a Mixer Group and an exposed cutoff.** In the bus inspector, **Add Low Pass to Mixer Group** (and **Add High Pass**) adds a Lowpass Simple (Highpass Simple) effect to the group, exposes its cutoff as `<Bus>_LowPass` and fills in Low Pass Parameter. Or do it by hand: add the effect, right-click its Cutoff freq, Expose it, and type its exposed name. Without one, the curve logs a warning once and does nothing.
- Pepper eases the cutoff over about 20 ms (in octaves) and writes it to the mixer only when it moves. Pitch curves are ignored on a bus.

```
Example: nitro's punch on the other cars
  Parameter asset: NitroPunch (0-1, global)
  Others bus: Mixer Group "Others"; Add Low Pass to Mixer Group
    Parameter Curve: NitroPunch → Low Pass, 0 → 18000 Hz, 1 → 2000 Hz
  Game code: AudioManager.Instance.RampParameter(nitroPunch, 1f, 0.3f), then back to 0
```

### 6.7 Pausing a Bus

For a game's pause, pause the buses the world plays on, and leave the pause menu's buses alone:

```csharp
// The game pauses (time scale 0): the cars and the world hold, the pause menu's clicks and music play on.
worldBus.Pause();      // its child buses (Vehicles, Ambience...) pause with it
// ... and on resume:
worldBus.Resume();
```

- **Pausing fades out.** Every sound on the bus and its child buses fades out over about 25 ms and holds its place, keeping no real voice (so the pause menu's sounds get them). `Pause` on its own would be a click.
- **Resuming carries on from where it was,** fading back in, every layer of an engine in the same frame, so they stay in phase.
- **Sounds posted to a paused bus** follow its **While Paused** setting. **Drop One-shots** (the default): a sound that doesn't loop is dropped before its first sample (a crash under the pause menu shouldn't play later), and a loop starts paused and plays on resume. **Hold**: every sound starts paused and plays on resume.
- **A child bus is paused while it or any parent is paused.** `IsPaused` says so; `Resume` on a child doesn't override its parent's pause.
- **It is a separate pause** from `AudioHandle.Pause` and `AudioManager.PauseAll`, which pause the sound at once, as before. A sound plays again only when none of them pauses it.
- **Timing during a pause:** set the pause menu's events to Time = Unscaled (§5.4) and the buses it ducks to Ducking Time = Unscaled (§6.4), so their cooldowns, delays and ducks run while the time scale is 0.
- A paused sound that isn't Persistent can be stolen first if the pool runs short during the pause, since it is silent; a Persistent one never is.

### 6.8 Player Volume

A Settings page's sliders (master, music, effects) set the **player's volume** on each bus, not its Volume:

```csharp
musicBus.PlayerVolumeDb = AudioExtensions.LinearToDb(musicSlider.value);   // -80 … +24 dB, 0 = as mixed
AudioManager.Instance.MasterVolumeDb = -3f;                                  // or SetMasterVolume(linear)
bool muted = AudioManager.Instance.IsAllMuted;                              // MuteAll's getter
```

- It is a level of its own, on top of the bus's Volume and any state's offset (§7), so a mix state never undoes it and it never undoes one.
- **It is never saved to the asset,** and each play session starts at 0 dB: the game saves the player's settings itself and sets them again at boot. (A bus's Volume, which `SetVolume` and `SetBusVolume` change, is the asset's: in the editor a change made in Play mode stays in it.)
- `AudioManager.GetBus(name)` finds a bus by name. An unknown name returns the master bus, as before, but now warns once; `SetBusVolume` with an unknown name warns once and changes nothing (it used to set the master bus).
- `Example08_AudioSettingsUI` is a complete settings page.

### 6.9 A Bus's Voice Cap

A bus can cap how many real voices its sounds use at once: **Max Real Voices** in its Voices section (0, the default, is no cap). A racing game caps the bus its other cars play on, so a pack of them can't crowd out your own car:

```csharp
othersBus.MaxRealVoices = 12;
int now = othersBus.RealVoiceCount;   // real voices of its sounds and its child buses' now
```

- **It counts** the real voices of the sounds whose Target Bus is this bus or one of its children.
- **Over it, the least important of those sounds go virtual,** a whole sound at a time, exactly as over the Audio Manager's Max Real Voices (§3.2, Voice Virtualization): when a sound starts, and in the voice pass, with the same stickiness. They keep their place and come back in step when there is room. A single sound with more voices than the cap keeps its most important ones.
- **It never ends a sound,** so it frees no voices in the pool: that is still the pool's business (Real + Virtual + Steal Headroom).
- The Audio Manager's Max Real Voices still applies on top. The bus inspector shows the live count in Play mode.

## State System

Source: https://peppersfx.com/docs/manual/state-system/

### 7.1 AudioState Overview

**Location:** `Events/AudioState.cs`

**Purpose:** Change multiple audio parameters based on game mode.

#### Properties

```csharp
string StateName { get; }                         // Unique identifier
string StateGroup { get; }                        // Mutually exclusive group
IReadOnlyList<BusVolumeProperty> BusVolumes { get; }      // Bus volume changes
IReadOnlyList<SwitchProperty> SwitchValues { get; }       // Switch changes
IReadOnlyList<RTPCProperty> RtpcValues { get; }           // RTPC changes
IReadOnlyList<EffectProperty> EffectProperties { get; }   // Mixer effect changes
```

### 7.2 State Groups

**Concept:** States in the same group are mutually exclusive.

**Example:**
```
State Group: "Location"
├── State: "Normal"
├── State: "Underwater"
└── State: "Cave"

State Group: "GameplayState"
├── State: "Menu"
├── State: "Playing"
└── State: "Paused"
```

**Behavior:**
- Only one state per group is active at a time
- Setting "Underwater" makes it the group's active state in place of "Normal" or "Cave"
- Different groups can have active states simultaneously
- Setting a state **applies its own values only**. Nothing from the previous state is undone, so give each state in a group a value for every bus, switch and RTPC its siblings change ("Normal" sets the SFX bus back to 0 dB, for example). The exception is a state whose **Bus Volume Mode** is **Offset** (below): its bus offsets go back when it ends.
- State names are unique across all groups
- Setting the state that is already active does nothing
- `AudioManager.ClearState(group, transitionTime)` leaves a group's state without setting another: an Offset state's offsets go back; nothing else is undone

#### Bus Volume Mode: Set Level or Offset

| Bus Volume Mode | The dB values mean | Leaving the state |
|---|---|---|
| **Set Level** (default, as before 3.1) | Each bus's level: written into its Volume, the same value the bus inspector and `SetBusVolume` set (so in the editor it stays in the asset after Play) | Nothing is put back |
| **Offset** | How far each bus moves, in a slot of its own on top of its Volume and the player's volume (§6.8). The asset is never changed. | The offsets go back, over the next state's (or `ClearState`'s) transition time |

Use **Offset** for mix states, so they never undo a Settings page:

```
State Group "Mode":
  Mix_Single      (Offset, no bus volumes)
  Mix_LocalSplit  (Offset: Hero -3 dB, Speed -3 dB)
AudioManager.Instance.SetState("Mix_LocalSplit", 0.5f);   // Hero moves -3 dB over 0.5 s
AudioManager.Instance.SetState("Mix_Single", 0.5f);       // and back
```

- Offset states in different groups add up on a bus (Split −3 dB and Nitro +2 dB: −1 dB); leaving one takes only its part away.
- The offset moves in a straight line in dB over the transition time, on unscaled time, in Pepper's per-frame step. A bus shows it as `StateOffsetDb` (and in its inspector in Play mode).
- A state's switches, RTPCs and effect properties work the same in both modes.

### 7.3 State Properties

#### BusVolumeProperty

```csharp
[Serializable]
public class BusVolumeProperty
{
    public AudioBus bus;
    public float volumeDb;
}
```

**Example:**
```
State: "Underwater"
BusVolumes:
  - SFX Bus: -9 dB (muffle sounds)
  - Music Bus: -12 dB (distant music)
  - Dialogue Bus: -6 dB (slightly muffled)
```

#### SwitchProperty

```csharp
[Serializable]
public class SwitchProperty
{
    public string switchGroup;
    public string switchValue;
}
```

**Example:**
```
State: "Underwater"
SwitchValues:
  - switchGroup: "Location", switchValue: "Underwater"
  - switchGroup: "Reverb", switchValue: "LargeHall"
```

#### RTPCProperty

```csharp
[Serializable]
public class RTPCProperty
{
    public string parameterName;
    public float value;
}
```

**Example:**
```
State: "Combat"
RtpcValues:
  - "MusicIntensity": 1.0
  - "HeartbeatIntensity": 0.8
```

#### EffectProperty

```csharp
[Serializable]
public class EffectProperty
{
    public AudioBus bus;
    public string propertyName;
    public float value;
}
```

**Example:**
```
State: "Underwater"
EffectProperties:
  - Bus: Master, Property: "ReverbMix", Value: 0.8
  - Bus: SFX, Property: "LowpassCutoff", Value: 1000.0
```

### 7.4 State Transitions

**Transition Time:** Controls how smoothly parameters change.

```csharp
public void SetState(string stateName, float transitionTime = 0.5f)
{
    if (!states.TryGetValue(stateName, out var nextState)) return;   // logs a warning
    if (activeStatesByGroup.TryGetValue(nextState.StateGroup, out var current) && current == nextState)
        return;                                                       // already active

    activeStatesByGroup[nextState.StateGroup] = nextState;
    nextState.Apply(transitionTime);
}
```

**Apply Implementation** (simplified):
```csharp
public void Apply(float transitionTime)
{
    var manager = AudioManager.Instance;

    // Bus volumes (Set Level): transition over transitionTime, or set at once when it is 0.
    // (An Offset state's bus volumes are moved by SetState and ClearState, which know the group.)
    foreach (var busVol in BusVolumes)
    {
        if (transitionTime > 0f) manager.TransitionBusVolume(busVol.bus, busVol.volumeDb, transitionTime);
        else busVol.bus.SetVolume(busVol.volumeDb);
    }

    // Switches: always immediate (switches don't transition)
    foreach (var sw in SwitchValues)
        manager.SetSwitch(sw.switchGroup, sw.switchValue);

    // RTPCs: transition over transitionTime too, or set at once when it is 0
    foreach (var rtpc in RtpcValues)
    {
        if (transitionTime > 0f) manager.TransitionRTPC(rtpc.parameterName, rtpc.value, transitionTime);
        else manager.SetRTPC(rtpc.parameterName, rtpc.value);
    }

    // Mixer effect properties: transition over transitionTime
    foreach (var effect in EffectProperties)
        manager.SetBusEffectProperty(effect.bus, effect.propertyName, effect.value, transitionTime);
}
```

> **Two quick state changes and RTPCs:** a newer RTPC transition on the same parameter replaces the one running (`TransitionRTPC`, §3.4), so changing state again before the first transition ends moves the value from where it is to the new state's value. Bus volume transitions replace each other the same way.
>
> **Effect properties** are found by name: the mixer must expose a parameter called `<BusName>_<Property>`, for example `SFX_LowpassCutoff`.

### 7.5 Common State Patterns

**Underwater State:**
```
StateGroup: "Location"
StateName: "Underwater"

BusVolumes:
  - SFX: -9dB
  - Music: -12dB
  - Ambience: -6dB

SwitchValues:
  - "Location": "Underwater"

RtpcValues:
  - "Underwater": 1.0

TransitionTime: 1.5s
```

**Pause State:**
```
StateGroup: "GameplayState"
StateName: "Paused"

BusVolumes:
  - SFX: -20dB
  - Music: -12dB
  - UI: 0dB (unchanged)

TransitionTime: 0.3s
```

**Combat State:**
```
StateGroup: "CombatState"
StateName: "InCombat"

RtpcValues:
  - "MusicIntensity": 1.0
  - "HeartbeatIntensity": 0.7

TransitionTime: 2.0s
```

## Multi-Position Audio

Source: https://peppersfx.com/docs/manual/multi-position-audio/

### 8.1 Concept

**What:** Multiple speakers playing synchronized audio at different 3D positions.

**Real-World Example:** Nightclub with 8 speakers playing the same music.

**Challenge:** Without synchronization, speakers have phasing issues (sounds canceling out).

**Solution:** DSP-scheduled playback ensures sample-accurate synchronization.

### 8.2 Architecture

#### AudioMultiPositionEmitterParent

**Component:** Manages child emitters

**Properties:**
```csharp
int maxEmitters = 16;                    // Limit (1-16)
bool autoFindChildren = true;            // Auto-detect children
bool autoUpdateChildren = true;          // Update when hierarchy changes
```

**Methods:**
```csharp
Vector3[] GetActivePositions();          // Positions of active emitters
Transform[] GetActiveTransforms();       // Transforms of active emitters
int ActiveEmitterCount { get; }          // Number active
void EnableAllEmitters();
void DisableAllEmitters();
void SetAllVolumes(float volume);
void RefreshChildren();
```

#### AudioMultiPositionEmitterChild

**Component:** Individual emitter point

**Properties:**
```csharp
bool isActive = true;                    // Enable/disable
float volumeMultiplier = 1f;             // Per-emitter volume (0-1)
bool useDirectionality = false;          // Draws a cone gizmo in the Scene view (no effect on sound)
float coneAngle = 90f;                   // That gizmo's cone angle (0-360)
```

**Properties (Read-Only):**
```csharp
Vector3 Position { get; }                // World position
Quaternion Rotation { get; }             // World rotation
Vector3 Forward { get; }                 // Forward direction
```

### 8.3 DSP Synchronization

**Problem Without Sync:**
```
Speaker A starts: Frame 1, Sample 0
Speaker B starts: Frame 1, Sample 512  ← Delayed by 512 samples
Speaker C starts: Frame 2, Sample 0    ← Delayed by ~2000 samples

Result: Phasing, echoing, muddy sound
```

**Solution With DSP Scheduling:**
```csharp
double dspTime = AudioSettings.dspTime + 0.1; // Schedule 100ms ahead

foreach (var position in emitterPositions)
{
    var voice = GetVoice();
    voice.source.clip = clip;
    voice.source.transform.position = position;
    voice.scheduledStartTime = dspTime;
    voice.source.PlayScheduled(dspTime);
}
```

**Result:** All speakers start at exact same DSP sample, perfect synchronization.

### 8.4 Setup Tutorial

**Step 1: Create Parent**
```
1. Create empty GameObject: "NightclubSpeakers"
2. Add component: AudioMultiPositionEmitterParent
3. Configure:
   - maxEmitters: 8
   - autoFindChildren: ✓
```

**Step 2: Create Children (Manual)**
```
1. Create child GameObject: "Speaker_01"
2. Position at (10, 2, 0)
3. Add component: AudioMultiPositionEmitterChild
4. Repeat for 8 speakers in circle pattern
```

**Step 2: Create Children (Auto - Inspector Button)**
```
1. Select parent
2. In Inspector, click "Create 8 Child Emitters (Circle Pattern)"
3. Automatically creates 8 speakers in circle
```

**Step 3: Create Event**
```
1. Create AudioEvent
2. Add action: Play music container
   (No multi-position setting is needed on the event: Step 4 posts it with PostMultiPosition.)
```

**Step 4: Script**
```csharp
using UnityEngine;
using AudioSystem;

public class NightclubAudio : MonoBehaviour
{
    [SerializeField] private AudioEvent musicEvent;
    private AudioMultiHandle musicHandle;

    void Start()
    {
        var parent = GetComponent<AudioMultiPositionEmitterParent>();
        musicHandle = musicEvent.PostMultiPosition(parent);

        Debug.Log($"Playing on {musicHandle.VoiceCount} speakers");
    }

    void OnDestroy()
    {
        musicHandle?.Stop(2f); // Fade out over 2s
    }
}
```

### 8.5 Per-Emitter Control

**Volume:**
```csharp
// Individually
emitterChild.VolumeMultiplier = 0.75f;

// All at once
emitterParent.SetAllVolumes(0.5f);
```

**Active State:**
```csharp
// Individual
emitterChild.IsActive = false; // Disable this speaker

// All
emitterParent.DisableAllEmitters();
emitterParent.EnableAllEmitters();
```

**Directionality (Scene view only):**
```csharp
emitterChild.UseDirectionality = true;
emitterChild.ConeAngle = 90f;  // draws a 90° cone along transform.forward
```
These two only draw a cone gizmo to help you aim an emitter. Playback doesn't read them: every active emitter is heard the same in every direction. To make one quieter, use its Volume Multiplier.

### 8.6 Use Cases

**Nightclub Speakers:**
```
Setup: 8 speakers in circle
Audio: Looping music
Result: Immersive club environment
```

**Stadium Announcer:**
```
Setup: 12 speakers around stadium
Audio: Announcer voice
Result: Realistic PA system
```

**Vehicle Multi-Speaker:**
```
Setup: 4 speakers (FL, FR, RL, RR)
Audio: Radio/music
Result: Realistic car audio
```

**Ambient Sound Array:**
```
Setup: 6 speakers in outdoor environment
Audio: Wind/nature ambience
Result: Enveloping soundscape
```

### 8.7 Performance Considerations

**Voice Count:**
- 1 multi-position event with 8 emitters = 8 voices
- Monitor total voice count: `AudioManager.Instance.GetStatistics()`

**Instance Limiting:**
```
Event: Multi-position music
MaxInstances: 1  ← Only one instance of entire array
```

**Occlusion:**
- Each emitter can be individually occluded
- Can be expensive with many emitters
- Consider disabling occlusion for some emitters

**Distance Culling:**
- Virtualization works per-voice
- Under voice pressure, distant emitters are virtualized first (importance falls with distance)
- No special handling needed

## Performance & Optimization

Source: https://peppersfx.com/docs/manual/performance-optimization/

### 9.1 Voice Management

#### Voice Limits

**Default Configuration:**
```csharp
maxRealVoices = 32;      // Physically playing sounds
maxVirtualVoices = 64;   // Virtualized sounds (time-tracking only)
```

**What Happens When Limit Reached:**
1. Over `maxRealVoices`, or over a bus's own Max Real Voices (§6.9): the least important **plays** go virtual (a play is a whole sound, all of an engine's layers), keeping their place in the clip (§3.2, Voice Virtualization).
2. Over Real + Virtual: an event makes room for its whole new play by ending whole plays, silent virtual ones first, then the least important. Persistent ones (§5.3) are never ended. If there isn't room even then, the new sound is skipped and nothing is stolen. A stolen sound fades out over Steal Fade Seconds (§3.2). `VoiceStealBehavior` only applies to an event's own Max Instances.
3. Critical priority makes a sound the last to go, not exempt: only Persistent plays are never stolen

**Unity's own limits.** Unity has its own Max Real Voices and Max Virtual Voices (Project Settings > Audio; 32 and 512 by default). If Pepper's Max Real Voices is higher than Unity's, or Real + Virtual + Steal Headroom is higher than Unity's virtual count, Pepper warns at startup and the Audio Manager inspector shows the numbers side by side. Over its own real limit, Unity silences sources itself, behind Pepper's back; Pepper sets `AudioSource.priority` from each event's priority (persistent sounds highest) so Unity spares the important ones.

**Recommended Settings:**
```
Desktop/Console: 32-64 real voices
Mobile: 16-24 real voices
VR: 24-32 real voices (high frame rate priority)
```

#### Voice Stealing Strategies

**By Priority:**
```csharp
public enum VoicePriority
{
    Low = 0,       // Weighs 1/8: distant ambience
    Medium = 64,   // Weighs 1/4: standard gameplay
    High = 128,    // Weighs 1/2: player actions
    Critical = 255 // Weighs 1, the strongest (still stealable; Persistent is the exemption): UI, dialogue
}
```
A sound's importance is how loud it is where it's heard times its priority's weight (§3.2), so a near, loud Low sound can outrank a far, quiet Medium one.

**By Behavior:**
```csharp
public enum VoiceStealBehavior
{
    Oldest,          // Steal longest-playing voice
    Quietest,        // Steal quietest voice
    Furthest,        // Steal most distant voice
    LowestPriority   // Steal by priority only
}
```

**Best Practice:**
```
UI sounds: Critical priority
Player footsteps: High priority
Enemy footsteps: Medium priority
Distant ambience: Low priority
```

#### Voice Virtualization

**What Gets Virtualized:**
1. Voices beyond the `maxRealVoices` limit, or a bus's Max Real Voices, least important first (distance × volume × the priority's weight)
2. Sounds past their Attenuation asset's Max Distance (in Spatial Mode = Pepper, from every listening point)
3. Nothing else: there is no other distance threshold, and under the limits every voice plays

**How It Works:**
```csharp
// Becoming virtual (the voice budget does this itself; you can too)
voice.MakeVirtual();
// - Fades out over about 25 ms if it can be heard, then pauses the AudioSource
// - Keeps its place in the clip, in samples, at its pitch
// - No audio output, minimal CPU cost
// - Called from your code: it stays virtual until MakeReal(); the budget won't bring it back

// Becoming real again
voice.MakeReal();
// - Moves the AudioSource to where it would have been, then resumes it
// - Fades back in over about 25 ms
// - Handles looping correctly
```
A voice comes back in phase at any pitch, Pepper's Doppler included, except for Unity's own Doppler, which Pepper can't see: give looping layers that must stay in step Doppler = Pepper, or a Doppler Level of 0 (§3.2, Voice Virtualization).

**Monitoring:**
```csharp
void OnGUI()
{
    var stats = AudioManager.Instance.GetStatistics();
    GUI.Label(new Rect(10, 10, 400, 20),
        $"Real: {stats.activeVoices}/{stats.realVoiceBudget}, " +
        $"Free in the pool: {stats.availableVoices} of {stats.poolSize}");
}
```

### 9.2 Memory Optimization

#### AudioClip Import Settings

**UI Sounds (Small, Frequent):**
```
Load Type: Decompress On Load
Compression Format: PCM
Quality: 100%

Reason: Small file size, instant playback, minimal CPU
```

**SFX (Medium, Common):**
```
Load Type: Compressed In Memory
Compression Format: Vorbis (mobile) or ADPCM (desktop)
Quality: 70-90%

Reason: Balance of file size, memory, and CPU
```

**Music (Large, Streaming):**
```
Load Type: Streaming
Compression Format: Vorbis
Quality: 70-80%

Reason: Large files stream from disk, low memory cost
```

**Ambience (Large Loops):**
```
Load Type: Streaming
Compression Format: Vorbis
Quality: 60-70%

Reason: Long loops, stream from disk
```

#### Resource Loading Strategy

**Startup (Automatic):**
```csharp
// AudioManager.Awake()
var audioEvents = Resources.LoadAll<AudioEvent>("Audio/Events");
var audioStates = Resources.LoadAll("Audio/States", typeof(AudioState));
```

**Key Insight:** Events and States load once at startup. Containers and clips are referenced, not duplicated.

**Memory Footprint:**
```
Events: Minimal (ScriptableObject metadata)
States: Minimal (ScriptableObject metadata)
Containers: Minimal (references to clips)
Clips: Depends on import settings
Voices: Fixed pool of Max Real + Max Virtual + Steal Headroom AudioSources (100 by default), built at start
```

### 9.3 CPU Optimization

#### Update Intervals

**Voice Management:**
```csharp
voiceUpdateInterval = 0.1f; // 10 times per second

// What it does:
// - Check if voices finished
// - Update virtualization
// - Clean up inactive voices
```

**Tuning:**
- Faster (0.05s): More responsive, higher CPU
- Slower (0.2s): Lower CPU, less responsive
- Recommended: 0.1s for most games

**Occlusion:**
```csharp
occlusionUpdateInterval = 0.2f; // 5 times per second

// What it does:
// - Raycast from listener to each voice
// - Update occlusion gain
// - Update low-pass filter
```

**Tuning:**
- Faster (0.1s): Smooth occlusion, high CPU
- Slower (0.3-0.5s): Lower CPU, slight lag
- Recommended: 0.2s for most games, 0.3-0.5s for mobile

#### Occlusion Optimization

**Layer Mask:**
```csharp
// Include only large geometry
occlusionMask = LayerMask.GetMask("Environment", "Buildings");

// Exclude:
// - Small props
// - Moving objects
// - Player
// - Enemies
```

**Per-Voice Occlusion:**
```
Only enable for important 3D sounds
Disable for:
  - 2D sounds (UI, music)
  - Distant ambience
  - Non-critical sounds
```

#### Distance and Virtualization

There are no fixed distance tiers. The `lodDistances` field on the AudioManager is not used in this version and is hidden in the inspector. Distance matters only through a voice's importance score: for a 3D sound it falls from 1 at the listener to 0 at the sound's own Max Distance (with an Attenuation asset, its curve's level there; with Spatial Mode = Pepper, the level it is heard at; 2D sounds don't lose importance with distance). When more than `maxRealVoices` are live, the lowest scores are virtualized first, so distant sounds give way before nearby ones. While you are under the limit, every sound plays regardless of distance.

To make a sound more or less likely to be virtualized, change its event's Priority or its container's Max Distance.

#### Listening Points

Everything in Pepper that depends on where the player is listening (voice importance, occlusion rays, the Furthest steal, which multi-position emitter is nearest, and with Spatial Mode = Pepper each 3D sound's level and pan) reads the **listening points**.

**Register one** (recommended). Tell Pepper where you listen from, usually the camera, and it never searches the scene:

```csharp
// Follow a transform: the point reads its pose every frame.
AudioListeningPoint point = AudioManager.Instance.AddListeningPoint(cameraTransform);

// Or move it yourself, in Update or LateUpdate:
AudioListeningPoint point = AudioManager.Instance.AddListeningPoint();
point.SetPose(rigPosition, rigRotation);

// When that camera goes away:
AudioManager.Instance.RemoveListeningPoint(point);
```

- Pepper's per-frame step runs after every LateUpdate, so a camera rig that moves in LateUpdate (Cinemachine) is already in place.
- The point's **velocity** (for Approach Speed and Doppler) is measured from how it moves each frame, unless you give it with `SetVelocity`. `ClearVelocity()` goes back to measuring, starting again from where the point is: call it on a camera cut too, so the cut isn't read as speed. Pointing `Follow` at another camera does that by itself.
- **If the transform a point follows is destroyed,** the point is removed (`IsRegistered` turns false), with a warning once a session. Remove your points when their camera goes; the warning says you didn't. (It used to stay where it last saw the camera, still in use.)
- **Unity's AudioListener** still does Unity's own 3D panning. If it isn't on the transform the point follows, `AudioManager.Instance.DriveUnityListener(listener)` moves it to the primary point every frame, so both hear from the same place.

**The primary point.** With several points, one is primary: the one `DriveUnityListener` keeps Unity's AudioListener on, the one the ambient system (§13) and SingleEmitter posts listen from, and with Spatial Mode = Unity the only one Pepper listens from. It is the first registered until you pick one:

```csharp
AudioManager.Instance.SetPrimaryListeningPoint(carViewPoint);   // menu camera → car view
bool isIt = carViewPoint.IsPrimary;
AudioManager.Instance.SetPrimaryListeningPoint(null);           // back to the first registered
```

Changing it doesn't make sounds jump: what Pepper measures from a point (Distance, Approach Speed and Angle, so Doppler and every curve on them, and attenuation filters) glides to the new one over about 100 ms. With Spatial Mode = Unity, Unity's own levels and pans still jump when its AudioListener moves.

**Several points, weighted: Spatial Mode = Pepper.** One AudioListener can't hear two places, so for split screen Pepper pans and attenuates 3D sounds itself. Set the Audio Manager's **Spatial Mode** to **Pepper** (in the inspector, or `AudioManager.Instance.SpatialMode = AudioSpatialMode.Pepper;` before the sounds start: a change applies to sounds started after it). Then every 3D sound plays at Spatial Blend 0 and, each frame, Pepper sets its level and pan from every point:

- **Level:** for each point, the sound's attenuation there (its Attenuation asset's volume curve, else Unity's own rolloff for its Min and Max Distance) times the point's **Weight** (0–1). The loudest wins. So a sound is as loud as from the point that hears it best.
- **Pan:** where it is, left to right, from each point, blended by how loud each point hears it, and narrowed by each point's **Pan Width** (0 = mono, centred; 1 = full stereo). It eases over about 50 ms.
- **At one point of weight 1 and width 1 it sounds exactly as Unity's 3D does** (the same rolloffs, the same constant-power pan, Spread the same way; measured on Unity 6000.0 and 6000.3). So single player can run Pepper mode too, and hear the code split screen runs.
- **Which point a sound is measured from** (for Distance, Approach Speed, Angle, Doppler, attenuation filters, occlusion rays and the Furthest steal): the one that hears it loudest, changing only when another hears it 1 dB louder, so a car halfway between two players doesn't flip. When it changes, those values glide over about 100 ms.
- **Max Distance:** a sound goes virtual only when it is past its Attenuation asset's Max Distance from every point.
- **Importance** (§3.2) is how loud it is heard, so a car near either player counts as near.
- **Doppler** is always Pepper's (§4.1).
- **After the points change** (one added or removed, the primary, a Follow, Weight or Pan Width), levels move to the new ones over about 100 ms instead of jumping.

```csharp
// Local split: both players' cameras, full weight, mono (top/bottom halves have no left and right).
var p1 = AudioManager.Instance.AddListeningPoint(player1Camera);
var p2 = AudioManager.Instance.AddListeningPoint(player2Camera);
p1.PanWidth = p2.PanWidth = 0f;

// Remote split: your camera in stereo, the second view's faintly (about −9 dB) and mono.
var mine = AudioManager.Instance.AddListeningPoint(myCamera);
var second = AudioManager.Instance.AddListeningPoint(secondViewCamera);
second.Weight = 0.35f;
second.PanWidth = 0f;
```

Pepper mode's limits: no spatializer plugins (HRTF); the project's Doppler Factor isn't read; a stereo clip keeps its two channels, balanced by the pan, where Unity's 3D folds it to mono, so give 3D sounds mono clips; up and down count only by shortening the sideways part. AudioSources that aren't Pepper's (the ambient system's) are still Unity's, heard from the AudioListener: keep it on the primary point with `DriveUnityListener`. The Live View (§10.6) shows each voice's point, level and pan.

**With no point registered,** Pepper searches the scene for an AudioListener, as before, and logs a warning once: "No listening point is registered". A listener it found is kept until it is destroyed. While there is none, it searches at most once a frame (it used to search on every call).

**`ListenerUtil.Set` still works:** it registers a point that follows the transform you give it. A point you add with `AddListeningPoint` takes priority over it. `ListenerUtil.Invalidate()` removes it and makes the next lookup search again. If its transform is destroyed, the search takes over, as before.

```csharp
ListenerUtil.Set(newCamera.transform);   // older code: still fine
Vector3 where = ListenerUtil.GetPosition();
```

`ListenerUtil.Get()` returns the primary point's transform. A point moved with `SetPose` has none, so use `ListenerUtil.GetPosition()` for the position.

In Play mode, the Audio Manager's inspector lists the points (weight, pan width, which is primary), or warns when there are none.

### 9.4 Mobile Optimization

**Recommended Settings:**
```csharp
maxRealVoices = 16;               // Lower limit
maxVirtualVoices = 32;            // Lower limit
voiceUpdateInterval = 0.15f;      // Slower updates
occlusionUpdateInterval = 0.4f;   // Much slower
```

**Clip Settings:**
```
All clips: Compressed In Memory or Streaming
Compression: Vorbis
Quality: 60-70% (lower for mobile)
```

**3D Audio:**
```
Use sparingly
Prefer 2D when possible
Limit max distance to reduce spatialization cost
```

**Best Practices:**
```
✓ Use instance limiting aggressively
✓ Lower voice counts
✓ Increase update intervals
✓ Disable occlusion or use very slow interval
✓ Profile on target device
```

### 9.5 Profiling

#### Unity Profiler

**Audio Module:**
```
Shows:
- Active AudioSource count
- AudioClip memory usage
- DSP buffer usage
- Audio thread time
```

**What to Look For:**
```
High voice count → Increase instance limits
High audio memory → Check clip import settings
Audio thread spikes → Reduce update frequencies
```

#### Custom Debug Tools

**Voice Count Display:**
```csharp
public class AudioDebugUI : MonoBehaviour
{
    void OnGUI()
    {
        var stats = AudioManager.Instance.GetStatistics();
        int y = 10;

        GUI.Label(new Rect(10, y, 400, 20),
            $"Real Voices: {stats.activeVoices}/{stats.totalVoices}");
        y += 20;

        GUI.Label(new Rect(10, y, 400, 20),
            $"Free Voices: {stats.availableVoices}");
    }
}
```

**Event Logging:**
```csharp
AudioHandle handle = myEvent.Post();
handle.OnStarted += () => Debug.Log($"Started: {handle.EventName}");
handle.OnFinished += () => Debug.Log($"Finished: {handle.EventName}");
```

## Advanced Features

Source: https://peppersfx.com/docs/manual/advanced-features/

### 10.1 Occlusion System

**How It Works:**
1. Raycast from AudioListener to each voice
2. If blocked, reduce volume + apply low-pass filter
3. Smooth transitions via lerp

**Implementation:**
```csharp
private IEnumerator OcclusionUpdate()
{
    while (true)
    {
        if (Time.unscaledTime - lastOcclusionUpdate > occlusionUpdateInterval)
        {
            lastOcclusionUpdate = Time.unscaledTime;
            // The listening point (§9.3), or the scene's AudioListener when none is registered
            if (!ListenerUtil.TryGetPosition(out Vector3 listenerPosition)) { yield return null; continue; }

            foreach (var voice in realVoices)
            {
                if (voice?.source == null) continue;

                Vector3 a = listenerPosition;
                Vector3 b = voice.source.transform.position;
                bool occluded = Physics.Linecast(a, b, occlusionMask);

                float targetGain = occluded ? 0.3f : 1f;
                float lerpSpeed = Mathf.Clamp01(occlusionUpdateInterval * 5f);
                voice.GainStack.OcclusionGain = Mathf.Lerp(
                    voice.GainStack.OcclusionGain,
                    targetGain,
                    lerpSpeed);

                voice.UpdateFinalVolume();

                // Low-pass cutoff is now written through the voice's OcclusionSlot mixer
                // group (see the Occlusion Mixer Slot Pool chapter), not via a per-voice
                // AudioLowPassFilter component.
            }
        }
        yield return null;
    }
}
```

**Performance Cost:**
```
Cost per frame = (realVoiceCount / updateInterval) raycasts

Example:
20 real voices, 0.2s interval = 100 raycasts/second = ~2 raycasts/frame @ 60fps
```

**Optimization:**
```
✓ Use coarse occlusionMask (only large geometry)
✓ Increase update interval on mobile
✓ Disable for non-critical sounds
✓ Disable entirely for 2D games
```

### 10.2 Ducking

**Automatic Volume Reduction:**

**Setup on Trigger Bus (e.g., Dialogue):**
```csharp
enableDucking = true;
duckingTargets = [
    { targetBus: Music_Bus, duckAmount: -10.5f },  // dB: about 30% of the level
    { targetBus: SFX_Bus, duckAmount: -6f }        // dB: about 50%
];
duckingAttack = 0.05f;   // Quick duck
duckingRelease = 0.8f;   // Slow return
```

**Behavior:**
```
Duck triggered (TriggerDucking action, hold = its Fade Duration) → Music/SFX duck over 0.05s
Hold elapses → Music/SFX return over 0.8s
```
Ducking is triggered, not detected from the bus's output; see §6.4.

**Common Patterns:**
```
Dialogue ducks Music: 70-80%
Dialogue ducks SFX: 40-60%
Important SFX ducks Music: 30-50%
UI sounds duck nothing: 0%
```

### 10.3 Crossfading

**Types:**

For both types, the outgoing sound fades along the incoming sound's curve run backwards in time.

**Linear:**
```csharp
float fadeIn  = x;        // Straight line
float fadeOut = 1f - x;
// Results in slight volume dip in middle
```

**Equal-Power (Recommended):**
```csharp
float fadeIn  = Mathf.Sin(x * Mathf.PI * 0.5f);
float fadeOut = Mathf.Cos(x * Mathf.PI * 0.5f);   // fadeIn² + fadeOut² = 1
// Maintains perceived loudness throughout
```

**Usage:**
```csharp
AudioManager.Instance.CrossFade(
    from: oldMusicContainer,
    to: newMusicContainer,
    duration: 2f,
    type: AudioEvent.CrossfadeType.EqualPower
);
```

**Event-Based:**
```
Event: "TransitionMusic"
Action:
  - Type: CrossFade
  - From Container: Music_Combat
  - To Container: Music_Calm
  - Target Bus: Music_Bus
  - Duration: 3.0s
  - Type: EqualPower
```

Set the action's **Target Bus** to route the incoming music through a bus, the same as a Play action, so it follows that bus's volume, mute and ducking. That includes the clips an auto-advancing Sequence starts later. With no Target Bus (and always when you call `AudioManager.CrossFade` directly), the incoming voices play unbussed, through the container's own Mixer Group. A 3D container plays at the position, or on the GameObject, you pass to `Post`. The incoming voices are not attached to the CrossFade event's handle: that handle finishes straight away. Stop the new music with `container.Stop()`, `StopAllSounds()`, or another CrossFade.

A container crossfade fades the voices of the "from" container that are playing at that moment. It doesn't cancel anything the outgoing sound was still going to start: a delayed Play action (the loop in the intro + loop recipe) or a Sequence's next clip will still come in, at full volume. When you hold the outgoing sound's handle, use a handle crossfade instead.

Changing your mind mid-crossfade is smooth: crossfading back while a sound is still fading in fades it out from the level it had reached. Note that the target always starts again from the top; a crossfade never resumes a sound that is fading out.

**Handle crossfade (recommended for music started by an event):**
```csharp
AudioHandle music = startMainTheme.Post();           // intro now, loop after a delay

// Later — fade the whole main theme out, including the loop it hasn't started yet,
// and fade the combat event in:
music = AudioManager.Instance.CrossFade(music, combatMusicEvent, 2f);
```

`CrossFade(AudioHandle from, AudioEvent to, float duration, CrossfadeType type = EqualPower, GameObject source = null, Vector3 position = default)` fades out every voice of `from` and cancels what it was still going to start (delayed Play actions, a Sequence's next clip). It then posts `to` normally, so its bus, priority, cooldown and Max Instances apply, and fades in the voices that post started. It returns the new handle. The old handle's `OnFinished` fires when its fade-out ends. `OnStopping` doesn't fire, as for every crossfade. Either side may be null. Voices `to` starts later (its own delayed Plays, a Sequence's next clip) come in at their normal level. If `to` is the same event as `from` and its Max Instances is reached, the instance limit ends the old play at once instead of fading it.

**Crossfades and the time scale.** A crossfade runs on its event's **Time** (§5.4): the CrossFade action's own event, or for a handle crossfade `to`'s event (else `from`'s). Scaled, the default, is game time, so a crossfade started while the game is paused (time scale 0) waits for the game to resume. Set the pause menu's music event to Unscaled and its crossfade completes during the pause. A container crossfade called from code has no event and runs on game time.

---

### 10.4 Beat-Scheduled SFX (BeatScheduler)

**Purpose:** Fire an AudioEvent on a tempo grid (BPM) whose rate can be changed at runtime *without* affecting pitch.

Unity's `AudioSource.pitch` scales both speed and pitch together — doubling it lifts the clip an octave. For rhythmic SFX (heartbeats, metronomes, ticking clocks, pulsing UI, sonar pings) you usually want the opposite: faster cadence, same timbre. `BeatScheduler` solves this by **retriggering a one-shot event** on an interval of `60 / BPM` seconds instead of time-stretching a continuous clip. Pitch never changes because the clip itself never changes — only how often it is re-posted.

**Class:** `AudioSystem.BeatScheduler` (MonoBehaviour, `RunTime/Utilities/BeatScheduler.cs`).

#### When to use it

| Use case | Fit |
|---|---|
| Heartbeat whose BPM rises with stress | ✅ ideal |
| Metronome / rhythm game tick | ✅ ideal |
| Clock "tick-tock" | ✅ ideal |
| Pulse ambience (reactor hum, sonar) | ✅ good |
| Musical content that must stay on-grid | ⚠️ works for single-hit beats; for layered music use a dedicated music system |
| Continuous loop that should play slower without pitch drop | ❌ use a mixer Pitch Shifter effect with `source.pitch` inverse instead |

#### Timing model

Beats are scheduled against `AudioSettings.dspTime`, not `Time.time`. Each `Update()` checks whether the DSP clock has reached the next grid time; if so, it posts the AudioEvent with that grid time as the scheduled DSP start (`AudioEvent.Post(scheduledDspTime)` → `AudioSource.PlayScheduled`), so each beat's audible onset is grid-anchored rather than firing-frame-anchored. Spacing between beats is exactly `BeatInterval` regardless of frame-rate jitter.

**Hitch policy.** If `Update()` runs while one or more grid times are already overdue (frame stall, very high BPM, scene-load slowness), the scheduler fires audio **at most once per Update** — anchored to the most-recent overdue grid time — and drops earlier missed beats. This prevents voice-stacking on recovery, which used to surface as a +6 to +12 dB thump when multiple overdue voices landed on the same DSP buffer boundary. The `OnBeat` callback still fires once per missed beat up to `maxCatchUpBeatsPerFrame`, so beat-counting game logic (e.g. "every 4th beat") stays synchronized with the grid even across hitches. The grid phase is preserved across stalls: post-recovery, beats land at the original `T₀ + N × BeatInterval` rather than at `dspTime + interval`.

Changing `Bpm` at runtime (inspector field, property setter, or keystroke into the BPM number field) re-anchors the next beat to `dspTime + new BeatInterval` so the new tempo is audible within one beat. Earlier authoring did not handle intermediate keystroke values (typing "120" passed through `bpm=1` which would make the scheduler appear silent until a 60-second stale tick elapsed); this is now handled automatically.

#### Inspector fields

| Field | Purpose |
|---|---|
| `Audio Event` | The AudioEvent asset posted on every beat (drag it in; there's no name lookup). From code: the `Event` property. |
| `Emitter` | Optional GameObject used as the sound source and spatial position. Defaults to the BeatScheduler's GameObject. |
| `Bpm` | Beats per minute. Also writable at runtime via the `Bpm` property. |
| `Max Catch-Up Beats Per Frame` | Cap on `OnBeat` callbacks per Update if the scheduler falls behind. Audio always fires at most ONCE per Update regardless — only `OnBeat` consumers (beat-counters driving game logic) see catch-up, keeping their count synced to the grid. Grid phase is preserved across stalls. |
| `Play On Enable` | Start scheduling when the component is enabled. |
| `Fire Immediately On Start` | If true, the first beat fires on the next frame. If false, it waits one full interval. |

#### Public API

```csharp
public float Bpm { get; set; }          // Clamp-guarded, min 1
public bool IsRunning { get; }          // True while scheduling
public double BeatInterval { get; }     // Seconds per beat, 60 / Bpm

public void StartScheduling();
public void StopScheduling();
public void ResyncPhase();              // Reset: next beat = now + BeatInterval

public event System.Action OnBeat;      // Main-thread callback per beat
```

#### Minimal example — stress-driven heartbeat

```csharp
using UnityEngine;
using AudioSystem;

public class StressHeartbeat : MonoBehaviour
{
    [SerializeField] private BeatScheduler heartbeat;
    [SerializeField] private float calmBpm = 60f;
    [SerializeField] private float panicBpm = 160f;

    [Range(0f, 1f)] public float stress;

    private void Update()
    {
        heartbeat.Bpm = Mathf.Lerp(calmBpm, panicBpm, stress);
    }
}
```

Drag the `Heartbeat_Thump` event asset into the BeatScheduler's `Audio Event` (a normal AudioEvent with a `RandomContainer` of 2–3 thump variations). No other plumbing required.

#### Common patterns

**Quantize gameplay to beats.** Subscribe to `OnBeat` to drive visual pulses, damage ticks, flashlight flicker, etc. The event fires on the main thread so Unity API calls are safe.

**Pause on gameplay pause.** Toggle the component's `enabled` or call `StopScheduling()` / `StartScheduling()`. The phase resets on restart unless you snapshot `BeatInterval` yourself.

**Multiple tempos simultaneously.** Add multiple `BeatScheduler` components to a GameObject, each pointing at a different event. They run independently and don't share a phase.

#### Limitations

- **Sample-accurate spacing, frame-bounded latency.** Each beat is scheduled to its grid DSP time via `PlayScheduled`, so spacing between consecutive beats is exactly `BeatInterval` regardless of frame-rate jitter. The audible onset of each beat can lag its grid time by up to one DSP buffer (Unity rounds past-time `PlayScheduled` to the next buffer boundary), but that lag is approximately constant across beats and doesn't affect perceived tempo. Suitable for rhythmic gameplay SFX and single-track musical-grid scheduling; for sample-aligned multi-track musical content, schedule `PlayScheduled` directly with explicit DSP times.
- **No musical phase alignment across schedulers.** Two schedulers at the same BPM are not guaranteed to fire on the same DSP frame.
- **Does not track segment/bar/measure structure.** It emits an unbroken stream of beats. For song-form authoring (intro / loop / outro), use an interactive-music layer above the SFX system.

### 10.5 Audition (outside Play mode)

**Window > Audio System > Audition** plays a container tree, or an event, while you edit it, so an engine can be tuned by ear without driving the car.

1. Select a container or an event in the Project window (with **Follow Selection** on, the window picks it up), or drag one into **Sound**. Press **Play**.
2. Move the sliders: one for every parameter the tree reads (Blends, pitch follow, Parameter Curves on containers and layers, Switch Group drivers), and for each one's **Bypass Slew While** parameter (an engine cut), in each parameter's range and unit. Values go through each parameter's Smoothing, as in the game; a "heard" line shows where the smoothing has got to. A slider shows the value written: where a sweep or a replay has it, and where a sweep ended.
3. Pick switch values from the dropdowns. A Switch set to Next Play Only plays again to pick up the new value; one set to Crossfade or Restart changes as it would in the game.
4. **Sweeps:** press **Add Sweep** for each parameter to move, and set its range, its seconds and how it carries on: **Once** (stops at the end), **Repeat** (starts again from the start) or **Back And Forth**. Any number run at once, one per parameter (RPM 900 → 7000 over 4 s while load goes 0 → 1 over 3 s). Moving a slider stops only that parameter's sweep.
5. Watch **Layers**: each sound playing, its level (dB), pitch (semitones), low-pass, whether it is real or virtual (silent, keeping its place), and for an event the bus it plays through. Keep the Inspector open beside the window: edits to curves, regions and root values are heard at once, and a curve or parameter added there gets its slider without selecting the sound again.

- **An event** plays its Play actions as a post would: each through its Target Bus (the bus's volume and mute), with the event's priority and Persistent flag, after its Delay. Its Set RTPC and Set Switch actions set the audition's values. Its other actions (Stop, Pause, Resume, states, ducking, crossfades) aren't auditioned; the window says how many it skipped. Max Instances and cooldowns don't apply, and the event itself is never changed.
- **Replay a Recording** (§10.6): pick a recording and press **Replay**. Every recorded value moves at once, as the game wrote it, through each parameter's Smoothing, so a smoothing change is heard on the replay; the recorded switch values are set as the game set them. **Loop** goes round (all of it, or the range you set) and **Time** scrubs: the values where you drag to are heard at once. Moving a recorded parameter's slider takes that one parameter off the recording; **Replay** again puts it back.
- **Distance** and **Angle** place the sound around the listener: they drive Distance, Approach Speed and Angle parameters and an Attenuation asset's filters.
- **Heard 2D.** Outside Play mode there may be no listener for Unity to pan and fade from, so a 3D sound is heard straight, at full level; check the distance fade and panning in Play mode.
- **Outside Play mode** a Sequence plays only its first clip, and Stop is immediate (both run on Unity coroutines, which don't advance there).
- **Generated engines** (Granular and Additive Engines, Unity 6.3 and later, §4.7) play here too: their Rpm and Load get sliders.
- The audition runs on its own hidden Audio Manager. It stops when you enter Play mode, when scripts reload and when the window closes, and it adds nothing to your scene.
- From code (editor tools): `AudioAudition.Begin(out whyNot)`, then `Play(container)` or `Play(audioEvent)`, `SetParameter`, `Sweep(parameter, from, to, seconds, SweepMode)`, `SetSwitch`, `Replay(recording)`, `Tick(dt)` every editor update, `GetLayers`, and `Dispose()`.

### 10.6 Live View and recording a drive (Play mode)

**Window > Audio System > Live View** shows, while the game runs, what each Audio Emitter (each car) is doing:

- **Its values:** every parameter set on the emitter, as written and as heard after smoothing, with "moving" while it is still on its way; and its switch values.
- **Its sounds:** each play posted on it, with its event and container, bus, whether it is Persistent, and whether it is real or virtual; the play's own values (set on its handle, such as each axle's slide speed); and a row per voice: its level (dB), pitch (semitones), its **region** for a layer of a Regions Blend ("1780–2510 RPM at 2300: in", "fading" or "out"), and, when virtual, **why**: over the cap, silent layer, past Max Distance, held by code (`MakeVirtual`), bus paused, emitter paused, or stopping (", fading" while it fades down).
- **No emitter** lists the sounds posted without one.

The Voice Pool Debug window's "Why virtual" column gives the same reasons.

**Recording.** Choose an emitter and press **Record**; drive; press **Stop and Save** and pick where the recording goes. It keeps what the game wrote to that emitter, every value (Bypass While ones included) and its switch values, from each frame, and only when they change. Replay it in the Audition window (§10.5) to tune a mix on a loop of a real lap. It doesn't keep values set on one sound's handle (a tyre's per-axle values) or global values. A recording still running when Play mode ends is offered for saving; one whose emitter is destroyed (a car reset or removed) stops there, and the Live View offers it for **Save** or **Discard**.

The **Gain dB** column (here and in the Audition window) is Pepper's gain to the AudioSource: volume, curves, bus, offsets, ducking and, in Pepper spatial mode, distance. Unity's own 3D distance fade (Spatial Mode Unity) and the mixer come after it, so it isn't what you hear; it reads -inf while a voice is parked virtual.

From code: `AudioEmitterRecorder.Begin(emitter, out whyNot)` and `End()` give an `AudioParameterRecording`; `AudioManager.GetPlaysDebug(list)` and `AudioEmitter.AllEnabled` are what the Live View reads, for a game's own debug overlay.

### 10.7 Loop Analysis

**Window > Audio System > Loop Analysis** measures engine loops (any loop, really). Select clips, or containers or a Blend playing them, press **Use Selection**, then **Analyse**:

- **Root:** the loop's fundamental, and the RPM it means for the **Cylinders** you set: a four-stroke engine fires each cylinder once every two turns, so RPM = fundamental × 120 ÷ cylinders (an inline-4 idling at 900 RPM sounds at 30 Hz, a V8 at 60 Hz). If a recording fools it by an octave, **÷2** and **×2** fix the reading. When the clip's name holds an RPM (the last number between 300 and 20000, as the Engine Builder reads it), a reading more than half an octave from it is flagged under the row: the pitch read an octave off, or a name that isn't the loop's RPM.
- **Cylinders is a scale.** Start from the engine's count, but go by the loops: their strongest pitch isn't always the firing rate, and a library tuned to notes has a scale of its own (one tuned to notes at RPM ÷ 20 Hz reads on 6, whatever the engine). When most readings sit 2 semitones or more from the RPMs in their names, the window names the count that fits, with a **Use N** button: a V8 library read at 6 is 5 semitones high, and gets 8. Cylinders is one setting for every engine, so set it again for each library: libraries of different engines, or tuned differently, read on different counts.
- **Loop Point:** whether the loop clicks where it goes round: the first sample against where the end was heading, compared with how much the sound moves sample to sample. "Clean", or "clicks".
- **Level Across It:** the first 50 ms against the last 50 ms; more than 3 dB is a jump to re-cut or crossfade.
- **Level:** RMS and peak in dBFS, and integrated loudness in LUFS (ITU-R BS.1770; a mono clip counts as one channel).
- **Seam ▶** plays the end and the start of the loop round and round, so you hear only the seam.

Clips must be **Decompress On Load** to be read (the right setting for loop layers anyway).

On a Regions Blend's Inspector, **Detect Root Values** measures each layer's clip and sets its Root Value (with Undo), then logs what it found; set **Cylinders** beside it. It writes the raw reading: the **÷2** and **×2** buttons here only change what this window shows, so if a loop reads an octave off, correct its Root Value by hand (halve or double it). The log is a warning when a reading is far from its clip's name, or when most are (it then names the cylinder count that fits).

> **Loops tuned to notes?** If each loop is pitch-corrected to one note, the most exact roots come from the notes, not from a measurement: Root = the note's frequency × 120 ÷ Cylinders (× 20 at 6). A loop named 2500 tuned to B2 (123.47 Hz) has its root at 2469.4, not 2500; neighbours rooted by their names can sit tens of cents apart in a crossfade and beat.

**Auto Layout** puts the layers in Root Value order. Sounds already playing keep the order they started with, so while a sound plays (in Play mode, or in the Audition window) it asks before re-ordering: until they are posted again, layers would play with each other's regions and pitch. Laying out regions without a new order is heard at once.

### 10.8 Engine Builder

> **Full version only.** In the free version, build the same tree by hand as the Vehicle Engine RPM recipe describes
> (§3); Loop Analysis (§10.7) and the Blend inspector's **Detect Root Values** are in both.

**Window > Audio System > Engine Builder** turns a car's engine loops into the whole tree the engine recipe describes (§3, Vehicle Engine RPM):

1. Select the loops and press **Use Selection**. Each row guesses its set (**OffLoad** when its name says off, decel, coast or overrun; else **OnLoad**) and its RPM (the last number between 300 and 20000 in its name: `Eng_OffLoad_2510`, `v8_on_4960rpm`). Correct them, or press **Detect** (§10.7), which uses the **Cylinders** above the rows (the same setting as Loop Analysis's: a scale, see §10.7). Changing Cylinders re-scales the rows Detect measured and keeps the ones you typed. A row more than half an octave from the RPM in its name is flagged under it; when most rows sit 2 semitones or more from their names, the window names the cylinder count that fits instead, with a **Use N** button.
2. Pick the **RPM** and **Load** parameters, or leave them empty to have EngineRpm (0–9000 RPM, about 15 ms of smoothing) and EngineLoad01 (0–1, up 50 ms, down 150 ms) made. Pick the **Target Bus** and, if you like, an **Attenuation**.
3. Press **Build**. It lists the clips whose import settings it changes, then makes, in the folder you chose:
   - one looping container per loop, with **Uses Parent Positioning** and **Uses Parent Output** (and Avoid Repeat Last 0: one clip has nothing to avoid);
   - an **OnLoad** and an **OffLoad** Blend on RPM: Regions layout, Root Values, Auto Layout, Equal Power, Pitch Follow, Silent Layers Virtualize, Force Loop;
   - the engine Blend on load over the two, crossfading at constant power from 0.3 to 0.7 load, 3D, Doppler Level 0;
   - one **Persistent** event at Priority High playing it on the Target Bus;
   - the clips set to mono and Decompress On Load (their compression is kept). A clip it folds to mono gets Unity's **Normalize** turned off, so the bands keep the levels they were recorded at; its dialog lists every change first.

With loops of one set only, the RPM Blend is the engine and there is no load Blend, so it sounds the same on and off the throttle; the window and its dialog say so. That suits a thin set for other cars; a player's car wants both sets. It never overwrites an asset. The two sets' crossfades fall at the same RPMs when their roots match; move one set's regions by hand to stagger them. Audition the event in §10.5.

### 10.9 The Container Validator and the other windows

**Window > Audio System > Container Validator** checks every container and event in the project:

- empty entries, null entries, zero weights; a Routing container with no clip;
- a Regions Blend where nothing plays, or the layers dip below -20 dB, somewhere in its parameter's range, and layers with no region (0–0). Silence from the bottom of the range (a skid at rest, wind at low speed) is a note, not a warning;
- a layer that follows pitch with no Root Value; a layer pitched past the Blend's **Tuning Warning** while it is heard (Pitch Follow over the follow parameter's own range, plus pitch curves on the Blend, the layer and its container);
- a 3D loop with Doppler Level above 0 in a Blend set to Virtualize; a stereo clip on a 3D layer; a streamed clip on a layer that goes virtual. Inside a nested Blend, a clip is judged by what it plays with (the outer Blend's 3D through Uses Parent Positioning, its Virtualize), and reported once;
- 3D distances, or with an Attenuation asset its curve still loud at its Max Distance (the sound goes virtual there);
- a Play action with no Target Bus (a warning when its container has no Mixer Group either: it plays straight to Unity's output); a looping event that isn't Persistent (a hint).

**Fix** and **Auto-Fix All** are undoable. The Blend Inspector shows the same Regions and tuning findings.

- **Audio Profiler:** Voice Usage is real voices against Max Real Voices (100% at the cap).
- **Voice Pool Debug:** Pool Objects against the pool's size (Max Real + Max Virtual + Steal Headroom), which should never change during a session; the real and virtual tables scroll separately.
- **Mixer and Profiler faders, mute and solo** are undoable and saved with the project, in Play mode too: a mix set while the game runs stays.

### 10.10 Engine Grains (Unity 6.3 and later)

**Window > Audio System > Engine Grains** cuts an engine sweep into a **Grain Table** for a Granular Engine (§4.7).

1. Drag the sweep into **Sweep**. It must be **Decompress On Load**; if it isn't, the window offers to set it (its
   compression is kept).
2. Say where its RPM comes from:
   - **Known:** type the RPM at the clip's first sample and at its last (**From → To**), and how it moves between them
     (**Curve**): **Straight Line**, the same RPM every second, or **Even Pitch**, the same number of semitones every
     second (the RPM multiplies by the same factor), as most synthesisers sweep. The number of periods of its pitch in
     one engine cycle is measured against them (6 for a sweep tuned to notes at RPM ÷ 20 Hz).
   - **From Pitch:** the RPM is measured from the sweep's pitch, RPM = pitch × 120 ÷ **Cylinders** (a scale shared with
     Loop Analysis, §10.7), looked for between the two RPMs typed. Use it for a recording, or a sweep that follows
     neither curve.
3. Press **Analyse**. Each grain is one engine cycle (two turns: 120 ÷ RPM seconds); every cut is moved, by less than
   half a period and at most 6% of a cycle, to where the waveform matches the start of the grain before it, so the
   grains join in phase. Each is tagged with the RPM its own length means.

   **The curve typed is checked against the sweep's own,** measured from a strong harmonic followed through it. A curve
   that doesn't fit puts every cut where no cycle ends, so when they disagree (the other curve, or the RPM changing more
   or less over the clip than typed) the window says so and offers buttons: the curve that fits, with the two ranges
   that keep one end you typed (it can't know which end is wrong). Each is cut on trial, and the one whose cuts match
   better comes first, marked **fits better**. Press it, or the other if you know that end is right; it analyses again.
4. Read the **report**: the grains and the RPM range they cover, and:
   - **No grain between A and B RPM:** the sweep jumps there; the player stretches the nearest grain across the gap.
   - **Only N grains per 1000 RPM:** a fast sweep; a slower one gives the player more to choose from.
   - **Holds about X RPM:** the RPM barely moves for a while (a note, not a problem): these grains are what the player
     varies a held RPM with.
   - **The grains are N% off the typed RPMs:** the sweep doesn't follow the curve typed. Check From, To and Curve, or
     try From Pitch.
   - **N% of the cuts found nothing like the cycle before within reach:** the same, seen from the cuts: the grains
     aren't whole engine cycles, and the engine would sound rough.
5. **One Grain At** loops the grain nearest an RPM, unchanged and with no crossfade: a click at its seam is a cut in the
   wrong place.
6. Press **Save**. The table is made beside the sweep as `<sweep>_Grains.asset`, or, when **Grain Table** names one
   (it fills the window with that table's settings), that table is updated, with Undo. Re-analyse whenever the sweep
   changes.

## Best Practices

Source: https://peppersfx.com/docs/manual/best-practices/

### 11.1 Project Organization

**Recommended Folder Structure:**
```
Assets/Audio/
├── Resources/Audio/
│   ├── Events/
│   │   ├── UI/
│   │   ├── Player/
│   │   ├── Enemies/
│   │   ├── Ambience/
│   │   └── Music/
│   └── States/
│       ├── Gameplay/
│       └── Location/
├── Containers/
│   ├── UI/
│   ├── Footsteps/
│   ├── Weapons/
│   ├── Impacts/
│   ├── Ambience/
│   └── Music/
├── Buses/
└── AudioClips/
    ├── SFX/
    │   ├── UI/
    │   ├── Footsteps/
    │   └── Weapons/
    ├── Music/
    └── VO/
```

### 11.2 Naming Conventions

**Containers:**
```
Format: Category_Description_Type

Examples:
Weapon_RifleShot_RnC       (Random Container)
UI_ButtonClick_RC          (Routing Container)
Music_MainTheme_BC         (Blend Container)
Footsteps_Switch_SwC       (Switch Container)
Alarm_Sequence_SeqC        (Sequence Container)
```

**Events:**
```
Format: Action_Description

Examples:
Play_WeaponRifleShot
Play_UIButtonClick
Start_MusicMainTheme
Trigger_DuckForDialogue
Set_StateUnderwater
```

**Buses:**
```
Format: Category_Bus or Category_Subcategory_Bus

Examples:
Master_Bus
SFX_Bus
SFX_Weapons_Bus
Music_Bus
Dialogue_Bus
```

### 11.3 Bus Hierarchy Design

**Typical Structure:**
```
Master (-3 dB)
├── SFX (0 dB)
│   ├── Player (0 dB)
│   │   ├── Footsteps (-6 dB)
│   │   └── Weapons (0 dB)
│   ├── Enemies (-3 dB)
│   ├── UI (0 dB)
│   └── Ambience (-6 dB)
├── Music (-6 dB)
│   ├── Gameplay (0 dB)
│   └── Menu (-3 dB)
├── Dialogue (0 dB)
└── VO (-3 dB)
```

**Guidelines:**
- **3-4 levels max** - Don't over-complicate
- **Leave headroom** - Master at -3 to -6 dB
- **Group by function** - Not by asset type
- **Plan for ducking** - Dialogue should duck Music/SFX

### 11.4 Container Design

**Variation Counts:**
```
Footsteps: 6-8 variations minimum
Weapon fire: 3-5 variations
Impacts: 4-6 per material
Voice lines: 10+ (more is better)
UI clicks: 2-3 variations
```

**Randomization Guidelines:**
```
Subtle:
  Volume: ±1-2 dB
  Pitch: ±50-100 cents
  Use for: Footsteps, UI

Moderate:
  Volume: ±3-4 dB
  Pitch: ±100-200 cents
  Use for: Weapons, impacts

Dramatic:
  Volume: ±5-6 dB
  Pitch: ±200-400 cents
  Use for: Explosions, special effects
```

**Repeat Avoidance:**
```
Frequent sounds (footsteps): avoidRepeatLast = 2-3
Weapons: avoidRepeatLast = 1-2
Voice lines: avoidRepeatLast = 3-5
```

### 11.5 Event Design

**Instance Limits:**
```
Explosions: 5-10
Gunshots: 8-12
Footsteps: 4-6
UI clicks: 2-3
Dialogue: 1
Music: 1
```

**Priority Assignment:**
```
Critical (255):
  - UI feedback
  - Dialogue
  - Tutorial VO

High (128):
  - Player footsteps
  - Player weapons
  - Important pickups

Medium (64):
  - Enemy sounds
  - Environmental feedback
  - Non-critical UI

Low (0):
  - Distant ambience
  - Background loops
  - Decorative sounds
```

**Cooldowns:**
```
UI clicks: 0.05-0.1s
Footsteps: Usually handled by animation
Weapon fire: Usually handled by game logic
Repeated impacts: 0.05-0.1s
```

### 11.6 State Design

**State Group Organization:**
```
Location:
  - Normal
  - Underwater
  - Cave
  - Indoor
  - Outdoor

GameplayState:
  - Menu
  - Playing
  - Paused
  - GameOver

CombatState:
  - Calm
  - Alert
  - Combat
```

**Transition Times:**
```
Fast (0.1-0.3s):
  - Pause/Unpause
  - UI state changes
  - Instant feedback

Medium (0.5-1.0s):
  - Entering water
  - Room changes
  - Combat state changes

Slow (1.5-3.0s):
  - Time of day
  - Weather changes
  - Gradual transitions
```

### 11.7 Common Pitfalls

**DON'T:**

❌ **Post events every frame**
```csharp
// BAD
void Update()
{
    if (isWalking)
        footstepEvent.Post();  // Spam!
}

// GOOD
public void PlayFootstep()  // Called from animation event
{
    footstepEvent.Post();
}
```

❌ **Forget instance limits**
```csharp
// Without maxInstances, this spams audio
for (int i = 0; i < 100; i++)
    explosionEvent.Post();
```

❌ **Over-use 3D spatialization**
```
Use 2D for: UI, music, non-positional SFX
Use 3D for: Positioned sounds only
```

❌ **Set all buses to 0 dB**
```
Leaves no headroom → clipping when many sounds play
Always leave -3 to -6 dB on Master
```

❌ **Ignore variation**
```
Single clip footsteps → machine gun effect
Always use RandomContainer with 4+ clips
```

**DO:**

✅ **Use cooldowns**
```csharp
Event cooldown prevents spam automatically
```

✅ **Add variations**
```csharp
6-8 clips + randomization = natural sound
```

✅ **Profile voice count**
```csharp
Monitor regularly, adjust maxInstances
```

✅ **Organize assets**
```csharp
Consistent folder structure
Clear naming conventions
```

✅ **Leave headroom**
```csharp
Master: -3 to -6 dB
Prevents clipping
```

## Troubleshooting

Source: https://peppersfx.com/docs/manual/troubleshooting/

### 12.1 Sound Not Playing

**Symptoms:** Event.Post() called, no sound.

**Checklist:**

1. **AudioManager exists?**
```csharp
// Check console for "AudioManager not found" error
// Add AudioManager to scene if missing
```

2. **Event in Resources folder?**
```
Events MUST be in: Assets/Audio/Resources/Audio/Events/
Check exact path, case-sensitive
```

3. **Container has clips?**
```
Open container asset
Check AudioClips list is not empty
Verify clips are assigned (not "None")
```

4. **Bus volume not -80 dB?**
```
Check bus hierarchy
Each bus in chain should be > -80 dB
```

5. **Max instances reached?**
```
Check event.MaxInstances
Check VoiceStealBehavior
Increase maxInstances or add stealing
```

6. **Cooldown active?**
```
Check event.Cooldown value
Wait cooldown duration between calls
```

7. **Console errors?**
```
Check for exceptions or warnings
Red errors prevent playback
```

### 12.2 No Variations

**Symptoms:** Same sound plays repeatedly, obviously.

**Checklist:**

1. **Using RandomContainer?**
```
Not RoutingContainer
Must be RandomContainer for variations
```

2. **Multiple clips assigned?**
```
Need 4+ clips for good variation
Check container's AudioClips list
```

3. **avoidRepeatLast set?**
```
Set to 2-3 for best results
Prevents recent clips from repeating
```

4. **Randomization enabled?**
```
Check enableVolumeRandomization
Check enablePitchRandomization
Set in base container settings
```

### 12.3 3D Sound Not Spatial

**Symptoms:** Sound plays but doesn't pan left/right or change volume with distance.

**Checklist:**

1. **Container is3D = true?**
```
Check container settings
3D Settings → is3D checkbox
```

2. **AudioListener in scene, and the listening point where you think?**
```
Only one AudioListener should exist
Usually on MainCamera
Check it's not disabled
```
Unity pans from its AudioListener; Pepper's distance-based features use the listening point (§9.3). If they're on different objects, register the point to follow the listener's transform, or call `AudioManager.Instance.DriveUnityListener(listener)`. In Play mode the Audio Manager's inspector shows the point in use.

3. **Spatial Blend = 1?**
```
AudioManager sets this automatically
But check if overridden somehow
```

4. **Min/Max Distance set correctly?**
```
minDistance: Full volume distance (e.g., 1)
maxDistance: Zero volume distance (e.g., 50)
Check values aren't reversed or extreme
```

5. **Playing at correct position?**
```
event.Post(gameObject, transform.position)
Verify position is in world space
Verify not at (0,0,0) always
```

### 12.4 Switch Container Not Switching

**Symptoms:** SwitchContainer always plays same container regardless of switch value.

**Checklist:**

1. **SetSwitch called BEFORE Post?** With When Switch Changes = Next Play Only (the default), a playing sound keeps its choice. Set Crossfade or Restart on the Switch if a playing loop should follow (§4.5).
```csharp
// CORRECT order
AudioManager.Instance.SetSwitch("Surface_Type", "Metal");
footstepEvent.Post();

// WRONG order
footstepEvent.Post();
AudioManager.Instance.SetSwitch("Surface_Type", "Metal");  // Too late!
```

1b. **A closer value wins.** A value set on the sound's handle or its Audio Emitter wins over the global one; `handle.GetEffectiveSwitch(group)` shows what the sound reads. A group **Driven By** a parameter ignores values set directly (a warning says so).

2. **Switch value matches entry?**
```
Case-sensitive matching
"Metal" != "metal"
Check spelling exactly
```

3. **Switch group correct?**
```
Verify switchGroupName matches
"Surface_Type" must match exactly
```

4. **Default container assigned?**
```
Assign default as fallback
Helps debug which code path is taken
```

5. **Debug log switch value:**
```csharp
string value = AudioManager.Instance.GetSwitch("Surface_Type");
Debug.Log($"Current switch value: {value}");
```

### 12.5 Occlusion Not Working

**Symptoms:** Sounds not muffled by walls.

**Checklist:**

1. **Occlusion mask includes geometry?**
```
Check AudioManager.occlusionMask
Should include layer with walls/geometry
Shouldn't include player layer
```

2. **Container `Use Occlusion = true`?**
```
Each container opts in per-instance via the Use Occlusion toggle.
Voice Mixer + OcclusionLayout must also be assigned on AudioManager for the low-pass.
Without a slot the sound only gets quieter behind walls; it keeps its treble.
```

3. **Sounds are 3D?**
```
Occlusion is meant for 3D sounds: rays go from the listener to the voice's position
It doesn't check is3D, but a 2D voice's position rarely means anything
Check container is3D = true
```

4. **AudioListener exists?**
```
Occlusion raycasts from listener position
Check listener component active
```

5. **Update interval too slow?**
```
Default 0.2s is fine
If too slow (>0.5s), noticeable lag
Check AudioManager.occlusionUpdateInterval
```

6. **Geometry has colliders?**
```
Raycast needs colliders to hit
Verify walls have colliders
Check collider layer matches occlusionMask
```

### 12.6 Blend Container Not Blending

**Symptoms:** Blend container plays but all layers same volume, no crossfading.

**Checklist:**

1. **Parameter value being set, in the right scope?**
```csharp
// What this play actually reads (handle, then emitter, then global, then default)
float value = handle.GetEffectiveParameter(combatIntensity);
Debug.Log($"Blend reads: {value}");

// Set explicitly for testing
AudioManager.Instance.SetRTPC("CombatIntensity", 0.5f);
```
A value set on an Audio Emitter only reaches sounds **posted on that emitter**; a value on a handle only reaches that sound. A global value is hidden by an emitter or handle value.

2. **Volume curves configured?**
```
Check BlendEntry.volumeCurve
Must not be flat line
Create varied curves in editor
```

3. **All layers have containers?**
```
Null containers don't play
Verify all entries assigned
```

4. **Loop enabled for music?**
```
Music should loop
Check container Loop = true
```

5. **Parameter name matches?**
```
blendParameterName (or the asset's Parameter Name) must match the name you set exactly
Case-sensitive: "CombatIntensity" != "combatintensity"
```

6. **Value in range?**
```
A named parameter is read clamped to 0-1. With a Parameter asset, the curves' X axis
is in the asset's unit and values are clamped to its Min..Max.
```

7. **Manual update mode?**
```
With the Audio Manager's Update Mode set to Manual, layers only move when Tick() is called.
```

### 12.7 Performance Issues

**Symptoms:** Audio stuttering, frame drops, high CPU.

**Diagnosis:**

**High Voice Count:**
```
Problem: realVoices > 50-60
Solution:
  - Lower maxRealVoices
  - Add maxInstances to events
  - Increase priorities correctly
```

**CPU Spikes:**
```
Problem: Update intervals too fast
Solution:
  - Increase voiceUpdateInterval (0.1 → 0.15s)
  - Increase occlusionUpdateInterval (0.2 → 0.4s)
  - Profile in Unity Profiler
```

**Memory Issues:**
```
Problem: Too many clips loaded
Solution:
  - Check clip import settings
  - Use Streaming for large files
  - Compressed In Memory for SFX
```

**Mobile Performance:**
```
Problem: General slowdown
Solution:
  - Reduce maxRealVoices to 16-24
  - Disable occlusion
  - Increase update intervals
  - Lower clip quality
```

### 12.8 Multi-Position Sync Issues

**Symptoms:** Multiple emitters playing out of sync, phasing.

**Checklist:**

1. **Which mode is the emitter parent in?**
```
Check AudioMultiPositionEmitterParent → Multi Position Type
Decorrelated offsets each emitter on purpose (random start + slight pitch), so it never sounds phase-locked.
SingleEmitter plays one voice at the nearest emitter.
For sample-locked playback at every position, post with a Vector3[] or Transform[] array instead.
```

2. **Using PostMultiPosition()?**
```csharp
// CORRECT
event.PostMultiPosition(emitterParent);

// WRONG
event.Post();  // Normal mode, no sync
```

3. **All emitters active?**
```
Check emitterChild.IsActive
Verify parent.ActiveEmitterCount > 0
```

4. **DSP buffering adequate?**
```
Default 0.1s latency usually fine
If still issues, increase buffer
```

## Ambient Propagation Subsystem

Source: https://peppersfx.com/docs/manual/ambient-propagation-subsystem/

**New in v2.3.0.** An optional, additive subsystem that ships in the same package as the rest of Pepper.SFX. It is designed specifically for **long-running ambient beds** (rain, wind, crowd murmur, machinery, rivers) that must route through world geometry in a physically plausible way — leaking *from* the window when the listener is in another room, muffling behind closed doors, swelling as openings widen.

Propagation is **not** a replacement for the SFX event pipeline. It lives next to it, sharing the same `AudioManager`, the same mixer group structure, and the same `AudioListener`. SFX events continue to handle discrete sounds (footsteps, weapons, UI). Propagation handles the persistent acoustic background.

### 13.1 Why This Subsystem Exists

**Standard 3D audio falls apart for ambient beds indoors.** Unity's built-in distance attenuation and a single `AudioLowPassFilter` raycast can occlude a sound, but they can't express:

- "The rain source is 100m away in the sky, but the listener should hear it *from the 2m-wide window*"
- "The door is halfway open, so the transmission is halfway between muffled and clear"
- "Walking through a doorway should smoothly crossfade the listener's acoustic perspective"

These are **routing** problems, not gain problems. Propagation solves them by modeling rooms as graph nodes and openings as edges, then running a per-frame shortest-path solve from every ambient source to the listener.

### 13.2 Mental Model

```
Zone_Outdoors ─────[Window]───── Zone_LivingRoom ─────[Door]───── Zone_Hallway
   (rain source)                      (listener may be here)        (or here)
```

- **Zones** are volumes of world space tagged as one acoustic room. They're the graph's nodes.
- **Portals** are openings that connect two zones. They're the graph's edges.
- **Ambient sources** declare "I exist in this zone with this clip." They don't play audio themselves.
- The **solver** finds the best path from each source's zone to the listener's zone (or the best few: `Max Paths Per Source`, §13.14), accumulating transmission loss in dB and the minimum cutoff frequency along the way.
- The **emitter** — a persistent, pooled `AudioSource` — is positioned at the portal the listener is hearing the source *through*, with volume and low-pass driven by the accumulated path.

When the listener moves between zones, the path changes, the emitter glides to a new portal, and the filtering/volume update smoothly. When a door opens, the portal's transmission multiplier increases and the next solve propagates that change end-to-end.

### 13.3 Architecture

**Namespace:** `AudioSystem.Propagation`
**Location:** `Assets/Scripts/SFX_System/RunTime/Propagation/`

```
Propagation/
├── Core/
│   ├── AudioZone.cs          ← MonoBehaviour, graph node
│   └── AudioPortal.cs        ← MonoBehaviour, graph edge + blend region
├── Runtime/
│   ├── PropagationManager.cs     ← singleton, orchestrates solve + emitters
│   ├── AmbientSource.cs          ← declares "there is an ambient here"
│   ├── AmbientEmitter.cs         ← pooled persistent voice
│   ├── AudioListenerZoneTracker.cs  ← on the player object (needs its Collider)
│   └── PropagationProximityCuller.cs ← scale groundwork
├── Interfaces/
│   └── IPortalDoorSource.cs  ← minimal door contract (portable)
└── Internal/
    ├── PropagationSolver.cs  ← pure Dijkstra
    └── PropagationPath.cs    ← solve result struct
```

### 13.4 The Solve Pipeline

Every `1 / solveRateHz` seconds (default 15 Hz, ≈ 67 ms), or immediately on any of several "dirty" triggers:

1. **Culling tick** (`PropagationProximityCuller.Tick`) — recomputes which zones and portals are within `activationRadius` of the listener. Runs every `cullCheckFrameInterval` frames (default 10). On the first tick after startup it's forced to run so the solver doesn't see an empty graph.

2. **Listener-zone resolution** — top-of-stack from `listenerZoneStack`. The stack uses last-entered-wins semantics so nested zones (e.g. Kitchen ⊂ House) resolve to the innermost zone the listener most recently crossed into.

3. **Blend portal selection** — if the listener is physically inside any `AudioPortal`'s trigger volume, that portal becomes the **blend portal**. If multiple overlap, the nearest wins.

4. **Per-source solve:**
   - **Blend region active?** Run Dijkstra **twice** — once targeting the zone on the portal's `blend=0` side, once targeting the `blend=1` side — then blend the two results using the listener's position along the portal's transition axis.
   - **Not in a blend region?** Single solve: source zone → listener zone.

5. **Apply results** to the source's `EmitterSlot`:
   - No active emitter yet → acquire one from the pool and `FadeInTo(…)`
   - Same portal as before → in-place retarget (smooth glide)
   - Different portal → move the current emitter to the fading slot, acquire a fresh one, crossfade

6. **Per-frame smoothing** (`AmbientEmitter.Tick`) — runs every frame regardless of solve rate. Smooths volume linearly, cutoff in log-frequency space, position in world space. Framerate-independent via `1 - exp(-smoothSpeed * dt)`.

**Dirty triggers that force an out-of-schedule solve:**
- Zone or portal registered / unregistered
- Listener entered / exited a zone or portal
- Ambient source registered / unregistered
- `IPortalDoorSource.OnChanged` fires
- Culler active set changes

**Outside-the-graph handling.** When the listener or source falls outside every registered `AudioZone`, propagation has no opinion. The `PropagationManager.silenceOutsideGraph` inspector toggle picks one of two readings:

- **Off (default — "whitelist mode").** `propGain = 1`, `propCutoff = 22 kHz`. Voices outside the graph play at full audibility. Right when AudioZones are a *whitelist* for bespoke acoustics and "outside the zones" means "the open world plays normally."
- **On ("complete-coverage mode").** `propGain = 0`, `propCutoff = 500 Hz`. Voices outside the graph fall silent and maximally muffled. Right when every walkable space is meant to be inside *some* zone and "outside" means the listener escaped intended geometry. The silence makes the gap obvious rather than masking the bug under full audibility.

The default is Off because surprise silence is harder to debug than surprise audibility. Affects only voices opted into `UsePropagation` — AmbientSources always behave as in whitelist mode regardless of the toggle.

### 13.5 Solver Math

The solver is plain Dijkstra over the zone graph. The twist is what goes into the edge cost.

**Edge cost** (portal `p`):
```
cost(p) = -20 * log10(transmissionMultiplier(p))
        + distancePenaltyDbPerMeter * distance
```

Transmission is amplitude-space (`[0, 1]`). Converting to dB makes losses *additive* along a path — summing edge costs in dB is equivalent to multiplying amplitudes, which is the physically correct composition of cascaded openings.

**Distance penalty** is optional (`0` by default). Raise it slightly to prefer geographically closer portals when transmission is similar, e.g. so a listener in a long corridor routes rain through the nearer of two equally-open windows.

**Cutoff aggregation** is by **minimum** across the path, not sum. A chain of low-pass filters is dominated by the tightest one — later filters cannot restore frequencies earlier ones removed. The solver tracks this separately from the Dijkstra cost and reads out the final value once it reaches the listener zone.

### 13.6 Blend Region Crossfading

The naive approach to doorway transitions — "if listener is in Zone A, play path A; if in Zone B, play path B" — produces an audible snap at the exact moment the listener crosses the threshold. Real rooms don't work that way; the listener's ears mix contributions from both spaces continuously across the doorway.

**The fix**, implemented in `PropagationManager.ApplyBlendedResult`:

1. Compute blend factor `t ∈ [0, 1]` from the listener's position along the portal's transition axis.
2. Solve twice — once targeting `GetZoneAtBlendFactorZero()`, once targeting `GetZoneAtBlendFactorOne()`.
3. **Volume**: blend in dB space (`Mathf.Lerp(aDb, bDb, t)`, then `10^(db/20)`) so the perceptual ramp is even.
4. **Cutoff**: blend in log-frequency space (`exp(lerp(log(aHz), log(bHz), t))`).
5. **Virtual emitter position**: linear world-space `Lerp` between the two path endpoints.
6. **Owning portal**: remains the blend portal throughout — never flipped mid-doorway, which would cause an unnecessary pool swap.

The result is a continuous, pop-free traversal of any doorway, regardless of how fast the listener walks through.

#### Auto-detecting blend axis orientation

Zone ordering (`ZoneA` vs `ZoneB`) is arbitrary — designers can drag them in any order. To avoid the manager needing to know which side is which, the portal auto-detects this in `DetectPositiveAxisIsZoneB`: it probes points slightly outside the trigger on each axis end and tests which zone's `ContainsPoint` returns true. The result is cached on first query. Designers never configure this directly — they just orient the GameObject's `+Z` through the opening.

#### Zone entry fades

Portals handle the "smooth doorway crossing" case via the blend region described above. **The interior of a zone has its own complementary mechanism**: `AudioZone.entryFadeMeters` (default 0). When set above 0, a point at the trigger surface has membership = 0 and a point that many world meters inside has membership = 1; in between, membership ramps linearly. Multi-collider zones take the max across colliders so overlapping boxes don't dip at internal junctions.

The runtime uses this membership to fade three things across the zone surface so designers don't hear a flip at the boundary:

- **Reverb-send level** (source-side) — a voice entering the zone tapers its contribution to the zone's reverb bus from 0 to full as it crosses the fade band.
- **Listener-side reverb profile** — when the listener crosses into a zone, the bus's `Room` parameter lerps from silent toward the zone's authored value across the band. Portal blend regions are unaffected; that path already has its own continuous crossfade.
- **`AudioZone.BaseVolumeDb` contribution** — a zone with non-zero baseline attenuation applies that baseline scaled by source membership, so AmbientSources crossing the surface ease in/out rather than stepping.

`entryFadeMeters = 0` (the default) preserves the original hard boundary — useful for tight rooms where you want instantaneous switching, or for any zone whose acoustic identity is binary by design. For non-rectangular zones built from multiple overlapping BoxColliders, set the fade smaller than the overlap depth to avoid dips at internal junctions.

### 13.7 Emitter Pool Design

Propagation emitters are **persistent looping voices**, not short-fire SFX. That has two important consequences:

**1. They bypass the SFX voice pool by design.** `AudioManager.OcclusionPerf` iterates only the pool-owned `realVoices` list and applies raycast-based occlusion + low-pass filtering. If propagation emitters were registered with that pool, they'd receive **two** filters stacked — propagation's portal-based low-pass *plus* occlusion's raycast low-pass — sounding far too dull. By owning their own `AudioSource`, propagation emitters sidestep this without any change to the SFX path.

**2. The Ambience mixer group still applies.** The emitters route `AudioSource.outputAudioMixerGroup = ambienceMixerGroup`, so bus ducking, master volume, scene-unload mixer fades, and effect sends all still function. They're decoupled from the voice pool, not from the mix bus.

**Pool lifecycle per source:**

```
EmitterSlot {
    Active  : AmbientEmitter   // currently voicing the best path
    Fading  : AmbientEmitter   // previous emitter, ramping down after swap
}
```

On a portal change:
1. `Fading` is recycled to the pool (only if already silent — otherwise keep it and skip the swap, to avoid a pop from abruptly stopping an audible source)
2. Old `Active` → `Fading`, `FadeOut()` called
3. New `Active` acquired from pool, `FadeInTo(newPortal, …)` with minimum 50 ms ramp

**Global cap:** `maxAmbientEmitters = 16` (inspector). When exceeded — pathological scenes with many simultaneous sources — the farthest emitter is faded out first.

### 13.8 Per-Frame Smoothing

Solves run at 15 Hz, but the ear is sensitive to parameter discontinuities at any rate. Every frame, `AmbientEmitter.Tick` pulls current values toward targets using:

```
k = 1 - exp(-smoothSpeed * dt)
current = lerp(current, target, k)
```

This is framerate-independent (doesn't drift at 30 FPS vs 120 FPS) and gives exponential approach with a time constant of `1 / smoothSpeed`. Default `smoothSpeed = 4` → ~250 ms to reach ~98% of a target. Values in the 3–5 range cover most use cases; higher values feel snappier but expose solve-tick boundaries.

**Pop-prevention rules**:
- Never start at full volume. First-frame rise is clamped to `dt / MinFadeSeconds` (50 ms).
- Never stop at non-zero volume. `Tick` only calls `Stop()` when both current and target are below the silence threshold AND `fadingOutForRelease` is true.
- Retargeting to an audible value clears the release flag, cancelling any in-progress fade-out.

### 13.9 Door Abstraction (`IPortalDoorSource`)

Propagation is shipping inside Pepper.SFX package, which is consumed by many projects. It cannot depend on any specific project's door system. The solution:

```csharp
namespace AudioSystem.Propagation
{
    public interface IPortalDoorSource
    {
        float OpenProgress { get; }   // 0 = closed, 1 = open
        event System.Action OnChanged;
    }
}
```

**Any MonoBehaviour** that implements this interface can be dragged into an `AudioPortal`'s `Door Source` field. Projects bridge their own door system (ScriptableObject channels, event buses, animator parameters, physics-driven hinges) with a thin adapter MonoBehaviour. The portal subscribes to `OnChanged` and requests an immediate re-solve when the event fires — so fast door swings don't wait for the next solve tick.

Portals with `doorSource == null` are treated as always open — windows, archways, vents.

### 13.10 Authoring Rules (Enforced by OnValidate)

Many propagation bugs are authoring mistakes. The inspector catches them:

- **Zone colliders must be triggers.** `AudioZone.OnValidate` force-sets `isTrigger = true` on every BoxCollider on the GameObject and logs a warning.
- **Portal colliders must overlap both zone colliders by ≥ 5 cm.** Without overlap, the listener can fall into a "no zone" gap at the doorway and emitters flicker. `AudioPortal.OnValidate` computes the AABB overlap and logs an inspector error on each zone that fails.
- **`closedTransmission` must be ≤ `baseTransmission`**, and `closedLowPassHz` must be ≤ `openLowPassHz`. Swapping these is a common mistake — the portal warns if detected.
- **Both zones required.** Null zone references log an inspector error. Zone self-loops (zoneA == zoneB) also logged.
- **Activation radius must be > 0.** Use `float.PositiveInfinity` to opt out of culling; zero is never valid.

### 13.11 Scale: The Proximity Culler

Naïve Dijkstra over 200 zones + 400 portals is O(V·E) per solve, per source. The `PropagationProximityCuller` ensures the solver only sees what matters:

- Every `cullCheckFrameInterval` frames (default 10), recompute the active set based on per-node `activationRadius` distance from listener.
- Global hard caps (`globalMaxActiveZones = 64`, `globalMaxActivePortals = 128`) drop the farthest when the radius filter still yields too many.
- The listener's current zone is **always** included even if outside its radius — prevents silent emitters for a listener standing next to a culled-out zone.
- Opt out per node: `activationRadius = float.PositiveInfinity` (e.g. outdoor ambience zones that should never cull).
- Opt out globally: `cullCheckFrameInterval = 0`.

**Startup**: the culler forces its first recompute to run immediately regardless of interval, so the solver never sees an empty graph during the first 10 frames of play.

### 13.12 Integration with Existing SFX_System Features

| Feature                          | Interaction with propagation                                                                          |
|----------------------------------|-------------------------------------------------------------------------------------------------------|
| `AudioManager` singleton         | Read-only consumer. Propagation does not modify AudioManager or add RTPC/state requirements.          |
| `SetRTPC` / `IRTPCListener`      | Reserved for global/weather parameters. Propagation drives per-emitter `AudioSource.volume` directly. |
| `AudioBus` + `AudioMixerGroup`   | AmbientEmitters route through a designated Ambience mixer group. Bus ducking and master fades still apply. |
| `AudioState`                     | Not wired in — designers can still author "Player_Outdoors" states that tweak the ambience bus.       |
| `AudioManager.OcclusionPerf`     | AmbientEmitters bypass the pool (no double-filtering). SFX voices that opt in via the container's `Use Propagation` flag compose propagation cutoff with their raycast cutoff (most-muffled-wins). |
| `AudioMultiPositionEmitterParent`| Orthogonal. Future `AmbientSource` refinement could delegate source-position selection to one.       |
| SFX events (`AudioEvent`)        | Containers can opt SFX voices into propagation cutoff (`Use Propagation`) and per-zone reverb sends (`Allow Reverb Send`). When neither flag is set, SFX is untouched by propagation. |

### 13.13 Performance

- **Solver**: ~0.1 ms per source per solve for a culled graph of ~20 zones / ~40 portals (Editor, mid-range desktop). Reusable `PropagationSolver.Buffers` eliminate per-tick GC.
- **Solve cadence**: 15 Hz default (≈ 67 ms per tick). Mobile can safely drop to 8 Hz — the emitter's per-frame smoothing hides the lower rate for walking-speed movement. Faster zone-trigger crossings or partially-closed-portal transitions benefit from the higher default; drop below 10 Hz only if CPU profiling justifies it.
- **Emitters**: cost = `maxAmbientEmitters` AudioSource channels. Default cap is 16 — well within voice headroom even on mobile.
- **Allocation-free** in the hot path: solver buffers, scan scratch list, culler scratch list, and emitter pool are all reused.

### 13.14 Design Limits

Known limits:

1. **One path per source by default.** With `Max Paths Per Source` at 1 (the default, on `PropagationManager`) the solver voices one path per source: if rain leaks through both a window and an open skylight, you hear it through whichever has lower transmission loss. Raise it (up to 6) to voice several paths at once, each through a different opening on the listener's side and each with its own emitter, so watch `Max Ambient Emitters`. While the listener stands inside a portal's trigger (the blend region), each side still uses one path.
2. **No diffraction.** Real sound bends around corners; the solver assumes straight-line zone adjacency. For small spaces this is rarely noticeable; for huge open-plan spaces you may want to subdivide into more zones.
3. **No raycast occlusion on AmbientEmitters.** AmbientEmitter routing is purely zone/portal topology — the pooled persistent voices do not participate in `AudioManager.OcclusionPerf`'s raycast pass. SFX voices opted into `Use Propagation` *do* compose both (propagation cutoff + raycast cutoff, min-wins). If you need clutter-based occlusion on top of an ambient bed (e.g. a crate blocking line of sight to the emitter), model the bed as an SFX-event-driven loop rather than an `AmbientSource`.
4. **Blend factor updates at solve rate, not per-frame.** For extremely fast doorway traversals (sub-100 ms) you may want to raise `solveRateHz` toward 20–30. For walking speeds the default 15 Hz is imperceptible.
5. **Box-shaped zones by default.** L-shaped zones work via multi-BoxCollider OR-union. For sphere/mesh-shaped zones, subclass `AudioZone` and override `ContainsPoint` / `ClosestSurfacePoint` — both are `virtual` for this reason.

### 13.15 Troubleshooting

**Sound appears flat or doesn't propagate through doorways.**
- Confirm zones and portals are registered: `Debug.Log(PropagationManager.Instance)` in play mode; inspector shows the manager component if auto-instantiated.
- Zone colliders must have `isTrigger = true` (usually auto-forced). Check the physics layer matrix — if the listener's layer doesn't interact with the zone's layer, trigger events never fire.
- `AudioListenerZoneTracker` must be on a GameObject with a Collider, usually the player root. On the camera that holds the `AudioListener` it never gets trigger events.

**Emitter flickers at a doorway.**
- Portal collider doesn't overlap one of the zone colliders by ≥ 5 cm. Inspector error will say which zone. Extend one or both to overlap.

**Pops or clicks.**
- Almost always an un-looped clip. The emitter sets `AudioSource.loop = true`; Unity replays the clip from sample 0 with no crossfade. The clip itself must be seamless.

**Door animation doesn't affect audio in real time.**
- The `IPortalDoorSource` implementation must fire `OnChanged` on value changes. Without it, the portal only picks up the new value on the next solve tick (≤ ~67 ms latency at the default 15 Hz).
- Spamming `OnChanged` every frame is fine — each fire triggers one re-solve, and the solve cost is modest — but prefer a threshold (e.g. `Δ ≥ 0.02`) to avoid redundant work during continuous animation.

**First solve after loading is silent for ~150 ms.**
- Fixed as of v2.3.0 — the culler's first tick runs immediately regardless of interval. If you still see this, confirm you're on v2.3.0 or later.

## Occlusion Mixer Slot Pool

Source: https://peppersfx.com/docs/manual/occlusion-mixer-slot-pool/

The system for muffling SFX voices behind walls, geometry, and (via propagation) through doorways. Ships alongside the propagation subsystem from chapter 13 and composes with it cleanly — propagation handles "rooms and openings," this chapter handles "stuff in the way between the listener and the emitter."

### 14.1 Why Mixer Slots, Not Per-Source Filters

The obvious way to muffle a 3D sound is to attach an `AudioLowPassFilter` to its `AudioSource` and modulate the cutoff. We tried that first. It clicks.

The cause: `AudioLowPassFilter` carries internal biquad filter state — the running coefficients of the IIR. When the host AudioSource is stopped and re-played (which happens every time the voice pool reuses an `AudioSource`), Unity resets the biquad to default state at the next sample boundary. Whatever signal is in the source's playback buffer hits an uninitialised filter and produces a sample-boundary discontinuity audible as a per-acquire click. Pool-driven SFX, especially anything firing fast like footsteps or weapon shots, surface this as a rhythmic ticking layered under the actual sound.

Mixer effects don't have this problem. `AudioMixerEffectController` instances live on `AudioMixerGroup`s — they don't reset when an AudioSource starts and stops. If we author N mixer groups per logical bus, each with a Lowpass effect whose cutoff is an exposed mixer parameter, voices can be **routed through** one of those groups for the duration of their playback. The voice's own AudioSource has no filter component at all. Muffling becomes a mixer write to a stable, long-lived effect — no biquad reset, no click.

That's the slot pool. **One mixer group per slot, N slots per bus.** A pre-built pool of routing destinations that voices borrow and return.

> **Filter curves are different.** A container's Low Pass and High Pass **Parameter Curves** (§4.1) do put an `AudioLowPassFilter` / `AudioHighPassFilter` on the voices that need them, switched off when fully open. They are meant for long sounds that move slowly through a filter (an engine loop dulling with load, wind opening with speed), where a reset at the voice's start doesn't matter. Occlusion still uses the slots described here, and short, fast-firing sounds should stay away from filter curves.

### 14.2 Mental Model

```
   ┌────────────────────────────────────────────────────────┐
   │  Voice Mixer (Unity AudioMixer asset)                   │
   │                                                          │
   │   Master                                                 │
   │     ├── Footsteps              ← logical bus            │
   │     │     └── Footsteps_OcclusionLayer                   │
   │     │           ├── Footsteps_Slot_00 ←─┐                │
   │     │           ├── Footsteps_Slot_01    │ voices borrow │
   │     │           ├── Footsteps_Slot_02    │ ONE of these │
   │     │           ├── Footsteps_Slot_03    │ at acquire   │
   │     │           ├── Footsteps_Slot_04    │ time         │
   │     │           └── Footsteps_Slot_05 ←─┘                │
   │     │                                                    │
   │     ├── Weapons                ← another logical bus     │
   │     │     └── Weapons_OcclusionLayer                     │
   │     │           ├── Weapons_Slot_00                      │
   │     │           …                                        │
   │     ⋮                                                    │
   └────────────────────────────────────────────────────────┘
```

- **Slots are pre-built**: the mixer groups, their Lowpass effects, and the exposed cutoff parameters are all authored at edit time. The runtime never adds or removes groups.
- **Voices acquire at play time**: when a container with `Use Occlusion` plays, `AudioManager.GetVoice(container)` calls `AcquireOcclusionSlot(bus)` to lease one of the free slots. The voice's `outputAudioMixerGroup` is set to the slot's mixer group for its entire lifetime.
- **Voices release on completion**: `ReturnVoice` pushes the slot back to the free queue. The released slot's cutoff is reset to 22 kHz (transparent) so the next voice that grabs it starts unmuffled.
- **Muffling is a mixer write**: every frame, `OcclusionPerf.LateUpdate` writes the smoothed cutoff target to the held slot's exposed parameter via `voiceMixer.SetFloat(slot.CutoffParam, hz)`. No filter component on the voice itself.

### 14.3 Authoring the Slot Layout

Open **Window ▸ Audio System ▸ Occlusion Layout** to author the slot hierarchy:

1. **Voice Mixer** — assign the project's voice mixer asset.
2. **Occlusion Layout** — assign or create an `OcclusionLayout` ScriptableObject. This is where the per-bus slot map gets serialized; the runtime reads it at startup.
3. **Reverb Send Bus Registry** (optional, covered in chapter 15) — when assigned, each generated slot also receives one Send effect per registered reverb bus.
4. **Slots Per Bus** — how many concurrent occluded voices each bus can host (default 6).
5. **Scan, Auto-Create, Refresh** — walks the project for `AudioContainer` assets with `Use Occlusion`, `Allow Reverb Send` or `Use Propagation` turned on (any of the three takes a slot at play time, see §14.4) and `AmbientSource` components with `Use Occlusion = true` in the open scenes, collects the unique mixer groups they play through (a layer with `Uses Parent Output` counts its Blend's or Switch's group), and authors one `<BusName>_OcclusionLayer` child group per bus, each containing N slot groups (`<BusName>_Slot_00`, `_Slot_01`, …) with a Lowpass effect and exposed cutoff parameter on each.

After Generate, the `OcclusionLayout` asset holds the layout. Drop it into `AudioManager` ▸ Occlusion Layout, and the runtime builds its slot pools from it at `Awake`.

The "Scan only" button runs the same scan without mutating the mixer — useful for sanity-checking which buses *would* be authored without committing changes.

### 14.4 Container Opt-In Flags

A voice acquires a slot when its container opts into any of three features:

| Container flag        | What it does                                                                       | Requires slot? |
|-----------------------|------------------------------------------------------------------------------------|----------------|
| `Use Occlusion`       | Raycast occlusion: muffle voices behind walls via listener→source linecast.        | For the low-pass (the volume drop works without one) |
| `Use Propagation`     | Propagation cutoff: muffle voices through portals via the propagation graph.       | For the low-pass (the volume drop works without one) |
| `Allow Reverb Send`   | Per-zone reverb sends (chapter 15).                                                | Yes            |
| `Static Emitter`      | Hint that this container's voices don't move. Speeds up the reverb-send driver.    | No (modifier)  |
| `Explicit Reverb Bus` | Override the zone-driven reverb send routing for this container.                   | No (modifier)  |

A container with none of the three feature flags routes voices directly to its bus (no slot). A container with at least one feature flag tries to acquire a slot when it plays; the AcquireOcclusionSlot call is upfront, before the AudioSource's `Play()`, because mid-playback `outputAudioMixerGroup` reassignment is click-prone in Unity.

**Pool exhaustion**: if all slots on the bus are in use when a new voice tries to acquire, `AcquireOcclusionSlot` returns null and the voice routes directly to the bus (no low-pass, no reverb sends; occlusion's and propagation's volume drop still applies, since it's written to the voice, not the mixer). A throttled warning is logged once per second per bus — bump Slots Per Bus on the layout asset if you see this consistently.

### 14.5 Runtime Lifecycle

The slot lifecycle per voice:

```
container.Play(position)
  ↓
AudioManager.GetVoice(container)
  ↓
  if (UseOcclusion || UsePropagation || AllowReverbSend)
      AcquireOcclusionSlot(container.MixerGroup) → slot
  ↓
ConfigureAudioSource(voice)
  ↓
  source.outputAudioMixerGroup = slot.MixerGroup  (or container.MixerGroup if no slot)
  ↓
source.Play()
  ↓
  ... [voice plays] ...
  ↓
  Every OcclusionUpdate tick (default 5 Hz):
    OcclusionRaycastGain = ...        ← raycast target
    OcclusionRaycastCutoff = ...      ← raycast cutoff target
  ↓
  Every frame, LateUpdate:
    Read propGain / propCutoff from PropagationManager cache (if UsePropagation)
    Compose: gainTarget = raycastGain × propGain
    Compose: cutoffTarget = min(raycastCutoff, propCutoff)
    Exponentially smooth voice.GainStack.OcclusionGain toward gainTarget
    voiceMixer.SetFloat(slot.CutoffParam, smoothedCutoff)
  ↓
source.Stop() or natural completion
  ↓
AudioManager.ReturnVoice(voice)
  ↓
  ReleaseOcclusionSlot(slot)
    ↓
    voiceMixer.SetFloat(slot.CutoffParam, 22000)   ← reset cutoff for next voice
    voiceMixer.SetFloat(slot.SendLevelParams[*], -80)  ← silence reverb sends
    pool.freeIndices.Enqueue(slot.IndexInPool)
```

Two key invariants: **the slot is acquired before the first audio sample plays**, and **the slot is reset before the next voice borrows it**. Both are click-prevention guarantees.

### 14.6 The Raycast Path (Use Occlusion)

For voices with `Use Occlusion = true`, the `OcclusionUpdate` coroutine fires a fan of rays from the listener toward the source on each tick (default 5 Hz, configurable via `Occlusion Update Interval`).

**Single ray** (`Occlusion Ray Count = 1`): the original behavior. A single linecast from listener to source. If blocked, the voice clamps to `raycastGain = 0.3` and `raycastCutoff ≈ 6.95 kHz` (the cutoff follows the gain: `Lerp(22000, 500, 1 − gain)`, so it never reaches 500 Hz from rays alone); if clear, both stay at unity / 22 kHz. Binary step.

**Multi-ray partial occlusion** (`Occlusion Ray Count > 1`, default 3): fans N rays toward N points spread perpendicular to the listener→source axis at the source end, with spread width `Occlusion Ray Spread Meters` (default 0.5 m). Counts how many of the N rays are blocked, computes a fraction, and lerps gain/cutoff targets by that fraction. With `RayCount = 3` you get four discrete blocked levels (0/3, 1/3, 2/3, 3/3) which the per-frame smoother rides over for perceptually continuous edge transitions — walking past a wall edge produces a gradient instead of a 10 dB step.

This is **edge diffraction approximated**: when the listener is behind a wall whose far edge is near the source, the wall-side ray is blocked but the edge-side ray clears, producing a partial occlusion fraction that crossfades the source up as you walk into line of sight. It's not a true geometric diffraction solver, but it sidesteps the worst artefact of binary occlusion (the "sudden snap" as the listener crosses an edge) at the cost of N raycasts instead of 1.

Raycasts run with `QueryTriggerInteraction.Ignore` so `AudioZone` and `AudioPortal` trigger volumes don't act as occluders. The source's own collider hierarchy and the listener's collider hierarchy are filtered out, so the emitter's primitive and the player's capsule don't self-occlude the line.

### 14.7 Composition With Propagation (Use Propagation)

For voices with `Use Propagation = true`, the `LateUpdate` smoother also reads the propagation subsystem's per-zone cache:

- `propGain` = `PropagationManager.GetSourceAudibility(sourceZone)` — the chain-of-portals linear amplitude weight from listener to source.
- `propCutoff` = `PropagationManager.GetSourcePropagationCutoff(sourceZone)` — the minimum cutoff across all portals on the path.

These compose with the raycast targets:

```
gainTarget   = raycastGain × propGain               (multiplicative)
cutoffTarget = min(raycastCutoff, propCutoff)       (most-muffled-wins)
```

Why min, not multiply, for cutoff? Cascaded low-pass filters are dominated by the tightest one — later filters can't restore frequencies an earlier one removed. The solver chains cutoffs the same way; raycast and propagation compose the same way; everything stays consistent.

**Outside-the-graph handling**: when the listener or source falls outside every registered `AudioZone`, propagation has no opinion. `PropagationManager.SilenceOutsideGraph` picks:

- **Off (default)**: `propGain = 1`, `propCutoff = 22 kHz`. Voices outside the graph play at full audibility. Use when AudioZones are a whitelist for bespoke acoustics and "outside" means "the open world plays normally."
- **On**: `propGain = 0`, `propCutoff = 500 Hz`. Voices outside the graph fall silent and maximally muffled. Use when every walkable space is meant to be inside *some* zone, and "outside" means "this is a level-design escape — surface the bug."

The default is Off because surprise silence is harder to debug than surprise audibility.

### 14.8 Per-Frame Smoothing

The slow OcclusionUpdate tick (5 Hz default = 200 ms) is too coarse for perceptual continuity — a 0.3→1.0 gain step at the tick boundary surfaces as a click. The fix: **slow tick stores step targets, per-frame `LateUpdate` smooths toward them**.

Two inspector-tunable time constants on AudioManager:

| Field                                  | Default | What it controls                                       |
|----------------------------------------|---------|--------------------------------------------------------|
| `Occlusion Gain Smoothing Seconds`     | 0.06    | Tau for the gain (volume) axis. Settles to 95% in ~3τ. |
| `Occlusion Cutoff Smoothing Seconds`   | 0.04    | Tau for the lowpass cutoff axis.                       |

Smoothing is framerate-independent: `k = 1 - exp(-dt / tau)`, then `current = lerp(current, target, k)`. At 60 fps with `tau = 0.06`, `k ≈ 0.24` per frame.

**Keep the two taus close to each other.** Large mismatches read as "the tone opens before the volume" (or vice versa) across an occlusion edge. The defaults (0.06 gain, 0.04 cutoff) are deliberately close.

**Unity's own `AudioSource.volume` ramp**: Unity applies its own ~40 ms ramp on every `volume` write at default DSP buffer size. That sets a floor on how snappy occlusion gain can feel regardless of our smoother. Set Project Settings ▸ Audio ▸ DSP Buffer Size to "Best Latency" to drop the floor to ~10 ms; designers chasing sub-50 ms perceived occlusion will need this.

### 14.9 Performance & Scaling

- **OcclusionUpdate cost**: `realVoiceCount × occlusionRayCount` raycasts per tick. At default settings (5 Hz × 3 rays × 20 voices = 300 rays/sec ≈ 5 raycasts per frame at 60 fps), this is negligible. Raycasts are microseconds each.
- **LateUpdate cost**: O(realVoiceCount) per frame for the smoother. One mixer SetFloat per voice with a slot. Tens of voices is free; hundreds is still cheap.
- **Pool sizing**: `defaultOcclusionSlotsPerBus` (default 6) means up to 6 concurrent occluded voices per bus. A scene firing more than 6 footsteps simultaneously on one bus will see pool exhaustion warnings — bump to 8–12 if needed. The cost per extra slot is a mixer group + one Lowpass effect + one exposed parameter, negligible at runtime.
- **Allocation-free** in the hot path: slot acquisition is queue dequeue (O(1), no allocation); cutoff writes are direct mixer calls.

### 14.10 Design Limits

1. **Slot exhaustion → no low-pass fallback.** When the pool is empty, new voices play through the bus directly (no slot, no low-pass; they still get quieter behind walls). This is intentional — graceful degradation beats failing to play. Watch the console for the throttled exhaustion warning and bump slots per bus accordingly.
2. **Multi-ray is not true diffraction.** It approximates edge softening for the most common case (wall with a near edge) but doesn't handle wraparound, multiple reflections, or frequency-dependent diffraction.
3. **Mixer is the cutoff source of truth.** There's no per-voice cached "current cutoff" — `LateUpdate` reads back via `voiceMixer.GetFloat` and lerps. Other code that writes to the same exposed parameter (a custom inspector slider during play, an editor script) will interleave with the smoother.
4. **One layout per project.** The slot pool architecture assumes a single voice mixer. Multi-mixer projects need separate AudioManagers (rarely needed).

### 14.11 Troubleshooting

**Voices play unmuffled even though `Use Occlusion` is on.**
- If they still get quieter behind walls, the rays work and only the slot is missing: the volume drop doesn't need one, the low-pass does.
- Is `Voice Mixer` assigned on AudioManager? Without it, slot pools never build and the warning at `Awake` will tell you so.
- Is `Occlusion Layout` assigned? Same diagnosis path.
- Did you re-run the Occlusion Layout Builder after adding the container? Containers added since the last Generate aren't in the layout yet.
- Inspect `AudioManager.OcclusionSlotPoolsReady` at play time — false means slot pools didn't build (mixer-layout mismatch, empty layout, etc.).

**Console says `Occlusion slot pool exhausted on bus 'X'`.**
- Self-explanatory: more concurrent occluded voices on that bus than slots configured. Increase `Slots Per Bus` on the layout asset and re-run Generate. The default 6 is sized for typical SFX density; weapon-heavy or footstep-dense scenes can want 10–16.

**Console says `... on bus 'X', which has no slots in the Occlusion Layout`.**
- A container with `Use Occlusion`, `Allow Reverb Send` or `Use Propagation` played through a bus the layout has no slots for (`AudioManager.GetVoice`, once per bus, only when a layout is assigned). The layout predates that bus needing slots: re-run **Scan, Auto-Create, Refresh** (§14.3).

**Sound clicks on the first frame of playback.**
- If the voice has a slot, the click is almost never from the system — check clip authoring (leading sample boundary, encoder pre-roll). If you can repro on a slotless container by toggling `Use Occlusion`, file a bug.

**Bus routing looks wrong in the mixer.**
- After Generate, each slot's mixer group should be a child of `<BusName>_OcclusionLayer`, which is a child of the user-authored bus. If you see slots floating at the master root or under a different bus, the layout asset is stale relative to the current mixer — re-run Generate.

**A specific container's voices ignore occlusion entirely.**
- Confirm the container has `Use Occlusion = true`. Confirm its `Mixer Group` is set to a bus that appears in the layout asset's bus list (containers whose bus isn't in the layout will be skipped silently at runtime, since there's no pool for that bus).

## Reverb Send Buses & Per-Zone Reverb

Source: https://peppersfx.com/docs/manual/reverb-send-buses-per-zone-reverb/

The "wet path" complement to the occlusion chapter. Where chapter 14 controlled how voices are *muffled* through geometry, this chapter controls how voices *contribute to* and *hear* the acoustic character of the rooms they're in. Two subsystems, one shared infrastructure.

### 15.1 Why Per-Zone Reverb

A single global reverb sounds wrong everywhere. A bathroom and a cathedral need very different decay times, reflection densities, and room sizes; sticking one preset across the whole game means most rooms feel like the same generic space. Per-zone reverb fixes that — but naively, in two distinct ways that don't compose.

**Approach 1: per-source reverb.** Each ambient bed and each SFX voice carries its own reverb settings. Right for ambient beds that should sound like the room they originate in (rain heard *through a window* should carry the outdoor character, not the room's). Wrong for SFX that should sound like the room the *source* is in (a gunshot fired in the bathroom should keep its bathroom-reverb tail even when the listener walks into the hallway). And expensive: N reverb instances running simultaneously.

**Approach 2: per-listener reverb.** A single reverb whose settings update based on the room the listener is currently in. Cheap (one reverb), and right for some sounds — but completely wrong for "a gunshot fired in the bathroom while the player is in the hallway should still sound like a bathroom gunshot." This approach makes every active sound sound like wherever the listener happens to be standing.

Neither is correct alone. Real acoustics combine both:

- **Routing is source-driven**: a voice's contribution goes to the reverb of the room it's *physically in*.
- **Character is room-driven**: each reverb bus represents one acoustic space, and its parameters don't change just because the listener walked to a different room.

The Reverb Send Bus subsystem implements this split. **Source-side: which bus a voice sends to is determined by the voice's zone.** **Listener-side: each bus's character is its own — defined by the bus's `ReverbSendBus` asset, the single source of truth.** Walking from the bathroom to the cathedral doesn't change which bus the bathroom gunshot is sending to — and doesn't change what the bathroom bus sounds like. Only the listener's *audibility weight* to that bus changes (the muffled "I can still hear it through the wall" attenuation), and that's handled by the propagation subsystem feeding the source-side audibility cache.

### 15.2 Mental Model

```
   Two independent axes per voice:

   ROUTING (source-side) — set on the AudioZone, decides which bus voices send to:
     AudioZone "Bathroom"   .ReverbBus = Reverb_Bathroom   ──►  send to Reverb_Bathroom bus
     AudioZone "Cathedral"  .ReverbBus = Reverb_Cathedral  ──►  send to Reverb_Cathedral bus
     AudioZone "Hallway"    .ReverbBus = (none)            ──►  no reverb sends from this zone

   CHARACTER (listener-side) — set on the ReverbSendBus asset, the single source of truth:
     ReverbSendBus "Reverb_Bathroom"   ──►  parametric params  OR  impulse response
     ReverbSendBus "Reverb_Cathedral"  ──►  parametric params  OR  impulse response
     (a bus's sound never depends on listener position or on any zone)
```

- **Voices** in the Bathroom zone whose container has `Allow Reverb Send = ✓` send a copy of their dry signal to `Reverb_Bathroom` at the container's authored level, scaled by the listener's audibility weight (1.0 same-zone, <1 through portals, 0 unreachable).
- **The `Reverb_Bathroom` bus** is one mixer group on the project's voice mixer. For a parametric bus it carries an SFX Reverb effect whose six listener-relevant parameters are exposed to the runtime via `AudioMixer.SetFloat`; for a convolution bus it carries the native convolution plugin (see §15.14).
- **The bus's character** comes entirely from its `ReverbSendBus` asset. For a parametric bus, the runtime driver writes the asset's six parameters onto the mixer effect each tick. The character does not depend on the listener's position or on any zone's profile — the asset *is* the room's identity.

### 15.3 The Two Halves Working Together

The clean separation between routing and character produces these expected behaviors:

| Scenario                                                | Source-side (which bus) | Listener-side (bus character) | Audibility scaling |
|---------------------------------------------------------|-------------------------|-------------------------------|---------------------|
| Listener in bathroom, gunshot in bathroom               | Bathroom                | Bathroom bus character        | 1.0 (same zone)     |
| Listener in hallway, gunshot in bathroom (door open)    | Bathroom                | Bathroom bus character        | ~0.3 (portal loss)  |
| Listener in hallway, gunshot in bathroom (door closed)  | Bathroom                | Bathroom bus character        | ~0.05 (closed door) |
| Listener in cathedral, gunshot in bathroom (no path)    | Bathroom                | Bathroom bus character        | 0 (unreachable)     |
| Listener in cathedral, choir voice in cathedral         | Cathedral               | Cathedral bus character       | 1.0                 |

The bathroom gunshot keeps sounding like a bathroom gunshot regardless of where the listener stands — only its loudness changes based on the listener's audibility to the bathroom. Two different voices in two different zones send to two different reverb buses, both running simultaneously, each carrying its own room's character.

### 15.4 The ReverbSendBus Asset

One ScriptableObject per acoustic space identity in the project. Create via Project ▸ Create ▸ Audio System ▸ Reverb Send Bus, name it after the room (e.g. `Reverb_Bathroom`).

Three layers of fields:

**Mixer wiring** (top of inspector):

| Field            | Purpose                                                                                                  |
|------------------|----------------------------------------------------------------------------------------------------------|
| `ReverbMixer`    | The voice mixer this bus lives on. Required — the bus's mixer group is auto-created under this asset.    |
| `ReverbBus`      | Auto-filled by Generate. The mixer group this SendBus owns. Leave null on first authoring.               |
| `OutputDestination` | Optional. The mixer group this bus's wet output routes to. Vestigial in single-mixer setups; left null is normal. |
| `ParentGroup`    | Optional. Drops the auto-created group under this parent instead of directly under master. The "ReverbsWet" return-bus convention. |

**Parametric reverb defaults** (the SFX Reverb effect's 14 parameters, split into Basic and Advanced):

- **Basic (4)**: `DryLevel`, `Room`, `DecayTime`, `ReverbLevel` — the parameters 80% of tuning happens on.
- **Advanced (10)**, behind an EditorPrefs-backed foldout that's closed by default: `RoomHF`, `RoomLF`, `DecayHFRatio`, `ReflectionsLevel`, `ReflectionsDelay`, `ReverbDelay`, `HFReference`, `LFReference`, `Diffusion`, `Density`.

These parametric defaults apply only when `Use Convolution` is **off**. When it's on, the bus ignores them and uses the impulse response instead.

**Convolution** (the alternative to the parametric reverb — see §15.14 for the full walkthrough):

| Field                   | Purpose                                                                                                  |
|-------------------------|----------------------------------------------------------------------------------------------------------|
| `Use Convolution`       | Off by default. When on, the bus uses a real impulse response (native convolution plugin) instead of the parametric SFX Reverb. The parametric fields above are ignored. |
| `Impulse Response`      | The IR `AudioClip` to convolve with. Must be CPU-readable — set its import **Load Type** to *Decompress On Load* or *PCM*. Mono or stereo (downmixed to mono in v1). Required when `Use Convolution` is on, or the bus is silent. |
| `Convolution Wet Trim`  | Wet output trim in dB (range -80…+20). 0 = unity. The live, cheap level control for the convolution wet path. |

A fourth convolution field, the IR *slot index*, is auto-assigned by Generate and hidden from the inspector — designers never set it.

The asset's **name is the bus id**. Sanitization strips characters that would produce invalid Unity exposed-parameter identifiers; a bus named `Cave (small)` becomes `Cavesmall` for parameter naming. Rename the asset and the bus identity follows.

### 15.5 The ReverbSendBusRegistry Asset

One per project. A flat list of every `ReverbSendBus` asset in the project, used by:

- The runtime drivers, to enumerate which buses exist and which mixer parameters to write to.
- The Occlusion Layout Builder, to author one Send effect per registered bus on every occlusion slot.

Create via Project ▸ Create ▸ Audio System ▸ Reverb Send Bus Registry. Open the Reverb Send Buses window (Window ▸ Audio System ▸ Reverb Send Buses) and click Refresh — the registry auto-populates from every `ReverbSendBus` asset in the project.

Drop the registry into `AudioManager` ▸ Reverb Send Bus Registry. The runtime gates the reverb-sends driver on the registry being assigned and non-empty.

### 15.6 Authoring Workflow (ReverbAutoCreator + Reverb Send Buses Window)

Two complementary editor UIs:

**Per-asset inspector** — select a `ReverbSendBus` asset to see the custom inspector. Four buttons:

| Button                    | What it does                                                                                                            |
|---------------------------|-------------------------------------------------------------------------------------------------------------------------|
| **Generate Mixer Group**  | Creates or finds the bus's mixer group and backfills `ReverbBus` on the SO. For a **parametric** bus: drops an SFX Reverb effect, writes the SO's parametric defaults to the target snapshot, and exposes the six runtime-driven parameters under schema names. For a **convolution** bus (`Use Convolution = on`): drops the native SFX Convolution Reverb plugin instead, assigns a free IR slot, and authors its IR Slot / Wet Trim / IR Gain params. Switching the toggle and re-generating auto-cleans the previous effect. Idempotent. |
| **Validate Wiring**       | Read-only health check. Reports "Wiring OK" or a bullet list of issues (missing mixer, missing effect, missing exposed param, mismatched OutputDestination, ParentGroup mismatch). |
| **Apply Params → Mixer**  | Pushes the SO's parametric values into the existing mixer effect without re-running the group/expose work. Use after tweaking parametric values on the SO that you want reflected on the mixer side. |
| **Pull Params ← Mixer**   | Copies the mixer effect's current values back onto the SO. Use after tweaking the mixer-window sliders that you want reflected on the SO side. |

**Project-wide window** — Window ▸ Audio System ▸ Reverb Send Buses:

| Button                            | What it does                                                                       |
|-----------------------------------|------------------------------------------------------------------------------------|
| **Create New Bus**                | Save File panel; creates a fresh `ReverbSendBus` asset at the chosen path.        |
| **Refresh**                       | Re-scans the project for SendBus assets and re-runs Validate on each.             |
| **Validate All**                  | Same as Refresh but with a summary HelpBox.                                       |
| **Generate All Missing**          | For every bus whose `ReverbBus` is null but whose `ReverbMixer` is assigned, runs `EnsureSendBus`. Buses with `ReverbBus` already filled are left alone (per-asset re-generation lives on the inspector). |

Each row in the list shows the bus's name, its assigned Mixer, its assigned Bus group (or `(not generated)`), and any Validate issues (collapsible).

### 15.7 Six Exposed Parameters, Not Fourteen

Unity's SFX Reverb effect has 14 parameters. Generate exposes six:

| Suffix              | Parameter                  | What it drives                                      |
|---------------------|----------------------------|-----------------------------------------------------|
| `_Wet`              | `Reverb` (late reverb dB)  | The diffuse tail level                              |
| `_Decay`            | `Decay Time` (seconds)     | Reverb tail length                                  |
| `_Room`             | `Room` (dB)                | Overall wet-signal gain                             |
| `_RoomHF`           | `Room HF` (dB)             | High-frequency tilt on the wet path                 |
| `_DecayHFRatio`     | `Decay HF Ratio` (ratio)   | How fast highs decay relative to mids               |
| `_Reflections`      | `Reflections` (dB)         | Early reflections gain                              |

These match the 1:1 field set on `AudioReverbProfile` — they're the six parameters that **describe a room's identity in a way that varies meaningfully between rooms**. Cathedral and bathroom differ on these six.

The other eight (DryLevel, RoomLF, ReflectionsDelay, ReverbDelay, HFReference, LFReference, Diffusion, Density) are static shaping rather than runtime-driven character — they describe *how this reverb is shaped* and stay at the SO-authored snapshot values, not written each tick.

The exposed-parameter names follow the schema `Reverb_<BusName>_<Suffix>`. The constants live on `ReverbSendBus` (`SuffixWet`, `SuffixDecay`, …) so authoring and runtime can't drift out of name agreement.

This whole six-parameter mechanism applies to **parametric** buses only. A convolution bus exposes no SFX Reverb params (its character is the impulse response) and is skipped by the listener-side driver — see §15.14.

### 15.8 The AudioZone Side

The zone's connection to the reverb subsystem is **routing only** — a single field:

```csharp
public AudioMixerGroup ReverbBus;       // routing target (source-side)
```

- **`ReverbBus`** is the mixer group voices physically in this zone send to (when their container has `Allow Reverb Send = ✓`). Drag in the `ReverbBus` field from a `ReverbSendBus` asset. Leave null for zones that don't have a dedicated reverb (the source-side send is then skipped for sources in that zone).

> **Source-of-truth note (changed 2026-05-21).** The zone no longer carries any reverb *character* — the old `AudioZone.ReverbProfile` field was removed. A bus's character lives entirely on its `ReverbSendBus` asset, which is now the single source of truth. To make a room "sound reverberant," tune the parameters (or assign an IR) on the bus asset, not on the zone. The zone only decides *which* bus voices route to (and, via `entryFadeMeters`, how that send fades across the zone boundary).

Multiple zones can feed the same bus (e.g. `Cathedral` and `Cathedral_Crypt` both pointing at `Reverb_Cathedral`) — useful for routing several rooms to one shared acoustic identity. Because character is now per-bus, **every zone feeding a given bus produces that bus's single character**; there is no per-zone variation on a shared bus. If you need two rooms to sound different, give them separate bus assets.

### 15.9 The Source-Side Runtime: `AudioManager.ReverbSends`

The "which bus, how loud" half. Runs at `reverbSendsUpdateInterval` (default 50 ms = 20 Hz) from a coroutine alongside the listener-side driver. Per tick, per voice with a slot:

1. **No container or `AllowReverbSend = false`**: every authored send on this slot gets silenced (so stale levels from a prior tick or prior voice don't leak).
2. **`ExplicitReverbBus` set**: the explicit-bus short-circuit. The voice sends at its container's `ReverbSendLevelDb` to the explicit bus only; all other registered buses get silenced. Use for sounds that need fixed acoustic character regardless of where the listener stands — music, narrator VO, scripted UI tails, cathedral choir always sounding like a cathedral.
3. **Otherwise — zone-driven routing**:
   - Resolve the source's current zone (cached for static emitters, re-resolved each tick for movers).
   - Look up listener audibility to that zone from the propagation cache: same-zone = 1.0, through portals = the linear-amplitude chain product, unreachable = 0.
   - Fold in source membership (`AudioZone.GetMembershipFactor`) so voices near a zone's surface taper smoothly across the boundary instead of flipping.
   - For each registered bus, compute `db = baseDb + 20·log10(audibility × membership)` if and only if the source's zone feeds *this* bus; else write the silent floor (-80 dB).

The per-tick `AudioMixer.SetFloat` on the slot's `SendLevelParams[bus.BusName]` writes the result.

**Immediate-on-Play write**: `AudioContainer.ConfigureAudioSource` calls `WriteReverbSendsImmediate` synchronously, so a voice's first audio frame already carries correct reverb routing. Without this, transient sounds (gunshots, single footstep clicks) on static emitters would play dry for up to one driver tick.

### 15.10 The Listener-Side Runtime: `AudioManager.ReverbBusParams`

The "what does each bus sound like" half. Same coroutine, same cadence. Per tick, per registered bus:

1. **Skip convolution buses** — their character is the impulse response, not parametric params (the six `Reverb_<Bus>_*` params aren't exposed on them).
2. **Read the bus's own character** from its `ReverbSendBus` asset via `bus.GetDefaultProfile(scratch)` into a non-allocating scratch profile. No zone lookup happens — the asset is the source of truth.
3. **Write six `AudioMixer.SetFloat`s** to the bus's exposed parameters (`Reverb_<Bus>_Wet`, `_Decay`, `_Room`, `_RoomHF`, `_DecayHFRatio`, `_Reflections`).

Each bus has one stable acoustic identity that never depends on listener position — only the source-side audibility (loudness) changes when the listener moves. Re-driving every tick (rather than once) is belt-and-suspenders against exposed-param fallback ambiguity; it's six `SetFloat`s per parametric bus, negligible for a handful of buses.

> **Changed 2026-05-21.** This driver used to resolve a "canonical zone" per bus (listener's zone, else first-registered via `FindFirstZoneFeedingBus`, else SO defaults) and write *that zone's* `ReverbProfile`. The source-of-truth unification replaced all of that with the unconditional `bus.GetDefaultProfile` read above. `FindFirstZoneFeedingBus` is no longer used by this path.

### 15.11 Container Opt-Ins, Revisited

The container flags that interact with this subsystem (defined in chapter 14, repeated here for context):

| Container flag              | Effect on the reverb-send path                                                                |
|-----------------------------|-----------------------------------------------------------------------------------------------|
| `Allow Reverb Send`         | Master opt-in. When off, voices from this container never send to any reverb bus.             |
| `Reverb Send Level Db`      | Per-container baseline level (dB) for the send. 0 dB = "as loud as dry", -∞ dB ≈ silent.      |
| `Static Emitter`            | Optimization: skip the source-zone resolve every tick for non-moving voices.                  |
| `Explicit Reverb Bus`       | Override the zone-driven routing entirely. Voice always sends to this bus at the authored dB. |

The `Reverb Send Level Db` slider on the container is the right place to dial individual sounds in or out of the wet mix without touching the zone's character — gunshots usually want a healthy send (0 to -3 dB), footsteps usually want quieter (-12 to -20 dB), UI clicks want either no reverb at all (`Allow Reverb Send = off`) or a tight UI-only reverb via `Explicit Reverb Bus`.

### 15.12 Performance

- **Reverb-sends driver cost**: O(voiceCount × busCount) per tick. Default 20 Hz × 32 real voices × (say) 5 buses = 3200 `SetFloat`s/sec. Negligible.
- **Bus-params driver cost**: O(busCount) per tick — six `SetFloat`s per parametric bus, convolution buses skipped, no zone scan (the old `FindFirstZoneFeedingBus` walk was removed in the source-of-truth unification). 5 buses × 20 Hz ≈ 600 `SetFloat`s/sec. Negligible.
- **Static-emitter cache**: `voice.CachedSourceZone` avoids the O(zoneCount) `GetZoneContainingPoint` walk every tick for voices marked `StaticEmitter`. Footsteps parented to the player don't get this — moving emitters re-resolve every tick.
- **`reverbSendsUpdateInterval`** (default 0.05 s = 20 Hz) trades responsiveness for CPU. Drop to 0.02 s (50 Hz) only if you have fast projectiles crossing zone boundaries and have measured the CPU is fine.

### 15.13 Design Limits

1. **One reverb effect per bus.** The schema assumes a single SFX Reverb on each generated mixer group. Stacking multiple reverbs on a bus is possible but not surfaced through the SO; you'd lose the Apply/Pull round-trip with the SO and the auto-exposed parameter set.
2. **Six driven parameters, eight static.** If you need `Diffusion` or `Density` to vary per-room, you'd extend `AudioReverbProfile` and add new `Suffix*` constants to `ReverbSendBus`. The architecture supports it; v1 just doesn't ship it.
3. **One character per bus.** A bus has a single acoustic identity (its `ReverbSendBus` asset). Several zones can route to one bus, but they all get that one character — there is no per-zone variation on a shared bus, and no mixing-by-distance between zones. If two rooms must sound different, author two bus assets.
4. **Convolution is Windows-only and in beta.** The native convolution path (§15.14) ships for Windows x64 only — macOS and consoles are Phase 4. It's feature-complete and build-validated for that scope, but carries known caveats: no runtime IR swap (the IR is fixed at author/scene-load time), ambient emitters can't render convolution (they fall back to inert parametric defaults — §15.14), and the convolver rebuilds on the audio thread (fine at load time, not yet ready for in-game IR changes).

### 15.14 Convolution Reverb (Windows, beta)

Convolution is the **alternative engine** for a reverb bus. Instead of Unity's parametric SFX Reverb (which approximates a room from a handful of knobs), a convolution bus convolves the dry send with a real **impulse response** (IR) — a recording of how an actual space (or an external hardware/plugin reverb) responds to an impulse. This captures the true character of cathedrals, stairwells, parking garages, or a favorite Lexicon patch in a way the parametric reverb can't.

It's an **opt-in, per-bus** choice: parametric stays the cheap default for ordinary zones; convolution is the path for hero spaces.

> **Status: beta, Windows x64 only.** Feature-complete and validated in a standalone Windows build, but see the caveats at the end of this section before relying on it. On every other platform a convolution bus is silent; see [Build Compatibility](https://peppersfx.com/docs/build-compatibility/).

**When to use which:**

| Use parametric (SFX Reverb)                       | Use convolution                                            |
|---------------------------------------------------|------------------------------------------------------------|
| Generic / cheap zones, lots of them               | Hero spaces where the room's identity matters              |
| You want to tune by ear with knobs                | You have (or can capture) a real IR of the space           |
| Cross-platform today                              | Windows only for now                                       |
| Live parameter changes are fine                   | IR is fixed at author/scene-load time (no in-game swap)    |

**Authoring a convolution bus:**

1. On the `ReverbSendBus` asset, tick **Use Convolution**. The parametric fields are ignored from here on.
2. Assign an **Impulse Response** clip. Set its import **Load Type** to *Decompress On Load* or *PCM* so the CPU can read its samples — without this the runtime upload fails (`GetData failed`). Mono or stereo (downmixed to mono in v1); ~4 s at 48 kHz is a typical ceiling for SFX.
3. Set **Convolution Wet Trim** (dB) to taste — this is the live, cheap level control for the wet path.
4. Click **Generate Mixer Group** on the asset. This drops the native *SFX Convolution Reverb* plugin on the bus group (instead of SFX Reverb), assigns the bus a free IR slot, and authors the plugin's IR Slot / Wet Trim / IR Gain params.
5. **Wire the send path** the same way as a parametric bus: run the Occlusion Layout Builder's **Auto-Create** so each slot gets a Send and the bus group gets a Receive. *Without this the bus is silent with no error* — see §15.6 / the workflow note. (This step is identical for parametric and convolution buses; convolution didn't change the send/receive plumbing.)

**Runtime behavior:** the IR samples are uploaded into the plugin's slot table at `AudioManager` startup (`UploadConvolutionIRs()` in `Awake`). The slot table is volatile, so the IRs re-upload cleanly on every play / scene reload. The authored slot index + Wet Trim / IR Gain params live in the mixer asset; the IR *samples* come from this runtime upload. Nothing depends on driving exposed params from script at runtime.

**Requirements:** the native plugin `SFXConvolutionReverb.dll` ships under `RunTime/Plugins/Windows/x86_64/` with **Load on startup** ticked in its import settings. Leave it on: without it the effect never registers in the mixer, and nothing warns you. The plugin runs on 64-bit Windows only; see [Build Compatibility](https://peppersfx.com/docs/build-compatibility/) for what happens on other platforms.

**Caveats (beta):**

- **No runtime IR swap.** The IR is fixed once uploaded. Changing IRs during gameplay (zone-driven IR selection, crossfade) is Phase 4 and requires moving the convolver rebuild off the audio thread first.
- **Ambients can't render convolution.** `AmbientEmitter` uses a per-source *parametric* `AudioReverbFilter`, not the convolution plugin. An ambient whose listener-zone routes to a convolution bus gets that asset's (inert) parametric defaults — **not** the impulse response. Treat ambients as parametric-only for now, or route them through the bus's send/receive.
- **Convolver rebuild is on the audio thread.** Fine because IRs only (re)assign at author / scene-load time, where the one-time hitch is inaudible. It would glitch if IRs swapped mid-gameplay — hence the no-runtime-swap caveat above.
- **Malformed/empty IR clips aren't fully guarded yet.** Trust your IR clips; a bad clip's behavior is undefined pending an input-validation pass.

### 15.15 Troubleshooting

**"Voices play but no reverb tail."**
- Confirm `Allow Reverb Send = ✓` on the container.
- Confirm the container's `Reverb Send Level Db` isn't at -∞ / -80 dB.
- Confirm `AudioManager.ReverbSendBusRegistry` is assigned and non-empty.
- Confirm the source's zone has `ReverbBus` pointing at a `ReverbSendBus` whose `ReverbBus` (the mixer group) is in the registry.
- Confirm the listener can reach the source's zone (a zone unreachable via portals produces audibility = 0).

**"A bus has no character — no decay, no reflections."**
- Did you run Generate on its `ReverbSendBus` asset? Until you do, the mixer group has no effect on it.
- Click Validate Wiring on the asset. It'll list every missing piece.
- Parametric bus: check the asset's `Room` value — at `-10000` mB the reverb is silent. Drag it toward 0 (the default).
- Convolution bus: check it has an `Impulse Response` assigned and that the clip is CPU-readable (Load Type = Decompress On Load / PCM). See §15.14.

**"The bus sounds like the wrong room."**
- Character comes from the bus's own `ReverbSendBus` asset, not from any zone, so "wrong room" means the wrong *asset* is wired. Confirm the zone's `ReverbBus` points at the bus group you think it does, and that you tuned (or assigned the IR to) that same asset.
- Remember several zones routing to one bus all share that bus's single character — that's by design, not a bug.

**"After re-generating, my mixer-window manual tweaks were wiped."**
- Generate runs `WriteParametricDefaults`, which pushes the SO's values into the mixer effect's target snapshot. If you've been tuning in the mixer window directly, run **Pull Params ← Mixer** *before* the next Generate to bring the SO into sync. After that, Generate is non-destructive — it writes back what's already there.

**"Voices in zone A still send to bus A's reverb after I changed zone A's `ReverbBus`."**
- The reverb-send driver re-resolves source zones every tick (or once-on-acquire for static emitters). Static-emitter voices in flight at the moment of the change still hold their cached zone. Stop and re-play them, or set `Static Emitter = ✓` only on voices that genuinely don't change zones.

**"Pool exhaustion warning on a bus that previously worked."**
- Slot pool exhaustion is the same warning shape from chapter 14 — see that troubleshooting block. Reverb-send voices and occlusion voices share the same per-bus slot pool, so a `weapons` bus configured for 6 slots can handle 6 *combined* occluded-or-reverb-sending voices, not 6 of each.

## Audio Loading & Memory

Source: https://peppersfx.com/docs/manual/audio-loading-memory/

This chapter covers **how clip audio gets into memory and onto a voice** — the RAM footprint of your audio and when the cost of loading it is paid. It's entirely opt-in and tiered. The API surface lives in [API_REFERENCE.md → Loading](https://peppersfx.com/docs/api/loading/).

### 16.1 Do I even need this?

| Your situation | What to use | Extra package? |
|---|---|---|
| **Small / medium game** | Nothing — clips are direct references and load with the project (the default). **Skip this chapter.** | — |
| **Lots of audio, occasional hitches on first play** | The **Warmer** (§16.4) — front-load clip data on your schedule. | No |
| **Open-world / live-service, RAM is the constraint** | The **Addressables backend** (§16.5) — load/unload a region's audio by zone. | `com.unity.addressables` |

Nothing here changes behavior for a project that doesn't opt in. The default path — direct `AudioClip` references resolved synchronously — is unchanged and zero-overhead.

### 16.2 The three layers

Cheapest first. Each is independent; you can use one without the others.

```
1. Import policy   — per-category Load Type / compression. Sets each clip's RAM footprint.   (automatic)
2. Warming         — pre-load a clip's audio DATA ahead of first play, to kill the hitch.     (no package)
3. Addressables    — load/unload the clip OBJECTS themselves by region, so only the current   (gated package)
                     zone's audio is resident.
```

The distinction between layers 2 and 3 matters: **warming** loads the *audio data* of a clip you already hard-reference (the object is already in memory); **Addressables** controls whether the clip *object* is in memory at all. Warming reduces hitches; Addressables reduces peak RAM.

### 16.3 Import policy (automatic)

The editor import pipeline (`Editor/AudioImport/`) stamps each clip's import settings from its **category preset** (`CategoryPreset.GetDefault`). You don't configure it per clip — you pick the category:

| Category | Load Type | Compression | Preload Audio Data | Why |
|---|---|---|---|---|
| UI | Decompress On Load | PCM | yes | tiny, fired often — cheapest to play |
| SFX | Decompress On Load | ADPCM | yes | short, fired often/overlapping |
| Music | **Streaming** | Vorbis | no | one instance, long — don't hold PCM in RAM |
| Ambience | **Streaming** | Vorbis | no | few instances, long |
| Dialogue | Compressed In Memory | Vorbis | no | many lines, decode on demand |

**Your project's settings.** The presets live in an **Audio Import Settings** asset in your project (Create ▸ Audio System ▸ Import Settings, anywhere under Assets). Until you make one, the code defaults above apply. The package ships none: an installed package is read-only, so one there couldn't be saved. With more than one, the first by path is used and the Console says which.

**Folder rules.** In the settings asset's **Folder Rules**, each rule is a name (its own category: "Engine loops", "Tyres"), a folder, whether it covers the folders below, and import settings. A clip imported into that folder **for the first time** gets the rule's settings, so engine loops dropped into `Assets/Audio/Cars/Engines` come in mono and Decompress On Load without a trip to the Import Manager. The most specific folder wins. Clips already in the project keep their settings, even when they are reimported, so a hand tweak is never undone; **Apply to Existing Clips** on a rule re-applies it. With no rules, imports are Unity's as before.

**The one authoring rule that bites people:** Streaming is **per-instance expensive** — a stream buffer plus disk reads *for every playing voice*. Right for music and long ambience (one or a few instances); **wrong** for a footstep or weapon pool firing many overlapping instances (many disk-streaming voices seeking at once → hitch). The presets already encode the right choice; the mistake is manually setting a short, frequently-fired SFX to Streaming.

| Load Type | RAM | Per-instance cost | Use for |
|---|---|---|---|
| Decompress On Load | high (full PCM) | cheapest | short SFX fired often — footsteps, gunshots |
| Compressed In Memory | medium | decode per play | many medium-length variants |
| Streaming | ~none (reads disk while playing) | stream buffer + disk seek **per voice** | music, long ambience — **one/few instances only** |

### 16.4 Warming (no extra package)

Categories with `Preload Audio Data = false` (Music/Ambience = Streaming, Dialogue = Compressed-In-Memory) load their audio data on **first play**, which hitches. The **warmer** front-loads that cost on *your* schedule — e.g. on zone-enter or level-load — operating on the clips you already hard-reference, with no Addressables dependency.

```csharp
// On zone-enter / level-load, before the sound is needed:
AudioManager.Instance.WarmContainer(zoneAmbienceContainer); // warms all its clips (recurses Switch/Blend)
AudioManager.Instance.WarmClip(clip);                       // a single clip
AudioManager.Instance.WarmClips(clipList);                  // a set, loaded in parallel
```

- `AmbientSource` warms its loop clip **automatically** on register, so an ambient bed that fades in is typically warm by the time it's audible.
- Biggest win for **Dialogue** (Compressed-In-Memory — decoding a line otherwise hitches) and the **Ambience first-play**. For pure **Streaming** clips the gain is smaller — they stream at play regardless.
- Finer control than the all-or-nothing `Preload Audio Data` import flag: you warm exactly the clips you're about to need, when you choose.

> **Addressables blind spot:** the warmer operates on **direct, hard-referenced** clips only. An addressable-authored entry (null clip + address) is invisible to it. Its loading is owned by **bank preload** (§16.5), which loads both the clip and its audio data, so it doesn't need the warmer. Don't expect `WarmContainer` to warm converted (addressable) content.

`AudioClipWarmer.Unload` exists but is blunt — it frees the data with **no check for live voices**. Only unload data you know nothing is playing. Safe, refcounted residency (that never unloads a clip under a playing voice) is what the Addressables backend adds.

### 16.5 Addressables backend

Requires **`com.unity.addressables`**. This loads and unloads the clip *objects* themselves by region, so only the current zone's audio is resident. The assembly (`SFXSystem.Addressables`) compiles automatically when the package is present; without it, everything here is dormant and the project runs on direct references — exactly like the netcode adapters (§17).

**Setup:**

1. **Install** `com.unity.addressables` (Package Manager). The `SFXSystem.Addressables` assembly compiles automatically when present.
2. **Mark the region's clips Addressable** and give them a shared **label** (e.g. `zone_crypt`) — easiest with the Authoring window (§16.6), which puts them in the label's own group, `Audio zone_crypt`, with one bundle per clip. By hand in the Addressables Groups window, **don't put every zone's clips in one group** with the default Bundle Mode (Pack Together): Unity unloads a bundle only as a whole, so leaving a zone would free nothing while you stand in another. Give each zone its own group, or set the group's **Bundle Mode** to **Pack Separately** (one bundle per clip). Pack Separately also frees the rest of a zone's clips while one of them, say a loop, plays on across the border. Measured in a test build with three zones: with Pack Separately, 7–11 MB of audio was loaded in any one zone against 26 MB for all three; with one shared group, every zone walked through stayed loaded, as much as loading all three up front.
3. **Author the container entries as addressable.** Easiest is the **Addressable Audio Authoring** window (§16.6): select the containers, pick the label + address style, hit Convert. By hand: set each entry's **address** to the clip's Addressable address, exactly as the Addressables Groups window shows it, and its **clip** to **None**. Use the address, not the asset GUID (unless the address *is* the GUID): a zone bank loads its clips by address, and an entry keyed any other way never loads and stays silent. The Loading Validator flags such keys as unregistered. *Per entry it's either a direct clip or an address — a populated clip would eager-load and defeat the point.*
4. **Add a `Zone Audio Bank`** component to the AudioZone's GameObject (Add Component ▸ *Audio ▸ Loading ▸ Zone Audio Bank*) and set its **Bank Label** to the label from step 2.
5. **Put one `Addressable Audio Runtime`** component in your first scene (Add Component ▸ *Audio ▸ Loading ▸ Addressable Audio Runtime*); a bootstrap scene is ideal. It starts the backend, which installs the addressable clip source and preloads/releases each zone's bank as the listener enters/exits. The backend **persists across scene loads**, so you need only one. A runtime in a later scene finds it already running, logs that, and does nothing (the first runtime's settings apply).

Now a zone's clips **load on enter** and **unload (after a short linger) on exit**. A clip still playing when you leave a zone stays resident until the voice finishes — **no mid-play unload**, including across a scene load. When a scene unloads, its zones count as exited, so their banks release normally. After teleporting the listener, call `PropagationManager.ResyncListenerAfterTeleport()`: the zones you left release their banks, and the ones you land in load theirs.

**Voice-safe residency (the important part).** A zone's bank releasing on exit does **not** immediately unload a clip a voice is still playing — a looping ambience, or a one-shot tail ringing out as you cross the border. Residency is refcounted across three holders:

```
clip resident while  (banks holding it)  +  (live voices bound to it)  +  (explicit pins)  > 0
```

The actual unload fires only when that total hits **0**, and then only after a **linger** window (default **5 s**) to absorb zone-border dithering (step out / step back in). A stuck-high refcount is only wasted RAM, never a click — the design deliberately errs toward holding the ref.

**Debug overlay.** Tick **Show Debug Overlay** on `Addressable Audio Runtime` to see each address's `bank / voice / pin / total` refcounts and warm/cold state live during Play. On zone-exit, `bank` drops to 0 but a playing voice keeps `voice ≥ 1`, so the clip stays warm until the voice ends plus linger. Off by default; zero cost when off.

**Addressable ambiences.** `AmbientSource` can be addressable too: set its **Looping Clip Address** and leave **Looping Clip** empty. The source **pins** the clip loaded for its active life (the `pin` refcount), so it's ready even when the ambience is heard through a portal *before* you enter the zone. Its resolved clip (null while an addressable clip is still loading) is exposed as `PlayableClip`; propagation reads that and defers until it's ready.

### 16.6 Authoring window — convert clips in one click

**Window ▸ Audio System ▸ Addressable Audio Authoring** does the whole "mark addressable + set address + assign label + null the direct clip" in one click, across Random / Sequence / Routing containers, and keeps the groups tidy afterwards — no Groups-window round-trip. It has two tabs.

**Convert Containers**

1. **Select** one or more AudioContainer assets in the Project.
2. Set options (all in-window):
   - **Bank Label** — dropdown of existing labels, plus *New label…*. This is the bank a `ZoneAudioBank` loads. Optional.
   - **Group** — *Bank's own group* (the default) puts the clips in `Audio <label>`, made on first use with one bundle per clip, so a zone's clips unload when the listener leaves (§16.5 step 2). You can also pick an existing group or *New group…* (also one bundle per clip). If the group you pick packs everything into one bundle and already holds another bank's clips, the window warns you. It also warns when the group isn't in builds (a blank group made in the Addressables Groups window, or one with **Include in Build** off): its clips would play in the editor and be missing from a build.
   - **Address Style** — how the key reads: *Label-scoped* (default) `<label>/<clip>` e.g. `Zone_Crypt/Add-S_1` (readable + organized); *Plain name* `Add-S_1`; *Asset path* `Assets/Audio/Add-S_1.wav`; *GUID* (rename-proof, unreadable). Collisions auto-resolve with a numeric suffix (`…_2`).
3. **Convert to Addressable** — marks each clip addressable (into the group, labeled), writes the readable address onto the container entry, nulls the direct clip. Undo-able for the containers; the Addressables entries stay.
4. **Revert to Direct** — relinks the direct clips from their addresses and clears the addresses. Assets stay marked Addressable by default; tick **Revert: also remove from Addressables** (with a confirmation) to fully un-addressable them — only safe when nothing else uses those addresses.

**Clips added later.** Add the clip to the container as a normal clip, select the container, and Convert again: only the new entries are converted. When the selected containers already have addressable clips, the tab shows their group and label, with a **Use** button, so the new clip joins them.

> Convert skips entries that are already addressable (clip already null). To re-address with a different style, **Revert first, then Convert**. The window logs what it touched.

**Groups**

Pick a group to see its audio clips, each marked **used ×N** or **unused**. Used means a container asset, or an `AmbientSource` in an open scene, points at the clip's address. Scripts, prefabs and closed scenes aren't searched, so check before removing an "unused" clip one of those plays.

- **Add Selected Clips** — puts the AudioClips selected in the Project into the group, with the chosen **Bank Label** (it starts as the label the group's clips share) and the Address Style from the other tab. Use it for a clip that isn't in a container, such as an ambience's loop: paste its address (the **Copy** button) into the AmbientSource's **Looping Clip Address**.
- **Remove** (per clip) and **Remove Unused** — take clips out of Addressables to clear out old ones. The clip assets stay in the project. A removed clip that something still points at goes silent; the confirmation names who. Ctrl+Z doesn't undo it: add the clip again instead.
- **Pack Each Clip Separately** — shown when the group packs several banks into one bundle (for example after converting every zone into the Default Group). It switches the group to one bundle per clip. Rebuild the Addressables content afterwards.
- **Include in Builds** — shown when Addressables leaves the group out of builds: it has no Content Packing & Loading schema (a blank group made in the Addressables Groups window), or its **Include in Build** is off. Its clips play in the editor but play nothing in a build, and Addressables only mentions it while building. The button gives the group the Default Group's build settings it lacks (one bundle per clip) and switches Include in Build on. Leave it if you keep the group out of builds on purpose.

A clip asset you delete from the project leaves its Addressables group by itself, so there's nothing to clean up for those.

### 16.7 Diagnostics

- **Precise miss warnings.** An address that can't resolve — **no backend active**, a **typo**, or an **unregistered** key — logs a precise, clickable, **once-per-address** warning instead of dropping silently. (An *expected* cold-drop — backend active, clip simply not preloaded yet — is not warned.)
- **Loading Validator.** **Window ▸ Audio System ▸ Loading Validator** → **Validate** scans every container asset and the open scene's `AmbientSource`s and reports: an address but no backend; an unregistered / typo'd address; an entry with *both* a clip and an address; addressable content but no `AddressableAudioRuntime` in the scene. Each finding has a **Select** button. The validator uses reflection, so it runs **even without the Addressables package installed**.

### 16.8 How it works (architecture)

Same dependency-inversion pattern as the netcode layer: a small seam in the core, with the package-specific weight quarantined in a gated assembly.

```
SFXSystem.Runtime
   IAudioClipSource (seam)  ──default──►  DirectClipSource   (returns the serialized clip, sync, zero overhead)
        ▲
SFXSystem.Addressables  (gated by com.unity.addressables)
   AddressableClipSource  ──►  refcounted Addressables load/unload by region
   AudioBank.Preload()/Release()  (a bank = an Addressables label)
```

- **Containers never read `.clip` directly.** They resolve through `AudioClipSources.Active` (an `IAudioClipSource`). The default `DirectClipSource` returns the serialized clip synchronously. The Addressables backend drops in as an alternative source without re-touching a single `Play()` method.
- **An entry holds EITHER a direct `AudioClip` OR an Addressables address string** — never both. The address is the key a bank's label resolves to, as shown in the Addressables Groups window (the GUID only if the address is the GUID). The core stays free of any Addressables type.
- **The play path stays synchronous on the warm path.** `TryGetClip` returns a resident clip instantly; only a *cold* clip returns false and the play is dropped (drop-on-cold, v1). Bank preload keeps zones warm, so ~every play is warm.
- **Voice-level refcount** is taken at the two chokepoints already in the core: `OnVoiceBound` (when `source.clip` is assigned) and `OnVoiceReleased` (when the voice returns to the pool). That's what makes a bank release safe against a playing voice.
- **Zone binding is decoupled.** `PropagationManager` raises `ListenerEnteredZone` / `ExitedZone` events; the Addressables assembly subscribes. Propagation never depends on Addressables, and vice-versa — the dependency is one-way (Addressables → core).

### 16.9 Status & limitations

- **Import policy & Warming:** stable; behavior-neutral for existing projects.
- **Addressables backend:** covers Random / Sequence / Routing per-entry addresses, the `AmbientSource` pin path, diagnostics + validator, and the authoring window. Automated tests cover a playing voice keeping its clip loaded after the zone's bank releases, one clip shared by two zones, linger at zone borders, cold entries, teardown, the backend persisting across scene loads, and zone enter/exit staying paired through teleports and unloaded zones.
- **Cold entries in a Sequence:** a cold entry drops that play, and the sequence stays on it, so the next play tries it again. With Auto Advance the run stops at that entry. Keep the zone's bank loaded before the sequence reaches it.
- **Tested in a player build** (Windows, 6000.0.48f1): three zones, walked in and out. Only the zone you stand in stays loaded, a loop started in one zone keeps playing (and keeps only its own clip loaded) after you walk into the next, and nothing stays loaded outside the zones.
- **Test unloading and memory in a build.** With the default Play Mode Script ("Use Asset Database"), Addressables in the editor loads straight from the AssetDatabase, and releasing a clip never actually unloads it. To see real unloads in the editor, build the content (Addressables Groups window ▸ Build ▸ New Build ▸ Default Build Script) and set Play Mode Script to "Use Existing Build"; rebuild the content after changing it. The memory you save only shows properly in a player build: make a Development Build and watch memory with Unity's Memory Profiler as you move between zones.
- **Out of scope (v1):** drop-on-cold (not defer-and-play-late) — keep zones preloaded; only the clip leaf is lazy (events/containers stay eager); zone-driven banks are one Addressables label per `AudioZone`.

### 16.10 Troubleshooting

| Symptom | Likely cause / fix |
|---|---|
| Addressable sound never plays | The clip is **cold** (its zone bank wasn't preloaded) → drop-on-cold. Confirm a `ZoneAudioBank` with the right label is on the zone and an `AddressableAudioRuntime` is in this scene or an earlier one. Check the entry's key is the clip's Addressables **address**, not its GUID (run the Loading Validator). Watch the Debug Overlay. |
| Addressable sound plays in the editor but not in a build | Its group isn't in builds: no Content Packing & Loading schema (a blank group from the Addressables Groups window) or **Include in Build** off. Addressables only says so while building ("does not have any associated AddressableAssetGroupSchemas"). The Authoring window's **Groups** tab flags the group and **Include in Builds** fixes it (§16.6); then rebuild the Addressables content. |
| `references addressable key '…', but no Addressables backend is active` | No backend installed/active: install `com.unity.addressables` **and** add an `AddressableAudioRuntime`, or assign a direct `AudioClip` to that entry. |
| An entry has both a clip and an address | A contradiction — the populated clip eager-loads. The **Loading Validator** flags it; null the direct clip (or Revert the entry). |
| Clip unloads mid-play / click on zone exit | Should not happen — residency is voice-refcounted. Check you didn't call `AudioClipWarmer.Unload` (blunt) or a raw `Addressables.Release` outside the refcounted source. |
| Load/unload churn at a zone border | Increase **Linger Seconds** on `AddressableAudioRuntime`. |
| Memory doesn't drop when you leave a zone (in a build) | The zone's clips share a bundle with clips still in use: one group for every zone, or a zone's loop still playing in a Pack Together group. The Authoring window's **Groups** tab flags such a group and can switch it to **Pack Each Clip Separately** (§16.6); or give each zone its own group. The Debug Overlay's counts going to 0 only tells you the system let go; the bundle frees when nothing else in it is held. |
| `WarmContainer` doesn't warm my converted content | Warming operates on **direct** clips only; addressable entries are owned by bank preload (§16.4). |
| Footsteps/weapons hitch under load | A short, frequently-fired SFX is set to **Streaming** — a per-voice disk stream. Set it to Decompress On Load (§16.3). |
| Addressable ambience silent until I enter the zone | Set the `AmbientSource`'s **Looping Clip Address** (leave **Looping Clip** empty) so it *pins* the clip. |

## Multiplayer (Netcode)

Source: https://peppersfx.com/docs/manual/multiplayer-netcode/

Multiplayer support lets you **post a sound on one player's machine and have every player hear it** — without your audio code knowing which netcode stack the project uses, and without changing anything about how local audio works. The API surface lives in [API_REFERENCE.md → Netcode (Multiplayer)](https://peppersfx.com/docs/api/netcode-multiplayer/).

**Applies to:** `SFXSystem.Netcode` (Phases 0–7). **Verified backends:** FishNet v4 (Phases 0–7 on one PC and on two PCs over a real network) · Netcode for GameObjects (NGO) 2.x (light testing only so far, not the full check FishNet had; expect rough edges). **Planned:** Mirror · NGO 1.x back-compat · position quantization.

### 17.1 The one thing to understand first

**No audio ever crosses the network.** When you fire a networked sound, all that travels is a tiny **~36-byte descriptor** — "play event #X at position Y (optionally attached to object Z)". Each machine then plays that event **locally** through the normal audio engine. You are syncing *intent*, not *sound*. That's why it's cheap, and why every local feature (occlusion, reverb, propagation, voices) keeps working untouched. Even the musical sync (§17.6) sends only *timing* (tempo + a phase anchor), never samples.

**In one sentence:** *Use `PostNetworkedEvent` instead of `PostEvent` for sounds everyone should hear; everything else stays exactly the same.*

The audio system never references a netcode package. You install **one** stack (NGO, FishNet, …) and the matching **adapter** lights up automatically. A backend you didn't install never compiles, so it can never break your build.

### 17.2 How it works

```
   PostNetworkedEvent("door_open", pos)
            │
            ├─ plays LOCALLY right now  ──────────────►  you hear it instantly (local echo)
            │
            └─ Broadcast(descriptor) ─► [adapter RPC] ─► server ─► other clients
                                                                      │
                                                         PostEvent(id, pos) on each
```

- **Local echo:** the instigator plays the sound immediately (zero network latency); only *other* peers get it over the wire. No double-play.
- **Authority:** server-authoritative relay — the client sends to the server, the server validates and relays to everyone else. (The adapter implements this; the core doesn't care.)
- **Identity on the wire:** each `AudioEvent` has a **stable ID** (a build-deterministic number derived from the asset's GUID). Both ends resolve the same ID to the same event. *Events must have a captured ID to be networkable* — see §17.3 step 2.
- **Seclusion:** delete the whole `Netcode` folder and your single-player game compiles and behaves identically. Networking is purely additive.
- **Leaving it out without deleting it:** add `SFXSYSTEM_DISABLE_NETCODE` to **Project Settings > Player > Scripting Define Symbols**. Every multiplayer assembly (the core, its editor tools, its tests and the FishNet, NGO and Mirror adapters) is then left out of the build, so none of its code or statics reach your game, and updating the package doesn't bring the folder back. Nothing else changes. Useful when your game does its own networking (a racing game that sends car state, not sound events).

| Layer | What it does |
|---|---|
| `SFXSystem.Runtime` | The audio engine. Knows nothing about networking. |
| `SFXSystem.Netcode` (core) | The agnostic contract: payload, transport interface, router, replicator, clock/transport, and the `NetworkedAudioManager` façade. References Runtime only. |
| `SFXSystem.Netcode.Ngo` / `.FishNet` / … | One tiny adapter per backend — the *only* code that references that stack. Auto-enabled when its package is installed. |

### 17.3 Quick Start

**Step 1 — Install a netcode backend.** NGO: Package Manager → *Netcode for GameObjects*. FishNet: import from the Asset Store. The matching adapter (`SFXSystem.Netcode.Ngo` / `.FishNet`) enables itself. Install only **one** stack.

**Step 2 — Give your events stable IDs.** Open **Window ▸ Audio System ▸ Audio Event IDs** and click **Capture All Missing IDs**. Every event needs a non-zero **Stable ID** to be networkable. Newly created events get one automatically on import; the sweep back-fills older ones.

**Step 3 — Put the transport in your scene.** Create one networked object and add the matching transport component: NGO → `NetworkObject` + `NgoAudioTransport`; FishNet → `NetworkObject` + `FishNetAudioTransport`. **Exactly one** per session, on a persistent networked object (e.g. an `AudioNetwork` GameObject) — **not** on per-player objects. It must be **active** in the scene.

**Step 4 — (optional) Add settings & health-check.** Drop a **`NetworkAudioSettings`** component in the scene to opt into proximity culling, an authority validator, and the clock tunables (§17.5). With none present, sensible defaults apply (validation allow-all, culling off). Open **Window ▸ Audio System ▸ Network Audio Debug** in Play mode to watch live session/clock/loop state.

**Step 5 — Post networked sounds.**
```csharp
using AudioSystem.Netcode;

// Heard by everyone (local echo + relay to others):
NetworkedAudioManager.PostNetworkedEvent("door_open", transform.position);

// Still 100% local — only this client hears it. Unchanged:
AudioManager.Instance.PostEvent("ui_click");
```

With no live session (single-player, not connected), `PostNetworkedEvent` gracefully falls back to a normal local play — so the same call works everywhere.

> **Authoring note:** the per-event **Multiplayer** foldout in the `AudioEvent` inspector (§17.4) only appears once a netcode backend is installed. The fields it exposes live on the Runtime `AudioEvent` and are inert without the `Netcode` layer, so single-player projects stay uncluttered.

### 17.4 Local vs networked — the mental model

| Call | Who hears it | Use it for |
|---|---|---|
| `AudioManager.Instance.PostEvent(...)` | **only this client** | UI clicks, this player's own HUD, anything client-private |
| `NetworkedAudioManager.PostNetworkedEvent(...)` | **everyone** | gunshots, doors, explosions, world sounds all players share |
| `NetworkedAudioManager.PostServerEvent(...)` | **everyone** (from the server) | round-start stingers, objective sounds the *server* decides — no local instigator |

Rule of thumb: if another player should hear it, use `PostNetworkedEvent`. If the **server** is the authority for it (no single client instigated it), use `PostServerEvent`. Otherwise use `PostEvent`.

Every capability below stays descriptor-only — still no audio on the wire.

**Attach a sound to a moving object (emitter binding).** Pass a networked `GameObject` and the sound **follows it on every client** instead of playing at a frozen point:
```csharp
NetworkedAudioManager.PostNetworkedEvent("grenade_bounce", grenade.transform.position, grenade);
```
The object needs a `NetworkObject`. Remote clients resolve its net-id and parent the voice to it; `position` is the spawn anchor **and** the fallback. If the object isn't resolvable yet (its spawn message may still be in flight), the sound is held for a short retry window (~0.5 s), then falls back to the static position — never a frozen sound at the origin, never an error.

**Shared loops you can stop (networked lifetime).** For a sound that must **start and later stop for everyone** — an alarm, a generator hum, a held ambience — use the loop API. It returns a handle:
```csharp
NetworkedSoundHandle alarm = NetworkedAudioManager.PostNetworkedLoop("alarm_loop", pos, alarmObj);
// …later, stop it on every client:
NetworkedAudioManager.StopNetworked(alarm);
```
- A **late joiner** automatically hears loops already running: the server keeps a registry of active loops and replays them to the new client only.
- **Loop sync tiers** control the joiner's phase — authored per-event (Multiplayer foldout, *Loop Sync Tier*): **0 None** (joiner starts from the beginning; everyone free-runs); **1 Aligned at join** (joiner fast-forwards into the shared phase once, then free-runs); **2 Phase-locked** (continuously grid-anchored and gapless — stays in phase across all machines; use for musical/rhythmic loops). Tier 2 **requires variation parity** — leave *Independent Variation* off, or each client phase-locks a *different* clip (the inspector warns). *Only meaningful for a loop that repeats one clip; an auto-advancing Sequence container is meant to free-run (this guard is not yet tested).*

  > **Tier 2 is experimental.** It is still under construction and shouldn't be relied upon in production in its current state. Two-PC testing shows it holding phase with no measurable drift over 15+ minutes, but a **late joiner can play one or two iterations out of phase** (then go briefly silent) before it locks on. Tiers 0 and 1 are unaffected.
- **Off-session** the same calls degrade to a plain local loop; the handle still stops it. Persistence is an **explicit** choice (this API), never inferred from a container's loop flag.

**Same random variant on every client (variation parity).** A `RandomContainer` normally rolls independently per machine. Networked posts force the **same** variant — clip choice *and* the per-voice pitch/volume roll — on every client by default.
```csharp
NetworkedAudioManager.PostNetworkedEvent("footstep", pos);                              // identical everywhere (default)
NetworkedAudioManager.PostNetworkedEvent("crowd_murmur", pos, independentVariation: true); // each client rolls its own
```
`independentVariation` is a nullable bool: `null` (default) uses the event's authored **Independent Variation (default)** flag; `true`/`false` overrides per call. The seed also covers the parts of a post that run later: a Play action with a Delay, and a `SequenceContainer`'s later clips (in Random order too) each get a seed worked out from the post's, so they pick the same variants on every machine. (Before 3.1, a Random-order Sequence past its first entry, and delayed Plays, escaped the seed.)

**Server-authored sounds.** When the **server** is the authority for a sound with no single client instigator, `PostServer*` originates from the server to **everyone**, with **no local echo**:
```csharp
NetworkedAudioManager.PostServerEvent("round_start", Vector3.zero);          // server only — warns + no-ops on a client
NetworkedSoundHandle hum = NetworkedAudioManager.PostServerLoop("reactor_hum", reactorPos, reactor);
NetworkedAudioManager.StopNetworked(hum);                                    // server-authored stop → All
```
Client-instigated relays run through a server-side **authority validator** first (assign `NetworkAudioSettings.ServerValidator` in code); reject → the sound is dropped for others (the instigator still heard its echo). A client can stop only loops it owns; server-authored loops can only be stopped by the server.

**Proximity culling — *don't send*.** With culling on, the server sends a spatial (3D) sound **only to clients whose listener is within its audible radius** — the packet is *never sent* out of range. That halves fanout and closes an audio-wallhack. 2D sounds are never culled.
```csharp
var settings = FindObjectOfType<NetworkAudioSettings>();
settings.ProximityCulling = true;
settings.ListenerPositionProvider = clientId => PlayerPositions.TryGet(clientId, out var p) ? p : (Vector3?)null;
```
Return `null` from the provider when a position is unknown → that client is **not** culled (fail-safe). A null provider makes culling **inert** (the Network Audio Debug window flags this). Active loops are re-evaluated over time (~33 Hz): a listener walking into range starts hearing the loop.

**Per-event reliability.** Every relay is **reliable** by default. Mark spammy positional one-shots (footsteps, full-auto gunfire) **Unreliable Delivery** in the Multiplayer foldout to send them on the unreliable channel (lower overhead, no head-of-line blocking). Loops, stops, snapshots, and scheduled cues always stay reliable.

### 17.5 Per-event authoring (Multiplayer foldout)

Shown in the `AudioEvent` inspector only when a netcode backend is installed:

| Field | Description |
|---|---|
| `Unreliable Delivery` | Relay this event's one-shots on the unreliable channel. |
| `Independent Variation (default)` | Default for `independentVariation` when a post passes `null`. |
| `Loop Sync Tier` | 0 None / 1 Aligned-at-join / 2 Phase-locked (**experimental**, see §17.4). Tier 2 needs variation parity, Max Instances 0 (or at least 3), Cooldown 0, and — for a Routing or Blend that plays several clips at once — clips of equal length. The inspector warns about each. |

`NetworkAudioSettings` (a scene component) holds the culling/clock config and the game-supplied hooks (`ListenerPositionProvider`, `ServerValidator`). See [API_REFERENCE.md → Netcode (Multiplayer)](https://peppersfx.com/docs/api/netcode-multiplayer/) for the full member list.

### 17.6 Musical sync — scheduled & quantized cues

For cross-machine *rhythmic* timing, the layer adds a shared **network clock** (maps network time onto each machine's local audio clock) and an optional **musical transport** (tempo + phase). Cues land together on every machine — the industry transport-and-quantize model, not varispeed.

```csharp
// Fire on a shared network time (each client maps it to its own dsp clock):
double t = NetworkClock.NetworkTime + 0.5;
NetworkedAudioManager.PostNetworkedScheduled("beep", pos, t);

// Server sets tempo once (networked on change, replayed to late joiners):
NetworkMusicTransport.SetTempo(bpm: 128, beatsPerBar: 4);

// Quantize a cue to the next beat/bar of the shared grid:
NetworkedAudioManager.PostNetworkedQuantized("stinger", pos, Quantize.NextBar);
```

- A scheduled cue is clamped to at least a minimum lead ahead (so even a distant client receives it before its onset); one that still arrives late is dropped rather than fired out-of-phase.
- `PostServerScheduled` / `PostServerQuantized` are the server-authored twins.
- A mid-session `SetTempo` change re-anchors **seamlessly at the next bar** of the current grid.
- **Scheduled/quantized cues are global (non-positional) by design** and bypass proximity culling — they're for music, not positional gameplay.
- `NetworkClock.ResyncClock()` forces a hard re-sample after a known hitch.

### 17.7 Per-backend notes

**NGO (Netcode for GameObjects) 2.x** — Adapter `NgoAudioTransport`, gated on `com.unity.netcode.gameobjects` (`SFXSYSTEM_NGO`). In-scene `NetworkObject`s auto-spawn on server start. Late-join snapshot fires from `OnClientConnectedCallback` (NGO has no per-observer hook, so it relies on scene-object sync completing before the callback). Server id is 0 and remote clients start at 1. *NGO has had light testing only; the full Phase 4–7 sweep FishNet had is still to do. It compiles and coexists with FishNet.*

**FishNet v4** — Adapter `FishNetAudioTransport`, gated on the `FISHNET` define. The transport's `NetworkObject` **must be active in the loaded scene** — it only registers once the object network-spawns (if a freshly added object doesn't spawn, save the scene). Late-join snapshot fires from `OnSpawnServer(NetworkConnection)` — per-observer, robust timing. Client ids can start at 0, so server-authored loop ids use a reserved `0xFFFFFFFF` owner namespace (handled for you).

> Run **one** backend at a time. Both adapters can be *present* in the project (each is gated), but you start a session with a single stack.

### 17.8 Current limitations (by design, for now)

- **Networked events should be "play" sounds.** Global state changes (RTPC / Switch / State / ducking) stay **locally driven** by each client's own game logic — networked posting doesn't replicate global audio state. (Variation parity covers randomness *within* a chosen branch, not the switch/state/RTPC input that chooses the branch.)
- **Scheduled / quantized cues are global (non-positional)** and bypass proximity culling by design — they're for musical sync, not positional gameplay.
- **Tier-2 phase-locked loops are experimental** — not for production yet. Known issue: a late joiner can play one or two iterations out of phase before locking on.
- **Tier-2 phase-locked loops are delivered to all peers** (the culler skips them).
- **Cross-machine tightness is bounded by the clock estimate** — quantization buys slot-agreement and drift-immunity, not closeness.
- **Position is full precision** (quantization for smaller packets is a future optimization). **Static / single-context** (one `AudioManager`, one router, one transport per process).
- **Scale.** Built for co-op and competitive sessions, scaling as far as your chosen netcode's authoritative-server model does (typically tens of players). Adds proximity culling but not MMO-grade interest management or sharding; for hundreds+ concurrent players a different replication architecture is required.
- **Breadth still open:** Mirror adapter and NGO 1.x back-compat. The NGO 2.x adapter has had light testing only.

### 17.9 Extending: writing a new backend adapter

1. Create a gated assembly under `Netcode/Adapters/<Stack>/` referencing `SFXSystem.Runtime`, `SFXSystem.Netcode`, and that stack's runtime assembly, constrained on the stack's define symbol.
2. Implement `INetworkAudioTransport` on a networked behaviour: **Play** via the stack's RPCs in `Broadcast`, raise `OnEventReceived` on receipt, marshal the `emitter` GameObject to a net-id and implement `TryResolveEmitter`; **Stop** via `BroadcastStop` → `OnStopReceived`; **Scope `All`** originates directly to all clients + host (never a dedicated server); **Scheduled / transport** implement `BroadcastScheduled` / `BroadcastTransport` and raise `OnScheduledReceived` / `OnTransportReceived` / `OnLoopJoinReceived`, expose `ServerTime` + `RoundTripTime`; **Late join** replays `NetworkAudioRegistry.Snapshot(...)` to a joining client; **Register** with `NetworkAudioRouter.Register(this)` / `Unregister(this)` and pump `AudioEventReplicator.Tick()` + `NetworkClock.Tick()` from `Update`.
3. Relay to everyone **except the sender** (it already played the local echo).

The core and the audio runtime never change.

### 17.10 Troubleshooting

| Symptom | Likely cause / fix |
|---|---|
| Sound plays locally but not on other clients | Transport component missing/inactive, or not on a spawned `NetworkObject`. Check **Network Audio Debug** — is the session Active? |
| `'<event>' has no stable id` warning | Run **Audio Event IDs ▸ Capture All Missing IDs**. |
| Nothing networks at all | Backend not installed, or no `NetworkManager`/transport in the scene. |
| Hearing the sound twice while testing | Multiplayer Play Mode plays *both* virtual players through one set of speakers (a flam). Expected; on real separate machines each player hears it once. |
| A moving sound plays at a frozen point on remote clients | The emitter object has no `NetworkObject`, or isn't spawned/observed on that client — it fell back to the static position. |
| A late joiner doesn't hear a running loop | Only `PostNetworkedLoop` sounds are snapshotted. On NGO, confirm the joiner synced the transport object before the snapshot fired (§17.7). |
| `StopNetworked` doesn't silence remotes | Keep the `NetworkedSoundHandle` from `PostNetworkedLoop` and pass *that* handle. |
| Culling on but everyone still hears everything | No `ListenerPositionProvider` assigned → culling is inert. Network Audio Debug ▸ Config Health flags this. |
| A Tier-2 loop plays a different clip per client | The event has both *Loop Sync Tier 2* and *Independent Variation* on. Turn Independent Variation off (the inspector warns). |
| A Tier-2 loop cuts out after a cycle or two | Each iteration is an ordinary post of the event, and they overlap. Max Instances 1–2 steals an iteration; a Cooldown rejects one. Use Max Instances 0 and Cooldown 0 (the inspector warns). |
| A layered Tier-2 loop doubles up or gaps every cycle | The Routing/Blend plays clips of different lengths; the loop length comes from the first clip. Make the layers the same length (the inspector warns). |
| A late joiner's Tier-2 loop is out of phase for a cycle or two, goes quiet, then locks on | Known issue — Tier 2 is experimental (§17.4). Tiers 0 and 1 don't have it. |
| One machine's audio slows down, crackles, or drifts badly even on Tier 0 | That machine's audio device is falling behind (its audio clock runs slow), not the network. Check the output device and its buffer size; close audio-heavy apps. Tier 2 re-anchors each cycle and recovers once the device does. |
| Quantized cue does nothing / warns | No musical transport set — call `NetworkMusicTransport.SetTempo(...)` on the server first. |

### 17.11 Dedicated servers: Inert

A dedicated server runs the same scenes and prefabs as a client, and must play nothing and cost nothing. Set Pepper inert once, at boot, before any Audio Manager starts:

```csharp
// The server's boot code, before the first scene with sounds loads.
[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
static void SilenceServer()
{
    if (IsDedicatedServer()) AudioManager.Inert = true;   // your own check
}
```

- **Every post** (`AudioEvent.Post`, `PostMultiPosition`, `AudioManager.Post` and `PostEvent`, `AudioEmitter.Post`) returns one shared, already-finished handle, without allocating and without logging, whether an Audio Manager exists or not. Its `OnFinished` runs at once when you subscribe; `EventName` is empty.
- **An Audio Manager that starts while inert** builds no voices, coroutines or per-frame step, and loads no buses. It still becomes `AudioManager.Instance` and loads the event registry, so code that looks events up (the multiplayer relay) keeps working.
- **The manager's parameter, switch and RTPC calls do nothing.** Values set on emitters and handles are kept as plain data and never stepped. Listening points still register (nothing reads them), so a game's references to them stay valid.
- **The ambient system doesn't create itself** when a zone, portal or ambient source is switched on.
- **It can't change while an Audio Manager runs** (it warns and keeps its value); a server stays a server. It goes back to false at the start of each play session.
- Pepper doesn't detect a server or batch mode by itself (its own tests run in batch mode): your game decides.

## Appendix A: Glossary

Source: https://peppersfx.com/docs/manual/appendix-a-glossary/

**AmbientEmitter:** Pooled persistent looping voice managed by the propagation subsystem. Bypasses the SFX voice pool; routed through an AudioMixerGroup.

**AmbientSource:** Component declaring "there is an ambient bed in this zone with this clip." Doesn't play audio directly — the propagation manager drives a pooled AmbientEmitter on its behalf.

**AudioContainer:** ScriptableObject defining how audio clips are organized and played

**AudioEvent:** ScriptableObject triggering audio actions

**AudioHandle:** Control interface for single voice playback

**AudioMultiHandle:** Control interface for multi-voice playback

**AudioPortal:** Propagation subsystem edge — connects two AudioZones and models an opening (door, window, archway) with transmission and low-pass cutoff driven by an optional IPortalDoorSource.

**AudioVoice:** Single playing audio instance

**AudioZone:** Propagation subsystem node — a volume of world space tagged as one acoustic room. Supports multiple BoxColliders for L-shapes.

**Bus:** Volume control group in hierarchical structure

**Crossfade:** Smooth transition between two containers

**Decibel (dB):** Logarithmic unit of volume

**Ducking:** Automatic volume reduction of target buses

**DSP Time:** Digital Signal Processor time for sample-accurate scheduling

**GainStack:** Layered volume control system

**IPortalDoorSource:** Interface any MonoBehaviour can implement to drive an AudioPortal's open/closed state. Decouples propagation from any specific project's door system.

**Instance Limiting:** Maximum concurrent playbacks of same event

**LOD:** In this system, the `enableLOD` switch for voice virtualization: once more than Max Real Voices are live, the least important voices are paused and tracked. There are no distance tiers.

**Multi-Position:** Synchronized playback across multiple emitters

**Occlusion:** Raycast-based sound blocking

**Portal:** See AudioPortal.

**Priority:** Voice stealing priority (Low, Medium, High, Critical)

**Propagation:** Zone/portal graph-based routing of long-running ambient beds through world geometry.

**PropagationManager:** Singleton orchestrator of the propagation subsystem. Owns registries, the solver, and the emitter pool. Auto-instantiated on first reference.

**RTPC:** Real-Time Parameter Control, dynamic audio parameter. The string API (`SetRTPC`) sets a parameter's global value by name (§3.4)

**Parameter:** A number the game sets and sounds read (RPM, speed, intensity). Defined by a Parameter asset (unit, range, default) or by name (§3.4)

**Scope (parameter):** Where a parameter value is stored: one play (a handle), one emitter, or global. A sound reads the first that has one

**Audio Emitter:** A component for an object that makes sounds (a car). Sounds posted on it read its parameter values

**Listening point:** Where the game listens from, usually a camera, registered with `AudioManager.AddListeningPoint`. Pepper's distance-based features use it instead of searching the scene; with Spatial Mode = Pepper several weighted points pan and attenuate every 3D sound (split screen) (§9.3)

**Spatial Mode:** Who pans and attenuates 3D sounds: Unity (the default, from its AudioListener) or Pepper (from every listening point) (§9.3)

**Smoothing (slew):** How fast what sounds hear follows a newly written parameter value: Ease (seconds to close 95% of the gap) or Rate (units per second), set on the Parameter asset (§3.4)

**State:** Game mode affecting multiple audio parameters

**Switch:** Conditional container selection

**Virtualization:** Pausing a voice to save a real AudioSource while keeping its place in the clip, so it comes back where it would have been

**Voice:** Playing audio instance

**Voice Stealing:** Stopping voice to make room for higher priority

**Zone:** See AudioZone.

## Appendix B: Quick Reference

Source: https://peppersfx.com/docs/manual/appendix-b-quick-reference/

### Common Code Patterns

**Play Sound:**
```csharp
myEvent.Post();
myEvent.Post(gameObject, transform.position);
```

**Control Playback:**
```csharp
AudioHandle handle = myEvent.Post();
handle.SetVolumeScale(0.5f);
handle.SetPitchOffset(2f);
handle.Stop(fadeTime: 1f);
```

**Bus Control:**
```csharp
AudioManager.Instance.SetBusVolume("Music", -6f, transitionTime: 1f);   // the mix (the asset's Volume)
musicBus.PlayerVolumeDb = -6f;                                           // a Settings page (runtime only)
```

**Cars:**
```csharp
car.VolumeOffsetDb = 2f;                                   // this car's trim, every sound on it
car.Post(impactEvent, localContactPoint, PostValues.Of(strength, 0.8f));
scrape.SetLocalOffset(localContactPoint);                  // a playing sound follows the contact
car.Post(whooshEvent, passDsp - 0.3, 0.2);                 // 0.2 s into the clip, timed to the pass
car.Teleport();                                            // after a reset: no Doppler spike
othersBus.MaxRealVoices = 12;                              // other cars can't crowd out your own
```

**Split screen:**
```csharp
AudioManager.Instance.SpatialMode = AudioSpatialMode.Pepper;          // at boot: Pepper pans, from every point
var p2 = AudioManager.Instance.AddListeningPoint(player2Camera);
p2.Weight = 1f; p2.PanWidth = 0f;                                    // full weight, mono
AudioManager.Instance.SetPrimaryListeningPoint(player1Point);       // where Unity's AudioListener goes
```

**State Change:**
```csharp
AudioManager.Instance.SetState("Underwater", transitionTime: 1.5f);
```

**Switch:**
```csharp
AudioManager.Instance.SetSwitch("Surface_Type", "Metal");
```

**RTPC:**
```csharp
AudioManager.Instance.SetRTPC("CombatIntensity", 0.75f);
```

**Multi-Position:**
```csharp
AudioMultiHandle multiHandle = event.PostMultiPosition(emitterParent);
```

## AudioManager

Source: https://peppersfx.com/docs/api/audiomanager/

**Namespace:** `AudioSystem`
**Inheritance:** `MonoBehaviour` (partial class)
**Access:** Singleton via `AudioManager.Instance`

### Inspector Configuration

The core AudioManager fields. Occlusion-related inspector fields (slot pools, ray count, smoothing taus) live in the [AudioManager Slot Pool API](https://peppersfx.com/docs/api/occlusion-mixer-slots/#audiomanager-slot-pool-api) section. Reverb-sends fields live in the [AudioManager Reverb-Sends API](https://peppersfx.com/docs/api/reverb-send-buses/#audiomanager-reverb-sends-api) section.

#### Lifecycle

| Field                  | Default | Description |
|------------------------|---------|-------------|
| `persistAcrossScenes`  | true    | On: `DontDestroyOnLoad`, as before 3.1 (the manager must be a root object), and a second manager removes its whole GameObject. Off: no `DontDestroyOnLoad`; the manager and its voices belong to its scene, and a second manager removes only its own component, with a warning. Read as `PersistAcrossScenes`. |

The voices and every coroutine Pepper runs live on "AudioVoices", a root object of Pepper's own (kept or scene-bound like the manager, destroyed with it), so switching the manager's GameObject or a parent off changes nothing.

#### Audio Configuration

| Field                                | Default | Description                                                                              |
|--------------------------------------|---------|------------------------------------------------------------------------------------------|
| `masterMixerGroup`                   | null    | Optional master mixer group handle. Not directly routed by AudioManager; exposed for project-side scripts. |
| `masterVolume` (range 0–1)           | 1       | Global linear volume multiplier applied to every voice. Combines with per-bus volumes.   |
| `muteAll`                            | false   | Global mute switch. When ON, every voice's output is forced to zero.                     |

#### Voices

| Field                  | Default | Description                                                                                                   |
|------------------------|---------|---------------------------------------------------------------------------------------------------------------|
| `maxRealVoices`        | 32      | Maximum voices playing through real AudioSources at once. Beyond this, the least important plays are kept virtual, a whole play at a time, and made real again when they matter more. Pepper warns at startup if this is above Unity's own Max Real Voices. |
| `maxVirtualVoices`     | 64      | Maximum virtual voices tracked behind the real-voice cap. Real + Virtual is the budget: when it is full, a new play makes room by ending whole plays (never persistent ones), or is skipped if it can't. |
| `stealHeadroom`        | 4       | Spare AudioSources beyond Real + Virtual, for stolen sounds still fading out. |
| `stealFadeSeconds`     | 0.025   | How long a stolen sound that can be heard fades out (pool steals, Max Instances steals, a Switch's Restart), never fewer than three frames; 0 = the old cut (3.1.0-dev.8). Read and set as `StealFadeSeconds`. |
| `stealDeclickSeconds`  | 0.005   | With `stealFadeSeconds` 0 only: how far ahead on the DSP clock a stolen voice is cut. |
| `voiceUpdateInterval`  | 0.1     | Seconds between voice priority / virtualization passes (default 10 Hz).                                       |
| `spatialMode`          | Unity   | Who pans and attenuates 3D sounds: Unity, or Pepper from every listening point (3.1.0-dev.8). See [Listening Point Methods](#listening-point-methods). |
| `updateMode`           | Automatic | When Pepper's per-frame step (parameter ramps, Blend layers, virtual voices) runs. See [UpdateMode / Tick](#updatemode--tick). |

#### Occlusion / LOD

| Field                       | Default | Description                                                                              |
|-----------------------------|---------|------------------------------------------------------------------------------------------|
| `occlusionMask`             | ~0      | Physics layer mask used by the occlusion raycast. The rays ignore trigger colliders, and AudioZone/AudioPortal make their colliders triggers when authored, so their layer doesn't need excluding. |
| `occlusionUpdateInterval`   | 0.2     | Seconds between OcclusionUpdate ticks (raycast cadence, default 5 Hz). Per-frame smoothing handles the in-between. |
| `enableLOD`                 | true    | Voice virtualization: once more than `maxRealVoices` (or a bus's `MaxRealVoices`) would be heard, the least important plays (distance × volume × the priority's weight, from a play's loudest voice) are virtualized, a whole play at a time. Off = nothing is virtualized for the budget (a Blend's Silent Layers still are). |
| `lodDistances`              | `{10, 25, 50, 100}` | Not used in this version; hidden in the inspector. There are no distance tiers. |

See the slot-pool subsection for `occlusionRayCount`, `occlusionRaySpreadMeters`, `occlusionGainSmoothingSeconds`, `occlusionCutoffSmoothingSeconds`, `voiceMixer`, `occlusionLayout`, and `defaultOcclusionSlotsPerBus`. See the reverb-sends subsection for `reverbSendBusRegistry` and `reverbSendsUpdateInterval`.

---

### Properties

#### Instance
```csharp
public static AudioManager Instance { get; }
```
**Description:** Singleton instance of AudioManager.
**Returns:** The active AudioManager in the scene.

#### Inert
```csharp
public static bool Inert { get; set; }
```
**Description:** For a dedicated server: set it once at boot, before any AudioManager starts. While true, every post (`AudioEvent.Post`, `PostMultiPosition`, `AudioManager.Post` / `PostEvent`, `AudioEmitter.Post`) returns one shared, already-finished handle without allocating or logging, with an AudioManager or without one; an AudioManager that starts builds no voices, coroutines or per-frame step (it still becomes `Instance` and loads the event registry); the manager's parameter, switch and RTPC calls do nothing; the ambient system doesn't create itself. Setting it while an AudioManager runs warns and keeps the value. False again at the start of each play session. See USER_GUIDE §17.11.

#### PersistAcrossScenes
```csharp
public bool PersistAcrossScenes { get; }
```
**Description:** The `persistAcrossScenes` setting (see Lifecycle above), read in Awake.

---

### Event Methods

#### PostEvent
```csharp
public AudioHandle PostEvent(string eventName, GameObject source = null, Vector3 position = default)
```
**Description:** Triggers an audio event by name.

**Parameters:**
- `eventName` - Name of the event to trigger (must exist in registry or Resources/Audio/Events/)
- `source` - (Optional) GameObject to attach sound to
- `position` - (Optional) 3D world position for spatial audio

**Returns:** `AudioHandle` for controlling playback, or `null` if event not found.

**Example:**
```csharp
AudioHandle handle = AudioManager.Instance.PostEvent("Play_Explosion");
AudioHandle handle2 = AudioManager.Instance.PostEvent("Play_Footstep", gameObject, transform.position);
```

#### GetEvent
```csharp
public AudioEvent GetEvent(string eventName)
```
**Description:** Gets an AudioEvent by name.

**Parameters:**
- `eventName` - Event name

**Returns:** `AudioEvent`, or `null` if not found.

#### GetEventContainer
```csharp
public AudioContainer GetEventContainer(string eventName)
```
**Description:** Gets the first container referenced by an event.

**Parameters:**
- `eventName` - Event name

**Returns:** `AudioContainer`, or `null` if not found.

---

### Posting by Reference

```csharp
public AudioHandle Post(AudioEvent audioEvent, AudioEmitter emitter)
public AudioHandle Post(AudioEvent audioEvent, AudioEmitter emitter, string point)
public AudioHandle Post(AudioEvent audioEvent, AudioEmitter emitter, PostValues values)
public AudioHandle Post(AudioEvent audioEvent, AudioEmitter emitter, string point, PostValues values)
public AudioHandle Post(AudioEvent audioEvent, AudioEmitter emitter, Vector3 localOffset, PostValues values)
public AudioHandle Post(AudioEvent audioEvent, AudioEmitter emitter, double startDsp, double startOffsetSeconds,
                        PostValues values = default)
public AudioHandle Post(AudioEvent audioEvent, GameObject source = null, Vector3 position = default)
```
**Description:** Post an event you hold a reference to: the same as `audioEvent.Post(emitter)`, `audioEvent.PostAtOffset(emitter, localOffset, values)` (an impact at the contact point), `audioEvent.Post(emitter, startDsp, startOffsetSeconds, values)` (a moment of the sound at a DSP time) and `audioEvent.Post(source, position)`; see [AudioEvent Post](https://peppersfx.com/docs/api/audioevent/#post) and [PostValues](https://peppersfx.com/docs/api/audioevent/#postvalues). Returns `null` (with a warning) when `audioEvent` is null. Write `Post(evt)` rather than `Post(evt, null)`: a bare `null` matches both overloads.

### Random Numbers

```csharp
public AudioRandomSource RandomNumbers { get; set; }   // Pepper (default) or Unity
```
**Description:** Where sounds get random numbers (Random containers' picks, a Sequence's random order, volume and pitch randomization, multi-position offsets). **Pepper**: a sound posted on an [AudioEmitter](https://peppersfx.com/docs/api/parameters/#audioemitter) draws from that emitter's own sequence (its `RandomSeed`), other sounds from one shared Pepper sequence; `UnityEngine.Random`'s state is never touched. **Unity**: `UnityEngine.Random`, as before 3.1. Inside a networked post's `AudioRandomScope`, `UnityEngine.Random` is used (seeded, then put back) either way, so every machine picks the same variation.

---

### Parameter Methods

Parameters are explained in USER_GUIDE Manual §3.4. These methods use the **global** scope: every sound with no emitter or play value reads it. Per-emitter values are on [AudioEmitter](https://peppersfx.com/docs/api/parameters/#audioemitter), per-play values on [AudioHandle](https://peppersfx.com/docs/api/audiohandle-audiomultihandle/#audiohandle). The string RTPC methods below are the same global values addressed by name: a name and an [AudioParameter](https://peppersfx.com/docs/api/parameters/#audioparameter) asset with that Parameter Name share one value.

#### SetParameter / ClearParameter / GetParameter / SnapParameter
```csharp
public void SetParameter(AudioParameter parameter, float value)
public void ClearParameter(AudioParameter parameter)
public float GetParameter(AudioParameter parameter)
public void SnapParameter(AudioParameter parameter)
```
**Description:** Set, forget, read or snap the global value. Sounds follow a value set through the asset with the parameter's [smoothing](https://peppersfx.com/docs/api/parameters/#parameterslew); the first one is heard at once. `GetParameter` returns what sounds hear now (after smoothing), else the default, clamped to the parameter's range. `ClearParameter` falls back to the default, easing there if smoothed. `SnapParameter` skips the smoothing now. `SetParameter` tells `IRTPCListener`s the written value, by the parameter's name; `ClearParameter` doesn't. A write outside the range is stored as written and logs one warning per parameter. A value that isn't a number (NaN, an infinity) is refused at every scope and by `SetRTPC`, ramps and `PostValues` too: sounds keep the last value, listeners aren't told, and the parameter warns once.

#### RampParameter
```csharp
public void RampParameter(AudioParameter parameter, float target, float seconds)
```
**Description:** Move the written global value to `target` over `seconds` (unscaled time, linear), from the value written before (else the default). Smoothing applies on top. A new ramp, a Set, a Snap or a Clear on the same parameter replaces it. Listeners are told every frame it moves.

#### SetRTPC
```csharp
public void SetRTPC(string parameterName, float value)
```
**Description:** Set the global value of the parameter named `parameterName`. Every sound without an emitter or play value follows it at once: values set by name are never smoothed, even if a Parameter asset of that name is. Blend layers pick it up in Pepper's per-frame step later in the same frame. Ends a `TransitionRTPC` running on the same name. Registered `IRTPCListener`s are told at once, inside the call.

**Parameters:**
- `parameterName` - Parameter name (case-sensitive)
- `value` - Parameter value. A name has no range of its own; a Blend that names it reads it clamped to 0–1.

**Example:**
```csharp
AudioManager.Instance.SetRTPC("CombatIntensity", 0.75f);
AudioManager.Instance.SetRTPC("EngineRPM", 0.5f);
```

#### GetRTPC
```csharp
public float GetRTPC(string parameterName)
```
**Description:** The global value set under this name, as written (not smoothed, not clamped).

**Returns:** The value, or `0f` if none has been set. A Parameter asset's default does not apply here.

#### TransitionRTPC
```csharp
public void TransitionRTPC(string parameterName, float targetValue, float duration)
```
**Description:** Moves the global value to a target over time (unscaled, linear), starting from `GetRTPC`. **A second call on the same name replaces the first**, and so does `SetRTPC`; before 3.1 both transitions kept running and fought. States with a transition time use this.

**Parameters:**
- `parameterName` - Parameter name
- `targetValue` - Target value
- `duration` - Transition duration in seconds (0 or less = `SetRTPC`)

**Example:**
```csharp
AudioManager.Instance.TransitionRTPC("CombatIntensity", 1.0f, 2f);
```

#### GetAllRTPCs
```csharp
public IReadOnlyDictionary<string, float> GetAllRTPCs()
```
**Description:** Every global value that has been set, by name and as written: values set with `SetRTPC` and global writes through Parameter assets. A live, read-only view. Enumerating it allocates, so use it in tools, not per frame. Writing a value while enumerating doesn't throw.

**Returns:** Parameter names mapped to their global values.

#### RegisterRTPCListener / UnregisterRTPCListener
```csharp
public void RegisterRTPCListener(IRTPCListener listener)
public void UnregisterRTPCListener(IRTPCListener listener)
```
**Description:** Registers/unregisters an object to receive callbacks when a **global** value changes: `SetRTPC`, `SetParameter`, and every frame of a `TransitionRTPC` or global `RampParameter`. Called synchronously. Emitter and play values don't notify.

**Example:**
```csharp
// Implement IRTPCListener
public class MyComponent : MonoBehaviour, IRTPCListener
{
    void OnEnable() => AudioManager.Instance.RegisterRTPCListener(this);
    void OnDisable() => AudioManager.Instance.UnregisterRTPCListener(this);

    public void OnRTPCChanged(string parameter, float value)
    {
        if (parameter == "EngineRPM") UpdateEngine(value);
    }
}
```

### Listening Point Methods

```csharp
public AudioListeningPoint AddListeningPoint(Transform follow = null)
public void RemoveListeningPoint(AudioListeningPoint point)
public IReadOnlyList<AudioListeningPoint> ListeningPoints { get; }
public void SetPrimaryListeningPoint(AudioListeningPoint point)   // null = the first registered (3.1.0-dev.8)
public AudioListeningPoint PrimaryListeningPoint { get; }          // 3.1.0-dev.8
public AudioSpatialMode SpatialMode { get; set; }                  // Unity (default) | Pepper (3.1.0-dev.8)
public void DriveUnityListener(AudioListener listener)    // null stops it
public AudioListener DrivenUnityListener { get; }
```
**Description:** Tell Pepper where the game listens from (see [AudioListeningPoint](https://peppersfx.com/docs/api/audioextensions-utilities/#audiolisteningpoint)). While any point is registered the scene is never searched; with none, Pepper falls back to the scene's AudioListener (see [ListenerUtil](https://peppersfx.com/docs/api/audioextensions-utilities/#listenerutil)). Points stay registered if the manager is replaced. A point whose followed transform is destroyed is removed, with one warning a session (since 3.1.0-dev.8; it used to stay where it last was).

**The primary point** (3.1.0-dev.8): the one the game picks with `SetPrimaryListeningPoint`, else the first registered. `DriveUnityListener` moves an AudioListener to it in every step, before Unity mixes, so Unity's 3D panning hears from the same place (skipped when the listener is on the transform the point follows); `ListenerUtil.Get` / `GetPosition`, the ambient system and SingleEmitter posts read it; with Spatial Mode = Unity it is the only point Pepper listens from. Picking another doesn't make sounds jump: what Pepper measures from it (the built-in Distance, Approach Speed and Angle, so Doppler and the curves on them; attenuation filters) glides to the new one over 100 ms. A point that isn't registered is refused, with a warning.

**SpatialMode** (3.1.0-dev.8; inspector: **Spatial Mode**). `Unity` (the default): Unity's 3D from its AudioListener, as before; weights and pan widths are unused. `Pepper`: every 3D voice plays at Spatial Blend 0 and Pepper sets its level (`GainStack.SpatialGain`) and `panStereo` from every point each frame. For each point, the voice's attenuation there (its Attenuation asset's volume curve, else Unity's rolloff for its Min and Max Distance) × the point's `Weight` is its contribution; the level is the largest, the pan Σ contribution × `PanWidth` × the point's pan ÷ Σ contribution, eased over about 50 ms. At one point of weight 1 and width 1 it reproduces Unity's 3D (rolloffs, constant-power pan, Spread; measured on 6000.0 and 6000.3). Each play is measured from the point that hears it loudest (changing only when another is 1 dB louder): its built-ins, Doppler, attenuation filters, occlusion rays, the Furthest steal. It goes virtual past Max Distance only from every point. Doppler is always Pepper's (a container on Unity's gets Pepper's at its Doppler Level). Levels ease over 100 ms after the points change. No spatializer plugins; the project's Doppler Factor isn't read; a stereo clip is balanced, not placed. A change applies to the sounds started after it. USER_GUIDE §9.3.

**Example:**
```csharp
var point = AudioManager.Instance.AddListeningPoint(mainCamera.transform);
// ... when the camera is destroyed:
AudioManager.Instance.RemoveListeningPoint(point);
```

#### UpdateMode / Tick
```csharp
public AudioUpdateMode UpdateMode { get; set; }   // Automatic (default) | Manual
public void Tick()
```
**Description:** When Pepper's per-frame step runs. In order: parameter ramps and smoothing (global, then emitters, then plays); bus parameter curves; the emitters and listening points (velocities, `DriveUnityListener`), with voices that follow their emitter moved to it; every dynamic play's tree (Blend layer levels, curves, pitch follow, switches); with Spatial Mode = Pepper, every 3D voice's level and pan; then virtual voices' positions, the fade around virtualization and the steal fade. **Automatic** runs it once a frame from a PlayerLoop step just before `PostLateUpdate.UpdateAudio`, after every LateUpdate, so values set anywhere in this frame's game code are heard this frame. It starts with the frame after the manager's Awake. **Manual** runs it only when you call `Tick()`, once a frame after your last write; ramps advance by `Time.unscaledDeltaTime`. Calling `Tick()` in Automatic mode advances ramps twice. Inspector field: **Update Mode**.

---

### Switch Methods

#### SetSwitch
```csharp
public void SetSwitch(string group, string value)
public void SetSwitch(AudioSwitchGroup group, string value)
```
**Description:** Sets the GLOBAL value of a switch group: every sound with no value of its own (handle) and none on its emitter reads it. A name and an [AudioSwitchGroup](https://peppersfx.com/docs/api/parameters/#audioswitchgroup) asset with that name are one switch. A value not in the asset's Values warns once; a group Driven By a parameter ignores it, with one warning (by name, only when the asset is loaded).

**Parameters:**
- `group` - Switch group name (e.g., "Surface_Type") or asset
- `value` - Switch value (e.g., "Metal", "Wood")

**Example:**
```csharp
AudioManager.Instance.SetSwitch("Surface_Type", "Metal");
AudioManager.Instance.SetSwitch(surfaceType, "Metal");   // the same switch, through its asset
```

#### ClearSwitch
```csharp
public void ClearSwitch(AudioSwitchGroup group)
public void ClearSwitch(string group)
```
**Description:** Forgets the global value: sounds read the group's Default Value (a Switch that only names its group: none, so its Default Container).

#### GetSwitch
```csharp
public string GetSwitch(string group)
public string GetSwitch(AudioSwitchGroup group)
```
**Description:** By name: the global value set, or empty string if not set. By asset: what a sound with no handle or emitter value reads (the global value, else the Default Value; for a driven group, what the parameter's global value gives).

#### GetAllSwitches
```csharp
public IReadOnlyDictionary<string, string> GetAllSwitches()
```
**Description:** Gets all current switch values.

**Returns:** Dictionary mapping switch groups to their current values.

---

### State Methods

#### SetState
```csharp
public void SetState(string stateName, float transitionTime = 0.5f)
```
**Description:** Activates an audio state; the group's previous state ends. A state whose `VolumeMode` is `Offset` moves its buses by its dB values (their `StateOffsetDb`), and the previous state's offsets go back, over `transitionTime` (unscaled, in Pepper's step). A `SetLevel` state (the default) sets the buses' Volume and puts nothing back, as before.

**Parameters:**
- `stateName` - Name of state to activate
- `transitionTime` - Duration of transition in seconds (default: 0.5s)

**Example:**
```csharp
AudioManager.Instance.SetState("Underwater", 1.5f);
AudioManager.Instance.SetState("Paused", 0.3f);
```

#### ClearState
```csharp
public void ClearState(string stateGroup, float transitionTime = 0.5f)
```
**Description:** Leaves `stateGroup`'s state without setting another (3.1.0-dev.7): an `Offset` state's bus offsets go back over `transitionTime`; a `SetLevel` state's changes stay. The group has no active state afterwards.

#### SetStateInGroup
```csharp
public void SetStateInGroup(string stateGroup, string stateName, float transitionTime = 0.5f)
```
**Description:** Sets a state within a specific state group.

**Parameters:**
- `stateGroup` - State group name
- `stateName` - State name within that group
- `transitionTime` - Transition duration

**Example:**
```csharp
AudioManager.Instance.SetStateInGroup("Location", "Underwater", 1.5f);
```

#### GetActiveState
```csharp
public AudioState GetActiveState(string stateGroup)
```
**Description:** Gets the currently active state for a state group.

**Returns:** Active `AudioState`, or `null` if no state active.

#### GetActiveStateName
```csharp
public string GetActiveStateName(string stateGroup)
```
**Description:** Gets the name of the currently active state.

**Returns:** State name, or empty string if none active.

#### GetAllActiveStates
```csharp
public IReadOnlyDictionary<string, AudioState> GetAllActiveStates()
```
**Description:** Gets all active states across all groups.

**Returns:** Dictionary mapping state group to active state.

---

### Bus Methods

#### SetBusVolume
```csharp
public void SetBusVolume(string busName, float volumeDb, float transitionTime = 0f)
```
**Description:** Sets a bus's Volume in decibels (the asset's value; an empty name is the master bus). **A name no bus has changes nothing and warns once per name** (since 3.1.0-dev.7; it used to set the master bus). For a player's volume from a Settings page, use [AudioBus.PlayerVolumeDb](https://peppersfx.com/docs/api/audiobus/) instead: a state can't undo it and it isn't saved to the asset.

**Parameters:**
- `busName` - Name of the bus
- `volumeDb` - Target volume in dB (0 = no change, -6 = half, -80 = silence)
- `transitionTime` - Transition duration in seconds (0 = instant)

**Example:**
```csharp
AudioManager.Instance.SetBusVolume("Music", -6f, 1f);  // Duck to half volume over 1 second
AudioManager.Instance.SetBusVolume("SFX", 0f, 0.5f);    // Return to full over 0.5s
```

#### TransitionBusVolume
```csharp
public void TransitionBusVolume(AudioBus bus, float targetVolumeDb, float transitionTime)
```
**Description:** Transitions a bus to a target volume over time using the bus reference directly.

**Parameters:**
- `bus` - The AudioBus reference
- `targetVolumeDb` - Target volume in dB
- `transitionTime` - Transition duration

#### SetBusEffectProperty
```csharp
public void SetBusEffectProperty(AudioBus bus, string propertyName, float value, float transitionTime = 0f)
```
**Description:** Sets an effect property on a bus with optional transition.

**Parameters:**
- `bus` - Target bus
- `propertyName` - Effect property name
- `value` - Target value
- `transitionTime` - Transition duration (0 = instant)

#### GetBus
```csharp
public AudioBus GetBus(string busName)
```
**Description:** Gets a bus by name.

**Returns:** `AudioBus`, or the master bus for an empty name. For a name no bus has it also returns the master bus, as before, and warns once per name (since 3.1.0-dev.7).

#### GetAllBuses
```csharp
public List<AudioBus> GetAllBuses()
```
**Description:** Gets all registered buses.

**Returns:** List of all buses.

---

### Crossfade Methods

#### CrossFade
```csharp
public void CrossFade(AudioContainer from, AudioContainer to, float duration,
    AudioEvent.CrossfadeType type = AudioEvent.CrossfadeType.EqualPower)
```
**Description:** Crossfades between two containers.

**Parameters:**
- `from` - Container to fade out
- `to` - Container to fade in
- `duration` - Crossfade duration in seconds
- `type` - Crossfade curve type (Linear or EqualPower)

Linear fades in with `x` and out with `1 − x`; EqualPower fades in with `sin(x·π/2)` and out with `cos(x·π/2)`. The incoming voices play unbussed (through the container's Mixer Group); the CrossFade event action routes them through its Target Bus instead, and places a 3D container at the post's position or source GameObject. Fades only the "from" voices playing now: what the outgoing sound was still going to start (a delayed Play, a Sequence's next clip) still starts. Use the handle overload below for that.

**Example:**
```csharp
AudioManager.Instance.CrossFade(oldMusicContainer, newMusicContainer, 2f);
```

#### CrossFade (handle)
```csharp
public AudioHandle CrossFade(AudioHandle from, AudioEvent to, float duration,
    AudioEvent.CrossfadeType type = AudioEvent.CrossfadeType.EqualPower,
    GameObject source = null, Vector3 position = default)
```
**Description:** Fades out every voice of `from` and cancels what it was still going to start (delayed Play actions, a Sequence's next clip), posts `to` and fades in the voices that post started. Returns the new handle (null when `to` is null).

- `from` finishes (`OnFinished`) when its fade-out ends; `OnStopping` does not fire.
- `to` is an ordinary post: bus, priority, cooldown and Max Instances apply. If it is the same event as `from` and Max Instances is reached, the old play is ended at once by the instance limit.
- Voices `to` starts later are not faded in.
- Either argument may be null.

**Example:**
```csharp
music = AudioManager.Instance.CrossFade(music, combatMusicEvent, 2f);
```

---

### Volume & Global Control Methods

#### SetMasterVolume
```csharp
public void SetMasterVolume(float volume)
```
**Description:** Sets master volume (global volume multiplier).

**Parameters:**
- `volume` - Volume in linear scale (0-1)

**Example:**
```csharp
AudioManager.Instance.SetMasterVolume(0.75f);  // 75% volume
```

#### GetMasterVolume
```csharp
public float GetMasterVolume()
```
**Description:** Gets current master volume.

**Returns:** Master volume (0-1).

#### MasterVolumeDb / SetMasterVolumeDb
```csharp
public float MasterVolumeDb { get; set; }
public void SetMasterVolumeDb(float db)
```
**Description:** The master volume in dB, beside the linear setter (the same value; 3.1.0-dev.7). Above 0 dB stays at full; −80 dB and below is silent.

#### IsAllMuted
```csharp
public bool IsAllMuted { get; }
```
**Description:** True while `MuteAll(true)` has every sound muted (3.1.0-dev.7).

#### MuteAll
```csharp
public void MuteAll(bool mute)
```
**Description:** Mutes or unmutes all audio.

**Parameters:**
- `mute` - `true` to mute, `false` to unmute

**Example:**
```csharp
AudioManager.Instance.MuteAll(true);   // Mute everything
AudioManager.Instance.MuteAll(false);  // Unmute everything
```

#### StopAllSounds
```csharp
public void StopAllSounds()
```
**Description:** Stops all currently playing sounds.

#### PauseAll
```csharp
public void PauseAll()
```
**Description:** Pauses all currently playing sounds, at once. Sounds posted afterwards play. For a game's pause, where a pause menu must still sound, pause buses instead ([AudioBus.Pause](https://peppersfx.com/docs/api/audiobus/#pause--resume--ispaused)).

#### UnpauseAll
```csharp
public void UnpauseAll()
```
**Description:** Resumes all paused sounds.

---

### Voice Management Methods

#### GetVoice
```csharp
public AudioVoice GetVoice()
```
**Description:** Allocates a voice from the pool. **Internal use only.**

**Returns:** Available voice, or `null` if pool exhausted.

#### ReturnVoice
```csharp
public void ReturnVoice(AudioVoice voice)
```
**Description:** Returns a voice to the pool. **Internal use only.**

#### GetStatistics
```csharp
public AudioStatistics GetStatistics()
```
**Description:** Gets current audio system statistics.

**Returns:** `AudioStatistics` with voice counts and system info.

**Example:**
```csharp
var stats = AudioManager.Instance.GetStatistics();
Debug.Log($"Real voices: {stats.activeVoices}/{stats.realVoiceBudget}");
```

---

### Debug Methods

#### GetVirtualVoiceCount
```csharp
public int GetVirtualVoiceCount()
```
**Description:** Gets the number of currently virtualized voices.

#### GetActiveVoicesDebug
```csharp
public List<AudioVoiceDebugInfo> GetActiveVoicesDebug()
```
**Description:** Gets detailed debug info for all active voices: for a virtual one, why (`virtualReasonKind`, see `VoiceVirtualReason`); its level, pitch and region.

**Returns:** List of `AudioVoiceDebugInfo` for each active voice.

#### GetPlaysDebug
```csharp
public void GetPlaysDebug(List<AudioPlayDebugInfo> into)
```
**Description:** Fills `into` with every play that has a live voice, each with its voices, ordered by play number: what the editor's Live View (USER_GUIDE §10.6) shows per emitter. A play with nothing sounding right now (a Switch with no choice, a Sequence between clips, a Delay still running) isn't listed. Allocates; for tools and debug overlays, not per-frame game code.

#### ReasonText
```csharp
public static string ReasonText(VoiceVirtualReason reason)
```
**Description:** The words the debug windows show for a reason: "over the cap", "silent layer", "past Max Distance", "held by code", "bus paused", "emitter paused", "stopping"; empty for `None`.

## AudioEvent

Source: https://peppersfx.com/docs/api/audioevent/

**Namespace:** `AudioSystem`
**Inheritance:** `ScriptableObject`

### Properties

#### EventName
```csharp
public string EventName { get; }
```
**Description:** Unique name identifying this event.

#### Actions
```csharp
public List<EventAction> Actions { get; }
```
**Description:** List of actions to execute when this event is posted.

#### Priority
```csharp
public VoicePriority Priority { get; }
```
**Description:** How important this event's sounds are (Low, Medium, High, Critical): a weight in each voice's importance, which decides what goes virtual and what is stolen first. Critical is the strongest weight, not an exemption; to keep a sound from ever being stolen, tick `Persistent`.

#### MaxInstances
```csharp
public int MaxInstances { get; }
```
**Description:** Maximum concurrent plays (0 = unlimited). One play is everything a single Play action starts: all of a multi-clip Routing container's clips, or all of a Blend's layers, count as one instance.

#### StealBehavior
```csharp
public VoiceStealBehavior StealBehavior { get; }
```
**Description:** Which play to end when the limit is reached (Oldest, Quietest, Furthest, LowestPriority). A steal ends the whole play, meaning every voice it started. Oldest means the play that started first, judged by start time rather than playback position. Quietest uses each play's loudest voice. Furthest uses each play's nearest voice.

#### Cooldown
```csharp
public float Cooldown { get; }
```
**Description:** Minimum time between triggers in seconds.

#### MaxInstancesPerEmitter / CooldownPerEmitter
```csharp
public int MaxInstancesPerEmitter { get; }   // 0 = no limit per emitter
public float CooldownPerEmitter { get; }     // seconds; 0 = none
```
**Description:** The same limits for one [AudioEmitter](https://peppersfx.com/docs/api/parameters/#audioemitter), on top of the game-wide ones: a post on an emitter already playing `MaxInstancesPerEmitter` plays of this event ends one of **that emitter's** plays, chosen by `StealBehavior`; a post sooner than `CooldownPerEmitter` after the last one on that emitter returns a finished handle. Other emitters aren't affected. Posts without an emitter aren't counted per emitter. On the event's `TimeMode`, like `Cooldown`.

#### TimeMode
```csharp
public AudioTimeMode TimeMode { get; set; }   // Scaled (default) or Unscaled
```
**Description:** Inspector: **Time**. The clock this event's timing runs on: `Cooldown`, `CooldownPerEmitter`, Delay actions, its sounds' Sequence gaps, its CrossFade action and `AudioManager.CrossFade(handle, thisEvent)`. Scaled is game time: it stops at time scale 0, as before. Unscaled is real time, for UI and pause-menu sounds. Changing it mid-session compares the next post with a time from the old clock once.

```csharp
public enum AudioTimeMode { Scaled, Unscaled }
```

#### Persistent
```csharp
public bool Persistent { get; }
```
**Description:** Inspector: **Persistent**. This event's plays are never stolen by the voice pool to make room for other sounds (an engine). They can still go virtual, and this event's own Max Instances can still end one. If the pool is full of persistent plays, a new sound is skipped with a warning. Their voices get Unity's highest `AudioSource.priority` (0).

---

### Methods

#### Post
```csharp
public AudioHandle Post(GameObject source = null, Vector3 position = default)
```
**Description:** Posts the event. Optionally attach to a GameObject and/or specify a 3D position.

**Parameters:**
- `source` - (Optional) GameObject to attach sound to
- `position` - (Optional) 3D world position for spatial audio

**Returns:** `AudioHandle` for controlling playback.

**Example:**
```csharp
// Non-spatial (2D)
AudioHandle handle = myEvent.Post();

// Attached to a GameObject at its position
AudioHandle handle = myEvent.Post(gameObject, transform.position);

// At a specific world position, not attached
AudioHandle handle = myEvent.Post(null, explosionPosition);
```

`Post(GameObject, Vector3, double scheduledDspTime)` starts the voices at an exact DSP time instead of the next buffer (tempo-driven callers).

#### Post (on an emitter)
```csharp
public AudioHandle Post(AudioEmitter emitter)
public AudioHandle Post(AudioEmitter emitter, double scheduledDspTime)
```
**Description:** Posts the event on an [AudioEmitter](https://peppersfx.com/docs/api/parameters/#audioemitter). 3D voices are placed and attached exactly as with `Post(emitter.gameObject, emitter.transform.position)`, and the sounds read the emitter's parameter values (after the handle's own, before the global ones). A null or destroyed emitter logs a warning and returns a finished handle with nothing playing. Same as `emitter.Post(evt)`.

> **Source change in 3.1:** `myEvent.Post(null)` with a bare `null` no longer compiles: it matches both this overload and `Post(GameObject, ...)`. Write `myEvent.Post()` for a 2D post.

#### Post (with values for that sound)
```csharp
public AudioHandle Post(AudioEmitter emitter, PostValues values)
public AudioHandle Post(AudioEmitter emitter, string point, PostValues values)
public AudioHandle Post(GameObject source, Vector3 position, PostValues values)
```
**Description:** Posts with [PostValues](#postvalues) for this sound only: they are set on the handle's play scope before any Play action runs, so the first sample hears them (an impact's strength, a footstep's surface). A delayed Play action reads them too.

#### PostAtOffset (an emitter, anywhere on it)
```csharp
public AudioHandle PostAtOffset(AudioEmitter emitter, Vector3 localOffset, PostValues values = default)
```
**Description:** Posts on `emitter` at `localOffset` (metres, in its own space), as at a named point but anywhere: an impact at the contact point (3.1.0-dev.7). The sound moves and turns with the emitter, reads its values, counts toward its Max Instances Per Emitter and Cooldown Per Emitter, and draws from its random numbers. Move it later with `AudioHandle.SetLocalOffset`. Same as `emitter.Post(evt, localOffset, values)`. It isn't an overload of `Post`, so that `Post(null, position, values)` keeps compiling.

#### Post (a moment of the sound at a DSP time)
```csharp
public AudioHandle Post(AudioEmitter emitter, double startDsp, double startOffsetSeconds, PostValues values = default)
public AudioHandle Post(GameObject source, Vector3 position, double startDsp, double startOffsetSeconds,
                        PostValues values = default)
```
**Description:** `startOffsetSeconds` into the sound (seconds of its clips at their recorded pitch) is heard at the DSP time `startDsp` (3.1.0-dev.7): a pass-by whoosh whose peak lands on the pass. If `startDsp` has passed, or is nearer than the next DSP buffer, the sound starts at the next buffer that much further in (at its pitch), so the same moment still lands on time; a one-shot already past its end plays nothing and its handle finishes; a loop wraps. Every voice the Play actions start with takes the offset (a Blend's layers stay aligned); a Sequence's later clips start from their beginning; a Play action with a Delay keeps its own timing. `startDsp` 0 = as soon as possible, from the offset. Same as `emitter.Post(evt, startDsp, startOffsetSeconds, values)`.

#### EstimateDuration
```csharp
public AudioDuration EstimateDuration(PostValues values = default)
public AudioDuration EstimateDuration(AudioEmitter emitter, PostValues values = default)
```
**Description:** How long the event plays if posted now with `values` (3.1.0-dev.7), before posting it. Random container: its shortest and longest clip. Switch: the choice the values pick (the given values, then the emitter's, then global, then the group's Default). Blend and Routing: their longest layer (a Blend's Loop Mode decides whether it loops). Sequence: the entry it plays next, or with Auto Advance the rest of the run (a run that starts again loops). Every Play action counts, its Delay added; the longest wins. A custom container: the shortest and longest of the clips it lists. Clips are measured at their recorded pitch; an addressable clip that isn't loaded is unknown. Draws no random numbers.

### AudioDuration

**Namespace:** `AudioSystem` (readonly struct)

```csharp
public float Shortest { get; }   // seconds
public float Longest { get; }    // seconds; for a loop, one time through
public bool Loops { get; }       // plays until stopped
public bool IsKnown { get; }     // false when nothing would play (the lengths are 0)
```

### PostValues

**Namespace:** `AudioSystem` (struct)

```csharp
public const int MaxParameters = 4;
public const int MaxSwitches = 2;
public static PostValues Of(AudioParameter parameter, float value)
public static PostValues Of(AudioSwitchGroup group, string value)
public PostValues With(AudioParameter parameter, float value)   // a later value for the same parameter wins
public PostValues With(AudioSwitchGroup group, string value)
public static PostValues VolumeOffset(float db)
public PostValues WithVolumeOffset(float db)          // the handle's SetVolumeOffset, before the first sample
public PostValues WithPitchOffset(float semitones)    // the handle's SetPitchOffset, before the first sample
public int ParameterCount { get; }
public int SwitchCount { get; }
public bool IsEmpty { get; }
```
**Description:** Values a post gives its sound (the play scope, like `AudioHandle.SetParameter` / `SetSwitch`), applied before its first voice starts, and its own volume and pitch offsets (3.1.0-dev.7), which also reach the voices it starts later. Building one allocates nothing. More than 4 parameters or 2 switches: the rest are dropped with one warning; set them on the returned handle.

```csharp
car.Post(impactEvent, "FrontAxle", PostValues.Of(strength, 0.8f).With(surface, "Grass"));
```

#### PostMultiPosition
```csharp
public AudioMultiHandle PostMultiPosition(Vector3[] positions, GameObject source = null)
public AudioMultiHandle PostMultiPosition(Transform[] transforms, GameObject source = null)
public AudioMultiHandle PostMultiPosition(AudioMultiPositionEmitterParent emitterParent, GameObject source = null)
```
**Description:** Posts event in multi-position mode (synchronized across multiple positions or emitters).

**Parameters:**
- `positions` - Array of 3D world positions
- `transforms` - Array of transforms to track
- `emitterParent` - Multi-position emitter parent component
- `source` - (Optional) GameObject to attach the voices to. On a 3D container each voice still plays at its own position and moves with `source`.

**Returns:** `AudioMultiHandle` for controlling all voices.

**Example:**
```csharp
// From position array
Vector3[] speakerPositions = { pos1, pos2, pos3 };
AudioMultiHandle mh = myEvent.PostMultiPosition(speakerPositions);

// From transforms
Transform[] speakers = GetSpeakerTransforms();
AudioMultiHandle mh = myEvent.PostMultiPosition(speakers);

// From emitter parent component
AudioMultiHandle mh = myEvent.PostMultiPosition(emitterParent);
```

#### GetContainer
```csharp
public AudioContainer GetContainer()
```
**Description:** Gets the first container referenced in this event's actions.

**Returns:** `AudioContainer`, or `null` if no Play action exists.

#### GetFirstActiveSource
```csharp
public AudioSource GetFirstActiveSource()
```
**Description:** Gets the first active AudioSource for this event.

**Returns:** `AudioSource`, or `null` if no voice is active.

#### CreateNew (Editor Only)
```csharp
public static AudioEvent CreateNew(string name, AudioContainer container, AudioBus bus)
```
**Description:** Factory method to create a new AudioEvent asset with pre-configured Play action.

---

### EventAction (Nested Class)

```csharp
[Serializable]
public class EventAction
{
    public ActionType type;
    public ActionScope scope;           // Stop/Pause/Resume: All (default) or ThisEmitter
    public AudioContainer container;
    public AudioBus targetBus;          // Play/CrossFade routing; TriggerDucking's trigger bus
    public float delay;
    public float fadeDuration;          // Stop fade-out; CrossFade/SetRTPC/SetState transition;
                                        // TriggerDucking hold time. Play ignores it.
    public AnimationCurve fadeCurve;    // Not used by any action in this version
    public string switchGroup;
    public string switchValue;
    public string rtpcName;
    public float rtpcValue;
    public string stateName;
    public AudioContainer fadeFromContainer;
    public CrossfadeType crossfadeType;

    public enum ActionType
    {
        Play, Stop, Pause, Resume,
        SetSwitch, SetRTPC, SetState,
        TriggerDucking, CrossFade
    }

    public enum ActionScope { All, ThisEmitter }
}
```

**`scope`:** which of this event's sounds a Stop, Pause or Resume action acts on. `All` (the default, as before): every one playing, on every emitter. `ThisEmitter`: only those posted on the [AudioEmitter](https://peppersfx.com/docs/api/parameters/#audioemitter) the event is posted on; posted without one, it acts on all.

### CrossfadeType (Nested Enum)

```csharp
public enum CrossfadeType
{
    Linear,      // Linear crossfade
    EqualPower   // Maintains perceived loudness
}
```

## AudioHandle & AudioMultiHandle

Source: https://peppersfx.com/docs/api/audiohandle-audiomultihandle/

### AudioHandle

**Namespace:** `AudioSystem`
**Description:** Controls a single audio playback instance: every voice the post started, including voices that start later. A Routing container with several clips, every layer of a Blend, and each clip an auto-advancing Sequence goes on to play all belong to the handle, so `Stop`, `Pause`, the volume and pitch calls, `SeekTo` and `SetLoop` reach the whole sound. `OnFinished` fires only when nothing is sounding and nothing more is coming: after a Sequence's last clip (not during a Delay After gap), and after any delayed Play actions. `Stop()` also cancels whatever was still to come.

#### Properties

```csharp
public string EventName { get; }
public AudioEvent SourceEvent { get; }
public AudioEmitter Emitter { get; } // The emitter it was posted on, or null
public bool IsPaused { get; }
public bool isPlaying { get; }  // True while any voice is playing
public float time { get; }      // Playback time of the primary (first) voice, in seconds
public float duration { get; }  // Clip duration of the primary (first) voice, in seconds
```

---

#### Events

```csharp
public event System.Action OnStarted;
public event System.Action OnLoop;      // declared, but not raised in this version
public event System.Action OnStopping;
public event System.Action OnFinished;
```
**Description:** Callbacks for playback lifecycle events.
- `OnStarted`: a voice of this post started.
- `OnStopping`: a `Stop(fadeTime)` fade-out has begun. Not raised for `Stop(0)` or by crossfades.
- `OnFinished`: the post has finished: every voice has ended and nothing is still to come. Subscribing after it finished invokes the handler at once.
- `OnLoop`: declared but never raised in this version. Don't rely on it.
- Subscribing `OnStarted`, `OnStopping` or `OnLoop` once the handle has finished does nothing: they can't fire any more. (An inert process's posts all return one such shared handle; see `AudioManager.Inert`.)

**Example:**
```csharp
AudioHandle handle = myEvent.Post();
handle.OnStarted += () => Debug.Log("Started");
handle.OnFinished += () => Debug.Log("Finished");
```

---

#### Methods

##### SetVolumeScale
```csharp
public void SetVolumeScale(float scale)
```
**Description:** Scales the sound relative to its authored volume. `1` = as authored, `0.5` = half. Calling it twice with 0.5 means 0.5, not 0.25. Container volume randomization and bus levels still apply on top. Reaches the voices playing now and the ones the sound starts later: a Sequence's next clip, a playing Switch's new choice, a delayed Play action (since 3.1.0-dev.7; before, only the voices playing then). `VolumeScale` reads it back.

**Parameters:**
- `scale` - Multiplier on the authored volume

##### SetVolumeOffset
```csharp
public void SetVolumeOffset(float db)
public float VolumeOffsetDb { get; }
```
**Description:** `SetVolumeScale` in dB (3.1.0-dev.7): `-3` plays the sound 3 dB below how it was authored, now and in the voices it starts later. The same slot as `SetVolumeScale`: the last call wins. Settable at the post with `PostValues.WithVolumeOffset`. Composes with the emitter's Volume Offset. A raise can't take a voice past its AudioSource's full volume.

##### SetVolumeAbsolute
```csharp
public void SetVolumeAbsolute(float linear)
```
**Description:** Replaces the authored volume with an exact level (linear, 1 = full scale), so `SetVolumeAbsolute(1f)` can be louder than the sound was authored. Use `SetVolumeScale` unless you mean to ignore the authored level.

> `SetVolume(float)` is obsolete. It has always been absolute, so it forwards to `SetVolumeAbsolute`. Switch to `SetVolumeScale` if you wanted a multiplier.

##### SetPitchOffset
```csharp
public void SetPitchOffset(float semitones)
```
**Description:** Shifts the voices by `semitones` on top of their own pitch: container pitch randomization and the other pitch-stack slots still apply. Idempotent: `SetPitchOffset(2f)` twice means +2, not +4. Clears an absolute pitch. Reaches the voices playing now and the ones the sound starts later (the same as `SetVolumeScale`, since 3.1.0-dev.7). Settable at the post with `PostValues.WithPitchOffset`. `PitchOffset` reads it back.

**Parameters:**
- `semitones` - Pitch offset (-12 to +12 typical range)

##### SetPitchAbsolute
```csharp
public void SetPitchAbsolute(float semitones)
```
**Description:** Plays the voices at exactly `semitones` from their recorded pitch, replacing container pitch randomization and every other pitch-stack slot (Doppler included). Use `SetPitchOffset` unless you mean to discard the authored variation. Unlike the offset, it reaches only the voices playing now (as does `SetVolumeAbsolute`).

##### SetLocalOffset / SetWorldPosition
```csharp
public void SetLocalOffset(Vector3 offset)
public void SetWorldPosition(Vector3 position)
```
**Description:** Move a playing sound (3.1.0-dev.7): a scrape loop following the contact along a wall. `SetLocalOffset` puts it at `offset` (metres) from the object it was posted on (its emitter, or the GameObject), in that object's space; it keeps moving and turning with it, attached or following (On Disable). `SetWorldPosition` puts it at a world position: on a sound posted on an object that becomes an offset from it; a sound posted at a world position moves there (and `SetLocalOffset` on it is from the world's origin). Voices the sound starts later, and Play actions still waiting out a Delay, start where it was moved to. Takes effect at once.

> `SetPitch(float)` is obsolete. It has always replaced the randomized pitch, so it forwards to `SetPitchAbsolute`. Switch to `SetPitchOffset` for a shift on top of the authored pitch.

##### Parameters (the play scope)
```csharp
public void SetParameter(AudioParameter parameter, float value)
public void ClearParameter(AudioParameter parameter)
public void RampParameter(AudioParameter parameter, float target, float seconds)
public void SnapParameter(AudioParameter parameter)
public void SnapAllParameters()
public void SetSlewOverride(AudioParameter parameter, ParameterSlew slew)
public void ClearSlewOverride(AudioParameter parameter)
public bool TryGetParameter(AudioParameter parameter, out float value)
public float GetEffectiveParameter(AudioParameter parameter)

// For tools: the values on this handle, as on an emitter (the Live View lists them)
public int ParameterCount { get; }
public string GetParameterNameAt(int index)
public float GetParameterValueAt(int index)     // as heard now (after smoothing)
public float GetParameterTargetAt(int index)    // as written
public bool IsParameterMovingAt(int index)      // ramping, smoothing or easing away
```
**Description:** A value for this sound only: it wins over its emitter's and the global value. Use it for values that differ between sounds on one emitter (each axle's slide speed). It is smoothed separately from the emitter's value; the first value set here is heard at once. `ClearParameter` falls back to the emitter's or global value, easing over if smoothed. `RampParameter` moves the written value in a straight line (unscaled time), smoothing on top; a new ramp, a Set, a Snap or a Clear replaces it. `SnapParameter` / `SnapAllParameters` skip the smoothing now. `SetSlewOverride` smooths this sound's value with other settings. `TryGetParameter` returns the value set on this handle, as written. `GetEffectiveParameter` returns what the sound hears now: its own value after smoothing, else its emitter's, else the global value, else the default, clamped to the range.

```csharp
AudioHandle frontAxle = car.Post(tyreEvent);
frontAxle.SetParameter(slideSpeed, 3.5f);
```

##### Attenuation (this play)
```csharp
public void SetAttenuation(AudioAttenuation attenuation)   // null = ClearAttenuation
public void ClearAttenuation()
```
**Description:** Play this sound's 3D voices with another [AudioAttenuation](https://peppersfx.com/docs/api/parameters/#audioattenuation) (a hero car heard further away), now and for voices it starts later; `ClearAttenuation` goes back to its containers' own. Changes this play only, never an asset. `GetEffectiveParameter` on a built-in parameter (Distance, Approach Speed, Angle) returns this sound's value.

##### Switches (the play scope)
```csharp
public void SetSwitch(AudioSwitchGroup group, string value)
public void ClearSwitch(AudioSwitchGroup group)
public bool TryGetSwitch(AudioSwitchGroup group, out string value)
public string GetEffectiveSwitch(AudioSwitchGroup group)
```
**Description:** A switch value for this sound only (one axle's surface): it wins over its emitter's and the global value. A Switch Container in the sound follows it as its `WhenSwitchChanges` says (USER_GUIDE §4.5). `GetEffectiveSwitch` returns what the sound reads: its own value, else its emitter's, else the global one, else the group's Default Value; for a group driven by a parameter, what the parameter gives in this sound's scopes (without a playing Switch's hysteresis). A driven group ignores `SetSwitch`, with one warning.

##### Stop
```csharp
public void Stop(float fadeTime = 0.1f)
```
**Description:** Stops playback with optional fade.

**Parameters:**
- `fadeTime` - Fade-out duration in seconds

##### Pause
```csharp
public void Pause()
```
**Description:** Pauses playback (can be resumed).

##### Resume
```csharp
public void Resume()
```
**Description:** Resumes paused playback.

##### Dispose
```csharp
public void Dispose()
```
**Description:** Cleans up event handlers to prevent memory leaks.

**Note:** `Dispose()` is called automatically when `OnFinished` is triggered. Manual disposal is only needed if you want to clean up before the sound finishes (e.g., when destroying a GameObject that subscribed to events).

---

### AudioMultiHandle

**Namespace:** `AudioSystem`
**Description:** Controls multiple synchronized voices (multi-position playback).

#### Properties

```csharp
public string EventName { get; }
public AudioEvent SourceEvent { get; }
public bool IsPaused { get; }
public bool isPlaying { get; }
public float time { get; }
public float duration { get; }
public int VoiceCount { get; }
public bool HasVoices { get; }
public MultiPositionType PositionType { get; }
```

---

#### Events

```csharp
public event System.Action OnStarted;
public event System.Action OnLoop;      // declared, but not raised in this version
public event System.Action OnStopping;
public event System.Action OnFinished;
```
Same meaning as on `AudioHandle`.

---

#### Global Methods (All Voices)

##### SetVolumeScale / SetVolumeAbsolute
```csharp
public void SetVolumeScale(float scale)
public void SetVolumeAbsolute(float linear)
```
**Description:** Same as on `AudioHandle`, applied to every voice. `SetVolumeAbsolute` keeps each emitter's relative balance. `SetVolume(float)` is obsolete and forwards to `SetVolumeAbsolute`.

##### SetPitchOffset / SetPitchAbsolute
```csharp
public void SetPitchOffset(float semitones)
public void SetPitchAbsolute(float semitones)
```
**Description:** Same as on `AudioHandle`, applied to every voice. The offset keeps each voice's randomization and Decorrelated nudge; the absolute pitch replaces them. `SetPitch(float)` is obsolete and forwards to `SetPitchAbsolute`.

##### Stop
```csharp
public void Stop(float fadeTime = 0.1f)
```
**Description:** Stops all voices with fade.

##### Pause / Resume
```csharp
public void Pause()
public void Resume()
```
**Description:** Pauses/resumes all voices.

##### Dispose
```csharp
public void Dispose()
```
**Description:** Cleans up event handlers and voice references.

---

#### Per-Emitter Methods

These methods take an **emitter index**: the position's index in the array (or emitter list) the post was given. Each one acts on every voice that emitter started. If the container starts several voices per play (a multi-clip Routing, a Blend), all of an emitter's layers are affected together. The index does not shift when other voices end.

##### SetVoiceVolumeScale
```csharp
public void SetVoiceVolumeScale(int emitterIndex, float scale)
```
**Description:** Scales one emitter relative to how it was authored (idempotent). `SetVoiceVolume` is deprecated and forwards here.

##### SetVoicePitchOffset / SetVoicePitchAbsolute
```csharp
public void SetVoicePitchOffset(int emitterIndex, float semitones)
public void SetVoicePitchAbsolute(int emitterIndex, float semitones)
```
**Description:** The pitch methods for one emitter. `SetVoicePitch` is obsolete and forwards to `SetVoicePitchAbsolute`.

##### StopVoice
```csharp
public void StopVoice(int emitterIndex, float fadeTime = 0.1f)
```
**Description:** Stops one emitter with fade.

##### PauseVoice / ResumeVoice
```csharp
public void PauseVoice(int emitterIndex)
public void ResumeVoice(int emitterIndex)
```
**Description:** Pauses/resumes one emitter.

---

#### Position Methods

##### UpdatePositions
```csharp
public void UpdatePositions(Vector3[] newPositions)
public void UpdatePositions(Transform[] newTransforms)
```
**Description:** Updates emitter positions, one entry per emitter. Every voice an emitter started moves with it.

##### RefreshPositions
```csharp
public void RefreshPositions()
```
**Description:** Re-reads positions from tracked transforms.

##### GetVoicePosition
```csharp
public Vector3? GetVoicePosition(int emitterIndex)
```
**Description:** Gets the position of one emitter.

**Returns:** Position, or `null` if that emitter has no live voice.

##### GetAllPositions
```csharp
public Vector3[] GetAllPositions()
```
**Description:** Gets positions of all voices, one entry per voice. An emitter whose container started several voices appears once for each of them.

## Parameters

Source: https://peppersfx.com/docs/api/parameters/

Explained in USER_GUIDE Manual §3.4. A sound reads a parameter's value from its play (handle), else its emitter, else the global scope, else the parameter's default.

### AudioParameter

**Namespace:** `AudioSystem`
**Inheritance:** `ScriptableObject`
**Menu:** Create > Audio System > Parameter

| Field | Description |
|---|---|
| `valueFrom` | Where the value comes from: `Game` (default: set by code, in three scopes), or a built-in Pepper works out per sound: `Distance` (m to the listening point), `ApproachSpeed` (m/s closing, + coming closer, eased over 50 ms), `Angle` (° on the horizontal plane: 0 ahead, + right, ±180 behind). A built-in ignores game writes (one warning per asset), clamps to the range, has no smoothing, and reads its default where there is no sound to measure. |
| `parameterName` | The name it answers to in the string API and in Blends that name a parameter. Empty = the asset's name. |
| `unitLabel` | Display only: RPM, m/s, 0-1. |
| `minValue`, `maxValue` | The range. Values are clamped when read, kept as written. One warning per asset for a write outside it. |
| `defaultValue` | Read when no scope has a value. |
| `slew` | Smoothing: how fast what sounds hear follows a written value ([ParameterSlew](#parameterslew)). Applies to writes through the asset, in every scope separately. The string API is never smoothed. |
| `bypassSlewWhile` | Optional on/off parameter: while it reads 0.5 or more in the same scope, the smoothing is skipped. |

```csharp
public string ParameterName { get; }   // parameterName, or the asset's name when empty
public string UnitLabel { get; }
public float Min { get; }              // swapped min/max are read the right way round
public float Max { get; }
public float Default { get; }          // clamped to the range
public ParameterSlew Slew { get; }
public AudioParameter BypassSlewWhile { get; }
public ParameterSource ValueFrom { get; }   // Game, Distance, ApproachSpeed, Angle
public bool IsBuiltIn { get; }             // ValueFrom isn't Game
public float Clamp(float value)
```

### AudioAttenuation

**Namespace:** `AudioSystem`
**Inheritance:** `ScriptableObject`
**Menu:** Create > Audio System > Attenuation

How a 3D sound changes with distance from the listening point, shared between containers (USER_GUIDE §4.1, "Attenuation assets"). Set in a container's 3D Settings, where it replaces Min Distance, Max Distance and Rolloff; children take it with Uses Parent Positioning.

| Field | Description |
|---|---|
| `maxDistance` (m) | Where the curves end. Past it a voice is made virtual (with LOD on), and real again inside 95% of it. The curves' last values hold beyond it. |
| `volumeDb` | Volume in dB against metres. Default: 0 dB to 2 m, −6 dB per doubling, −60 dB at 100 m, straight lines between keys. |
| `lowPass`, `lowPassHz` | Optional low-pass cutoff in Hz against metres (octaves between keys). |
| `highPass`, `highPassHz` | Optional high-pass cutoff in Hz against metres. |
| `spread`, `spreadCurve` | Optional spread 0 (a point) to 1 (fully wide) against metres. |

```csharp
public float MaxDistance { get; }
public AnimationCurve VolumeDb { get; }
public bool UsesLowPass { get; }   public AnimationCurve LowPassHz { get; }
public bool UsesHighPass { get; }  public AnimationCurve HighPassHz { get; }
public bool UsesSpread { get; }    public AnimationCurve Spread { get; }
public bool HasFilters { get; }               // low- or high-pass on: its voices are updated every frame
public float VolumeDbAt(float metres)
public float GainAt(float metres)             // linear 0..1
public float LowPassAt(float metres)          // open (22000) when off
public float HighPassAt(float metres)         // open (10) when off
public float SpreadAt(float metres)           // 0 when off
```

**How it plays (Unity spatial mode, the default).** A 3D voice with an asset plays with `rolloffMode = Custom`, `maxDistance` = the asset's, and the volume and spread curves converted to Unity's custom curves (`AudioSource.SetCustomCurve`, over distance ÷ Max Distance; spread as angle ÷ 360, so 1 = 180°), set only when the voice's asset changes. Unity applies them while mixing, from its AudioListener; keep it on the listening point (`DriveUnityListener`). Pepper sets the low- and high-pass from each voice's own distance to the listening point every frame (eased about 20 ms), combined with Parameter Curves (lowest low-pass, highest high-pass). The voice's importance uses `GainAt(distance)`. The pool puts the source back to Logarithmic and spread 0.

### ParameterSlew

**Namespace:** `AudioSystem` (serializable struct)

```csharp
public SlewMode mode;        // None, Rate, Ease
public float upSeconds;      // Ease: seconds to close 95% of a rise (0 = at once)
public float downSeconds;    // Ease: seconds to close 95% of a fall
public float upRate;         // Rate: units per second rising (0 = at once)
public float downRate;       // Rate: units per second falling

public static ParameterSlew None { get; }
public static ParameterSlew Ease(float upSeconds, float downSeconds)
public static ParameterSlew Rate(float upRate, float downRate)
public bool IsSmoothing { get; }
public float Step(float current, float target, float dt)   // one step, for tools and tests
```

**Ease** moves `current += (target - current) * (1 - 0.05^(dt / T))`, so the gap closes by 95% every `T` seconds however the time is split into frames. **Rate** moves at most `rate * dt` per step and stops on the target. Smoothing runs in the manager's per-frame step on unscaled time. The first value a scope gets is heard at once; `Snap` skips the smoothing.

### AudioEmitter

**Namespace:** `AudioSystem`
**Inheritance:** `MonoBehaviour` (sealed; one per GameObject)
**Menu:** Add Component > Audio System > Audio Emitter

An object that makes sounds and holds parameter values for them (one car). Sounds posted on it read its values before the global ones.

```csharp
public AudioHandle Post(AudioEvent audioEvent)    // same as audioEvent.Post(this)
public AudioHandle Post(AudioEvent audioEvent, string point)   // at a named point; same as audioEvent.Post(this, point)
public AudioHandle Post(AudioEvent audioEvent, int point)      // by number (FindPoint); -1 = the origin
public AudioHandle Post(AudioEvent audioEvent, PostValues values)                // values for that sound only
public AudioHandle Post(AudioEvent audioEvent, string point, PostValues values)
public AudioHandle Post(AudioEvent audioEvent, Vector3 localOffset, PostValues values = default)   // anywhere on it (an impact)
public AudioHandle Post(AudioEvent audioEvent, double startDsp, double startOffsetSeconds,
                        PostValues values = default)   // a moment of the sound at a DSP time (a pass-by)

// Level and pitch against the other emitters (inspector: Volume Offset, Pitch Offset), on every sound on it, now and later
public float VolumeOffsetDb { get; set; }         // dB, 0 = as authored; can't lift a sound past full volume
public float PitchOffsetCents { get; set; }       // cents, 0 = as recorded

// Random numbers (AudioManager.RandomNumbers = Pepper): this emitter's own sequence
public int RandomSeed { get; }                    // 0 = a different sequence every run
public void SetRandomSeed(int seed)               // start again from seed: the same seed replays the same picks

// Named points: offsets in this object's own space (a car's "Exhaust", "Intake", "FrontAxle")
public IReadOnlyList<EmitterPoint> Points { get; }  // EmitterPoint { string name; Vector3 offset; }
public int FindPoint(string point)                // its number, or -1 (the first, if two share a name)
public int SetPoint(string point, Vector3 offset) // add, or move an existing one; later posts only
public Vector3 GetPointOffset(int point)
public Vector3 GetPointPosition(int point)        // world space, now

// Velocity, shared by every sound on it (read by Approach Speed and Pepper's Doppler)
public Vector3 Velocity { get; }                  // measured in Pepper's per-frame step, unless given
public void SetVelocity(Vector3 metresPerSecond)  // give it yourself (a rigidbody's); stops measuring
public void ClearVelocity()                       // measure again
public void Teleport()                            // it jumped (a reset, a respawn): the jump isn't speed

// Switched off or destroyed (inspector: On Disable, Stop Fade Seconds)
public EmitterDisableMode WhenDisabled { get; set; }   // Keep (default, as before), Stop, Pause; read at each post
public float StopFadeSeconds { get; set; }             // seconds, default 0.1

public void SetParameter(AudioParameter parameter, float value)
public void ClearParameter(AudioParameter parameter)
public void RampParameter(AudioParameter parameter, float target, float seconds)
public void SnapParameter(AudioParameter parameter)
public void SnapAllParameters()
public void SetSlewOverride(AudioParameter parameter, ParameterSlew slew)
public void ClearSlewOverride(AudioParameter parameter)
public bool TryGetParameter(AudioParameter parameter, out float value)   // set here, as written
public float GetEffectiveParameter(AudioParameter parameter)             // heard now: here, else global, else default; clamped

// Switches (one car's surface); a driven group ignores them, with a warning
public void SetSwitch(AudioSwitchGroup group, string value)
public void ClearSwitch(AudioSwitchGroup group)
public bool TryGetSwitch(AudioSwitchGroup group, out string value)       // set here
public string GetEffectiveSwitch(AudioSwitchGroup group)                 // here, else global, else the Default Value

// For tools: the values on this emitter
public int ParameterCount { get; }
public string GetParameterNameAt(int index)
public float GetParameterValueAt(int index)     // as heard now (after smoothing)
public float GetParameterTargetAt(int index)    // as written
public bool IsParameterMovingAt(int index)      // ramping, smoothing or easing away
public int SwitchCount { get; }
public string GetSwitchGroupAt(int index)
public string GetSwitchValueAt(int index)

// For tools: every Audio Emitter enabled now (the Live View, a game's debug overlay). Don't change it.
public static IReadOnlyList<AudioEmitter> AllEnabled { get; }
```

- `SetParameter`: the emitter's sounds follow the value through the parameter's smoothing; the first value set here is heard at once.
- `ClearParameter`: the sounds go back to the global value, easing over if the parameter is smoothed.
- `RampParameter` moves the written value in a straight line from the one written before (or what the sounds hear, if none), on unscaled time; smoothing applies on top. A new ramp, a Set, a Snap or a Clear replaces it.
- `SnapParameter` / `SnapAllParameters`: the sounds hear the written value now (a ramp jumps to its end). For a reset or a teleport. Values set on the sounds' handles have their own `SnapAllParameters`.
- `SetSlewOverride`: smooth this emitter's value with other settings than the parameter's (a per-car attack). Affects this emitter's value only.

Values work without an AudioManager (an emitter can be set up before one exists); ramps and smoothing need one to advance.

**Named points.** A sound posted at a point is attached to the emitter at the point's offset (in its own space, so its scale applies), its later voices too (a Sequence's next clip), so it moves and turns with the object; a 2D container ignores the place. It reads the emitter's parameter values like any sound on it. An unknown name warns once per name and plays at the origin. `SetPoint` changes later posts; sounds already playing stay where they were attached. `AudioEvent.Post(AudioEmitter, string point, double scheduledDspTime = 0.0)` and `Post(AudioEmitter, int point, double scheduledDspTime)` (the DSP time has no default there: `Post(emitter, 1)` is the older overload with a DSP time) and `AudioManager.Post(audioEvent, emitter, point)` do the same. In the inspector, the points are listed and can be dragged in the Scene view while the object is selected.

**Posting at an offset** (3.1.0-dev.7). `Post(evt, localOffset, values)` is a named point anywhere: an impact at the contact point, with this emitter's values, Max Instances Per Emitter, Cooldown Per Emitter and random numbers (`AudioEvent.PostAtOffset`). A playing sound moves with `AudioHandle.SetLocalOffset` (a scrape following the contact). `Post(evt, startDsp, startOffsetSeconds, values)` is [AudioEvent's timed post](https://peppersfx.com/docs/api/audioevent/#post-a-moment-of-the-sound-at-a-dsp-time).

**Level and pitch** (3.1.0-dev.7). `VolumeOffsetDb` and `PitchOffsetCents` reach every sound on the emitter, playing or posted later, through their own gain and pitch slots (`GainStack.EmitterGain`, `PitchStack.Emitter`), and compose with a sound's own offset. Set them in the inspector or from code, also in Play mode. An AudioSource's volume stops at 1, so a raise can't lift a sound already at full level.

**Teleport** (3.1.0-dev.7). After a jump that isn't motion (a reset to the track, a respawn, a remote car placed), `Teleport()`: Pepper's next step takes the new position and measures nothing from the jump, so Approach Speed and Doppler don't spike. The last velocity stays until a new one is measured; a velocity given with `SetVelocity` is kept. It doesn't touch parameter values: call `SnapAllParameters` too if they jump.

**Switched off or destroyed.** `WhenDisabled` (`EmitterDisableMode`):
- `Keep` (default): as before 3.1. 3D sounds are attached to the object: switched off, Unity stops them with it (a loop is never reclaimed); destroyed, they are cut with a warning and Pepper rebuilds their voices.
- `Stop`: switched off or destroyed, every sound posted on it fades out over `StopFadeSeconds` where it is, with whatever it was still going to start (Delay actions, a Sequence's next clip), and goes back to the pool.
- `Pause`: switched off, its sounds fade out over about 25 ms and hold their place, keeping no real voice; switched on, they carry on from there, in phase. Destroyed, they stop with the fade.

With `Stop` or `Pause`, its sounds aren't attached: they follow the object (position and rotation, at their point), moved by Pepper every frame after every LateUpdate and before Unity mixes, so a fade can outlive the object. While it is off, posts on it return a finished handle and play nothing. The setting is read at each post; sounds already playing keep the way they were attached.

**Example:**
```csharp
AudioEmitter car = GetComponent<AudioEmitter>();
AudioHandle engine = car.Post(engineEvent);
car.SetParameter(rpm, 4200f);   // only this car's engine

car.WhenDisabled = EmitterDisableMode.Stop;   // removed from car select: its sounds fade out, not cut
```

```csharp
public enum EmitterDisableMode { Keep, Stop, Pause }
```

### AudioSwitchGroup

**Namespace:** `AudioSystem`
**Inheritance:** `ScriptableObject`
**Menu:** Create > Audio System > Switch Group

A switch that Switch Containers read (a surface, a weather), with its values. A sound reads its handle's value, else its emitter's, else the global one, else `Default` (USER_GUIDE §4.5).

| Field | Description |
|---|---|
| `groupName` | The name it answers to in the string API (`AudioManager.SetSwitch`, state and event actions) and in Switches that name a group. Empty = the asset's name. |
| `values` | The values it can take. Switch inspectors offer them; a value set that isn't here warns once. Empty = any. |
| `defaultValue` | Read when nothing is set. Empty = none (the Switch plays its Default Container). |
| `drivenBy` | Optional Parameter asset that picks the value through `ranges`, read in each sound's scopes. Values set directly are then ignored, with one warning. |
| `ranges` | `SwitchRange { string value; float from; }`: each value from its start up to the next one's; the first also covers below. Kept sorted. |
| `hysteresis` | How far past a boundary (in the parameter's unit) the parameter must go to change the value. Each playing sound remembers its own range. |

```csharp
public string GroupName { get; }
public IReadOnlyList<string> Values { get; }
public string Default { get; }
public AudioParameter DrivenBy { get; }
public IReadOnlyList<SwitchRange> Ranges { get; }
public float Hysteresis { get; }
public bool IsDriven { get; }                  // DrivenBy set and at least one range
public bool HasValue(string value)             // in Values, or Values is empty
public string ValueFor(float parameterValue)   // the ranges, without hysteresis
```

## AudioContainer (Base)

Source: https://peppersfx.com/docs/api/audiocontainer-base/

**Namespace:** `AudioSystem`
**Inheritance:** `ScriptableObject`
**Abstract:** Yes (use specific container types)

### Properties

```csharp
public string ContainerName { get; }
public string Description { get; }
public List<string> Tags { get; }
public AudioMixerGroup MixerGroup { get; set; }
public bool Is3D { get; }
public float MinDistance { get; }
public float MaxDistance { get; set; }      // the setter writes a runtime override, never the asset
public AudioRolloffMode RolloffMode { get; }
public AudioAttenuation Attenuation { get; } // a shared distance asset (a runtime override first); replaces the three above
public float DopplerLevel { get; set; }     // Unity's Doppler on 3D voices: 1 = Unity's default, 0 = none (0–5)
public DopplerMode Doppler { get; set; }    // Unity (default: DopplerLevel) or Pepper
public float DopplerExaggeration { get; set; }  // Pepper Doppler: ×1–3
public float DopplerMaxCents { get; set; }      // Pepper Doppler: the largest shift either way (0–2400 cents)
public float PitchLimitSemitones { get; }   // 0 = no limit; see PitchStack
public bool HasOverrides { get; }
public bool UsesParentPositioning { get; set; }  // inside a Blend or Switch: take the parent's 3D settings
public bool UsesParentOutput { get; set; }       // inside a Blend or Switch: play through the parent's Mixer Group
public List<ParameterCurve> ParameterCurves { get; }  // volume, pitch and filters driven by parameters
```

`ParameterCurves`: see [ParameterCurve](https://peppersfx.com/docs/api/enums-data-structures/#parametercurve-curveproperty). A container with curves makes its plays update every frame.

`DopplerLevel` (inspector: **Doppler Level**, in 3D Settings) is written to every 3D voice's `AudioSource.dopplerLevel` while `Doppler` is Unity; the pool puts 1 back. Unity's Doppler changes a voice's speed without Pepper seeing it, so a virtual voice can't follow it: on looping layers that must stay in step (engine layers) use Pepper's Doppler, or set 0. The Sound Builder's Doppler Level slider writes it.

`Doppler` (3.1.0-dev.7; inspector: **Doppler**, with **Doppler Exaggeration** and **Doppler Max Cents**): with `DopplerMode.Pepper`, Unity's Doppler Level is 0 on the voices and Pepper writes `PitchStack.Doppler` every step: ratio = c ÷ (c − v), c = 343 m/s, v the play's closing speed on the listening point (its Approach Speed: the emitter's velocity, or the play's measured motion, against the point's, eased over 50 ms), in cents × `DopplerExaggeration`, clamped to ± `DopplerMaxCents`. A play using it joins the per-frame pass. 50 m/s relative swings about 5.1 semitones at ×1. It is applied after the Pitch Limit and kept in a virtual voice's place. See [DopplerMath](https://peppersfx.com/docs/api/audiovoice-audiovoiceenhanced/#dopplermath).

`UsesParentPositioning` and `UsesParentOutput` (inspector: **Parent Settings**) are off by default. When on, a container played inside a Blend or Switch uses that parent's 3D settings (3D on or off, Min/Max Distance, Rolloff, Doppler Level, Doppler and its two settings) or Mixer Group instead of its own; if the parent passes the question on too, it goes up the play's tree until a container answers it. A container's own occlusion, reverb and propagation options always apply. A Blend's or Switch's own settings otherwise never reach its children.

#### Routing / Slot Pool Opt-Ins

```csharp
public bool UseOcclusion { get; }          // raycast occlusion
public bool UsePropagation { get; }        // propagation cutoff (composes with raycast via min-wins)
public bool AllowReverbSend { get; }       // per-zone reverb sends
public float ReverbSendLevelDb { get; }    // per-container reverb send level (dB)
public bool StaticEmitter { get; }         // hint: this voice doesn't move during playback
public ReverbSendBus ExplicitReverbBus { get; }  // override zone-driven send routing
```

Setting any of `UseOcclusion`, `UsePropagation`, or `AllowReverbSend` to true causes the container to acquire an [OcclusionSlot](https://peppersfx.com/docs/api/occlusion-mixer-slots/#occlusionslot) at play time. The slot carries the low-pass and the reverb sends; occlusion's and propagation's volume drop is written to the voice and applies even when no slot is available. See [Manual chapter 14](https://peppersfx.com/docs/manual/occlusion-mixer-slot-pool/) for the slot pool architecture and chapter 15 for per-zone reverb sends.

`StaticEmitter` and `ExplicitReverbBus` are modifiers, not feature flags — they refine the behavior of the reverb-send driver but don't on their own cause a slot to be acquired.

---

### Methods

#### Play
```csharp
public abstract AudioVoice Play(Vector3 position = default, GameObject parent = null)
public AudioVoice Play(Vector3 position, GameObject parent, List<AudioVoice> spawned)
```
**Description:** Plays the container. Containers that start several voices at once (a Routing container with more than one clip, every layer of a Blend, whatever a Switch selects) start all of them in both overloads. The first overload returns only the **primary** (first) voice. The second also appends **every** voice it started to `spawned`, primary first. Use the second when you need to control the whole sound. It also sets `AudioVoice.RootContainer` to this container on each of those voices.

**Returns:** The primary `AudioVoice`, or `null` if nothing played.

**Custom containers:** override the single-voice `Play`. If your container starts several voices per play, also override `protected virtual AudioVoice PlayInto(List<AudioVoice> spawned, Vector3 position, GameObject parent)`, and implement the single-voice `Play` as `Play(position, parent, new List<AudioVoice>())`. Override `EstimateVoiceCount` too (below).

#### EstimateVoiceCount
```csharp
public virtual int EstimateVoiceCount()
```
**Description:** How many voices one play of this container starts at once, at most. An event makes room for this many before it plays the container, and skips the play without stealing anything if it can't. 1 by default (a Sequence plays one clip at a time); a Routing container counts its entries with a clip or an address, a Blend adds up its layers' estimates, a Switch takes the largest of its choices. A play that starts more voices than its estimate still gets them, each stealing a whole play if the pool is full.

**One play, one start time.** All the voices a play starts are scheduled on one DSP time: one buffer ahead for a single voice, two for a play of several (so a walk through many layers can't straddle a buffer), or the post's explicit DSP time. A voice a container starts later (a Sequence's next clip) starts one buffer ahead of when it starts.

#### Stop / StopImmediate
```csharp
public abstract void Stop()
public abstract void StopImmediate()
```
**Description:** Stops **every play** of this container asset (with or without fade), including paused and virtualized voices. A SequenceContainer also ends its auto-advance run. Only voices the container still owns are stopped; a voice that has since been reused by another sound is left alone. To stop **one** play, stop its `AudioHandle`.

**Concurrent plays:** every container can be playing several times at once. BlendContainer used to stop its previous play on every post; it no longer does (set Max Instances 1 on the event to restart instead). A SequenceContainer keeps one position and one auto-advance run per asset; see USER_GUIDE §4.4.

#### Runtime Override Methods
```csharp
public void SetOverride(ContainerOverrides overrides)
public void SetOverride3D(bool value)
public void ClearOverrides()
```
**Description:** Apply or clear non-serialized runtime 3D setting overrides. These do not persist to the asset.

**Example:**
```csharp
// Override 3D settings at runtime
var overrides = new AudioContainer.ContainerOverrides
{
    is3D = true,
    minDistance = 2f,
    maxDistance = 30f
};
myContainer.SetOverride(overrides);

// Or just toggle 3D
myContainer.SetOverride3D(true);

// Clear all overrides
myContainer.ClearOverrides();
```

#### Voice Query Methods
```csharp
public AudioSource GetFirstActiveSource()
public bool HasActiveVoices()
public int GetActiveVoiceCount()
```
**Description:** Query the state of voices currently playing from this container.

---

### ContainerOverrides (Nested Struct)

```csharp
public struct ContainerOverrides
{
    public bool? is3D;
    public float? minDistance;
    public float? maxDistance;
    public AudioRolloffMode? rolloffMode;
    public AudioAttenuation attenuation;   // in place of the container's own (null = no override)
    public void Clear();
}
```
Overrides are never saved to the asset. `MaxDistance`'s setter writes `maxDistance` here.

## Container Types

Source: https://peppersfx.com/docs/api/container-types/

### RoutingContainer

**Menu:** Create > Audio System > Routing Container

#### Properties

```csharp
public List<AudioClip> AudioClips { get; }
public float Volume { get; }
public bool Loop { get; }
```

**Description:** Plays all assigned clips simultaneously. Use for layered sounds (e.g., explosion = blast + debris + shockwave).

**Factory Method (Editor Only):**
```csharp
public static RoutingContainer CreateNew(string name, AudioClip clip, float vol = 1f, bool looping = false, bool is3D = false)
```

---

### RandomContainer

**Menu:** Create > Audio System > Random Container

#### Properties

```csharp
public List<WeightedAudioClip> AudioClips { get; }
public int AvoidRepeatLast { get; }
public bool UseWeighting { get; }
public float Volume { get; }
public bool Loop { get; }
```

#### Methods

```csharp
public void ClearHistory()
```
**Description:** Clears the repeat-avoidance history: the shared one and every emitter's.

**Avoid Repeat Last** keeps one history per [AudioEmitter](https://peppersfx.com/docs/api/parameters/#audioemitter) the container is posted on, so a car never repeats its own last clips whatever other cars played, and one shared history for posts without one. A networked post (inside an `AudioRandomScope`) ignores and doesn't record it. Picks draw from Pepper's random numbers (see `AudioManager.RandomNumbers`) and allocate nothing. At or above the clip count it does nothing (every clip stays available); `OnValidate` warns about it from two clips up.

**Description:** Randomly selects one clip per play, with weighting and repeat avoidance.

---

### SequenceContainer

**Menu:** Create > Audio System > Sequence Container

#### Properties

```csharp
public List<SequenceEntry> Entries { get; }
public SequenceContainer.PlaybackMode SequencePlaybackMode { get; }
public bool LoopSequence { get; }
public bool AutoAdvance { get; set; }
public float Volume { get; }
```

#### PlaybackMode (Nested Enum)

```csharp
public enum PlaybackMode
{
    Forward,   // 0->1->2->3->0...
    Reverse,   // 3->2->1->0->3...
    PingPong,  // 0->1->2->3->2->1->0...
    Random     // Random order
}
```

#### Methods

```csharp
public void ResetSequence()
public void SetIndex(int index)
public AudioVoice PlayNext(Vector3 position = default, GameObject parent = null)
```

**Description:** Plays clips in sequence. `PlayNext()` advances the sequence and plays the next clip. `AutoAdvance` controls whether the sequence auto-advances after each clip finishes.

---

### SwitchContainer

**Menu:** Create > Audio System > Switch Container

#### Properties

```csharp
public AudioSwitchGroup SwitchGroup { get; }       // the group asset, or null (then switchGroupName)
public string SwitchGroupName { get; }             // the asset's GroupName, or the name field
public List<SwitchEntry> SwitchEntries { get; }
public AudioContainer DefaultContainer { get; }
public SwitchChangeMode WhenSwitchChanges { get; } // NextPlayOnly (default), Crossfade, Restart
public float CrossfadeTime { get; }                // Crossfade only, seconds (unscaled); default 0.15
public float Volume { get; }
```

#### Methods

```csharp
public void SetSwitch(string switchValue)          // sets the group's GLOBAL value (also before the first play)
public string GetCurrentSwitch()                   // the value the last play of this asset picked
public AudioContainer GetActiveContainer()         // the container the last play of this asset picked
```

**Description:** Selects a child container by the switch group's value in the play's scopes (handle, emitter, global, the group's Default). The child plays as part of the same play, under its own node in the play's tree: a Blend under it reads its parameter in that play's scopes, and a Sequence under it reports later clips to the same handle. Every voice the child starts, later ones included, gets the Switch's Volume.

**When the value changes while it plays** (`WhenSwitchChanges`): `NextPlayOnly` keeps the choice (the next play picks the new value). `Crossfade` and `Restart` put the play in the per-frame pass, which reads the value every frame. On a change, the new choice plays from its start under a new node of the same play, as late voices of the handle (no second `OnStarted`); with Crossfade both fade along equal-power curves in `GainStack.SwitchGain`, with Restart the old one fades out as a steal does (the Audio Manager's Steal Fade Seconds, 0.025 s by default and at least three frames; 0 cuts it a few ms ahead) and the new one starts at full level. A choice still fading out that is chosen again fades back up. A choice faded to silence stops two DSP buffers later, and nothing more starts in it (a Sequence there stands down). Room is made for the new voices without stealing this play; if the pool can't, the old voices stop at once and the new ones take them. A virtual play's new voices start virtual. A paused play doesn't follow until resumed. A value with nothing to play fades the play to silence and holds it alive. A Switch only follows if its first choice played something.

---

### BlendContainer

**Menu:** Create > Audio System > Blend Container
**Implements:** `IRTPCListener`

#### Properties

```csharp
public List<BlendEntry> BlendEntries { get; }
public AudioParameter BlendParameter { get; }   // wins over the name when set
public string BlendParameterName { get; }       // the asset's ParameterName when one is set
public float Volume { get; }
public BlendLoopMode LoopMode { get; set; }           // FromLayers (default), ForceLoop, ForceOneShot
public SilentLayerBehaviour SilentLayers { get; set; } // KeepPlaying (default) or Virtualize
public float SilentThresholdDb { get; set; }          // Virtualize: a layer below this goes virtual (-60; -90..-20)
public const float SilentHysteresisDb = 6f;           // ...and comes back this far above it
[Obsolete] public bool Loop { get; }                  // never read; see LoopMode
public BlendLayout Layout { get; set; }               // VolumeCurves (default) or Regions
public CrossfadeShape Crossfade { get; set; }         // Regions: Linear, EqualPower (default), SCurve
public AudioParameter PitchFollowParameter { get; set; } // each layer plays at value ÷ its rootValue
public float AutoLayoutFade { get; }                  // share of each gap between roots a crossfade covers
public float TuningWarningSemitones { get; }          // the inspector's tuning check threshold
public IReadOnlyList<AudioVoice> LayerVoices { get; }
```

#### Methods

```csharp
public float GetCurrentBlendValue()             // what a play with no emitter or handle value reads
public void AutoLayout()                        // regions from the entries' rootValue (Regions layout)
[Obsolete] public void UpdateBlend(float blendValue)   // sets the parameter's global value
public void OnRTPCChanged(string parameter, float value)
```

**Layouts.** `VolumeCurves`: each entry's `volumeCurve` sets its level (0–1) against the Blend's parameter, as before. `Regions`: each entry plays between `regionMin` and `regionMax`, fading in over `fadeInWidth` and out over `fadeOutWidth` in the `Crossfade` shape; `AutoLayout` places the regions half way between neighbouring entries' `rootValue`s, each crossfade covering `AutoLayoutFade` of the gap, the lowest reaching the parameter's Min and the highest its Max. Equal Power keeps the summed power at 1 (unrelated recordings); Linear and S-Curve keep the summed level at 1.

**Pitch follow.** With `PitchFollowParameter` set, each entry with `followPitch` and a `rootValue` plays at value ÷ `rootValue`, clamped to ±`followRangeSemitones`, in the pitch stack's `Follow` slot. Entries' `curves` apply to that layer only.

**Loop Mode.** `FromLayers`: each layer loops as its own container says (as before). `ForceLoop` / `ForceOneShot`: every layer's voices loop / don't, later voices included. A nested Blend left at `FromLayers` takes the outer one's. The old `loop` field is hidden and never read; Sound Builder (Simple) writes `LoopMode` (Loop ticked = `ForceLoop`, unticked = `FromLayers`).

**Silent layers.** `Virtualize`: each frame, a layer voice whose own level (`BaseGain × MultiplierGain × RtpcGain × CurveGain`: its volume, the crossfade and curves; not bus, occlusion, fades or crossfades) is below `SilentThresholdDb` is made virtual and held so while it stays below `SilentThresholdDb + SilentHysteresisDb`; it keeps its place in the clip and comes back in step. A layer silent at the start starts virtual. It is never stolen on its own: steals take whole plays. A nested Blend left at `KeepPlaying` takes the outer one's.

**One start time.** Every voice of a play is scheduled on the play's start time: two DSP buffers ahead for a play of several voices (one for a single voice), or the post's explicit DSP time.

**Description:** Plays multiple containers, each layer at a level set by its curve against one parameter. **Each play reads the parameter in its own scopes** (handle, emitter, global, default), so two copies posted on two emitters blend independently. The layers follow the value once a frame, in Pepper's per-frame step (see `AudioManager.UpdateMode`). With a `BlendParameter` asset, the curves' X axis is in its unit and values are clamped to its range; with only a name, values are clamped to 0–1. Any container can be a layer, Blends and Switches included: each nested Blend reads its own parameter in the same play's scopes, and a layer under several Blends gets the product of their curves. Voices a layer starts later (a Sequence's next clip) get the curves and the Blend's Volume too. Only plays with a Blend in their tree are evaluated each frame.

The Blend no longer registers as an RTPC listener. `OnRTPCChanged` is kept for code that calls it: with the Blend's parameter name it sets that parameter's global value. `UpdateBlend` is obsolete and does the same.

---

### GeneratorContainer (Unity 6000.3 and later)

**Namespace:** `AudioSystem.Generators` · **Assembly:** `SFXSystem.Generators`, which compiles only on Unity 6000.3 and
later (its `SFXSYSTEM_GENERATORS` define comes from the editor version). On earlier versions nothing here exists.
**Implements:** `UnityEngine.Audio.IAudioGenerator`

An abstract container whose sound is computed while it plays instead of read from a clip: the container is itself the
Unity 6.3 generator its voice's AudioSource plays. Pepper's engine generators (the granular engine and the additive
layer, in development) derive from it; so can your own.

```csharp
public float Volume { get; }
public abstract int ParameterCount { get; }                 // at most GeneratorValues.Capacity (8)
public abstract AudioParameter GetParameter(int index);     // value i of what each voice is sent; null reads 0
protected abstract GeneratorInstance CreateGenerator(ControlContext context, AudioFormat? nestedFormat,
                                                     ProcessorInstance.CreationParameters creationParameters);
```

**How it plays.** A voice from Pepper's pool, like any container, so buses, volume, the pitch stack, Doppler, Pepper's
panning, the voice filters, stealing, pause, virtual voices and Blend nesting all apply. The AudioSource's `loop` is
on: it plays until it is stopped (`EstimateDuration` reports it as a loop). It reports `isRealtime` false, so the
AudioSource's pitch resamples it. A virtual voice is paused: it isn't processed, and it carries on from where it was.
When the voice goes back to the pool its generator is cleared.

**Values.** Every step, after the plays are evaluated, each playing voice is sent a `GeneratorValues` message:
`GetParameter(i)` read in that voice's own play (its handle, then its emitter, then the global value, then the
default; after smoothing; clamped; a built-in from the play's place). Two cars on one engine asset each get their own
RPM. A paused voice is sent nothing until it resumes. A value is heard about one DSP buffer after it is sent. Each
message also carries `Seconds`, the unscaled time of the step that sent it.

**Writing a generator.** Allocate an unmanaged real-time struct with Pepper's control half:

```csharp
protected override GeneratorInstance CreateGenerator(ControlContext context, AudioFormat? nestedFormat,
                                                     ProcessorInstance.CreationParameters creationParameters)
    => context.AllocateGenerator(new MyRealtime(), new GeneratorControl<MyRealtime>(), nestedFormat, creationParameters);
```

- **`IGeneratorRealtime`** (extends Unity's `GeneratorInstance.IRealtime`): `Configure(int sampleRate)` before the first
  buffer, `Dispose()` when the instance goes, plus Unity's `Process` (fill the buffer, mono) and `Update`. In `Update`,
  `GeneratorValues.Receive(context, pipe, ref latest, out float seconds)` returns true when new values have arrived,
  with the time all the steps that sent them covered (a buffer often brings two frames' values, or none). Move from the
  old values to the new ones over that time, plus what was left of the last move, not across one buffer: frames and
  buffers don't line up, so a ramp per buffer moves a value the game changes every frame in uneven steps. Pepper's
  engines do this. Allocate nothing managed on this side.
- **`GeneratorControl<TRealtime>`**: sets the output to mono at the system's rate and passes each `GeneratorValues`
  straight down to the real-time half.
- **`GeneratorValues`**: `Count`, an indexer, `Capacity` = 8, `Seconds` (the step's unscaled time; after
  `3.1.0-dev.11`), and `Receive` (with or without `seconds`).

#### GrainTable

One engine sweep cut into grains, one engine cycle (two turns, 120 ÷ RPM seconds) each, for the granular player. Made
by the Engine Grains window, not by hand. It keeps a reference to the sweep clip (which must be Decompress On Load) and,
per grain, where it starts and how long it is (frames at the clip's rate) and the RPM its length means.

```csharp
public AudioClip Sweep { get; }
public IReadOnlyList<GrainTable.Grain> Grains { get; }   // Start, Length, Rpm; in the sweep's order
public int PeriodsPerCycle { get; }                       // periods of the fundamental in one cycle
public float MinRpm { get; }
public float MaxRpm { get; }
public GrainTable.RpmSource Source { get; }               // Known (typed) or FromPitch
public float FromRpm { get; }
public float ToRpm { get; }
public GrainTable.RpmCurve Curve { get; }                 // Known: StraightLine or EvenPitch
public int Cylinders { get; }
```

`RpmCurve` is how a typed RPM moves between From and To: **StraightLine** (the same RPM every second) or **EvenPitch**
(the same number of semitones every second, as most synthesisers sweep: the RPM multiplies by the same factor).

#### GranularEngine

**Menu:** Create > Audio System > Granular Engine (Unity 6.3+) · **Extends:** GeneratorContainer

A car engine played grain by grain from Grain Tables. At the end of each grain it takes the grain whose RPM is nearest
the car's, picked at random among up to Variation grains either side that are within half a semitone (never the same
one twice in a row), and resamples it to land exactly on the RPM, sample by sample by the RPM the sweep had there (a
line through the grain's RPM at its middle, at the pace its neighbours climb), so a held RPM holds its pitch through
the grain. The RPM and load move to each step's values over that step's time. Each grain fades into the next over
Crossfade Ms with gains that sum to 1 (the grains are cut in phase). The on-load and off-load sweeps blend by load at equal power;
the idle loop takes over below the sweeps' lowest RPM, at equal power from Idle Rpm. The AudioSource's pitch (Doppler,
pitch offsets) applies on top.

```csharp
public AudioParameter Rpm { get; }        // value 0: the car's RPM
public AudioParameter Load { get; }       // value 1: 0 off load to 1 on load; null = on load only
public GrainTable OnLoad { get; }         // the climbing sweep
public GrainTable OffLoad { get; }        // optional: the falling sweep
public AudioClip Idle { get; }            // optional: an idle loop (Decompress On Load)
public float IdleRpm { get; }             // the RPM the idle loop was recorded at (900)
public float CrossfadeMs { get; }         // 1–10, default 3
public int Variation { get; }             // 0–8, default 2
```

The sweeps' and idle's samples are loaded into memory when a voice starts and stay loaded while the engine asset is;
they are read again after a new analysis. With no Grain Table (and no idle) a post plays nothing and warns once.

#### AdditiveEngine

**Menu:** Create > Audio System > Additive Engine (Unity 6.3+) · **Extends:** GeneratorContainer

An engine's firing orders as sine tones, for weight under a loop engine or a granular one (as a layer in a Blend); not a
whole engine. Order 1 is the firing frequency, RPM × Cylinders ÷ 120. Each order's level moves from its off-load to its
on-load level with the load. A little noise, low-passed at Noise Brightness times the firing frequency, takes the edge
off. Orders at 45% of the output's sample rate or above are left out; at RPM 0 it is silent.

```csharp
public AudioParameter Rpm { get; }                       // value 0
public AudioParameter Load { get; }                      // value 1; null = on load
public int Cylinders { get; }                            // 1–16: the scale of order 1
public IReadOnlyList<AdditiveEngine.Order> Orders { get; } // order, offLoad, onLoad (0–1); the first 16 play
public float NoiseOffLoad { get; }                       // the noise's RMS off load
public float NoiseOnLoad { get; }                        // and on load
public float NoiseBrightness { get; }                    // 1–32 × the firing frequency
public const int MaxOrders = 16;
```

#### GeneratorCost

What Pepper's generators cost on the mixing thread, measured where they run, a build included (for the Steam Deck).
While `Measuring` is off, each generator buffer only checks a flag.

```csharp
public static bool Measuring { get; set; }              // switching it on starts a new measurement
public static long Buffers { get; }                     // buffers measured, all generators together
public static double Milliseconds { get; }              // their time on the mixing thread
public static double MicrosecondsPerBuffer { get; }
public static double Seconds { get; }                   // since the measurement started
public static double CoreSharePerInstance(int instances) // 0–1
public static string Report(int instances)              // one line for the log
public static void Reset()
```

Generator containers also show in the tools: the Audition gives their parameters sliders and plays them outside Play
mode, the Container Validator checks them (and counts them as loops for its Persistent note), and the debug windows
name a generator voice "(generated)".

## AudioBus

Source: https://peppersfx.com/docs/api/audiobus/

**Namespace:** `AudioSystem`
**Inheritance:** `ScriptableObject`

### Properties

```csharp
public string BusName { get; }
public AudioBus ParentBus { get; }
public AudioMixerGroup MixerGroup { get; }
public float VolumeDb { get; }                        // the asset's Volume (SetVolume)
public float VolumeMultiplier { get; }
public float StateOffsetDb { get; }                   // what Offset states add now (runtime only)
public float PlayerVolumeDb { get; set; }             // the player's volume, -80…+24 dB (runtime only)
public bool Mute { get; }
public bool IsMuted { get; }                          // this bus or a parent is muted
public bool Solo { get; }
public IReadOnlyList<EffectSend> Sends { get; }
public bool EnableDucking { get; }
public IReadOnlyList<DuckingTarget> DuckingTargets { get; }
public float DuckingAttack { get; }
public float DuckingRelease { get; }
public AudioTimeMode DuckingTimeMode { get; set; }    // the clock a duck on this bus runs on: Scaled (default) or Unscaled
public BusPauseBehaviour WhilePaused { get; set; }    // a sound posted while paused: DropOneShots (default) or Hold
public bool IsPaused { get; }                         // this bus or a parent is paused
public List<ParameterCurve> ParameterCurves { get; }   // Volume (dB), Low Pass and High Pass (Hz); global scope
public string LowPassParameter { get; }               // the exposed mixer cutoff Low Pass curves write
public string HighPassParameter { get; }              // the exposed mixer cutoff High Pass curves write
public float CurveVolumeGain { get; }                 // the curves' level now, linear (part of GetFinalVolume)
public float LowPassHz { get; }                       // the low-pass cutoff Pepper sets now (22000 = open)
public float HighPassHz { get; }                      // the high-pass cutoff Pepper sets now (10 = open)
public int MaxRealVoices { get; set; }                // its real-voice cap, 0 = none (3.1.0-dev.8)
public int RealVoiceCount { get; }                    // real voices of its sounds and its child buses' now
```

**Max Real Voices** (3.1.0-dev.8, USER_GUIDE §6.9; inspector: **Voices > Max Real Voices**): the most real voices the sounds whose Target Bus is this bus or one of its children may use at once; 0 (the default) = no cap. Over it, the least important of them go virtual, a whole sound at a time, at a sound's start and in the voice pass, like the Audio Manager's Max Real Voices, which still applies; a single sound bigger than the cap keeps its most important voices. It never ends a sound.

**Parameter Curves** (USER_GUIDE §6.6) are evaluated in Pepper's per-frame step from each parameter's global value, after smoothing. Volume multiplies into `GetFinalVolume` (child buses and every assigned voice's `BusGain` follow; the serialized `VolumeDb` is untouched). Low Pass and High Pass ease in octaves over about 20 ms and are written with `AudioMixer.SetFloat` to the bus's Mixer Group under `LowPassParameter` / `HighPassParameter` when they move; with no Mixer Group or no such exposed parameter the bus logs one warning and stops trying. Pitch curves are ignored. The bus inspector's **Add Low Pass / High Pass to Mixer Group** buttons add a Lowpass Simple / Highpass Simple effect and expose its `Cutoff freq`.

---

### Methods

#### Volume & Mute
```csharp
public void SetVolume(float newVolumeDb)
public float GetFinalVolume()
public void SetMute(bool newMute)
public void SetSolo(bool newSolo)
```
**Description:** `GetFinalVolume()` returns the final linear volume including the entire parent bus hierarchy: `VolumeDb + StateOffsetDb + PlayerVolumeDb` as a gain, times `VolumeMultiplier`, the ducking and the curves, times the parent's. It is 0 when this bus or a parent is muted, and while another bus is soloed unless this bus or one of its parents is soloed too. That includes a parent of a soloed bus: it passes the soloed bus through, but its own `GetFinalVolume()` is 0, so the sounds posted straight to it are silent. `SetVolume` writes the asset's Volume (in the editor a Play-mode change stays in the asset).

`SetSolo` works as on a mixing desk: while any bus is soloed, the soloed buses and their child buses are heard, through their parents (whose volume, mute and ducking still apply), and every other bus is silenced. **Sounds posted straight to a parent of a soloed bus are silenced too**; solo the parent to hear them. Mute still wins. A solo change reaches every bus's voices, paused and virtual ones too. Before 3.1.0 (after `3.1.0-dev.12`) a bus was heard only if it was soloed itself, so soloing a child bus silenced it too and soloing a parent silenced its children.

**Three levels** (3.1.0-dev.7, USER_GUIDE §6.8 and §7): **Volume** is the asset's (the mix); **StateOffsetDb** is what the active Offset states give the bus, moved by `AudioManager.SetState` / `ClearState`; **PlayerVolumeDb** is a Settings page's, set by the game. The last two are runtime only: never written to the asset, 0 at the start of each play session. A state never undoes the player's volume, nor the player a state.

#### Voice Management
```csharp
public void AssignToVoice(AudioVoice voice)
public void RemoveVoice(AudioVoice voice)
public AudioSource GetFirstActiveSource()
public void GetActiveSources(List<AudioSource> outList)
```

#### Ducking
```csharp
public void TriggerDucking(float holdDuration = 0f)
public void ApplyDucking(float amountDb, float attack, float hold, float release)
```
**Description:** `TriggerDucking()` uses the bus's configured ducking settings. `ApplyDucking()` applies custom ducking parameters (`amountDb` is negative dB; times in seconds). Ducking is triggered, not driven by the bus's output. **The deepest duck wins** (since 3.1.0-dev.7): each trigger is a duck of its own, and while several run on a bus it follows the deepest at each moment, so none cuts another short (it used to be one envelope per bus, replaced by each trigger). A new duck starts from the level the bus is at, so re-triggering one duck sounds as it always did. Each duck runs on the ducked bus's `DuckingTimeMode` as it was when triggered: Scaled (the default) freezes at time scale 0; Unscaled completes during a pause. At most 16 run at once on a bus (the one ending first gives way).

#### Pause / Resume / IsPaused
```csharp
public void Pause()
public void Resume()
public bool IsPaused { get; }
public BusPauseBehaviour WhilePaused { get; set; }

public enum BusPauseBehaviour { DropOneShots, Hold }
```
**Description:** For a game's pause: pause the world's buses and the pause menu's buses play on. `Pause()` holds every sound on this bus and its child buses: each fades out over about 25 ms and keeps its place, holding no real voice. `Resume()` brings them back from there, fading in, every layer of a sound in the same frame so they stay in phase. A child bus is paused while it or a parent is (`IsPaused`), and `Resume()` on a child doesn't override its parent. A sound posted to a paused bus starts held; with `DropOneShots` (the default) one whose voices don't loop is dropped before its first sample and its handle finishes at once, with `Hold` it plays on resume. Separate from `AudioHandle.Pause` and `AudioManager.PauseAll` (which still pause at once): a sound plays only when none of them pauses it. Pausing a paused bus, or resuming one that isn't, does nothing. Not paused at the start of each play session.

#### Factory Methods (Editor Only)
```csharp
public static AudioBus CreateNew(string name, AudioBus parent = null, AudioMixerGroup mixer = null)
public void EditorSetConfiguration(string name, AudioBus parent = null, AudioMixerGroup mixer = null)
```

---

### EffectSend (Nested Class)

```csharp
[Serializable]
public class EffectSend
{
    public string sendName;
    public float sendLevel;
    public bool prePost;
}
```

### DuckingTarget (Nested Class)

```csharp
[Serializable]
public class DuckingTarget
{
    public AudioBus targetBus;
    public float duckAmount = -6f;   // attenuation in dB, -80..0
}
```

## AudioState

Source: https://peppersfx.com/docs/api/audiostate/

**Namespace:** `AudioSystem`
**Inheritance:** `ScriptableObject`

### Properties

```csharp
public string StateName { get; }
public string StateGroup { get; }
public StateVolumeMode VolumeMode { get; set; }       // SetLevel (default, as before) or Offset
public IReadOnlyList<BusVolumeProperty> BusVolumes { get; }
public IReadOnlyList<SwitchProperty> SwitchValues { get; }
public IReadOnlyList<RTPCProperty> RtpcValues { get; }
public IReadOnlyList<EffectProperty> EffectProperties { get; }

public enum StateVolumeMode { SetLevel, Offset }
```

**VolumeMode** (3.1.0-dev.7; inspector: **Bus Volume Mode**). `SetLevel`: each bus is set to its `volumeDb` (`AudioBus.SetVolume`, the asset's Volume), and leaving the state puts nothing back, as before. `Offset`: each bus moves by its `volumeDb` in `AudioBus.StateOffsetDb`, on top of its Volume and the player's volume, never touching the asset; when another state in the group is set, or `AudioManager.ClearState` clears the group, the offsets go back over that transition time. Offset states in several groups add up on one bus.

---

### Methods

#### Apply
```csharp
public void Apply(float transitionTime)
```
**Description:** Applies this state's properties (bus volumes, RTPCs, switches, effects). An `Offset` state's bus volumes are left to `AudioManager.SetState`, which knows which states are active.

---

### Nested Property Classes

```csharp
[Serializable]
public class BusVolumeProperty
{
    public AudioBus bus;
    public float volumeDb;
}

[Serializable]
public class SwitchProperty
{
    public string switchGroup;
    public string switchValue;
}

[Serializable]
public class RTPCProperty
{
    public string parameterName;
    public float value;
}

[Serializable]
public class EffectProperty
{
    public AudioBus bus;
    public string propertyName;
    public float value;
}
```

## AudioVoice & AudioVoiceEnhanced

Source: https://peppersfx.com/docs/api/audiovoice-audiovoiceenhanced/

### AudioVoice (Base)

**Namespace:** `AudioSystem`
**Description:** Base voice representation.

#### Properties

```csharp
public AudioSource source { get; }
public bool isPlaying { get; }
public float volumeMultiplier { get; set; }
```

#### Methods

```csharp
public void SetVolume(float volume)
public void UpdateMasterVolume(float masterVolume)
public void Stop(float fadeTime = 0f)
public void StopImmediate()
```

---

### AudioVoiceEnhanced

**Namespace:** `AudioSystem`
**Inheritance:** `AudioVoice`
**Description:** Enhanced voice with gain stack, virtualization, and scheduling. **Not typically accessed directly.**

#### Properties

```csharp
public GainStack GainStack { get; }
public AudioEvent SourceEvent { get; }
public AudioContainer Container { get; }        // the innermost container that configured this voice (its
                                                // occlusion/reverb/propagation flags drive it)
public AudioContainer RootContainer { get; }    // the container that was played (e.g. the Blend around a layer)
public AudioBus Bus { get; }
public int Priority { get; }
public bool IsVirtual { get; }
public float VirtualTime { get; }               // where a virtual voice is in its clip now, in seconds
public double VirtualSamples { get; }           // the same in the clip's samples; written back on MakeReal
public double ScheduledStartTime { get; }
public double ScheduledEndTime { get; }
public OcclusionSlot OcclusionSlot { get; }     // mixer slot held while playing (null when not occluding)
```

#### Methods

```csharp
public GainStack GainStack { get; }
public PitchStack PitchStack { get; }
public void UpdateFinalVolume()
public void UpdateFinalPitch()    // writes PitchStack.GetFinal(container's Pitch Limit) to source.pitch
public void MakeVirtual()         // from your code: held virtual until MakeReal (the budget won't undo it);
                                  // an audible voice fades out over ~25 ms, then its source pauses
public void MakeReal()            // seeks to VirtualSamples while paused, resumes, fades in over ~25 ms;
                                  // over Max Real Voices, the least important other sounds go virtual
public void UpdateVirtualTime(float deltaTime)   // advance by deltaTime at the voice's pitch; only for a
                                                 // voice no AudioManager steps. No-op while paused; wraps
public float GetImportance()      // distance × GainStack.GetGainWithoutRealize() × priority
```

**Virtual position.** While a voice is virtual, the AudioManager's per-frame step moves `VirtualSamples` on by the audio clock's advance (`AudioSettings.dspTime`) × the voice's pitch (`source.pitch`, which the pitch stack writes), and wraps it for a loop. A pitch change counts from the next step, when Unity first plays it. Paused voices and starts still scheduled ahead don't advance. A virtual one-shot ends once its position passes the end of its clip. `AudioHandle.SeekTo` on a virtual voice moves the position it comes back at. Unity's own Doppler isn't seen; see `AudioContainer.DopplerLevel`.

**The fade.** `MakeVirtual` on a voice that can be heard (playing, started, not muted, above −80 dB) fades `GainStack.RealizeGain` to 0 over about 25 ms, in at least three steps of at most one per mixed DSP buffer (two volume changes in one buffer can leave Unity's own short ramp unfinished), then pauses the source; any other voice pauses at once. `MakeReal` fades it back to 1 the same way. A pause during the fade out finishes it at once. A `Stop(fadeTime)` during it lets it finish and then ends the voice. A voice with no AudioManager has no fade.

---

### GainStack (Nested Class)

```csharp
public class GainStack
{
    public float BaseGain { get; set; }       // Container/Event volume
    public float BusGain { get; set; }        // Bus hierarchy
    public float OcclusionGain { get; set; }  // Occlusion attenuation
    public float RtpcGain { get; set; }       // Blend curves. RESERVED: sole writer is the Blend's
                                              // per-frame step (product of every enclosing Blend's curve).
                                              // No second writer — see the reservation note in GainStack.cs.
    public float SchedulerGain { get; set; }  // Crossfade/transition
    public float FadeGain { get; set; }       // Stop(fadeTime) ramp, 1 → 0. RESERVED: sole writer is
                                              // AudioVoice's fade-out. Reset to 1 at the pool boundary.
    public float MultiplierGain { get; set; } // Per-voice multiplicative — volume randomization,
                                              // SwitchContainer/BlendContainer outer Volume,
                                              // and AudioExtensions.PlayWithVolume write here.
    public float UserGain { get; set; }       // AudioHandle.SetVolumeScale / SetVolumeOffset — idempotent runtime scale,
                                              // given to every voice of the handle's plays, later ones too.
    public float EmitterGain { get; set; }    // the Audio Emitter's Volume Offset; sole writer: the manager.
    public float DuckingGain { get; set; }    // (Deprecated) ducking is applied at the bus, not the voice.
                                              // Settable for back-compat but NOT included in GetFinalGain.

    public float CurveGain { get; set; }      // volume curves (ParameterCurve), summed in dB; sole writer: the play tree
    public float RealizeGain { get; set; }    // the fade around virtualization, 0 while parked; sole writer:
                                              // AudioVoice's virtualization. Reset to 1 at the pool boundary.
    public float SwitchGain { get; set; }     // a playing Switch's crossfade (equal power); sole writer: the play
                                              // tree. Left out of the silent-layer check. Reset to 1 at the pool boundary.
    public float SpatialGain { get; set; }    // Spatial Mode = Pepper: the level from the listening points (largest
                                              // weight × attenuation, less what Spread takes); 1 in Unity mode. Sole
                                              // writer: Pepper's spatial step (3.1.0-dev.8). Reset to 1 at the pool boundary.
    public float GetGainWithoutRealize()      // BaseGain * BusGain * OcclusionGain * RtpcGain * CurveGain * SchedulerGain * FadeGain * MultiplierGain * UserGain * SwitchGain * EmitterGain * SpatialGain
    public float GetFinalGain()               // GetGainWithoutRealize() * RealizeGain
    public void ApplyToSource(AudioSource source)
    public void Reset()
}
```

### PitchStack (Nested Class)

The pitch counterpart of `GainStack`: every contributor to a voice's playback rate owns one slot, and only `AudioVoice.UpdateFinalPitch()` writes `AudioSource.pitch`. Every slot is a ratio (1 = unchanged).

```csharp
public class PitchStack
{
    public const float MaxRatio = 3f;           // Unity's AudioSource.pitch ceiling
    public const float MinRatio = 0.001f;       // floor: a voice is never stopped by its pitch

    public float Randomization { get; set; }    // container pitch randomization
    public float Decorrelation { get; set; }    // Decorrelated multi-position nudge
    public float Follow { get; set; }           // a Blend's pitch follow (value ÷ root), set by the play tree
    public float Curve { get; set; }            // pitch curves (ParameterCurve, cents), set by the play tree
    public float Doppler { get; set; }          // Pepper's Doppler (a container with Doppler = Pepper), set by the play tree;
                                                // applied after the limit
    public float TimeScale { get; set; }        // reserved: slow motion (planned)
    public float User { get; set; }             // AudioHandle.SetPitchOffset (every voice of its plays, later ones too)
    public float Emitter { get; set; }          // the Audio Emitter's Pitch Offset

    public bool HasAbsolute { get; }            // SetPitchAbsolute / the obsolete SetPitch
    public float Absolute { get; }
    public void SetAbsolute(float ratio);       // play at exactly this ratio, ignoring every slot
    public void ClearAbsolute();

    public float GetFinal(float limitSemitones = 0f);   // product of the slots (or the absolute ratio), clamped;
                                                        // the limit leaves Doppler out (it comes after)
    public void Reset();
    public static float SemitonesToRatio(float semitones);
}
```

### DopplerMath

```csharp
public enum DopplerMode { Unity, Pepper }

public static class DopplerMath
{
    public const float SpeedOfSound = 343f;    // m/s
    public static float Cents(float closingSpeed, float exaggeration, float maxCents);   // 1200·log2(c ÷ (c − v)) × exaggeration, within ±maxCents
    public static float Ratio(float closingSpeed, float exaggeration, float maxCents);   // the same as a playback-rate ratio
}
```
**Description:** Pepper's Doppler shift (3.1.0-dev.7), as a container set to `DopplerMode.Pepper` applies it. `closingSpeed` is positive when the sound and the listener close in; a speed at or past 90% of the speed of sound reads as 90%. 50 m/s is about +272.7 cents, −50 m/s about −235.7.

## AudioExtensions & Utilities

Source: https://peppersfx.com/docs/api/audioextensions-utilities/

### AudioExtensions

**Namespace:** `AudioSystem`
**Type:** Static utility class

#### Extension Methods

```csharp
public static AudioVoice PlayAtPosition(this AudioContainer container, Vector3 position)
public static AudioVoice PlayAttached(this AudioContainer container, GameObject target)
public static AudioVoice PlayWithVolume(this AudioContainer container, float volumeScale, Vector3 position = default)
```

All three return the primary voice. `PlayWithVolume` multiplies `volumeScale` into every voice the play started, on top of volume randomization and any Switch/Blend outer volume.

**Example:**
```csharp
myContainer.PlayAtPosition(explosionPos);
myContainer.PlayAttached(player);
myContainer.PlayWithVolume(0.5f, transform.position);
```

#### Conversion Methods

```csharp
public static float DbToLinear(float db)      // 10^(db/20)
public static float LinearToDb(float linear)   // 20 * log10(linear), or -80 if linear <= 0
public static float CentsToPitch(float cents)  // 2^(cents/1200)
```

**Example:**
```csharp
float linear = AudioSystem.AudioExtensions.DbToLinear(-6f);  // ~0.5
float db = AudioSystem.AudioExtensions.LinearToDb(0.5f);      // ~-6dB
float pitch = AudioSystem.AudioExtensions.CentsToPitch(100f); // 1.059 (1 semitone up)
```

> **Unity 6.3 and newer** has its own `UnityEngine.AudioExtensions`. In a script with both `using UnityEngine;` and `using AudioSystem;`, the short name `AudioExtensions` is ambiguous there and won't compile (error CS0104). Write `AudioSystem.AudioExtensions`, as above, or add `using AudioExtensions = AudioSystem.AudioExtensions;` at the top of the file. The extension methods (`PlayAtPosition` and the others) aren't affected.

---

### ListenerUtil

**Namespace:** `AudioSystem`
**Type:** Static utility class

```csharp
public static Vector3 GetPosition()                    // the listener's position (zero if none)
public static bool TryGetPosition(out Vector3 position)
public static Transform Get()                          // the primary point's Follow transform, or the scene listener
public static void Set(Transform listener)             // registers a point that follows it; null removes it
public static void Invalidate()                        // removes Set's point; the next lookup searches again
```

**Description:** Where the listener is, for Pepper's distance-based features (voice importance, occlusion rays, the Furthest steal, multi-position picks). With a [listening point](#audiolisteningpoint) registered, the primary point (`AudioManager.SetPrimaryListeningPoint`, else the first) is the listener and nothing is searched for. With none, the scene is searched for an AudioListener with a one-time warning; a found listener is kept until destroyed, and while there is none the search runs at most once a frame. `Set` registers a point, which a point added with `AudioManager.AddListeningPoint` takes priority over; if its transform is destroyed, the search takes over again. `Get` returns null for a point placed with `SetPose`: use `GetPosition`.

---

### AudioListeningPoint

**Namespace:** `AudioSystem`
**Type:** class (created by `AudioManager.AddListeningPoint`)

```csharp
public Transform Follow { get; set; }      // read the pose from this transform; null = SetPose
public Vector3 Position { get; }
public Quaternion Rotation { get; }
public Vector3 Velocity { get; }           // measured each step, unless SetVelocity was called
public float Weight { get; set; }          // 0-1: how much it counts, with Spatial Mode = Pepper
public float PanWidth { get; set; }        // 0 mono … 1 stereo, with Spatial Mode = Pepper
public bool IsRegistered { get; }
public bool IsPrimary { get; }             // 3.1.0-dev.8
public void SetPose(Vector3 position, Quaternion rotation)   // ignored while Follow is alive
public void SetVelocity(Vector3 metresPerSecond)             // from then on, not measured
public void ClearVelocity()                                  // measure again, from where it is (a camera cut)
```

`Velocity` feeds Approach Speed and Pepper's Doppler. `ClearVelocity` (3.1.0-dev.7) goes back to measuring and starts again from the point's place, so a camera cut isn't read as speed; the last velocity stays until a new one is measured. Pointing `Follow` at another transform does the same (3.1.0-dev.8), keeping a velocity given with `SetVelocity`.

**Description:** Where the game listens from. While `Follow` is set and alive, the point reads that transform; **if it is destroyed, the point is removed** (`IsRegistered` false), with one warning a session (3.1.0-dev.8; it used to stay where it last was). Set the pose in Update or LateUpdate: Pepper's step runs after every LateUpdate. With the Audio Manager's Spatial Mode = Unity, Pepper listens from the primary point (`IsPrimary`; see [Listening Point Methods](https://peppersfx.com/docs/api/audiomanager/#listening-point-methods)); with Pepper, every point counts by its `Weight` (a sound's level is the largest weight × its attenuation from a point) and `PanWidth` (0 gives the sounds it hears no pan). Changing `Follow`, `Weight` or `PanWidth` eases Pepper's levels over 100 ms.

---

### BeatScheduler

**Namespace:** `AudioSystem`
**Inheritance:** `MonoBehaviour`
**File:** `RunTime/Utilities/BeatScheduler.cs`

**Description:** Fires an AudioEvent on a tempo grid (BPM) whose rate can be changed at runtime **without affecting pitch**. Each beat is a fresh one-shot post of the event asset (`AudioEvent.Post` with the beat's grid time as its scheduled start), not a time-stretch of a continuous clip. Timing is anchored to `AudioSettings.dspTime` so cadence is stable under frame-rate fluctuation.

**Use cases:** heartbeats, metronomes, ticking clocks, pulsing ambiences, sonar pings — any rhythmic SFX whose rate must vary independently of pitch.

#### Inspector Fields

| Field | Type | Description |
|---|---|---|
| `audioEvent` (Inspector: **Audio Event**) | `AudioEvent` | The AudioEvent asset posted each beat. Also the `Event` property. |
| `emitter` | `GameObject` | Optional emitter used for the posted event's source and position. Defaults to the BeatScheduler's own GameObject. |
| `bpm` | `float` (1–600) | Beats per minute. Also writable at runtime via the `Bpm` property. |
| `maxCatchUpBeatsPerFrame` | `int` (1–16) | Cap on `OnBeat` callbacks per Update if the scheduler falls behind (frame hitch, very high BPM). Audio always plays at most ONCE per Update regardless of this value — overdue audio beats are dropped to prevent voice-stacking thump. Only affects `OnBeat` consumers that count beats for game logic (`every 4th beat trigger X`), keeping them synchronized with the grid across hitches. |
| `playOnEnable` | `bool` | Start scheduling automatically when enabled. |
| `fireImmediatelyOnStart` | `bool` | Fire the first beat on the next frame (true) or wait one interval (false). |

#### Properties

```csharp
public AudioEvent Event { get; set; }   // The event posted each beat (the Audio Event field)
public float Bpm { get; set; }          // Clamp-guarded, min 1. Setter applies to the next beat onward.
public bool IsRunning { get; }
public double BeatInterval { get; }     // 60 / Bpm, in seconds
```

#### Methods

```csharp
public void StartScheduling();          // Safe to call while already running (no-op).
public void StopScheduling();           // Stops firing. Does not stop voices already posted.
public void ResyncPhase();              // Reset phase: next beat fires at now + BeatInterval.
```

#### Events

```csharp
public event System.Action OnBeat;      // Fired on the main thread on every beat, after the event is posted.
```

Exceptions thrown by subscribers are caught and logged — they will not break the scheduler.

#### Example

```csharp
using UnityEngine;
using AudioSystem;

public class StressHeartbeat : MonoBehaviour
{
    [SerializeField] private BeatScheduler heartbeat;
    [SerializeField] private float calmBpm = 60f;
    [SerializeField] private float panicBpm = 160f;

    [Range(0f, 1f)] public float stress;

    private void Update()
    {
        heartbeat.Bpm = Mathf.Lerp(calmBpm, panicBpm, stress);
    }
}
```

#### Notes

- **Frame-level accuracy, not sample-level.** Actual playback lands on the next audio callback (a few ms after the frame). For sample-accurate musical grid scheduling, use `AudioSource.PlayScheduled` directly.
- **BPM changes apply to the next beat.** The beat already queued is not rewound — this is deliberate so tempo ramps sound natural.
- **Multiple schedulers are independent.** Two `BeatScheduler` components at the same BPM are not phase-locked to each other.
- See also: *Manual §10.4 Beat-Scheduled SFX* and *Cookbook → Rhythmic SFX*.

---

### IRTPCListener (Interface)

```csharp
public interface IRTPCListener
{
    void OnRTPCChanged(string parameter, float value);
}
```

**Description:** Implement this interface to receive notifications when a parameter's **global** value changes (`SetRTPC`, `SetParameter`, and each frame of a transition or global ramp), by name and synchronously. Emitter and play values don't notify. Register via `AudioManager.Instance.RegisterRTPCListener()`. Nested in `AudioManager` (`AudioManager.IRTPCListener`).

## AudioEventRegistry

Source: https://peppersfx.com/docs/api/audioeventregistry/

**Namespace:** `AudioSystem`
**Inheritance:** `ScriptableObject`
**Access:** Singleton via `AudioEventRegistry.Instance`

### Description

Central registry for AudioEvents and AudioStates. Eliminates the Resources folder requirement by tracking assets in a single registry.

**Purpose:**
- Store references to all Events and States
- Auto-detect and use instead of Resources.LoadAll
- Allow Events/States to live anywhere in project
- Backwards compatible (falls back to Resources if no registry)

### Properties

```csharp
public static AudioEventRegistry Instance { get; }
public IReadOnlyList<AudioEvent> AudioEvents { get; }
public IReadOnlyList<AudioState> AudioStates { get; }
```

### Methods

```csharp
public void RegisterEvent(AudioEvent audioEvent)
public void RegisterState(AudioState audioState)
public void AutoPopulateFromResources()   // Editor only
public void AutoPopulateFromProject()     // Editor only
public void ValidateRegistry()            // Editor only
```

### Setup Example

```csharp
// 1. Create registry asset:
// Right-click -> Create > Audio System > Audio Event Registry

// 2. Place in: Assets/Audio/Resources/AudioEventRegistry.asset

// 3. Populate registry (in Inspector):
//    Click "Populate from Resources" or "Populate from Entire Project"

// 4. AudioManager automatically uses registry at startup
//    (Falls back to Resources.LoadAll if registry not found)
```

**Migration:** See [Migration](https://peppersfx.com/docs/migration/) in the User Guide for full details.

## Multi-Position Emitters

Source: https://peppersfx.com/docs/api/multi-position-emitters/

### AudioMultiPositionEmitterParent

**Namespace:** `AudioSystem`
**Inheritance:** `MonoBehaviour`

**Description:** Parent component that manages a group of child emitters for multi-position audio playback.

#### Properties

```csharp
public MultiPositionType PositionType { get; }
public float PositionLerpTime { get; }
public bool UseSpreadCurve { get; }
public float MinSpatialBlend { get; }
public float MaxRandomOffset { get; }
public float MaxPitchVariationCents { get; }
public IReadOnlyList<AudioMultiPositionEmitterChild> AllEmitters { get; }
public IReadOnlyList<AudioMultiPositionEmitterChild> ActiveEmitters { get; }
public int ActiveEmitterCount { get; }
public bool HasActiveEmitters { get; }
```

#### Methods

```csharp
public Vector3[] GetActivePositions()
public Transform[] GetActiveTransforms()
public void RefreshChildren()
public void EnableAllEmitters()
public void DisableAllEmitters()
public void SetAllVolumes(float volume)
```

**Example:**
```csharp
var emitterParent = GetComponent<AudioMultiPositionEmitterParent>();
AudioMultiHandle mh = myEvent.PostMultiPosition(emitterParent);
```

---

### AudioMultiPositionEmitterChild

**Namespace:** `AudioSystem`
**Inheritance:** `MonoBehaviour`

**Description:** Individual emitter point in a multi-position setup.

#### Properties

```csharp
public bool IsActive { get; set; }
public float VolumeMultiplier { get; set; }
public bool UseDirectionality { get; set; }   // Scene-view cone gizmo only; not read during playback
public float ConeAngle { get; set; }          // that gizmo's angle, 0–360
public Vector3 Position { get; }
public Quaternion Rotation { get; }
public Vector3 Forward { get; }
```

`UseDirectionality` and `ConeAngle` only draw a cone in the Scene view. They don't change how an emitter sounds.

## Editor Tools

Source: https://peppersfx.com/docs/api/editor-tools/

**Note:** These tools are Unity Editor extensions and not available at runtime.

### AudioAuditionWindow and AudioAudition

**Access:** `Window > Audio System > Audition` (USER_GUIDE §10.5)

Plays a container tree, or an event's Play actions, outside Play mode with a slider for every parameter it reads (Bypass Slew While parameters included), its switch values, any number of sweeps, a recording's replay and a live table of its layers; it follows the selected container or event, keeps playing while it is edited, and reads the tree again when it changes in the Inspector. The window runs an `AudioAudition` (namespace `AudioSystem`, in the Runtime assembly but used only outside Play mode):

```csharp
public enum SweepMode { Once, Repeat, BackAndForth }

public sealed class AudioAudition : System.IDisposable
{
    public static AudioAudition Current { get; }
    public static AudioAudition Begin(out string whyNot);   // the running one; null in Play mode or with another Audio Manager
    public AudioContainer Container { get; }                // what plays: a container...
    public AudioEvent Event { get; }                        // ...or an event
    public int SkippedActions { get; }                      // the event's actions not auditioned
    public bool IsPlaying { get; }                          // also while an event's delayed Play is to come
    public float Distance { get; set; }                     // m from the listening point at the origin
    public float Angle { get; set; }                        // °, 0 ahead, + right
    public void Play(AudioContainer container);
    public void Play(AudioEvent audioEvent);
    public void Stop();                                     // immediate
    public void Tick(float dt);                             // call every editor update

    public void SetParameter(AudioParameter p, float v);  public void SetParameter(string name, float v);   // takes it off its sweep or the replay
    public void SnapParameter(AudioParameter p);
    public float GetParameter(AudioParameter p);           public float GetParameter(string name);          // heard
    public float GetWrittenParameter(AudioParameter p);    public float GetWrittenParameter(string name);   // written: what a slider shows

    public void Sweep(AudioParameter p, float from, float to, float seconds, SweepMode mode);
    public void Sweep(string name, float from, float to, float seconds, SweepMode mode);
    public void Sweep(AudioParameter p, float from, float to, float seconds, bool backAndForth = false);   // as before
    public void Sweep(string name, float from, float to, float seconds, bool backAndForth = false);
    public void StopSweep();                                // every sweep
    public void StopSweep(AudioParameter p);              public void StopSweep(string name);
    public bool IsSweeping { get; }                         // any
    public bool IsSweepingParameter(AudioParameter p);    public bool IsSweepingParameter(string name);

    public void Replay(AudioParameterRecording recording);  // from its start, looping; null stops it
    public AudioParameterRecording Recording { get; }
    public bool IsReplaying { get; }
    public bool ReplayLooping { get; set; }                 // default true; false stops at the end
    public float ReplayTime { get; set; }                   // set = scrub (snapped)
    public void SetReplayLoop(float start, float end);      // end <= start = all of it
    public float ReplayLoopStart { get; }  public float ReplayLoopEnd { get; }
    public void StopReplay();
    public bool IsReplayed(AudioParameter p);              public bool IsReplayed(string name);

    public void SetSwitch(AudioSwitchGroup g, string v);  public void SetSwitch(string group, string v);
    public string GetSwitch(AudioSwitchGroup g);          public string GetSwitch(string group);
    public void GetLayers(List<AuditionLayer> into);       // Container, Clip, LevelDb, PitchSemitones, LowPassHz, Virtual, Bus
    public static void FindInputs(AudioContainer root, AuditionInputs into);   // Parameters, ParameterNames, SwitchGroups, SwitchGroupNames, SwitchValues
    public static void FindInputs(AudioEvent audioEvent, AuditionInputs into); // every Play action's tree
    public void Dispose();
}
```

**How it runs.** `Begin` creates a hidden (`HideAndDontSave`) Audio Manager in Manual update mode and starts it without `Awake` (edit mode doesn't call it): the voice pool only, no coroutines, no PlayerLoop step, no event, bus or occlusion loading. It registers a listening point at the origin facing +z and a hidden source object that `Distance` and `Angle` move. Values are set on that manager's global scope: assets through their smoothing, names through the string API. `Tick` runs the event's delayed actions, the replay, the manager's step, the sweeps and, every 0.1 s, the voice pass. A play is placed in 3D but heard 2D (spatial blend 0). A Next Play Only Switch in the tree plays again when a switch value is set by hand (not by a replay). Built-in parameters and driven Switch Groups follow the place and their parameter, not `SetParameter`/`SetSwitch`. Outside Play mode a Sequence plays its first clip only and a stop is immediate. `Dispose` stops everything and destroys the hidden objects and the listening point; the window calls it before Play mode, before a script reload and when it closes.

**Sweeps** run one per parameter, any number at once: a new sweep of a parameter replaces its earlier one, and setting a parameter by hand stops only its own. **Once** ends at `to` (the written value stays there); **Repeat** starts again from `from`; **BackAndForth** turns round.

**An event** (`Play(AudioEvent)`) runs its Play actions as a post would: through each action's Target Bus (volume, mute), with the event's priority and Persistent flag, after the action's Delay; its Set RTPC and Set Switch actions set the audition's values; the rest are counted in `SkippedActions`. Max Instances and cooldowns don't apply, and the event's own state is never touched.

**A replay** writes every recorded value at once, as the game wrote it, through the parameter's smoothing, holding each key until the next; the recorded switch values are set as the game set them. Going round the loop and setting `ReplayTime` snap the values (heard at once). A parameter set by hand or swept is taken off the replay; `Replay` again restores it.

### AudioLiveViewWindow, AudioEmitterRecorder and AudioParameterRecording

**Access:** `Window > Audio System > Live View` (USER_GUIDE §10.6), in Play mode

Every Audio Emitter with its values (written and heard) and switches, and each play on it (`AudioManager.GetPlaysDebug`): event, container, bus, Persistent, real or virtual, its own values (`AudioHandle.ParameterCount` and the listing beside it) and each voice's level, pitch, region and reason for being virtual. **Record** and **Stop and Save** record the chosen emitter:

```csharp
public sealed class AudioEmitterRecorder
{
    public static AudioEmitterRecorder Begin(AudioEmitter emitter, out string whyNot);   // Play mode only
    public AudioParameterRecording End();     // in memory; save it with AssetDatabase.CreateAsset
    public AudioEmitter Emitter { get; }
    public AudioParameterRecording Recording { get; }
    public float Seconds { get; }             // unscaled
    public bool IsRecording { get; }          // false after End, or once the emitter is destroyed
}

public sealed class AudioParameterRecording : ScriptableObject
{
    public string EmitterName { get; }
    public float Length { get; }              // seconds
    public IReadOnlyList<ParameterTrack> Parameters { get; }   // parameter (asset or null), parameterName, times, values; ValueAt(t): NaN = not set
    public IReadOnlyList<SwitchTrack> Switches { get; }        // group, times, values; ValueAt(t): "" = not set
    public ParameterTrack Find(AudioParameter p);  public ParameterTrack Find(string name);
}
```

A recorder samples its emitter at the start of each of Pepper's steps, after the frame's game code: every value set on it as written (a ramp's position while it runs), Bypass While ones included, and its switch values, keeping a key only when one changes; a value the game clears is a NaN key. Values set on a play's handle and global values aren't recorded. While nothing records, the step does nothing for it.

### LoopAnalysisWindow

**Access:** `Window > Audio System > Loop Analysis` (USER_GUIDE §10.7)

Per clip (Decompress On Load): its fundamental by the YIN method and the Root Value it gives, RPM = fundamental × 120 ÷ cylinders (a four-stroke engine), with ×2 and ÷2 for an octave slip; a seam check at the loop point (the first sample against the line through the last two, over the clip's own RMS second difference: over 4× clicks) and the level of the first against the last 50 ms; a preview of the seam; RMS and peak in dBFS and integrated loudness in LUFS (ITU-R BS.1770-4, a mono clip as one channel). A Regions Blend's Inspector has **Detect Root Values**, which sets each layer's Root Value from its clip (with Undo) for the cylinder count set beside it. Cylinders is a scale, one setting shared by the three tools. A reading more than half an octave from the RPM in its clip's name is flagged; when most readings sit 2 semitones or more from them, the tools name the cylinder count that puts them within a semitone (**Use N** in the windows; a Console warning from Detect Root Values, which still writes the raw reading).

### EngineBuilderWindow

**Access:** `Window > Audio System > Engine Builder` (USER_GUIDE §10.8)

From selected loops (each one's set, OnLoad or OffLoad, and RPM guessed from its name, typed, or detected with its own Cylinders slider, shared with Loop Analysis; a detected RPM far from its name's is flagged): one looping single-clip container per loop (Uses Parent Positioning and Output, Avoid Repeat Last 0); an on-load and an off-load Regions Blend on RPM (Root Values, Auto Layout, Equal Power, Pitch Follow, Silent Layers Virtualize, Force Loop); a Regions Blend on load crossfading them at constant power from 0.3 to 0.7 (3D, Doppler Level 0); one Persistent event on the chosen Target Bus. Empty RPM and Load fields make EngineRpm (0–9000 RPM) and EngineLoad01 (0–1). The clips are set to mono and Decompress On Load after a confirmation listing them; no asset is ever overwritten. With one set only, the RPM Blend is the root and there is no load Blend; the window and its dialog say so.

### EngineGrainsWindow

**Access:** `Window > Audio System > Engine Grains` (Unity 6000.3 and later)

Cuts an engine sweep (Decompress On Load) into a [GrainTable](https://peppersfx.com/docs/api/container-types/#graintable). The sweep's RPM is **Known**, typed from one
RPM to another over the whole clip along a **Curve** (Straight Line or Even Pitch: a synthesised sweep), or measured
**From Pitch** with the Cylinders scale shared with Loop Analysis, looked for between the two RPMs typed. Each cut is
one engine cycle long at that RPM, then moved, by less than half a period of the fundamental and at most 6% of a cycle,
to where the waveform best matches the start of the grain before it, stretched to the new pitch. With a typed RPM, the
periods of the fundamental per cycle are measured against it, and the sweep's own curve is measured from a strong
harmonic followed through it: when it disagrees with the one typed (the other curve, or the RPM changing by more than 3%
more or less over the clip), the window says so and offers the curve that fits, with the two ranges that keep one typed
end, each cut on trial and the one whose cuts match better first. The report gives the range covered and warns of gaps
(no grain over 250 RPM), a fast sweep (under 10 grains per 1000 RPM), a typed curve the grains don't follow (over 3% off
on average) and cuts that found nothing like the cycle before within reach (over 20% of them below a 0.5 match); it notes
held stretches (under 50 RPM of change for 0.3 s or more). **One Grain At** loops the grain nearest an RPM, unchanged, to
hear whether its cuts are clean. Saving makes `<sweep>_Grains.asset` beside the clip, or updates the table it was given
(with Undo).

### AudioContainerValidator (Container Validator)

**Namespace:** `AudioSystem.Editor`
**Access:** `Window > Audio System > Container Validator` (USER_GUIDE §10.9)

```csharp
public static void Validate(AudioContainer container, List<ValidationIssue> issues);
public static void ValidateEvent(AudioEvent audioEvent, List<ValidationIssue> issues);
public static void ApplyFix(ValidationIssue issue);   // under Undo
public class ValidationIssue { AudioContainer container; Object target; string issue; MessageType severity; Action fix; }
```

Every container and event in the project: empty or null entries and zero weights; a Routing container with no clip; Regions gaps, dips and 0–0 regions; a layer following pitch with no Root Value; pitch past a Blend's Tuning Warning (Pitch Follow over the follow parameter's own range, plus pitch curves); a 3D loop with Doppler in a Virtualize Blend; stereo clips on 3D layers and streaming clips on layers that go virtual; 3D distances, or the Attenuation asset's curve at its Max Distance; a Play action with no Target Bus (a warning without a Mixer Group, else Info); a looping event that isn't Persistent (Info). `target` is the event for an event's issue (`container` is null then).

### Audio Import Settings and folder rules

**Namespace:** `AudioSystemEditor.Import`

The project's `AudioImportSettings` asset (Create ▸ Audio System ▸ Import Settings, under Assets; the first by path when there are several, never one inside a package) holds the category presets and **Folder Rules**:

```csharp
public class FolderImportRule { string name; string folder; bool includeSubfolders; bool enabled; CategoryPreset settings; }
public List<FolderImportRule> FolderRules { get; }
public FolderImportRule RuleFor(string assetPath);   // the most specific enabled folder; null when none
```

`AudioImportRulesPostprocessor` applies a clip's rule when the clip is first imported (a new file); later reimports keep the clip's settings. The inspector's **Apply to Existing Clips** re-applies a rule to the clips already in its folder.

### SoundBuilderSimpleWindow

**Namespace:** `AudioSystemEditor`
**Type:** EditorWindow
**Access:** `Window > Audio System > Sound Builder (Simple)`

#### Description

One-click sound setup wizard that creates Bus + Container + Event with all references pre-filled.

**Features:**
- 5 creation modes: Complete Setup, Container Only, Event Only, Bus Only, Batch Import
- All 5 container types supported
- Auto-create folder structure
- Validate Resources placement

#### Usage

1. `Window > Audio System > Sound Builder (Simple)`
2. Drop AudioClip(s) in field
3. Choose a creation mode and container type
4. Click "Create Complete Sound Setup"
5. Done!

---

### AudioEventEditor

**Namespace:** `AudioSystemEditor`
**Type:** Custom Inspector (Editor Only)
**Applies To:** AudioEvent assets

#### Description

Custom Inspector for AudioEvent: whether the event can be found by name or id, and the stable id.

**Features:**
- Says whether the event is in the AudioEventRegistry (or, with no registry, in Resources/Audio/Events), with **Add to Registry** or **Move to Resources** buttons. Only posting by name or id (`AudioManager.PostEvent`, networked posts) needs that: an event held in a field (`myEvent.Post()`) plays wherever it is. Earlier versions said such an event "will NOT load at runtime" and warned in the Console on import; both were wrong and are gone.
- Bakes the asset's GUID into the event on import (the stable network id).

---

### AudioEventRegistryEditor

**Namespace:** `AudioSystemEditor`
**Type:** Custom Inspector (Editor Only)
**Applies To:** AudioEventRegistry assets

#### Description

Custom Inspector for AudioEventRegistry with utility buttons and migration guide.

**Buttons:**
- **Populate from Resources Folders** - Fast for existing Resources-based projects
- **Populate from Entire Project** - Searches entire project
- **Validate Registry (Remove Nulls)** - Cleans up missing references
- **Clear All** - Removes all registered assets (with confirmation)

---

### Occlusion Layout Builder Window

**Namespace:** `AudioSystemEditor.Occlusion`
**Type:** EditorWindow
**Access:** `Window > Audio System > Occlusion Layout`

Authors the per-bus occlusion slot hierarchy on the project's voice mixer and serializes it to an `OcclusionLayout` asset. See [Manual §14.3](https://peppersfx.com/docs/manual/occlusion-mixer-slot-pool/#143-authoring-the-slot-layout).

**Top-bar fields:**
- **Voice Mixer** — the mixer to author into
- **Occlusion Layout** — the asset to populate (or click "Create New")
- **Reverb Send Bus Registry** (optional) — when assigned, each generated slot also receives one Send effect per registered reverb bus
- **Slots Per Bus** — concurrent occluded voices per bus (default 6)

**Actions:**
- **Scan, Auto-Create, Refresh** — walks the project for containers with `useOcclusion`, `allowReverbSend` or `usePropagation` (each takes a slot at play time) and ambient sources with `useOcclusion`, collects the unique mixer groups they play through (a layer with `usesParentOutput` counts its parent's), authors `<Bus>_OcclusionLayer` + slot groups under each, exposes their cutoff parameters and (optional) Send level parameters, writes the result to the OcclusionLayout asset.
- **Scan only (no mixer changes)** — read-only sanity check.
- **Diagnose Reflection** — dumps a reflection report to the Console for the audio internals (debug aid when the auto-creator misbehaves on a new Unity version).

A foldout at the bottom shows the manual schema for designers who prefer to hand-author the slot hierarchy.

---

### Reverb Send Buses Window

**Namespace:** `AudioSystemEditor.Reverb`
**Type:** EditorWindow
**Access:** `Window > Audio System > Reverb Send Buses`

Project-wide overview of `ReverbSendBus` assets. See [Manual §15.6](https://peppersfx.com/docs/manual/reverb-send-buses-per-zone-reverb/#156-authoring-workflow-reverbautocreator--reverb-send-buses-window).

**Top-bar actions:**
- **Create New Bus** — Save File panel for authoring a fresh `ReverbSendBus` asset
- **Refresh** — re-scans the project for `t:ReverbSendBus` and re-runs Validate per asset
- **Validate All** — same as Refresh but with a summary HelpBox
- **Generate All Missing** — runs `ReverbAutoCreator.EnsureSendBus` on every bus whose `ReverbBus` is null and whose `ReverbMixer` is assigned

Per-row UI: bus name (link-label, pings the asset), assigned mixer, assigned bus group, and a foldable issue list from `ReverbAutoCreator.Validate`. Auto-refreshes on window focus.

---

### ReverbSendBusInspector

**Namespace:** `AudioSystemEditor.Reverb`
**Type:** Custom Inspector (Editor Only)
**Applies To:** `ReverbSendBus` assets

Adds four top-of-inspector action buttons that drive `ReverbAutoCreator`:

| Button                    | What it does                                                                                                  |
|---------------------------|---------------------------------------------------------------------------------------------------------------|
| **Generate Mixer Group**  | Authors / refreshes the mixer group + SFX Reverb effect + exposed parameters. Disabled until `Reverb Mixer` is assigned. |
| **Validate Wiring**       | Read-only check; reports "Wiring OK" or a bullet list of issues. Always enabled.                              |
| **Apply Params → Mixer**  | Pushes the SO's parametric values into the mixer effect without re-running the group/expose work. Enabled once `Reverb Bus` is generated. |
| **Pull Params ← Mixer**   | Copies the mixer effect's current values back onto the SO.                                                    |

The ten Advanced parametric reverb fields live behind an EditorPrefs-backed foldout (closed by default); the four Basic fields stay visible. EditorPrefs key is project-wide so the toggle survives selection changes.

---

### AudioPortalEditor / AudioZoneEditor / PropagationManagerEditor

**Namespace:** `AudioSystemEditor.Propagation`
**Type:** Custom Inspectors (Editor Only)

Diagnostic inspectors for the propagation subsystem's runtime components.

- **AudioPortalEditor** — adds a Portal Diagnostics panel showing door source status, current transmission / cutoff (live in play mode), and the auto-detected blend-axis side mapping. Includes a "Re-detect zone sides" button.
- **AudioZoneEditor** — adds a Zone Diagnostics panel showing live reverb profile values, volume collider counts, and the list of `AudioPortal`s in loaded scenes referencing this zone.
- **PropagationManagerEditor** — adds a Runtime Debug panel (play mode only) showing registered zone/portal/source counts, active zone/portal counts after culling, the listener's zone stack, blend-portal membership, pending hysteresis events, and emitter pool counters.

All three refresh every repaint while in play mode (via `RequiresConstantRepaint`).

## Propagation

Source: https://peppersfx.com/docs/api/propagation/

**Namespace:** `AudioSystem.Propagation`
**Added in:** v2.3.0
**Location:** `Assets/Scripts/SFX_System/RunTime/Propagation/`

Zone/portal graph-based routing for long-running ambient beds. Additive — does not modify the SFX event pipeline. See [Manual Chapter 13](https://peppersfx.com/docs/manual/ambient-propagation-subsystem/) for architecture and design rationale.

---

### PropagationManager

**Namespace:** `AudioSystem.Propagation`
**Inheritance:** `MonoBehaviour`
**Access:** `PropagationManager.Instance` (lazy-instantiated at play time)

Singleton orchestrator. Owns zone/portal/source registries, the Dijkstra solver, the emitter pool, and per-frame smoothing.

#### Properties

```csharp
public static PropagationManager Instance { get; }
public static bool HasInstance { get; }
```

`Instance` returns null in Edit mode (to prevent phantom GameObject creation on inspector edits). `HasInstance` is null-safe for use in `OnDisable` during scene teardown.

#### Inspector Configuration

| Field                            | Default | Description                                                                                                 |
|----------------------------------|---------|-------------------------------------------------------------------------------------------------------------|
| `solveRateHz`                    | 15      | Solves per second. Per-frame emitter smoothing handles the in-between.                                      |
| `distancePenaltyDbPerMeter`      | 0       | Extra dB cost per meter of portal-to-portal distance. 0 = pure transmission routing.                        |
| `silenceOutsideGraph`            | false   | When false, voices outside every AudioZone play at full audibility (whitelist mode). When true, they fall silent and maximally muffled (complete-coverage mode). See [Manual §13.4](https://peppersfx.com/docs/manual/ambient-propagation-subsystem/#134-the-solve-pipeline). |
| `transmissionSkipThreshold`      | 1e-5    | Linear-amplitude floor below which the solver treats a portal as fully closed and skips it. Raise to cull near-closed doors earlier. |
| `drawListenerZoneOverlay`        | false   | Editor-only debug overlay. When ON, draws a scene-view label above the listener showing the current zone name and inside-portal count. |
| `maxAmbientEmitters`             | 16      | Global cap. Farthest emitters silenced first when exceeded.                                                 |
| `prewarmPoolSize` (range 0–64)   | 0       | Pre-allocate this many AmbientEmitter GameObjects at Start. Clamped to maxAmbientEmitters. 0 = lazy.        |
| `emitterSmoothSpeed`             | 4       | Per-frame smoothing speed for volume/cutoff/position.                                                       |
| `maxPathsPerSource` (range 1–6)  | 1       | How many simultaneous propagation paths each ambient source may voice. 1 = original single-best-path. Raise to hear an ambience leak through multiple openings at once. |
| `enableObstruction`              | false   | Per-emitter listener→virtual-emitter raycast obstruction on top of portal-based propagation.                |
| `obstructionLayerMask`           | ~0      | Physics layer mask for the obstruction raycast.                                                             |
| `obstructionAttenuationDb` (0–30)| 6       | Extra dB applied when the obstruction ray is blocked.                                                       |
| `obstructionCutoffHz` (100–22000)| 2000    | Upper bound on the low-pass cutoff under obstruction. Combines with solver cutoff via min-wins.             |
| `zoneDwellSeconds` (0–1)         | 0.15    | Dwell time before a listener zone enter/exit commits. Absorbs straddle-jitter on boundary crossings. 0 = instant commit. |
| `culler`                         | —       | Nested `PropagationProximityCuller` configuration (see below).                                              |
| `listenerOverride`               | null    | Optional explicit listener transform. Without one, the listening point registered with Pepper (`AudioManager.AddListeningPoint`); only with no point, the scene's `AudioListener`, then `Camera.main`. |

#### Registration API

```csharp
public void RegisterZone(AudioZone z);
public void UnregisterZone(AudioZone z);
public void RegisterPortal(AudioPortal p);
public void UnregisterPortal(AudioPortal p);
public void RegisterSource(AmbientSource s);
public void UnregisterSource(AmbientSource s);
```

Zones, portals, and ambient sources self-register via their `OnEnable` / `OnDisable`. Manual calls are safe (idempotent).

#### Notification API (typically called only by `AudioListenerZoneTracker`)

```csharp
public void NotifyListenerEnteredZone(AudioZone z);
public void NotifyListenerExitedZone(AudioZone z);
public void NotifyListenerEnteredPortal(AudioPortal p);
public void NotifyListenerExitedPortal(AudioPortal p);
public void NotifyPortalParamsChanged(AudioPortal p);
```

`NotifyPortalParamsChanged` triggers an immediate re-solve instead of waiting for the next scheduled tick. Called from `AudioPortal.HandleDoorChanged` when the door source fires `OnChanged`.

#### Queries

```csharp
public AudioZone GetCurrentListenerZone();
public AudioZone GetZoneContainingPoint(Vector3 worldPoint);
public float GetSourceAudibility(AudioZone sourceZone);
public float GetSourcePropagationCutoff(AudioZone sourceZone);
public AudioZone GetResolvedListenerReverbProfile(Vector3 listenerPos, AudioReverbProfile dest);
public AudioZone GetResolvedListenerReverbProfile(AudioReverbProfile dest);
public bool SilenceOutsideGraph { get; }
```

- `GetCurrentListenerZone` — top of the listener zone stack, or null if the listener isn't inside any registered zone.
- `GetZoneContainingPoint` — first registered zone whose `ContainsPoint(worldPoint)` returns true, or null. Used by the reverb-send driver to resolve source zones.
- `GetSourceAudibility` / `GetSourcePropagationCutoff` — per-zone reads from the listener-audibility cache, populated each solve tick. Same-zone = 1.0 / 22 kHz; through-portals = chain-of-portals weight; unreachable = 0 / 500 Hz.
- `GetResolvedListenerReverbProfile` — fills the provided `AudioReverbProfile` with the listener's current zone's reverb *character*, resolved zone → `ReverbBus` → `ReverbSendBus` SO (portal-blend lerped when inside a blend region). Returns the canonical zone that was resolved. Still used by the per-source ambient path (`AmbientEmitter`); the per-bus parametric driver no longer calls it.

---

### AudioZone

**Namespace:** `AudioSystem.Propagation`
**Inheritance:** `MonoBehaviour`
**Required Components:** `BoxCollider` (auto-forced to `isTrigger = true`)

A volume of world space tagged as one acoustic room. Nodes of the propagation graph.

#### Inspector

| Field              | Default | Description                                                                      |
|--------------------|---------|----------------------------------------------------------------------------------|
| `zoneId`           | ""      | Optional debug identifier. Not used at runtime.                                 |
| `baseVolumeDb`     | 0       | Optional per-zone attenuation baseline added to ambient source volume.          |
| `activationRadius` | 50      | Distance from listener beyond which this zone is culled. `Infinity` = never cull. The culler preserves transitive reachability — a zone connected to the listener's zone through near portals is force-included even when individually out of range. |
| `entryFadeMeters` (Min 0) | 0 | Soft membership band measured inward from the trigger surface. 0 = hard boundary (binary in/out). When > 0, a point at the surface has membership 0 and a point this many meters inside has membership 1; lerps linearly in between. Used to fade reverb sends, listener-side reverb character, and `BaseVolumeDb` smoothly across the boundary. |
| `reverbBus`        | null    | The mixer reverb bus voices physically in this zone send to (source-side). Drag in the `ReverbBus` field from a `ReverbSendBus` asset. Null = no reverb-send routing for sources in this zone. The bus's *character* lives on its `ReverbSendBus` asset, not here. See [Reverb Send Buses](https://peppersfx.com/docs/api/reverb-send-buses/). |

#### Properties

```csharp
public string ZoneId { get; }
public float BaseVolumeDb { get; }
public float ActivationRadius { get; }
public float EntryFadeMeters { get; }
public AudioMixerGroup ReverbBus { get; }          // null when no bus assigned; routing only (character lives on the ReverbSendBus SO)
public IReadOnlyList<BoxCollider> VolumeColliders { get; }
```

`VolumeColliders` is populated from `GetComponents<BoxCollider>()` in `Awake` — add multiple BoxColliders for L-shapes, they're OR-unioned.

#### Virtual Methods (override for custom shapes)

```csharp
public virtual bool ContainsPoint(Vector3 worldPoint);
public virtual Vector3 ClosestSurfacePoint(Vector3 worldPoint);
public virtual float GetMembershipFactor(Vector3 worldPoint);  // 0..1; binary when entryFadeMeters == 0
```

Default implementations iterate all volume colliders. Subclass to support sphere-shaped or mesh-shaped zones without touching the solver. Subclasses that override `GetMembershipFactor` must respect the contract "0 at surface, 1 once fully inside."

---

### AudioPortal

**Namespace:** `AudioSystem.Propagation`
**Inheritance:** `MonoBehaviour`
**Required Components:** `BoxCollider` (auto-forced to `isTrigger = true`)

Edge of the propagation graph. Connects two zones, optionally modulated by an `IPortalDoorSource`, and doubles as the listener blend region.

#### Inspector — Zones

| Field              | Default | Description                                                                                  |
|--------------------|---------|----------------------------------------------------------------------------------------------|
| `zoneA`            | null    | One of the two connected zones.                                                              |
| `zoneB`            | null    | The other connected zone.                                                                    |
| `autoDetectZones`  | false   | On first enable, probe the portal's own trigger-collider world bounds and pick the two `AudioZone`s whose volumes overlap. Lets designers drop a portal into a doorway without hand-assigning the zone refs. One-time scan at OnEnable; manually-assigned refs are kept as fallback if fewer than two are found. |

`zoneA` and `zoneB` are required (either assigned manually or filled by auto-detect). `OnValidate` errors if either is null or if `zoneA == zoneB`.

#### Inspector — Door

| Field           | Description                                                                       |
|-----------------|-----------------------------------------------------------------------------------|
| `doorSourceRaw` | MonoBehaviour implementing `IPortalDoorSource`. Null = always open.               |

`OnValidate` clears the reference and logs an error if the assigned MonoBehaviour doesn't implement the interface.

#### Inspector — Transmission

| Field                | Default | Description                                                      |
|----------------------|---------|------------------------------------------------------------------|
| `baseTransmission`   | 1.0     | Amplitude multiplier when fully open (`OpenProgress = 1`).       |
| `closedTransmission` | 0.1     | Amplitude multiplier when fully closed (`OpenProgress = 0`).     |
| `openLowPassHz`      | 12000   | Low-pass cutoff when fully open. Slightly muffled but audibly distinct from transparent — a door-less portal at least makes itself heard.    |
| `closedLowPassHz`    | 600     | Low-pass cutoff when fully closed.                                |

`OnValidate` warns if `closedTransmission > baseTransmission` or `closedLowPassHz > openLowPassHz` (values likely swapped).

#### Inspector — Blend Region

| Field                 | Default          | Description                                                              |
|-----------------------|------------------|--------------------------------------------------------------------------|
| `transitionAxisLocal` | `Vector3.forward`| Local-space axis pointing through the opening. Used for blend-factor computation. |
| `activationRadius`    | 50               | Distance from listener beyond which this portal is culled.               |

#### Properties

```csharp
public AudioZone ZoneA { get; }
public AudioZone ZoneB { get; }
public IPortalDoorSource DoorSource { get; }
public float ActivationRadius { get; }
public BoxCollider TriggerCollider { get; }
public event Action<AudioPortal> OnPortalParamsChanged;
```

#### Methods

```csharp
public float GetOpenProgress();                          // 0..1; returns 1 if no door source
public float GetTransmissionMultiplier();                // linear amplitude, dB-interpolated
public float GetCutoffHz();                              // log-frequency-interpolated
public Vector3 GetVirtualEmitterPosition(Vector3 listenerWorldPos);
public float GetBlendFactor(Vector3 listenerWorldPos);   // 0..1 along transition axis
public AudioZone GetZoneAtBlendFactorZero();             // zone on the blend=0 axis side
public AudioZone GetZoneAtBlendFactorOne();              // zone on the blend=1 axis side
public AudioZone GetOpposite(AudioZone z);               // solver graph traversal
```

`GetZoneAtBlendFactorZero/One` auto-detect which zone sits on each side of the transition axis (lazy-cached on first call). Designers never configure this — they just orient the GameObject's `+Z` through the opening.

---

### AmbientSource

**Namespace:** `AudioSystem.Propagation`
**Inheritance:** `MonoBehaviour`

Declares an ambient bed. Does not play audio directly — the `PropagationManager` drives a pooled `AmbientEmitter` on its behalf.

#### Inspector — Source

| Field                  | Default | Description                                                                          |
|------------------------|---------|--------------------------------------------------------------------------------------|
| `sourceZone`           | null    | The zone where this ambience originates (required).                                  |
| `loopingClip`          | null    | The looping audio clip. Must be loop-authored (no pops at boundary).                 |
| `ambienceMixerGroup`   | null    | `AudioMixerGroup` to route through. Use the Ambience bus for bus ducking / mix fades.|
| `useOcclusion`         | false   | Flag for the Occlusion Layout Builder scan. When true, this source's mixer group is included so a slot layer is generated under it. Does not change emitter audio behavior — propagation drives the per-emitter low-pass directly. |

#### Inspector — Level

| Field                  | Default | Description                                                                          |
|------------------------|---------|--------------------------------------------------------------------------------------|
| `sourceBaseVolumeDb`   | 0       | Baseline volume in dB. Propagation attenuation is subtracted from this. Clamped to [-60, 12] in the inspector. |
| `playOnStart`          | true    | Auto-register with `PropagationManager` on enable. Set false for sources controlled manually (weather toggling rain). |

#### Inspector — 3D Rolloff (optional override)

| Field                  | Default            | Description                                                                          |
|------------------------|--------------------|--------------------------------------------------------------------------------------|
| `overrideRolloff`      | false              | Master switch for the override block. When false, the emitter uses neutral defaults (Linear / 1m / 500m), tuned for ambient beds whose spatial position is dominated by the propagation solver. |
| `rolloffMode`          | `Linear`           | Distance falloff curve. Linear = evenly distributed; Logarithmic = matches Unity's default. Custom not supported here. |
| `minDistance` (Min 0.01)| 1                 | Distance at which the source is at full volume.                                       |
| `maxDistance` (Min 0.1) | 500               | Distance at which the source becomes inaudible (Linear) or quiet (Log).               |

Override settings apply to the AudioSource component on the managed emitter each time it's acquired from the pool. Leave `overrideRolloff = false` (the default) when the source's role is "propagation-routed bed" — the solver's per-emitter LPF and the portal-driven virtual-emitter position handle spatialisation. Turn on for tight point-source ambiences (a humming machine that needs a 10m maxDistance, etc.).

#### Properties

```csharp
public AudioZone SourceZone { get; }
public AudioClip LoopingClip { get; }
public AudioMixerGroup MixerGroup { get; }
public float SourceBaseVolumeDb { get; }
public bool UseOcclusion { get; }
```

#### Methods

```csharp
public void SetBaseVolumeDb(float db);   // clamped to [-80, 20]; picked up on next solve
public void Register();                  // manual registration (when playOnStart is false)
public void Unregister();                // fades out cleanly, doesn't abruptly stop
public void ApplyRolloffTo(AudioSource s);  // applies override (or defaults) to the emitter's AudioSource;
                                            // called by AmbientEmitter.Initialize on acquire
```

---

### AmbientEmitter

**Namespace:** `AudioSystem.Propagation`
**Inheritance:** `MonoBehaviour` (sealed)
**Menu:** Hidden from Add Component menu — managed programmatically by `PropagationManager`

Pooled persistent looping voice. Owns its own `AudioSource` and `AudioLowPassFilter`. Bypasses the SFX voice pool by design — routed through the designated Ambience mixer group for bus integration.

You generally don't interact with this component directly; the `PropagationManager` pool manages lifecycle.

#### Properties

```csharp
public AmbientSource OwningSource { get; }
public AudioPortal OwningPortal { get; }     // null for direct same-zone playback
public bool IsSilent { get; }                // safe-to-recycle check
public float TargetVolumeLinear { get; }
public float CurrentVolumeLinear { get; }
public Vector3 TargetPosition { get; }
```

#### Methods (called by PropagationManager)

```csharp
public void Initialize(AmbientSource owner, AudioClip clip, AudioMixerGroup group, float smoothSpeed);
public void FadeInTo(AudioPortal portal, float targetVolLinear, float targetCutoffHz, Vector3 pos);
public void SetTarget(float volumeLinear, float cutoffHz, Vector3 pos);
public void SetOwningPortal(AudioPortal portal);
public void FadeOut();
public bool Tick(float dt);                  // returns true when safe to release
public void ReleaseImmediate();              // unconditional stop + state reset
```

---

### AudioListenerZoneTracker

**Namespace:** `AudioSystem.Propagation`
**Inheritance:** `MonoBehaviour`

Attach to the GameObject that carries the player's Collider, usually the player root, not the camera that holds the `AudioListener`: Unity only sends trigger events to a GameObject with a Collider. Watches for trigger enter/exit on `AudioZone` and `AudioPortal` colliders and forwards events to `PropagationManager`.

Auto-adds a kinematic `Rigidbody` if none is present — required for Unity trigger events on static zone/portal colliders.

#### Inspector

| Field            | Default | Description                                                                |
|------------------|---------|----------------------------------------------------------------------------|
| `audioZoneLayer` | Everything | Optional layer mask filter. Limits trigger detection to specified layers. |

---

### IPortalDoorSource

**Namespace:** `AudioSystem.Propagation`
**Type:** Interface

Minimal contract any MonoBehaviour can implement to drive an `AudioPortal`'s open/closed state. Portable — propagation does not depend on any project-specific door system.

```csharp
public interface IPortalDoorSource
{
    float OpenProgress { get; }      // 0 = closed, 1 = open
    event System.Action OnChanged;   // fire when OpenProgress changes meaningfully
}
```

Firing `OnChanged` triggers an immediate re-solve on the subscribed portal. Spamming it every frame is safe but redundant; prefer threshold-based dispatch (e.g. `Δ ≥ 0.02`).

#### Adapter Pattern

Projects typically bridge their own door state (animator float, ScriptableObject channel, physics hinge) with a thin adapter MonoBehaviour:

```csharp
using AudioSystem.Propagation;

public class DoorAnimatorAdapter : MonoBehaviour, IPortalDoorSource
{
    public float OpenProgress => animator.GetFloat("openAmount");
    public event Action OnChanged;
    // ... fire OnChanged on threshold changes
}
```

---

### PropagationProximityCuller

**Namespace:** `AudioSystem.Propagation`
**Type:** `[Serializable]` class (sub-component of `PropagationManager`, not a separate MonoBehaviour)

Trims the active solver graph to zones and portals within range of the listener. Scales propagation to large levels without modifying solver logic.

#### Inspector (nested under PropagationManager)

| Field                     | Default | Description                                                                      |
|---------------------------|---------|----------------------------------------------------------------------------------|
| `cullCheckFrameInterval`  | 10      | Frames between active-set recomputations. 0 = culler disabled (everything active).|
| `globalMaxActiveZones`    | 64      | Hard cap on active zones after radius filter. Farthest dropped first.            |
| `globalMaxActivePortals`  | 128     | Hard cap on active portals after radius filter.                                  |

#### Properties

```csharp
public bool Enabled { get; }     // true if cullCheckFrameInterval > 0
```

The culler's first tick runs immediately regardless of interval, so the solver never sees an empty graph during startup.

## Occlusion Mixer Slots

Source: https://peppersfx.com/docs/api/occlusion-mixer-slots/

Pre-built per-bus pools of mixer groups used as routing targets for SFX voices that need cutoff modulation. Replaces per-source `AudioLowPassFilter` (which clicked on Stop→Play biquad reset). See [Manual chapter 14](https://peppersfx.com/docs/manual/occlusion-mixer-slot-pool/) for architecture and design rationale.

---

### OcclusionLayout

**Namespace:** `AudioSystem`
**Inheritance:** `ScriptableObject`
**Menu:** Create > Audio System > Occlusion Layout
**Editor window:** Window > Audio System > Occlusion Layout

Generated layout describing which mixer groups serve as occlusion slots for each user-authored bus. Authored at edit time by the Occlusion Layout Builder; consumed at runtime by `AudioManager` to build per-bus slot pools.

One asset per project. Reference it from `AudioManager` ▸ Occlusion Layout.

#### Properties

```csharp
public AudioMixer VoiceMixer { get; }
public IReadOnlyList<BusEntry> Buses { get; }
```

`VoiceMixer` is the mixer the layout was generated against. At runtime, `AudioManager` refuses to build slot pools if its assigned `voiceMixer` doesn't match this — re-run the builder against the correct mixer.

#### Nested Classes

```csharp
[Serializable]
public sealed class BusEntry
{
    public AudioMixerGroup Bus;   // user-authored bus (e.g. Footsteps)
    public SlotEntry[] Slots;     // generated occlusion slots under this bus
}

[Serializable]
public sealed class SlotEntry
{
    public AudioMixerGroup MixerGroup;   // the slot's mixer group (voice's outputAudioMixerGroup)
    public string CutoffParam;           // exposed parameter name for the slot's Lowpass cutoff
    public SendEntry[] Sends;            // per-ReverbSendBus send params, indexed by registry order
}

[Serializable]
public sealed class SendEntry
{
    public string RoomId;          // ReverbSendBus.BusName key
    public string SendLevelParam;  // exposed mixer parameter name for the Send level (dB)
}
```

---

### OcclusionSlot

**Namespace:** `AudioSystem`
**Inheritance:** Plain `public sealed class` (not a Unity component)

One slot inside a per-bus pool. Voices borrow a slot at acquire time (`AudioManager.GetVoice(container)`) and return it on `AudioManager.ReturnVoice(voice)`. While held, the voice's `outputAudioMixerGroup` is set to the slot's mixer group and any subsystem can modulate muffle by writing to the slot's exposed parameters.

#### Fields

```csharp
public readonly AudioMixerGroup MixerGroup;            // voice routes through this
public readonly string CutoffParam;                    // exposed Lowpass cutoff (Hz)
public readonly int IndexInPool;                       // position inside the BusSlotPool
public readonly AudioMixerGroup OwningBus;             // the user-authored bus this slot belongs to
public readonly Dictionary<string, string> SendLevelParams;  // ReverbSendBus.BusName → exposed Send level param (dB)
```

All fields are `readonly` — the slot is immutable once authored. Modulating the slot at runtime means writing to the mixer via `voiceMixer.SetFloat(slot.CutoffParam, hz)` or `voiceMixer.SetFloat(slot.SendLevelParams[roomId], levelDb)`.

`SendLevelParams` is empty when no `ReverbSendBusRegistry` was assigned at layout-generation time.

---

### AudioManager Slot Pool API

The acquire/release surface lives on `AudioManager`. Most projects never call these directly — `AudioManager.GetVoice(container)` handles slot lifecycle automatically based on the container's opt-in flags. The public API is exposed for diagnostics and custom routing scenarios.

#### Inspector Fields

| Field                                  | Default | Description                                                                              |
|----------------------------------------|---------|------------------------------------------------------------------------------------------|
| `voiceMixer` (`VoiceMixer`)            | null    | The mixer asset hosting the occlusion slot groups. Must match `OcclusionLayout.VoiceMixer`. |
| `occlusionLayout` (`OcclusionLayout`)  | null    | The generated layout asset. Required for slot pools to build at startup.                 |
| `defaultOcclusionSlotsPerBus`          | 6       | Default slots-per-bus used by the Occlusion Layout Builder. Per-bus overrides live on the layout asset. |
| `occlusionRayCount` (range 1–5)        | 3       | Rays per voice per occlusion tick. 1 = binary, 3+ = partial occlusion via blocked fraction. |
| `occlusionRaySpreadMeters` (range 0–2) | 0.5     | Width of the side-ray spread at the source end (meters).                                 |
| `occlusionGainSmoothingSeconds`        | 0.06    | Tau for per-frame exponential smoothing of `GainStack.OcclusionGain`.                    |
| `occlusionCutoffSmoothingSeconds`      | 0.04    | Tau for per-frame exponential smoothing of the slot's mixer cutoff parameter.            |
| `occlusionUpdateInterval`              | 0.2     | Seconds between OcclusionUpdate ticks (raycast cadence). Per-frame smoothing handles the in-between. |
| `occlusionMask`                        | ~0      | Physics layer mask used by the occlusion raycast.                                        |

#### Properties

```csharp
public AudioMixer VoiceMixer { get; }
public OcclusionLayout OcclusionLayout { get; }
public int DefaultOcclusionSlotsPerBus { get; }
public bool OcclusionSlotPoolsReady { get; }
```

`OcclusionSlotPoolsReady` is `true` once `InitializeOcclusionSlotPools` ran successfully at `Awake` — i.e. both `voiceMixer` and `occlusionLayout` are assigned, they agree on which mixer the layout targets, and at least one bus entry produced a slot pool.

#### Methods

##### AcquireOcclusionSlot

```csharp
public OcclusionSlot AcquireOcclusionSlot(AudioMixerGroup bus)
```

Acquires a free slot from the pool owned by `bus`. Returns null if (a) no pool exists for the bus (the bus wasn't in the layout), (b) the slot pool isn't ready, or (c) all slots are in use (pool exhausted — voice plays with no low-pass and no reverb sends, though occlusion's volume drop still applies; a throttled warning is logged once per second per bus). This method logs nothing for cases (a) and (b); `GetVoice(container)` warns once per bus for case (a) when an Occlusion Layout is assigned, since the layout is then out of date.

Caller is responsible for calling `ReleaseOcclusionSlot` exactly once. The voice pool's `ReturnVoice` handles this for voices acquired via `GetVoice(container)`.

##### ReleaseOcclusionSlot

```csharp
public void ReleaseOcclusionSlot(OcclusionSlot slot)
```

Returns the slot to its pool. Resets the slot's cutoff to 22 kHz and silences all reverb-send parameters so the next voice on this slot starts clean. Safe to call with null.

##### GetOcclusionSlotsInUse / GetOcclusionSlotCapacity

```csharp
public int GetOcclusionSlotsInUse(AudioMixerGroup bus)
public int GetOcclusionSlotCapacity(AudioMixerGroup bus)
```

Diagnostic counters. Both return `-1` if no pool exists for the given bus.

**Example — runtime diagnostic HUD:**

```csharp
foreach (var bus in interestingBuses)
{
    int inUse = AudioManager.Instance.GetOcclusionSlotsInUse(bus);
    int cap   = AudioManager.Instance.GetOcclusionSlotCapacity(bus);
    GUI.Label(rect, $"{bus.name}: {inUse}/{cap} slots");
}
```

## Reverb Send Buses

Source: https://peppersfx.com/docs/api/reverb-send-buses/

The "wet path" complement to occlusion. Source-side: voices in a tagged zone send to a per-zone reverb bus. Listener-side: each bus's character is defined by its own `ReverbSendBus` asset (the single source of truth) and driven onto the mixer each tick — parametric buses via six exposed SFX Reverb params, convolution buses via a native impulse-response plugin (§15.14). See [Manual chapter 15](https://peppersfx.com/docs/manual/reverb-send-buses-per-zone-reverb/) for architecture and design rationale.

---

### ReverbSendBus

**Namespace:** `AudioSystem`
**Inheritance:** `ScriptableObject`
**Menu:** Create > Audio System > Reverb Send Bus

One acoustic-space identity per asset. Owns one mixer group on the project's voice mixer, hosting one SFX Reverb effect with six exposed parameters that the listener-side driver writes per tick. The asset's `name` is the bus id.

#### Properties — Mixer Wiring

```csharp
public AudioMixer ReverbMixer { get; }           // mixer this bus lives on
public AudioMixerGroup ReverbBus { get; }        // mixer group this bus owns (auto-filled by Generate)
public AudioMixerGroup OutputDestination { get; } // optional cross-mixer output target
public AudioMixerGroup ParentGroup { get; }      // optional parent for the "ReverbsWet" return-bus convention
public string MixerGroupGuid { get; }            // hidden idempotency key for re-Generate rename-safety
```

#### Properties — Parametric Defaults

The 14 SFX Reverb parameters split into Basic and Advanced. Basic surfaces in the inspector by default; Advanced lives behind an EditorPrefs-backed foldout.

```csharp
// Basic (levels in millibels, mB, like Unity's SFX Reverb: 0 = full, -10000 = silent)
public float DryLevel { get; }       // -10000..0 mB. Default -10000 (wet-only).
public float Room { get; }           // -10000..0 mB. Default 0 (audible).
public float DecayTime { get; }      //   0.1..20 s. Default 1.49
public float ReverbLevel { get; }    // -10000..2000 mB. Default 200

// Advanced
public float RoomHF { get; }            // -10000..0 mB. Default 0
public float RoomLF { get; }            // -10000..0 mB. Default 0
public float DecayHFRatio { get; }      // 0.1..2 ratio. Default 0.83
public float ReflectionsLevel { get; }  // -10000..1000 mB. Default -2602
public float ReflectionsDelay { get; }  // 0..0.3 s. Default 0.007
public float ReverbDelay { get; }       // 0..0.1 s. Default 0.011
public float HFReference { get; }       // 1000..20000 Hz. Default 5000
public float LFReference { get; }       // 20..1000 Hz. Default 250
public float Diffusion { get; }         // 0..100 %. Default 100
public float Density { get; }           // 0..100 %. Default 100
```

Only the six listener-relevant parameters (`ReverbLevel`, `DecayTime`, `Room`, `RoomHF`, `DecayHFRatio`, `ReflectionsLevel`) are exposed to the runtime driver. The other eight describe bus identity and stay at the SO-authored snapshot defaults.

#### Properties — Convolution (Phase 3.2, Windows)

When `UseConvolution` is true the bus uses the native convolution plugin instead of SFX Reverb, and the parametric defaults above are ignored. See [Manual §15.14](https://peppersfx.com/docs/manual/reverb-send-buses-per-zone-reverb/#1514-convolution-reverb-windows-beta) for the authoring walkthrough and beta caveats.

```csharp
public bool UseConvolution { get; }          // false = parametric SFX Reverb; true = convolution plugin
public AudioClip ImpulseResponse { get; }    // the IR to convolve; must be CPU-readable (Decompress On Load / PCM)
public float ConvolutionWetTrimDb { get; }   // -80..+20 dB wet trim, 0 = unity
public int ConvolutionSlot { get; }          // index in the plugin's IR slot table; -1 = unassigned (hidden; Generate assigns it)
```

`ConvolutionSlot` is `[HideInInspector]` — `ReverbAutoCreator` assigns a stable free slot at Generate, and both the authored "IR Slot" effect param and the runtime IR upload (`AudioManager.UploadConvolutionIRs`) read it. Designers never set it.

#### Identity Helpers

```csharp
public string BusName { get; }                    // sanitized form of asset.name, safe for mixer param ids
public string ParamName(string suffix);           // "Reverb_<BusName>_<suffix>"

public const string SuffixWet           = "Wet";           // → ReverbLevel
public const string SuffixDecay         = "Decay";         // → DecayTime
public const string SuffixRoom          = "Room";          // → Room
public const string SuffixRoomHF        = "RoomHF";        // → RoomHF
public const string SuffixDecayHFRatio  = "DecayHFRatio";  // → DecayHFRatio
public const string SuffixReflections   = "Reflections";   // → ReflectionsLevel

public void GetDefaultProfile(AudioReverbProfile dest);   // non-allocating copy of SO defaults into dest
public static string SanitizeBusName(string raw);
```

`ParamName("Wet")` for a bus named "Bathroom" returns `"Reverb_Bathroom_Wet"` — that's the exposed mixer parameter the runtime driver writes to.

`GetDefaultProfile` is the **primary** (and only) source for `AudioManager.DriveReverbBusParams`: every parametric bus is driven from its own SO character each tick, unconditionally — no zone lookup. (Before the 2026-05-21 source-of-truth unification this was only a fallback "when no zone feeds the bus"; the zone-driven path was removed.) Convolution buses skip the driver entirely.

#### Editor Surface

```csharp
#if UNITY_EDITOR
public void EditorSetReverbBus(AudioMixerGroup group);
public void EditorSetOutputDestination(AudioMixerGroup group);
public void EditorSetMixerGroupGuid(string guid);
public void EditorSetConvolutionSlot(int slot);   // ReverbAutoCreator assigns the IR slot at Generate
#endif
```

Called by the per-asset inspector's Generate path. Runtime treats the SO as read-only.

---

### ReverbSendBusRegistry

**Namespace:** `AudioSystem`
**Inheritance:** `ScriptableObject`
**Menu:** Create > Audio System > Reverb Send Bus Registry

Flat list of every `ReverbSendBus` asset in the project. One per project. Reference it from `AudioManager` ▸ Reverb Send Bus Registry.

#### Properties

```csharp
public IReadOnlyList<ReverbSendBus> Buses { get; }
public int BusCount { get; }
```

#### Methods

```csharp
public ReverbSendBus FindByName(string busName);  // case-sensitive lookup by ReverbSendBus.BusName
```

#### Editor Surface

```csharp
#if UNITY_EDITOR
public void EditorSetBuses(List<ReverbSendBus> entries);
#endif
```

Called by the Reverb Send Buses window's Refresh button after re-scanning the project for `t:ReverbSendBus` assets.

---

### AudioReverbProfile

**Namespace:** `AudioSystem.Propagation`
**Inheritance:** `[Serializable] public class`

Reverb character parameters — six fields, each matching one of the listener-relevant SFX Reverb parameters. Authored on a `ReverbSendBus` SO (the source of truth) and copied into a non-allocating scratch buffer by the bus-params driver; also interpolatable across portal blend regions by the per-source ambient path.

#### Fields

```csharp
[Range(-10000f, 0f)]   public float Room             = -10000f;  // dB, overall wet gain
[Range(-10000f, 0f)]   public float RoomHF           = 0f;       // dB, HF tilt
[Range(0.1f, 20f)]     public float DecayTime        = 1.49f;    // seconds
[Range(0.1f, 2f)]      public float DecayHFRatio     = 0.83f;    // ratio
[Range(-10000f, 1000f)] public float ReflectionsLevel = -2602f;  // dB, early reflections
[Range(-10000f, 2000f)] public float ReverbLevel      = 200f;    // dB, late reverb tail
```

Default (`Room = -10000`) is **inaudible** — zones that don't author a profile produce zero behavior change. Set `Room` toward 0 dB to enable. This default is the profile's own: a new `ReverbSendBus` asset starts at `Room = 0` (audible).

#### Methods

```csharp
public static void Lerp(AudioReverbProfile a, AudioReverbProfile b, float t, AudioReverbProfile dest);
public void CopyFrom(AudioReverbProfile src);
public bool IsEffectivelySilent { get; }   // true when Room ≤ -9999 dB
public static readonly AudioReverbProfile Off;  // shared singleton, Room = -10000
```

`Lerp` and `CopyFrom` write into `dest` rather than returning a fresh instance, so the manager can blend across portal regions without per-frame allocation.

---

### AudioZone reverb fields

`AudioZone` (see [Propagation section](https://peppersfx.com/docs/api/propagation/#audiozone)) has one reverb-relevant field — **routing only**:

```csharp
public AudioMixerGroup ReverbBus { get; }       // routing target (source-side); null when unassigned
```

- **`ReverbBus`** — the mixer group voices physically in this zone send to. Drag in a `ReverbSendBus`'s `ReverbBus` field. Leave null for zones with no dedicated reverb (the source-side send is skipped for sources in that zone). Returns null at runtime when explicitly left empty.

> **Removed 2026-05-21.** `AudioZone.ReverbProfile` (the per-zone character field) was deleted in the source-of-truth unification. A bus's character now lives entirely on its `ReverbSendBus` SO; the zone only routes. The `entryFadeMeters` field (general propagation, see the AudioZone inspector table) still governs how the send fades across the zone boundary.

Multi-zone-to-bus aggregation is supported — several zones can share a `ReverbBus`. Because character is per-bus now, all zones feeding a given bus produce that bus's single SO character (no per-zone variation on a shared bus).

---

### AudioManager Reverb-Sends API

#### Inspector Fields

| Field                                                    | Default | Description                                                                                  |
|----------------------------------------------------------|---------|----------------------------------------------------------------------------------------------|
| `reverbSendBusRegistry` (`ReverbSendBusRegistry`)        | null    | Project's bus registry. Reverb-sends driver is gated on this being assigned and non-empty.   |
| `reverbSendsUpdateInterval` (range 0.005–0.5)            | 0.05    | Seconds between reverb-sends + bus-params driver ticks (default ≈ 20 Hz).                    |

#### Property

```csharp
public ReverbSendBusRegistry ReverbSendBusRegistry { get; }
```

#### Synchronous Send Write

```csharp
public void WriteReverbSendsImmediate(AudioVoiceEnhanced voice, AudioContainer container);
```

Synchronous per-voice send-level write, called by `AudioContainer.ConfigureAudioSource` right after the source has been positioned and routed. Ensures a voice's first audio frame already carries correct reverb routing, without waiting for the next driver tick (≈ 50 ms latency).

Safe to call when the registry is empty / mixer missing / voice has no slot / container opts out — the internal guards short-circuit and the call becomes a no-op.

Most projects never call this directly — `AudioContainer.ConfigureAudioSource` does. Surfaced publicly for custom playback paths that bypass the standard `Play()` route.

## Enums & Data Structures

Source: https://peppersfx.com/docs/api/enums-data-structures/

### VoicePriority
```csharp
public enum VoicePriority
{
    Low = 0,       // Least important: weighs 1/8
    Medium = 64,   // Standard priority: weighs 1/4
    High = 128,    // Important sounds: weighs 1/2
    Critical = 255 // The strongest weight, 1: last to go, but still stealable (Persistent is the exemption)
}
```

A voice's importance (`AudioVoice.GetImportance`) is how loud it is where it is heard times its priority's weight: priority ÷ 255, but at least 1/8, so a Low sound's distance and loudness count (since 3.1.0-dev.8; Low weighed 0, and always went first).

---

### AudioSpatialMode
```csharp
public enum AudioSpatialMode
{
    Unity,   // Unity's 3D from its AudioListener (default, as before 3.1)
    Pepper   // Pepper pans and attenuates from every listening point, weighted
}
```
`AudioManager.SpatialMode` (3.1.0-dev.8); see [Listening Point Methods](https://peppersfx.com/docs/api/audiomanager/#listening-point-methods).

---

### VoiceStealBehavior
```csharp
public enum VoiceStealBehavior
{
    Oldest,          // Steal longest-playing voice
    Quietest,        // Steal quietest voice
    Furthest,        // Steal most distant voice
    LowestPriority   // Steal by priority only
}
```

---

### MultiPositionType
```csharp
public enum MultiPositionType
{
    SingleEmitter,  // Single voice, dynamically positioned at dominant emitter
    Decorrelated    // All emitters play with phase decorrelation
}
```

---

### WeightedAudioClip
```csharp
[Serializable]
public class WeightedAudioClip
{
    public AudioClip clip;
    public float weight = 1f;           // Selection probability (0-10)
    public float volumeMultiplier = 1f; // Per-clip volume (0-1)
}
```

---

### SequenceEntry
```csharp
[Serializable]
public class SequenceEntry
{
    public AudioClip clip;
    public float volumeMultiplier = 1f;  // Per-clip volume
    public bool loop = false;             // Loop this clip
    public float delayAfter = 0f;         // Delay before next (0-5s)
}
```

---

### SwitchEntry
```csharp
[Serializable]
public class SwitchEntry
{
    public string switchValue = "";     // Value to match
    public AudioContainer container;     // Container to play
}
```

### ParameterSource
```csharp
public enum ParameterSource { Game, Distance, ApproachSpeed, Angle }   // AudioParameter.ValueFrom
```

### AudioRandomSource
```csharp
public enum AudioRandomSource { Pepper, Unity }   // AudioManager.RandomNumbers
```

### SwitchChangeMode, SwitchRange
```csharp
public enum SwitchChangeMode { NextPlayOnly, Crossfade, Restart }   // SwitchContainer.WhenSwitchChanges

[Serializable]
public struct SwitchRange                // AudioSwitchGroup.Ranges
{
    public string value;                 // the switch value in this range
    public float from;                   // where it starts, in the driving parameter's unit
    public SwitchRange(string value, float from)
}
```

---

### BlendEntry
```csharp
[Serializable]
public class BlendEntry
{
    public AudioContainer container;                                    // Layer container
    public AnimationCurve volumeCurve = AnimationCurve.Linear(0,0,1,1); // VolumeCurves layout: value -> level (0-1).
                                                                        // X: 0-1 for a named parameter, the
                                                                        // asset's unit for a Parameter asset.
    public float rootValue;                     // the value it was recorded at (pitch follow, Auto Layout); 0 = none
    public float regionMin, regionMax;          // Regions layout: where it plays
    public float fadeInWidth, fadeOutWidth;     // Regions layout: fade lengths inside the region
    public bool followPitch = true;             // pitch follow applies to this layer
    public float followRangeSemitones = 12f;    // pitch follow's limit, ±semitones
    public List<ParameterCurve> curves;         // curves for this layer only
}
```

---

### ParameterCurve, CurveProperty
```csharp
[Serializable]
public sealed class ParameterCurve
{
    public AudioParameter parameter;   // X axis; wins over parameterName
    public string parameterName;       // X axis by name (not clamped; 0 when unset)
    public CurveProperty property;     // VolumeDb, PitchCents, LowPassHz, HighPassHz
    public AnimationCurve curve;       // X: the parameter's unit; Y: dB, cents or Hz
    public float Evaluate(float x);    // filters: straight in octaves between keys
}

public enum CurveProperty { VolumeDb, PitchCents, LowPassHz, HighPassHz }
```
On `AudioContainer.ParameterCurves` (every sound below that container) or a `BlendEntry`'s `curves` (that layer). Read in the play's scopes every frame. On one container, and down the tree: dB and cents add (into `GainStack.CurveGain` and `PitchStack.Curve`), the lowest low-pass and the highest high-pass win. Filter curves switch on the `AudioLowPassFilter` / `AudioHighPassFilter` every pooled voice has had, switched off, since the pool was built, ease the cutoff over about 20 ms (set at once before the first sample), and switch it off when fully open (22000 Hz / 10 Hz).

### BlendLayout, CrossfadeShape, BlendLoopMode, SilentLayerBehaviour
```csharp
public enum BlendLayout { VolumeCurves, Regions }
public enum CrossfadeShape { Linear, EqualPower, SCurve }  // -6 dB, -3 dB, eased; each pair complementary
public enum BlendLoopMode { FromLayers, ForceLoop, ForceOneShot }   // BlendContainer.LoopMode
public enum SilentLayerBehaviour { KeepPlaying, Virtualize }        // BlendContainer.SilentLayers
```

---

### SlewMode
```csharp
public enum SlewMode
{
    None, // heard at once
    Rate, // fixed speed in units per second, rising and falling
    Ease  // closes 95% of the gap in a set time, rising and falling
}
```
See [ParameterSlew](https://peppersfx.com/docs/api/parameters/#parameterslew).

---

### AudioUpdateMode
```csharp
public enum AudioUpdateMode
{
    Automatic, // Pepper's per-frame step runs after every LateUpdate, before the audio is mixed
    Manual     // it runs only when you call AudioManager.Tick()
}
```

---

### AudioStatistics
```csharp
public class AudioStatistics
{
    public int activeVoices;            // real voices now
    public int availableVoices;         // free in the pool
    public int totalVoices;             // Max Real + Max Virtual
    public int liveRealVoices;          // every pooled AudioSource alive: playing, virtual or free
    public int realVoiceBudget;         // Max Real Voices
    public int poolSize;                // Max Real + Max Virtual + Steal Headroom: what liveRealVoices stays at
    public int voicesLostToDestruction;
    public int activeLoops;
    public int registeredContainers;
}
```

**Usage:**
```csharp
var stats = AudioManager.Instance.GetStatistics();
Debug.Log($"Real voices: {stats.activeVoices}/{stats.realVoiceBudget}, pool {stats.liveRealVoices}/{stats.poolSize}");
```

---

### AudioVoiceDebugInfo
```csharp
[Serializable]
public class AudioVoiceDebugInfo
{
    public int id;
    public string containerName;
    public string eventName;
    public string clipName;
    public string busName;
    public bool isPlaying;
    public bool isVirtual;
    public bool isLooping;
    public float volume;
    public float volumeDb;
    public float pitch;
    public float time;
    public float length;
    public float playTime;
    public bool is3D;
    public float distance;
    public float distanceToListener;
    public Vector3 position;
    public AudioVoice voice;
    public int priority;
    public int playId;                          // one number per play: all of an engine's layers share it
    public bool persistent;
    public VoiceVirtualReason virtualReasonKind;  // None while real
    public string virtualReason;                // its words, plus ", fading" while it fades down
    public float levelDb;                       // its whole gain stack, in dB: Pepper's gain, before Unity's own 3D fade and the mixer ("Gain dB" in the windows)
    public float pitchSemitones;                // from the recording
    public string region;                       // a Regions Blend layer's region and where the value is
    public int listeningPoint;                  // its play's point, an index into ListeningPoints (-1: none) (3.1.0-dev.8)
    public bool pepperPanned;                   // Spatial Mode = Pepper pans it
    public float spatialGainDb;                 // Pepper's level from the points, dB
    public float pan;                           // Pepper's pan, -1 left … 1 right
}

public enum VoiceVirtualReason
{
    None, OverTheCap, SilentLayer, PastMaxDistance, HeldByCode, BusPaused, EmitterPaused, Stopping
}

public sealed class AudioPlayDebugInfo           // AudioManager.GetPlaysDebug
{
    public int playId;
    public string eventName, containerName, busName;
    public AudioEmitter emitter;                 // null: posted without one
    public AudioHandle handle;                   // its own values: handle.ParameterCount and the listing beside it
    public bool persistent, isVirtual;
    public List<AudioVoiceDebugInfo> voices;
}
```

**Why a voice is virtual** (`VoiceVirtualReason`, checked in this order): **Stopping** (it ends once faded down), **BusPaused** (its bus or a parent is paused), **EmitterPaused** (its emitter is switched off with On Disable = Pause), **HeldByCode** (`AudioVoice.MakeVirtual`), **PastMaxDistance** (its Attenuation asset's), **SilentLayer** (a Virtualize Blend's layer below its threshold), else **OverTheCap** (more would be heard than Max Real Voices, and its play is among the least important).

**Usage:**
```csharp
var voices = AudioManager.Instance.GetActiveVoicesDebug();
foreach (var v in voices)
    Debug.Log($"{v.eventName}: {v.clipName} {v.levelDb:F1} dB {(v.isVirtual ? "virtual: " + v.virtualReason : "real")}");
```

## Loading

Source: https://peppersfx.com/docs/api/loading/

**Namespaces:** `AudioSystem.Loading` (always available) · `AudioSystem.Loading.Addressables` (gated by `com.unity.addressables`)

The clip-loading layer: import policy, warming, and the optional Addressables backend. See the [User Guide → Audio Loading & Memory](https://peppersfx.com/docs/manual/audio-loading-memory/) for the concepts and setup.

### Always available (SFXSystem.Runtime)

```csharp
// The seam every container resolves clips through. Default = DirectClipSource.
interface IAudioClipSource {
    bool TryGetClip(in AudioClipRef clipRef, out AudioClip clip); // hot path; false = cold → drop
    bool SupportsAddressables { get; }   // false on Direct — tells a real misconfig from a cold-drop
    void Pin(string address);            // hold an addressable clip resident (persistent holders); no-op on Direct
    void Unpin(string address);
}

// Optional companion an addressable source also implements (Direct does not).
interface IVoiceLifecycleListener {
    void OnVoiceBound(AudioVoice voice);     // source.clip just assigned → voice refcount++
    void OnVoiceReleased(AudioVoice voice);  // voice returning to pool → voice refcount--
}

readonly struct AudioClipRef {
    AudioClip DirectClip; string Address;    // an entry is EITHER a direct clip OR an address
                                             // Address = the Addressables address (what a bank label resolves to),
                                             // not the asset GUID unless the address IS the GUID
    bool HasAddress; bool IsEmpty;
    AudioClipRef(AudioClip clip);
    AudioClipRef(AudioClip clip, string address);
}

static class AudioClipSources {
    static IAudioClipSource Active { get; set; }          // default DirectClipSource; assigning null reverts to it
    static IVoiceLifecycleListener VoiceListener { get; } // cached; the active source's listener, if any
    // Resolve + diagnose: warns once-per-address when an address can't resolve for lack of a backend
    // (vs an expected cold-drop). Containers / AmbientSource use this instead of Active.TryGetClip.
    static bool TryResolve(in AudioClipRef clipRef, Object context, out AudioClip clip);
}

// Pre-load clip audio data ahead of play (coroutines). No Addressables dependency.
static class AudioClipWarmer {
    static bool IsWarm(AudioClip);
    static IEnumerator Warm(AudioClip);
    static IEnumerator WarmAll(IEnumerable<AudioClip>);    // parallel
    static bool Unload(AudioClip);                         // blunt — no live-voice check (Addressables handles that)
}

// AudioManager convenience hosts (it's the persistent coroutine runner). Return the coroutine.
Coroutine AudioManager.WarmClip(AudioClip);
Coroutine AudioManager.WarmClips(IEnumerable<AudioClip>);
Coroutine AudioManager.WarmContainer(AudioContainer);      // uses EnumerateClips()

// Every clip a container could play (cycle-safe; recurses Switch/Blend children):
IEnumerable<AudioClip> AudioContainer.EnumerateClips();

// Optional addressable key per entry (empty for direct entries):
class WeightedAudioClip { AudioClip clip; float weight; float volumeMultiplier; string address; } // Random
class SequenceEntry     { AudioClip clip; …; string address; }                                    // Sequence
class RoutingEntry      { AudioClip clip; string address; }                                        // Routing

// AmbientSource: addressable loop clip — pins the clip on the active source for its active life
// (and moves the pin if the active source changes, e.g. the Addressables backend starting later).
string   AmbientSource.LoopingClipAddress;   // serialized field; Inspector: "Looping Clip Address"
AudioClip AmbientSource.PlayableClip;         // resolved clip; null while an addressable clip is loading

// Raised on genuine listener zone-membership change (the addressable bank binder subscribes).
// Always paired one-to-one: an Exit is also raised when ResyncListenerAfterTeleport leaves a zone,
// when a zone the listener is in is disabled/destroyed/unloaded, and when the manager itself is destroyed.
static event Action<AudioZone> PropagationManager.ListenerEnteredZone;
static event Action<AudioZone> PropagationManager.ListenerExitedZone;
```

### Gated by com.unity.addressables

Namespace `AudioSystem.Loading.Addressables`; assembly `SFXSystem.Addressables` (compiles only when the package is present).

```csharp
// Refcounted addressable clip source. Installed as AudioClipSources.Active when AddressableAudioRuntime starts the backend.
sealed class AddressableClipSource : IAudioClipSource, IVoiceLifecycleListener {
    float LingerSeconds;                    // keep-warm after refcount 0 (default 5)
    void BankAcquire(string address);       // called by AudioBank
    void BankRelease(string address);
    void Tick(float unscaledNow);           // linger sweep (driven by AddressableAudioRuntime)
    void ReleaseAll();                       // teardown hard-reset (truth is zero)
    void GetDebugEntries(List<DebugEntry>);  // overlay readout
}

// A bank = an Addressables label. Preload loads/refcounts every clip under it; Release drops them.
sealed class AudioBank {
    AudioBank(string label, AddressableClipSource source);
    string Label; bool IsLoaded;
    void Preload();   // idempotent (refcounted per bank; survives re-entered zones)
    void Release();
}

// MonoBehaviours (Add Component ▸ Audio ▸ Loading):
ZoneAudioBank            // on an AudioZone GameObject; holds the bank label (BankLabel)
AddressableAudioRuntime  // starts the backend: installs the source, binds zone events, ticks linger.
                         // The backend persists across scene loads (own hidden DontDestroyOnLoad object);
                         // one runtime is enough — later ones (other scenes) log and do nothing.
```

**Refcount model:** `resident(address) = (banks holding it) + (live voices bound to it) + (pins) > 0`. Bank `Release`, `OnVoiceReleased`, and `Unpin` each decrement; the real unload fires at 0, after `LingerSeconds`. A clip a bank or pin loads also has its audio data loaded, so its first play doesn't hitch. Teardown (`ReleaseAll`) force-releases everything regardless of count; it runs only when the backend is destroyed (application quit / leaving Play Mode), not on scene loads.

**Cold-post policy (v1):** a not-yet-resident addressable clip makes `TryGetClip` return false → the play is dropped (like a null clip, but without the missing-clip warning). A Sequence container stays on a cold entry, so its next play tries that entry again; an Auto Advance run ends there. Bank preload is the warm path; there is no defer-and-play-late in v1.

**Editor tooling:** **Window ▸ Audio System ▸ Addressable Audio Authoring** (Convert/Revert containers; gated assembly `SFXSystem.Addressables.Editor`) and **Window ▸ Audio System ▸ Loading Validator** (always-on; runs via reflection even without the package).

## Netcode (Multiplayer)

Source: https://peppersfx.com/docs/api/netcode-multiplayer/

**Namespace:** `AudioSystem.Netcode`
**Assemblies:** `SFXSystem.Netcode` (core, references Runtime only) · `SFXSystem.Netcode.Ngo` / `.FishNet` (adapters, auto-gated on their package)

Backend-agnostic networked audio. See the [User Guide → Multiplayer (Netcode)](https://peppersfx.com/docs/manual/multiplayer-netcode/) for concepts, setup, and the mental model. No audio crosses the wire — only a ~36-byte descriptor.

### NetworkedAudioManager

The static gameplay façade.

| Method | Description |
|---|---|
| `AudioHandle PostNetworkedEvent(string eventName, Vector3 position, GameObject emitter = null, bool? independentVariation = null)` | One-shot: plays locally now (echo) + relays to other peers. Returns the **local** handle. `emitter` attaches it to a moving networked object (null = static). `independentVariation`: `null` = the event's authored default; `true`/`false` = override. Warns + plays local-only if the event has no stable ID. |
| `AudioHandle PostNetworkedEvent(int stableId, …)` | Same, by stable ID. |
| `NetworkedSoundHandle PostNetworkedLoop(string eventName, Vector3 position, GameObject emitter = null, bool? independentVariation = null)` | Starts a **shared persistent (loop)** sound tracked for stop, culling + late-join (phase per the event's Loop Sync Tier). Returns a handle carrying the shared instance ID + the local echo. On a dedicated server, warns and redirects to `PostServerLoop`. |
| `void StopNetworked(NetworkedSoundHandle handle)` | Stops the local echo now **and** broadcasts the stop (scope `All` for server-authored, else `Others`). Safe on a null / pure-local handle. |
| `AudioHandle PostServerEvent(string / int, …)` | **Server-authored** one-shot to everyone (scope `All`), no local echo. Warns + no-ops on a client. Off-session → plain local play. |
| `NetworkedSoundHandle PostServerLoop(string eventName, …)` | Server-authored loop to everyone; handle's `Local` is null, `ServerAuthored` is true. Tracked for late-join. |
| `AudioHandle PostNetworkedScheduled(string / int, Vector3 position, double networkTime, …)` | Fire at a shared **network time**; returns the scheduled local echo. Warns if the event name/id is unknown. |
| `void PostServerScheduled(string / int, …, double networkTime, …)` | Server-authored scheduled one-shot (scope `All`). |
| `AudioHandle PostNetworkedQuantized(string, Vector3, Quantize, …)` | Schedule on the next beat/bar of the shared musical grid. Requires a transport (`SetTempo`); warns + returns null otherwise. |
| `void PostServerQuantized(string, Vector3, Quantize, …)` | Server-authored quantized cue. |
| `void ResyncClock()` | Force the network clock to hard-re-sample its offset next tick. |

### NetworkedSoundHandle

| Member | Description |
|---|---|
| `ulong InstanceId` | Shared cross-client identity, `(ownerClientId << 32 | counter)`. `0` = not a networked instance. Server-authored loops use a reserved `0xFFFFFFFF` owner namespace. |
| `AudioHandle Local` | The instigator's local-echo handle. Null off-session and for server-authored / Tier-2 loops. |
| `bool IsValid` | True when `InstanceId != 0`. |
| `bool ServerAuthored` | True for `PostServerLoop` — selects the stop scope (`All`). |

### NetworkMusicTransport & NetworkClock

`NetworkMusicTransport` (static) — shared tempo/phase:

| Member | Description |
|---|---|
| `void SetTempo(double bpm, int beatsPerBar)` | **Server only.** Author the transport; networked on change, replayed to late joiners. A mid-session change re-anchors seamlessly at the next bar. |
| `bool IsSet` · `double Bpm` · `int BeatsPerBar` · `double PhaseAnchor` | Current grid state (`PhaseAnchor` = network time of beat 0). |
| `double NextBeatNetworkTime(double from)` / `NextBarNetworkTime(double from)` | The next grid slot ≥ `from`, in network time. |

`NetworkClock` (static) — network-time ↔ local dsp:

| Member | Description |
|---|---|
| `double NetworkTime` | This machine's current network time (synced server time; local dsp off-session). |
| `double NetworkToLocalDsp(double t)` | Map a network-time target to local `AudioSettings.dspTime` for `PlayScheduled`. |
| `void ResyncClock()` | Force a hard re-sample of the offset. |

### NetworkAudioSettings

MonoBehaviour — scene config + game-supplied hooks.

| Member | Description |
|---|---|
| `bool ProximityCulling` | Opt into culling. Default off. |
| `Func<ulong, Vector3?> ListenerPositionProvider` | Game-supplied per-client listener position (server calls it). Null → culling inert. Assigned in code. |
| `NetworkAudioValidator ServerValidator` | Server-side authority gate. Null → allow-all. Assigned in code. |
| `float DefaultAudibleRadius` · `float LoopReevalSeconds` | Culling fallback radius + loop re-eval rate. |
| clock/lead tunables | `ClockSmoothing`, `ClockResyncThreshold`, `ScheduleLeadFloor`, `ScheduleLeadRttFactor`. |

### NetworkAudioEvent & NetworkAudioScope

`NetworkAudioEvent` (struct) — the wire payload:

| Field | Description |
|---|---|
| `int EventId` | The `AudioEvent.StableId` to play. |
| `Vector3 Position` | World position — also the emitter fallback/anchor. |
| `ulong EmitterNetId` | Optional network-object id to attach to. `0` = static. |
| `ulong InstanceId` | Shared identity for a persistent/loop sound. `0` = a one-shot. |
| `int Seed` | Variation seed. Non-zero forces the SAME variant on every client; `0` = independent. |

Plus `Pack` / `Unpack` — the canonical **36-byte** wire format (round-trip covered by `NetworkAudioEventPackTests`).

`NetworkAudioScope` (enum): `Others` (default — everyone but the sender) · `All` (server-authored) · `Owner` *(reserved)* · `Proximity` *(reserved enum value; culling is realised on the `Others`/`All` paths as "don't send")*. Passing an unhonored scope logs a warning and relays as `Others`.

**Per-event authoring** (`AudioEvent`, Multiplayer foldout, shown only with a backend installed): `Unreliable Delivery`, `Independent Variation (default)`, `Loop Sync Tier` (0/1/2; Tier 2 is **experimental** — see [User Guide §17.4](https://peppersfx.com/docs/manual/multiplayer-netcode/#174-local-vs-networked--the-mental-model)). For the `INetworkAudioTransport` boundary — implementing a new backend — see [User Guide §17.9](https://peppersfx.com/docs/manual/multiplayer-netcode/#179-extending-writing-a-new-backend-adapter).

## Quick Reference

Source: https://peppersfx.com/docs/api/quick-reference/

### Common Patterns

**Play Sound:**
```csharp
myEvent.Post();
myEvent.Post(gameObject, transform.position);
```

**Control:**
```csharp
AudioHandle h = myEvent.Post();
h.SetVolumeScale(0.5f);
h.SetPitchOffset(2f);
h.Stop(1f);
```

**Bus:**
```csharp
AudioManager.Instance.SetBusVolume("Music", -6f, 1f);
```

**State:**
```csharp
AudioManager.Instance.SetState("Underwater", 1.5f);
```

**Switch:**
```csharp
AudioManager.Instance.SetSwitch("Surface_Type", "Metal");
```

**RTPC:**
```csharp
AudioManager.Instance.SetRTPC("CombatIntensity", 0.75f);
AudioManager.Instance.TransitionRTPC("CombatIntensity", 1.0f, 2f);
```

**Global Controls:**
```csharp
AudioManager.Instance.StopAllSounds();
AudioManager.Instance.PauseAll();
AudioManager.Instance.UnpauseAll();
AudioManager.Instance.MuteAll(true);
```

**Multi-Position:**
```csharp
AudioMultiHandle mh = myEvent.PostMultiPosition(emitterParent);
mh.SetVoiceVolumeScale(0, 0.5f);  // Per-emitter control
mh.UpdatePositions(newTransforms);
```

## Version History

Source: https://peppersfx.com/docs/api/version-history/

**v3.1.0 (dev)** - October 2026
- Dev snapshots for testing in other projects; see `CHANGELOG.md` at the package root and "Changes since 3.0.0" in `BETA_KNOWN_ISSUES.md` for what changed.
- **Scoped parameters:** [AudioParameter](https://peppersfx.com/docs/api/parameters/#audioparameter) assets, [AudioEmitter](https://peppersfx.com/docs/api/parameters/#audioemitter), per-play values on `AudioHandle`, global `SetParameter`/`RampParameter`, `AudioEvent.Post(AudioEmitter)`, `AudioManager.Post`, and `AudioManager.UpdateMode`/`Tick`. The string RTPC API is the global scope. Blend Containers read their parameter per play, once a frame; `BlendContainer.UpdateBlend` is obsolete.
- **Parameter curves, regions and pitch follow:** [ParameterCurve](https://peppersfx.com/docs/api/enums-data-structures/#parametercurve-curveproperty) (volume dB, pitch cents, low- and high-pass Hz) on any container and Blend entry; Blend `Layout` (Volume Curves or Regions), `Crossfade` shape and `AutoLayout`; `PitchFollowParameter` with per-entry `rootValue`, `followPitch` and `followRangeSemitones`; `GainStack.CurveGain`; per-voice filters for filter curves.
- **Nested containers:** every play keeps a tree of the containers it reached, so nested Blends read their parameters per play and late voices get their Blend's curve and Volume. New `AudioContainer.UsesParentPositioning` / `UsesParentOutput`.
- **Listening points:** `AudioManager.AddListeningPoint` / `RemoveListeningPoint` / `ListeningPoints` / `DriveUnityListener`, [AudioListeningPoint](https://peppersfx.com/docs/api/audioextensions-utilities/#audiolisteningpoint), and `ListenerUtil.TryGetPosition`. With a point registered the scene is never searched; without one, the search warns once and runs at most once a frame.
- **Parameter smoothing:** [ParameterSlew](https://peppersfx.com/docs/api/parameters/#parameterslew) (None, Rate, Ease with separate rise and fall) on `AudioParameter`, per-emitter and per-play overrides, `SnapParameter` / `SnapAllParameters`, and the Bypass Slew While parameter.
- **Virtual voices keep their place:** positions in samples on the audio clock at the voice's pitch (`AudioVoice.VirtualSamples`), a short fade around virtualizing and realizing (`GainStack.RealizeGain`, `GetGainWithoutRealize`), and `AudioContainer.DopplerLevel`.
- **The play is the unit of the voice pool:** whole-play steals after making room (`AudioContainer.EstimateVoiceCount`), plays real or virtual as a whole with stickiness, one start time per play, `BlendContainer.LoopMode` / `SilentLayers` / `SilentThresholdDb` (`Loop` obsolete), `AudioEvent.Persistent`, Unity voice-limit warnings and `AudioSource.priority`.
- **No forced multiplayer code:** the `SFXSYSTEM_DISABLE_NETCODE` define leaves the netcode assemblies out; `PropagationManager` hears from the registered listening point.
- **Named emitter points:** [AudioEmitter](https://peppersfx.com/docs/api/parameters/#audioemitter) `Points`, `Post(event, "Exhaust")` / `Post(event, number)`, `FindPoint`, `SetPoint`, `GetPointOffset` / `GetPointPosition`, `EmitterPoint`; `Velocity`, `SetVelocity`, `ClearVelocity`; `AudioEvent.Post(AudioEmitter, point)` and `AudioManager.Post(event, emitter, point)`.
- **Switches per sound, following while they play:** [AudioSwitchGroup](https://peppersfx.com/docs/api/parameters/#audioswitchgroup) assets (names still work), with `DrivenBy`, `Ranges` and `Hysteresis`; `SetSwitch` / `ClearSwitch` / `TryGetSwitch` / `GetEffectiveSwitch` on `AudioEmitter` and `AudioHandle`; `AudioManager.SetSwitch(AudioSwitchGroup, value)`, `ClearSwitch`, `GetSwitch(AudioSwitchGroup)`; `SwitchContainer.SwitchGroup`, `WhenSwitchChanges` and `CrossfadeTime`; `GainStack.SwitchGain`.
- **Distance assets and built-in values:** [AudioAttenuation](https://peppersfx.com/docs/api/parameters/#audioattenuation) (volume, low-pass, high-pass and spread over metres, Max Distance), `AudioContainer.Attenuation`, `ContainerOverrides.attenuation`, `AudioHandle.SetAttenuation` / `ClearAttenuation`; `AudioParameter.ValueFrom` (`ParameterSource`: Distance, ApproachSpeed, Angle) and `IsBuiltIn`. `AudioContainer.MaxDistance`'s setter writes a runtime override.
- **Audition outside Play mode:** Window > Audio System > Audition and [AudioAudition](https://peppersfx.com/docs/api/editor-tools/#audioauditionwindow-and-audioaudition) (`AuditionLayer`, `AuditionInputs`): play a container tree with parameter sliders, switch values, a sweep and a layer readout while editing it.
- **One-shots per emitter:** `AudioEvent.MaxInstancesPerEmitter` / `CooldownPerEmitter`; [PostValues](https://peppersfx.com/docs/api/audioevent/#postvalues) and the `Post` overloads that take it (event, emitter, manager); `AudioManager.RandomNumbers` (`AudioRandomSource`: Pepper's own streams by default, or Unity); `AudioEmitter.RandomSeed` / `SetRandomSeed`; Random containers' Avoid Repeat Last per emitter.
- **Bus property curves:** `AudioBus.ParameterCurves` (Volume, Low Pass, High Pass on global values), `LowPassParameter` / `HighPassParameter` (exposed mixer cutoffs), `CurveVolumeGain`, `LowPassHz`, `HighPassHz`; the bus inspector's Add Low Pass / High Pass buttons.
- **Lifecycle, teardown and pause (3.1.0-dev.5):** `AudioManager.PersistAcrossScenes` and Pepper's own "AudioVoices" root (switching the manager off changes nothing); `AudioManager.Inert` for dedicated servers; `AudioEmitter.WhenDisabled` (`EmitterDisableMode`: Keep, Stop, Pause) and `StopFadeSeconds`; `EventAction.scope` (`ActionScope`: All, ThisEmitter); `AudioBus.Pause` / `Resume` / `IsPaused` / `WhilePaused` (`BusPauseBehaviour`); `AudioEvent.TimeMode` and `AudioBus.DuckingTimeMode` (`AudioTimeMode`: Scaled, Unscaled). Finished handles ignore new `OnStarted` / `OnStopping` / `OnLoop` subscriptions.
- **Tools (3.1.0-dev.6):** the Audition plays events too, runs any number of sweeps (`SweepMode`), replays recordings and shows written values ([AudioAudition](https://peppersfx.com/docs/api/editor-tools/#audioauditionwindow-and-audioaudition)); the [Live View](https://peppersfx.com/docs/api/editor-tools/#audioliveviewwindow-audioemitterrecorder-and-audioparameterrecording) with `AudioManager.GetPlaysDebug`, `AudioPlayDebugInfo`, `VoiceVirtualReason`, the new `AudioVoiceDebugInfo` fields, `AudioHandle`'s value listing and `AudioEmitter.AllEnabled`; `AudioEmitterRecorder` and `AudioParameterRecording`; [Loop Analysis](https://peppersfx.com/docs/api/editor-tools/#loopanalysiswindow); the [Engine Builder](https://peppersfx.com/docs/api/editor-tools/#enginebuilderwindow); the [Container Validator](https://peppersfx.com/docs/api/editor-tools/#audiocontainervalidator-container-validator)'s project-wide rules and `ValidateEvent`; [folder import rules](https://peppersfx.com/docs/api/editor-tools/#audio-import-settings-and-folder-rules) (no settings asset ships in the package); `AudioStatistics.poolSize`; undoable bus faders.
- **Routing, mix and positions (3.1.0-dev.7):** offsets that stick: `AudioEmitter.VolumeOffsetDb` / `PitchOffsetCents`, `AudioHandle.SetVolumeOffset` / `VolumeOffsetDb` / `VolumeScale` / `PitchOffset`, `PostValues.WithVolumeOffset` / `WithPitchOffset` / `VolumeOffset`, `GainStack.EmitterGain`, `PitchStack.Emitter`, and a handle's `SetVolumeScale` / `SetPitchOffset` reaching voices it starts later; posting anywhere on an emitter (`AudioEmitter.Post(evt, localOffset, values)`, `AudioEvent.PostAtOffset`, `AudioManager.Post(evt, emitter, localOffset, values)`) and moving a playing sound (`AudioHandle.SetLocalOffset` / `SetWorldPosition`); timed posts (`Post(emitter, startDsp, startOffsetSeconds, values)` on the event, emitter and manager) and `AudioEvent.EstimateDuration` (`AudioDuration`); Pepper's Doppler (`AudioContainer.Doppler`, `DopplerExaggeration`, `DopplerMaxCents`, `DopplerMode`, `DopplerMath`), `AudioEmitter.Teleport`, `AudioListeningPoint.ClearVelocity`; ducks combining by the deepest (`AudioBus.ApplyDucking`); `AudioState.VolumeMode` (`StateVolumeMode`: SetLevel, Offset), `AudioManager.ClearState`, `AudioBus.StateOffsetDb` / `PlayerVolumeDb` / `IsMuted`, `AudioManager.MasterVolumeDb` / `SetMasterVolumeDb` / `IsAllMuted`; `SetBusVolume` with an unknown name changes nothing.
- **Many cars and split screen (3.1.0-dev.8):** `AudioManager.SpatialMode` ([AudioSpatialMode](https://peppersfx.com/docs/api/enums-data-structures/#audiospatialmode): Unity, Pepper), Pepper panning and attenuating 3D sounds from every listening point by its `Weight` and `PanWidth` (`GainStack.SpatialGain`), reproducing Unity's 3D at one point; `AudioManager.SetPrimaryListeningPoint` / `PrimaryListeningPoint`, `AudioListeningPoint.IsPrimary`; a point whose transform is destroyed is removed; each play measured from its own point, gliding over 100 ms when it changes; `AudioBus.MaxRealVoices` / `RealVoiceCount`; `AudioManager.StealFadeSeconds` (steals fade); Low priority weighs 1/8 in importance; every pooled voice carries its low- and high-pass from the start; `AudioVoiceDebugInfo.listeningPoint` / `pepperPanned` / `spatialGainDb` / `pan`.

**v3.0.0** - July 2026
- **New subsystem: Multiplayer (Netcode)** — backend-agnostic networked audio. Post a sound on one machine and every player hears it; no audio crosses the wire, only a ~36-byte descriptor each machine plays locally. Install one netcode stack and its adapter lights up automatically; a backend you didn't install never compiles. See [Manual chapter 17](https://peppersfx.com/docs/manual/multiplayer-netcode/) and [API → Netcode (Multiplayer)](https://peppersfx.com/docs/api/netcode-multiplayer/).
  - `NetworkedAudioManager` façade — `PostNetworkedEvent` / `PostNetworkedLoop` / `StopNetworked`, server-authored `PostServer*`, scheduled/quantized cues
  - Emitter binding (sound follows a moving `NetworkObject`), shared loop lifetime + late-join snapshot, cross-client variation parity (seed on the wire)
  - Competitive hardening — server authority/validation, proximity culling (= don't-send), per-event `Unreliable Delivery`
  - Musical sync — `NetworkClock` (network-time ↔ local dsp) + `NetworkMusicTransport` (tempo/phase), loop phase-lock tiers (Tier 2 **experimental** — not for production yet)
  - `NetworkAudioSettings` scene component; **Network Audio Debug** window; per-event **Multiplayer** foldout on `AudioEvent`
  - Adapters: NGO 2.x (`SFXSYSTEM_NGO`) and FishNet v4 (`FISHNET`). *Verified on FishNet, one PC and two PCs; NGO has had light testing only.*
- **New subsystem: Audio Loading & Memory** — tiered, opt-in control over clip RAM footprint and load timing. Default direct-reference path is unchanged and zero-overhead. See [Manual chapter 16](https://peppersfx.com/docs/manual/audio-loading-memory/) and [API → Loading](https://peppersfx.com/docs/api/loading/).
  - `AudioClipWarmer` + `AudioManager.WarmClip/WarmClips/WarmContainer` — front-load clip audio data ahead of first play (no extra package)
  - `IAudioClipSource` seam (`AudioClipSources.Active`, default `DirectClipSource`) — containers resolve clips through it; per-entry `address` on `WeightedAudioClip` / `SequenceEntry` / `RoutingEntry`
  - Optional **Addressables backend** (gated on `com.unity.addressables`): load/unload a region's clips by zone via `ZoneAudioBank` + `AddressableAudioRuntime`, voice-safe refcounted residency (banks + voices + pins), drop-on-cold, linger
  - **Addressable Audio Authoring** window (convert clips in one click) + **Loading Validator** window. *Voice-hold correctness verified; build-scale RAM profiling pending.*
- **Additive** — no v2.5.0 APIs changed. Both subsystems are inert until opted into (netcode: install a stack + add a transport; loading: use the warmer or install Addressables).

**v2.5.0** - May 2026
- **New subsystem: Occlusion Mixer Slot Pool** — per-bus pre-built mixer-slot pools replace per-source `AudioLowPassFilter`s. Eliminates the per-acquire biquad-reset click; cutoff modulation is a stable mixer-side write. See [Manual chapter 14](https://peppersfx.com/docs/manual/occlusion-mixer-slot-pool/).
  - `OcclusionLayout` + `OcclusionSlot` types
  - `AudioManager.AcquireOcclusionSlot` / `ReleaseOcclusionSlot` and slot-pool diagnostics
  - Multi-ray partial occlusion (`occlusionRayCount`, `occlusionRaySpreadMeters`) — N-level edge gradient instead of binary
  - Per-frame exponential smoothing via `occlusionGainSmoothingSeconds` / `occlusionCutoffSmoothingSeconds`
  - Occlusion Layout Builder window (`Window > Audio System > Occlusion Layout`)
- **New subsystem: Reverb Send Buses & Per-Zone Reverb** — source-side routing + listener-side bus-character driver. SFX voices contribute to the reverb of the room they're fired in; each bus's character is defined by its `ReverbSendBus` asset (the single source of truth, since the 2026-05-21 unification). See [Manual chapter 15](https://peppersfx.com/docs/manual/reverb-send-buses-per-zone-reverb/).
  - `ReverbSendBus` (one acoustic-space identity per asset) + `ReverbSendBusRegistry`
  - `AudioReverbProfile` (six SFX Reverb character params, authored on the bus SO)
  - `AudioZone.ReverbBus` (routing target; character lives on the `ReverbSendBus` SO, not the zone)
  - **Convolution reverb option (Phase 3.2, Windows x64, beta)** — `ReverbSendBus.UseConvolution` swaps the parametric SFX Reverb for a native impulse-response convolution plugin. See [Manual §15.14](https://peppersfx.com/docs/manual/reverb-send-buses-per-zone-reverb/#1514-convolution-reverb-windows-beta).
  - `AudioManager.WriteReverbSendsImmediate` — synchronous on-Play write so first audio frame carries correct routing
  - `AudioContainer` opt-in flags: `AllowReverbSend`, `ReverbSendLevelDb`, `StaticEmitter`, `ExplicitReverbBus`
  - Reverb Send Buses window (`Window > Audio System > Reverb Send Buses`) + per-asset Generate/Validate/Apply/Pull inspector
- **AudioContainer routing flags** — `UseOcclusion`, `UsePropagation`, `AllowReverbSend` opt SFX containers into the new slot pool. `UseOcclusion` enables raycast occlusion; `UsePropagation` composes propagation cutoff into the same voice via most-muffled-wins (min cutoff, multiplicative gain). The two routing/muffling subsystems now integrate cleanly with the propagation subsystem from v2.3.0.
- **Soft zone boundaries** — `AudioZone.entryFadeMeters` smooths reverb sends, listener-side reverb character, and `BaseVolumeDb` across the zone surface. 0 (default) preserves the v2.3.0 binary boundary.
- **Outside-the-graph behavior** — `PropagationManager.silenceOutsideGraph` toggle picks between whitelist mode (outside = audible, default) and complete-coverage mode (outside = silent + muffled).
- **Reachability-preserving culler** — `PropagationProximityCuller` now keeps zones reachable through near portals active even when individually out of activation-radius range. Two-zone-via-portal scenes no longer fall silent on tight radii.
- **Higher default solve rate** — `PropagationManager.solveRateHz` default 8 → 15 (≈ 67 ms cache step). Fast zone-trigger crossings and partially-closed-portal transitions no longer surface audible step changes.
- **Lower default open low-pass** — `AudioPortal.openLowPassHz` default 18000 → 12000. A portal without a door source is now audibly distinct from full transparency on typical speakers, surfacing authoring mistakes early.

**v2.3.0** - April 2026
- **New subsystem: `AudioSystem.Propagation`** — zone/portal graph-based routing for ambient beds
- `AudioZone` / `AudioPortal` MonoBehaviours (authoring)
- `AmbientSource` / `AmbientEmitter` (declaration + pooled persistent voice)
- `PropagationManager` singleton + `AudioListenerZoneTracker`
- `IPortalDoorSource` interface for portable door integration
- `PropagationProximityCuller` for large-level scale (per-node activation radius + global caps)
- Pure Dijkstra solver with reusable buffers (allocation-free hot path)
- Blend-region crossfading for pop-free doorway traversal
- Additive — does not modify any v2.2.0 APIs

**v2.2.0** - March 2026
- Runtime container override system (3D settings)
- Per-voice control on AudioMultiHandle
- RTPC transitions with `TransitionRTPC()`
- `StopAllSounds()`, `PauseAll()`, `UnpauseAll()`
- `MuteAll(bool)` replaces separate Mute/Unmute methods
- AudioStatistics replaces Statistics struct
- VoiceStealBehavior: added `Furthest`, removed `None`
- GainStack: added `DuckingGain`, `ApplyToSource()`, `Reset()`
- SequenceContainer: `AutoAdvance`, `PlayNext()`
- AudioBus: ducking system, effect sends
- AudioState: structured property classes
- Multi-position emitter components
- `IRTPCListener` interface
- `ListenerUtil` utility class
- `AudioVoiceDebugInfo` for runtime debugging

**v2.0.0** - January 2026
- AudioEventRegistry system
- Quick Sound Setup Wizard (5 modes), now Sound Builder (Simple)
- AudioEvent Inspector validation
- Batch import support

**v1.0** - Initial release
- Complete audio middleware system
- 5 container types
- Event system with multi-actions
- Hierarchical bus mixing
- State management
- Multi-position audio
- Voice virtualization & LOD
- Occlusion system

---

**End of API Reference**

---

*For tutorials, see [Cookbook](https://peppersfx.com/docs/cookbook/overview/) in the User Guide*
*For deep knowledge, see [Manual](https://peppersfx.com/docs/manual/overview/) in the User Guide*
*For quick start, see [Quick Start](https://peppersfx.com/docs/quick-start/) in the User Guide*

*Pepper.SFX v3.0.0 - Professional Audio Middleware for Unity*

## Known issues

Source: https://peppersfx.com/docs/known-issues/

This is a heads-up for beta testers: things that may not work as intended in this build yet, and places where the guides are out of date. If you hit one of these, it's already known. If you hit something that isn't listed, please report it.

Last updated: November 2026

---

### Where the guides are wrong

- **Free version.** The guides in the Documentation~ folder are an older copy.

### Things that might not work

- **Convolution reverb** ("Use Convolution" on a Reverb Send Bus) only works on 64-bit Windows, not Windows on ARM. On any other platform the bus stays silent, and you may get an error when the game starts. The normal reverb works everywhere except Web builds. See "Build Compatibility" in the User Guide.
- **Web builds** play sound, but occlusion doesn't muffle and there's no reverb, because Unity's Web audio has no mixer effects. See "Build Compatibility" in the User Guide.
- **Mac and Linux editor.** The console error about SFXConvolutionReverb.dll when the editor opens should be gone in this build. If you still see it, please report it.
- **Automatic mixer setup** in the Occlusion Layout and Reverb Send Buses windows has only been tested on Unity 6000.0.48f1 and may fail on newer versions. If it does, click "Diagnose Reflection" in the Occlusion Layout window and send us the console output.
- **Sound Builder (Simple)** (formerly the Quick Sound Setup Wizard) always warns that events must be in a Resources folder. You can ignore that if you use an Audio Event Registry. Its preview play button may do nothing.
- **Icons.** Custom icons on SFX assets and components may not show. This is cosmetic only.
- **Unity version.** You need Unity 6000.0.48f1 or newer. Package Manager will let you install on older 6000.0 versions, but those aren't supported. The package's automated tests pass on 6000.0.48f1 and 6000.3.19f1.
- **Unity 6.3: `AudioExtensions` in your own scripts.** Unity 6.3 added its own `UnityEngine.AudioExtensions`. A script with both `using UnityEngine;` and `using AudioSystem;` that calls `AudioExtensions.LinearToDb` (or `DbToLinear`, `CentsToPitch`) stops compiling with error CS0104. Write `AudioSystem.AudioExtensions.LinearToDb`, or add `using AudioExtensions = AudioSystem.AudioExtensions;` to that file.

### Known limitations

- **Stop actions.** A Stop action in an event only stops sounds that same event started. It can't stop another event's sound, such as music started elsewhere. To stop a sound, keep the handle you got from Post and call Stop on it. Its Scope (All or This Emitter) only narrows which of that event's sounds it reaches.
- **Removing many cars at once.** An Audio Emitter set to Stop keeps its persistent sounds' voices until their fade ends, so removing dozens of such objects in the same frame can fill the voice pool and skip a sound (with a warning). Shorten their Stop Fade Seconds if your game does that.
- **Sequence Containers.** Each Sequence Container asset keeps a single position, so two objects playing the same one share it. If you need two independent sequences, duplicate the asset.
- **Stopping a container.** Calling Stop on a container stops every sound playing from that container asset. To stop just one of them, stop its handle.
- **Multi-position emitter cones.** Use Directionality and Cone Angle on an Audio Multi-Position Emitter Child only draw a cone in the Scene view. They don't change the sound: every emitter is heard the same in every direction. Use Volume Multiplier to make one quieter.
- **Big bursts of sounds.** If a very large number of sounds start in the same frame, some are skipped (with a warning) when the voice pool can't free voices fast enough. Nothing is cut for a sound that is then skipped. Raise Steal Headroom on the Audio Manager if it happens often.
- **Decorrelated multi-position playback** may click on sharp sounds like gunshots.
- **Spatial Mode = Pepper** has no spatializer plugins (HRTF), doesn't read the project's Doppler Factor, and balances a stereo clip rather than placing it (give 3D sounds mono clips). Unity's own AudioSources (the ambient system's) are still heard from the AudioListener: keep it on the primary point with `DriveUnityListener`. Changing the mode affects sounds started after the change.

### Changes since 3.0.0

- **Volume on handles.** SetVolume and SetVoiceVolume still work but show "obsolete" warnings. Use SetVolumeScale (relative to the authored volume) or SetVolumeAbsolute. Per emitter, use SetVoiceVolumeScale.
- **Blend Containers.** Posting a Blend Container event again now plays a second copy alongside the first. If you want it to restart instead, set the event's Max Instances to 1.
- **Reverse sequences.** Sequence Containers in Reverse mode now start from the last clip.
- **Multi-position handles.** The per-emitter methods (SetVoiceVolumeScale, StopVoice and the others) now take the emitter number, not a voice number.
- **Multi-position posts with a source.** If you pass a source GameObject to PostMultiPosition, each 3D voice now plays at its own position, attached to the source so it moves with it. Before, every voice played from the source itself and the positions were ignored.
- **Equal Power crossfades.** The outgoing sound now fades out along a true equal-power curve, so loudness stays steady through the crossfade. It used to drop away early, so the old sound is now noticeably louder through the middle of the fade. Linear crossfades are unchanged.
- **CrossFade actions and buses.** A CrossFade action with a Target Bus now routes the incoming sound through that bus, so it follows the bus's volume slider, mute and ducking. Before, it ignored the bus. With no Target Bus nothing changes.
- **Fade Duration on Play actions.** Play actions never used it. Sound Builder (Simple) no longer shows it for Play.
- **Delayed actions.** An action with a Delay that isn't a Play (CrossFade, Stop, SetState, SetRTPC, SetSwitch, ducking, Pause, Resume) used to be skipped whenever nothing from that post was still playing when the delay ended. They now run. Only stopping the post's handle cancels them. If an event of yours has such an action that "never did anything", it will now.
- **CrossFade actions** place a 3D sound at the position or GameObject passed to Post, instead of the world origin. A crossfaded-in Sequence's later clips now get the Target Bus too. Crossfading back while a sound is still fading in no longer makes it jump up first.
- **Handle crossfade.** New `AudioManager.CrossFade(handle, event, duration)`: crossfades from a sound you hold the handle of, and also cancels what it was still going to start, such as the loop of an intro + loop event.
- **Sound Builder (Simple)** now asks for the Fade From Container when you make a Crossfade event. Without one, the crossfade did nothing.
- **LOD Distances** on the Audio Manager are hidden. They never did anything: voices are only virtualized once there are more than Max Real Voices.
- **Pitch on handles.** SetPitch and SetVoicePitch still work but show "obsolete" warnings. They replace the container's pitch randomization, as before; that is now called SetPitchAbsolute. The new SetPitchOffset (and SetVoicePitchOffset) shifts the pitch on top of the randomization instead. Containers also have a new **Pitch Limit**, off by default.
- **ConvolutionReverbDevTester** was removed. It was a temporary development harness for the convolution reverb. If you added it to a scene, that scene now shows a "missing script" on the object; remove the component.
- **Parameters per object and per sound.** New Parameter assets, the Audio Emitter component and per-handle values let two objects play the same Blend with different values (two cars, two RPMs). `SetRTPC` and the other string calls keep working: they set the global value, which every sound without its own value follows. See "Parameters & Scopes" (Manual §3.4).
- **Blend Containers follow their parameter once a frame.** A `SetRTPC` used to move the Blend's layers inside the call. They now move in Pepper's per-frame update, after every LateUpdate and before the frame's audio, so it is still the same frame. Code that reads a layer's gain straight after `SetRTPC` sees the old value until then. RTPC listeners are still told inside the call. `BlendContainer.UpdateBlend` is obsolete: it sets the parameter's global value.
- **Nested Blend Containers multiply.** A layer under two Blends now gets the product of both curves. Before, whichever parameter had changed last decided its level.
- **Later clips in a Blend or Switch.** A Sequence inside a Blend or Switch now plays its later clips at the Blend's curve and the Blend's and Switch's Volume, like its first clip. Before, they came in at full level, so such a sound may now be quieter after its first clip.
- **Curves, regions and pitch follow.** Containers can have Parameter Curves (volume, pitch, low- and high-pass), and Blends can use a Regions layout and Pitch Follow for engines. All of it is off until you add it, so existing sounds don't change.
- **Parent Settings.** Containers have two new options, Uses Parent Positioning and Uses Parent Output, for taking a Blend's or Switch's 3D settings or Mixer Group. They are off, so nothing changes unless you tick them.
- **TransitionRTPC replaces.** A second `TransitionRTPC` on the same name (two quick state changes, for example) now replaces the first, and a `SetRTPC` ends a running transition. Before, they ran together and fought.
- **Parameter smoothing.** Parameter assets can ease their values (Smoothing on the asset). It only applies to values set through the asset, so `SetRTPC` code sounds exactly as before.
- **Example 06 (vehicle engine)** now takes a Parameter asset and uses its Smoothing instead of its own "Rpm Transition Speed" field, which is gone. An Audio Emitter is added to the car with it. Without a Parameter asset it falls back to the old name, set globally and not smoothed.
- **Listening points.** You can now tell Pepper where you listen from: `AudioManager.Instance.AddListeningPoint(cameraTransform)`. If you don't, everything works as before, but a warning appears once per play session: "No listening point is registered". Code that calls `ListenerUtil.Set` counts as registering one.
- **`Post(null)`.** Calling `myEvent.Post(null)` with a bare `null` no longer compiles, because the new `Post(AudioEmitter)` matches it too. Write `myEvent.Post()`.
- **Virtual voices.** A sound that went virtual (more sounds than Max Real Voices) now comes back exactly where it would have been at any pitch. It used to come back off its place when pitched (randomization, pitch offsets, engine RPM). It also fades out over a few frames before going silent and fades back in, instead of cutting, so for those frames one more sound than Max Real Voices can be heard. A virtual one-shot at a raised pitch ends sooner than before, when its clip would have.
- **Stealing ends a whole sound.** When the voice pool is full, Pepper now ends whole sounds to make room (all of a Blend's layers, all of a Routing container's clips), never one layer of a sound while the rest plays on. A sound that can't get all its voices is skipped before anything is cut for it.
- **Starting while the real voices are full.** A new sound that matters less than everything already playing now starts virtual (silent, keeping its place) instead of pushing a more important sound out. Before, a new sound always started real. And an important virtual sound now comes back while the real voices are full, taking the place of one that clearly matters less.
- **Blend layers start on one exact time**, one audio buffer (a few milliseconds) later than a single sound starts, so they are sample-aligned.
- **Blend Loop Mode and Silent Layers.** The Blend's Loop checkbox, which was never read, is replaced by **Loop Mode** (From Layers, as before; Force Loop; Force One Shot). Sound Builder (Simple) sets Force Loop when its Loop is ticked. **Silent Layers = Virtualize** frees the real voices of layers that are near silence (engines); the default, Keep Playing, is as before.
- **Persistent events.** Tick Persistent on an event (an engine) so its sounds are never stolen. Off by default.
- **Unity's voice limits.** Pepper warns at startup if its Max Real Voices, or its total voices, are above Unity's own (Project Settings > Audio), and sets each voice's `AudioSource.priority` from its event.
- **MakeVirtual from your code.** `voice.MakeVirtual()` now keeps the voice virtual until you call `MakeReal()`; the voice budget no longer brings it back by itself.
- **Priority of reused voices.** A container played directly from code (not through an event) now always starts at High priority, as on a fresh voice, instead of whatever the reused voice's last sound had.
- **Posting with no Audio Manager** now logs a warning once per event and no longer uses up the event's cooldown.
- **Ambient system listener.** Zones, portals and ambient sources now listen from the listening point you registered with `AudioManager.AddListeningPoint`, not from the first AudioListener in the scene. If you register a point somewhere other than your AudioListener, the ambience follows the point. Its Listener Override field still wins.
- **Leaving out multiplayer.** New define `SFXSYSTEM_DISABLE_NETCODE` (Project Settings > Player > Scripting Define Symbols) leaves the multiplayer code out of your project. Nothing changes unless you set it.
- **Named points on an Audio Emitter.** An Audio Emitter can list named points (a car's Exhaust, Intake, axles): `car.Post(exhaustEvent, "Exhaust")` plays the sound attached at that spot. Drag the points in the Scene view. An Audio Emitter without points works as before. See "Named points" (Manual §3.4).
- **Switches per car, and while playing.** A switch (a surface) can now be set on an Audio Emitter or a handle, not only globally, and a Switch Container can follow a change while it plays: **When Switch Changes** = Crossfade or Restart. The default, Next Play Only, is how Switches always worked. New **Switch Group** assets list a group's values; `SetSwitch("Surface", ...)` keeps working and is the same switch. A group can also be driven by a parameter. See "When Switch Changes" and "Switch Group assets" (Manual §4.5).
- **`SwitchContainer.SetSwitch`** used to do nothing until that container had played once. It now works straight away.
- **A Sequence in a far-away sound.** When a sound has gone virtual (silent because it's far away or less important), its Sequence's next clip now starts virtual too. Before, it started audible and could push a more important sound out for half a second.
- **Distance assets and Distance/Approach Speed/Angle.** New **Attenuation** assets describe how 3D sounds fade, dull, thin and narrow with distance, shared between containers; a sound past its Max Distance goes silent (virtual) until it comes back in range. Parameter assets can take their value from Distance, Approach Speed or Angle. Containers without an Attenuation asset work as before. See "Attenuation assets" (Manual §4.1) and "Built-in values" (§3.4).
- **Audition.** New Window > Audio System > Audition plays a container while you edit it, with sliders for its parameters, a sweep and a live layer table, outside Play mode. Please report anything it leaves behind or any sound that differs from Play mode beyond the known limits (heard 2D; Sequences play their first clip). See Manual §10.5.
- **Audio's random numbers are its own.** Which variation plays, and volume and pitch randomization, no longer use Unity's random generator: each Audio Emitter has its own sequence (with an optional Random Seed), other sounds share one. Your gameplay's random sequence is no longer changed by sounds playing. If you relied on `Random.InitState` to get the same audio picks, set the Audio Emitter's Random Seed instead, or set the Audio Manager's Random Numbers to Unity. Multiplayer posts work as before.
- **No-repeat per car.** A Random container's Avoid Repeat Last now applies per Audio Emitter: each car avoids its own recent clips.
- **Per-car limits and values at post.** Events have Max Instances Per Emitter and Cooldown Per Emitter (off by default), and a post can carry values for its sound (`PostValues`). See "Per Audio Emitter" (Manual §5.3) and "Values at post" (§3.4).
- **Bus curves.** A bus can now follow a parameter: its volume, and a low- or high-pass on its Mixer Group (the bus inspector adds the filter for you). Buses without curves are unchanged. See "Parameter Curves on a Bus" (Manual §6.6).
- **`container.MaxDistance = x`** in code now changes only the running game. Before, in the editor it changed the asset itself and stayed after Play.
- **`SetSwitch(null, ...)`** with a bare `null` group no longer compiles, because the new asset overload matches it too. Pass a group name or asset.
- **Doppler Level** on containers (3D Settings), default 1 as before. Set it to 0 on engine layers so they stay in step when they go virtual and come back. Sound Builder (Simple)'s Doppler Level slider now sets it; before, it did nothing.
- **Switching the Audio Manager off.** The pooled voices now live under "AudioVoices", a root object of Pepper's own, which also runs Pepper's background work. Switching the Audio Manager's GameObject off no longer stops anything; before, it stopped Pepper for good. Use `PauseAll`, a bus `Pause` or `StopAllSounds` to silence the game.
- **Persist Across Scenes** on the Audio Manager (on by default, as before). Turn it off to keep the manager under another object; a second manager then removes only its own component instead of its whole GameObject. See "Memory & Lifecycle" (Manual §2.4).
- **Dedicated servers.** `AudioManager.Inert = true`, set at boot, makes every post silent and free, with or without an Audio Manager. See Manual §17.11.
- **Cars that come and go.** An Audio Emitter's **On Disable** (Keep, the default and as before; Stop; Pause) decides what its sounds do when the object is switched off or destroyed: fade out where they are, or pause and come back in phase. See "Switched off or destroyed" (Manual §3.4).
- **Stop, Pause and Resume actions** have a **Scope**: All (the default, as before) or This Emitter, so one car's post doesn't reach every car's sounds.
- **Pausing a bus.** `bus.Pause()` / `Resume()` hold a bus's sounds (and its child buses'), faded, without a real voice, while other buses (a pause menu) play on. See "Pausing a Bus" (Manual §6.7).
- **Time on events, Ducking Time on buses.** Scaled by default, as before; Unscaled lets a UI sound's cooldown, a delay, a Sequence gap, a crossfade or a duck run while the time scale is 0.
- **The "was skipped" warning** shows at most every 5 s, with a count.
- **Finished handles** ignore new `OnStarted`, `OnStopping` and `OnLoop` subscriptions; they could never fire.
- **Tools for authoring engines and mixes.** The Audition plays events too, runs several sweeps at once, and replays a drive recorded in the new **Live View** (Play mode: every Audio Emitter's values and sounds, and why a voice is virtual). New **Loop Analysis** (a loop's RPM, seam and loudness) and **Engine Builder** (an engine's whole tree from its loops). See Manual §10.5–§10.9. Please report anything they get wrong.
- **Container Validator** checks events too, and Blends' regions, pitch and Doppler. It no longer reports "No mixer group" on every container: a Play action with neither a Target Bus nor a Mixer Group is what it warns about now.
- **Events outside the registry.** The event Inspector no longer says an event "will NOT load at runtime", and no warning is logged on import: an event held in a field plays wherever it is. Only posting by name or id needs the registry.
- **Import settings.** The package no longer ships an Audio Import Settings asset (it couldn't be saved once installed). Make one in your project (Create > Audio System > Import Settings) to change the presets; without one the defaults apply, the same values the shipped asset had. New **Folder Rules** apply settings to clips first imported into a folder.
- **Bus faders, mute and solo** in the Mixer and Audio Profiler windows can be undone, and are saved with the project, also when moved in Play mode.
- **Audio Profiler and Voice Pool Debug.** Voice Usage is now real voices against Max Real Voices (it read 50% at the cap); the pool window compares its objects with the pool's whole size.
- **Handle volume and pitch reach later voices.** `SetVolumeScale` and `SetPitchOffset` on a handle now also reach the voices the sound starts later: a Switch's new choice, a Sequence's next clip, a Play action with a Delay. Before, those started at the authored level and pitch. `SetVolumeAbsolute` and `SetPitchAbsolute` still reach only the voices playing now. New: `SetVolumeOffset` (dB), and both offsets can be given at the post (`PostValues.WithVolumeOffset`, `WithPitchOffset`).
- **Overlapping ducks: the deepest wins.** Each trigger is now a duck of its own and the bus follows the deepest, so a short or shallow duck no longer cuts a long or deep one short (a UI blip during a dialogue duck used to bring the music back up under the dialogue). Re-triggering the same duck sounds as it did.
- **`SetBusVolume` with a name no bus has** now changes nothing and warns once. Before, it set the master bus. `GetBus` with such a name still returns the master bus, now with a warning.
- **Level and pitch per Audio Emitter.** New **Volume Offset** (dB) and **Pitch Offset** (cents) on an Audio Emitter reach every sound on it. 0 by default, so nothing changes.
- **Posting anywhere on an Audio Emitter, and moving a sound.** `car.Post(impactEvent, localOffset, values)` plays at that spot with the car's values and limits; `handle.SetLocalOffset` / `SetWorldPosition` move a playing sound. See "Posting at an offset" (Manual §3.4).
- **Timed posts and lengths.** `Post(emitter, startDsp, startOffsetSeconds, values)` makes a moment of the sound land on a DSP time (a pass-by's peak on the pass); `EstimateDuration` tells how long an event will play. See Manual §5.1.
- **Pepper's Doppler.** A container's new **Doppler** setting can be Pepper (exaggeration, maximum shift) instead of Unity's (the default, as before). With it, sounds that go virtual come back in step. `AudioEmitter.Teleport()` and `AudioListeningPoint.ClearVelocity()` keep a reset or a camera cut from reading as speed. See "Doppler" (Manual §4.1).
- **Offset states and the player's volume.** A state's **Bus Volume Mode** can be Offset: its buses move by that much and go back when the state ends (`ClearState` leaves a group). Set Level, the default, works as before. A bus's **Player Volume** (`PlayerVolumeDb`) is a Settings page's volume, never saved and never undone by a state. Also `MasterVolumeDb`, `IsAllMuted` and `AudioBus.IsMuted`. See Manual §6.8 and §7.2. Example 08 now sets player volumes.
- **Low priority counts.** A Low sound weighs 1/8 in how important it is (Medium 1/4, High 1/2, Critical 1, as before). It used to weigh 0, so a Low sound right beside you went virtual, or was stolen, before a Medium one you could hardly hear. See Manual §3.2.
- **Steals fade.** A sound stolen to make room, a play an event's Max Instances ends, and a Switch set to Restart's old choice now fade out over the Audio Manager's new **Steal Fade Seconds** (0.025 s, at least three frames) instead of cutting, which could click. A stolen sound keeps its voice a few frames longer while it fades; if bursts of sounds start getting skipped, raise Steal Headroom. Steal Fade Seconds 0 brings back the cut. A sound stolen before it has started now frees its voice at once.
- **A listening point whose camera is destroyed is removed,** with a warning once per session, instead of staying where the camera was. Remove your points when their camera goes. See "Listening Points" (Manual §9.3).
- **Split screen.** The Audio Manager's new **Spatial Mode** can be Pepper: Pepper then pans and attenuates 3D sounds itself, from every listening point by its Weight and Pan Width, and sounds exactly as Unity's 3D at one point. Unity, the default, works as before. You can pick the primary listening point (`SetPrimaryListeningPoint`), and a camera change no longer reads as speed. See "Listening Points" (Manual §9.3).
- **A bus can cap its real voices** (**Max Real Voices**, 0 = none by default), so a group of sounds can't crowd out the rest. See Manual §6.9.
- **Voice filters.** Every pooled voice now carries its low- and high-pass from the start, switched off (a switched-off filter isn't heard), instead of adding them mid-game the first time a filter curve needed them.
- **A parameter value that isn't a number** (NaN, or an infinity, say from a division by zero in game code) is now refused with a warning once per parameter, and sounds keep the last value. Before, it stayed until the value was snapped, and a Blend played every band at once. If you see the warning, fix the code that computes the value.
- **Engine Builder.** Clips it folds to mono keep their level: it turns Unity's Normalize off on them, which used to level every loop. The engine event it makes is Priority High. Trees built before keep their settings.
- **Engine loops and Cylinders.** The Engine Builder makes its loop containers with Avoid Repeat Last 0, and a one-clip Random container no longer warns about Avoid Repeat Last (it never stopped a clip playing). Cylinders is a scale, not always the engine's count: when most loops read 2 semitones or more from the RPMs in their names (set it per library), Loop Analysis, the Engine Builder and Detect Root Values name the count that fits, and flag a single loop that reads an octave off. See Manual §10.7 and §10.8.
- **Sounds on a bus with no slots.** The Occlusion Layout window now makes slots for every bus whose sounds use Use Occlusion, Allow Reverb Send or Use Propagation (it used to count Use Occlusion only, so the other two could play with no reverb send and no low-pass). Click its Scan, Auto-Create, Refresh again to add them. When an Occlusion Layout is assigned and a sound still plays through a bus it has no slots for, the console warns once per bus.

### Full version only

- **Upgrade From Free** may not work in this beta. Don't convert a real project yet, and back up first if you try it.
- **Multiplayer** is tested with FishNet v4. Netcode for GameObjects 2.x has had only light testing so far, so expect rough edges. NGO 1.x and FishNet v3 cause compile errors.
- **Addressables: one group for every zone saves no memory.** Unity can only unload a bundle as a whole, so with every zone's clips in one Pack Together group (like the Default Group), leaving a zone frees nothing. The Addressable Audio Authoring window and Sound Builder now put each bank's clips in its own group by default. If you converted zones into the Default Group with an earlier build, the window's Groups tab flags it and can switch it to one bundle per clip. See "Authoring window" in the User Guide.
- **Phase-locked loops (Loop Sync Tier 2)** are experimental. A player who joins late may hear the loop out of sync for one or two cycles before it locks in.
- **Proximity culling** can use the wrong range for events that play a Switch or Blend container, so a nearby player might not get the sound.
- **Sound Builder (Advanced)** is brand new, so expect rough edges. The free version has Sound Builder (Simple).
- **Engine Builder** is in the full version only. The free version keeps Loop Analysis and the Blend inspector's Detect Root Values, so you can still build an engine's tree by hand (User Guide §10.8).
- **Generated engines** (Granular and Additive Engines, Manual §4.7, and the Engine Grains window) are in the full version only, and need Unity 6000.3 or later. They haven't been measured on a Steam Deck yet (about 0.4% of a core each on a desktop PC). Their grains are resampled with the simplest interpolation, which may dull very high harmonics. Grain tables cut by Engine Grains in 3.1.0-dev.10 or earlier from a sweep that rises or falls evenly in pitch (most synthesisers) were cut along a straight line, so their grains aren't whole engine cycles: analyse them again with **Curve: Even Pitch** (Manual §10.10). In 3.1.0-dev.11 and earlier a held RPM warbled once an engine cycle, worst at low RPM, and a rev climbed in uneven steps: both fixed after dev.11, with no need to cut the tables again. Since then a generated engine moves to each frame's RPM over the time that frame took, so it hears the RPM about a frame and two audio buffers late (25–75 ms).
- **Audio Profiler.** "Est. CPU" is worked out from the voice count, not measured, and "Managed heap" is all of your game's managed memory, not just audio. Use Unity's Profiler for real audio figures.
- **Example scripts** work with either input setting (old Input Manager, new Input System, or Both). The audio settings UI example (Example 08) needs the Unity UI package; without it, that one example is left out.
- **Import Manager settings** live in an Audio Import Settings asset in your project, so an update keeps them. Without one, the code defaults apply.
- **Mixer window.** It creates Assets/Settings/Audio/MixerLayout.asset by itself to save its layout.

---

### Reporting a problem

Please include:

- your Unity version
- your platform (Windows, Mac or Linux)
- whether you're on the free or full version
- the steps to reproduce the problem
- any console errors

## Migration

Source: https://peppersfx.com/docs/migration/

### Why Migrate?

#### Current Pain Points (Resources-based)
❌ Events MUST be in `Assets/Audio/Resources/Audio/Events/` (confusing, easy to mess up)
❌ States MUST be in `Assets/Audio/Resources/Audio/States/`
❌ Resources folder increases build size
❌ No validation when placed incorrectly (silent failures)
❌ Tedious folder management

#### Benefits After Migration (Registry-based)
✅ Place Events/States ANYWHERE in your project
✅ Better organization
✅ Smaller build size
✅ Clear validation and errors
✅ Version control friendly
✅ Backwards compatible (no breaking changes)

---

### Migration Process (5-10 minutes)

#### Step 1: Create AudioEventRegistry

1. Right-click in Project → `Create > Audio System > Audio Event Registry`
2. Name it exactly: **"AudioEventRegistry"**
3. Place in: `Assets/Audio/Resources/AudioEventRegistry.asset`

**Important:** The registry itself should be in a Resources folder so AudioManager can auto-find it at runtime.

#### Step 2: Populate Registry from Existing Assets

1. Select the `AudioEventRegistry` asset
2. In Inspector, click **"Populate from Resources Folders"**
3. Verify: Registry should now show all your existing Events and States

Console output:
```
✓ Registry populated: 45 events, 12 states
```

#### Step 3: Test That Everything Still Works

1. Enter Play Mode
2. Check Console for:
   ```
   Loading audio assets from AudioEventRegistry
   ✓ Loaded from Registry: 45 events, 12 states
   ```
3. Test your sounds - they should work exactly as before

**No code changes needed!** AudioManager automatically detects the registry.

#### Step 4: Move Events/States Out of Resources (Optional)

**This step is optional but recommended for organization:**

1. Create new folders outside Resources:
   ```
   Assets/Audio/
   ├── Events/          ← Move Events here (outside Resources)
   ├── States/          ← Move States here (outside Resources)
   ├── Containers/      ← (unchanged)
   └── Buses/           ← (unchanged)
   ```

2. Drag Events from `Assets/Audio/Resources/Audio/Events/` → `Assets/Audio/Events/`
3. Drag States from `Assets/Audio/Resources/Audio/States/` → `Assets/Audio/States/`

4. Update Registry:
   - Select `AudioEventRegistry`
   - Click **"Populate from Entire Project"**
   - Verify all Events/States are still registered

5. Delete empty Resources folders (if desired)

#### Step 5: Validate Registry

1. Select `AudioEventRegistry`
2. Click **"Validate Registry (Remove Nulls)"**
3. Check Console:
   ```
   ✓ Registry validated: No issues found
   ```

---

### Migration Checklist

- [ ] AudioEventRegistry created
- [ ] Registry placed in Resources folder
- [ ] Registry populated from Resources
- [ ] Tested in Play Mode (sounds work)
- [ ] (Optional) Moved Events/States out of Resources
- [ ] (Optional) Updated registry from entire project
- [ ] Registry validated

---

### Backwards Compatibility

**The system is fully backwards compatible:**

| Scenario | What Happens |
|----------|--------------|
| Registry exists | AudioManager uses registry (new way) |
| No registry found | AudioManager uses Resources.LoadAll (old way) |
| Both registry and Resources | Registry takes priority |

**This means:**
- Old projects without registry continue working
- New projects can use registry from day 1
- Gradual migration is safe

---

### Adding New Sounds After Migration

#### Option 1: Quick Wizard (Recommended)
1. `Window > Audio System > Sound Builder (Simple)`
2. Create sound assets
3. Open `AudioEventRegistry`
4. Click **"Populate from Entire Project"**

#### Option 2: Manual
1. Create AudioEvent anywhere in project
2. Open `AudioEventRegistry`
3. Drag new Event into "Registered Events" array
4. OR click **"Populate from Entire Project"**

**Tip:** Set up a post-processing script to auto-update registry when Events are created.

---

### Common Migration Issues

#### Issue: "No AudioEvents found in Resources/Audio/Events"
**Cause:** Registry not found, falling back to Resources.LoadAll
**Fix:** Ensure registry is named "AudioEventRegistry" and placed in `Assets/Audio/Resources/AudioEventRegistry.asset`

#### Issue: "Loaded 0 events" after migration
**Cause:** Registry is empty
**Fix:** Select registry → Click "Populate from Entire Project"

#### Issue: Some sounds don't play after migration
**Cause:** Events not registered
**Fix:** Open registry → Click "Validate Registry" → Re-populate

#### Issue: Registry has null references
**Cause:** Events were deleted but registry not updated
**Fix:** Click "Validate Registry (Remove Nulls)"

---

### Performance Comparison

#### Before (Resources-based)
- `Resources.LoadAll<AudioEvent>("Audio/Events")` at startup
- All Resources assets included in build
- Load time: ~50-200ms (project dependent)

#### After (Registry-based)
- Direct reference lookup (no scanning)
- Only registered assets in build
- Load time: ~5-20ms (instant)

**Result:** Faster startup, smaller builds

---

### Team Workflow

#### Before Migration
❌ "Where do Events go again? Assets/Audio/Resources/Audio/Events?"
❌ "Why isn't my sound playing?" (placed in wrong folder)
❌ "Do I need Resources nested inside Audio folder?"

#### After Migration
✅ "Events can go anywhere, just update the registry"
✅ Inspector shows clear warnings if Event not registered
✅ Single registry asset, auto-detected

---

### Advanced: Custom Registry Locations

If you don't want registry in Resources, you can manually assign it:

```csharp
// In your bootstrap script
void Awake()
{
    var customRegistry = Resources.Load<AudioEventRegistry>("MyCustomPath/AudioEventRegistry");
    // AudioManager will find it via Resources.Load
}
```

OR create a custom singleton accessor:
```csharp
public class MyAudioConfig : MonoBehaviour
{
    [SerializeField] private AudioEventRegistry registry;

    void Awake()
    {
        // Inject registry into AudioManager
        // (requires minor AudioManager modification)
    }
}
```

---

### Rollback Plan

If migration causes issues, you can instantly rollback:

1. Delete or move `AudioEventRegistry` out of Resources
2. AudioManager will fallback to old `Resources.LoadAll` method
3. Everything works as before

**No code changes needed for rollback!**

---

### Summary

#### What Changes:
- AudioEvents/States can live anywhere (not just Resources)
- AudioEventRegistry tracks all assets
- AudioManager auto-detects registry

#### What Stays the Same:
- All existing code works unchanged
- AudioEvent.Post() API identical
- Container/Bus workflow unchanged
- Old Resources-based projects still work

#### Time Investment:
- Initial migration: **5-10 minutes**
- Per new sound after: **+10 seconds** (update registry)

#### ROI:
- Eliminates #1 confusion point for new users
- Better project organization
- Faster builds and startup

---

### Next Steps

After migration:
1. ✅ Update team documentation
2. ✅ Use Sound Builder (Simple) for new sounds
3. ✅ Consider removing Resources folders entirely
4. ✅ Update registry when adding/removing Events