Audio

Available in: Interface Scripts Client Entity Scripts Server Entity Scripts Assignment Client Scripts

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

Signals
nop

Properties:
Name Type Description
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.
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.

Methods

getRecording() → {boolean}
Check whether an audio recording is currently being made.
Returns:
true if an audio recording is currently being made, otherwise false.
Type: boolean
isStereoInput() → {boolean}
Get whether or not the audio input is used in stereo.
Returns:
true if the audio input is used in stereo, otherwise false.
Type: boolean
onContextChanged()
Deprecated:
This function is deprecated and will be removed.
playSound(sound, injectorOptionsopt) → {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.
Parameters:
Name Type Attributes Default 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.
Returns:
The audio injector that plays the audio file.
Type: AudioInjector
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);
playSystemSound(sound, position) → {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.
Parameters:
Name Type Description
sound SoundObject The content of an audio file, loaded using SoundCache.getSound. See SoundObject for supported formats.
position Vec3 The position in the domain to play the sound.
Returns:
The audio injector that plays the audio file.
Type: AudioInjector
setInputDevice(device, isHMD)
Parameters:
Name Type Description
device object
isHMD boolean
Deprecated:
This function is deprecated and will be removed.
setOutputDevice(device, isHMD)
Parameters:
Name Type Description
device object
isHMD boolean
Deprecated:
This function is deprecated and will be removed.
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);
setReverbOptions(options)
Configure reverberation options. Use setReverb to enable or disable reverberation.
Parameters:
Name Type Description
options AudioEffectOptions The reverberation options.
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.
startRecording(filename) → {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.
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.
Returns:
true if the specified file could be opened and audio recording has started, otherwise false.
Type: boolean
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);
}
stopRecording()
Finish making an audio recording started with startRecording.

Signals

contextChanged(context) → {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".
Returns:
Type: Signal
disconnected() → {Signal}
Triggered when the client is disconnected from the audio mixer.
Returns:
Type: Signal
environmentMuted() → {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.
Returns:
Type: Signal
inputLevelChanged(level) → {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).
Returns:
Type: Signal
inputReceived(inputSamples) → {Signal}
Triggered when a frame of audio input is processed.
Parameters:
Name Type Description
inputSamples Int16Array The audio input processed.
Returns:
Type: Signal
inputVolumeChanged(volume) → {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.
Returns:
Type: Signal
isStereoInputChanged(isStereo) → {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.
Returns:
Type: Signal
mutedByMixer() → {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.
Returns:
Type: Signal
mutedChanged(isMuted) → {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.
Returns:
Type: Signal
Example

Report when audio input is muted or unmuted

Audio.mutedChanged.connect(function (isMuted) {
  print("Audio muted: " + isMuted);
});
noiseGateClosed() → {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.
Returns:
Type: Signal
noiseGateOpened() → {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.
Returns:
Type: Signal
noiseReductionChanged(isEnabled) → {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.
Returns:
Type: Signal
nop() → {Signal}
Deprecated:
This signal is deprecated and will be removed.
Returns:
Type: Signal
receivedFirstPacket() → {Signal}
Triggered when the client receives its first packet from the audio mixer.
Returns:
Type: Signal