11. Core API Reference | SoundGroup

An interface that manages Sound Groups

Group Functions:

• SoundGroup::setMaxAudible Sets the maximum number of playbacks to be audible at once in a sound group.
• SoundGroup::getMaxAudible Retrieves the maximum number of playbacks to be audible at once in a sound group.
• SoundGroup::setMaxAudibleBehavior This function changes the way the sound playback behaves when too many sounds are playing in a soundgroup.
• SoundGroup::getMaxAudibleBehavior Retrieves the current max audible behavior.
• SoundGroup::setMuteFadeSpeed Sets a mute fade time.
• SoundGroup::getMuteFadeSpeed Retrieves the current mute fade time.
• SoundGroup::setVolume Sets the volume of the sound group.
• SoundGroup::getVolume Retrieves the volume of the sound group.

• FMOD_SOUNDGROUP_BEHAVIOR Values specifying behavior when a sound group's max audible value is exceeded.

Sound Functions:

• SoundGroup::setMaxAudible Sets the maximum number of playbacks to be audible at once in a sound group.
• SoundGroup::getMaxAudible Retrieves the maximum number of playbacks to be audible at once in a sound group.
• SoundGroup::getNumSounds Retrieves the current number of sounds in this sound group.
• SoundGroup::getSound Retrieves a sound.
• SoundGroup::getNumPlaying Retrieves the number of currently playing Channels for the SoundGroup.
• SoundGroup::stop Stops all sounds within this soundgroup.

General:

• SoundGroup::getName Retrieves the name of the sound group.
• SoundGroup::release Releases a soundgroup object and returns all sounds back to the master sound group.
• SoundGroup::setUserData Sets a user value associated with this object.
• SoundGroup::getUserData Retrieves a user value associated with this object.
• SoundGroup::getSystemObject Retrieves the parent System object.

FMOD_SOUNDGROUP_BEHAVIOR

Values specifying behavior when a sound group's max audible value is exceeded.

typedef enum FMOD_SOUNDGROUP_BEHAVIOR {
  FMOD_SOUNDGROUP_BEHAVIOR_FAIL,
  FMOD_SOUNDGROUP_BEHAVIOR_MUTE,
  FMOD_SOUNDGROUP_BEHAVIOR_STEALLOWEST,
  FMOD_SOUNDGROUP_BEHAVIOR_MAX
} FMOD_SOUNDGROUP_BEHAVIOR;

enum SOUNDGROUP_BEHAVIOR
{
    BEHAVIOR_FAIL,
    BEHAVIOR_MUTE,
    BEHAVIOR_STEALLOWEST,
    MAX,
}

FMOD.SOUNDGROUP_BEHAVIOR_FAIL
FMOD.SOUNDGROUP_BEHAVIOR_MUTE
FMOD.SOUNDGROUP_BEHAVIOR_STEALLOWEST
FMOD.SOUNDGROUP_BEHAVIOR_MAX

FMOD_SOUNDGROUP_BEHAVIOR_FAIL

Excess sounds will fail when calling System::playSound.

FMOD_SOUNDGROUP_BEHAVIOR_MUTE

Excess sounds will begin mute and will become audible when sufficient sounds are stopped.

FMOD_SOUNDGROUP_BEHAVIOR_STEALLOWEST

Excess sounds will steal from the quietest Sound playing in the group.

FMOD_SOUNDGROUP_BEHAVIOR_MAX

Maximum number of SoundGroup behaviors.

When using FMOD_SOUNDGROUP_BEHAVIOR_MUTE, SoundGroup::setMuteFadeSpeed can be used to stop a sudden transition.
Instead, the time specified will be used to cross fade between the sounds that go silent and the ones that become audible.

See Also: SoundGroup::setMaxAudibleBehavior, SoundGroup::getMaxAudibleBehavior, SoundGroup::setMaxAudible, SoundGroup::getMaxAudible, SoundGroup::setMuteFadeSpeed, SoundGroup::getMuteFadeSpeed

