Audio

Description

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

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

Properties

Name Type Summary
muted boolean

true if the audio input is muted for the current user context (desktop or HMD), otherwise false.

mutedDesktop boolean

true if desktop audio input is muted, otherwise false.

mutedHMD boolean

true if the HMD input is muted, otherwise false.

warnWhenMuted boolean

true if the "muted" warning is enabled, otherwise false. When enabled, if you speak while your microphone is muted, "muted" is displayed on the screen as a warning.

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.

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.

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.

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.

pushToTalk boolean

true if push-to-talk is enabled for the current user context (desktop or HMD), otherwise false.

pushToTalkDesktop boolean

true if desktop push-to-talk is enabled, otherwise false.

pushToTalkHMD boolean

true if HMD push-to-talk is enabled, otherwise false.

pushingToTalk boolean

true if the user is currently pushing-to-talk, otherwise false.

avatarGain number

The gain (relative volume in dB) that avatars' voices are played at. This gain is used at the server.

localInjectorGain number

The gain (relative volume in dB) that local injectors (local environment sounds) are played at.

serverInjectorGain number

The gain (relative volume in dB) that server injectors (server environment sounds) are played at. This gain is used at the server.

systemInjectorGain number

The gain (relative volume in dB) that system sounds are played at.

pushingToTalkOutputGainDesktop number

The gain (relative volume in dB) that all sounds are played at when the user is holding the push-to-talk key in desktop mode.

acousticEchoCancellation boolean

true if acoustic echo cancellation is enabled, otherwise false. When enabled, sound from the audio output is suppressed when it echos back to the input audio signal.

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.

isSoloing boolean

true if currently audio soloing, i.e., playing audio from only specific avatars. Read-only.

soloList Array.<Uuid>

The list of currently soloed avatar IDs. Empty list if not currently audio soloing. Read-only.

Methods

Name Return Value Summary
addToSoloList None

Adds avatars to the audio solo list. If the audio solo list is not empty, only audio from the avatars in the list is played.

getAvatarGain number

Gets the gain (relative volume) that avatars' voices are played at. This gain is used at the server.

getInjectorGain number

Gets the gain (relative volume) that environment sounds from the server are played at.

getLocalEcho boolean

Gets whether your microphone audio is echoed back to you by the client. When enabled, microphone audio is echoed even if you're muted or not using push-to-talk.

getLocalInjectorGain number

Gets the gain (relative volume) that environment sounds from the client are played at.

getPushingToTalkOutputGainDesktop number

Gets the output volume gain that is used when the user is holding the push-to-talk key. Should be negative.

getRecording boolean

Checks whether an audio recording is currently being made.

getServerEcho boolean

Gets whether your microphone audio is echoed back to you from the server. When enabled, microphone audio is echoed only if you're unmuted or are using push-to-talk.

getSystemInjectorGain number

Gets the gain (relative volume) that system sounds are played at.

isStereoInput boolean

Gets whether the audio input is used in stereo.

onContextChanged None

Deprecated: This function is deprecated and will be removed.

playSound AudioInjector

Starts playing or "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

Starts 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

Removes avatars from the audio solo list. If the audio solo list is not empty, only audio from the avatars in the list is played.

resetSoloList None

Clears the audio solo list.

setAvatarGain None

Sets the gain (relative volume) that avatars' voices are played at. This gain is used at the server.

setInjectorGain None

Sets the gain (relative volume) that environment sounds from the server are played at.

setInputDevice None

Deprecated: This function is deprecated and will be removed.

setLocalEcho None

Sets whether your microphone audio is echoed back to you by the client. When enabled, microphone audio is echoed even if you're muted or not using push-to-talk.

setLocalInjectorGain None

Sets the gain (relative volume) that environment sounds from the client are played at.

setOutputDevice None

Deprecated: This function is deprecated and will be removed.

setPushingToTalkOutputGainDesktop None

Sets the output volume gain that will be used when the user is holding the push-to-talk key. Should be negative.

setReverb None

