Skip to main content

Volume and Mixing

How loud a sound is depends on three volumes, multiplied together: the slot's, the sound component's, and the application's master volume. This page covers the master volume and how to build the controls that players expect on top of the three: a mute button, separate levels for music and effects, and music that dips under speech.

The Volume Chain​

VolumeSet withApplies to
Slotslot.volumeOne sound of an entity
Componententity.sound.volumeEvery sound of an entity
Masterapp.systems.sound.volumeEvery sound in the application

Each is a value from 0 to 1, and the volume you hear is the three multiplied together. A slot at 0.5, on a component at 0.5, with the master volume at 0.5, plays at 0.125. For a positional sound, the fade for distance is applied on top.

Setting the volume of one sound instance replaces the slot and component part of the chain for that sound. The master volume still applies.

Master Volume​

The master volume belongs to the sound system, which every surface reaches through the application. It takes effect at once, on sounds that are already playing as well as new ones.

app.systems.sound.volume = 0.5;

Muting​

To mute, set the master volume to 0, and set it back to unmute. Sounds keep playing while they are muted, so music is where it should be when the sound comes back. Players expect a mute setting to be remembered, so save it:

let muted = localStorage.getItem('muted') === 'true';

function applyMute() {
app.systems.sound.volume = muted ? 0 : 1;
}

function toggleMute() {
muted = !muted;
localStorage.setItem('muted', muted);
applyMute();
}

applyMute();

Mixing Groups​

Players usually want to set music and sound effects apart. PlayCanvas has no mixer of its own, but two simple patterns give you groups of sounds with a volume each.

Use the component's volume. When each kind of sound has its own entity, each component's volume is the level of a group. This suits non-positional sound: one entity for music, one for interface sounds, one for speech.

music.sound.volume = 0.6;
interfaceSounds.sound.volume = 0.9;

A component's volume changes the sounds that are already playing, with one exception: sounds on an overlapping slot keep the volume they started with, and the new volume applies from the next play. For overlapping sounds that must follow a volume control at once, use a gain node.

Route slots through a shared gain node. Sound effects are often spread over many entities, each with a sound component of its own. To give them one volume, create a Web Audio GainNode and make it the output of every slot in the group:

const effectsGroup = app.systems.sound.context.createGain();

// for each slot in the group
slot.setExternalNodes(effectsGroup);

// then one value sets the level of them all
effectsGroup.gain.value = 0.5;

The node stays in place for every sound the slots play from then on. Do not call clearExternalNodes() on a slot that shares a node with others. See Sharing Effects for why.

Ducking​

Ducking turns one group down while something more important plays: the music dips under a line of speech, then comes back. The events of the sound component tell you when to dip and when to recover, and moving the volume over a few frames avoids a sudden jump:

let target = 1;
voice.sound.on('play', () => {
target = 0.25;
});
voice.sound.on('stop', () => {
target = 1;
});

app.on('update', (dt) => {
// move the music a little of the way to its target each frame
const volume = music.sound.volume;
music.sound.volume = volume + (target - volume) * Math.min(dt * 6, 1);
});

stop fires however the sound finishes, so the music recovers whether the speech ends or is cut off.

Pausing All Audio​

When the browser tab is hidden, PlayCanvas suspends audio and pauses every sound. When the tab is shown again, they carry on from where they were. You do not need to do anything.

To pause the sounds of your own accord, for a pause menu, pause the sound components. pause() and resume() with no slot name act on every slot of a component:

const sources = app.root.findComponents('sound');

for (const source of sources) {
source.pause();
}

// later
for (const source of sources) {
source.resume();
}

Setting app.timeScale to 0 freezes the simulation but not the audio, so pause the sounds as well.

Example​

This Engine app plays music, a stream of sound effects and a bell, each from its own sound component. The three bars show the volume of each group once the master volume is applied: green for the music, red for the effects and yellow for the bell. Ring the bell to hear the music duck under it.

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);

const load = (name) => {
const asset = new Asset(name, 'audio', {
url: `https://developer.playcanvas.com/assets/${name}.mp3`
});
return new Promise((resolve) => {
asset.ready(() => resolve(asset));
app.assets.add(asset);
app.assets.load(asset);
});
};
const [musicAsset, sfxAsset, bellAsset] = await Promise.all([load('music'), load('sfx'), load('bell')]);

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

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

