SoundSource objects are used to position sounds within your Scene. Sounds emitted can be either positional, directional or ambient; they can either be buffered or be played directly. Coupled with direct filtering and audio effects each sound source can be controlled independently to give the best audio experience to your users.

Static Variables

Name	Description
`object`	Parent Object where the SoundSource component is attached.
Declaration Object *object
`soundbuffer`	The active SoundBuffer Asset connected to the active SoundSource.
Declaration SoundBuffer *soundbuffer
`group`	Current SoundGroup the active SoundSource belongs to (if any).
Declaration SoundGroup *group
`source_id`	Internal source id given by the underlying sound API (OpenAL).
Declaration unsigned int source_id
`direct_filter`	Current AudioFilter connected to the active SoundSource.
Declaration AudioFilter *direct_filter

Variables

Name Description

priority Value used by the sound queue system to determine the active SoundSource priority.

Declaration

unsigned char priority

Range

0 to 255

option PresetOption set for the active SoundSource.

Declaration

PresetOption option

speaker_type Defines the way the sound of the active SoundSource is emitted in space.

Declaration

SpeakerType speaker_type

distance_model Custom DistanceModel to apply to the SoundSource.

Declaration

DistanceModel distance_model

pitch Controls the internal playback speed of the SoundBuffer associated to the active SoundSource.

Declaration

float pitch

Range

0.5 to 2.0

gain Controls the volume of the active SoundSource.

Declaration

float gain

Range

0.0 to 1.0

air_absorption Multiplier to the amount of air absorption applied to the SoundSource.

Declaration

float air_absorption

Range

0.0 to 10.0

Note: This value it is multiplied by an internal gain value per meter which represents normal atmospheric humidity and temperature.

room_rolloff_factor Additional factor to the SoundSource roll-off factor which is used to attenuate the reflected sound according to the source-listener distance.

Declaration

float room_rolloff_factor

Range

0.0 to 10.0

min_gain Minimum amount of gain that can be applied to the SoundSource.

Declaration

float min_gain

Range

0.0 to 1.0

Note: This value will be used to clamp the gain if it goes below that level. If a value of zero is set, then the gain will not be corrected.

max_gain Defines the amplitude threshold and indicates the maximal gain that can be applied to the SoundSource.

Declaration

float max_gain

Range

0.0 to 1.0

Note: This value will be used to clamp the gain if it goes above that level after processing various attenuation factors.

rolloff_factor Affect the distance attenuation calculations based on inverse distance with the roll off.

Declaration

float rolloff_factor

Range

0.0 to inf.

Note: For distances smaller than the value set in max. distance this will scale the distance attenuation over the applicable range (taking ref. distance into consideration).

max_distance Maximum distance the sound should still be heard.

Declaration

float max_distance

Range

0.0 to inf.

Note: The attenuation will be interpolated (based on the attenuation model selected in the sound settings) between the reference distance and the maximum distance.

reference_distance Act as the minimum distance the SoundSource should be emitting at full capacity.

Declaration

float reference_distance

Range

0.0 to inf.

cone_outer_gain Define the volume level outside of the cone defined by the outer angle.

Declaration

float cone_outer_gain

Range

0.0 to 1.0

cone_outer_gain_hf The high-frequency gain of the outside cone defined by the outer angle.

Declaration

float cone_outer_gain_hf

Range

0.0 to 1.0

cone_inner_angle The inner angle of the directional SoundSource cone (in degree).

Declaration

float cone_inner_angle

Range

0.0 to 360.0 degrees

Note: The default value of 360 degrees means that the inner angle covers the entire distance, which is equivalent to an omnidirectional (positional) SoundSource.

cone_outer_angle The outside angle of the directional SoundSource cone (in degree).

Declaration

float cone_outer_angle

Range

0.0 to 360.0 degrees

Note: The default value of 360 means that the outer angle covers the entire source radius. If the inner angle is also 360, then the zone for angle-dependent attenuation is set to zero.

effectslot_mask Bit mask created from EffectSlot flags that tell the system which AudioEffect should be applied on the SoundSource.

Declaration

EffectSot effectslot_mask

velocity Current SoundSource velocity vector.

Declaration

vec3 velocity

Note: Only apply when the SoundSource SpeakerType is either kDirection or kPositional; else will always be zero.

state Active playback state of the SoundSource.

Declaration

State state

warmstart The amount of time to seek before starting the playback of the SoundSource.

Declaration

float warmstart

flags Bit mask of various options currently applied to the SoundSource.

Declaration

int flags

Cap	Value	Description
`SND_FLAG_AUTO_PLAY`	`bit.lshift(1,0)`	Notify the internal system that the SoundSource should start playing immediately when loaded.
`SND_FLAG_AUTO_LOOP`	`bit.lshift(1,1)`	Rewind the SoundSource when the end of the SoundBuffer is reached.
`SND_FLAG_AUTO_VELOCITY`	`bit.lshift(1,2)`	Automatically calculate and update the velocity of the SoundSource.
`SND_FLAG_AUTO_DELETE`	`bit.lshift(1,3)`	Remove the SoundSource Object as soon as it stops playing.
`SND_FLAG_RANDOMIZE_WARMSTART`	`bit.lshift(1,4)`	Randomize the warmstart time.

auto_play Specify to the internal system that the SoundSource should start playing as soon it is loaded.

