Audio

This section provides guidance for setting up audio. Studio currently supports the following audio file types:

• mp3
• m4a

Audio can be added to the entity via the Studio interface or in code. Adding them in Studio is done via the 'New Component' button. The Audio component features various play settings.

Audio Properties

Property Name	Type	Default	Required	Description
url	String	-	true	The source url.
volume	Number	1	false	How loud the audio will be played. A value between 0 and 1
loop	Boolean	false	false	Whether the audio restarts after it finishes playing or not.
paused	Boolean	false	false	Whether the audio is paused or currently playing.
pitch	Number	1	false	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	Boolean	false	false	Whether the audio is positional (considers position relative to the listener) or not.
refDistance	Number	1	false	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	Name of the distance model	'inverse'	false	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	Number	1	false	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	Number	10000	false	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.

Play audio

import {world} from '@8thwall/ecs'
world.audio.play()

Pause audio

import {world} from '@8thwall/ecs'
world.audio.pause()

Mute audio

import {world} from '@8thwall/ecs'
world.audio.mute()

Unmute audio

import {world} from '@8thwall/ecs'
world.audio.unmute()

Configure an audio source

import * as ecs from '@8thwall/ecs'
ecs.Audio.set(world, eid, {url: 'https://some.example/bg-music.mp3'})

Configure audio settings

import * as ecs from '@8thwall/ecs'
ecs.Audio.set(world, eid, {
  url: 'https://some.example/bg-music.mp3',
  volume: 0.8,
  loop: true,
  pitch: 2.0,
  paused: false,
})

Configure a positional audio source

import * as ecs from '@8thwall/ecs'
ecs.Audio.set(world, eid, {
  url: 'https://some.example/sound.m4a',
  positional: true
})

// custom settings
import * as ecs from '@8thwall/ecs'
ecs.Audio.set(world, eid, {
  url: 'https://some.example/sound.m4a',
  volume: 0.8,
  loop: true,
  positional: true,
  refDistance: 10,
  distanceModel: 'linear',
  rolloffFactor: 0.8,
  maxDistance: 20000,
})