engine.sound Functions

WarningThe scope of applications for UnigineScript is limited to implementing materials-related logic (material expressions, scriptable materials, brush materials). Do not use UnigineScript as a language for application logic, please consider C#/C++ instead, as these APIs are the preferred ones. Availability of new Engine features in UnigineScript (beyond its scope of applications) is not guaranteed, as the current level of support assumes only fixing critical issues.

Controls the general sound settings, such as volume, speed of sound, the Doppler factor, sound adaptation and sound mixer channels. Settings can be loaded from a *.sound file or changed by the corresponding functions below.

In the *.sound file, the sound settings are stored in the <sound> section, for example:

Source code (XML)

<?xml version="1.0" encoding="utf-8"?>
<settings version="2.5.0.1">
	<sound>
		<scale>1</scale>
		<volume>0.8458</volume>
		<doppler>1</doppler>
		<velocity>340.3</velocity>
		<adaptation>0.01</adaptation>
		<attenuation>3</attenuation>
		<hrtf>0</hrtf>
		<source source="0" limit="2"/>
		<source source="1" limit="4"/>
		<source source="2" limit="4"/>
		<source source="4" volume="0.4"/>
	</sound>
</settings>

Usage Example#

The following example shows how to load sound settings from the *.sound file, change them and then save back to the sound settings file. Settings are loaded at startup. While the sound source (AmbientSource) is playing, you can use keyboard to change sound volume, toggle sounds on and off, and display current velocity. On shutdown the current sound settings are saved.

Source code (UnigineScript)

#include <core/unigine.h>

AmbientSource source;

int init() {
	
	// load sound settings from a file
	engine.sound.loadSettings("sound_settings.sound");

	// create a sound source that plays a sample
	source = new AmbientSource("ambient_source.oga",1);
	source.setLoop(1);
	source.play();
	
	return 1;
}

int update() {
	
	// enable/disable sounds in the scene
	if (engine.app.clearKeyState('z')) {
		engine.sound.setEnabled(!engine.sound.isEnabled());
		log.message("The enabled flag is %d\n", engine.sound.isEnabled());
	}

	// print the current speed of sound
	if (engine.app.clearKeyState('c')) {
		log.message("Sound velocity: %f\n", engine.sound.getVelocity());
	}

	// make the sound louder
	if (engine.app.clearKeyState('n')) {
		if (engine.sound.getVolume() != 1.0f) engine.sound.setVolume(engine.sound.getVolume() + 0.1f);
		log.message("The sound is louder %f\n", engine.sound.getVolume());
	}

	// make the sound quieter
	if (engine.app.getKeyState('m')) {
		if (engine.sound.getVolume() > 0.0f) engine.sound.setVolume(engine.sound.getVolume() - 0.1f);
		log.message("The sound is quieter %f\n", engine.sound.getVolume());
	}
	
	return 1;
}

int shutdown() {

	// save the sound settings into the file
	engine.sound.saveSettings("sound_settings.sound",1);
	source.clearPtr();
	
	return 1;
}

Methods:

Name	Description View: Sort by:
setAdaptation	Sets sound occlusion with the specified adaptation time.
getAdaptation	Returns the current time set for sound adaptation, that is used when the sound source becomes occluded or other way round.
setAttenuation	Sets the specified sound attenuation mode.
getAttenuation	Returns the current sound attenuation mode.
setData	Sets user data associated with the world.
getData	Returns user string data associated with the world.
setDoppler	Sets the Doppler factor.
getDoppler	Returns the current Doppler factor.
setEnabled	Enables or disables all sounds in the scene.
isEnabled	Returns a value indicating if sounds in the scene are enabled.
setHRTF	Enables or disables the HRTF (Head Related Transfer Function) mode.
isHRTF	Returns a value indicating if the binaural HRTF (Head Related Transfer Function) sound is enabled.
setSourceReverbMode	Sets sound reverberation mode.
getSourceReverbMode	Returns current sound reverberation mode.
setSourceOcclusion	Enables or disables occlusion for sounds.
isSourceOcclusion	Returns a value indicating if occlusion for sounds is enabled.
setScale	Set the time scale for the sound playing.
getScale	Returns the current time scale for the sound playing.
getTotalTime	Returns the total time of asynchronous loading sounds.
setVelocity	Sets the velocity value the Doppler shift calculation is based upon.
getVelocity	Returns the current velocity value the Doppler shift calculation is based upon.
setVolume	Sets the sound volume.
getVolume	Returns the current sound volume.
setSourceLimit	Limits the number of simultaneously played sound sources per one mixer channel.
getSourceLimit	Returns the current number of simultaneously played sound sources per one mixer channel.
setSourceVolume	Sets the volume of the specified mixer channel.
getSourceVolume	Returns the current volume of the specified mixer channel.
loadSettings	Loads the sound settings from the given file.
loadWorld	Loads a sound state from the Xml.
renderWorld	Forces update of the sound system: all sound changes (such as play() or stop() events and change of parameters) will be applied at once.
saveSettings	Saves the current sound settings to the given file.
saveState	Saves a sound state into the stream.
restoreState	Restores a sound state from the stream.
saveWorld	Saves a sound state into the given Xml node.

