To setup a Sound, you ask the SoundCache for it first. This will return a Sound object.
var latinSound = SoundCache.getSound(HIFI_PUBLIC_BUCKET + "sounds/Lobby/latin.stereo.raw")
This either downloads the sound for you or grabs it from the cache. Note that because raw files do not include a header you have the option to name them as “.stereo.raw” to indicate that the file is stereo.
You can check if the Sound object has downloaded with the ‘downloaded’ property.
if (latinSound.downloaded)
Sounds that are not downloaded will not play anything if you call Audio.playSound with them.
To actually play the sound, you'll want to call Audio.playSound with the sound object.
var injector = Audio.playSound(latinSound);
This will inject the sound by sending it to the right audio-mixer (if you are connected to at least one).
There are various options you can pass to playSound as an object with name-value pairs.
var options = { loop: true, position: { x: 10, y: 20, z: 30 } }
var injector = Audio.playSound(options);
Here is a full list of the options you can pass to playSound.
- volume - value from 0.0 to 1.0 - default is 1.0
- position - object with x, y, z - default is { x: 0, y: 0, z: 0 }
- orientation - obect with x, y, z, w (quaternion) - default is { x: 0, y: 0, z: 0, w: 1 }
- loop - boolean, default is false
- stereo - boolean, default is false (can be ovveridden by WAV header or RAW filename)
- localOnly, boolean, default is false - injects audio locally without going through audio-mixer
- secondOffset, default is 0.0, number of seconds to offset into the sound when starting
- ignorePenumbra, boolean, default is false - don't subject this sound to the penumbra filter
Note that position, orientation and ignorePenumbra have no effect when localOnly is true. The local sounds are played without any spatialization.
The object returned from a call to playSound is an AudioInjector. While it is running you can change the options above via the property .options.
injector.options = { position: newPosition }
There are a number of methods you can call on the AudioInjector object to control the playback and get information about its current state.
injector.restart(); // stops and starts from beginning - very useful for repeated sounds
injector.stop() // stops playing immediately
injector.isPlaying(); // true if still playing
injector.getLoudness(); // returns a value from 0.0 to 1.0, the loudness in last frame
You can also connect to the finished signal of the AudioInjector object to know when it is done.
injector.finished.connect(function(){
// your injector is done playing
});