Enables or disables reverberation. Reverberation is done by the client on the post-mix audio. The reverberation options come from either the domain's audio zone configured on the server or settings scripted by setReverbOptions.

setReverbOptions None

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

setServerEcho None

Sets whether your microphone audio is echoed back to you from the server. When enabled, microphone audio is echoed only if you're unmuted or are using push-to-talk.

setStereoInput None

Sets whether the audio input should be used in stereo. If the audio input doesn't support stereo then setting a value of true has no effect.

setSystemInjectorGain None

Sets the gain (relative volume) that system sounds are played at.

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

Finishes making an audio recording started with startRecording.

toggleLocalEcho None

Toggles the echoing of microphone audio back to you by the client. When enabled, microphone audio is echoed even if you're muted or not using push-to-talk.

toggleServerEcho None

Toggles the echoing of microphone audio back to you from the server. When enabled, microphone audio is echoed only if you're unmuted or are using push-to-talk.

Signals

Name Summary
acousticEchoCancellationChanged

Triggered when acoustic echo cancellation is enabled or disabled.

avatarGainChanged

Triggered when the avatar gain changes.

clippingChanged

Triggered when the clipping state of the input audio changes.

contextChanged

Triggered when the current context of the audio changes.

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.

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.

localInjectorGainChanged

Triggered when the local injector gain changes.

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 for the current context (desktop or HMD).

mutedDesektopChanged

Triggered when desktop audio input is muted or unmuted.

mutedHMDChanged

Triggered when HMD 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 audio input noise reduction is enabled or disabled.

nop

Deprecated: This signal is deprecated and will be removed.

pushingToTalkChanged

Triggered when the user starts or stops push-to-talk.

pushingToTalkOutputGainDesktopChanged

Triggered when the push to talk gain changes.

pushToTalkChanged

Triggered when push-to-talk is enabled or disabled for the current context (desktop or HMD).

pushToTalkDesktopChanged

Triggered when push-to-talk is enabled or disabled for desktop mode.

pushToTalkHMDChanged

Triggered when push-to-talk is enabled or disabled for HMD mode.

receivedFirstPacket

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

serverInjectorGainChanged

Triggered when the server injector gain changes.

systemInjectorGainChanged

Triggered when the system injector gain changes.

warnWhenMutedChanged

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

Method Details

(static) addToSoloList( ids )

Adds avatars to the audio solo list. If the audio solo list is not empty, only audio from the avatars in the list is played.

Parameters

Name Type Description
ids Array.<Uuid>

Avatar IDs to add to the solo list.

Example

Listen to a single nearby avatar for a short while.

// Find nearby avatars.
var RANGE = 100; // m
var nearbyAvatars = AvatarList.getAvatarsInRange(MyAvatar.position, RANGE);

// Remove own avatar from list.
var myAvatarIndex = nearbyAvatars.indexOf(MyAvatar.sessionUUID);
if (myAvatarIndex !== -1) {
    nearbyAvatars.splice(myAvatarIndex, 1);
}

if (nearbyAvatars.length > 0) {
    // Listen to only one of the nearby avatars.
    var avatarName = AvatarList.getAvatar(nearbyAvatars[0]).displayName;
    print("Listening only to " + avatarName);
    Audio.addToSoloList([nearbyAvatars[0]]);

    // Stop listening to only the one avatar after a short while.
    Script.setTimeout(function () {
        print("Finished listening only to " + avatarName);
        Audio.resetSoloList();
    }, 10000); // 10s

} else {
    print("No nearby avatars");
}
(static) getAvatarGain( ) → {number}
Returns: The avatar gain (dB) at the server.

Gets the gain (relative volume) that avatars' voices are played at. This gain is used at the server.

Example

Report current audio gain settings.

// 0 value = normal volume; -ve value = quieter; +ve value = louder.
print("Avatar gain: " + Audio.getAvatarGain());
print("Environment server gain: " + Audio.getInjectorGain());
print("Environment local gain: " + Audio.getLocalInjectorGain());
print("System gain: " + Audio.getSystemInjectorGain());
(static) getInjectorGain( ) → {number}
Returns: The injector gain (dB) at the server.

