# Audio objects

Audio objects are instances you create from code to play the sounds or music you previously registered in **Audio Creator**.\
Each class encapsulates specific rules and behaviours and offers a fluent, **method-chaining** API.

<table><thead><tr><th width="133">Object</th><th width="373">What it represents</th><th>Typical use</th></tr></thead><tbody><tr><td><strong><code>Sound</code></strong></td><td>A single <strong>SFX</strong> (footstep, shot, UI click…) that might play many times.</td><td>Any kind of sound effect.</td></tr><tr><td><strong><code>Music</code></strong></td><td>One <strong>music</strong> track (ambient, boss theme…) that can loop.</td><td>Constant background music.</td></tr><tr><td><strong><code>Playlist</code></strong></td><td>A <strong>sequential queue</strong> of tracks; plays in order, supports shuffle, fade-in/out and per-track callbacks.</td><td>Background music made of several tracks in succession.</td></tr><tr><td><strong><code>DynamicMusic</code></strong></td><td>Several tracks playing <strong>in parallel</strong>, letting you add/remove layers (drums, strings, SFX) according to gameplay.</td><td>Reactive dynamic music.</td></tr></tbody></table>

### 🧰 Key concepts

* **Fluent API** – Every setter returns the same instance, so you can chain configuration and the final `Play()` in one sentence.
* **Automatic Object Pooling** – Internally, each object requests a `SoundsGoodAudioSource` from the pool, avoiding runtime instantiation.
* **Callbacks** (`OnPlay`, `OnComplete`, etc.) – Hook gameplay logic (screen shake, particles, achievements) without coroutines or `Invoke`.
* **Volume persistence** – If you assign an `Output`, its level is saved to `PlayerPrefs`; **Output Manager** restores it on start-up.

### 🔄 Recommended lifecycle

1. **Create**

   ```csharp
   var coinSound = new Sound(SFX.Coin).SetVolume(0.7f);
   ```
2. **Play / control**

   ```csharp
   coinSound.Play();
   coinSound.Pause();
   coinSound.Resume(0.5f); // 0.5-second fade-in
   coinSound.Stop(0.2f);   // 0.2-second fade-out
   ```
3. **Finish**
   * When it ends (`OnComplete`), the object returns its `AudioSource` to the pool.
   * The class instance stays alive; you can reconfigure it and call `Play()` again.

> 📝 **Tip:** Don’t instantiate an audio object every frame; keep references if you’ll reuse the same SFX (footsteps, rapid fire, etc.).

### 🚀 Next step

Dive into each audio object to master every feature:

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Sound</strong></td><td><a href="audio-objects/sound">sound</a></td></tr><tr><td><strong>Music</strong></td><td><a href="audio-objects/music">music</a></td></tr><tr><td><strong>Playlist</strong></td><td><a href="audio-objects/playlist">playlist</a></td></tr><tr><td><strong>DynamicMusic</strong></td><td><a href="audio-objects/dynamicmusic">dynamicmusic</a></td></tr></tbody></table>
