Passer au contenu principal

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.

AudioNewComponent

Audio Properties

Property NameTypeDefaultRequiredDescription
urlString-trueThe source url.
volumeNumber1falseHow loud the audio will be played. A value between 0 and 1
loopBooleanfalsefalseWhether the audio restarts after it finishes playing or not.
pausedBooleanfalsefalseWhether the audio is paused or currently playing.
pitchNumber1falseThe 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.
positionalBooleanfalsefalseWhether the audio is positional (considers position relative to the listener) or not.
refDistanceNumber1falseOnly 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.
distanceModelName of the distance model'inverse'falseOnly 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.
rolloffFactorNumber1falseOnly 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
maxDistanceNumber10000falseOnly 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,
})