Audio

Description

The Audio API provides facilities to interact with audio inputs and outputs and to play sounds.

Supported Script Types: Interface Scripts • Client Entity Scripts • Avatar Scripts • Server Entity Scripts • Assignment Client Scripts

Properties

Name Type Summary
muted boolean true if the audio input is muted, otherwise false.
noiseReduction boolean true if noise reduction is enabled, otherwise false. When enabled, the input audio signal is blocked (fully attenuated) when it falls below an adaptive threshold set just above the noise floor.
inputLevel number The loudness of the audio input, range 0.0 (no sound) – 1.0 (the onset of clipping). Read-only.
clipping boolean true if the audio input is clipping, otherwise false.
inputVolume number Adjusts the volume of the input audio; range 0.01.0. If set to a value, the resulting value depends on the input device: for example, the volume can't be changed on some devices, and others might only support values of 0.0 and 1.0.
isStereoInput boolean true if the input audio is being used in stereo, otherwise false. Some devices do not support stereo, in which case the value is always false.
context string The current context of the audio: either "Desktop" or "HMD". Read-only.
devices object Read-only. Deprecated: This property is deprecated and will be removed.
isSoloing boolean Read-only. true if any nodes are soloed.
soloList Array.<Uuid> Read-only. Get the list of currently soloed node UUIDs.

Methods

Name Return Value Summary
addToSoloList None Add nodes to the audio solo list
getAvatarGain number Gets the avatar gain at the server.
getInjectorGain number Gets the injector gain at the server.
getLocalEcho None
getLocalInjectorGain number Gets the local injector gain in the client.
getRecording boolean Check whether an audio recording is currently being made.
getServerEcho None
getSystemInjectorGain number Gets the injector gain for system sounds.
isStereoInput boolean Get whether or not the audio input is used in stereo.
onContextChanged None

Deprecated: This function is deprecated and will be removed.

