# Claude brief: Suno-class generation + lyric lock

_Date: 2026-09-02. Audience: Claude acting as staff engineer for a mega-skilled operator. Skip tutorials. Do not scaffold a platform they did not ask for._

This file (BRIEF.md) is the complete product brief, roadmap, and operating rules. Read it in the repo. Do not fetch a loopback web server or an /api/brief route — those are not reachable from another machine. Regenerated from src/lib/brief.ts (npm run brief). Do not summarize this file away.

## North star

Prompt → real song, then edit the words without moving the band.

Ship a Suno-class product loop first (text to full song with vocals, lyrics, library, player). Then add the thing Suno does not actually do: new lyrics on an existing mix, instrumental frozen, timing locked. Then a menu of licensed voices — never an unlicensed famous throat.

These are **three different ML jobs**. A YouTube “Frank Sinatra sings Careless Whisper” video is job 3 only (timbre), same lyrics, keep-music. It is not lyric lock. Do not learn the wrong lesson from it.

**Job 1 — Suno-class generate.** Style prompt + optional lyrics → full song with vocals. This is ACE-Step / YuE / MiniMax behind a queue, not Tone.js and not a new foundation model. Chirp v5 is closed. Do not try to beat it in Stage 1.

**Job 2 — Lyric lock.** Change the words. Keep the instrumental. Keep the clock. Text-based singing voice editing (MeloDISinger-class). Duration is a hard budget. Arbitrary fan lyrics that do not fit the melody are infeasible — rewrite them, do not force them.

**Job 3 — Voice / style.** Sing this in a chosen licensed voice. RVC / Seed-VC keep lyrics and timing; they do not write new words. Licensed voicebanks (session singers, Synth V / ACE / Kits-class contracts) are the ship path. Celebrity scrape is a complaint, not a milestone.

## Hard rules (non-negotiable)

- Do not train a new foundation music model. ACE-Step already paid that bill (~32k A100-hours published). Wrap it.
- Do not treat the Tone.js toy studio as the music model. It is a seeded synth that proves the product loop.
- Do not clone living artists or scrape celebrity likeness. Licensed voices only. Famous names are a legal stage, not an ML stage.
- Do not start Stage 2 training until Stage 0 (bakeoff) writes a go/no-go memo with audio and metrics.
- Claude writes glue, lyrics, duration packing, eval, and product code. A GPU does Demucs / WhisperX / ACE-Step / RVC. Claude cannot be the singer and cannot hear mix artifacts.
- Non-edit regions of a lyric-lock job must stay bit-identical to the source mix. If the drums move, it is a cover, not an edit. Fail the job.
- If asked for both a lyric-lock and an unlicensed star voice, ship the lock on a licensed or user-owned voice. Refuse the star.

## Who does what

| Who | Does |
| --- | --- |
| Claude | Product (this Next.js app), lyric LLM, duration packer, G2P, structure tags, eval harness, job queue UI, go/no-go writeups. Almost all of Stage 0 software. |
| GPU worker | Demucs/UVR stems, WhisperX/MFA alignment, ACE-Step / YuE generate and repaint, RVC/Seed-VC, later SVE infill. One 4090 or A100 is enough to test viability. |
| Human ears | Listen. Kill criteria are mix-level. Claude cannot grade bleed, plate tails, or doubled choruses. Ten songs, not ten thousand. |
| Lawyer / A&R | Voice contracts, catalog, likeness. Enters at Stage 3. Does not block Stages 0–2 if voices are licensed or the operator’s own. |

## Suno-class functionality

We want the **product loop people mean when they say Suno**, implemented on **open weights** (ACE-Step 1.5 default; YuE if VRAM allows). We do **not** want a Chirp v5 replica train.

Suno’s public surface (from their app, help center, and Vercel writeup): Custom and Simple generate, instrumental, library, player, Extend, Cover, Persona, Add Vocals / Add Instrumental, stems, Studio replace, credits, feed, iOS. Internals: Next.js + closed hierarchical audio-token transformers (Bark was the 2023 open diagram; production is Chirp v2→v5.5).

Map every feature to a stage. If it is not in Stage 1/1b, do not build it while generate still plays a synth.