// a group is an entity with a sound component, and a bar that shows its volume
const createGroup = (name, x, color) => {
const material = new StandardMaterial();
material.diffuse = color;
material.update();

const group = new Entity(name);
group.addComponent('sound', { positional: false });
app.root.addChild(group);

const bar = new Entity(`${name}-bar`);
bar.addComponent('render', { type: 'box', material });
bar.setPosition(x, 0, 0);
app.root.addChild(bar);

return { group, bar };
};
const music = createGroup('music', -2, new Color(0.3, 0.75, 0.45));
const effects = createGroup('effects', 0, new Color(0.9, 0.3, 0.35));
const voice = createGroup('voice', 2, new Color(0.95, 0.75, 0.2));

music.group.sound.addSlot('loop', { asset: musicAsset.id, loop: true });
voice.group.sound.addSlot('bell', { asset: bellAsset.id });

// the effects are an audio sprite: four sounds in one file
const sprites = [[0, 0.7], [1, 0.8], [2, 0.7], [3, 1.3]];
sprites.forEach(([startTime, duration], i) => {
effects.group.sound.addSlot(`effect${i}`, { asset: sfxAsset.id, startTime, duration });
});

// the mix: a level for each group, and the master volume
const mix = { master: 1, music: 0.8, effects: 0.8, voice: 1, muted: false };

// duck the music while the bell rings
let duck = 1;
let duckTarget = 1;
voice.group.sound.on('play', () => {
duckTarget = 0.25;
});
voice.group.sound.on('stop', () => {
duckTarget = 1;
});

// controls
const panel = document.createElement('div');
panel.style.cssText = 'position: absolute; left: 12px; top: 12px; right: 12px; display: flex; flex-wrap: wrap; gap: 8px 14px; align-items: center; color: #ccc; font: 14px sans-serif;';
document.body.appendChild(panel);

let running = false;
const startButton = document.createElement('button');
startButton.textContent = 'Start';
startButton.onclick = () => {
running = !running;
startButton.textContent = running ? 'Stop' : 'Start';
if (running) {
music.group.sound.play('loop');
} else {
music.group.sound.stop();
}
};
panel.appendChild(startButton);

const addSlider = (text, key) => {
const label = document.createElement('label');
const input = document.createElement('input');
Object.assign(input, { type: 'range', min: 0, max: 1, step: 0.01, value: mix[key] });
input.style.width = '80px';
input.oninput = () => {
mix[key] = Number(input.value);
};
label.append(`${text} `, input);
panel.appendChild(label);
};
addSlider('Master', 'master');
addSlider('Music', 'music');
addSlider('Effects', 'effects');

const muteLabel = document.createElement('label');
const muteInput = document.createElement('input');
muteInput.type = 'checkbox';
muteInput.onchange = () => {
mix.muted = muteInput.checked;
};
muteLabel.append(muteInput, ' Mute');
panel.appendChild(muteLabel);

const bellButton = document.createElement('button');
bellButton.textContent = 'Ring bell';
bellButton.onclick = () => voice.group.sound.play('bell');
panel.appendChild(bellButton);

let timer = 0;
let next = 0;
app.on('update', (dt) => {
// play the next effect every 1.2 seconds
timer += dt;
if (running && timer > 1.2) {
timer = 0;
effects.group.sound.play(`effect${next++ % sprites.length}`);
}

// apply the mix: the master volume, then a volume for each group
duck += (duckTarget - duck) * Math.min(dt * 6, 1);
app.systems.sound.volume = mix.muted ? 0 : mix.master;
music.group.sound.volume = mix.music * duck;
effects.group.sound.volume = mix.effects;
voice.group.sound.volume = mix.voice;

// each bar shows what its group plays at: the master volume × the group's volume
for (const { group, bar } of [music, effects, voice]) {
const height = Math.max(app.systems.sound.volume * group.sound.volume * 3, 0.02);
bar.setLocalScale(1, height, 1);
bar.setPosition(bar.getPosition().x, height / 2 - 1, 0);
}
});

Some things to try:

  • Click Start, then drag Master down. Every bar falls together. Drag Music and Effects to change the balance between them.
  • Click Ring bell. The music bar dips while the bell rings and recovers when it stops. Change 0.25 to 0 to cut the music out altogether.
  • Tick Mute, wait a few seconds, and untick it. The music has moved on: muted sounds keep playing.

See Also​