SoundGroup::getMaxAudible

Retrieves the maximum number of playbacks to be audible at once in a sound group.

FMOD_RESULT SoundGroup::getMaxAudible(
  int *maxaudible
);

FMOD_RESULT FMOD_SoundGroup_GetMaxAudible(
  FMOD_SOUNDGROUP *soundgroup,
  int *maxaudible
);

RESULT SoundGroup.getMaxAudible(
  out int maxaudible
);

SoundGroup.getMaxAudible(
  maxaudible
);

maxaudible Out

Maximum number of playbacks to be audible at once.

• Range: [-1, inf)
• Default: -1

See Also: SoundGroup::setMaxAudible

SoundGroup::getMaxAudibleBehavior

Retrieves the current max audible behavior.

FMOD_RESULT SoundGroup::getMaxAudibleBehavior(
  FMOD_SOUNDGROUP_BEHAVIOR *behavior
);

FMOD_RESULT FMOD_SoundGroup_GetMaxAudibleBehavior(
  FMOD_SOUNDGROUP *soundgroup,
  FMOD_SOUNDGROUP_BEHAVIOR *behavior
);

RESULT SoundGroup.getMaxAudibleBehavior(
  out SOUNDGROUP_BEHAVIOR behavior
);

SoundGroup.getMaxAudibleBehavior(
  behavior
);

behavior Out

SoundGroup max playbacks behavior. (FMOD_SOUNDGROUP_BEHAVIOR)

• Default: FMOD_SOUNDGROUP_BEHAVIOR_FAIL

See Also: SoundGroup::setMaxAudibleBehavior

SoundGroup::getMuteFadeSpeed

Retrieves the current mute fade time.

FMOD_RESULT SoundGroup::getMuteFadeSpeed(
  float *speed
);

FMOD_RESULT FMOD_SoundGroup_GetMuteFadeSpeed(
  FMOD_SOUNDGROUP *soundgroup,
  float *speed
);

RESULT SoundGroup.getMuteFadeSpeed(
  out float speed
);

SoundGroup.getMuteFadeSpeed(
  speed
);

speed Out

Fade time. 0 = no fading.

• Units: Seconds
• Range: [0, inf)
• Default: 0

See Also: SoundGroup::setMuteFadeSpeed

SoundGroup::getName

Retrieves the name of the sound group.

FMOD_RESULT SoundGroup::getName(
  char *name,
  int namelen
);

FMOD_RESULT FMOD_SoundGroup_GetName(
  FMOD_SOUNDGROUP *soundgroup,
  char *name,
  int namelen
);

RESULT SoundGroup.getName(
  out string name,
  int namelen
);

SoundGroup.getName(
  name
);

name Out

Name of the SoundGroup. (UTF-8 string)

namelen

Length of name.

• Units: Bytes

See Also: System::createSoundGroup

SoundGroup::getNumPlaying

Retrieves the number of currently playing Channels for the SoundGroup.

FMOD_RESULT SoundGroup::getNumPlaying(
  int *numplaying
);

FMOD_RESULT FMOD_SoundGroup_GetNumPlaying(
  FMOD_SOUNDGROUP *soundgroup,
  int *numplaying
);

RESULT SoundGroup.getNumPlaying(
  out int numplaying
);

SoundGroup.getNumPlaying(
  numplaying
);

numplaying Out

Number of actively playing Channels from sounds in this SoundGroup.

This routine returns the number of Channels playing. If the SoundGroup only has one Sound, and that Sound is playing twice, the figure returned will be two.

See Also: System::createSoundGroup, System::getMasterSoundGroup

SoundGroup::getNumSounds

Retrieves the current number of sounds in this sound group.

FMOD_RESULT SoundGroup::getNumSounds(
  int *numsounds
);

FMOD_RESULT FMOD_SoundGroup_GetNumSounds(
  FMOD_SOUNDGROUP *soundgroup,
  int *numsounds
);

