Troubleshooting
Each section below starts from what you hear, lists the usual causes, most likely first, and links to the page that explains each one.
No Sound
Nothing Plays at All
- Audio is locked. Browsers keep audio off until the user clicks or taps the page. Sounds played before then start at the first click, and a key press does not count. See Autoplay and User Gestures.
- The application has no sound system. An Engine app built from
AppBaseneeds aSoundManager,SoundComponentSystemandAudioHandler. Without the system,addComponent('sound')returnsnullandentity.soundis undefined. Without the handler, the asset fails withNo resource handler for asset type: 'audio'. Without the sound manager, it fails withAudio manager has no audio context. See Setting Up the Application. - The volume is 0. Check the master volume, and the volume of the component and of the slot. A saved mute setting is easy to forget.
- The phone is set to silent. On an iPhone, Web Audio is silent while the ring/silent switch is set to silent. See Phones and Tablets.
One Sound Doesn't Play
- The slot name is wrong.
play()returnsnullfor a name the component does not have. Names are case sensitive. - The component or its entity is disabled.
play()does nothing and returnsnull. See Enabling and Disabling. - The slot has no asset, or its asset failed to load. Listen for the asset's
errorevent. A file that the browser cannot decode fails withUnable to decode audio data. - The browser cannot decode the format. A sound that plays in one browser and not in another is usually in a format that the second one does not support. See Supported Formats.
- The asset type was not recognized. In Web Components,
<pc-asset>only recognizes.mp3files as audio by their extension. Give other formatstype="audio". - It is too far away. A positional sound beyond its
maxDistanceis silent with the linear distance model. See the next section.
Positional Sounds
A Sound Is Silent or Too Quiet
- The sound is positional, and should not be. Sound components are positional by default. Music or an interface sound on a positional component fades as the camera moves away from its entity. Turn Positional off. See Positional and Non-Positional Sounds.
- The listener is not where you think. With no audio listener, sounds are heard from the world origin, not from the camera. With several, only the one enabled most recently is used. A disabled listener goes on being heard from where it last was. See The Audio Listener.
- The source is beyond
maxDistance. With the linear model, a sound is silent frommaxDistanceoutwards.
A Sound Doesn't Fade with Distance
The default maxDistance is 10,000, which fades a sound so gradually that it seems not to fade at all. Set maxDistance to the distance at which the sound should be silent, or use the inverse distance model. See Distance.
A Sound Doesn't Move Between the Speakers
- The component is not positional. Only positional sounds are panned.
- The listener is on the sound's own entity, or on one that moves with it. A sound at the listener's position is always in the middle.
- The sound is in front or behind. Sounds are panned left and right only, so a sound that crosses from front to back does not change. See Panning.
Playback
Sounds Cut Each Other Off
A slot plays one sound at a time, so playing it again restarts it. Turn Overlap on for sounds that should pile up, such as gunshots and footsteps. See Overlapping Sounds.
A Sound Goes On After Its Entity Is Destroyed
Sounds on an overlapping slot play to their end, even when the entity is destroyed or disabled. Stop the slot before you destroy the entity, or turn Overlap off.
Changing Volume or Pitch Does Nothing
On an overlapping slot, changes to volume, pitch, startTime and duration apply to the next play, not to sounds that are already playing. The same is true of the volume and pitch of the sound component. To change a sound that is playing, set the property on its sound instance.
A Burst of Sound at the First Click
One-shot sounds that were played while audio was locked all start together when it unlocks. Skip them while the audio context is not running. See Sounds Played While Locked.
A Sound Is Late the First Time
The asset had not loaded. A slot that is played before its asset is ready plays once the file has downloaded and decoded. Preload the asset, or load it before it is needed. See When Audio Loads.
A Loop Has a Gap or a Click
The engine loops without a gap, so the gap is in the file: silence at its ends, or a loop that is not cut on a musical boundary. See Seamless Loops.
The end Event Never Fires
- The sound loops. A looping sound never reaches its end.
- The sound was stopped. A sound that is stopped fires
stop, notend. Listen forstopto act either way. - You listened on an old instance. Each play creates a new sound instance. Listen on the slot or the component instead, which fire for every play.
Effects
An Error When Clearing Effects
clearExternalNodes() throws an InvalidAccessError when the slot shares its nodes with a slot that has already been cleared. Do not clear slots that share nodes. See Sharing Effects.
An Effect Does Nothing
- The nodes are not connected to each other. With two nodes passed to
setExternalNodes(), the engine connects the sound to the first and the last to the speakers. The connections between them are yours to make. - The nodes came from another audio context. Create them from
app.systems.sound.context. - The slot overlaps. Nodes set on an overlapping slot apply to the next play.
Memory
Audio Uses a Lot of Memory
Every loaded sound is held in memory decoded, at about 11 MB for each minute of mono audio, however small its file is. Use mono for sound effects, loop short sections of music rather than loading long tracks, and unload assets you have finished with. See Memory.
See Also
- Autoplay and User Gestures - Why audio waits for a click
- Audio Assets - Formats, loading and memory
- Positional Audio - The listener and distance models