voice-training-ui CLAUDE.md

Voice Garden 🌷 — project guide for Claude

A cozy, quantitative voice-feminization training tracker for Rachel. She records herself (usually the Rainbow Passage), tells you what she was practicing, and you analyze it and surface — kindly and specifically — what to work on next.

If she shares a recording or asks how a take went, use the analyze-voice skill (.claude/skills/analyze-voice/SKILL.md). It's the operating manual for the whole workflow; this file is the why and the shape.

---

Initial setup (first run — read this first if the project is fresh)

This may be a starter copy: the app, the analyze-voice skill, the reusable annotation lib, the shared reference voices (reference.json), and an _example annotation template are all here — but there may be no recordings yet (empty recordings.json). The user adds their own; everything else is structure for you to drive.

Prerequisites (install whatever's missing):

• ffmpeg — brew install ffmpeg (macOS) / apt-get install ffmpeg (Linux). Required by analyze.py to read mp3/m4a.
• uv — the Python/dependency manager (https://docs.astral.sh/uv). Use uv, never pip.
• Node + npm — for the dashboard.

Bootstrap:

uv sync                                   # Python deps (parselmouth, numpy) → .venv
cd dashboard-react && npm install         # dashboard deps
npm run dev                               # → http://localhost:5173

Add the first recording (this drives the whole dashboard):

uv run analyze.py "/path/to/recording.mp3" --label "what they were trying"

Refresh the dashboard. Then author that take's insight by following the analyze-voice skill — copy dashboard-react/src/annotations/entries/_example.tsx to 00N.tsx (matching the new recording's id) and fill in the slots.

Ownership note: this guide and the skill were written for the original user ("Rachel"). Treat "the user" as whoever you're working with now — keep the same warm, compass-not-judge tone and all the conventions below.