Constructor
new Sound(assetopt, randomnessopt, rangeopt, taperopt, onloadCallbackopt)
Create a sound object and cache the audio for later use
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
asset | string | | <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> | soundDefaultRange | World space max range of sound |
taper | number | <optional> | soundDefaultTaper | At what percentage of range should it start tapering |
onloadCallback | SoundLoadCallback | <optional> | callback function to call when sound is loaded |
- Source
// load an audio asset file
const sound_example = new Sound('sound.mp3');
// create a zzfx sound
const sound_example = new Sound([.5,.5]);
// play a sound
sound_example.play();Members
loadedPercent
Properties| Type | Description |
|---|---|
| number | Percentage of this sound currently loaded, sounds fetched from a url stay at 0 until decoding completes |
- Source
onloadCallback :SoundLoadCallback|undefined
- SoundLoadCallback |
undefined
| Type | Description |
|---|---|
| SoundLoadCallback | | function to call when sound is loaded |
- Source
output :AudioNode|AudioEffectNodes|undefined
- AudioNode |
AudioEffectNodes | undefined
| Type | Description |
|---|---|
| AudioNode | | Node or effect to route every play of this sound through instead of the master gain
|
- Source
randomness :number
- number
| Type | Description |
|---|---|
| number | How much to randomize frequency each time sound plays |
- Source
range
Properties| Type | Description |
|---|---|
| number | World space max range of sound |
- Source
sampleBuffer :AudioBuffer|undefined
- AudioBuffer |
undefined
| Type | Description |
|---|---|
| AudioBuffer | | Decoded audio shared by every play of this sound |
- Source
sampleChannels
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.
- Source
sampleChannels
- Source
sampleLength
Properties| Type | Description |
|---|---|
| number | How many samples per channel this sound has |
- Source
sampleRate
Properties| Type | Description |
|---|---|
| number | Sample rate for this sound |
- Source
taper
Properties| Type | Description |
|---|---|
| number | At what percentage of range should it start tapering |
- Source
Methods
buildSampleBuffer()
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
- Source
getDuration() → {number}
Get how long this sound is in seconds
- Source
- How long the sound is in seconds (0 if loading)
- Type:
- number
isLoaded() → {boolean}
Check if sound is loaded, for sounds fetched from a url
- Source
- True if sound is loaded and ready to play
- Type:
- boolean
(async) loadSound(filename) → {Promise}
Loads a sound from a URL and decodes it into sample data.
| Name | Type | Description |
|---|---|---|
filename | string |
- Source
- Type:
- Promise
play(posopt, volumeopt, pitchopt, randomnessScaleopt, loopopt, pausedopt) → {SoundInstance|undefined}
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
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
pos | Vector2 | <optional> | World space position to play the sound if any | |
volume | number | <optional> | 1 | How much to scale volume by |
pitch | number | <optional> | 1 | How much to scale pitch by |
randomnessScale | number | <optional> | 1 | How much to scale pitch randomness |
loop | boolean | <optional> | false | Should the sound loop? |
paused | boolean | <optional> | false | Should the sound start paused |
- Source
- The sound instance, or undefined if sound is disabled, not loaded, out of range, or running in headless mode
- Type:
- SoundInstance |
undefined
playLoop(posopt, volumeopt, pitchopt, randomnessScaleopt, pausedopt) → {SoundInstance|undefined}
Play the sound on a loop, the same as play with loop on; stop or change it through the SoundInstance returned
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
pos | Vector2 | <optional> | World space position to play the sound if any | |
volume | number | <optional> | 1 | How much to scale volume by |
pitch | number | <optional> | 1 | How much to scale pitch by |
randomnessScale | number | <optional> | 1 | How much to scale pitch randomness |
paused | boolean | <optional> | false | Should the sound start paused |
- Source
- The sound instance, or undefined if sound is disabled, not loaded, out of range, or running in headless mode
- Type:
- SoundInstance |
undefined
playMusic(volumeopt, loopopt, pausedopt) → {SoundInstance|undefined}
Play a music track that loops by default
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
volume | number | <optional> | 1 | Volume to play the music at |
loop | boolean | <optional> | true | Should the music loop? |
paused | boolean | <optional> | false | Should the music start paused |
- Source
- The sound instance, or undefined if sound is disabled, not loaded, or running in headless mode
- Type:
- SoundInstance |
undefined
playNote(semitoneOffsetopt, posopt, volumeopt) → {SoundInstance|undefined}
Play the sound as a musical note with a semitone offset This can be used to play music with chromatic scales
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
semitoneOffset | number | <optional> | 0 | How many semitones to offset pitch |
pos | Vector2 | <optional> | World space position to play the sound if any | |
volume | number | <optional> | 1 | How much to scale volume by |
- Source
- The sound instance, or undefined if sound is disabled, not loaded, out of range, or running in headless mode
- Type:
- SoundInstance |
undefined