chore(phase-0): stabilise foundation for Studio build

- Extract WAV assembly (buildWav, mergeFloat32Arrays, decodeFloat32Chunk, SAMPLE_RATE) into web/lib/audio/wav.ts so it can be reused by the Studio playback engine and library waveform previews - Add server/waveform.py with compute_peaks() / write_peaks() — reads any WAV, mixes to mono, returns min/max peak arrays matching the WaveformPeaks TypeScript type - Add server/ids.py with prefixed URL-safe ID helpers (gen_id, proj_id, asset_id, etc.) using stdlib secrets — no new dependency - Add docs/studio-build-plan.md — full execution spec covering stack decisions, data models, API contract, component hierarchy, phase breakdown and acceptance criteria - Ignore data/ directory (generated audio, waveforms, SQLite DB)
2026-06-13 03:58:07 +00:00 · 2026-05-02 17:24:45 +01:00
parent 0236807928
commit 47e0c7e512
6 changed files with 1098 additions and 48 deletions
@@ -20,8 +20,12 @@ web/tsconfig.tsbuildinfo
 web/next-env.d.ts
 web/node_modules/
 # Generated data (audio files, waveforms, SQLite DB)
 data/
 # OS
 .DS_Store
 Thumbs.db
 .vscode/settings.json
 .claude/settings.local.json
 *.txt
