Guidance

Search the docs

Start here

What Pepper.SFX is, your first sound, and which platforms it builds for.

• Introduction

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

• Quick Start

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

• 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…

Cookbook

Recipes for one outcome each, from the asset to the code: UI sounds, footsteps, weapons, music, occlusion, reverb.

• Cookbook: overview

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

• Setup & Organization

  What: Complete setup from scratch to playing first sound

• UI Sounds

  What: Button with click sound and subtle variations

• Footsteps & Movement

  Result: Natural-sounding footsteps synced to animation!

• Weapons & Combat

  What: Weapon shot with variations and instance limiting

• Music Systems

  What: Music with intro that transitions to seamless loop

• Rhythmic SFX

  Use BeatScheduler (AudioSystem.BeatScheduler, MonoBehaviour in RunTime/Utilities/) for any SFX whose rate must vary at runtime without changing pitch…

• 3D Spatial Audio

  3D Spatial Audio: Pepper.SFX documentation. Pepper.SFX is audio middleware for Unity.

• States & RTPCs

  Result: Smooth transition to muffled underwater audio!

• Multi-Position Audio

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

• Performance & Debugging

  Result: Development HUD showing audio system stats!

• 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…

• 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…

• 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…

• Appendix: Quick Reference

  Appendix: Quick Reference: Pepper.SFX documentation. Pepper.SFX is audio middleware for Unity.

Manual

How each part works and why: architecture, containers, events, buses, states, performance, propagation, loading, multiplayer.

• Manual: overview

  The Manual is the system's deep reference — architecture, design rationale, and chapter-by-chapter coverage of every subsystem. Read it once…

• Introduction

  Introduction in the Pepper.SFX manual: What This Manual Covers, Prerequisites, How to Use This Manual, Companion Documents.

• System Architecture

  System Architecture in the Pepper.SFX manual: Design Philosophy, The Audio Pipeline, Component Hierarchy, Memory & Lifecycle.

• Core Components

  Core Components in the Pepper.SFX manual: AudioManager, AudioVoice & AudioVoiceEnhanced, AudioHandle & AudioMultiHandle, Parameters & Scopes.

• Audio Containers

  Containers define how audio clips are organized and played. All containers inherit from AudioContainer base class.

• Events System

  Events System in the Pepper.SFX manual: AudioEvent Overview, Event Actions, Instance Limiting, Cooldown System, Multi-Position Mode.

• Bus & Mixing

  Bus & Mixing in the Pepper.SFX manual: Bus Architecture, Decibel System, Hierarchical Volume, Ducking System, Unity AudioMixer Integration, Parameter…

• State System

  State System in the Pepper.SFX manual: AudioState Overview, State Groups, State Properties, State Transitions, Common State Patterns.

• Multi-Position Audio

  Multi-Position Audio in the Pepper.SFX manual: Concept, Architecture, DSP Synchronization, Setup Tutorial, Per-Emitter Control, Use Cases, Performance…

• Performance & Optimization

  Performance & Optimization in the Pepper.SFX manual: Voice Management, Memory Optimization, CPU Optimization, Mobile Optimization, Profiling.

• Advanced Features

  Advanced Features in the Pepper.SFX manual: Occlusion System, Ducking, Crossfading, Beat-Scheduled SFX (BeatScheduler), Audition (outside Play mode)…

• Best Practices

  Best Practices in the Pepper.SFX manual: Project Organization, Naming Conventions, Bus Hierarchy Design, Container Design, Event Design, State Design…

• Troubleshooting

  Troubleshooting in the Pepper.SFX manual: Sound Not Playing, No Variations, 3D Sound Not Spatial, Switch Container Not Switching, Occlusion Not Working…

• 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…

• 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…

• 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…

• 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…

• 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…

• Appendix A: Glossary

  Appendix A: Glossary: Pepper.SFX documentation. Pepper.SFX is audio middleware for Unity.

• Appendix B: Quick Reference

  Appendix B: Quick Reference in the Pepper.SFX manual: Common Code Patterns.

API reference

Every public class, method and property, with examples.

• AudioManager

  AudioManager API in Pepper.SFX: Inspector Configuration, Properties, Event Methods, Posting by Reference, Random Numbers, Parameter Methods, Listening…

• AudioEvent

  AudioEvent API in Pepper.SFX: Properties, Methods, AudioDuration, PostValues, EventAction (Nested Class), CrossfadeType (Nested Enum).

• AudioHandle & AudioMultiHandle

  AudioHandle & AudioMultiHandle API in Pepper.SFX: AudioHandle, AudioMultiHandle.

• 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…

• AudioContainer (Base)

  AudioContainer (Base) API in Pepper.SFX: Properties, Methods, ContainerOverrides (Nested Struct).

• Container Types

  Container Types API in Pepper.SFX: RoutingContainer, RandomContainer, SequenceContainer, SwitchContainer, BlendContainer, GeneratorContainer (Unity…

• AudioBus

  AudioBus API in Pepper.SFX: Properties, Methods, EffectSend (Nested Class), DuckingTarget (Nested Class).

• AudioState

  AudioState API in Pepper.SFX: Properties, Methods, Nested Property Classes.

• AudioVoice & AudioVoiceEnhanced

  AudioVoice & AudioVoiceEnhanced API in Pepper.SFX: AudioVoice (Base), AudioVoiceEnhanced, GainStack (Nested Class), PitchStack (Nested Class), DopplerMath.

• AudioExtensions & Utilities

  AudioExtensions & Utilities API in Pepper.SFX: AudioExtensions, ListenerUtil, AudioListeningPoint, BeatScheduler, IRTPCListener (Interface).

• AudioEventRegistry

  AudioEventRegistry API in Pepper.SFX: Description, Properties, Methods, Setup Example.

• Multi-Position Emitters

  Multi-Position Emitters API in Pepper.SFX: AudioMultiPositionEmitterParent, AudioMultiPositionEmitterChild.

• Editor Tools

  Editor Tools API in Pepper.SFX: AudioAuditionWindow and AudioAudition, AudioLiveViewWindow, AudioEmitterRecorder and AudioParameterRecording…

• Propagation

  Zone/portal graph-based routing for long-running ambient beds. Additive — does not modify the SFX event pipeline. See Manual Chapter 13 for architecture…

• 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…

• 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…

• Enums & Data Structures

  Enums & Data Structures API in Pepper.SFX: VoicePriority, AudioSpatialMode, VoiceStealBehavior, MultiPositionType, WeightedAudioClip, SequenceEntry…

• Loading

  The clip-loading layer: import policy, warming, and the optional Addressables backend. See the User Guide → Audio Loading & Memory for the concepts and…

• Netcode (Multiplayer)

  Backend-agnostic networked audio. See the User Guide → Multiplayer (Netcode) for concepts, setup, and the mental model. No audio crosses the wire — only…

• Quick Reference

  Quick Reference API in Pepper.SFX: Common Patterns.

• Version History

  For quick start, see Quick Start in the User Guide

More

Known issues in this release and moving older projects across.

• 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…

• Migration

  Events MUST be in Assets/Audio/Resources/Audio/Events/ (confusing, easy to mess up)