# 7. 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 sound group.
- 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.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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 sound group.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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
  Value stored on this object.

See Also: SoundGroup::setUserData

## SoundGroup::getVolume

Retrieves the volume of the sound group.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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.

C
C++
C#
JS

    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.

Associates some data with this object to give it context, it will be passed back via callbacks but otherwise remain untouched.

See Also: SoundGroup::getUserData

## SoundGroup::setVolume

Sets the volume of the sound group.

C
C++
C#
JS

    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.

C
C++
C#
JS

    FMOD_RESULT SoundGroup::stop();

    FMOD_RESULT FMOD_SoundGroup_Stop(FMOD_SOUNDGROUP *soundgroup);

    RESULT SoundGroup.stop();

    SoundGroup.stop();

See Also: System::playSound