playSound AudioInjector Starts playing — "injecting" — the content of an audio file. The sound is played globally (sent to the audio mixer) so that everyone hears it, unless the injectorOptions has localOnly set to true in which case only the client hears the sound played. No sound is played if sent to the audio mixer but the client is not connected to an audio mixer. The AudioInjector object returned by the function can be used to control the playback and get information about its current state.
playSystemSound AudioInjector Start playing the content of an audio file, locally (isn't sent to the audio mixer). This is the same as calling Audio.playSound with AudioInjector.AudioInjectorOptions localOnly set true and the specified position.
removeFromSoloList None Remove nodes from the audio solo list
resetSoloList None Reset the list of soloed nodes.
setAvatarGain None Sets the avatar gain at the server. Units are Decibels (dB)
setInjectorGain None Sets the injector gain at the server. Units are Decibels (dB)
setInputDevice None

Deprecated: This function is deprecated and will be removed.

setLocalEcho None
setLocalInjectorGain None Sets the local injector gain in the client. Units are Decibels (dB)
setOutputDevice None

Deprecated: This function is deprecated and will be removed.

setReverb None Enable or disable reverberation. Reverberation is done by the client, on the post-mix audio. The reverberation options come from either the domain's audio zone if used — configured on the server — or as scripted by setReverbOptions.
setReverbOptions None Configure reverberation options. Use setReverb to enable or disable reverberation.
setServerEcho None
setStereoInput None Set whether or not the audio input should be used in stereo. If the audio input does not support stereo then setting a value of true has no effect.
setSystemInjectorGain None Sets the injector gain for system sounds. Units are Decibels (dB)
startRecording boolean Starts making an audio recording of the audio being played in-world (i.e., not local-only audio) to a file in WAV format.
stopRecording None Finish making an audio recording started with startRecording.
toggleLocalEcho None
toggleServerEcho None

Signals

Name Summary
clippingChanged Triggered when the clipping state of the input audio changes.
contextChanged Triggered when the current context of the audio changes.
desktopMutedChanged Triggered when desktop audio input is muted or unmuted.
disconnected Triggered when the client is disconnected from the audio mixer.
environmentMuted Triggered when the client is muted by the mixer because they're within a certain radius (50m) of someone who requested the mute through Developer > Audio > Mute Environment.
hmdMutedChanged Triggered when HMD audio input is muted or unmuted.
inputLevelChanged Triggered when the input audio level changes.
inputReceived Triggered when a frame of audio input is processed.
inputVolumeChanged Triggered when the input audio volume changes.
isStereoInputChanged Triggered when the input audio use changes between mono and stereo.
mutedByMixer Triggered when the client is muted by the mixer because their loudness value for the noise background has reached the threshold set for the domain in the server settings.
mutedChanged Triggered when the audio input is muted or unmuted.
noiseGateClosed Triggered when the noise gate is closed: the input audio signal is blocked (fully attenuated) because it has fallen below an adaptive threshold set just above the noise floor. Only occurs if Audio.noiseReduction is true.
noiseGateOpened Triggered when the noise gate is opened: the input audio signal is no longer blocked (fully attenuated) because it has risen above an adaptive threshold set just above the noise floor. Only occurs if Audio.noiseReduction is true.
noiseReductionChanged Triggered when the audio input noise reduction is enabled or disabled.
nop

Deprecated: This signal is deprecated and will be removed.

pushingToTalkChanged Triggered when pushing to talk.
receivedFirstPacket Triggered when the client receives its first packet from the audio mixer.
warnWhenMutedChanged Triggered when "warn when muted" is enabled or disabled.

Method Details

(static) addToSoloList( uuidList )

Add nodes to the audio solo list

Parameters

Name Type Description
uuidList Array.<Uuid> List of node UUIDs to add to the solo list.
(static) getAvatarGain( ) → {number}
Returns: gain (in dB)

Gets the avatar gain at the server.

(static) getInjectorGain( ) → {number}
Returns: gain (in dB)

Gets the injector gain at the server.

(static) getLocalEcho( )

(static) getLocalInjectorGain( ) → {number}
Returns: gain (in dB)

Gets the local injector gain in the client.

(static) getRecording( ) → {boolean}
Returns: true if an audio recording is currently being made, otherwise false.

Check whether an audio recording is currently being made.

(static) getServerEcho( )

(static) getSystemInjectorGain( ) → {number}
Returns: gain (in dB)

Gets the injector gain for system sounds.

(static) isStereoInput( ) → {boolean}
Returns: true if the audio input is used in stereo, otherwise false.

Get whether or not the audio input is used in stereo.

(static) onContextChanged( )

Deprecated: This function is deprecated and will be removed.

(static) playSound( sound, injectorOptionsopt ) → {AudioInjector}
Returns: The audio injector that plays the audio file.

Starts playing — "injecting" — the content of an audio file. The sound is played globally (sent to the audio mixer) so that everyone hears it, unless the injectorOptions has localOnly set to true in which case only the client hears the sound played. No sound is played if sent to the audio mixer but the client is not connected to an audio mixer. The AudioInjector object returned by the function can be used to control the playback and get information about its current state.

Parameters

Name Type Attributes Default Value Description
sound SoundObject The content of an audio file, loaded using SoundCache.getSound. See SoundObject for supported formats.
injectorOptions AudioInjector.AudioInjectorOptions <optional>
{} Audio injector configuration.
Example

Play a sound.

var sound = SoundCache.getSound(Script.resourcesPath() + "sounds/sample.wav");
var injector;
var injectorOptions = {
    position: MyAvatar.position
};

Script.setTimeout(function () { // Give the sound time to load.
    injector = Audio.playSound(sound, injectorOptions);
}, 1000);
(static) playSystemSound( sound ) → {AudioInjector}
Returns: The audio injector that plays the audio file.

Start playing the content of an audio file, locally (isn't sent to the audio mixer). This is the same as calling Audio.playSound with AudioInjector.AudioInjectorOptions localOnly set true and the specified position.

Parameters

Name Type Description
sound SoundObject The content of an audio file, loaded using SoundCache.getSound. See SoundObject for supported formats.
(static) removeFromSoloList( uuidList )

Remove nodes from the audio solo list

Parameters

Name Type Description
uuidList Array.<Uuid> List of node UUIDs to remove from the solo list.
(static) resetSoloList( )

Reset the list of soloed nodes.

(static) setAvatarGain( gain )

Sets the avatar gain at the server. Units are Decibels (dB)

Parameters

Name Type Description
gain number (in dB)
(static) setInjectorGain( gain )

Sets the injector gain at the server. Units are Decibels (dB)

Parameters

Name Type Description
gain number (in dB)
(static) setInputDevice( device, isHMD )

Deprecated: This function is deprecated and will be removed.

Parameters

Name Type Description
device object
isHMD boolean
(static) setLocalEcho( )

(static) setLocalInjectorGain( gain )

Sets the local injector gain in the client. Units are Decibels (dB)

Parameters

Name Type Description
gain number (in dB)
(static) setOutputDevice( device, isHMD )

Deprecated: This function is deprecated and will be removed.

Parameters

Name Type Description
device object
isHMD boolean
(static) setReverb( enable )

Enable or disable reverberation. Reverberation is done by the client, on the post-mix audio. The reverberation options come from either the domain's audio zone if used — configured on the server — or as scripted by setReverbOptions.

Parameters

Name Type Description
enable boolean true to enable reverberation, false to disable.
Example

Enable reverberation for a short while.

var sound = SoundCache.getSound(Script.resourcesPath() + "sounds/sample.wav");
var injector;
var injectorOptions = {
    position: MyAvatar.position
};

Script.setTimeout(function () {
    print("Reverb OFF");
    Audio.setReverb(false);
    injector = Audio.playSound(sound, injectorOptions);
}, 1000);

Script.setTimeout(function () {
    var reverbOptions = new AudioEffectOptions();
    reverbOptions.roomSize = 100;
    Audio.setReverbOptions(reverbOptions);
    print("Reverb ON");
    Audio.setReverb(true);
}, 4000);

Script.setTimeout(function () {
    print("Reverb OFF");
    Audio.setReverb(false);
}, 8000);
(static) setReverbOptions( options )

Configure reverberation options. Use setReverb to enable or disable reverberation.

Parameters

Name Type Description
options AudioEffectOptions The reverberation options.
(static) setServerEcho( )

(static) setStereoInput( stereo )

Set whether or not the audio input should be used in stereo. If the audio input does not support stereo then setting a value of true has no effect.

Parameters

Name Type Description
stereo boolean true if the audio input should be used in stereo, otherwise false.
(static) setSystemInjectorGain( gain )

Sets the injector gain for system sounds. Units are Decibels (dB)

Parameters

Name Type Description
gain number (in dB)
(static) startRecording( filename ) → {boolean}
Returns: true if the specified file could be opened and audio recording has started, otherwise false.

Starts making an audio recording of the audio being played in-world (i.e., not local-only audio) to a file in WAV format.

Parameters

Name Type Description
filename string The path and name of the file to make the recording in. Should have a .wav extension. The file is overwritten if it already exists.
Example

Make a 10 second audio recording.

var filename = File.getTempDir() + "/audio.wav";
if (Audio.startRecording(filename)) {
    Script.setTimeout(function () {
        Audio.stopRecording();
        print("Audio recording made in: " + filename);
    }, 10000);

} else {
    print("Could not make an audio recording in: " + filename);
}
(static) stopRecording( )

Finish making an audio recording started with startRecording.

(static) toggleLocalEcho( )

(static) toggleServerEcho( )

Signal Details

clippingChanged( isClipping )
Returns: Signal

Triggered when the clipping state of the input audio changes.

Parameters

Name Type Description
isClipping boolean true if the audio input is clipping, otherwise false.
contextChanged( context )
Returns: Signal

Triggered when the current context of the audio changes.

Parameters

Name Type Description
context string The current context of the audio: either "Desktop" or "HMD".
desktopMutedChanged( isMuted )
Returns: Signal

Triggered when desktop audio input is muted or unmuted.

Parameters

Name Type Description
isMuted boolean true if the audio input is muted for desktop mode, otherwise false.
disconnected( )
Returns: Signal

Triggered when the client is disconnected from the audio mixer.

environmentMuted( )
Returns: Signal

Triggered when the client is muted by the mixer because they're within a certain radius (50m) of someone who requested the mute through Developer > Audio > Mute Environment.

hmdMutedChanged( isMuted )
Returns: Signal

Triggered when HMD audio input is muted or unmuted.

Parameters

Name Type Description
isMuted boolean true if the audio input is muted for HMD mode, otherwise false.
inputLevelChanged( level )
Returns: Signal

Triggered when the input audio level changes.

Parameters

Name Type Description
level number The loudness of the input audio, range 0.0 (no sound) – 1.0 (the onset of clipping).
inputReceived( inputSamples )
Returns: Signal

Triggered when a frame of audio input is processed.

Parameters

Name Type Description
inputSamples Int16Array The audio input processed.
inputVolumeChanged( volume )
Returns: Signal

Triggered when the input audio volume changes.

Parameters

Name Type Description
volume number The requested volume to be applied to the audio input, range 0.01.0. The resulting value of Audio.inputVolume depends on the capabilities of the device: for example, the volume can't be changed on some devices, and others might only support values of 0.0 and 1.0.
isStereoInputChanged( isStereo )
Returns: Signal

Triggered when the input audio use changes between mono and stereo.

Parameters

Name Type Description
isStereo boolean true if the input audio is stereo, otherwise false.
mutedByMixer( )
Returns: Signal

Triggered when the client is muted by the mixer because their loudness value for the noise background has reached the threshold set for the domain in the server settings.

mutedChanged( isMuted )
Returns: Signal

Triggered when the audio input is muted or unmuted.

Parameters

Name Type Description
isMuted boolean true if the audio input is muted, otherwise false.
Example

Report when audio input is muted or unmuted

Audio.mutedChanged.connect(function (isMuted) {
    print("Audio muted: " + isMuted);
});
noiseGateClosed( )
Returns: Signal

Triggered when the noise gate is closed: the input audio signal is blocked (fully attenuated) because it has fallen below an adaptive threshold set just above the noise floor. Only occurs if Audio.noiseReduction is true.

noiseGateOpened( )
Returns: Signal

Triggered when the noise gate is opened: the input audio signal is no longer blocked (fully attenuated) because it has risen above an adaptive threshold set just above the noise floor. Only occurs if Audio.noiseReduction is true.

noiseReductionChanged( isEnabled )
Returns: Signal

Triggered when the audio input noise reduction is enabled or disabled.

Parameters

Name Type Description
isEnabled boolean true if audio input noise reduction is enabled, otherwise false.
nop( )
Returns: Signal

 

pushingToTalkChanged( talking )
Returns: Signal

Triggered when pushing to talk.

Parameters

Name Type Description
talking boolean true if broadcasting with PTT, false otherwise.
receivedFirstPacket( )
Returns: Signal

Triggered when the client receives its first packet from the audio mixer.

warnWhenMutedChanged( isEnabled )
Returns: Signal

Triggered when "warn when muted" is enabled or disabled.

Parameters

Name Type Description
isEnabled boolean true if "warn when muted" is enabled, otherwise false.