addSound()
world.audio.addSound(eid, audio)
Description
Add sound to an entity.
Parameters
| Property | Type | Description |
|---|---|---|
| eid | Eid | The eid of the entity to add sound to. |
| audio | AudioSettings | Audio settings. |
AudioSettings
type AudioSettings = {url, volume, loop, pitch, paused, positional, refDistance, rolloffFactor, distanceModel, maxDistance}
| Property | Type | Default | Description |
|---|---|---|---|
| url | string | - | The source url. |
| volume (optional) | number | 1 | How loud the audio will be played. A value between 0 and 1. |
| loop (optional) | boolean | false | Whether the audio restarts after it finishes playing or not. |
| paused (optional) | boolean | false | Whether the audio is paused or currently playing. |
| pitch (optional) | number | 1 | The factor used to change the audio's pitch, with 1.0 being the audio's default, 2.0 being one octave higher, 0.5 one octave lower, etc. |
| positional (optional) | boolean | false | Whether the audio is positional (considers position relative to the listener) or not. |
| refDistance (optional) | number | 1 | Only applied if positional is true. The value indicating at what distance the volume from this source will start reducing as the listener moves away. Must be a non-negative value. |
| distanceModel (optional) | string | inverse | Only applied if positional is true. The algorithm used to reduce volume as the distance increases between this audio source and the listener. Possible values include linear, inverse, and exponential. |
| rolloffFactor (optional) | number | 1 | Only applied if positional is true. How quickly volume is reduced as distance increases between this audio source and the listener. The acceptable range of values changes depending on the distanceModel, shown by the following: linear: 0 to 1, inverse: 0 to Infinity, exponential: 0 to Infinity |
| maxDistance (optional) | number | 10000 | Only applied if positional is true and distanceModel equals linear. The max distance between this audio source and the listener. Volume is not reduced after this point. Must be a positive value. |
Returns
Returns a Sound object:
type Sound = {id, audioNode, element, controller, url, paused}
| Property | Type | Description |
|---|---|---|
| id | Eid | The eid of the sound. |
| audioNode | Audio / PositionalAudio | The three.js audio node. |
| element | HTMLAudioElement | The HTML audio element. |
| controller | AbortController | The audio AbortController. |
| url | string | The source url. |
| paused | boolean | Whether the audio is paused or currently playing. |