Firelight Technologies FMOD Studio API

System::playSound

Plays a sound object on a particular channel and ChannelGroup if desired.

C++ Syntax

FMOD_RESULT System::playSound(
  FMOD::Sound *sound,
  FMOD::ChannelGroup *channelgroup,
  bool paused,
  FMOD::Channel **channel
);

C Syntax

FMOD_RESULT FMOD_System_PlaySound(
  FMOD_SYSTEM *system,
  FMOD_SOUND *sound,
  FMOD_CHANNELGROUP *channelgroup,
  FMOD_BOOL paused,
  FMOD_CHANNEL **channel
);

C# Syntax

RESULT System.playSound(
  Sound sound,
  ChannelGroup channelGroup,
  bool paused,
  out Channel channel
);

JavaScript Syntax

System.playSound(
  sound,                           
  channelgroup,                    
  paused,                          
  channel                          // writes value to channel.val
);

Parameters

sound

Pointer to the sound to play. This is opened with System::createSound.

channelgroup

Pointer to a channelgroup become a member of. This is more efficient than using Channel::setChannelGroup, as it does it during the channel setup, rather than connecting to the master channel group, then later disconnecting and connecting to the new channelgroup when specified. Optional. Use 0/NULL to ignore (use master ChannelGroup).

paused

True or false flag to specify whether to start the channel paused or not. Starting a channel paused allows the user to alter its attributes without it being audible, and unpausing with Channel::setPaused actually starts the sound.

channel

Address of a channel handle pointer that receives the newly playing channel. Optional. Use 0/NULL to ignore.

Return Values

If the function succeeds then the return value is FMOD_OK.
If the function fails then the return value will be one of the values defined in the FMOD_RESULT enumeration.

Remarks

When a sound is played, it will use the sound's default frequency and priority.

A sound defined as FMOD_3D will by default play at the position of the listener.
To set the 3D position of the channel before the sound is audible, start the channel paused by setting the paused flag to true, and calling Channel::set3DAttributes. Following that, unpause the channel with Channel::setPaused.

Channels are reference counted. If a channel is stolen by the FMOD priority system, then the handle to the stolen voice becomes invalid, and Channel based commands will not affect the new sound playing in its place.
If all channels are currently full playing a sound, FMOD will steal a channel with the lowest priority sound.
If more channels are playing than are currently available on the soundcard/sound device or software mixer, then FMOD will 'virtualize' the channel. This type of channel is not heard, but it is updated as if it was playing. When its priority becomes high enough or another sound stops that was using a real hardware/software channel, it will start playing from where it should be. This technique saves CPU time (thousands of sounds can be played at once without actually being mixed or taking up resources), and also removes the need for the user to manage voices themselves.
An example of virtual channel usage is a dungeon with 100 torches burning, all with a looping crackling sound, but with a soundcard that only supports 32 hardware voices. If the 3D positions and priorities for each torch are set correctly, FMOD will play all 100 sounds without any 'out of channels' errors, and swap the real voices in and out according to which torches are closest in 3D space.
Priority for virtual channels can be changed in the sound's defaults, or at runtime with Channel::setPriority.

See Also

• System::createSound
• Channel::setPaused
• Channel::setPriority
• Channel::set3DAttributes
• Sound::setDefaults
• System::init

Version 1.10.03 Built on Feb 1, 2018