RESULT SoundGroup.getNumSounds(
  out int numsounds
);

SoundGroup.getNumSounds(
  numsounds
);

numsounds Out

Number of Sounds in this SoundGroup.

See Also: SoundGroup::getSound

SoundGroup::getSound

Retrieves a sound.

FMOD_RESULT SoundGroup::getSound(
  int index,
  Sound **sound
);

FMOD_RESULT FMOD_SoundGroup_GetSound(
  FMOD_SOUNDGROUP *soundgroup,
  int index,
  FMOD_SOUND **sound
);

RESULT SoundGroup.getSound(
  int index,
  out Sound sound
);

SoundGroup.getSound(
  index,
  sound
);

index

Index of the sound.

sound Out

Sound object. (Sound)

Use SoundGroup::getNumSounds in conjunction with this function to enumerate all sounds in a SoundGroup.

See Also: System::createSound

SoundGroup::getSystemObject

Retrieves the parent System object.

FMOD_RESULT SoundGroup::getSystemObject(
  System **system
);

FMOD_RESULT FMOD_SoundGroup_GetSystemObject(
  FMOD_SOUNDGROUP *soundgroup,
  FMOD_SYSTEM **system
);

RESULT SoundGroup.getSystemObject(
  out System system
);

SoundGroup.getSystemObject(
  system
);

system Out

System object. (System)

See Also: System::createSoundGroup, System::getMasterSoundGroup

SoundGroup::getUserData

Retrieves a user value associated with this object.

FMOD_RESULT SoundGroup::getUserData(
  void **userdata
);

FMOD_RESULT FMOD_SoundGroup_GetUserData(
  FMOD_SOUNDGROUP *soundgroup,
  void **userdata
);

RESULT SoundGroup.getUserData(
  out IntPtr userdata
);

SoundGroup.getUserData(
  userdata
);

userdata Out

User data set by calling SoundGroup::setUserData.

This function allows arbitrary user data to be retrieved from this object. See the User Data section of the glossary for an example of how to get and set user data.

SoundGroup::getVolume

Retrieves the volume of the sound group.

FMOD_RESULT SoundGroup::getVolume(
  float *volume
);

FMOD_RESULT FMOD_SoundGroup_GetVolume(
  FMOD_SOUNDGROUP *soundgroup,
  float *volume
);

RESULT SoundGroup.getVolume(
  out float volume
);

SoundGroup.getVolume(
  volume
);

volume Out

Volume level.

• Units: Linear
• Range: [0, 1]
• Default: 1

See Also: SoundGroup::setVolume

SoundGroup::release

Releases a soundgroup object and returns all sounds back to the master sound group.

FMOD_RESULT SoundGroup::release();

FMOD_RESULT FMOD_SoundGroup_Release(FMOD_SOUNDGROUP *soundgroup);

RESULT SoundGroup.release();

SoundGroup.release();

You cannot release the master SoundGroup.

See Also: System::createSoundGroup, System::getMasterSoundGroup

SoundGroup::setMaxAudible

Sets the maximum number of playbacks to be audible at once in a sound group.

FMOD_RESULT SoundGroup::setMaxAudible(
  int maxaudible
);

FMOD_RESULT FMOD_SoundGroup_SetMaxAudible(
  FMOD_SOUNDGROUP *soundgroup,
  int maxaudible
);

RESULT SoundGroup.setMaxAudible(
  int maxaudible
);

SoundGroup.setMaxAudible(
  maxaudible
);

maxaudible

Maximum number of playbacks to be audible at once. -1 denotes unlimited.

• Range: [-1, inf)
• Default: -1

If playing instances of sounds in this group equal or exceed number specified here, attepts to play more of the sounds with be met with FMOD_ERR_MAXAUDIBLE by default.
Use SoundGroup::setMaxAudibleBehavior to change the way the sound playback behaves when too many sounds are playing. Muting, failing and stealing behaviors can be specified. See FMOD_SOUNDGROUP_BEHAVIOR.

