Song Genome — Product Specification

Version: 1.3.0 Last updated: 2026-07-27 Status: 1.0.0 released. Fadr, MusicAtlas, ElevenLabs, and Deepgram are wired and verified against real audio. Analysis runs server-side and survives a closed tab.

1. What the product is

Song Genome is songwriting intelligence for songwriters, producers, and topliners. Users upload a track they love — a released song, a reference, or their own demo — and the app reverse-engineers its musical DNA: key, tempo, chord progression, sections, energy curve, harmonic complexity, mood, era, "sounds like" references, and a plain-English why for every tag.

The user then talks to their music: a roster of specialist AI agents can discuss the track in natural language, by keyboard or hands-free voice. Chat is the primary interface; the DNA specimen sheet is the shared context.

The design language is "specimen sheet, not dashboard": tabular numbers, dashed borders as a confidence signal, no chart gradients, no glow.

2. What the app does TODAY (v1.0.0)

2.1 Authentication

• Email/password and Google OAuth via Lovable Cloud auth.
• Route gate at /_authenticated/* — unauthenticated users are redirected to /auth.
• No anonymous sign-ups, no forced email confirmation, no password-complexity policing, password fields are not masked.

2.2 Track library

• Authenticated users see their own tracks at /library (RLS scoped to auth.uid()).
• Upload enforces limits before a byte reaches the worker: audio MIME types only, 50 MB, 12 minutes.
• Metadata fields are optional and labelled if known — the pipeline works with a blank key, BPM, or artist.
• Track detail page at /tracks/:trackId renders pipeline progress first, then the DNA specimen sheet.
• Title and original artist are inline-editable; setting an artist auto-requeues MusicAtlas enrichment.

2.3 Analysis pipeline (server-side)

• submitTrackForAnalysis → advanceAnalysis → retryStage. One stage per call, forward-only, idempotent.
• Stages: fadr_submit → fadr_poll → derive → interpret → enrich → done.
• Per-stage timeout ceilings: separation 20 min, derivation 5 min, interpretation 3 min, enrichment 2 min.
• A pg_cron job hits /api/public/hooks/analysis-tick every minute, so closing the tab does not cancel analysis.
• Every transition writes to analysis_events — stage, attempt, duration, error code — and the track page renders that ledger.
• Errors are split: a safe user-facing message on the track, full provider detail admin-only.
• Poll-only. There are no provider webhooks and 1.0 does not need any.

2.4 Music DNA layer

All DNA reads go through MusicDNAProvider in src/lib/music-dna/. Providers are swappable; the schema, confidence model, and L3 prompt library stay the same.

Current provider stack:

• self-built — Fadr for L1 (key, BPM, time signature, chord progression, section timestamps, stems) + JS/Web Audio L2 + Gemini L3. This is the live default.
• musicatlas — live enrichment by artist + title for catalog key/BPM/loudness/genre/influences; merged under overrides.musicatlas.
• cyanite — Plan C provider, interface only, reserved for commercial licensing customers.

Three-layer taxonomy:

• L1 Measured (confidence 1.0) — key, BPM, time signature, chord progression, section timestamps, loudness, stems. Solid borders. Provider-labelled: Fadr data says Fadr.
• L2 Derived (0.9) — energy curve (Web Audio RMS), section loudness, harmonic complexity, vocal presence, stereo width, chord movement classification (Roman numerals + common names like "Sensitive Female Progression"). Dashed borders.
• L3 Interpreted (0.7) — genre, sub-genre, mood adjectives, era feel, "sounds like" references, plain-English why per tag. Muted borders with a "why this tag?" affordance.

Nothing is invented. A value that was not measured renders as not measured, never as a plausible default.

Full detail on layers, thresholds, and confidence: /methodology.

2.5 Cross-checking and grounding

• Tempo reconciliation — Fadr, MusicAtlas, and the derived curve are compared; half/double-time readings are detected and the reconciled value is shown with its sources.
• Disagreement surfacing — where providers conflict on key, BPM, or loudness, both readings are shown rather than silently picking one.
• L3 grounding guard — interpreted output is fact-checked against the measured layer; claims that contradict measurements are dropped before they reach the user.

2.6 Agent roster (chat)

Five specialist agents, each with its own system prompt, tool set, and default Deepgram Aura-2 voice.

Tools: get_track_dna, search_tracks, compare_tracks — all user-scoped Supabase reads.

Entry points: per-track at /tracks/:trackId, global at /chat and /chat/:threadId with a session sidebar. A Track focus dropdown switches the thread's target track or keeps it library-wide; the choice persists to the thread.

2.7 Hands-free voice

• Deepgram STT + Aura-2 TTS on the chat surface.
• VAD loop with sensitivity presets so the mic does not trigger on the app's own playback.
• Voice is selectable per agent and persists per browser (localStorage), not per account — a server-side per-account voice preference is post-1.0.

2.8 Creative artifacts

• /tracks/:trackId/create generates a Blueprint, a Suno prompt, and chord variations from the track's DNA.
• ElevenLabs generates 30-second DNA-seeded sketches; each artifact takes 👍/👎 feedback that feeds the learned profile.

2.9 Correction log and learned profile

• Every DNA tag has a pencil-edit affordance.
• Corrections are logged to dna_corrections and surfaced as overrides on future reads.
• user_preferences aggregates corrections and artifact feedback into a per-user profile that steers later L3/L4 prompts.
• Threshold retuning happens between METHODOLOGY_VERSION bumps; single-user corrections never silently change methodology.

2.10 DNA visuals

Five dynamic visualizations below the specimen sheet: DNA Helix, Energy Ribbon, Chord Constellation, Section Contact Sheet, Confidence Weather.

2.11 Deletion and data control

• Delete a track from the library row or the track page: audio object, DNA blobs, analysis events, corrections, artifacts and their feedback, chat threads and messages all go. Billing rows survive de-linked.
• Delete the account from a typed-confirm Danger zone: everything above for every track, plus preferences, bug reports, usage events, the whole storage folder, and the auth user.

2.12 Operations

• analysis_events job ledger + header job-status indicator.
• api_usage_events with USD cost per call; /admin shows 30-day cost, per-provider breakdown, and the API-readiness matrix.
• Per-user daily spend caps on every paid path — Fadr, MusicAtlas, ElevenLabs, and all Gemini calls. Paid providers fail closed; the AI gateway fails open.
• Error boundaries and a route-level error component on all authenticated routes; /report-bug writes to bug_reports.

2.13 Landing / trust

• Marketing route at / describes the Isolate → Measure → Reason → Create flow.
• SEO metadata per route (title, description, og:*, twitter:card).
• Public documentation routes, all linked from a shared site footer and each downloadable as Markdown: /spec (this page), /methodology (the full method behind every number), /roadmap, /terms, /privacy, /report-bug. Terms and Privacy name every processor of uploaded audio and state the copyrighted-reference position.

3. Post-1.0 roadmap

Designed, not shipped. Live status: /roadmap.

• Server-side account voice preferences — move voice choice off localStorage.
• Hum-to-analyze — user hums, voice is isolated, pitch contour analyzed.
• Comparison mode — two-track radar over normalized L2 vectors with an LLM caption.
• Python-based L2 metrics — rhythmic density, groove signature, MERT embeddings, Essentia mood.
• Reference Scout Nebula — 2D projection of MusicAtlas embeddings as a taste map.
• `mio_relationships` — inspired_by / derived_blueprint / cover_of edges (deferred from MRE v2.1).
• pgvector "songs like this" — only meaningful past ~50 tracks in the system.

4. Data model

Public schema tables, all with RLS + explicit GRANTs:

• tracks — uploaded audio, status, stage, attempt, stems
• dna_blobs — L1/L2/L3 payload, provider, methodology version, provenance
• dna_corrections — user corrections keyed to (track_id, tag_path)
• analysis_events — per-stage job ledger
• api_usage_events — usage + USD cost per provider call
• chat_threads / chat_messages — agent sessions, scope track:<id> or global
• creative_artifacts — blueprints, Suno prompts, chord variations, snippets
• artifact_feedback — 👍/👎 on generated artifacts
• user_preferences — learned profile from corrections and feedback
• knowledge_items — admin knowledge library entries
• bug_reports — user-submitted bug reports (anonymous allowed; a forged user_id is rejected)

Storage: private tracks bucket (owner-only read) and knowledge.

Server functions touching user data use requireSupabaseAuth. The only public endpoint is /api/public/hooks/analysis-tick, which only advances jobs their owners already started.

5. Architecture

• Framework: TanStack Start v1 on Vite 7, React 19. SSR-capable, deployed to Cloudflare Workers (edge).
• Styling: Tailwind v4 via src/styles.css, semantic tokens only — no hardcoded colors.
• Backend: Lovable Cloud. App-internal logic uses createServerFn; cron and webhooks live under src/routes/api/public/*.
• AI: Lovable AI Gateway (Gemini) for interpretation, chat, and creative layers. Deepgram STT/TTS. ElevenLabs for snippets and fallback stems. Fadr for L1. MusicAtlas for catalog enrichment.
• DNA provider abstraction: MusicDNAProvider at src/lib/music-dna/provider.ts. Never hardcode a provider in feature code. The interface is documented as aspirational — no refactor was made for 1.0.

6. Aesthetics (locked)

The full design authority is published at /aesthetics — paper-and-ink color system, semantic layer tokens, the confidence-as-line-style rule, the coverage and grayscale tests, and the encoding of every visual. The rules below are the summary; the playbook wins on any aesthetic disagreement.

• Voice: specimen sheet, not dashboard. Reference: Braun product manuals, ECM record inserts, Muji signage.
• Numbers: font-variant-numeric: tabular-nums. Values right-aligned in tables.
• Borders: solid = measured, dashed = derived, muted = interpreted. Border is the confidence signal — no colored badges for confidence.
• Charts: line only. No gradient fills, no glow, no drop shadow.
• Chips: DNA tags are chips with a thin border; hover reveals the why string.
• Chat surface: transcript is the UI. Tool calls render as inline pill-shaped cards, not JSON.
• No generic AI aesthetic. No purple/indigo gradients. No Inter/Poppins as headline fonts.
• Motion encodes data, never decorates. Animation speed comes from confidence, weight from duration, opacity from frequency. No idle glow, no ambient shimmer.
• Wide data scrolls, the page does not. Anything wider than the viewport (chord ribbon, event ledger) lives in its own horizontal scroller; the document never scrolls sideways on a phone.

7. Release history

| v1.0.1 | Documentation pass: methodology published in-app at /methodology with a Markdown download, shared site footer across every public page, admin integration matrix corrected (Deepgram live), leftover test track purged. |

Live status: .lovable/plan.md. Operational procedure: docs/runbook.md. Test evidence: docs/release-test-record.md.

8. Non-goals

• Not a DAW. We do not replace Logic, Ableton, or FL Studio.
• Not a distribution platform. We do not publish to Spotify.
• Not a stock-music library. Snippets are sketches for the songwriter, not licensed cues.
• Not a general-purpose chatbot. Every agent is scoped to songwriting.

9. Canonical vocabulary (v2.0 arc)

An external architecture doc proposes a canonical vocabulary for this class of product: MIO, MRE, and Music Memory. We agree with the vocabulary and disagree with adopting it now. It is a naming upgrade, not an architecture change — the bones already match — and a rename pass before the product has paying users is churn without user-visible value.

Policy: ship 1.0 on the current code names. Adopt the canonical vocabulary as a v2.0 milestone gated on real paying users. The provider abstraction already isolates naming to a handful of files, so the future rename stays mechanical.

Definitions:

• MIO — Music Intelligence Object. The canonical, versioned, auditable data object every subsystem reads and writes. Today: our MusicDNA blob.
• MRE — Music Reasoning Engine. L1 measured → L2 derived → L3 interpreted → L4 creative → L5 adaptive. Today: src/lib/music-dna/ + src/lib/mre/.
• Music Memory. The per-user learned profile that steers future runs. Today: dna_corrections + user_preferences + artifact_feedback.

Adoption trigger: real paying users. Until then, we do not rename.

This spec is the source of truth for scope; `/methodology` is the source of truth for method. When it changes, bump `APP_VERSION` in `src/lib/app-version.ts` and keep `.lovable/plan.md` in sync.