Skip to content

i-audio-source.component overview

Table of contents

utils

AudioDistanceModel (type alias)

How a positional audio source's gain falls off with distance from the listener - the same three curves the Web Audio PannerNode itself offers, so packages/audio (and any future adapter built on the same primitive) can map this straight through. 'inverse''s slope is steepest close to refDistance, which is the main amplifier of otherwise-inaudible per-tick position jitter into an audible volume swing for a source sitting close to the listener (e.g. a chase-cammed vehicle's own engine), which is why IAudioSource3dComponent/ IAudioSource2dComponent default to 'linear' instead.

Signature

export type AudioDistanceModel = 'linear' | 'inverse' | 'exponential'

AudioSourceDescriptor (interface)

Settings for a new audio source, handed to IAudioSceneComponent['factory'].createSource. clip is whatever decoded/loadable representation the adapter's own factory produces from loadClip (e.g. a Web Audio AudioBuffer) - never a raw URL, so a level JSON's "Sound" class and the "PlaySound" blueprint node both resolve a clip via loadClip first.

Signature

export interface AudioSourceDescriptor<Clip = unknown> {
  clip: Clip
  loop?: boolean
  /**
   * Loop region, in seconds from the start of the clip - for a clip authored with a lead-in
   * before its seamless loop point (a common pattern for engine/ambience loops: play the intro
   * once, then loop only the sustain portion). Ignored when `loop` is `false`. `loopEnd` of `0`
   * (the default, matching `AudioBufferSourceNode.loopEnd`'s own default) means "the end of the
   * clip" rather than a literal zero-length loop.
   */
  loopStart?: number
  loopEnd?: number
  volume?: number
  playbackRate?: number
  /**
   * Positional (spatialized relative to the active listener) vs. flat/non-positional audio.
   * Defaults to `true`. Set `false` for ambient/music/UI sounds, or for a source whose distance
   * to the listener can't meaningfully change (e.g. the player's own chase-cammed vehicle, whose
   * engine sound sits at a roughly fixed distance/angle from the camera every frame) - turning
   * spatialization off avoids wasting a pan/distance calculation on a position delta that's
   * already near-zero, and sidesteps the jitter `AudioDistanceModel`'s doc describes for that same
   * scenario.
   */
  spatial?: boolean
  /**
   * Output bus/category name (e.g. `"sfx"`, `"music"`, `"ambient"`) - see
   * `IAudioSceneComponent.setBusVolume`. Defaults to `"sfx"`. Bus names don't need to be declared
   * up front; an unset bus behaves as if its volume were `1`.
   */
  bus?: string
  /** Whether to start playing immediately once created. Defaults to `true`. */
  autoplay?: boolean
}

IAudioSourceComponent (interface)

One audio-emitting component: a single sound instance, positioned in the world like a display object (IPositionable) and lifecycle-managed like any other world component (IWorldComponent). Wrapped by the dimension-specific AudioSource(2d|3d)Entity in app-facing code - see gg-engine-audio-adapter for the contract an adapter's own implementation must satisfy.

Signature

export interface IAudioSourceComponent<D, R, ATypeDoc extends AudioTypeDocRepo<D, R> = AudioTypeDocRepo<D, R>>
  extends IWorldComponent<D, R, GgWorldTypeDocAPatch<D, R, ATypeDoc>>,
    IPositionable<D, R> {
  loop: boolean
  /** See `AudioSourceDescriptor.loopStart`/`loopEnd` - same semantics, readable/writable at runtime. */
  loopStart: number
  loopEnd: number
  volume: number
  playbackRate: number
  spatial: boolean
  bus: string

  readonly isPlaying: boolean

  /**
   * Fires once when playback reaches the end of a non-looping clip (never fires for a looping
   * source, since it never ends on its own). What `AudioSource(2d|3d)Entity.playOneShot` and the
   * `"PlaySound"` blueprint node subscribe to in order to remove/dispose the transient source
   * once it's done.
   */
  readonly ended$: Observable<void>

  play(): void

  pause(): void

  stop(): void

  clone(): IAudioSourceComponent<D, R, ATypeDoc>
}