getGroup

Get a sound group by its name. Use it to see which sounds are in a group right now, or to check that a group exists.

getGroup(groupName: string): SoundGroup | undefined;

Parameters

Parameter	Type	Default	Description
groupName	string	required	Name of the group.

Returns

SoundGroup | undefined: the group, or undefined when no group has that name. A SoundGroup has these fields:

Property	Type	Description
id	string	The group name.
sounds	Set<string>	IDs of the current members, overlapping instances such as 'laser:2' included.
maxInstances	number (optional)	The limit given to createSoundGroup.
playOptions	PlayOptions (optional)	The options merged into every member.

Example

import { SoundHub } from 'soundhub';

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

soundHub.createSoundGroup('effects', { maxInstances: 3 });
soundHub.play('laser', { overlap: true, groupId: 'effects' });
soundHub.play('laser', { overlap: true, groupId: 'effects' });

const group = soundHub.getGroup('effects');
if (group) {
  console.log(group.sounds.size);  // 2
  console.log([...group.sounds]);  // ['laser:1', 'laser:2']
}

Good to know

• You get the live object the hub uses, not a copy. Read from it, but change groups through the group methods: editing sounds or maxInstances directly skips the work those methods do.
• Instances that finished playing are cleared from sounds the next time a new instance of that sound starts, so the set can briefly list sounds that are no longer audible.

See also

• createSoundGroup: make a group.
• addToSoundGroup: add a member.
• soundGroup: overview of sound groups.