AudioInjector

• Properties • Methods • Signals • Type Definitions • Method Details • Signal Details •

Description

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

Plays or "injects" the content of an audio file.

Create using Audio API methods.

Properties

Name Type Summary
playing boolean

true if the audio is currently playing, otherwise false. Read-only.
loudness number

The loudness in the last frame of audio, range 0.0 – 1.0. Read-only.
options AudioInjector.AudioInjectorOptions

Configures how the injector plays the audio.
Constructor
new AudioInjector( )

Methods

Name Return Value Summary
getLoudness number

Gets the loudness of the most recent frame of audio played.
getOptions AudioInjector.AudioInjectorOptions

Gets the current configuration of the audio injector.
isPlaying boolean

Gets whether or not the audio is currently playing.
restart None

Stops current playback, if any, and starts playing from the beginning.
setOptions None

Configures how the injector plays the audio. This will replace all current AudioInjectorOptions.
stop None

Stops audio playback.

Signals

Name Summary
finished

Triggered when the audio has finished playing.

Type Definitions

AudioInjectorOptions
Type: object

Configures where and how an audio injector plays its audio.

Properties

Name Type Summary
position Vec3

The position in the domain to play the sound.

Default Value: Vec3.ZERO

orientation Quat

The orientation in the domain to play the sound in.

Default Value: Quat.IDENTITY

volume number

Playback volume, between 0.0 and 1.0.

Default Value: 1.0

pitch number

Alter the pitch of the sound, within +/- 4 octaves. The value is the relative sample rate to resample the sound at, range 0.0625 – 16.0.
A value of 0.0625 lowers the pitch by 4 octaves.
A value of 1.0 means there is no change in pitch.
A value of 16.0 raises the pitch by 4 octaves.

Default Value: 1.0

loop boolean

If true, the sound is played repeatedly until playback is stopped.

Default Value: false

secondOffset number

Starts playback from a specified time (seconds) within the sound file, ≥ 0.

Default Value: 0

localOnly boolean

If true, the sound is played back locally on the client rather than to others via the audio mixer.

Default Value: false

ignorePenumbra boolean

Deprecated: This property is deprecated and will be removed.

Default Value: false

Method Details

(static) getLoudness( ) → {number}
Returns: The loudness of the most recent frame of audio played, range 0.0 – 1.0.

Gets the loudness of the most recent frame of audio played.
(static) getOptions( ) → {AudioInjector.AudioInjectorOptions}
Returns: Configuration of how the injector plays the audio.

Gets the current configuration of the audio injector.

Example

Prints injector options to log

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

Script.setTimeout(function () { // Give the sound time to load.
    injector = Audio.playSound(sound, injectorOptions);
}, 1000);

Script.setTimeout(function () {
    const options = injector.getOptions();

    print("Current AudioInjectorOptions: ",JSON.stringify(options)); // Print all options to log

    print("Volume is set to ", options.volume);
}, 2000);
(static) isPlaying( ) → {boolean}
Returns: true if the audio is currently playing, otherwise false.

Gets whether or not the audio is currently playing.

Example

See if a sound is playing.

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

Script.setTimeout(function () { // Give the sound time to load.
    injector = Audio.playSound(sound, injectorOptions);
}, 1000);

Script.setTimeout(function () {
    print("Sound is playing: " + injector.isPlaying());
}, 2000);
(static) restart( )

Stops current playback, if any, and starts playing from the beginning.
(static) setOptions( options )

Configures how the injector plays the audio. This will replace all current AudioInjectorOptions.

Parameters

Name Type Description
options AudioInjector.AudioInjectorOptions

Configuration of how the injector plays the audio.
Example

Reduce the volume of the sound without changing other existing options.

const sound = SoundCache.getSound(Script.resourcesPath() + "sounds/sample.wav");
let injector;
const injectorOptions = {
    position: MyAvatar.position,
    volume: 1.0,
};

Script.setTimeout(function () { // Give the sound time to load.
    injector = Audio.playSound(sound, injectorOptions);
}, 1000);

Script.setTimeout(function () {
    const options = injector.getOptions();
    options.volume = 0.2 // Reduce volume
    injector.setOptions(options); // replace existing options
}, 5000);
(static) stop( )

Stops audio playback.

Example

Stop playing a sound before it finishes.

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

Script.setTimeout(function () { // Give the sound time to load.
    injector = Audio.playSound(sound, injectorOptions);
}, 1000);

Script.setTimeout(function () {
    injector.stop();
}, 2000);

Signal Details

finished( )
Returns: Signal

Triggered when the audio has finished playing.

Example

Report when a sound has finished playing.

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

Script.setTimeout(function () { // Give the sound time to load.
    injector = Audio.playSound(sound, injectorOptions);
    injector.finished.connect(function () {
        print("Finished playing sound");
    });
}, 1000);