LittleJS 1.30.1

Audio

Sound

Sound Object - Stores a sound for later

  • this can be used to load and play wave, mp3, and ogg files
  • it can also create sounds using the ZzFX sound generator
  • can attenuate and apply stereo panning to sounds
  • sound instance control with pause/resume capability

Create sounds using the ZzFX Sound Designer.

Constructor

new Sound(asset, randomness, range, taper, onloadCallback)engineAudio.js:243

Create a sound object and cache the audio for later use

asset string|URL|Array<(number|undefined)> optional

Filename or URL of an audio file, or a zzfx array

randomness number optional

How much to randomize frequency each time sound plays, for zzfx sounds it overrides the array's own randomness, which is used if undefined

range number optional, default soundDefaultRange

World space max range of sound

taper number optional, default soundDefaultTaper

At what percentage of range should it start tapering

onloadCallback SoundLoadCallback optional

Called once the sound has loaded, or its file failed to, so a game counting its sounds goes on; isLoaded says which

// load an audio asset file
const music = new Sound('sound.mp3');

// create a zzfx sound
const blip = new Sound([.5,.5]);

// play a sound
blip.play();

Members

Methods

Members

loadedPercent : numberengineAudio.js:257

Percentage of this sound currently loaded, sounds fetched from a url stay at 0 until decoding completes

onloadCallback : SoundLoadCallback|undefinedengineAudio.js:298

function to call when sound is loaded

output : AudioNode|AudioEffectNodes|undefinedengineAudio.js:302

Node or effect to route every play of this sound through instead of the master gain

  • Where this sound's audio goes, unlike AudioEffect.output which is an effect's own node, effects chain with connect()
randomness : numberengineAudio.js:276

How much to randomize frequency each time sound plays

range : numberengineAudio.js:338

World space max range of sound, 0 for no limit; a range that is set is the sound's own, in 3D too

rangeIsDefault : booleanengineAudio.js:271

No range was given, so it got soundDefaultRange; played in 3D such a sound is heard to render3D.soundDefaultRange instead, which is further; setting range makes it false

sampleBuffer : AudioBuffer|undefinedengineAudio.js:291

Decoded audio shared by every play of this sound

sampleChannels : Array<(Array<number>|Float32Array)>|undefinedengineAudio.js:350

Sample data for each channel Sounds keep their samples in an audio buffer, so reading this rebuilds the arrays from it and caches them. The copies are safe to hold onto, playing a sound detaches the buffer's own channel arrays.

sampleLength : numberengineAudio.js:280

How many samples per channel this sound has

sampleRate : numberengineAudio.js:278

Sample rate for this sound

taper : numberengineAudio.js:273

At what percentage of range should it start tapering

Methods

buildSampleBuffer()engineAudio.js:374

Move this sound's samples into an audio buffer that every play can share Does nothing if there is already a buffer or no samples to build one from

getDuration() → numberengineAudio.js:484

Get how long this sound is in seconds

Returns
  • How long the sound is in seconds (0 if loading)
isLoaded() → booleanengineAudio.js:490

Check if sound is loaded, for sounds fetched from a url

Returns
  • True if sound is loaded and ready to play
loadSound(filename) → Promise<void>asyncengineAudio.js:495

Loads a sound from a URL and decodes it into sample data

filename string
play(pos, volume, pitch, randomnessScale, loop, paused) → SoundInstance|undefinedengineAudio.js:397

Play the sound

  • Browsers hold audio until the first user input, a sound played before it returns a paused instance that starts on its own once audio runs, unless paused or stopped first; a one shot that would have ended by then is dropped, and only the newest play of each sound waits, so a sound played every frame starts once
pos Vector2 optional

World space position to play the sound if any

volume number optional, default 1

How much to scale volume by

pitch number optional, default 1

How much to scale pitch by

randomnessScale number optional, default 1

How much to scale pitch randomness

loop boolean optional, default false

Should the sound loop?

paused boolean optional, default false

Should the sound start paused

Returns
  • The sound instance, or undefined if sound is disabled, not loaded, out of range, or running in headless mode
playLoop(pos, volume, pitch, randomnessScale, paused) → SoundInstance|undefinedengineAudio.js:455

Play the sound on a loop, the same as play with loop on; stop or change it through the SoundInstance returned

pos Vector2 optional

World space position to play the sound if any

volume number optional, default 1

How much to scale volume by

pitch number optional, default 1

How much to scale pitch by

randomnessScale number optional, default 1

How much to scale pitch randomness

paused boolean optional, default false

Should the sound start paused

Returns
  • The sound instance, or undefined if sound is disabled, not loaded, out of range, or running in headless mode
playMusic(volume, loop, paused) → SoundInstance|undefinedengineAudio.js:464

Play a music track that loops by default

volume number optional, default 1

Volume to play the music at

loop boolean optional, default true

Should the music loop?

paused boolean optional, default false

Should the music start paused

Returns
  • The sound instance, or undefined if sound is disabled, not loaded, or running in headless mode
playNote(semitoneOffset, pos, volume) → SoundInstance|undefinedengineAudio.js:474

Play the sound as a musical note with a semitone offset This can be used to play music with chromatic scales

semitoneOffset number optional, default 0

How many semitones to offset pitch

pos Vector2 optional

World space position to play the sound if any

volume number optional, default 1

How much to scale volume by

Returns
  • The sound instance, or undefined if sound is disabled, not loaded, out of range, or running in headless mode