| Feature | Suno | We ship | Notes |
| --- | --- | --- | --- |
| Custom mode (style + lyrics) | Ships | Stage 1 MVP | Primary generate path. Lyrics are a request to the music model, not a lock to an existing mix. |
| Simple / describe a song | Ships | Stage 1 MVP | Claude (or any LLM) writes titled lyrics + [Verse]/[Chorus] tags, then the music model sings them. |
| Instrumental toggle | Ships | Stage 1 MVP | Same worker, no vocal stem. Easy. |
| Full song with vocals | Chirp v5 | Stage 1 MVP | ACE-Step 1.5 or YuE. Expect open-weight quality, not v5. That is the honest 2026 clone. |
| Library + player + download | Ships | Stage 1 MVP | Object storage + CDN later. Local files + Postgres/SQLite is fine for the first GPU slice. |
| Credits / queue UI | Ships | Stage 1 MVP | Mock credits are fine. Real billing is Stage 4. The queue must survive a 30s–2min GPU job. |
| Extend | Ships | Stage 1b editor | Continue from the last N seconds. ACE-Step-class models already have this hook. Band is allowed to evolve. |
| Cover / restyle | Ships | Stage 1b editor | New performance of the same song idea. Drums may move. Do not advertise this as lyric lock. |
| Get stems | Ships | Stage 1b editor | Demucs/UVR on the master. Needed anyway for lyric lock. Ship as a user feature once the worker exists. |
| Add vocals / add instrumental | Ships | Stage 1b editor | Latent edit / second pass. Useful. Still a regenerate, not a surgical lyric swap. |
| Replace a section | Studio | Stage 2 lock | Suno’s replace often re-performs the band. Our replace must freeze non-edit audio bit-identically. |
| Lyric lock (new words, frozen mix) | Does not ship this | Stage 2 lock | The differentiator. Duration packer + infill + stem mix. Stage 0 decides if open weights are enough. |
| Persona / custom voice | Ships | Stage 3 voice | Licensed or user-consented banks only. A menu of 5–20 singers beats one stolen star. |
| Feed / social / Copilot / iOS | Ships | Stage 4 later | Do not build a social network before the songs are real. Web first. |
| Unlicensed famous likeness on a hit | Legal war | Never | WMG settlement was reported ~$500M. Not a sprint. Not a Claude task. |

## Roadmap

Do these in order. Stage 2 is gated on Stage 0. Stage 3 is gated on a voice you actually own. Stage 4 is gated on listenable Stage 1.

### Stage 0 — Viability bakeoff

*Inference only. No product. No training.*

| | |
| --- | --- |
| Status | next |
| Compute | One 4090 or A100 for a few days |
| GPU money | $50–$400 |

**Goal.** Prove or kill lyric-lock with open models on a known 8-bar clip before writing a training script.

**Claude does.** Done on CPU: packer, G2P, eval harness, A/B/C lyrics, synth fixture, GPU runbook. Remaining: go/no-go memo after GPU audio + ears.

**GPU does.** Demucs, WhisperX/MFA, ACE-Step repaint, RVC same-lyric control, optional naive vocode+crossfade.

**Not this stage.** No Next.js scope creep. No foundation-model train. No celebrity voice.

**Deliverables**

- A frozen test pack: one dry-ish mix, 8 bars, isolated vocal + instrumental, alignment JSON, original lyrics.
- Three lyric conditions generated by Claude: same phoneme count, +25% syllables, half syllables.
- Baseline audio for each condition, plus a same-lyric RVC control.
- A one-page memo with metrics, kill-criteria hits, and a Stage 2 go / no-go / pivot.

**Stage goals (definition of done)**

- **Alignment exists.** WhisperX or MFA produces usable phone/word times on the dry vocal. If alignment is garbage, stop — later stages will lie.
- **Same-lyric RVC is clean.** Convert the original vocal to another licensed timbre, mix back, drums untouched. This is the YouTube-cover ceiling. If this fails, the stems are too wet to edit.
- **Feasible lyric can infill.** Same phoneme-count line: new words, original instrumental, no drum movement, consonants on the old onsets ±30 ms on the dry verse.
- **Infeasible lyrics are rejected.** The +25% and half-syllable lines are either rewritten by the packer or explicitly failed. Never silently chew vowels and call it locked.
- **Wet chorus is measured, not wished.** Repeat the feasible line on a stacked/wet chorus. Record whether bleed/reverb kills the splice. That number decides Stage 2 training, not vibes.

**Kill criteria**

- Band or drums move on a supposed lock (it is a cover — label it, do not ship as lock).
- Non-edit region regenerates or loudness-matches into a new noise floor.
- Alignment cannot be trusted on the dry verse.
- Wet chorus collapse with no salvage path (then lock is verse-only, or kill the feature).

