Vamp

Vamp is a local-first, headless music engine for coding agents: a versioned JSON song format with a deterministic offline renderer, a CLI, an MCP server, and a TypeScript SDK. It lets an agent compose original, editable background music on its own machine — no account, no cloud API, and no network access at render time.

Highlights

• Fully local. Rendering is a local process over a JSON file. Nothing is downloaded at render time; on Linux the offline guarantee is enforced inside a network-free namespace in CI.

• Editable source, not a prompt lottery. A song is data — notes, instruments, patterns, effects, automation — so edits are revision-safe and deterministic instead of re-rolls.

• Real sampled instruments by default. The auto backend renders General MIDI presets through FluidSynth and a local GM SoundFont, with a dependency-free oscillator synth as fallback.

• Complete render artifacts. Every render produces a master WAV, per-track stems, a Type 1 MIDI file, and a report (duration, peak, clipping, loudness, backend, hashes, warnings).

• Agent-native surfaces. CLI with JSON envelopes and stable exit codes, a stdio MCP server with 14 tools, and a typed SDK — all revision-safe and confined to a project root.

Related MCP server: VOCALOID MCP

Status

v1 is published on npm at version 0.1.0 and CI-verified on Linux, macOS, and Windows. WAV is the only render format — MP3 export and playback are not implemented.

Install

npm i -g @gxaditya/vamp
vamp --version
vamp doctor        # reports FluidSynth + SoundFont provisioning

Or without a global install:

npx -y @gxaditya/vamp-cli --version
npx -y @gxaditya/vamp-mcp-server --project-root "$PWD/vamp-projects"

The rest of this README covers the development workspace — for the published packages' tool contracts see docs/api.md and docs/mcp.md.

Requirements

• Node.js ≥ 22.13 and pnpm 10.15.1 (via corepack enable).

• Python ≥ 3.11 — only for the generated-types import check; stdlib only.

• FluidSynth 2.x + a GM SoundFont (recommended) for sampled rendering. Without them, everything works through the built-in synth.

  # Debian/Ubuntu
  sudo apt install fluidsynth fluid-soundfont-gm
  # macOS — plus a GM .sf2 under ~/.local/share/vamp/soundfonts/ (or VAMP_SOUNDFONT_PATH)
  brew install fluid-synth

  Provisioning, search order, and the pinned FluidR3 checksum are in docs/instruments.md.

Build and verify

pnpm install
pnpm build
pnpm check:generated      # generated types in sync with the schema
pnpm lint && pnpm typecheck
pnpm test                 # fast + native + security suites

Quick start (CLI)

pnpm exec vamp doctor          # check FluidSynth / SoundFont provisioning
pnpm exec vamp init my-cue --preset lofi --duration 45 --bpm 90
pnpm exec vamp validate vamp-projects/my-cue/song.json
pnpm exec vamp render vamp-projects/my-cue/song.json \
  --out vamp-projects/my-cue/renders/master

A render writes master.wav, one stem-*.wav per audible track, song.mid, and report.json, refusing overwrites without --overwrite. Useful options: --sample-rate 44100|48000 (default 48000), --backend auto|builtin|fluidsynth, --no-stems, --no-midi, --no-report, --no-normalize, --json for a single machine-readable envelope. Exit codes: 0 success (validation warnings do not fail), 1 failure (validation, file, project, render, cancellation), 2 usage error.

Commands: init, validate, info, render, schema, presets, doctor. Full contracts and envelope shapes: docs/api.md.

MCP server

The vamp-mcp stdio server exposes the whole agent loop over 14 tools: discovery (health_check, get_schema_guide, list_instruments, list_presets), authoring and revision-safe edits (validate_song, create_song, get_song, list_projects, update_song, add_track, add_notes, set_pattern, set_instrument), and render_song for bounded, confined rendering into a project's renders/ tree.

{
  "mcpServers": {
    "vamp": {
      "command": "node",
      "args": [
        "/absolute/path/to/vamp/packages/mcp-server/dist/main.js",
        "--project-root",
        "/absolute/path/to/vamp-projects"
      ]
    }
  }
}

Configuration also comes from VAMP_PROJECT_ROOT, VAMP_FLUIDSYNTH_PATH, and VAMP_SOUNDFONT_PATH; arguments take precedence over environment variables. Every persisted edit requires expectedRevision — a stale revision returns a repairable project.revision.conflict and changes nothing. Client setup for Claude Code, Cursor, and Codex, plus full tool contracts: docs/mcp.md.

SDK

@gxaditya/vamp-sdk is a typed facade over the shared libraries — the same result, error, and revision contracts with no HTTP and no service:

import { VampClient } from '@gxaditya/vamp-sdk';

const client = new VampClient({ root: '/absolute/path/to/vamp-projects' });
// validate, create, edit with expectedRevision, render, and inspect reports

Example songs

examples/songs/ ships five authored BGM cues that render fully offline on the built-in instruments, each with a brief, duration math, render commands, and revision-safe edit prompts:

See examples/README.md for the catalog and audition checklist.

Packages

Architecture and data flow: docs/architecture.md.

Development

ESM-only TypeScript (strict, NodeNext), Vitest, ESLint + Prettier. Common commands from the repo root:

CI (.github/workflows/ci.yml) runs three job groups on every push: core checks on Linux, a platform matrix (ubuntu/macos/windows) with build, lint, typecheck, and test gates plus CLI/MCP/render smokes, and a native matrix that provisions FluidSynth and the pinned SoundFont on all three OSes and runs the native suite offline — including a network-free unshare --net render on Linux.

Guarantees and scope

• Determinism. The built-in synth is byte-deterministic for identical song, options, engine build, and platform. FluidSynth output is pinned same-machine only — cross-platform byte identity is not claimed.

• Offline. No network or model calls after provisioning; no audio device required.

• Security model. Lexical + realpath project-root confinement (including symlink escapes), argument-array subprocesses with sanitized environments and bounded output, atomic writes, advisory locks. Enforced in process logic, not an OS sandbox.

• Versioning. Package SemVer and song schemaVersion are independent. Loading never migrates; a future schema version requires an explicit, user-invoked migration.

• Not in v1. MP3 export, realtime playback, HTTP MCP transport, Python SDK, GUI, generative models, tempo maps, vocals. The schema rejects unknown fields rather than half-supporting them.

Troubleshooting

• audio.backend.missing_dependency — FluidSynth not on PATH. Install it or pass --fluidsynth-path (Windows health checks rely on PATHEXT resolution). VAMP_FLUIDSYNTH_PATH avoids repeating the flag.

• audio.asset.checksum_mismatch — the SoundFont on disk is not the pinned FluidR3 bytes. Re-provision per docs/instruments.md; never edit the checksum to make a check pass.

• project.path.confined — the path uses traversal, an absolute/drive/UNC form, or an escaping symlink. Use plain forward-slash relative paths under assets/ or renders/.

• macOS paths show /private/... — /tmp and /var are symlinks; the store realpath-resolves the root. This is confinement working, not corruption.

• project.lock.busy — another writer holds the project lock; the wait is bounded, and crashed-process locks are recovered as stale automatically.

License

AGPL-3.0-only. Third-party notices: THIRD_PARTY_NOTICES.md.