Skip to main content
Glama

Vamp

CI

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:

Song

Use

Length

BPM

Key

lofi-coding-bed.song.json

Lo-fi coding bed

45 s

90

A minor

explainer-upbeat.song.json

Tutorial / explainer

30 s

112

G major

ambient-focus-bed.song.json

Ambient focus

60 s

60

A minor

corporate-bed.song.json

Corporate clean

30 s

108

C major

tension-stinger.song.json

Dramatic stinger

6 s

110

D minor

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

Packages

Package

Purpose

@gxaditya/vamp

Umbrella: CLI + MCP server + SDK

@gxaditya/vamp-schema

Canonical JSON Schema, generated TS/Python types, validation, normalization

@gxaditya/vamp-engine

Song→timeline compiler, MIDI export, built-in and FluidSynth backends, WAV/stem/report renderer

@gxaditya/vamp-project

Filesystem projects: revision-safe edits, atomic writes, locks, root confinement

@gxaditya/vamp-cli

The vamp command line

@gxaditya/vamp-mcp-server

The vamp-mcp stdio MCP server

@gxaditya/vamp-sdk

Typed local client facade

Architecture and data flow: docs/architecture.md.

Development

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

Command

Purpose

pnpm build

Build all packages to dist/

pnpm test

Full suite (builds first)

pnpm test:fast

Fast regression suite

pnpm test:native

FluidSynth + pinned-SoundFont suite

pnpm test:security

Hardening and adversarial suites

pnpm lint / pnpm format:check

ESLint / Prettier gates

pnpm check:generated / check:python-types

Generated-type drift checks

pnpm generate:types

Regenerate TS + Python types from the schema

pnpm verify:soundfont <path>

Verify the pinned FluidR3 checksum offline

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Enables coding agents to compose, tune, render, mix, and audit native VOCALOID3/4 projects from scratch, acting as a production bridge between intent and finished song.
      22
      14
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to create and edit Strudel music code, render offline WAV audio, and obtain structured hearing reports with waveform, spectrogram, BPM, and onset analysis.
      AGPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents to compose, edit and run multi-agent pipelines represented as songs, where channels are agents, notes are agent calls, and mixer buses carry each agent's output to the next. Lets agents create and modify arrangements, validate and render projects headlessly, play them back live in a studio window, and export the result as WAV or MP3, with every change undoable and cached takes replayed for free.
      43 npm
      MIT