LittleJS Audio System
- Play audio files (mp3, ogg, wave) and generate sounds with ZzFX
- ZzFX sound generator integration: ZzFX
- Sound caching for fast playback and memory efficiency
- Volume control with attenuation and stereo panning
- 2D spatial audio based on camera position with distance-based falloff
- Sound instance management (pause, resume, stop)
- Speech synthesis for text-to-speech
- Music playback with ZzFXM support
- Web Audio API integration with master gain control
- Sounds and the master bus can route through effects, see the audio effects plugin
- Source
Classes
Members
(static) audioContext :AudioContext
Audio context used by the engine, undefined outside a browser, where the engine runs headless
- AudioContext
- Source
(static, constant) audioDefaultSampleRate
Default sample rate used for sounds
- Default Value
- 44100
- Source
(static) audioMasterGain :GainNode
Master gain node for all audio to pass through, made at load so effects can connect to it any time
- GainNode
- Source
Methods
(static) audioIsRunning() → {boolean}
Check if the audio context is running and available for playback
- Source
- True if the audio context is running, false when there is none
- Type:
- boolean
(static) createAudioBuffer(sampleChannels, sampleRateopt) → {AudioBuffer}
Copy arrays of samples into a new audio buffer
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
sampleChannels | Array | Array of arrays of samples (for stereo playback) | ||
sampleRate | number | <optional> | 44100 | Sample rate for the sound |
- Source
- The audio buffer holding the samples
- Type:
- AudioBuffer
(static) getNoteFrequency(semitoneOffset, rootFrequencyopt) → {number}
Get frequency of a note on a musical scale
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
semitoneOffset | number | How many semitones away from the root note | ||
rootFrequency | number | <optional> | 220 | Frequency at semitone offset 0 |
- Source
- The frequency of the note
- Type:
- number
(static) playAudioBuffer(buffer, volumeopt, rateopt, panopt, loopopt, gainNodeopt, offsetopt, onendedopt, outputopt, pannerNodeopt) → {AudioBufferSourceNode|undefined}
Play an audio buffer with given settings The buffer can be shared by any number of sounds playing at once
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
buffer | AudioBuffer | The audio buffer to play | ||
volume | number | <optional> | 1 | How much to scale volume by |
rate | number | <optional> | 1 | The playback rate to use |
pan | number | <optional> | 0 | How much to apply stereo panning |
loop | boolean | <optional> | false | True if the sound should loop when it reaches the end |
gainNode | GainNode | <optional> | Optional gain node for volume control while playing (disconnected when the sound ends) | |
offset | number | <optional> | 0 | Where to start in the sound, in its own seconds whatever the rate |
onended | AudioEndedCallback | <optional> | Callback for when the sound ends | |
output | AudioNode | | <optional> | Node or effect to connect the gain to instead of the master gain | |
pannerNode | StereoPannerNode | <optional> | Optional stereo panner for panning while playing, its pan already set (disconnected when the sound ends) |
- Source
- The source node of the sound played, undefined if play fails
- Type:
- AudioBufferSourceNode |
undefined
(static) playSamples(sampleChannels, volumeopt, rateopt, panopt, loopopt, sampleRateopt, gainNodeopt, offsetopt, onendedopt, outputopt, pannerNodeopt) → {AudioBufferSourceNode|undefined}
Play cached audio samples with given settings
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
sampleChannels | Array | Array of arrays of samples to play (for stereo playback) | ||
volume | number | <optional> | 1 | How much to scale volume by |
rate | number | <optional> | 1 | The playback rate to use |
pan | number | <optional> | 0 | How much to apply stereo panning |
loop | boolean | <optional> | false | True if the sound should loop when it reaches the end |
sampleRate | number | <optional> | 44100 | Sample rate for the sound |
gainNode | GainNode | <optional> | Optional gain node for volume control while playing (disconnected when the sound ends) | |
offset | number | <optional> | 0 | Where to start in the sound, in its own seconds whatever the rate |
onended | AudioEndedCallback | <optional> | Callback for when the sound ends | |
output | AudioNode | | <optional> | Node or effect to connect the gain to instead of the master gain | |
pannerNode | StereoPannerNode | <optional> | Optional stereo panner for panning while playing, its pan already set (disconnected when the sound ends) |
- Source
- The source node of the sound played, undefined if play fails
- Type:
- AudioBufferSourceNode |
undefined
(static) setAudioMasterEffect(inputopt, outputopt)
Route all sound through an effect between the master gain and the speakers
- Pass a node or an effect, or the first and last of a chain, each a node or an effect
- With one argument a node is both ends, and an effect uses its own input and output
- The output node is disconnected from everything else first, so it only feeds the speakers
- The two ends of a chain must already be connected to each other, like effectA.connect(effectB)
- Call with no arguments to remove the effect, an effect that was the master goes back to feeding the master gain
- Debug video capture records the end of the master chain, but loses its tap if the effect changes mid-capture
| Name | Type | Attributes | Description |
|---|---|---|---|
input | AudioNode | | <optional> | Node or effect the master gain connects to |
output | AudioNode | | <optional> | Node or effect that connects to the audio destination, defaults to the input's output |
- Source
(static) speak(text, volumeopt, rateopt, pitchopt, languageopt) → {SpeechSynthesisUtterance|undefined}
Speak text with passed in settings
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
text | string | The text to speak | ||
volume | number | <optional> | 1 | How much to scale volume by |
rate | number | <optional> | 1 | How quickly to speak |
pitch | number | <optional> | 1 | How much to change the pitch by |
language | string | <optional> | The language/accent to use (examples: en, it, ru, ja, zh) |
- Source
- The utterance that was spoken, or undefined if speech is unavailable
- Type:
- SpeechSynthesisUtterance |
undefined
(static) speakStop()
Stop all queued speech
- Source
(static) zzfx(…zzfxSound) → {AudioBufferSourceNode|undefined}
Generate and play a ZzFX sound
| Name | Type | Attributes | Description |
|---|---|---|---|
zzfxSound | Array | <repeatable> | Array of ZzFX parameters, ex. [.5,.5] |
- Source
- The audio node of the sound played, undefined if play fails
- Type:
- AudioBufferSourceNode |
undefined
(static) zzfxG(volumeopt, randomnessopt, frequencyopt, attackopt, sustainopt, releaseopt, shapeopt, shapeCurveopt, slideopt, deltaSlideopt, pitchJumpopt, pitchJumpTimeopt, repeatTimeopt, noiseopt, modulationopt, bitCrushopt, delayopt, sustainVolumeopt, decayopt, tremoloopt, filteropt) → {Array}
Generate samples for a ZzFX sound
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
volume | number | <optional> | 1 | Volume scale (percent) |
randomness | number | <optional> | 0.05 | How much to randomize frequency (percent Hz) |
frequency | number | <optional> | 220 | Frequency of sound (Hz) |
attack | number | <optional> | 0 | Attack time, how fast sound starts (seconds) |
sustain | number | <optional> | 0 | Sustain time, how long sound holds (seconds) |
release | number | <optional> | 0.1 | Release time, how fast sound fades out (seconds) |
shape | number | <optional> | 0 | Shape of the sound wave |
shapeCurve | number | <optional> | 1 | Squareness of wave (0=square, 1=normal, 2=pointy) |
slide | number | <optional> | 0 | How much to slide frequency (kHz/s) |
deltaSlide | number | <optional> | 0 | How much to change slide (kHz/s/s) |
pitchJump | number | <optional> | 0 | Frequency of pitch jump (Hz) |
pitchJumpTime | number | <optional> | 0 | Time of pitch jump (seconds) |
repeatTime | number | <optional> | 0 | Resets some parameters periodically (seconds) |
noise | number | <optional> | 0 | How much random noise to add (percent) |
modulation | number | <optional> | 0 | Frequency of modulation wave, negative flips phase (Hz) |
bitCrush | number | <optional> | 0 | Resamples at a lower frequency in (samples*100) |
delay | number | <optional> | 0 | Overlap sound with itself for reverb and flanger effects (seconds) |
sustainVolume | number | <optional> | 1 | Volume level for sustain (percent) |
decay | number | <optional> | 0 | Decay time, how long to reach sustain after attack (seconds) |
tremolo | number | <optional> | 0 | Trembling effect, rate controlled by repeat time (percent) |
filter | number | <optional> | 0 | Filter cutoff frequency, positive for HPF, negative for LPF (Hz) |
- Source
- Array of audio samples
- Type:
- Array
Type Definitions
AudioEffectNodes
Anything with input and output audio nodes, like an effect from the audio effects plugin
- Object
- Source
AudioEndedCallback(source)
| Name | Type | Description |
|---|---|---|
source | AudioBufferSourceNode |
- Source
SoundLoadCallback(sound)
| Name | Type | Description |
|---|---|---|
sound | Sound |
- Source