lecodes-sdk 1.0.0 → 1.2.0

package/src/audio/audio.ts

@@ -1,161 +1,161 @@
-// The `audio` global (docs/audio-plan.md §2): 2D playback, one-shots at a world point, buses.
-// 3D playback from a node goes through the AudioSource aspect (gl/AudioSource.ts), which calls
-// back into `_play` here with its source id; the listener lives on `scene.audio`.
-//
-//   audio.play(click, { bus: 'ui' })
-//   audio.playAt(impact, hit.point, { maxDistance: 25 })
-//   audio.bus('sfx').reverb = 'cave'
-//   audio.stopAll(0.2)
-
-import { cx, cy, cz, type Vec3Like } from "../math/vec"
-import { Bus } from "./Bus"
-import type { Sound } from "./Sound"
-import { audioSupported } from "./support"
-import { Voice } from "./Voice"
-
-export type PlaySoundOptions = {
-  /** 0 … 1 (and above, at your own risk). Default 1. */
-  volume?: number
-  /** Playback rate, 1 = unchanged. Default 1. */
-  pitch?: number
-  loop?: boolean
-  /** Bus name; default: the source's bus, `sfx` for 2D. */
-  bus?: string
-  /** Higher survives voice stealing when the pool is full. Default 0. */
-  priority?: number
-  /** Fade-in seconds. Default 0. */
-  fade?: number
-  /** Seconds into the clip to start from. */
-  startAt?: number
-  /** 2D only: -1 left … 1 right. */
-  pan?: number
-}
-
-export type Rolloff = "none" | "inverse" | "linear" | "exponential"
-
-/** Distance model of an AudioSource / playAt. */
-export type SpatialOptions = {
-  /** Metres of full volume around the source. Default 1. */
-  minDistance?: number
-  /** Metres beyond which the source no longer gets quieter. Default 50. */
-  maxDistance?: number
-  /** How volume falls between the two: `inverse` (default, physical), `linear`, `exponential`, `none`. */
-  rolloff?: Rolloff
-}
-
-export const ROLLOFF: Record<Rolloff, number> = { none: 0, inverse: 1, linear: 2, exponential: 3 }
-
-/** @internal CAUD_SRC_* order. */
-export function sourceParams(o: { minDistance: number, maxDistance: number, rolloff: Rolloff, coneInner: number, coneOuter: number, coneOuterGain: number, doppler: number, spread: number, occlusion: boolean, bus: number }): Float32Array {
-  return new Float32Array([ o.minDistance, o.maxDistance, ROLLOFF[o.rolloff] ?? 1, o.coneInner, o.coneOuter, o.coneOuterGain, o.doppler, o.spread, o.occlusion ? 1 : 0, o.bus ])
-}
-
-export type AudioStats = {
-  voicesPlaying: number
-  voicesMono: number
-  voicesStereo: number
-  /** Voices displaced (or dropped) by a fuller pool since start. */
-  stolen: number
-  clips: number
-  clipBytes: number
-  /** Master peak since the previous read, linear (1 = full scale). */
-  peak: number
-  sampleRate: number
-  /** The reverb zone the listener is in (0 = none) and how far inside (0 … 1). */
-  listenerZone: number
-  zoneBlend: number
-  /** Voices rendered binaurally right now (see `audio.hrtf`). */
-  hrtfVoices: number
-}
-
-const DEFAULT_BUSES = [ "master", "sfx", "music", "ui", "voice" ]
-
-class AudioSystem {
-  private readonly _buses = new Map<string, Bus>()
-  private _hrtf = false
-  private _hrtfVoices = 16
-  private _timeScalePitch = false
-
-  /** True when this host mixes sound. Everything below is a silent no-op otherwise. */
-  get supported(): boolean { return audioSupported }
-
-  /** HRTF binaural rendering (MIT KEMAR filters on the CPU): sounds get a real up / down / behind in
-   *  HEADPHONES. Off by default — on speakers it only smears the image. Applies to the `hrtfVoices`
-   *  nearest 3D voices; the rest keep plain panning. */
-  get hrtf(): boolean { return this._hrtf }
-  set hrtf(v: boolean) { this._hrtf = v; if (audioSupported) _creatorAudio.setHrtf(v, this._hrtfVoices) }
-  /** `Time.scale` also pitches the sfx bus: slow motion drops every effect's tone, like a film. Default
-   *  false — a pause only mutes sfx, the menu click keeps its pitch. */
-  get timeScalePitch(): boolean { return this._timeScalePitch }
-  set timeScalePitch(v: boolean) { this._timeScalePitch = v; if (audioSupported) _creatorAudio.setTimeScalePitch(v) }
-  /** How many voices get the (CPU-heavier) binaural path. Default 16. */
-  get hrtfVoices(): number { return this._hrtfVoices }
-  set hrtfVoices(n: number) { this._hrtfVoices = n; if (audioSupported && this._hrtf) _creatorAudio.setHrtf(true, n) }
-
-  /** A bus by name — the five built-ins, or an app-defined one created on first use. */
-  bus(name: string): Bus {
-    let b = this._buses.get(name)
-    if (b) return b
-    let id = -1
-    if (audioSupported) {
-      id = _creatorAudio.busId(name)
-      if (id < 0 && !DEFAULT_BUSES.includes(name)) id = _creatorAudio.createBus(name)
-      if (id < 0) console.warn(`audio.bus('${name}'): no free bus slot (16 max)`)
-    }
-    b = new Bus(name, id)
-    this._buses.set(name, b)
-    return b
-  }
-  get master(): Bus { return this.bus("master") }
-
-  /** @internal the bus id for an options object (or -1 = the source's). */
-  _busId(name: string | undefined): number {
-    if (name === undefined) return -1
-    return this.bus(name)._id
-  }
-
-  /** 2D playback (UI, stingers, music one-shots). */
-  play(sound: Sound, options: PlaySoundOptions = {}): Voice {
-    return this._play(sound, 0, options)
-  }
-
-  /** A one-shot at a world position with its own transient source — impacts, ricochets, debris.
-   *  The source is freed when the voice ends. */
-  playAt(sound: Sound, position: Vec3Like, options: PlaySoundOptions & SpatialOptions = {}): Voice {
-    if (!audioSupported || !sound.ready) return new Voice(0, options.volume ?? 1, options.pitch ?? 1, 0)
-    const src = _creatorAudio.createSource()
-    _creatorAudio.setSourceParams(src, sourceParams({
-      minDistance: options.minDistance ?? 1, maxDistance: options.maxDistance ?? 50, rolloff: options.rolloff ?? "inverse",
-      coneInner: 360, coneOuter: 360, coneOuterGain: 1, doppler: 0, spread: 0, occlusion: false, bus: this._busId(options.bus ?? "sfx"),
-    }))
-    _creatorAudio.setSourcePosition(src, cx(position), cy(position), cz(position))
-    const v = this._play(sound, src, options)
-    if (v._tok === 0) { _creatorAudio.destroySource(src); return v }
-    v._ownSource = src
-    v._watch()
-    return v
-  }
-
-  /** @internal shared by play / playAt / AudioSource.play. */
-  _play(sound: Sound, sourceId: number, options: PlaySoundOptions): Voice {
-    const volume = options.volume ?? 1, pitch = options.pitch ?? 1, pan = options.pan ?? 0
-    if (!audioSupported || !sound.ready) return new Voice(0, volume, pitch, pan)
-    const clip = sound._pick()
-    if (clip === 0) return new Voice(0, volume, pitch, pan)
-    const tok = _creatorAudio.play(clip, sourceId, this._busId(options.bus), volume, pitch, !!options.loop,
-      options.priority ?? 0, options.fade ?? 0, options.startAt ?? 0, pan)
-    return new Voice(tok, volume, pitch, pan)
-  }
-
-  /** Stop every voice on every bus (fade in seconds). */
-  stopAll(fade = 0): void { if (audioSupported) _creatorAudio.stopAll(fade) }
-
-  /** Engine counters for a debug overlay or a perf log. */
-  get stats(): AudioStats {
-    const s = audioSupported ? _creatorAudio.stats() : new Float32Array(11)
-    return { voicesPlaying: s[0], voicesMono: s[1], voicesStereo: s[2], stolen: s[3], clips: s[4], clipBytes: s[5], peak: s[6], sampleRate: s[7], listenerZone: s[8], zoneBlend: s[9], hrtfVoices: s[10] ?? 0 }
-  }
-}
-
-export const audio = new AudioSystem()
-export type { AudioSystem }
+// The `audio` global (docs/audio-plan.md §2): 2D playback, one-shots at a world point, buses.
+// 3D playback from a node goes through the AudioSource aspect (gl/AudioSource.ts), which calls
+// back into `_play` here with its source id; the listener lives on `scene.audio`.
+//
+//   audio.play(click, { bus: 'ui' })
+//   audio.playAt(impact, hit.point, { maxDistance: 25 })
+//   audio.bus('sfx').reverb = 'cave'
+//   audio.stopAll(0.2)
+
+import { cx, cy, cz, type Vec3Like } from "../math/vec"
+import { Bus } from "./Bus"
+import type { Sound } from "./Sound"
+import { audioSupported } from "./support"
+import { Voice } from "./Voice"
+
+export type PlaySoundOptions = {
+  /** 0 … 1 (and above, at your own risk). Default 1. */
+  volume?: number
+  /** Playback rate, 1 = unchanged. Default 1. */
+  pitch?: number
+  loop?: boolean
+  /** Bus name; default: the source's bus, `sfx` for 2D. */
+  bus?: string
+  /** Higher survives voice stealing when the pool is full. Default 0. */
+  priority?: number
+  /** Fade-in seconds. Default 0. */
+  fade?: number
+  /** Seconds into the clip to start from. */
+  startAt?: number
+  /** 2D only: -1 left … 1 right. */
+  pan?: number
+}
+
+export type Rolloff = "none" | "inverse" | "linear" | "exponential"
+
+/** Distance model of an AudioSource / playAt. */
+export type SpatialOptions = {
+  /** Metres of full volume around the source. Default 1. */
+  minDistance?: number
+  /** Metres beyond which the source no longer gets quieter. Default 50. */
+  maxDistance?: number
+  /** How volume falls between the two: `inverse` (default, physical), `linear`, `exponential`, `none`. */
+  rolloff?: Rolloff
+}
+
+export const ROLLOFF: Record<Rolloff, number> = { none: 0, inverse: 1, linear: 2, exponential: 3 }
+
+/** @internal CAUD_SRC_* order. */
+export function sourceParams(o: { minDistance: number, maxDistance: number, rolloff: Rolloff, coneInner: number, coneOuter: number, coneOuterGain: number, doppler: number, spread: number, occlusion: boolean, bus: number }): Float32Array {
+  return new Float32Array([ o.minDistance, o.maxDistance, ROLLOFF[o.rolloff] ?? 1, o.coneInner, o.coneOuter, o.coneOuterGain, o.doppler, o.spread, o.occlusion ? 1 : 0, o.bus ])
+}
+
+export type AudioStats = {
+  voicesPlaying: number
+  voicesMono: number
+  voicesStereo: number
+  /** Voices displaced (or dropped) by a fuller pool since start. */
+  stolen: number
+  clips: number
+  clipBytes: number
+  /** Master peak since the previous read, linear (1 = full scale). */
+  peak: number
+  sampleRate: number
+  /** The reverb zone the listener is in (0 = none) and how far inside (0 … 1). */
+  listenerZone: number
+  zoneBlend: number
+  /** Voices rendered binaurally right now (see `audio.hrtf`). */
+  hrtfVoices: number
+}
+
+const DEFAULT_BUSES = [ "master", "sfx", "music", "ui", "voice" ]
+
+class AudioSystem {
+  private readonly _buses = new Map<string, Bus>()
+  private _hrtf = false
+  private _hrtfVoices = 16
+  private _timeScalePitch = false
+
+  /** True when this host mixes sound. Everything below is a silent no-op otherwise. */
+  get supported(): boolean { return audioSupported }
+
+  /** HRTF binaural rendering (MIT KEMAR filters on the CPU): sounds get a real up / down / behind in
+   *  HEADPHONES. Off by default — on speakers it only smears the image. Applies to the `hrtfVoices`
+   *  nearest 3D voices; the rest keep plain panning. */
+  get hrtf(): boolean { return this._hrtf }
+  set hrtf(v: boolean) { this._hrtf = v; if (audioSupported) _creatorAudio.setHrtf(v, this._hrtfVoices) }
+  /** `Time.scale` also pitches the sfx bus: slow motion drops every effect's tone, like a film. Default
+   *  false — a pause only mutes sfx, the menu click keeps its pitch. */
+  get timeScalePitch(): boolean { return this._timeScalePitch }
+  set timeScalePitch(v: boolean) { this._timeScalePitch = v; if (audioSupported) _creatorAudio.setTimeScalePitch(v) }
+  /** How many voices get the (CPU-heavier) binaural path. Default 16. */
+  get hrtfVoices(): number { return this._hrtfVoices }
+  set hrtfVoices(n: number) { this._hrtfVoices = n; if (audioSupported && this._hrtf) _creatorAudio.setHrtf(true, n) }
+
+  /** A bus by name — the five built-ins, or an app-defined one created on first use. */
+  bus(name: string): Bus {
+    let b = this._buses.get(name)
+    if (b) return b
+    let id = -1
+    if (audioSupported) {
+      id = _creatorAudio.busId(name)
+      if (id < 0 && !DEFAULT_BUSES.includes(name)) id = _creatorAudio.createBus(name)
+      if (id < 0) console.warn(`audio.bus('${name}'): no free bus slot (16 max)`)
+    }
+    b = new Bus(name, id)
+    this._buses.set(name, b)
+    return b
+  }
+  get master(): Bus { return this.bus("master") }
+
+  /** @internal the bus id for an options object (or -1 = the source's). */
+  _busId(name: string | undefined): number {
+    if (name === undefined) return -1
+    return this.bus(name)._id
+  }
+
+  /** 2D playback (UI, stingers, music one-shots). */
+  play(sound: Sound, options: PlaySoundOptions = {}): Voice {
+    return this._play(sound, 0, options)
+  }
+
+  /** A one-shot at a world position with its own transient source — impacts, ricochets, debris.
+   *  The source is freed when the voice ends. */
+  playAt(sound: Sound, position: Vec3Like, options: PlaySoundOptions & SpatialOptions = {}): Voice {
+    if (!audioSupported || !sound.ready) return new Voice(0, options.volume ?? 1, options.pitch ?? 1, 0)
+    const src = _creatorAudio.createSource()
+    _creatorAudio.setSourceParams(src, sourceParams({
+      minDistance: options.minDistance ?? 1, maxDistance: options.maxDistance ?? 50, rolloff: options.rolloff ?? "inverse",
+      coneInner: 360, coneOuter: 360, coneOuterGain: 1, doppler: 0, spread: 0, occlusion: false, bus: this._busId(options.bus ?? "sfx"),
+    }))
+    _creatorAudio.setSourcePosition(src, cx(position), cy(position), cz(position))
+    const v = this._play(sound, src, options)
+    if (v._tok === 0) { _creatorAudio.destroySource(src); return v }
+    v._ownSource = src
+    v._watch()
+    return v
+  }
+
+  /** @internal shared by play / playAt / AudioSource.play. */
+  _play(sound: Sound, sourceId: number, options: PlaySoundOptions): Voice {
+    const volume = options.volume ?? 1, pitch = options.pitch ?? 1, pan = options.pan ?? 0
+    if (!audioSupported || !sound.ready) return new Voice(0, volume, pitch, pan)
+    const clip = sound._pick()
+    if (clip === 0) return new Voice(0, volume, pitch, pan)
+    const tok = _creatorAudio.play(clip, sourceId, this._busId(options.bus), volume, pitch, !!options.loop,
+      options.priority ?? 0, options.fade ?? 0, options.startAt ?? 0, pan)
+    return new Voice(tok, volume, pitch, pan)
+  }
+
+  /** Stop every voice on every bus (fade in seconds). */
+  stopAll(fade = 0): void { if (audioSupported) _creatorAudio.stopAll(fade) }
+
+  /** Engine counters for a debug overlay or a perf log. */
+  get stats(): AudioStats {
+    const s = audioSupported ? _creatorAudio.stats() : new Float32Array(11)
+    return { voicesPlaying: s[0], voicesMono: s[1], voicesStereo: s[2], stolen: s[3], clips: s[4], clipBytes: s[5], peak: s[6], sampleRate: s[7], listenerZone: s[8], zoneBlend: s[9], hrtfVoices: s[10] ?? 0 }
+  }
+}
+
+export const audio = new AudioSystem()
+export type { AudioSystem }