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 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) that avatars' voices are played at. This gain is used at the server.
localInjectorGain number The gain (relative volume) that local injectors (local environment sounds) are played at.
serverInjectorGain number The gain (relative volume) that server injectors (server environment sounds) are played at. This gain is used at the server.
systemInjectorGain number The gain (relative volume) that system sounds are played at.
pushingToTalkOutputGainDesktop number The gain (relative volume) that all sounds are played at when the user is holding the push-to-talk key in Desktop mode.
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
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 PTT.

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 PTT.
(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

avatarGainChanged( gain )
Returns: Signal

Triggered when the avatar gain changes.

Parameters

Name Type Description
gain number The new avatar gain value.
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.
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.
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.
systemInjectorGainChanged( gain )
Returns: Signal

Triggered when the system injector gain changes.

Parameters

Name Type Description
gain number The new system injector gain value.
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.