Variables:

Name	Description
SOUND_ATTENUATION_EXPONENT = 4	Exponential distance rolloff model, modeling an exponential dropoff in gain as distance increases between the source and listener.
SOUND_ATTENUATION_EXPONENT_CLAMPED = 5	Exponential Distance clamped model.
SOUND_ATTENUATION_INVERSE = 0	Inverse distance rolloff model.
SOUND_ATTENUATION_INVERSE_CLAMPED = 1	Inverse distance clamped model.
SOUND_ATTENUATION_LINEAR = 2	Linear distance rolloff model.
SOUND_ATTENUATION_LINEAR_CLAMPED = 3	Linear distance clamped model.
SOUND_NUM_SOURCES = 32	Number of sound sources.
SOUND_REVERB_DISABLED = 0	Reverberation is disabled.
SOUND_REVERB_MULTIPLE = 2	Multiple-environment reverberation.
SOUND_REVERB_SINGLE = 1	Single-environment reverberation.

Sound Class

Members

void engine.sound.setAdaptation ( float adaptation ) #

Sets sound occlusion with the specified adaptation time.

Arguments

float adaptation - Time for sound adaptation to a filter, used when the sound source becomes occluded or other way round.

float engine.sound.getAdaptation ( ) #

Returns the current time set for sound adaptation, that is used when the sound source becomes occluded or other way round.

Return value

Time for sound adaptation to a filter.

void engine.sound.setAttenuation ( int attenuation ) #

Sets the specified sound attenuation mode. Attenuation is the ability of a sound to lower in volume as the player moves away from it.

Arguments

int attenuation - One of the SOUND_ATTENUATION_* variables. The default value is SOUND_ATTENUATION_LINEAR_CLAMPED.

int engine.sound.getAttenuation ( ) #

Returns the current sound attenuation mode.

Return value

One of the SOUND_ATTENUATION_* variables.

void engine.sound.setData ( string data ) #

Sets user data associated with the world. This string is written directly into a *.world file, into the data child tag of the sound tag, for example:

Source code (XML)

<world version="1.21">
	<sound>
		<data>User data</data>
	</sound>
</world>

Arguments

string data - New user data. Data can contain an XML formatted string

string engine.sound.getData ( ) #

Returns user string data associated with the world. This string is written directly into the data tag of the *.world file, into the data child tag of the sound tag, for example:

Source code (XML)

<world version="1.21">
	<sound>
		<data>User data</data>
	</sound>
</world>

Return value

User data. Data can contain an XML formatted string.

void engine.sound.setDoppler ( float doppler ) #

Sets the Doppler factor. This parameter allows you to exaggerate or tone-down the Doppler shift effect. By default, it is set to 1.0f.

Arguments

float doppler - Doppler factor.

float engine.sound.getDoppler ( ) #

Returns the current Doppler factor. This parameter allows you to exaggerate or tone-down the Doppler shift effect. The default value is 1.0f.

Return value

Doppler factor.

void engine.sound.setEnabled ( int enabled ) #

Enables or disables all sounds in the scene.

