Sound
- Last UpdatedOct 22, 2025
- 6 minute read
The Sound node is used to create and manipulate a 3D-positioned sounds. Currently AVEVA™ XR engine supports only .ogg files for sound.
Platform support
This node is fully supported on XR-Windows, XR-Portable Windows, XR-Portable iOS, XR-Portable Android, and XR-Portable WASM platforms.
|
XR-WIN |
XR-P-WIN |
XR-P-IOS |
XR-P-AND |
XR-P-WASM |
|---|---|---|---|---|
|
Full support |
Full support |
Full support |
Full support |
Full support |
|
|
|
|
|
|
Types of sound
There are three possible types of sounds: sound, music, and bank.
|
Sound type |
Description |
|---|---|
|
sound |
The sound is loaded in memory on application start. Only 256 sounds or music-type sounds are allowed. |
|
music |
The sound is read from a stream loaded on application start. Only 256 sounds or music-type sounds are allowed. |
|
bank |
The sound is loaded when started and added to the soundbank. A sound defined as bank cannot be played directly, but only through the soundbank. |
Note: When the sound is of bank type, the volume, loop and other attributes are directly handled by the Soundbank node.
Code example
This is a code example for the Sound node.
<Sound name="sound0" file="VOX_0_ToccaLaGoccia.ogg" type="sound" />
Position
The Sound node must be inside a context node, such as Context or Global.
AttenuationType
The attenuationType parameter can be used to define the spatial attenuation behavior of the sound.
Note: Attenuation works only for sound files of mono type (single channel). Stereo sounds can be used when the sound is not required to be spatial. In that case, we suggest setting the type to music.
There are three options.
|
Value |
Description |
|---|---|
|
none |
The sound is not attenuated. Regardless of the sound source position, the sound is always heard. |
|
distance |
The sound is heard at volume value when the distance from the source is less than distanceRayMin. The sound heard volume is decreased linearly from volume value to 0 between distanceRayMin and distanceRay. The sound cannot be heard if the distance from the sound source position is bigger then distanceRay. |
|
invdistance |
The sound is heard at volume value when the distance from the source is less than distanceRayMin. The sound heard volume is decreased using the inverse of the distance from volume value to 10% of volume value between distanceRayMin and distanceRay. The sound will still be heard, but will slowly decay when the value of source position is larger than distanceRay. |
LoopRange
Range loop can be used to modify the portion of the sound effect to be played in loop.
-
The first time the sound is played from 0 to the loopRange.y (loop range end point).
-
For all the other loops the sound is played from loopRange.xto loopRange.y (loop range start and end points).
-
If loop is set to false the last time the sound is executed, it is played from loopRange.x (loop range start point) to the end of the sound effect.
This enables you to design sound effects comprised of an intro part, a looped part, and an outro.
Volume and Gain
Volume and gain have different scopes.
|
Parameter |
Description |
|---|---|
|
volume |
Equalizes the sound according to all the other sounds. |
|
gain |
Changes the sound intensity. This may reflect on attenuation distances and heard volume. |
Using gain
Gain can be used to create effects based on the change of the intensity of the emitted sound.
For example, using a gain configured as volumeAndDistance for a running engine modifies sound intensity and attenuation distance, according to engine RPMs.
Depending on gainMode setting, the gain value can influence the following.
|
Value |
Description |
|---|---|
|
none |
None. |
|
volume |
The gain is used to multiply volume. |
|
distance |
The gain is used to multiply distanceRayMin and distanceRay. |
|
volumeAndDistance |
The gain multiplies both volume and attenuation distances. |
Sound fields
These are the fields for Sound node. Only the node-specific fields are indicated, not fields obtained by inheritance>
Field inheritance: NodeBase > Sound
|
Fields |
Type |
Use |
Default value |
Description |
|---|---|---|---|---|
|
attenuationType |
senum |
Optional |
None |
When set to none, the sound volume is not spatially attenuated. When set to distance, the volume decreases linearly inside the distanceRay. When set to invdistance, the sound is attenuated using the inverse of the distance from the sound source. |
|
autostart |
sbool |
Optional |
false |
When true, the Sound plays automatically when the application starts. |
|
currentTime |
sfloat |
Read only |
Not set |
Returns the time position of the sound. |
|
debug |
sbool |
Optional |
false |
Set to true to see sound position and attenuation sphere. |
|
distanceRay |
sfloat |
Optional |
1 |
Used when attenuationType is set to distance or invdistance. Defines the ray of the sphere inside which the attenuation takes place. |
|
distanceRayMin |
sfloat |
Optional |
0 |
Used when attenuationType is set to distance or invdistance. Defines the ray of the sphere inside which the attenuation takes place. |
|
dopplerScaler |
sfloat |
Optional |
1 |
Sets doppler intensity when attenuation is in effect. Must be within [0.0f, inf]. |
|
file |
sstring |
Optional |
Not set |
Sets the sound file name. |
|
gain |
sfloat |
Optional |
1 |
Multiplies heart volume and/or attenuation distances according to gainMode. |
|
gainMode |
senum |
Optional |
none |
Defines how the gain influence the volume. Available values are: none, volume, distance, volumeAndDistance. |
|
invDistanceAttenuation |
sfloat |
Optional |
5 |
Works only when attenuationType is InvDistance. Regulates how quickly the sound attenuates towards zero when outside of distanceRay. Must be within [0, 100] |
|
length |
sfloat |
Read only |
Not set |
Returns the length of the sound, in seconds. |
|
loop |
sbool |
Optional |
false |
When true, the sound loops. |
|
loopRange |
svec2 |
0 -1 |
Restricts the range of the sound. It works only if loop is enabled. The first parameter is the range starting point, the second the ending point. Both are expressed in seconds. If -1 is set as range ending point, the sound plays from the starting point to the end. |
|
|
pause |
sevent |
Optional |
Not set |
Pauses the sound play. |
|
pitch |
sfloat |
Optional |
1 |
Increases or decreases speed of sound so making it higher or lower. Can be used at runtime on a looped sound to arrange its tone according to a variable. This creates a sort of audio animation. |
|
position |
svec3 |
Optional |
Not set |
Sets the position of sound. |
|
set_currentTime |
sfloat |
Optional |
Not set |
Sets the currentTime from outside. |
|
start |
sevent |
Optional |
Not set |
Starts the sound play. |
|
stop |
sevent |
Optional |
Not set |
Stops the sound play. |
|
stop_out |
sevent |
Read only |
Not set |
Triggered when not looped sound reaches its end. |
|
type |
senum |
Optional |
Music |
Specifies type as sound, music, or bank, depending on the use.
|
|
volume |
sfloat |
Optional |
1 |
Sets the volume in the interval 0-1. |