Skip to content

Audio Source ​

The AudioSystem plays sounds with the Web Audio API. It is not part of the EcsGame defaults, add it in onCreate:

ts
protected override onCreate() {
  this.world.addSystem(new AudioSystem())
}

Audio files are loaded like any other asset, content.load(AudioAssetType, '/audio/impact.ogg') resolves to an AudioBuffer, decoded with the audio context of the system. Create the system before loading audio.

  • An AudioSourceComponent plays its clip at the position of its entity. play() and stop() are requests that the system applies in its next render step. Changes to volume, playbackRate, loop and the distance settings apply to a playing sound.
  • A spatial source is attenuated and panned relative to the listener. refDistance, rolloffFactor, maxDistance and distanceModel control how the volume drops with distance. Turn spatial off for music or UI sounds.
  • autoplay starts the sound when the entity is activated. Deactivating the entity stops it.
  • The AudioListenerComponent marks the entity that hears, usually the camera. There is one listener per audio context, the system uses the first active one. In the example the listener is the blue square in the center, facing into the screen, so the orange emitter pans from ear to ear as it orbits.

Browsers keep audio suspended until the user interacts with the page. The system resumes it on the first click or key press, so click into the example to hear it.

Sounds that don't need an entity, like UI clicks or impacts, can be played with world.getSystem(AudioSystem).audio.playOneShot(buffer). The AudioDevice behind it doesn't depend on the ECS and can be used by plain games as well, see the breakout example.

ts
import {
  AudioAssetType,
  AudioListenerComponent,
  AudioSourceComponent,
  AudioSystem,
  CameraComponent,
  EcsGame,
  SpriteComponent,
  TransformComponent,
} from '@gglib/components'
import { GameEntity } from '@gglib/ecs'
import { PlatformId } from '@gglib/graphics'
import { vec3 } from '@gglib/math'
import { mount } from 'tweak-ui'

export default (canvas: HTMLCanvasElement, tools: HTMLElement, platform: PlatformId) => {
  const game = new Game({ canvas, platform })

  const panel = mount(tools, (ui) => {
    const source = game.source
    ui.group('Audio', (ui) => {
      ui.scalar(game, 'masterVolume', { label: 'Master volume', range: true, min: 0, max: 1, step: 0.01 })
    })
    ui.group('Source', (ui) => {
      ui.scalar(source, 'volume', { range: true, min: 0, max: 2, step: 0.01 })
      ui.scalar(source, 'playbackRate', { range: true, min: 0.25, max: 2, step: 0.01 })
      ui.scalar(source, 'refDistance', { range: true, min: 0.1, max: 10, step: 0.1 })
      ui.scalar(source, 'rolloffFactor', { range: true, min: 0, max: 5, step: 0.01 })
      ui.bool(source, 'spatial')
      ui.bool(source, 'loop')
      ui.bool(game, 'ping', { label: 'Ping' })
      ui.scalar(game, 'interval', { label: 'Ping interval', range: true, min: 0.1, max: 2, step: 0.05 })
      ui.button('Play', { onClick: () => game.playSound() })
      ui.button('Stop', { onClick: () => game.stopSound() })
    })
    ui.group('Orbit', (ui) => {
      ui.scalar(game, 'radius', { range: true, min: 0, max: 14, step: 0.1 })
      ui.scalar(game, 'speed', { range: true, min: -3, max: 3, step: 0.01 })
    })
  })

  game.run()
  return () => {
    game.destroy()
    panel.dispose()
  }
}

class Game extends EcsGame {
  public source = new AudioSourceComponent({ refDistance: 2, rolloffFactor: 1 })
  public masterVolume = 0.5
  public ping = true
  public interval = 0.6
  public radius = 8
  public speed = 1

  private clips: AudioBuffer[] = []
  private emitter!: GameEntity
  private angle = 0
  private nextPing = 0

  protected override onCreate(): void {
    // the audio system is opt-in
    this.world.addSystem(new AudioSystem())
  }

  public override onInitialize(): void {
    this.createCamera()
    // the listener sits in the center, facing into the screen
    this.createEntity({
      name: 'listener',
      parent: this.scene.entity,
      transform: new TransformComponent(),
      components: [new AudioListenerComponent(), new SpriteComponent({ width: 1.5, height: 1.5 }).setColor(0.3, 0.6, 1)],
    })
    this.emitter = this.createEntity({
      name: 'emitter',
      parent: this.scene.entity,
      transform: new TransformComponent({ position: vec3(this.radius, 0, 0) }),
      components: [this.source, new SpriteComponent({ width: 1, height: 1 }).setColor(1, 0.6, 0.2)],
    })
  }

  protected override async onLoadContent(): Promise<void> {
    // decoded with the audio context of the system
    this.clips = await Promise.all(
      [0, 1, 2, 3, 4].map((i) => this.content.load(AudioAssetType, `/audio/impact/impactGlass_medium_00${i}.ogg`)),
    )
  }

  private createCamera() {
    const entity = this.createEntity({
      name: 'camera',
      parent: this.scene.entity,
      transform: new TransformComponent({ position: vec3(0, 0, 10) }),
      components: [new CameraComponent({ type: 'orthographic', orthographicScale: 32, near: 0.1, far: 100 })],
    })
    this.scene.setCamera(0, entity.component(CameraComponent))
  }

  override onUpdate(time: number, dt: number): void {
    this.scene.getCamera<CameraComponent>(0).aspect = this.device.output.aspectRatio
    this.world.getSystem(AudioSystem).audio.volume = this.masterVolume

    this.angle += this.speed * dt
    const transform = this.emitter.getTransform<TransformComponent>()!
    transform.setPosition(Math.cos(this.angle) * this.radius, Math.sin(this.angle) * this.radius, 0)

    if (this.ping && this.clips.length && time >= this.nextPing) {
      this.nextPing = time + this.interval
      this.playRandomClip()
    }
  }

  public playSound() {
    this.playRandomClip()
  }

  public stopSound() {
    this.ping = false
    this.source.stop()
  }

  private playRandomClip() {
    if (this.clips.length) {
      this.source.setClip(this.clips[Math.floor(Math.random() * this.clips.length)]).play()
    }
  }
}

Released under the MIT License.