Gets the gain (relative volume) that environment sounds from the server are played at.

(static) getLocalEcho( ) → {boolean}
Returns: true if echoing microphone audio back to you from the client is enabled, false if it isn't.

Gets whether your microphone audio is echoed back to you by the client. When enabled, microphone audio is echoed even if you're muted or not using push-to-talk.

(static) getLocalInjectorGain( ) → {number}
Returns: The injector gain (dB) in the client.

Gets the gain (relative volume) that environment sounds from the client are played at.

(static) getPushingToTalkOutputGainDesktop( ) → {number}
Returns: gain - The output volume gain (dB) while using push-to-talk.

Gets the output volume gain that is used when the user is holding the push-to-talk key. Should be negative.

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

Checks whether an audio recording is currently being made.

(static) getServerEcho( ) → {boolean}
Returns: true if echoing microphone audio back to you from the server is enabled, false if it isn't.

Gets whether your microphone audio is echoed back to you from the server. When enabled, microphone audio is echoed only if you're unmuted or are using push-to-talk.

(static) getSystemInjectorGain( ) → {number}
Returns: The injector gain (dB) in the client.

Gets the gain (relative volume) that system sounds are played at.

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

Gets whether 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 or "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>
{}

Configures where and how the audio injector plays the audio file.

Example

Play a sound.

var sound = SoundCache.getSound("http://hifi-content.s3.amazonaws.com/ken/samples/forest_ambiX.wav");

function playSound() {
    var injectorOptions = {
        position: MyAvatar.position
    };
    var injector = Audio.playSound(sound, injectorOptions);
}

function onSoundReady() {
    sound.ready.disconnect(onSoundReady);
    playSound();
}

if (sound.downloaded) {
    playSound();
} else {
    sound.ready.connect(onSoundReady);
}
(static) playSystemSound( sound ) → {AudioInjector}
Returns: The audio injector that plays the audio file.

Starts 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, which is loaded using SoundCache.getSound. See SoundObject for supported formats.

(static) removeFromSoloList( ids )

Removes avatars from the audio solo list. If the audio solo list is not empty, only audio from the avatars in the list is played.

Parameters

Name Type Description
ids Array.<Uuid>

Avatar IDs to remove from the solo list.

(static) resetSoloList( )

Clears the audio solo list.

(static) setAvatarGain( gain )

Sets the gain (relative volume) that avatars' voices are played at. This gain is used at the server.

Parameters

Name Type Description
gain number

The avatar gain (dB) at the server.

(static) setInjectorGain( gain )

Sets the gain (relative volume) that environment sounds from the server are played at.

Parameters

Name Type Description
gain number

The injector gain (dB) at the server.

(static) setInputDevice( device, isHMD )

Deprecated: This function is deprecated and will be removed.

Parameters

Name Type Description
device object

Device.

isHMD boolean

Is HMD.

(static) setLocalEcho( )

Sets whether your microphone audio is echoed back to you by the client. When enabled, microphone audio is echoed even if you're muted or not using push-to-talk.

Example

Echo local audio for a few seconds.

Audio.setLocalEcho(true);
Script.setTimeout(function () {
    Audio.setLocalEcho(false);
}, 3000); // 3s
(static) setLocalInjectorGain( gain )

Sets the gain (relative volume) that environment sounds from the client are played at.

Parameters

Name Type Description
gain number

The injector gain (dB) in the client.

(static) setOutputDevice( device, isHMD )

Deprecated: This function is deprecated and will be removed.

Parameters

Name Type Description
device object

Device.

isHMD boolean

Is HMD.

(static) setPushingToTalkOutputGainDesktop( gain )

Sets the output volume gain that will be used when the user is holding the push-to-talk key. Should be negative.

Parameters

Name Type Description
gain number

The output volume gain (dB) while using push-to-talk.

(static) setReverb( enable )

Enables or disables reverberation. Reverberation is done by the client on the post-mix audio. The reverberation options come from either the domain's audio zone configured on the server or settings 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 )

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

Parameters

Name Type Description
options AudioEffectOptions

The reverberation options.

