Skip to main content

Audio

PlayCanvas plays audio through the browser's Web Audio API. An entity with a sound component is a sound source: it holds the sounds the entity can make, and plays them from where the entity is. An entity with an audio listener component is the ears of the scene, usually the camera.

Positional Sound

Load the example above, then click inside it: browsers keep audio off until you interact with a page. The robot's footsteps come from the robot, so they move from one ear to the other and fade as it walks around the camera. On Each Surface compares how each surface sets up the same thing.

How Audio Works​

  • Audio assets hold the sounds. An audio file is decoded in full when it loads, so it plays the instant you ask for it.
  • The sound component makes an entity a sound source. Its volume and pitch apply to everything the entity plays.
  • Sound slots are the named sounds of a sound component. Each slot plays one audio asset, or part of one, with a volume and pitch of its own, and can loop or play automatically.
  • Sound instances are sounds that are playing. Each time a slot plays, it creates an instance that you can pause, seek, fade and listen to for events.
  • Positional audio pans a sound between the speakers and fades it with distance, by where its entity is relative to the audio listener.
  • Master volume scales every sound in the application, and effects such as filters and reverb come from Web Audio nodes that you add to a slot's output.

One rule shapes every audio feature on the web: a page cannot make a sound until the user has interacted with it. PlayCanvas starts its audio on the first click or tap. Autoplay and User Gestures explains what that means for music and for sounds that play on load.

On Each Surface​

The sound component is the same everywhere, but the surfaces expose different amounts of it. Anything a surface has no markup or UI for, you can reach through the engine component from code.

EngineEditorReactWeb Components
Load a soundAn audio assetUpload an audio fileAn audio asset, from code<pc-asset>
Make an entity a sound sourceentity.addComponent('sound')A Sound componentThe engine API<pc-sound>
Give it a soundentity.sound.addSlot()A slot in the Sound componentThe engine API<pc-sound-slot>
Play, pause and stopentity.sound.play()From a scriptThe engine APIThe engine API
Place the listenerentity.addComponent('audiolistener')An Audio Listener componentThe engine API<pc-audio-listener>
Master volume and effectsapp.systems.soundFrom a scriptThe engine APIThe engine API
note

PlayCanvas React has no sound components of its own yet. Its <Application> includes the engine's sound systems, so you add the sound component to an entity from a small component of your own. Each page in this section shows how.

In This Section​

  • Getting Started - Loading a sound, adding a sound component and playing your first sound.
  • Audio Assets - Formats, how much memory a sound uses, loops, long music and audio sprites.
  • Playing Sounds - Slots, looping, overlapping one-shots, playing part of a file, and volume and pitch.
  • Controlling Playback - Sound instances, pausing, seeking, events, fades and crossfades.
  • Positional Audio - The audio listener, distance models and panning.
  • Volume and Mixing - Master volume, muting, mixing music against effects, and ducking.
  • Effects and Analysis - Filters, echo and reverb with Web Audio nodes, and reading the sound for visualizers.
  • Autoplay and User Gestures - Why audio waits for a click, and how to design around it.
  • Troubleshooting - What to check when you hear nothing, or something unexpected.

See Also​