Arguments

int enabled - 1 to enable all sounds, 0 to disable them.

int engine.sound.isEnabled ( ) #

Returns a value indicating if sounds in the scene are enabled.

Return value

1 if sounds are enabled; otherwise, 0.

void engine.sound.setHRTF ( int hrtf ) #

Enables or disables the HRTF (Head Related Transfer Function) mode. This mode provides imitation of the surround sound for the stereo wired headset.

Arguments

int hrtf - 1 to enable binaural sound; 0 to disable it.

int engine.sound.isHRTF ( ) #

Returns a value indicating if the binaural HRTF (Head Related Transfer Function) sound is enabled. An HRTF provides imitation of the surround sound for the stereo wired headset.

Return value

1 if the binaural sound is enabled; otherwise, 0.

void engine.sound.setSourceReverbMode ( int mode ) #

Sets sound reverberation mode.

Arguments

int mode - Reverberation mode. One of the SOUND_REVERB_* variables. The default value is SOUND_REVERB_MULTIPLE.

int engine.sound.getSourceReverbMode ( ) #

Returns current sound reverberation mode.

Return value

Current sound reverberation mode. One of the SOUND_REVERB_* variables. The default value is SOUND_REVERB_MULTIPLE.

void engine.sound.setSourceOcclusion ( int occlusion ) #

Enables or disables occlusion for sounds. When enabled, the sound will be occluded when there are other nodes between the listener and the sound source.

Arguments

int occlusion - 1 to enable occlusion for sounds, 0 to disable it.

int engine.sound.isSourceOcclusion ( ) #

Returns a value indicating if occlusion for sounds is enabled. When enabled, the sound will be occluded when there are other nodes between the listener and the sound source.

Return value

1 if sound occlusion for sounds is enabled; otherwise, 0.

void engine.sound.setScale ( float scale ) #

Set the time scale for the sound playing.

Arguments

float scale - Sound time scale. The provided value is clamped in the range [0; 2].

float engine.sound.getScale ( ) #

Returns the current time scale for the sound playing.

Return value

Sound time scale.

void engine.sound.setSourceLimit ( int source, int limit ) #

Limits the number of simultaneously played sound sources per one mixer channel. This setting is also available in the Editor global sound settings.

Arguments

int source - Number of the mixer channel (from 0 to 31).
int limit - The maximum number of sound sources that can be played simultaneously.

int engine.sound.getSourceLimit ( int source ) #

Returns the current number of simultaneously played sound sources per one mixer channel.

Arguments

int source - Number of the mixer channel (from 0 to 31).

Return value

The maximum number of sound sources that can be played simultaneously.

void engine.sound.setSourceVolume ( int source, float volume ) #

Sets the volume of the specified mixer channel.

Arguments

int source - Number of the mixer channel (from 0 to 31).
float volume - Channel volume. The provided value is clamped within [0;1] range, where 0 means muted sound and 1 is the maximum volume.

float engine.sound.getSourceVolume ( int source ) #

Returns the current volume of the specified mixer channel.

Arguments

int source - Number of the mixer channel (from 0 to 31).

Return value

Volume of the specified mixer channel. The returning value is in range [0;1], where 0 means muted sound and 1 is the maximum volume.

float engine.sound.getTotalTime ( ) #

Returns the total time of asynchronous loading sounds.

Return value

The total time value, milliseconds.

void engine.sound.setVelocity ( float velocity ) #

Sets the velocity value the Doppler shift calculation is based upon. By default, it is set to 343.3f. If you have players moving really fast, then you may want to adjust this to prevent the Doppler shift from distorting the sound too much.

Arguments

float velocity - New velocity value for the Doppler shift calculation to be set.

float engine.sound.getVelocity ( ) #

Returns the current velocity value the Doppler shift calculation is based upon. By default, it is set to 343.3f. If you have players moving really fast, then you may want to adjust this to prevent the Doppler shift from distorting the sound too much.

Return value

Current velocity value for the Doppler shift calculation.

void engine.sound.setVolume ( float volume ) #

Sets the sound volume. By default, it is set to 1.0f.

Arguments