@@ -0,0 +1,925 @@
 # VibePod Studio — Build Plan
 **Version:** 1.0  
 **Authors:** LyAhn + Claude (Anthropic) + Codex  
 **Date:** 2026-05-02  
 **Status:** Active
 ---
 ## Table of Contents
 1. [Product Goal](#1-product-goal)
 2. [Current Architecture](#2-current-architecture)
 3. [Locked Technical Decisions](#3-locked-technical-decisions)
 4. [Non-Goals](#4-non-goals)
 5. [Data Models](#5-data-models)
 6. [Storage Layout](#6-storage-layout)
 7. [API Contract](#7-api-contract)
 8. [Frontend Routes](#8-frontend-routes)
 9. [Component Hierarchy](#9-component-hierarchy)
 10. [Timeline Rendering Model](#10-timeline-rendering-model)
 11. [Playback Model](#11-playback-model)
 12. [Export Rendering Model](#12-export-rendering-model)
 13. [Phase Breakdown](#13-phase-breakdown)
 14. [Acceptance Criteria](#14-acceptance-criteria)
 15. [Deferred Decisions](#15-deferred-decisions)
 16. [Third-Party Library Policy](#16-third-party-library-policy)
 ---
 ## 1. Product Goal
 VibePod becomes a **script-aware AI podcast creation studio** where users can generate, arrange, edit, regenerate, and export podcast episodes from written scripts.
 The headline feature that differentiates VibePod from generic audio editors:
 > Every generated clip knows where it came from in the script and can be regenerated, replaced, or compared — without touching the original audio file.
 The existing fast-generation page stays as the quick path. Studio grows alongside it.
 ---
 ## 2. Current Architecture
 ### What exists today
 | Layer | Details |
 |---|---|
 | Frontend | Next.js 15 · React 19 · TypeScript 5 · Tailwind CSS 4 · App Router |
 | Backend | FastAPI · uvicorn · Python 3.10+ |
 | Model | VibeVoice Realtime 0.5B via JezzWTF fork |
 | Audio format | 24 kHz · float32 PCM · streamed as SSE · assembled to WAV in browser |
 | State management | React `useReducer` in `page.tsx` — no Zustand, no Redux |
 | Persistence | None — generated audio is an ephemeral browser Blob |
 | Packages | pnpm workspace (frontend) · uv (Python) |
 ### Current generation flow
 ```
 User submits script
  → POST /api/generate (Next.js proxy)
  → POST /generate (FastAPI)
  → VibeVoice inference thread
  → SSE stream of base64 float32 PCM chunks
  → Browser decodes chunks, adaptive buffering, live Web Audio playback
  → On complete: chunks merged, RIFF/WAV header prepended, Blob URL created
  → User can play back or download the WAV
 ```
 ### Key files
 ```
 web/
  app/
    page.tsx                    main generation UI (AppState via useReducer)
    api/generate/route.ts       SSE proxy to FastAPI
    api/health/route.ts         health check proxy
  components/
    Header.tsx
    TextInputPanel.tsx
    AudioPlayer.tsx
    GenerationControls.tsx
    StatusLog.tsx
  hooks/
    useStreamingGeneration.ts   core streaming + WAV assembly
    useAudioPlayer.ts           HTML5 audio element wrapper
 server/
  vibevoice_server.py           entire FastAPI app (972 lines)
  start.sh                      launcher (CPU/CUDA detection, uv sync, uvicorn)
  download_model.py             HuggingFace prefetch
 docs/
  studio-build-plan.md          this file
 roadmap.md                      high-level phase vision
 DESIGN.md                       brand + design system (colours, type, spacing)
 AGENTS.md                       AI agent / CI guide
 ```
 ---
 ## 3. Locked Technical Decisions
 These decisions are final and must not be revisited without explicit agreement. New phases build on them.
 ### 3.1 Rendering approach — Hybrid DOM + Canvas 2D
 The Studio uses a **hybrid rendering model**:
 | Layer | Technology |
 |---|---|
 | App shell, layout, sidebars, panels, inspector | React + Tailwind CSS (DOM) |
 | Track headers, controls, transport, modals | React + Tailwind CSS (DOM) |
 | Timeline clip containers + positioning | React + CSS (`left`/`width` from time → pixels) |
 | Waveform rendering inside clips | Raw Canvas 2D |
 | Timeline ruler | Raw Canvas 2D |
 | Playhead overlay | Raw Canvas 2D |
 | Browser playback preview | Web Audio API |
 | Final render + export | Python + FFmpeg (server-side only) |
 **Why not full canvas:** Every non-waveform element — buttons, text, inputs, scroll, keyboard focus, accessibility — works better in DOM. Reimplementing all of that in canvas is wasted effort.
 **Why not pure CSS:** Waveform peaks are thousands of pixel-height values per clip. DOM representation would be extremely slow. Canvas draws them in a tight loop in milliseconds.
 **Why not WaveSurfer.js as the core:** WaveSurfer owns playback and its own event model. VibePod Studio needs its own clip model, its own timeline, and eventually its own multi-track playback. Adapting around WaveSurfer's assumptions creates friction. It may be used for standalone audio preview components (e.g., the generation page player), not the Studio timeline.
 **Why not Konva.js:** Overkill for v1. Konva is designed for fully canvas-based scenes (whiteboards, diagrams). VibePod's timeline is mostly DOM. The additional mental model (Stage/Layer/Group/Transformer) is not justified unless interaction complexity grows significantly beyond v1.
 ### 3.2 Frontend stack — No additions without justification
 Build inside the existing stack. New packages require a written reason in this document.
 **Approved additions (to be installed when their phase begins):**
 | Package | Purpose | Phase |
 |---|---|---|
 | `zustand` | Studio editor state | Phase 2 |
 | `@dnd-kit/core` + `@dnd-kit/utilities` | Clip drag-and-drop in timeline | Phase 2 |
 | `better-sqlite3` | SQLite for job and project persistence | Phase 1 |
 **Conditionally approved (evaluate at phase start):**
 | Package | Purpose | Condition |
 |---|---|---|
 | `framer-motion` | Clip move animations | Only if DnD-kit transitions feel rough after prototype |
 | `@radix-ui/react-*` | Accessible modal/dropdown primitives | Only if building custom is taking too long |
 ### 3.3 Backend stack — Python + FFmpeg for all rendering
 Browser-side audio mixing is only for **preview**. Export always goes to the Python backend.
 **Approved backend additions:**
 | Package | Purpose | Phase |
 |---|---|---|
 | `soundfile` | Already present — WAV read/write | Phase 1 |
 | `numpy` | Audio array manipulation | Phase 1 |
 | `pydub` | Audio trimming, mixing, concatenation | Phase 2 |
 | `pyloudnorm` | Loudness normalisation (LUFS) | Phase 5 |
 FFmpeg must be available on the server host. The render endpoint assumes `ffmpeg` is on PATH.
 ### 3.4 State management — Zustand for Studio, useReducer stays on generation page
 The existing generation page uses `useReducer` and works well. Do not refactor it.
 Studio requires a shared store that multiple components read and write (timeline, inspector, transport, script panel). Zustand is the right tool. It is lightweight, does not require providers, and handles editor-style state (undo stacks, selection, playhead) cleanly.
 ### 3.5 Database — SQLite from Phase 1
 Do not start with flat JSON files. SQLite is still a single file, requires no server process, and gives proper queries, transactions, and schema migrations from day one. Use `better-sqlite3` in the Next.js API layer.
 Schema lives in `web/lib/db/schema.sql`. Migrations are numbered SQL files in `web/lib/db/migrations/`.
 ### 3.6 Audio sample rate
 All generated audio is 24 kHz float32 mono (VibeVoice output). Studio renders at 44.1 kHz stereo WAV or 48 kHz for podcast MP3 export. The render pipeline handles resampling.
 ---
 ## 4. Non-Goals
 These will not be built and must not creep in:
 - **Real-time collaborative editing** — single-user per project only
 - **Cloud sync or user accounts** — local-first, no auth system
 - **MIDI or music composition** — audio clips only, no MIDI tracks
 - **Plugin system** — no third-party audio plugin API
 - **Browser-side FFmpeg (ffmpeg.wasm)** — all rendering is server-side
 - **Mobile / responsive Studio layout** — Studio targets desktop viewport only
 - **Offline PWA** — the server must be running; no service worker caching of model output
 - **Real-time voice cloning** — out of scope until VibeVoice supports it cleanly
 - **Exporting to streaming platforms** — export to file only; no Spotify/Apple Podcasts upload
 ---
 ## 5. Data Models
 ### 5.1 Generation job
 ```ts
 type GenerationJob = {
  id: string;                      // "gen_<nanoid>"
  createdAt: string;               // ISO 8601
  status: "pending" | "generating" | "complete" | "error" | "cancelled";
  script: string;
  speaker: string;
  cfgScale: number;
  inferenceSteps: number;
  durationSecs: number | null;     // set on complete
  sampleRate: number;              // always 24000
  audioPath: string | null;        // relative to data/generations/<id>/audio.wav
  waveformPath: string | null;     // relative to data/generations/<id>/waveform.json
  errorMessage: string | null;
 };
 ```
 ### 5.2 Studio project
 ```ts
 type StudioProject = {
  id: string;                      // "proj_<nanoid>"
  name: string;
  createdAt: string;
  updatedAt: string;
  script: ScriptDocument;
  assets: AudioAsset[];
  tracks: Track[];
  edits: EditOperation[];
  renderSettings: RenderSettings;
 };
 ```
 ### 5.3 Script document
 ```ts
 type ScriptDocument = {
  blocks: ScriptBlock[];
 };
 type ScriptBlock = {
  id: string;                      // "block_<nanoid>"
  speakerId: string;
  text: string;
  order: number;
  generatedAssetId: string | null;
  timelineClipIds: string[];
 };
 ```
 ### 5.4 Audio asset
 ```ts
 type AudioAsset = {
  id: string;                      // "asset_<nanoid>"
  projectId: string | null;        // null = generation library asset
  kind: "generated_voice" | "upload" | "music" | "sfx" | "render";
  filePath: string;
  durationSecs: number;
  sampleRate: number;
  channels: number;
  waveformPath: string | null;
  source: {
    generationJobId?: string;
    scriptBlockId?: string;
    providerId?: string;
    modelId?: string;
    voiceId?: string;
    settings?: Record<string, unknown>;
  } | null;
 };
 ```
 ### 5.5 Track
 ```ts
 type Track = {
  id: string;                      // "track_<nanoid>"
  name: string;
  type: "voice" | "music" | "sfx" | "ambience" | "master";
  order: number;
  muted: boolean;
  solo: boolean;
  gainDb: number;
  clips: TimelineClip[];
 };
 ```
 ### 5.6 Timeline clip
 ```ts
 type TimelineClip = {
  id: string;                      // "clip_<nanoid>"
  assetId: string;
  trackId: string;
  startTime: number;               // seconds from timeline origin
  sourceStart: number;             // trim start within source asset (seconds)
  sourceEnd: number;               // trim end within source asset (seconds)
  gainDb: number;
  fadeInMs: number;
  fadeOutMs: number;
  linkedScriptRange: {
    blockId: string;
    startChar: number;
    endChar: number;
  } | null;
 };
 ```
 ### 5.7 Edit operation (non-destructive EDL)
 ```ts
 type EditOperation =
  | { type: "split";  clipId: string; at: number }
  | { type: "trim";   clipId: string; sourceStart: number; sourceEnd: number }
  | { type: "move";   clipId: string; startTime: number; trackId: string }
  | { type: "gain";   clipId: string; gainDb: number }
  | { type: "fade";   clipId: string; fadeInMs: number; fadeOutMs: number }
  | { type: "delete"; clipId: string }
  | { type: "mute";   trackId: string; muted: boolean }
  | { type: "solo";   trackId: string; solo: boolean };
 ```
 ### 5.8 Take (regeneration history)
 ```ts
 type Take = {
  id: string;                      // "take_<nanoid>"
  scriptBlockId: string;
  assetId: string;
  voiceId: string;
  modelId: string;
  settings: Record<string, unknown>;
  createdAt: string;
  rating: number | null;           // 1-5 stars, optional
  notes: string | null;
  isActive: boolean;               // true = the one placed on the timeline
 };
 ```
 ### 5.9 Render settings
 ```ts
 type RenderSettings = {
  format: "wav" | "mp3";
  sampleRate: 44100 | 48000;
  bitrate: number | null;          // kbps, null for WAV
  normaliseLoudness: boolean;
  lufsTarget: number;              // default -16 LUFS for podcast
  metadata: {
    title: string;
    artist: string;
    album: string;
    episodeNumber: number | null;
    description: string;
  } | null;
 };
 ```
 ### 5.10 Waveform peaks
 ```ts
 type WaveformPeaks = {
  sampleRate: number;
  durationSecs: number;
  channels: number;
  samplesPerPixel: number;
  length: number;
  data: {
    min: number[];                 // range -1.0 to 0.0
    max: number[];                 // range 0.0 to 1.0
  };
 };
 ```
 ---
 ## 6. Storage Layout
 ```
 data/
  generations/
    gen_<id>/
      audio.wav                   raw float32 WAV at 24 kHz
      waveform.json               WaveformPeaks at 256 samples/pixel
      metadata.json               GenerationJob fields (denormalised)
  projects/
    proj_<id>/
      project.json                full StudioProject serialised
      assets/
        asset_<id>.wav            uploaded or imported audio
      renders/
        render_<timestamp>.wav    exported renders
        render_<timestamp>.mp3
  db/
    vibepod.db                    SQLite database
 ```
 The SQLite database is the source of truth for IDs, status, and relationships. JSON files are the source of truth for audio and waveform data.
 ---
 ## 7. API Contract
 All new routes are under `/api/`. The Next.js app proxies to FastAPI only for generation and health. Persistence routes are handled directly by Next.js API routes talking to SQLite.
 ### 7.1 Generation (existing, extended)
 ```
 POST   /api/generate                   start streaming generation (existing)
 GET    /api/health                     server health check (existing)
 ```
 ### 7.2 Generation library (Phase 1)
 ```
 GET    /api/generations                list all jobs, newest first
                                       query: ?limit=20&offset=0&status=complete
 GET    /api/generations/:id            get single job metadata
 GET    /api/generations/:id/audio      stream WAV file
 GET    /api/generations/:id/waveform   get WaveformPeaks JSON
 DELETE /api/generations/:id            delete job and files
 ```
 ### 7.3 Projects (Phase 2)
 ```
 POST   /api/projects                   create project
 GET    /api/projects                   list projects
 GET    /api/projects/:id               get project with full StudioProject
 PUT    /api/projects/:id               save/autosave project
 DELETE /api/projects/:id               delete project and assets
 ```
 ### 7.4 Project assets (Phase 2)
 ```
 POST   /api/projects/:id/assets        upload audio file or import from generation
 GET    /api/projects/:id/assets/:aid   get asset metadata
 DELETE /api/projects/:id/assets/:aid   remove asset
 ```
 ### 7.5 Takes (Phase 3)
 ```
 GET    /api/projects/:id/takes/:blockId         list takes for a script block
 POST   /api/projects/:id/takes/:blockId         save new take
 PUT    /api/projects/:id/takes/:blockId/:takeId  set active take
 DELETE /api/projects/:id/takes/:blockId/:takeId  delete take
 ```
 ### 7.6 Render (Phase 5)
 ```
 POST   /api/projects/:id/render        start render job (sends EDL to Python)
 GET    /api/projects/:id/renders       list render history
 GET    /api/projects/:id/renders/:rid  poll render status
 GET    /api/projects/:id/renders/:rid/download  stream rendered file
 ```
 All error responses follow:
 ```json
 { "error": "human-readable message", "code": "SNAKE_CASE_CODE" }
 ```
 ---
 ## 8. Frontend Routes
 ```
 /                                  generation page (current fast path, unchanged)
 /library                           generation library — browse and replay saved jobs
 /projects                          project dashboard — create or open Studio projects
 /studio/:projectId                 Studio workspace
 /studio/new                        redirect: creates project + navigates to /studio/:id
 ```
 ---
 ## 9. Component Hierarchy
 ### Generation page (existing — do not restructure without reason)
 ```
 page.tsx
  Header
  TextInputPanel
  GenerationControls
  StatusLog
  AudioPlayer
 ```
 ### Library page (Phase 1)
 ```
 /app/library/page.tsx
  Header
  LibraryPage
    GenerationCard[]
      WaveformPreview          (small static canvas render of peaks)
      GenerationMetadata       (speaker, duration, date, settings)
      GenerationActions        (play, download, open in studio, delete)
 ```
 ### Projects dashboard (Phase 2)
 ```
 /app/projects/page.tsx
  Header
  ProjectsPage
    NewProjectButton
    ProjectCard[]
      ProjectThumbnail
      ProjectMetadata
      ProjectActions
 ```
 ### Studio workspace (Phase 2+)
 ```
 /app/studio/[projectId]/page.tsx
  StudioShell
    StudioTopBar
      ProjectNameInput
      UndoButton / RedoButton
      SaveStatus
      ExportButton
    StudioBody
      ProjectSidebar
        SidebarTabs (Script | Voices | Media | Effects | Templates)
        ScriptPanel           (Phase 3)
        VoicesPanel
        MediaBin              (Phase 2)
        EffectsPanel          (Phase 4)
      StudioMain
        TimelineRuler         (canvas)
        TimelineArea
          TimelineTrack[]     (one per track)
            TrackHeader
            TrackClipArea
              TimelineClip[]
                WaveformCanvas  (canvas)
                ClipLabel
      InspectorPanel
        ClipInspector         (when clip selected)
          ClipMetadata
          GainControl
          FadeControls
          RegenerateButton    (Phase 3)
          TakeStack           (Phase 3)
        TrackInspector        (when track selected)
        EmptyInspector        (nothing selected)
    TransportBar
      PlayPauseButton
      StopButton
      PlayheadTimeDisplay
      ZoomControls
      SnapToggle
 ```
 ---
 ## 10. Timeline Rendering Model
 ### Clip positioning
 Timeline clips are DOM elements with CSS `position: absolute`. Position and size derive from the project's pixels-per-second zoom level:
 ```ts
 const left = clip.startTime * pixelsPerSecond;
 const width = (clip.sourceEnd - clip.sourceStart) * pixelsPerSecond;
 ```
 The `pixelsPerSecond` value lives in Zustand and changes with zoom. All clip positions recompute via derived selectors.
 ### Waveform canvas
 Each `TimelineClip` contains a `<canvas>` element that receives peak data as a prop. The renderer draws one vertical line per pixel column:
 ```ts
 function drawWaveform(
  ctx: CanvasRenderingContext2D,
  peaks: WaveformPeaks,
  width: number,
  height: number,
  color: string
 ): void {
  const midY = height / 2;
  ctx.clearRect(0, 0, width, height);
  ctx.strokeStyle = color;
  ctx.lineWidth = 1;
  for (let x = 0; x < width; x++) {
    const peakIndex = Math.floor((x / width) * peaks.length);
    const minY = midY + peaks.data.min[peakIndex] * midY;
    const maxY = midY - peaks.data.max[peakIndex] * midY;
    ctx.beginPath();
    ctx.moveTo(x + 0.5, minY);
    ctx.lineTo(x + 0.5, maxY);
    ctx.stroke();
  }
 }
 ```
 The canvas rerenders when `width`, `peaks`, or zoom changes. It does not rerender on playback.
 ### Playhead
 The playhead is a separate absolutely-positioned element (thin vertical line) that overlays the entire timeline area. Its `left` position is updated via `requestAnimationFrame` during playback — no React state updates, direct DOM style write.
 ### Timeline ruler
 A `<canvas>` element spanning the full timeline width. Draws time markers at intervals derived from current zoom level. Rerenders on zoom change only.
 ---
 ## 11. Playback Model
 Studio preview uses the **Web Audio API**, not HTML5 `<audio>`.
 ### Graph
 ```
 AudioBufferSourceNode (per clip)
  → GainNode (clip gain + fades)
    → GainNode (track gain)
      → GainNode (master gain)
        → AudioContext.destination
 ```
 ### Scheduling
 On play, the engine:
 1. Reads current `playheadTime` from Zustand.
 2. For each clip where `clip.startTime + (clip.sourceEnd - clip.sourceStart) > playheadTime`:
   - Calculates `offset = playheadTime - clip.startTime + clip.sourceStart` (clamped to 0)
   - Calls `source.start(audioCtx.currentTime, offset)`
 3. All sources start in sync via a shared `startTime = audioCtx.currentTime + 0.01` anchor.
 On stop or seek, all sources are disconnected and the graph is torn down. A new graph is built on the next play call.
 ### Audio buffer cache
 Fetched WAV files are decoded to `AudioBuffer` via `AudioContext.decodeAudioData()` and cached by asset ID. Cache is invalidated if the asset is deleted or replaced.
 ### Fade implementation
 Fades are implemented as `AudioParam` ramps on the clip GainNode:
 ```ts
 gainNode.gain.setValueAtTime(0, startTime);
 gainNode.gain.linearRampToValueAtTime(clipGain, startTime + fadeInSecs);
 gainNode.gain.setValueAtTime(clipGain, endTime - fadeOutSecs);
 gainNode.gain.linearRampToValueAtTime(0, endTime);
 ```
 ---
 ## 12. Export Rendering Model
 When the user triggers export, the frontend sends a render request to the Python backend. The browser is never involved in mixing.
 ### Request payload
 ```ts
 type RenderRequest = {
  projectId: string;
  tracks: Track[];
  clips: TimelineClip[];
  assets: Array<{ id: string; filePath: string }>;
  settings: RenderSettings;
 };
 ```
 ### Python render pipeline
 ```python
 # Pseudocode — actual implementation lives in server/render.py
 def render_project(req: RenderRequest) -> str:
    # 1. Load all source audio files into numpy arrays
    # 2. Determine total timeline duration
    # 3. Create output buffer (zeros) at target sample rate
    # 4. For each clip (sorted by startTime):
    #    a. Load source audio
    #    b. Resample to target sample rate if needed
    #    c. Apply trim (sourceStart → sourceEnd)
    #    d. Apply gain (dB → linear)
    #    e. Apply fade in/out (linear ramp)
    #    f. Place at clip.startTime offset in output buffer
    # 5. Apply track gain to each track's summed signal
    # 6. Sum all tracks into master buffer
    # 7. Apply master gain
    # 8. If normaliseLoudness: apply pyloudnorm to target LUFS
    # 9. Export WAV or MP3 via soundfile / ffmpeg
    # 10. Write to data/projects/<id>/renders/<timestamp>.wav
    # 11. Return file path
 ```
 Render runs in a background thread. The client polls `GET /api/projects/:id/renders/:rid` for status.
 ---
 ## 13. Phase Breakdown
 ### Phase 0 — Stabilise (current state → pre-Phase 1)
 **Goal:** Clean foundation. No new features.
 Tasks:
 - [ ] Extract WAV assembly from `useStreamingGeneration.ts` into `web/lib/audio/wav.ts`
 - [ ] Extract waveform peak generation into `server/waveform.py`
 - [ ] Confirm generation cancellation works cleanly (stream abort + server cancel_event)
 - [ ] Add `nanoid` to backend for stable generation IDs
 - [ ] Add `data/` directory to `.gitignore`
 **Acceptance:** WAV assembly is a pure function with unit tests. Generation IDs are stable.
 ---
 ### Phase 1 — Persistent Generation Library
 **Goal:** Every generation is saved. Users can browse, play, and download past generations.
 **Backend tasks:**
 - [ ] Add SQLite setup (`data/db/vibepod.db`, schema migration 001)
 - [ ] `generations` table: `id, created_at, status, script, speaker, cfg_scale, inference_steps, duration_secs, sample_rate, audio_path, waveform_path, error_message`
 - [ ] On generation complete: save WAV to `data/generations/<id>/audio.wav`
 - [ ] On generation complete: compute and save waveform peaks to `data/generations/<id>/waveform.json`
 - [ ] Implement `GET /api/generations` (list, paginated)
 - [ ] Implement `GET /api/generations/:id` (single)
 - [ ] Implement `GET /api/generations/:id/audio` (stream file)
 - [ ] Implement `GET /api/generations/:id/waveform` (peaks JSON)
 - [ ] Implement `DELETE /api/generations/:id` (delete row + files)
 **Frontend tasks:**
 - [ ] Install `better-sqlite3` + types
 - [ ] Create `web/lib/db/` — schema, migration runner, query helpers
 - [ ] Create `/library` route and `LibraryPage` component
 - [ ] `GenerationCard` component: waveform preview canvas, metadata, play/download/delete actions
 - [ ] `WaveformPreview` component: draws peaks on canvas (static, no playback)
 - [ ] Mini audio player for library card playback (reuse `useAudioPlayer` hook)
 - [ ] Link "Open in Studio" button (navigates to `/studio/new?fromGeneration=<id>`)
 - [ ] Add "Library" link to `Header`
 **Acceptance:**
 - Generate audio → close browser → reopen → generation appears in library with waveform
 - Play button plays correct audio
 - Delete removes from library and disk
 - Library renders without error when empty
 ---
 ### Phase 2 — Studio MVP
 **Goal:** Single-track timeline editor. Open a generation, view waveform, trim/split/delete, export WAV.
 **Backend tasks:**
 - [ ] `projects` table: `id, name, created_at, updated_at, project_json`
 - [ ] `assets` table: `id, project_id, kind, file_path, duration_secs, sample_rate, channels, waveform_path, source_json`
 - [ ] Implement `POST /api/projects`
 - [ ] Implement `GET /api/projects` (list)
 - [ ] Implement `GET /api/projects/:id`
 - [ ] Implement `PUT /api/projects/:id` (save)
 - [ ] Implement `DELETE /api/projects/:id`
 - [ ] Implement `POST /api/projects/:id/assets` (import from generation or upload)
 - [ ] Implement basic render endpoint (single voice track, WAV out only)
 **Frontend tasks:**
 - [ ] Install `zustand`, `@dnd-kit/core`, `@dnd-kit/utilities`
 - [ ] Create Studio Zustand store (`web/stores/studioStore.ts`)
  - Project state, selected clip, playhead time, zoom, isPlaying, undo stack
  - Actions: selectClip, moveClip, splitClip, trimClip, setClipGain, undo, redo
 - [ ] Create `/projects` route and dashboard
 - [ ] Create `/studio/[projectId]` route
 - [ ] `StudioShell` — top-level layout
 - [ ] `StudioTopBar` — project name, undo/redo, save status, export button
 - [ ] `ProjectSidebar` — tabs shell + `MediaBin` tab
 - [ ] `MediaBin` — list assets, drag to timeline
 - [ ] `TimelineArea` — scrollable container with tracks
 - [ ] `TimelineRuler` — canvas ruler, rerenders on zoom
 - [ ] `TimelineTrack` — track header + clip area
 - [ ] `TimelineClip` — positioned div, selectable, draggable
 - [ ] `WaveformCanvas` — canvas inside clip, draws peaks
 - [ ] `InspectorPanel` — shows selected clip properties
 - [ ] `TransportBar` — play/pause/stop, time display, zoom slider
 - [ ] Web Audio playback engine (`web/lib/audio/playbackEngine.ts`)
 - [ ] Autosave: debounced PUT on every store change (500ms delay)
 - [ ] Export dialog: format picker → POST /api/projects/:id/render → poll → download
 **Acceptance:**
 - Open generation from library → Studio loads with waveform on single track
 - Play button plays audio in sync with playhead
 - Drag clip moves it on timeline
 - Split at playhead creates two clips
 - Trim handles reduce clip duration
 - Delete removes clip
 - Export produces downloadable WAV
 - Undo/redo works for all operations
 ---
 ### Phase 3 — Script-Linked Regeneration
 **Goal:** Script blocks are the source of truth. Clicking a clip highlights the script. Regenerating a clip produces a new take.
 **Backend tasks:**
 - [ ] `takes` table: `id, project_id, script_block_id, asset_id, voice_id, model_id, settings_json, created_at, rating, notes, is_active`
 - [ ] Implement takes API endpoints (list, create, set active, delete)
 - [ ] Waveform peak generation on regenerated takes
 **Frontend tasks:**
 - [ ] `ScriptPanel` sidebar tab — editable script blocks with speaker labels
 - [ ] Script block → clip bidirectional linking (click clip → highlight block, click block → select clip)
 - [ ] Clip inspector: show source script text (read-only in Phase 3)
 - [ ] `RegenerateButton` in inspector — sends block text + current voice settings → new generation
 - [ ] Regeneration creates new Take, new Asset, new Clip (does not replace existing clip automatically)
 - [ ] `TakeStack` in inspector — list takes for selected block, click to preview, "Replace in timeline" action
 - [ ] Per-block voice setting override (speaker, cfg_scale, inference_steps)
 **Acceptance:**
 - Clicking a clip selects the related script block in ScriptPanel
 - Clicking a script block selects the clip on the timeline
 - Regenerate produces a new take visible in TakeStack
 - "Replace in timeline" swaps the clip's asset to the new take
 - Previous take is preserved and can be restored
 - Undo works across take replacements
 ---
 ### Phase 4 — Multi-Speaker Podcast Builder
 **Goal:** Multiple voice tracks, music/SFX tracks, speaker assignment, show templates.
 **Tasks:**
 - [ ] Multiple tracks: Host, Guest, Music, SFX, Ambience
 - [ ] Track type icons and colour coding per track type
 - [ ] Per-track mute/solo buttons (functional in Web Audio engine)
 - [ ] Track gain slider
 - [ ] Speaker assignment per track (voice preset tied to track)
 - [ ] Music/SFX uploads to media bin
 - [ ] Basic music ducking on voice tracks (auto-gain on music track when voice plays)
 - [ ] Show template: save a project's track layout + speaker assignments as a reusable template
 - [ ] Template picker on new project creation
 **Acceptance:**
 - Two voice tracks play independently and mix correctly
 - Mute/solo work
 - Music bed plays under voice tracks
 - Saving as template creates a new project correctly
 - Exported WAV contains all tracks mixed
 ---
 ### Phase 5 — Production Export
 **Goal:** MP3 export, loudness normalisation, podcast metadata, render queue, mastering presets.
 **Tasks:**
 - [ ] MP3 export via FFmpeg on render backend
 - [ ] `pyloudnorm` integration — LUFS targeting per preset
 - [ ] Export presets: Podcast Balanced, Podcast Loud, Audiobook, Raw WAV, YouTube Audio
 - [ ] ID3 metadata fields in export dialog (title, artist, episode number, cover art, description)
 - [ ] Render job queue — multiple renders can be queued
 - [ ] Render status polling with progress bar
 - [ ] Render history panel in project
 - [ ] Autosave recovery: on crash/close, restore last autosaved state on next open
 **Acceptance:**
 - MP3 export produces valid file with correct ID3 tags
 - Loudness normalisation hits target LUFS ± 0.5
 - Render queue processes jobs sequentially
 - Recovering an autosave restores timeline to last saved state
 ---
 ## 14. Acceptance Criteria
 ### Cross-cutting criteria (all phases)
 - No TypeScript `any` types anywhere in Studio code
 - Zustand store actions are pure (no side effects except explicit async actions)
 - Autosave never blocks the UI thread
 - Undo/redo covers every timeline mutation
 - No orphaned audio files — deleting a project deletes its files
 - Waveform canvas does not rerender on playback (only on zoom/resize)
 - Playhead position updates at 60fps via `requestAnimationFrame`, not React state
 ---
 ## 15. Deferred Decisions
 These are intentionally not decided yet. Revisit at the phase that needs them.
 | Decision | Deferred until |
 |---|---|
 | Voice cloning / custom voice upload | Depends on VibeVoice roadmap |
 | XTTS or ElevenLabs as second provider | Phase 3+ — only after VoiceModelProvider abstraction is proven |
 | Clip crossfades (overlapping clips) | Phase 4 — requires mixing model update |
 | Clip-level EQ / compression | Phase 5 |
 | Per-segment emotion / style tags | Phase 3 evaluation |
 | WebSocket vs SSE for render progress | Phase 5 — evaluate based on render durations seen in practice |
 | IndexedDB caching of AudioBuffers | Phase 2 evaluation — only if cache miss latency is a real problem |
 | Noise gate / background removal | Post-Phase 5 |
 | Multi-window Studio (popout inspector etc.) | Not planned |
 ---
 ## 16. Third-Party Library Policy
 VibePod is an open-source project. Any third-party library integrated into the codebase must satisfy:
 1. **License:** MIT, Apache 2.0, BSD 2/3-Clause, or ISC. No GPL unless the entire application is separately GPL-licensed. No CC-NC.
 2. **Attribution:** Add to a `LICENSES.md` file in the repo root when integrating. Include library name, version, license type, and project URL.
 3. **Size:** For frontend packages, run `bundlephobia` before adding. Prefer packages under 20 kB gzipped unless there is no alternative.
 4. **Maintenance:** Prefer packages with active maintenance. Check last commit date and open issue count before adding.
 5. **Source code:** If copying or adapting a snippet (not a full package), add an inline comment with the source URL and license.
 ---
 *This document is the execution specification. The high-level vision lives in `roadmap.md`. When in doubt about scope, refer to Section 4 (Non-Goals) first.*
@@ -0,0 +1,35 @@
 """Stable, URL-safe ID generation for VibePod entities."""
 import secrets
 def _make_id(prefix: str) -> str:
    return f"{prefix}_{secrets.token_urlsafe(8)}"
 def gen_id() -> str:
    return _make_id("gen")
 def proj_id() -> str:
    return _make_id("proj")
 def asset_id() -> str:
    return _make_id("asset")
 def track_id() -> str:
    return _make_id("track")
 def clip_id() -> str:
    return _make_id("clip")
 def block_id() -> str:
    return _make_id("block")
 def take_id() -> str:
    return _make_id("take")
@@ -0,0 +1,77 @@
 """Waveform peak generation for VibePod.
 Reads a WAV file and produces min/max peak arrays suitable for canvas rendering.
 The output format matches the WaveformPeaks TypeScript type in the frontend.
 """
 from __future__ import annotations
 import json
 from pathlib import Path
 import numpy as np
 import soundfile as sf
 def compute_peaks(
    audio_path: str | Path,
    samples_per_pixel: int = 256,
 ) -> dict:
    """Compute min/max waveform peaks from a WAV file.
    Args:
        audio_path: Path to a WAV file (any bit depth, any channel count).
        samples_per_pixel: How many audio samples are condensed into one peak pair.
                           256 is a good default for a ~1000px wide waveform at
                           standard podcast lengths.
    Returns:
        A dict matching the WaveformPeaks TypeScript type:
        {
            "sampleRate": int,
            "durationSecs": float,
            "channels": int,
            "samplesPerPixel": int,
            "length": int,           # number of peak pairs
            "data": {
                "min": [float, ...], # values in [-1.0, 0.0]
                "max": [float, ...], # values in [0.0, 1.0]
            }
        }
    """
    samples, sample_rate = sf.read(str(audio_path), dtype="float32", always_2d=True)
    # Mix to mono by averaging channels
    mono = samples.mean(axis=1)
    total_samples = len(mono)
    duration_secs = total_samples / sample_rate
    channels = samples.shape[1]
    # Pad so total_samples is divisible by samples_per_pixel
    remainder = total_samples % samples_per_pixel
    if remainder:
        pad = samples_per_pixel - remainder
        mono = np.concatenate([mono, np.zeros(pad, dtype=np.float32)])
    frames = mono.reshape(-1, samples_per_pixel)
    peak_min = frames.min(axis=1).tolist()
    peak_max = frames.max(axis=1).tolist()
    length = len(peak_min)
    return {
        "sampleRate": int(sample_rate),
        "durationSecs": round(duration_secs, 4),
        "channels": int(channels),
        "samplesPerPixel": samples_per_pixel,
        "length": length,
        "data": {
            "min": [round(float(v), 5) for v in peak_min],
            "max": [round(float(v), 5) for v in peak_max],
        },
    }
 def write_peaks(audio_path: str | Path, output_path: str | Path, samples_per_pixel: int = 256) -> None:
    """Compute peaks and write them to a JSON file."""
    peaks = compute_peaks(audio_path, samples_per_pixel)
    Path(output_path).write_text(json.dumps(peaks, separators=(",", ":")), encoding="utf-8")
@@ -1,8 +1,8 @@
 "use client";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { buildWav, decodeFloat32Chunk, mergeFloat32Arrays, SAMPLE_RATE } from "@/lib/audio/wav";
 const SAMPLE_RATE = 24_000;
 const DEFAULT_PREBUFFER_SECS = 5.0;
 const DEFAULT_REBUFFER_THRESHOLD_SECS = 1.0;
 const DEFAULT_RESUME_THRESHOLD_SECS = 3.0;
@@ -30,53 +30,6 @@ interface UseStreamingGenerationOptions {
  resumeThresholdSecs?: number;
 }
 function mergeFloat32Arrays(chunks: Float32Array<ArrayBuffer>[]): Float32Array<ArrayBuffer> {
  const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
  const out = new Float32Array(total);
  let offset = 0;
  for (const chunk of chunks) {
    out.set(chunk, offset);
    offset += chunk.length;
  }
  return out;
 }
 function buildWav(samples: Float32Array<ArrayBuffer>, sampleRate: number): Blob {
  const dataSize = samples.length * 4;
  const buffer = new ArrayBuffer(44 + dataSize);
  const view = new DataView(buffer);
  const writeString = (offset: number, value: string) => {
    for (let i = 0; i < value.length; i += 1) {
      view.setUint8(offset + i, value.charCodeAt(i));
    }
  };
  writeString(0, "RIFF");
  view.setUint32(4, 36 + dataSize, true);
  writeString(8, "WAVE");
  writeString(12, "fmt ");
  view.setUint32(16, 16, true);
  view.setUint16(20, 3, true);
  view.setUint16(22, 1, true);
  view.setUint32(24, sampleRate, true);
  view.setUint32(28, sampleRate * 4, true);
  view.setUint16(32, 4, true);
  view.setUint16(34, 32, true);
  writeString(36, "data");
  view.setUint32(40, dataSize, true);
  new Float32Array(buffer, 44).set(samples);
  return new Blob([buffer], { type: "audio/wav" });
 }
 function decodeFloat32Chunk(data: string): Float32Array<ArrayBuffer> {
  const raw = atob(data);
  const bytes = new Uint8Array(raw.length);
  for (let i = 0; i < raw.length; i += 1) {
    bytes[i] = raw.charCodeAt(i);
  }
  return new Float32Array(bytes.buffer as ArrayBuffer);
 }
 export function useStreamingGeneration({
  onLog,
  onStart,
@@ -0,0 +1,56 @@
 export const SAMPLE_RATE = 24_000;
 export function decodeFloat32Chunk(data: string): Float32Array<ArrayBuffer> {
  const raw = atob(data);
  const bytes = new Uint8Array(raw.length);
  for (let i = 0; i < raw.length; i += 1) {
    bytes[i] = raw.charCodeAt(i);
  }
  return new Float32Array(bytes.buffer as ArrayBuffer);
 }
 export function mergeFloat32Arrays(
  chunks: Float32Array<ArrayBuffer>[]
 ): Float32Array<ArrayBuffer> {
  const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
  const out = new Float32Array(total);
  let offset = 0;
  for (const chunk of chunks) {
    out.set(chunk, offset);
    offset += chunk.length;
  }
  return out;
 }
 /** Builds a float32 RIFF/WAV Blob from raw PCM samples. */
 export function buildWav(
  samples: Float32Array<ArrayBuffer>,
  sampleRate: number
 ): Blob {
  const dataSize = samples.length * 4;
  const buffer = new ArrayBuffer(44 + dataSize);
  const view = new DataView(buffer);
  const writeString = (offset: number, value: string) => {
    for (let i = 0; i < value.length; i += 1) {
      view.setUint8(offset + i, value.charCodeAt(i));
    }
  };
  writeString(0, "RIFF");
  view.setUint32(4, 36 + dataSize, true);
  writeString(8, "WAVE");
  writeString(12, "fmt ");
  view.setUint32(16, 16, true);
  view.setUint16(20, 3, true); // PCM float32
  view.setUint16(22, 1, true); // mono
  view.setUint32(24, sampleRate, true);
  view.setUint32(28, sampleRate * 4, true); // byte rate
  view.setUint16(32, 4, true); // block align
  view.setUint16(34, 32, true); // bits per sample
  writeString(36, "data");
  view.setUint32(40, dataSize, true);
  new Float32Array(buffer, 44).set(samples);
  return new Blob([buffer], { type: "audio/wav" });
 }