Skip to main content

createSoundGroup

Create a named sound group. A group can cap how many of its sounds play at once and give its members shared play options, such as a lower volume for all effects.

createSoundGroup(groupName: string, options?: { maxInstances?: number; playOptions?: PlayOptions }): void;

Parameters​

ParameterTypeDefaultDescription
groupNamestringrequiredName of the group. Used by every other group method.
options{ maxInstances?: number; playOptions?: PlayOptions }{}Settings for the group, see below.

Options​

PropertyTypeDefaultDescription
maxInstancesnumberno limitThe most sounds the group holds at once. When a new one joins a full group, the oldest is stopped and leaves.
playOptionsPlayOptionsnoneOptions merged into every sound that joins. They win over the sound's own options. Options passed to play() win over them for a plain sound, but not for an overlapping instance, which joins the group after its options are set.

Returns​

Nothing.

Example​

import { SoundHub } from 'soundhub';

const soundHub = new SoundHub();
await soundHub.loadSound('laser', '/audio/laser.mp3');

// At most 3 lasers at once, all at half volume
soundHub.createSoundGroup('effects', {
  maxInstances: 3,
  playOptions: { volume: 0.5 },
});

// Play straight into the group with the groupId play option
soundHub.play('laser', { overlap: true, groupId: 'effects' });
soundHub.play('laser', { overlap: true, groupId: 'effects' });
soundHub.play('laser', { overlap: true, groupId: 'effects' });
soundHub.play('laser', { overlap: true, groupId: 'effects' }); // stops the first one

Good to know​

  • A name that is already taken is ignored with a debug log. The existing group keeps its settings.
  • There are two ways in: addToSoundGroup, or the groupId play option. With overlap, each new instance ('laser:1', 'laser:2') joins the group, which is what makes maxInstances a voice limit.
  • Playing with a groupId that does not exist does not play the sound at all. Only a debug log says why.
  • No event is dispatched.

See also​