Unigine.SoundSource Class
| Inherits: | Node |
This class is used to create directional sound sources. The source's sound fades out linearly in a specified range (see getMinDistance() and getMaxDistance()). If inner and outer sound cones are defined, they will also have their share in the attenuation factor (see the getConeInnerAngle() and getConeOuterAngle() functions).
Notice
Attenuation is available only for mono sound sources. If a source is the stereo one, it won't attenuate with the distance.
Sound sources are automatically handled by the sound manager. When the sound source is within the audible range, it is loaded into the memory (a full sample or its chunk, depending on whether the source is static or streamed). When it gets outside the audible range, the sound file is automatically deleted from the memory. Static sound sources are instanced; streamed ones are not.
If you still want to manage a sound source manually, you can check if it has stopped
playing and after that delete it.
There is also no limitation on the number of sound sources in the world, as only currently audible ones are rendered. In the worst case scenario, when the number of simultaneously heard sound sources exceeds the hardware capabilities, some of them will not played.
Creating a Sound Source#
To create a sound source, create an instance of the SoundSource class and specify all required settings:
Source code (C#)
// create a new sound source using the given sound sample file
SoundSource sound = new SoundSource("sound.mp3");
// disable sound muffling when being occluded
sound.Occlusion = 0;
// set the distance at which the sound gets clear
sound.MinDistance = 10.0f;
// set the distance at which the sound becomes out of audible range
sound.MaxDistance = 100.0f;
// set the gain that result in attenuation of 6 dB
sound.Gain = 0.5f;
// loop the sound
sound.Loop = 1;
// start playing the sound sample
sound.Play();Updating an Existing Sound Source#
To update the sound source settings, you can call the corresponding methods:
Source code (C#)
// change the sample file of the playing sound source
if ((sound.IsPlaying) && (App.clearKeyState('c') == 1))
{
// specify a new sample file
sound.SampleName = "sound_1.mp3";
// reduce the gain
sound.Gain = 0.2f;
}As sound has its own thread that updates at 30 FPS, changes won't be applied immediately. However, you can force updating by using the renderWorld() method.
Sound events like play() or stop() aren't updated immediately as well. So, when you need to perform operations that require stopping of the playback (for example, updating the time, from which the sample should be played), you need to force update the sound thread after stopping the playback:
Source code (C#)
// check if the sound sample is playing
if (sound.IsPlaying)
{
// stop playing the sample
sound.Stop();
// force updating of the sound thread
Sound.RenderWorld(1);
// update time
sound.Time = 0.0f;
// play the sample
sound.Play();
}See Also
- Playing Sounds on Collisions article to learn how to play sound sources on collisions with physical bodies.
- A set of UnigineScript API samples located in the <UnigineSDK>/data/samples/sounds/ folder:
- sound_static_00
- sound_static_01
- sound_static_02
- sound_static_03
- sound_static_04
- sound_stream_00
SoundSource Class
Properties
bool IsStopped#
A value indicating if playback is currently stopped.
bool IsPlaying#
A value indicating if the sample is currently being played.
float RoomRolloff#
The current scaling room rolloff factor for the sound source that determines attenuation of the reverberation sound over distance.
set
Updates the scaling room rolloff factor for the sound source that determines attenuation of the reverberation sound over distance.
set value -
Room rolloff factor in range [0.0; 10.0].
float Adaptation#
The current adaptation time period for the sound source, during which the volume of the occluded sound gradually changes (fading in and out). this parameter is used to make sounds fade in and out smoothly.
set
Sets the new adaptation time period for the sound source, during which the volume of the occluded sound gradually changes (fading in and out). This parameter is used to make sounds fade in and out smoothly.
set value -
Adaptation time to be set, in seconds. 0.0f means instant adaptation.
int Occlusion#
A value indicating if sound source should be muffled when being occluded.
set
Updates a value indicating if the sound source should be muffled when being occluded.
set value -
Positive number if the sound should be muffled by occlusion; otherwise, 0.
int OcclusionMask#
The current bit mask that determines which objects occlude the sound source. for a sound to be occluded by an object's surface, at least one bit of this mask should match the occlusion mask of object's surface. Each surface has its own occlusion value, that determines how much it affects sounds in case of occlusion.
Notice
Sound occlusion must be enabled.
set
Updates the bit mask, that determines which objects occlude the sound source. For a sound to be occluded by an object's surface, at least one bit of this mask should match the occlusion mask of object's surface. Each surface has its own occlusion value, that determines how much it affects sounds in case of occlusion.
Notice
Sound occlusion must be enabled.
set value -
Integer, each bit of which is a mask for sound source occlusion.
float MinDistance#
A distance, at which the sound starts to fade, in units.
set
Updates a distance, at which the sound starts to fade, in units.
set value -
Distance in units.
float MaxDistance#
A distance, at which the sound completely fades out, in units.
set
Updates a distance, at which the sound completely fades out, in units.
set value -
Distance in units.
float ConeOuterGain#
The current gain controlling the sound intensity outside the oriented cone defined by the outer angle.
set
Updates the gain controlling the sound intensity outside the oriented cone defined by the outer angle.
set value -
Cone outer gain in range [0.0;1.0].
float ConeOuterGainHF#
The current gain filter value for the sound source that attenuates the reverberation sound at high frequencies outside the oriented cone.
set
Updates the gain filter value for the sound source that attenuates the reverberation sound at high frequencies outside the oriented cone.
set value -
High-frequency reverberation gain value in range [0.0;1.0].
float ConeOuterAngle#
The current angle of the outer sound cone. when moving to the edge of the outer cone, sound volume is fading up to the outside the cone gain value.
set
Updates an angle of the outer sound cone. When moving to the edge of the outer cone, sound volume is fading up to the gain value outside the oriented cone.
set value -
Cone outer angle in degrees.
float ConeInnerAngle#
The current angle of the inner sound cone. sound volume in the inner cone does not change.
set
Updates an angle of the inner sound cone. Sound volume in the inner cone does not change. 360 degrees represents an omnidirectional sound source.
set value -
Cone inner angle in degrees.
float AirAbsorption#
The current air absorption value for the sound source that determines the distance-dependent attenuation of the reverberation sound at high frequencies caused by the propagation medium.
set
Updates the air absorption value for the sound source that determines the distance-dependent attenuation of the reverberation sound at high frequencies caused by the propagation medium.
set value -
Air absorption value in range [0.0;10.0].
float Time#
The current time, at which the sample is being played.
set
int ReverbMask#
The current bit mask that determines what reverberation zones can be heard. For sound to reverberate, at least one bit of this mask should match with the player's reverberation mask. At the same time, reverb mask of the reverberation zone should also match with the player's one (but not necessarily in the same bit as this mask matches it).
set
Updates the bit mask that determines what reverberation zones can be heard. For sound to reverberate, at least one bit of this mask should match with the player's reverberation mask. At the same time, reverb mask of the reverberation zone should also match with the player's one (but not necessarily in the same bit as this mask matches it).
set value -
Integer, each bit of which is a mask for reverberating sound sources.
int SourceMask#
A bit mask that determines to what sound channels the source belongs to. For a sound source to be heard, its mask should match at least with the player's sound mask in at least one bit.
set
Updates a bit mask that determines to what sound channels the source belongs to. For a sound source to be heard, its mask should match with the player's sound mask in at least one bit.
set value -
Integer, each bit of which specifies a sound channel.
string SampleName#
The sound sample file of the sound source.
set
Sets a new sound file for the ambient sound.
set value -
Path to the sound sample file.
float Pitch#
The current sound pitch.
set
Updates a sound pitch.
set value -
Factor, by which the current pitch will be multiplied in range [0.1;10.0].
bool IsStream#
A value indicating whether the sound is streamed or not.
set
Set a value indicating whether the sound is streamed or not.
set value -
true if the sound is a streamed one; otherwise, false.
bool IsRestartOnEnable#
A value indicating if playback is to be restarted from the beginning each time the sound source is enabled.
set
Enables or disables playback restart on enabling the sound source.
set value -
true to enable playback restart on enabling the sound source, false to disable it.
bool IsPlayOnEnable#
A value indicating if playback is to be started each time the sound source is enabled.
Notice
Playback will begin from the moment it was previously stopped. To enable playback from the beginning use the setRestartOnEnable() method.
set
Enables or disables playback start on enabling the sound source.
Notice
Playback will begin from the moment it was previously stopped. To enable playback from the beginning use the setRestartOnEnable() method.
set value -
true to enable playback start on enabling the sound source, false to disable it.
int Loop#
A value indicating if the sample is looped.
set
Updates a value indicating if the sample should be looped.
set value -
Positive number to loop the sample, 0 to play it only once.
float Length#
The total length of the sound sample.
float Gain#
The current gain controlling the sound intensity. is set to 0, the sound source is muted.
set
Updates the gain controlling the sound intensity. Setting the value to 0.0 mutes the sound source.
set value -
Gain value in range [0.0;1.0].
Members
static SoundSource ( string name, int stream = 0 ) #
Constructor. Creates a new world sound source using a given sound sample file.Arguments
- string name - Path to the sound sample file.
- int stream - Positive value to create a streaming source, 0 to create a static source. If the flag is set, the sample will not be fully loaded into memory. Instead, its successive parts will be read one by one into a memory buffer.
void Play ( ) #
Starts playing the sample.void Stop ( ) #
Stops playback. This function saves the playback position so that playing of the file can be resumed from the same point.Notice
The playback won't stop immediately, as the sound thread is updated at 30 FPS. So, when you need to perform operations that require stopping of the playback (for example, updating the time, from which the sample should be played), you need to force update the sound thread after stopping the playback.
static int type ( ) #
Returns the type of the node.Return value
Sound type identifier.Last update:
2020-07-31
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)