Declaration

bool auto_play

auto_loop Loop back the SoundSource when the end of the audio stream is reached.

Declaration

bool auto_loop

auto_velocity Let the internal system calculate and update the velocity of the SoundSource.

Declaration

bool auto_velocity

Note: Only apply for kPositional and kDirectional SoundSource Object that are not static.

auto_delete Automatically remove the SoundSource from the Scene it belong when it stops playing.

Declaration

bool auto_delete

randomize_warmstart Randomize the warmstart time before playback.

Declaration

bool randomize_warmstart

Functions

Name	Description
`SetSoundBuffer`	Connect an existing SoundBuffer Asset to the active SoundSource.
Declaration void SetSoundBuffer( SoundBuffer soundbuffer ) Parameters* `soundbuffer`: Reference to an existing SoundBuffer; to disconnect the Asset set it to `nil`.
`EnableStreaming`	Enable SoundBuffer streaming.
Declaration bool EnableStreaming( unsigned char buffer_count, unsigned short buffer_size ) Parameters `buffer_count`: Total amount of buffers (1 to 8). `buffer_size`: Amount of memory per buffer (8192 to 32768 bytes). Return Value `true` if the streaming have been enabled; `false` if it was already enabled.
`Stop`	Helper to modify the current streaming buffer configuration.
Declaration bool SetStreamingBuffers( unsigned char buffer_count, unsigned short buffer_size ) Parameters `buffer_count`: Total amount of buffers (1 to 8). `buffer_size`: Amount of memory per buffer (8192 to 32768 bytes). Return Value `true` if streaming is enabled and the update was successfull; else return `false`.
`DisableStreaming`	Disable streaming and destroy all allocated buffers.
Declaration bool DisableStreaming( void ) Return Value `true` if sound streaming is disabled successfully; `false` if the SoundSource had no streaming capabilities.
`Play`	Start/resume the active SoundSource playback.
Declaration bool Play( void ) Return Value `true` if the SoundSource start/resume playing successfully; `false` if it was already playing.
`Pause`	Pause the active SoundSource playback.
Declaration bool Pause( void ) Return Value `true` if the SoundSource pause successfully; `false` if it was already paused.
`Stop`	Stop the active SoundSource playback.
Declaration bool Stop( void ) Return Value `true` if the SoundSource stop playing; `false` if it was not already playing.
`Seek`	Move the audio stream to a specific time where `1.0 = 1sec.`.
Declaration void Seek( float playback_time ) Parameters `playback_time`: The new playback time to jump to.
`GetPlaybackTime`	Return the current playback time for the active SoundSource.
Declaration float GetPlaybackTime( void ) Return Value The current playback time where `1.0 = 1sec.`.
`GetDuration`	Helper function that return the total duration of the SoundSource audio stream.
Declaration float GetDuration( void )
`GetBuffersQueued`	Function that returns the current amount of queued buffers.
Declaration int GetBuffersQueued( void ) Return Value The number of queued buffer. Note If streaming is not enabled the value returned by this function will always be 0. Streaming should be enabled to receive any valid value from this function.
`SetAudioFilter`	Connect an AudioFilter to the existing SoundSource.
Declaration void SetAudioFilter( AudioFilter audiofilter ) Parameters* `audiofilter`: Reference to an existing AudioFilter Asset; to disconnect the Asset set it to `nil`.
`SetEffectSlotAudioFilter`	Assign an existing AudioFilter to a specific slot.
Declaration bool SetEffectSlotAudioFilter( unsigned char slot, AudioFilter audiofilter ) Parameters* `slot`: The slot index (0 to 3) to connect/disconnect the AudioFilter. `audiofilter`: Reference to an existing AudioFilter Asset; to disconnect the slot set this parameter to `nil`. Return Value `true` if the operation is successfull; `false` if the slot index is out of bounds.
`HideAll`	Retrieve the AudioFilter connected to a specific slot.
Declaration AudioFilter GetEffectSlotAudioFilter( unsigned char slot ) Return Value* `nil` if the slot index provided is out of bounds or if no AudioFilter is connected to it.
`ClearEffectSlotAudioFilters`	Clear all the AudioFilter slots connected to the active SoundSource.
Declaration void ClearEffectSlotAudioFilters( void )
`Sync`	Force to update and synchronize all AudioFilter slots associated with the current SoundSource.
Declaration void Sync( void )

Events

Callbacks	Description
`OnPlay`	This callback gets called when the SoundSource received the signal to start playing.
Declaration function OnPlay()
`OnResume`	Triggered if the SoundSource was paused and then start playing again.
Declaration function OnResume()
`OnPause`	Triggered when the SoundSource gets paused.
Declaration function OnPause()
`OnStop`	Called when the SoundSource received the stop signal.
Declaration function OnStop()

SpeakerType

Available types of speaker that dictate the way the SoundSource propagate sounds in your world.

kAmbient: Playback audio tracks without any attenuation. Regardless of the listener distance to the source, the sound is constant. It is typically used to play background music or other types of background sound effects.
kPositional: Can be defined as omnidirectional, this type launches sound in every direction and is attenuated based on the listener-source distance.
kDirectional: Emit sounds using an inner and outer cone; just like kPositional it is also affected by the distance with the listener. The two cones that form the directional sound source can be adjusted independently depending on the type of emission you are stimulating as well as the front and back gain.