Pepper.SFX
All Guidance pages

Guidance / Manual

Troubleshooting

12.1 Sound Not Playing

Symptoms: Event.Post() called, no sound.

Checklist:

  1. AudioManager exists?
// Check console for "AudioManager not found" error
// Add AudioManager to scene if missing
  1. Event in Resources folder?
Events MUST be in: Assets/Audio/Resources/Audio/Events/
Check exact path, case-sensitive
  1. Container has clips?
Open container asset
Check AudioClips list is not empty
Verify clips are assigned (not "None")
  1. Bus volume not -80 dB?
Check bus hierarchy
Each bus in chain should be > -80 dB
  1. Max instances reached?
Check event.MaxInstances
Check VoiceStealBehavior
Increase maxInstances or add stealing
  1. Cooldown active?
Check event.Cooldown value
Wait cooldown duration between calls
  1. 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
  1. Multiple clips assigned?
Need 4+ clips for good variation
Check container's AudioClips list
  1. avoidRepeatLast set?
Set to 2-3 for best results
Prevents recent clips from repeating
  1. 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
  1. 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.

  1. Spatial Blend = 1?
AudioManager sets this automatically
But check if overridden somehow
  1. 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
  1. 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).
// 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).

  1. Switch value matches entry?
Case-sensitive matching
"Metal" != "metal"
Check spelling exactly
  1. Switch group correct?
Verify switchGroupName matches
"Surface_Type" must match exactly
  1. Default container assigned?
Assign default as fallback
Helps debug which code path is taken
  1. Debug log switch value:
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
  1. 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.
  1. 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
  1. AudioListener exists?
Occlusion raycasts from listener position
Check listener component active
  1. Update interval too slow?
Default 0.2s is fine
If too slow (>0.5s), noticeable lag
Check AudioManager.occlusionUpdateInterval
  1. 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?
// 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.

  1. Volume curves configured?
Check BlendEntry.volumeCurve
Must not be flat line
Create varied curves in editor
  1. All layers have containers?
Null containers don't play
Verify all entries assigned
  1. Loop enabled for music?
Music should loop
Check container Loop = true
  1. Parameter name matches?
blendParameterName (or the asset's Parameter Name) must match the name you set exactly
Case-sensitive: "CombatIntensity" != "combatintensity"
  1. 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.
  1. 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.
  1. Using PostMultiPosition()?
// CORRECT
event.PostMultiPosition(emitterParent);

// WRONG
event.Post();  // Normal mode, no sync
  1. All emitters active?
Check emitterChild.IsActive
Verify parent.ActiveEmitterCount > 0
  1. DSP buffering adequate?
Default 0.1s latency usually fine
If still issues, increase buffer

From the Pepper.SFX 3.1 guides (USER_GUIDE.md). Something wrong or unclear? Tell me.