**Exit.** A written go/no-go. Go = Stage 2 infill is the gap (train $25k–$120k GPU band) or glue is enough. No-go = wrap generate-only (Stage 1) and drop lock, or restrict lock to dry stems the user uploads.

### Stage 1 — Suno-class generate

*Real songs. Open weights. This UI.*

| | |
| --- | --- |
| Status | planned |
| Compute | Persistent GPU worker (A100-class or 4090) |
| GPU money | Worker ~$1.20–$1.60/hr; pennies per song |

**Goal.** Replace Tone.js with ACE-Step or YuE so Create song produces an actual vocal track. Same product loop the toy studio already has.

**Claude does.** Worker API, job queue, storage, lyrics LLM, structure tags, seed, library, player, error/empty/loading states. Keep this Next.js app.

**GPU does.** ACE-Step 1.5 (default) or YuE if VRAM ≥16 GB. Do not fine-tune yet.

**Not this stage.** No Chirp replica train. No social feed. No iOS. Tone.js may remain as an offline demo fallback when the worker is down.

**Deliverables**

- GPU worker with a generate endpoint: prompt, lyrics, instrumental flag, seed, duration cap.
- This app’s /studio talks to the worker; library stores audio URLs, not just synth specs.
- Simple mode: LLM writes lyrics + title from a description, then generate.
- Custom mode: user lyrics respected at section-structure level (not sample-lock).

**Stage goals (definition of done)**

- **Prompt → WAV.** A user can type a style prompt and get a song with vocals in under two minutes on a warm worker.
- **Lyrics in, lyrics out.** Custom lyrics appear in the vocal, section tags honored enough to be useful. Not phoneme-locked. Honest copy in the UI.
- **Deterministic seed.** Same prompt + seed + lyrics = same (or near-same) take, so the library is not a slot machine.
- **Instrumental mode.** Toggle produces a band-only mix.
- **Library is audio.** Play, rename, delete, download. Survives refresh. Empty/error/loading states are real.

**Kill criteria**

- Open model output is unusable for the intended users after a 20-song listen (then try YuE / MiniMax; still unusable → do not fake it with Tone.js).
- Worker cannot be operated at < $0.10/successful song including retries.

**Exit.** A Suno-like web loop on open weights. Users can make and keep songs. Lyric lock is still a separate button that does not exist yet.

### Stage 1b — Suno editor features

*Extend, stems, cover — still not lock.*

| | |
| --- | --- |
| Status | planned |
| Compute | Same worker |
| GPU money | Same rates; stems add a Demucs pass |

**Goal.** Match the Suno editor people actually use, with honest labeling when the band is allowed to move.

**Claude does.** UI for extend / cover / stems / add vocals. Copy that never calls a regenerate a ‘lock’.

**GPU does.** ACE-Step extend/cover/repaint hooks + Demucs.

**Not this stage.** Do not implement Replace as lyric-lock until Stage 2. Cover ≠ lock.

**Deliverables**

- Extend by N seconds from the tail.
- Cover/restyle with a new style prompt.
- Download stems (vocals / drums / bass / other as the splitter allows).
- Add vocals to an instrumental and add instrumental to a vocal, if the model supports it.

**Stage goals (definition of done)**

- **Extend feels like a continuation.** Harmony and groove continue; seams are not embarrassing on headphones.
- **Stems are a product feature.** User can pull vocals vs band. This is also the Stage 2 input.
- **Honest cover.** UI says the arrangement may change. Never marketed as ‘keep the music, change the words’.

**Kill criteria**

- Extend always resets the song (then hide the button).
- Stems too wet to remix — still ship them, but Stage 2 must require user-uploaded dry vocals.

**Exit.** Suno-shaped editor on open weights. Differentiator still unbuilt.

### Stage 2 — Lyric lock

*New words. Frozen mix. Hard duration budget.*

| | |
| --- | --- |
| Status | gated |
| Compute | Inference always; train only if Stage 0 says glue lost |
| GPU money | Glue: cents/edit. Train infiller: $25k–$120k GPU if needed |

**Goal.** Edit lyrics on an existing song without moving the instrumental. Non-edit audio bit-identical. Packer refuses lines that cannot fit.

**Claude does.** Productize the Stage 0 packer (already prototyped at /lyric-lock). Feasible-lyric rewrite. Region selection. Eval in CI on the frozen test pack.

**GPU does.** Infill on the vocal stem, mix back through the original FX if possible. Train an SVE infiller only after the bakeoff memo says open repaint cannot hold the clock.

