Skip to main content

Getting Started

Playing a sound takes three things: an audio asset that holds the sound, a sound component that makes an entity a sound source, and a slot on that component that names the sound and plays the asset. This page sets up all three and plays a bell.

Setting Up the Application​

In the Editor, React and Web Components, sound is ready to use. An Engine app that you build from AppBase only includes the features you register, so give it a sound manager, the sound component system and the handler that loads audio files:

const options = new AppOptions();
options.soundManager = new SoundManager();
options.componentSystems = [SoundComponentSystem, AudioListenerComponentSystem];
options.resourceHandlers = [AudioHandler];

AudioListenerComponentSystem is only needed for positional audio. See Bundle Size and Tree Shaking for the full list of systems and handlers.

Playing a Sound​

Load the file as an audio asset, add a sound component to an entity, add a slot that plays the asset, and play the slot by name:

// load the audio file
const asset = new Asset('bell', 'audio', {
url: 'https://developer.playcanvas.com/assets/bell.mp3'
});
app.assets.add(asset);
app.assets.load(asset);

// make an entity a sound source, with a slot that plays the asset
const bell = new Entity('bell');
bell.addComponent('sound', { positional: false });
bell.sound.addSlot('ring', { asset: asset.id });
app.root.addChild(bell);

// play the slot
bell.sound.play('ring');

You do not have to wait for the asset. A slot that is played before its asset has loaded starts as soon as the asset arrives.

A sound component is positional by default: it plays its sounds from where its entity is, and fades them with distance from the audio listener. The examples on this page turn that off, which is what you want for music, interface sounds and anything else that should sound the same wherever the camera is.

The First Click​

Browsers do not let a page make a sound until the user has interacted with it. Until then, the audio system is locked, and anything you play is held back. PlayCanvas unlocks audio on the first click, tap or mouse press anywhere in the page.

A sound that you play in response to a click is not affected, because the click itself unlocks the audio. A sound that plays on load, such as background music, starts at the first click instead. Autoplay and User Gestures covers this in detail.

Example​

This Engine app loads a bell sound, gives a sphere a sound component with one slot, and rings the bell each time you click the canvas.

Live Example
import {
AppBase,
AppOptions,
Asset,
AudioHandler,
CameraComponentSystem,
Color,
createGraphicsDevice,
DEVICETYPE_WEBGPU,
Entity,
FILLMODE_FILL_WINDOW,
LightComponentSystem,
RenderComponentSystem,
RESOLUTION_AUTO,
SoundComponentSystem,
SoundManager,
StandardMaterial
} from 'playcanvas';

// create the application with the component systems and resource handlers it uses
const canvas = document.getElementById('application');
const device = await createGraphicsDevice(canvas, {
deviceTypes: [DEVICETYPE_WEBGPU]
});
device.maxPixelRatio = Math.min(window.devicePixelRatio, 2);

const options = new AppOptions();
options.graphicsDevice = device;
options.soundManager = new SoundManager();
options.componentSystems = [
RenderComponentSystem,
CameraComponentSystem,
LightComponentSystem,
SoundComponentSystem
];
options.resourceHandlers = [AudioHandler];

const app = new AppBase(canvas);
app.init(options);
app.setCanvasFillMode(FILLMODE_FILL_WINDOW);
app.setCanvasResolution(RESOLUTION_AUTO);
window.addEventListener('resize', () => app.resizeCanvas());
app.start();

app.scene.ambientLight = new Color(0.35, 0.35, 0.4);

// load the bell, an audio asset
const asset = new Asset('bell', 'audio', {
url: 'https://developer.playcanvas.com/assets/bell.mp3'
});
await new Promise((resolve) => {
asset.ready(resolve);
app.assets.add(asset);
app.assets.load(asset);
});

const camera = new Entity('camera');
camera.addComponent('camera', {
clearColor: new Color(0.11, 0.12, 0.17)
});
camera.setPosition(0, 0, 4);
app.root.addChild(camera);

const light = new Entity('light');
light.addComponent('light');
light.setEulerAngles(48, 38, 0);
app.root.addChild(light);

// the bell is a sphere with a sound component, and one slot that plays the asset
const material = new StandardMaterial();
material.diffuse = new Color(0.95, 0.7, 0.2);
material.update();

const bell = new Entity('bell');
bell.addComponent('render', { type: 'sphere', material });
bell.addComponent('sound', { positional: false });
bell.sound.addSlot('ring', { asset: asset.id });
app.root.addChild(bell);

// click to ring the bell, and swell the sphere to show the ring
let swell = 0;
canvas.addEventListener('click', () => {
bell.sound.play('ring');
swell = 1;
});
app.on('update', (dt) => {
swell = Math.max(0, swell - dt * 3);
bell.setLocalScale(1 + swell * 0.3, 1 + swell * 0.3, 1 + swell * 0.3);
});

const label = document.createElement('div');
label.style.cssText = 'position: absolute; left: 12px; bottom: 10px; color: #ccc; font: 14px sans-serif; pointer-events: none;';
label.textContent = 'Click to ring the bell.';
document.body.appendChild(label);

Some things to try:

  • Add pitch: 0.5 to the slot's options to ring a bell an octave lower.
  • Click quickly. Each click cuts the last ring short, because a slot plays one sound at a time unless it is set to overlap. Add overlap: true to the slot's options to let the rings pile up. See Playing Sounds.
  • Remove positional: false. Nothing changes yet: an application without an audio listener hears from the world origin, and that is where the bell is. Then move the bell with bell.setPosition(3, 0, 0) to hear it from the right.

See Also​