High-quality automatic BGM and sound effect composition engine with 4-channel chiptune synthesis
npm install algo-chipEnglish | ζ₯ζ¬θͺ
High-quality automatic BGM composition engine with 4-channel chiptune synthesis
https://github.com/user-attachments/assets/b0897d24-abd3-4d9a-932a-4a0d4280a1f3
- Motif-based composition: Pre-defined musical patterns with intelligent variation
- 4-channel chiptune synthesis: Classic 4-channel audio (2x square wave, triangle, noise)
- Deterministic generation: Seed-based RNG for reproducible results
- Dual distribution: npm package + standalone UMD bundle for CDN/ tag
``bash`
npm install algo-chip
Copy the AudioWorklets when using npm
1. Copy node_modules/algo-chip/packages/core/worklets into the directory that your bundler serves as static assets (for example public/worklets in Vite/Next.js or CRA). Automate this in your build step so upgrades stay in sync.workletBasePath
2. Set to the public path you copied to (e.g. workletBasePath: "/worklets/"). AlgoChipSynthesizer defaults to ./worklets/, and missing files will cause audioWorklet.addModule to throw at runtime.
`html`
Important: When using Web Audio playback (AlgoChipSynthesizer) via UMD, you need to specify where to load the AudioWorklet processors from.
Option 1: Use GitHub Pages CDN (Recommended)
`html`
Option 2: Self-host worklets
`html
`
`typescript
import { generateComposition } from "algo-chip";
const result = await generateComposition({
lengthInMeasures: 16,
seed: 12345,
twoAxisStyle: {
percussiveMelodic: -0.4, // Percussive-leaning
calmEnergetic: 0.5, // Energetic
},
});
// result.events - Playback event timeline
// result.meta - Generation metadata (BPM, key, etc.)
console.log(
Generated ${result.events.length} events at ${result.meta.bpm} BPM`
);
`typescript
import { SEGenerator } from "algo-chip";
const generator = new SEGenerator();
const se = generator.generateSE({
type: "jump",
seed: 42,
});
// se.events - SE event timeline
// se.meta - SE metadata
`
#### Available SE types
SEGenerator supports the following type strings out of the box (see se.md
for template details):
| Type | Description |
| --- | --- |
| jump | Light ascending jump sound |coin
| | Coin/collectible pickup |explosion
| | Short noise-heavy explosion |hit
| | Damage/impact accent |powerup
| | Power-up fanfare burst |select
| | UI/menu selection blip |laser
| | Retro shot/laser |click
| | Minimal percussive click |synth
| | Single-note synth accent |tone
| | Sustained square/triangle tone |
Use the table as a quick reference when wiring SE triggers; each entry maps to a
template family with deterministic parameter ranges.
The core package includes AlgoChipSynthesizer for Web Audio-based playback with volume control:
`typescript
import {
generateComposition,
SEGenerator,
AlgoChipSynthesizer,
} from "algo-chip";
// Initialize synthesizer
const audioContext = new AudioContext();
const synth = new AlgoChipSynthesizer(audioContext);
// Optional: specify custom worklet path
// const synth = new AlgoChipSynthesizer(audioContext, { workletBasePath: './custom-path/' });
await synth.init();
// Play BGM with volume control (looped playback returns immediately)
const bgm = await generateComposition({ seed: 123 });
synth.playLoop(bgm.events, {
volume: 0.8, // 80% volume (default: 1.0)
});
// Play SE with volume control
const seGenerator = new SEGenerator();
const jump = seGenerator.generateSE({ type: "jump" });
await synth.play(jump.events, {
volume: 0.5, // 50% volume (default: 1.0)
});
`
Volume option:
- Default: 1.0 (base gain = 0.7)0.0+
- Range: (e.g., 0.5 = 50%, 1.5 = 150%)
- Applied at playback time, not generation time
Note: AlgoChipSynthesizer requires a browser environment (Web Audio API).playLoop()
Call for background loops (do not await) and await play() for
finite renders or sound effects.
Advanced SE playback patterns (ducking, quantization, controller wiring) are
documented in USAGE.md alongside pointers into the demo helpers.
When you need session management (auto-looped BGM, SE ducking/quantization,
visibility pause, etc.) import the util helpers directly from algo-chip.algo-chip/util
You can also target the subpath if you prefer an explicit
entry point for bundlers.
ESM / npm
`typescript
import {
createAudioSession,
createVisibilityController,
} from "algo-chip";
const session = createAudioSession({
workletBasePath: "./worklets/",
});
await session.resumeAudioContext();
const bgm = await session.generateBgm({ seed: 9001 });
await session.playBgm(bgm, { loop: true });
const detachVisibility = createVisibilityController(session);
// Later: detachVisibility(); await session.close();
`
CDN / UMD
Both the core engine and util helpers ship prebuilt bundles on GitHub Pages:
`html`
See USAGE.md for deeper API coverage (SE ducking, quantization,
default overrides, timeline inspection, etc.).
`bash`
npm install
`bash`
npm run build # Build all packages
npm run build:core # Build core library only
npm run build:demo # Build demo app only
npm run build:pages # Build and deploy to docs/ (GitHub Pages)
`bash`
npm run dev # Start demo dev server (http://localhost:5173)
npm run preview # Preview production build
``
algo-chip/
βββ packages/
β βββ core/ # Core workspace (exports re-used by npm "algo-chip")
β β βββ src/ # TypeScript source (5-phase pipeline)
β β βββ motifs/ # Motif JSON libraries (chords, melody, rhythm, etc.)
β β βββ dist/ # Build output
β β βββ index.js # ESM bundle
β β βββ index.d.ts # TypeScript definitions
β β βββ algo-chip.umd.js # UMD bundle
β βββ util/ # Util workspace (AudioSession helpers re-exported via root)
β β βββ src/ # Session orchestration, ducking, quantization
β β βββ dist/
β β βββ index.js # ESM bundle
β β βββ algo-chip-util.umd.js
β βββ demo/ # Demo web application
β βββ src/ # Demo UI code (Web Audio playback)
β βββ index.html # Main demo page
β βββ dist/ # Demo build output
βββ docs/ # GitHub Pages artifacts (auto-generated)
βββ index.html # Demo page (from packages/demo/dist)
βββ assets/ # Vite build output (from packages/demo/dist)
βββ lib/ # UMD bundles (copied from packages/*/dist)
β βββ algo-chip.umd.js
β βββ algo-chip-util.umd.js
βββ worklets/ # Web Audio Worklet processors (from packages/demo/dist)
The composition engine follows a five-phase pipeline:
1. Structure Planning - BPM, key, sections, chord progressions
2. Motif Selection - Rhythm, melody, bass, drum pattern assignment
3. Event Realization - Convert abstract motifs to concrete note events
4. Techniques - Apply echo, detune, arpeggios
5. Timeline Finalization - Sort events, convert beatβtime, generate diagnostics
- score.md (ζ₯ζ¬θͺ) - Production specification (primary reference)se.md
- (ζ₯ζ¬θͺ) - Sound effect generation specificationAGENTS.md
- - Development guidelines and coding conventionsdocs/
- - GitHub Pages deployment target (kept in sync via npm run build:pages`)
- Live Demo
- API Docs
- UMD Bundle
- Util UMD Bundle
- algo-chip on npm