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 of audio file or zzfx array | |
randomness | number | <optional> | How much to randomize frequency each time sound plays, for zzfx sounds the zzfx default 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
Properties| Type | Description |
|---|---|
| SoundLoadCallback | function to call when sound is loaded |
- Source
randomness
Properties| 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
- AudioBuffer
| Type | Description |
|---|---|
| AudioBuffer | Decoded audio shared by every play of this sound |
- Source
sampleChannels :Array.<(Array.<number>|Float32Array)>
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.
- Array.<(Array.<number>|Float32Array)>
- 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}
Play the sound Sounds may not play until a user interaction occurs
| 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, or running in headless mode
- Type:
- SoundInstance
playMusic(volumeopt, loopopt, pausedopt) → {SoundInstance}
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
- Type:
- SoundInstance
playNote(semitoneOffsetopt, posopt, volumeopt) → {SoundInstance}
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
- Type:
- SoundInstance