**Not this stage.** No famous voices. No regenerating the drums ‘to make it fit’. No shipping lock on wet choruses if Stage 0 killed that path.

**Deliverables**

- Select a region → propose feasible lyrics (LLM + G2P + span budget) → render → mix.
- Bit-identical outside the edit window (hash the non-edit samples in tests).
- If Stage 0 required training: a small SVE infiller on dry vocals, paper-scale to low six figures GPU, not a new Chirp.

**Stage goals (definition of done)**

- **Packer is a product surface.** User sees Locked / Crammed / Broken before paying for a GPU job. Broken lines get a rewrite, not a render.
- **Dry verse lock.** On the Stage 0 clip, feasible new lyrics, drums hash-equal, consonants within ±30 ms of target onsets.
- **Whole-song policy.** Documented: verse-only vs wet-chorus. Do not silently fail on stacks.

**Kill criteria**

- Cannot keep non-edit audio identical after mix.
- Infill needs a foundation-model retrain to sound acceptable — that is a different company. Stop.

**Exit.** A working ‘rewrite this line’ control on dry or user-supplied stems. This is the product people think Suno already is.

### Stage 3 — Licensed voices

*A menu, not a mugshot.*

| | |
| --- | --- |
| Status | gated |
| Compute | Same worker + per-voice adapters |
| GPU money | Recording/licensing dwarfs GPU. Custom bank: mid four to low five figures |

**Goal.** Apply lyric lock (or generate) in a chosen licensed voice. Five good singers beat one stolen star.

**Claude does.** Voice picker UX, consent/license metadata on every asset, never a ‘make it sound like <famous living artist>’ prompt.

**GPU does.** RVC/Seed-VC or trained adapters on contracted audio. User-uploaded voice with explicit consent is allowed.

**Not this stage.** No celebrity scrape. No ‘Sinatra / Careless Whisper’ as a feature. That YouTube genre is the control, not the product.

**Deliverables**

- At least one contracted or operator-owned voicebank plus user-voice (opt-in).
- License and consent stored with the job. Outputs watermarked or tagged internally.
- Style prompts describe genre, not a living person’s identity.

**Stage goals (definition of done)**

- **Picker ships.** Generate and lock both take a voice id. Default is a licensed or user voice, never a star.
- **Same-lyric convert still works.** RVC path remains for ‘this take, that licensed throat’ — the YouTube method, productized cleanly.

**Kill criteria**

- Any feature that requires an unlicensed named artist to demo. Delete it.

**Exit.** Voice is a licensed dimension of the same two jobs: generate and lock.

### Stage 4 — Product scale

*Credits, CDN, moderation — after the songs are real.*

| | |
| --- | --- |
| Status | later |
| Compute | Fleet if demand exists |
| GPU money | Tens of thousands / month only with users |

**Goal.** Run it like a music product: billing, storage, moderation, maybe mobile. Not a new model.

**Claude does.** Auth, Stripe, object storage, CDN, content policy, rate limits.

**GPU does.** Batching, distillation only if latency/cost demands it.

**Not this stage.** No social feed as a substitute for quality. No foundation-model program hiding in this stage.

**Deliverables**

- Real credits and billing.
- CDN audio, loudness/true-peak pipeline.
- Abuse/moderation for voice and lyric misuse.

**Stage goals (definition of done)**

- **A stranger can pay and get a song.** Without the operator SSH-ing into a pod.

**Kill criteria**

- Scale spend before Stage 1 quality is listenable.

**Exit.** A company, if the songs and the lock are real. Otherwise stay a tool.


## Stage 0 bakeoff protocol (execute this before any training)

**Clip.** One dry-ish commercial-style track you have rights to (or an original). First 8 bars of a verse, not a wet chorus. Export: mix, instrumental, vocal, 44.1 kHz WAV.

**Lyric conditions (Claude writes these against the alignment):**

- A — same phoneme/syllable count as the original line (duration-feasible).
- B — ~25% more syllables (packer should cram or refuse).
- C — ~half the syllables (melisma / sparse).

**Pipeline (in this order):**

1. Demucs or UVR → vocal + instrumental. Keep the original mix as ground truth.
2. RVC/Seed-VC on the original vocal, same lyrics, mix onto the instrumental (control: YouTube cover).
3. WhisperX or MFA → word/phone times. Hand-correct the 8 bars if needed. This file is gold.
4. Claude packer + G2P assigns phonemes into the original span (MeloDRP-style ratios that sum to the old duration).
5. ACE-Step lyric-edit / repaint constrained to the vocal region if the API allows; else score-path SVS over the original instrumental.
6. Naive vocode + crossfade last: non-edit samples must be bit-identical. If this baseline wins, do not train.
7. Repeat A on a wet stacked chorus as a stress test, not as the first test.

