title: sound type: components layout: docs parent_section: components source_code: src/components/sound.js
The sound component defines the entity as a source of sound or audio. The sound component is positional and is thus affected by the components-position.
NOTE: Playing sound on iOS — in any browser — requires a physical user interaction. This is a browser limitation, and internal A-Frame events (like fusing cursors) do not count as interaction. Ways to deal with this include using a Begin Experience button to start ambient music, or creating audio sprites with libraries like Howler.js.
<a-entity id="river" geometry="primitive: plane" material="color: blue" position="-10 0 0" sound="src: url(river.mp3); autoplay: true"></a-entity>
Property | Description | Default Value |
---|---|---|
autoplay | Whether to automatically play sound once set. | false |
distanceModel | linear , inverse , or exponential |
inverse |
loop | Whether to loop the sound once the sound finishes playing. | false |
maxDistance | Maximum distance between the audio source and the listener, after which the volume is not reduced any further. | 10000 |
on | An event for the entity to listen to before playing sound. | null |
poolSize | Numbers of simultaneous instances of this sound that can be playing at the same time | 1 |
positional | Whether or not the audio is positional (movable). | true |
refDistance | Reference distance for reducing volume as the audio source moves further from the listener. | 1 |
rolloffFactor | Describes how quickly the volume is reduced as the source moves away from the listener. | 1 |
src | Selector to an asset <audio> or url() -enclosed path to sound file. |
null |
volume | How loud to play the sound. | 1 |
Event Name | Description |
---|---|
pauseSound | Pause sound. |
playSound | Play sound. |
stopSound | Stop sound. |
Event Name | Description |
---|---|
sound-loaded | Triggered when sound file is loaded. Event detail will contain the sound's name and id . |
sound-ended | Triggered when sound finishes playing. Event detail will contain the sound's name and id . |
The sound
component can also listen to an event before playing as well. For example, we might have a laughing sound play every time we click a monster:
<a-entity cursor position="0 0 -5"></a-entity> <a-entity id="elmo" geometry="primitive: box" material="src: elmo.png" sound="src: url(ticklelaugh.mp3); on: click"></a-entity>
For performance, we recommend to block the scene on the sound asset to preload and cache. We can do so through the asset management system:
<a-scene> <a-assets> <audio id="river" src="river.mp3" preload="auto"></audio> </a-assets> <a-entity sound="src: #river"></a-entity> </a-scene>
To programmatically pause or resume a playing sound, we can tell the entity to pause or resume:
var entity = document.querySelector('[sound]'); entity.components.sound.stopSound();
Or to pause only the sound:
entity.components.sound.pauseSound();
And to play the sound:
entity.components.sound.playSound();