SoundGroup::getNumPlaying can be used to determine how many instances of the sounds in the SoundGroup are currently playing.

See Also: SoundGroup::getMaxAudible, SoundGroup::setMaxAudibleBehavior, SoundGroup::getMaxAudibleBehavior

SoundGroup::setMaxAudibleBehavior

This function changes the way the sound playback behaves when too many sounds are playing in a soundgroup.

FMOD_RESULT SoundGroup::setMaxAudibleBehavior(
  FMOD_SOUNDGROUP_BEHAVIOR behavior
);

FMOD_RESULT FMOD_SoundGroup_SetMaxAudibleBehavior(
  FMOD_SOUNDGROUP *soundgroup,
  FMOD_SOUNDGROUP_BEHAVIOR behavior
);

RESULT SoundGroup.setMaxAudibleBehavior(
  SOUNDGROUP_BEHAVIOR behavior
);

SoundGroup.setMaxAudibleBehavior(
  behavior
);

behavior

SoundGroup max playbacks behavior. (FMOD_SOUNDGROUP_BEHAVIOR)

• Default: FMOD_SOUNDGROUP_BEHAVIOR_FAIL

See Also: SoundGroup::getMaxAudibleBehavior, SoundGroup::setMaxAudible, SoundGroup::getMaxAudible

SoundGroup::setMuteFadeSpeed

Sets a mute fade time.

FMOD_RESULT SoundGroup::setMuteFadeSpeed(
  float speed
);

FMOD_RESULT FMOD_SoundGroup_SetMuteFadeSpeed(
  FMOD_SOUNDGROUP *soundgroup,
  float speed
);

RESULT SoundGroup.setMuteFadeSpeed(
  float speed
);

SoundGroup.setMuteFadeSpeed(
  speed
);

speed

Fade time. 0 = no fading.

• Units: Seconds
• Range: [0, inf)
• Default: 0

If a mode besides FMOD_SOUNDGROUP_BEHAVIOR_MUTE is used, the fade speed is ignored.

When more sounds are playing in a SoundGroup than are specified with SoundGroup::setMaxAudible, the least important Sound (ie lowest priority / lowest audible volume due to 3D position, volume etc) will fade to silence if FMOD_SOUNDGROUP_BEHAVIOR_MUTE is used, and any previous sounds that were silent because of this rule will fade in if they are more important.

See Also: SoundGroup::getMuteFadeSpeed

SoundGroup::setUserData

Sets a user value associated with this object.

FMOD_RESULT SoundGroup::setUserData(
  void *userdata
);

FMOD_RESULT FMOD_SoundGroup_SetUserData(
  FMOD_SOUNDGROUP *soundgroup,
  void *userdata
);

RESULT SoundGroup.setUserData(
  IntPtr userdata
);

SoundGroup.setUserData(
  userdata
);

userdata

Value stored on this object.

This function allows arbitrary user data to be attached to this object. See the User Data section of the glossary for an example of how to get and set user data.

See Also: SoundGroup::getUserData

SoundGroup::setVolume

Sets the volume of the sound group.

FMOD_RESULT SoundGroup::setVolume(
  float volume
);

FMOD_RESULT FMOD_SoundGroup_SetVolume(
  FMOD_SOUNDGROUP *soundgroup,
  float volume
);

RESULT SoundGroup.setVolume(
  float volume
);

SoundGroup.setVolume(
  volume
);

volume

Volume level.

• Units: Linear
• Range: [0, 1]
• Default: 1

Scales the volume of all Channels playing Sounds in this SoundGroup.

See Also: SoundGroup::getVolume

SoundGroup::stop

Stops all sounds within this soundgroup.

FMOD_RESULT SoundGroup::stop();

FMOD_RESULT FMOD_SoundGroup_Stop(FMOD_SOUNDGROUP *soundgroup);

RESULT SoundGroup.stop();

SoundGroup.stop();

See Also: System::playSound