**Metrics:**

- Non-edit sample hash / max abs error vs source mix.
- Drum-stem correlation vs source (must stay ~1.0 for a lock).
- Onset error of target consonants vs alignment (ms).
- Human AB: ‘did the band move?’ yes/no. One no from a trusted ear fails the take.

## What this repo already is

- `BRIEF.md` — This document. Canonical pasteable brief. Regenerated from src/lib/brief.ts via npm run brief.
- `src/lib/brief.ts` — Source of truth for stages, Suno feature map, kill criteria, and this markdown.
- `src/app/page.tsx` — Public Suno stack briefing: Next.js product, Bark architecture, closed Chirp, clone difficulty.
- `src/app/lyric-lock/page.tsx + src/lib/lyric-lock.ts + src/components/lyric-packer.tsx` — Why lock is three models. Product packer: G2P, Locked/Crammed/Broken, A/B/C conditions, rewrite-not-render.
- `src/app/cost/page.tsx + src/lib/cost.ts` — Dollar bands. Do not reopen the foundation-model invoice.
- `src/app/studio/page.tsx + src/components/studio-app.tsx + src/lib/compose.ts + src/lib/generate.ts` — Toy Suno loop: prompt, lyrics, generate, play, library. Seeded Tone.js, not a neural net. generate.ts is the Stage 1 swap (job id + WAV).
- `scripts/bakeoff/` — Stage 0: CPU synth pack, packer CLI, eval harness, GPU.md runbook. No weights, no train. npm run bakeoff

The toy studio is **seeded Web Audio / Tone.js**. Same prompt ⇒ same arrangement. That is intentional. Stage 1 swaps the renderer, not the UX.

Dev note: on some VMs Turbopack HMR is broken; use `next dev --webpack` or `next build && next start`. Unlock AudioContext on pointerdown; do not import Tone at module load.

## What Claude should do this week

1. **Do not train anything.** CPU Stage 0 is implemented. If you start a foundation-model run, you have failed the assignment.
2. **Rent one GPU for inference.** Packer, eval, synth fixture, and GPU.md are in scripts/bakeoff/. The gate is Demucs + WhisperX + ACE-Step + RVC on a 4090/A100. No go/no-go without those WAVs and human ears.
3. **Keep the studio as the generate UX.** src/lib/generate.ts is the swap. When a worker exists, return { renderer: 'gpu', jobId, wavUrl }. Until then, do not pretend the synth is Chirp.
4. **Packer is the product surface.** Locked / Crammed / Broken plus rewrite. Python G2P in the worker later; the TypeScript heuristic is what Stage 0 uses now.

## Money (do not re-litigate)

- A100-class inference ~$1.20–$1.60/hr. A generate or edit is **cents**, not the invoice.
- ACE-Step published pretrain ≈ 120×A100 × ~264 h ≈ 32k GPU-h ≈ **$45k one run**. Do not redo it.
- Lyric-lock same throat, productized: **$250k–$1.5M**, mostly people.
- Plus licensed voices: **$400k–$3M**.
- Famous likeness: **$10M–$500M+**, not GPU.
- SVE infiller train **beyond open weights**, skilled: **$25k–$120k GPU**, and only if Stage 0 says so.

## Suggested stack (when you write code)

- Keep this Next.js + TypeScript + Tailwind + shadcn app as the product.
- GPU worker: Python, FastAPI or similar, ACE-Step 1.5, Demucs, WhisperX. Queue: any boring queue.
- Packer: TypeScript now (see `src/lib/lyric-lock.ts`); Python G2P in the worker later.
- Storage: local disk in Stage 1, object storage in Stage 4.
- No second component library. No database until audio files exist.

## Definition of “Suno functionality” for this project

A stranger can open the web app, type a style (and optionally lyrics), and hear a **generated song with vocals** they can save and replay. They can later **rewrite a line** without the drums changing, on a feasible lyric, with a **licensed or user-owned** voice. That is the whole product. Everything else is either Suno chrome (extend, stems, cover) or a company (feed, iOS, Chirp, labels).

If you are unsure whether a task belongs, ask: does this make generate real, lock true, or voice licensed? If no, do not do it.