SoundGroup

A sound group is a named set of sounds. It can do two things for its members: cap how many of them play at once, and give them shared play options. Removing the group stops all of them in one call.

The interface

This is what getGroup returns:

export interface SoundGroup {
    id: string; // internal usage (groupName)
    sounds: Set<string>; // Stores sound IDs belonging to this group
    maxInstances?: number; // Maximum number of concurrent instances allowed in the group
    playOptions?: PlayOptions; // Add playOptions to the group
  }

Property	Type	Description
`id`	`string`	The group name you passed to `createSoundGroup`.
`sounds`	`Set<string>`	IDs of the members, overlapping instances such as `'laser:2'` included.
`maxInstances`	`number` (optional)	When a new member joins a full group, the oldest member is stopped and leaves.
`playOptions`	`PlayOptions` (optional)	Merged into every sound that joins, over the sound's own options.

How sounds join

addToSoundGroup(groupName, soundId) adds a loaded sound by hand.
The groupId play option on play adds the sound when it starts. With overlap: true, every new instance joins by itself, which turns maxInstances into a voice limit for rapid effects.

The group methods

Method	What it does
`createSoundGroup(groupName, options?)`	Makes a group with an optional `maxInstances` and `playOptions`.
`addToSoundGroup(groupName, soundId)`	Adds a sound and merges the group options into it.
`removeFromSoundGroup(groupName, soundId)`	Takes a sound off the member list without stopping it.
`getGroup(groupName)`	Returns the group, or `undefined`.
`removeSoundGroup(groupName)`	Stops every member, removes overlapping instances and deletes the group. Loaded sounds stay in the hub.

Example

import { SoundHub } from 'soundhub';

const soundHub = new SoundHub();
await soundHub.loadSounds([
  { id: 'tokyo-train', url: '/audio/tokyo-train-melody.mp3' },
  { id: 'bells-melody', url: '/audio/bells-melody.mp3' },
  { id: 'techno-tune', url: '/audio/techno-tune.mp3' },
]);

soundHub.createSoundGroup('ambient-group', { playOptions: { loop: true, volume: 0.5 } });

soundHub.addToSoundGroup('ambient-group', 'tokyo-train');
soundHub.addToSoundGroup('ambient-group', 'bells-melody');
soundHub.addToSoundGroup('ambient-group', 'techno-tune');

// Each one loops at 0.5, from the group options
soundHub.play('tokyo-train');
soundHub.play('bells-melody');
soundHub.play('techno-tune');

// Stop all three and delete the group
soundHub.removeSoundGroup('ambient-group');

Try it

A group with room for two

Idle

No group yet

tokyo-trainstopped
bells-melodystopped
techno-tunestopped
helicopternot in the group

Add all three: the third one stops the oldest member to stay within two. Then start the helicopter and remove the group. Only the members stop.

Code

Your clicks show up here as soundhub calls

Good to know

A group has no volume or mute of its own. Its playOptions are copied into each member when it joins, so changing them afterwards does nothing for sounds already in the group.
maxInstances counts members, not only sounds that are playing. A loaded sound added with addToSoundGroup takes a slot until it leaves.
Group options win over a sound's own options. Options passed to play() win over the group for a plain sound, but not for an overlapping instance.
A sound remembers its group, so removeFromSoundGroup is undone by the next play() of that sound. removeSoundGroup does clear the link.
Playing with a groupId that does not exist does not play the sound. None of the group methods dispatch an event.

The interface​

How sounds join​

The group methods​

Example​

Try it​

Good to know​

See also​