aiaudiojs — 音效系統

import { Aside } from ‘@astrojs/starlight/components’;

aiaudiojs 是包在 Howler.js 外層的薄 shell，補足 ai*js 家族的生命週期約束：dispose() 冪等、AbortSignal 全路徑支援、first-class crossfade()。Howler 本身以 peerDependency 存在，保持可升級。

安裝

pnpm add aiaudiojs howler

快速開始

import { createAudio } from "aiaudiojs";

const audio = createAudio({
  autoUnlock: true,         // 綁定第一個 user gesture 解鎖 AudioContext（預設開啟）
  resumeOnVisibility: true, // iOS Safari 背景切回時 best-effort 恢復
});

// 1. 載入音效（回傳 Promise<Sound>）
const zap  = await audio.load("zap.mp3");
const bgm1 = await audio.load("level1.mp3");
const bgm2 = await audio.load("level2.mp3");

// 2. 播放
zap.play({ volume: 0.8 });
bgm1.play({ loop: true });

// 3. 場景切換時平滑 crossfade
await audio.crossfade(bgm1, bgm2, { duration: 2 });

// 4. 需要進階功能：直接取 Howler 原生 Howl 物件
const howl = zap.nativeHowl;

// 5. 清理
audio.disposeAll(); // 銷毀此 audio 實例建立的所有 sound

主要 API

API	說明
`audio.load(url, signal?)`	載入音效，回傳 `Promise<Sound>`
`sound.play(opts?)`	播放，`opts` 可帶 `loop`、`volume`、`signal`
`sound.pause()`	暫停
`sound.stop()`	停止並回到開頭
`sound.fade(from, to, duration)`	音量漸變
`audio.crossfade(a, b, opts)`	兩個 sound 之間 crossfade
`sound.dispose()`	銷毀這個 sound（冪等）
`audio.disposeAll()`	銷毀所有 sound
`sound.nativeHowl`	取得底層 Howl 物件（escape hatch）

Crossfade 模式

// 預設：linear curve，透過 Howl.fade() 實作
await audio.crossfade(bgm1, bgm2, { duration: 2 });

// Equal-power curve：sin/cos 曲線，感知音量更平均
// 在 AudioContext timeline 上排程，支援 AbortSignal 中途取消
await audio.crossfade(bgm1, bgm2, {
  duration: 2,
  curve: "equal-power",
  signal: ctrl.signal,
});

刻意排除的功能

aiaudiojs 不包含合成器（synth）、MIDI、audio worklet、3D spatial audio（用 Howler 的 spatial plugin）、音效 sprite 生成（用 audiosprite CLI）。保持輕量是設計原則，不是遺漏。

常見搭配

與 aifsmjs 搭配：FSM 場景切換時 trigger crossfade，FSM entry/exit 觸發音效 play/stop
與 aieventjs 搭配：遊戲事件（玩家死亡、擦彈）觸發音效播放
獨立使用：互動網頁、展示頁的背景音樂管理