float volume - Sound volume. 0 means the muted sound, 1 means the maximum volume.

float engine.sound.getVolume ( ) #

Returns the current sound volume. The default value is 1.0f.

Return value

Sound volume. 0 means the muted sound, 1 means the maximum volume.

int engine.sound.loadSettings ( string name, int clear = false ) #

Loads the sound settings from the given file.

Arguments

string name - Path to a sound settings file (*.sound).
int clear - Clear flag. Set 1 to clear settings before loading (new settings shall be applied right after loading them), or 0 not to clear.

Return value

1 if the sound settings are loaded successfully; otherwise, 0.

int engine.sound.loadWorld ( Xml xml ) #

Loads a sound state from the Xml. The sound state includes such settings as the volume, velocity, adaptation, Doppler factor, time scale and number of sound sources and their volumes.

Arguments

Xml xml - Xml node.

Return value

1 if the sound state is loaded successfully; otherwise, 0.

void engine.sound.renderWorld ( int force ) #

Forces update of the sound system: all sound changes (such as play() or stop() events and change of parameters) will be applied at once. The sound thread is updated at 30 FPS. Imagine, you have a sound sample playing and you want to update the time, from which the sample should be played. But playback won't stop immediately, so the a new time value won't be set. You need force updating of the sound thread after stopping it:

Source code (UnigineScript)

AmbientSource sound = new AmbientSource("ambient_sample.oga");;
// ...
// check if the sound sample is playing
if(sound.isPlaying()) {
	// stop playing the sample
	sound.stop();
	// force updating of the sound thread
	engine.sound.renderWorld(1);
	// update time
	sound.setTime(45.0f);
	// continue playing the sample 
	sound.play();
}

Arguments

int force - 1 to force update of the sound system; otherwise, 0.

int engine.sound.saveSettings ( string name, int force = 0 ) #

Saves the current sound settings to the given file.

Arguments

string name - Path to a sound settings file (*.sound).
int force - Force flag indcating if forced saving of sound settings is enabled.

Return value

1 if the sound settings are saved successfully; otherwise, 0.

int engine.sound.saveState ( Stream stream ) #

Saves a sound state into the stream. The sound state includes such settings as the volume, velocity, adaptation, Doppler factor, time scale and number of sound sources and their volumes.

Example using saveState() and restoreState() methods:

Source code (UnigineScript)

// create a sound source that plays a sample and set its state
source = new AmbientSource("ambient_source.oga",1);
source.setScale(0.75f);

// save state
Blob blob_state = new Blob();
source.saveState(blob_state);

// change state
source.setScale(1.25f);

// restore state
blob_state.seekSet(0); // returning the carriage to the start of the blob
source.restoreState(blob_state);

Arguments

Stream stream - Stream to save the state into.

Return value

1 if the sound state is saved successfully; otherwise, 0.

int engine.sound.restoreState ( Stream stream ) #

Restores a sound state from the stream. The sound state includes such settings as the volume, velocity, adaptation, Doppler factor, time scale and number of sound sources and their volumes.

Example using saveState() and restoreState() methods:

Source code (UnigineScript)

// create a sound source that plays a sample and set its state
source = new AmbientSource("ambient_source.oga",1);
source.setScale(0.75f);

// save state
Blob blob_state = new Blob();
source.saveState(blob_state);

// change state
source.setScale(1.25f);

// restore state
blob_state.seekSet(0); // returning the carriage to the start of the blob
source.restoreState(blob_state);

Arguments

Stream stream - Stream to restore the state from.

Return value

1 if the sound state is restored successfully; otherwise, 0.

int engine.sound.saveWorld ( Xml xml, int force = 0 ) #

Saves a sound state into the given Xml node. The sound state includes such settings as the volume, velocity, adaptation, Doppler factor, time scale and number of sound sources and their volumes.

Arguments

Xml xml - Xml node.
int force - Force flag indicating if forced saving of the sound state is enabled.

Return value

1 if the sound state is saved successfully; otherwise, 0.

Last update: 2022-03-10

Help improve this article

Was this article helpful?

Report a problem related to this article

(or select a word/phrase and press Ctrl+Enter)