Skip to content

prd.md

Latest commit

 

History

History
134 lines (100 loc) · 7.99 KB

prd.md

File metadata and controls

134 lines (100 loc) · 7.99 KB
Raw

Serenade — Product Requirements Document

1. Problem

Music producers who want AI assistance face a binary choice: opaque generative models that produce full tracks they cannot edit, or manual DAW work with no AI support. Neither is right. A producer needs an AI that understands musical intent, generates transparent symbolic artifacts (MIDI, automation, vocal stems), and keeps the DAW as the final source of truth.

2. Solution

Serenade is a Claude Code copilot for Ardour producers. Claude plans and edits songs through a local MCP server; Ardour remains the authoritative session host. The AI never "owns" the song — it issues change plans that compile into Ardour-visible artifacts: MIDI regions, track templates, plugin presets, automation envelopes, and vocal stems from SoulX-Singer.

3. Goals

  • G1 — Claude can bootstrap a full Ardour session from a SongSpec JSON in one command.
  • G2 — Claude can compose MIDI (harmony, bass, drums, melody) deterministically with no music foundation model.
  • G3 — Claude can render lead vocals and harmonies via SoulX-Singer zero-shot synthesis.
  • G4 — Human edits inside Ardour are preserved across incremental MCP reconcile operations.
  • G5 — The MCP server ships with a conservative local-only security posture by default.
  • G6 — All contracts are schema-validated and testable without a running Ardour instance.

4. Non-Goals

  • NG1 — No generative music foundation model (Suno, Udio, MusicGen, etc.). MIDI is always symbolic.
  • NG2 — No cloud MCP exposure. stdio by default; loopback HTTP for debugging only.
  • NG3 — No Windows-native Ardour integration in v0 (WSL2 Linux target only).
  • NG4 — No real-time audio processing inside the MCP server.
  • NG5 — No per-speaker voice training in v0 (SoulX zero-shot only; RVC/so-vits-svc in v1).

5. Users

Persona Need
Producer-songwriter Wants to describe a chord progression or song structure and get a playable Ardour session.
Beatmaker Wants drum patterns, bass lines, and synth leads wired to plugins without manual track setup.
Vocal arranger Wants to align lyrics to a melody and render with a voice reference, without hiring a vocalist.
Hobbyist Wants to make music with minimal DAW expertise; uses natural language to drive the session.

6. Functional Requirements

6.1 MCP Tools (all 10 in v0)

Tool Requirement
system.health Returns live status of Ardour OSC connection, SoulX availability, and project root.
session.bootstrap Creates or reconciles an Ardour session from SongSpec; reconcile-not-recreate by default.
tracks.create Creates missing tracks from TrackDef[]; skips existing tracks by name.
markers.create Adds named markers at beat or sample positions; no duplicate names.
midi.upsert_region Creates or replaces a MIDI region on a target track; validates time bounds.
audio.import_file Imports a WAV/FLAC file onto a target track at a given sample offset.
plugins.apply_mapping Applies a plugin chain from the category registry or an explicit override.
automation.write Writes an automation lane (gain, pan, plugin param) from a list of time-value points.
vocals.render_soulx Renders a vocal stem via SoulX-Singer subprocess given a VoiceProfile + target metadata.
mix.export Exports the session to WAV/FLAC mix (and optionally stems) via SimpleExport.

6.2 MIDI Generation

  • Chord plans from Roman numerals or explicit chord names via music21.
  • Bass lines (root/5th, octave, arpeggiated) from chord plans.
  • Drum patterns from human-readable JSON grid (kick/snare/hat/etc.) → GM MIDI.
  • Optional rule-based monophonic melody from scale degrees.
  • Lyric syllable → note alignment for vocal metadata generation.
  • All generators are deterministic given the same SongSpec.

6.3 Vocal Synthesis

  • Default engine: SoulX-Singer (zero-shot, score-conditioned).
  • VoiceProfile = prompt_wav + prompt_metadata.json + language + pitch_shift.
  • v0: preprocess-first mode — user provides prompt audio + SoulX preprocessing output as metadata.
  • v1: metadata-compiler mode — system converts MIDI + lyrics directly to SoulX target metadata.
  • Secondary engines planned for v1: RVC (timbre transfer from scratch vocals), so-vits-svc.

