algo-chip (Demo)

English | 日本語

High-quality automatic BGM composition engine with 4-channel chiptune synthesis

https://github.com/user-attachments/assets/b0897d24-abd3-4d9a-932a-4a0d4280a1f3

🎵 Features

- 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/

`

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






`

🚀 Usage

$3

`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
);
`

$3

`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.

$3

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)
- Range: 0.0+ (e.g., 0.5 = 50%, 1.5 = 150%)
- Applied at playback time, not generation time

Note: AlgoChipSynthesizer requires a browser environment (Web Audio API).
Call playLoop() 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.

$3

When you need session management (auto-looped BGM, SE ducking/quantization,
visibility pause, etc.) import the util helpers directly from algo-chip.
You can also target the subpath algo-chip/util 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.).

🛠️ Development

$3

`bash
npm install
`

$3

`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)
`

$3

`bash
npm run dev # Start demo dev server (http://localhost:5173)
npm run preview # Preview production build
`

📁 Project Structure

`
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)
`

🎼 Pipeline Architecture

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

📖 Documentation

- score.md (日本語) - Production specification (primary reference)
- se.md (日本語) - Sound effect generation specification
- AGENTS.md - Development guidelines and coding conventions
- docs/ - GitHub Pages deployment target (kept in sync via npm run build:pages`)

🔗 Links

- Live Demo
- API Docs
- UMD Bundle
- Util UMD Bundle
- algo-chip on npm