Open source

Vocal Synth Engine. Sing with code.

A deterministic vocal instrument engine. Render singing voices from score data using additive synthesis, 15 voice presets, and real-time WebSocket streaming. Play live, jam with others, or render to WAV.

Get started Handbook

Clone

git clone https://github.com/mcp-tool-shop-org/vocal-synth-engine.git

Run

npm ci && npm run dev

Open

http://localhost:4321 # cockpit UI

Features

Everything you need to synthesize, play, and collaborate.

Additive Synthesis

Harmonic partials, spectral envelopes, and noise residual combine to produce natural singing voices from pure math.

15 Voice Presets

Frozen analysis artifacts from Kokoro TTS voices plus lab presets, each with multiple timbres and binary .f32 assets.

Real-Time Streaming

WebSocket audio streaming with latency calibration, hold pedal, velocity/breathiness sliders, and live telemetry.

Multi-User Jams

Collaborative sessions with host authority, guest participation, track ownership, participant attribution, and shared recording.

Cockpit UI

Browser-based SPA with piano roll editor, live chromatic keyboard, XY pad for timbre morphing, render bank, and telemetry.

Deterministic Output

Seeded RNG ensures reproducible output from the same inputs. Every render includes provenance tracking with commit SHA and score hash.

Quick Start

Development

# Clone and start the dev server
git clone https://github.com/mcp-tool-shop-org/vocal-synth-engine.git
cd vocal-synth-engine
npm ci
npm run dev

# Open the cockpit UI at http://localhost:4321

Production

# Build everything (cockpit + server)
npm run build

# Start the production server
npm start

# Or deploy with Docker
docker build -t vocal-synth .
docker run -p 4321:4321 vocal-synth

API Reference

REST endpoints and WebSocket paths.

Endpoint

Method

Description

`/api/health`

GET

Server health, version, uptime

`/api/presets`

GET

List voice presets with timbres and metadata

`/api/phonemize`

POST

Convert lyrics text to phoneme events

`/api/render`

POST

Render a score to WAV

`/api/renders`

GET

List all saved renders

`/api/renders/:id/audio.wav`

GET

Download render WAV file

`/ws`

Live mode — single-user note playback

`/ws/jam`

Jam sessions — multi-user collaboration

Cockpit UI

Three tabs, one instrument.

Score Editor

Piano roll with drag-to-create notes (C2-C6), per-note velocity/timbre/breathiness controls, lyrics input with phoneme generation.

Live Mode

24-key chromatic keyboard with MIDI input, XY pad for real-time timbre morphing, hold pedal, metronome with quantize grid.

Render Bank

Browse, play, pin, rename, and delete saved renders. Load scores back into the editor. Side-by-side telemetry comparison.