6.4 Ardour Integration

  • Lua EditorAction scripts for structural edits: session bootstrap, track creation, markers, MIDI regions, audio import, automation, export.
  • OSC adapter for responsive surface control: transport, strip fader/pan/mute/solo, plugin params, save.
  • Ardour runs in WSL2 with xvfb-run and JACK dummy backend for headless scripted operations.
  • All scripts are checked into the repo under adapters/ardour-lua/scripts/.
  • Ardour version is pinned in CLAUDE.md; Lua API is regenerated per pinned build.

6.5 State Management

  • MCP server maintains a per-session sidecar file (.serenade-state.json) that records route IDs, file hashes, marker IDs, and render paths.
  • All mutation tools accept and return a stateHash (etag) and reject stale edits.
  • OSC SSID cache is invalidated after every Lua structural edit.
  • session.bootstrap with rebuild: true is the only allowed destructive path.

6.6 Plugin Registry

  • Category-to-template registry in packages/plugin-registry/mappings.json.
  • Categories: synth.lead, synth.pad, synth.bass, synth.pluck, drums.acoustic, drums.electronic, sampler, fx.bus, vocal.lead, vocal.double, vocal.harmony.
  • Preferred open-source stack: Surge XT (synths), DrumGizmo (acoustic drums), sfizz (SFZ sampler), Calf Studio Gear (FX), Dragonfly Reverb, x42 utilities.
  • Claude may only select from the registry by category — never supply raw plugin executable paths.

7. Non-Functional Requirements

7.1 Security

  • MCP transport: stdio (default); loopback HTTP at 127.0.0.1 only for debugging.
  • All file paths validated against allowedRoots; .. traversal and symlink escapes rejected.
  • Allowed file types: .ardour, .lua, .wav, .flac, .mid, .json, .sfz, .template.
  • Fixed executable allowlist for subprocess calls (no arbitrary shell from tool inputs).
  • Per-tool rate limiting and max concurrent render jobs.
  • Hard timeout on vocals.render_soulx and mix.export.
  • Structured request logs with tool name, allowed-path decision, subprocess exit code.

7.2 Testability

  • All 10 MCP tools are testable without a live Ardour instance (mock OSC + mock subprocess).
  • JSON schemas validate all fixtures in CI.
  • MIDI generation is deterministic and covered by pytest unit tests.
  • Integration tests run against a mock OSC receiver (udp4 socket).
  • Ardour smoke tests run against a pinned Ardour version with xvfb in CI (nightly).

7.3 Performance

  • system.health responds in < 200 ms.
  • MIDI generation for a 4-bar pattern: < 2 s.
  • SoulX render: hard timeout at 5 min; expected < 2 min for short phrases.
  • Mix export: hard timeout at 10 min.
  • OSC messages: fire-and-forget UDP; no blocking waits on reply.

8. Success Metrics (v0)

  • just demo produces a playable Ardour session from fixtures/songs/demo.song.json end-to-end with no errors.
  • All 10 MCP tools pass contract tests against their documented output shapes.
  • MIDI generation for demo song is bit-identical across runs (determinism check).
  • No path-traversal or symlink-escape succeeds against the pathGuard (security unit tests).

9. Phased Roadmap

Phase Scope Estimated effort
v0 Repo scaffold, schemas, MCP skeleton (10 tools), Lua bootstrap + export, OSC adapter, MIDI generation modules, SoulX subprocess wrapper, demo fixture, CI skeleton 2–3 weeks
v0.5 Template registry + preset application, incremental reconcile logic, OSC mix edits, full fixture suite, integration tests 2 weeks
v1 Metadata compiler (MIDI+lyrics → SoulX JSON), automation writer, harmony/double-stack vocals, RVC engine support, hardened CI (xvfb Ardour smoke tests), security audit 4–6 weeks