(static) setServerEcho( serverEcho )

Sets whether your microphone audio is echoed back to you from the server. When enabled, microphone audio is echoed only if you're unmuted or are using push-to-talk.

Parameters

Name Type Description
serverEcho boolean

true to enable echoing microphone back to you from the server, false to disable.

(static) setStereoInput( stereo )

Sets whether the audio input should be used in stereo. If the audio input doesn't 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 gain (relative volume) that system sounds are played at.

Parameters

Name Type Description
gain number

The injector gain (dB) in the client.

(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( )

Finishes making an audio recording started with startRecording.

(static) toggleLocalEcho( )

Toggles the echoing of microphone audio back to you by the client. When enabled, microphone audio is echoed even if you're muted or not using push-to-talk.

(static) toggleServerEcho( )

Toggles the echoing of microphone audio back to you from the server. When enabled, microphone audio is echoed only if you're unmuted or are using push-to-talk.

Signal Details

acousticEchoCancellationChanged( isEnabled )
Returns: Signal

Triggered when acoustic echo cancellation is enabled or disabled.

Parameters

Name Type Description
isEnabled boolean

true if acoustic echo cancellation is enabled, otherwise false.

avatarGainChanged( gain )
Returns: Signal

Triggered when the avatar gain changes.

Parameters

Name Type Description
gain number

The new avatar gain value (dB).

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".

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.

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, while 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.

localInjectorGainChanged( gain )
Returns: Signal

Triggered when the local injector gain changes.

Parameters

Name Type Description
gain number

The new local injector gain value (dB).

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 for the current context (desktop or HMD).

Parameters

Name Type Description
isMuted boolean

true if the audio input is muted for the current context (desktop or HMD), otherwise false.

Example

Report when audio input is muted or unmuted

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

Triggered when desktop audio input is muted or unmuted.

Parameters

Name Type Description
isMuted boolean

true if desktop audio input is muted, otherwise false.

Example

Report when desktop muting changes.

Audio.mutedDesktopChanged.connect(function (isMuted) {
    print("Desktop muted: " + isMuted);
});
mutedHMDChanged( isMuted )
Returns: Signal

Triggered when HMD audio input is muted or unmuted.

Parameters

Name Type Description
isMuted boolean

true if HMD audio input is muted, otherwise false.

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 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

Deprecated: This signal is deprecated and will be removed.

pushingToTalkChanged( talking )
Returns: Signal

Triggered when the user starts or stops push-to-talk.

Parameters

Name Type Description
talking boolean

true if started push-to-talk, false if stopped push-to-talk.

pushingToTalkOutputGainDesktopChanged( gain )
Returns: Signal

Triggered when the push to talk gain changes.

Parameters

Name Type Description
gain number

The new output gain value (dB).

pushToTalkChanged( enabled )
Returns: Signal

Triggered when push-to-talk is enabled or disabled for the current context (desktop or HMD).

Parameters

Name Type Description
enabled boolean

true if push-to-talk is enabled, otherwise false.

Example

Report when push-to-talk changes.

Audio.pushToTalkChanged.connect(function (enabled) {
    print("Push to talk: " + (enabled ? "on" : "off"));
});
pushToTalkDesktopChanged( enabled )
Returns: Signal

Triggered when push-to-talk is enabled or disabled for desktop mode.

Parameters

Name Type Description
enabled boolean

true if push-to-talk is enabled for desktop mode, otherwise false.

pushToTalkHMDChanged( enabled )
Returns: Signal

Triggered when push-to-talk is enabled or disabled for HMD mode.

Parameters

Name Type Description
enabled boolean

true if push-to-talk is enabled for HMD mode, otherwise false.

receivedFirstPacket( )
Returns: Signal

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

serverInjectorGainChanged( gain )
Returns: Signal

Triggered when the server injector gain changes.

Parameters

Name Type Description
gain number

The new server injector gain value (dB).

systemInjectorGainChanged( gain )
Returns: Signal

Triggered when the system injector gain changes.

Parameters

Name Type Description
gain number

The new system injector gain value (dB).

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.