Skip to main content

addToSoundGroup

Add a sound to a group. The sound takes on the group's play options and counts toward the group's maxInstances.

addToSoundGroup(groupName: string, soundId: string): void;

Parameters​

ParameterTypeDefaultDescription
groupNamestringrequiredName of a group made with createSoundGroup.
soundIdstringrequiredID of the sound to add.

Returns​

Nothing.

Example​

import { SoundHub } from 'soundhub';

const soundHub = new SoundHub();
await soundHub.loadSounds([
  { id: 'rain', url: '/audio/rain.mp3' },
  { id: 'wind', url: '/audio/wind.mp3' },
]);

soundHub.createSoundGroup('ambience', { playOptions: { volume: 0.4, loop: true } });

soundHub.addToSoundGroup('ambience', 'rain');
soundHub.addToSoundGroup('ambience', 'wind');

// Both play looped at 0.4, from the group options
soundHub.play('rain');
soundHub.play('wind');

// Options passed to play() still win
soundHub.play('rain', { volume: 0.8 });

Good to know​

  • The group's playOptions are merged into the sound's own play options and stay there. Taking the sound out of the group later does not undo that.
  • If the group is already at maxInstances, the oldest member is stopped and leaves to make room. Loaded sounds count, not only playing ones.
  • An unknown group name does nothing apart from a debug log. An unknown sound id is still recorded in the group, it just has no options to merge.
  • You rarely need this for overlapping instances. Pass the groupId play option to play and each instance joins by itself.
  • No event is dispatched.

See also​