v0.1.0

CHIP AUDIO
ENGINE

浏览器端芯片音频合成引擎

TypeScript + Web Audio API · Chiptune · 8-bit / 16-bit SFC

SCROLL

FEATURES

11 项核心特性，为浏览器游戏音频而生

总线树架构

master → music / sfx → ui / gameplay 层级混音，灵活控制每一层音量与效果

振荡器 + 采样

内置 OscillatorProvider 与 SampleProvider，支持合成器与采样双模式播放

Timbre Pack

将波形、包络、滤波器抽象为可复用音色包，BGM 创作即插即用

Score 乐谱

音名 + 时值 + 演奏表情的声明式 BGM 格式，代码即乐谱

演奏表情

layback / swing / humanize / velocityCurve 让机器演奏更自然

侧链闪避

BGM 播放时自动降低 sfx / ui 音量，智能避让关键音效

事件聚合

debounce / stack / arpeggio 策略防止高频事件导致声音爆炸

空间音频

2D 坐标映射为 pan、距离滤音与混响 send，身临其境的方位感

混响引擎

room / hall / plate 三种预设，程序化 IR 轻量短尾混响

焦点模式

viewport / follow / zone / legion 四种空间聚焦策略

Score 校验

validateScore() 在运行前捕获乐谱语法错误，提前排雷

QUICK START

三步上手，在浏览器中合成芯片音乐

1
安装
bash
# npm
npm install chip-audio-engine

# pnpm
pnpm add chip-audio-engine
2
初始化引擎
typescript
import { ChipAudioEngine } from 'chip-audio-engine';

const engine = new ChipAudioEngine();
engine.init();
3
播放音效
typescript
// 播放一个 UI 点击音效
engine.play('ui.click');

FULL EXAMPLE

Timbre Pack + Score 完整 BGM 创作流程

typescript
import { ChipAudioEngine } from 'chip-audio-engine';

const engine = new ChipAudioEngine();
engine.init();

// 1. 加载音色包
engine.loadTimbrePack({
  name: 'my-pack',
  timbres: {
    lead: {
      provider: 'oscillator',
      waveforms: [{ type: 'square', gain: 0.5, detune: -4 }],
      envelope: { attack: 5, decay: 30, sustain: 0.3, release: 60 },
    },
    bass: {
      provider: 'oscillator',
      waveforms: [{ type: 'triangle', gain: 0.6 }],
      envelope: { attack: 2, decay: 20, sustain: 0.5, release: 40 },
    },
  },
});

// 2. 加载乐谱
engine.loadScore({
  id: 'title',
  name: 'Title Theme',
  bpm: 120,
  timbrePack: 'my-pack',
  config: { loop: true },
  tracks: [
    {
      timbre: 'lead',
      notes: [
        { note: 'E5', duration: 'q' },
        { note: 'G5', duration: 'q' },
        { note: 'A5', duration: 'h' },
      ],
    },
    {
      timbre: 'bass',
      notes: [
        { note: 'A2', duration: 'w' },
        { note: 'E2', duration: 'w' },
      ],
    },
  ],
});

// 3. 播放 BGM
engine.playBGM('title', { fadeIn: 500 });

ARCHITECTURE

从乐谱到扬声器的音频信号流

INPUT
Score
RESOURCE
Timbre Pack
CORE
Engine
MIXER
AudioBus
OUTPUT
Speaker
ChannelPool
DuckManager
Aggregator
ReverbEngine
SpatialAudio

TIMBRE PACK

16bit-sfc 内置音色包一览 — 温润柔和的 SFC 风格音色

LEAD
squaresquarelowpass
A:5 D:30 S:0.3 R:60
BASS
trianglesquarelowpass
A:2 D:20 S:0.5 R:40
PAD
sinesinetrianglelowpass
A:80 D:100 S:0.6 R:200
ARP
squarelowpass
A:1 D:15 S:0 R:20
KICK
sinepitch drop
A:1 D:80 S:0 R:60
SNARE
noisetrianglehighpass
A:1 D:40 S:0 R:30
HIHAT
noisehighpass
A:0 D:10 S:0 R:5

LIVE DEMO

点击播放，聆听 Chip Audio Engine 合成的芯片音乐

Title Screen
BPM 130 · 5 Tracks · ~8s loop · 16bit-sfc
lead bass arp kick hihat
Ready
Hero's March
BPM 130 · 7 Tracks · ~2min · Epic Battle Theme
lead bass pad arp kick snare hihat
Ready

SCORE v2 DEMO

Hero's March (v2) — 章节结构、Pattern 复用、Velocity 曲线

Hero's March (v2)
BPM 130 · 7 Tracks · 5 Chapters · 36 Patterns · 16bit-sfc
Ready
v2 特性：
  • 小节网格对齐
  • Pattern 复用（36 个）
  • Velocity 曲线
  • Chapter 断点续写
  • 文件体积：48 KB（v1: 148 KB）

API OVERVIEW

主要类与模块一览

ChipAudioEngine引擎主入口
AudioBus音频总线
ChannelPool声道池
Aggregator事件聚合器
DuckManager闪避管理器
OscillatorProvider振荡器合成
SampleProvider采样播放
ReverbEngine混响引擎
SpatialAudio空间音频
BGMEngineBGM 引擎
TimbrePackLoader音色包加载器
MusicUtils音乐工具函数
FocusManager焦点模式
ScoreValidatorScore 校验
EventEmitter事件发射器
SoundPackLoader音效包加载器