docs/build-plan.md

# Voice Isolation App — Build Plan

## Project Structure

```
voice-isolation-live/
├── backend/
│   ├── main.py               # FastAPI app entry point
│   ├── demucs_runner.py      # Demucs model logic
│   ├── requirements.txt      # Python dependencies
│   └── uploads/              # Temp folder for uploaded audio
│       └── .gitkeep
├── frontend/
│   ├── index.html            # Upload form + audio player
│   ├── style.css             # Basic styling
│   └── app.js                # Fetch API calls to backend
├── docs/
│   ├── voiceisolation-idea.md
│   └── build-plan.md         # This file
├── .gitignore
└── README.md
```

---

## Step-by-Step Build Guide

### Step 1 — Set Up the Python Environment

**Goal:** Get Demucs installed and running on a local audio file.

1. Create and activate a virtual environment:
   ```bash
   python -m venv venv
   source venv/bin/activate      # Linux/Mac
   venv\Scripts\activate         # Windows
   ```

2. Install Demucs:
   ```bash
   pip install demucs
   ```

3. Test it on any `.mp3` or `.wav` file:
   ```bash
   demucs --two-stems=vocals path/to/audio.mp3
   ```
   - Output lands in `separated/htdemucs/<track-name>/`
   - You want `vocals.wav` (isolated voice) and `no_vocals.wav` (background)

**Done when:** You can run Demucs from the terminal and get a clean vocals file.

---

### Step 2 — Build the FastAPI Backend

**Goal:** Accept an audio file upload, run Demucs on it, return the clean vocal track.

1. Install FastAPI and dependencies:
   ```bash
   pip install fastapi uvicorn python-multipart
   ```

2. Create `backend/demucs_runner.py`:
   - Function that takes a file path
   - Runs Demucs via `subprocess` or the Python API
   - Returns the path to the output `vocals.wav`

3. Create `backend/main.py`:
   - `POST /upload` — accepts audio file, saves to `uploads/`, runs Demucs, returns cleaned file
   - `GET /download/{filename}` — serves the processed file back to the client
   - CORS enabled so the frontend can talk to it

4. Run the server:
   ```bash
   uvicorn backend.main:app --reload
   ```

5. Test with curl or Postman:
   ```bash
   curl -X POST http://localhost:8000/upload -F "file=@test.mp3"
   ```

**Done when:** Posting an audio file to the API returns a downloadable clean vocal track.

---

### Step 3 — Build the Frontend

**Goal:** A simple webpage where users upload audio and hear the result.

1. Create `frontend/index.html`:
   - File input (`<input type="file" accept="audio/*">`)
   - Upload button
   - Status message ("Processing..." / "Done!")
   - Two audio players: original and cleaned

2. Create `frontend/app.js`:
   - On upload: POST the file to `http://localhost:8000/upload`
   - On response: load the returned audio URL into the second player
   - Show a loading spinner while Demucs runs

3. Create `frontend/style.css`:
   - Clean, minimal layout — centered card, readable font

4. Open `index.html` directly in the browser (no server needed for frontend yet).

**Done when:** You can upload a file in the browser, wait, and play back the isolated voice.

---

### Step 4 — Deploy to Hugging Face Spaces

**Goal:** Get a live, shareable URL for your demo.

1. Create a free account at [huggingface.co](https://huggingface.co)

2. Create a new Space:
   - Type: **Docker** (gives full control for FastAPI + Demucs)
   - Or type: **Gradio** (easier, but limits your custom frontend)

3. Add a `Dockerfile` to the project root:
   - Base image: `python:3.11`
   - Copy backend files
   - Install dependencies from `requirements.txt`
   - Expose port 7860 (Spaces default)
   - Run: `uvicorn backend.main:app --host 0.0.0.0 --port 7860`

4. Push to the Space's git repo:
   ```bash
   git remote add space https://huggingface.co/spaces/<your-username>/<space-name>
   git push space main
   ```

5. Update the frontend `app.js` to point to your live Space URL instead of `localhost`.

**Done when:** Your Space is live and someone else can upload audio from their browser.

---

## Dependency Checklist

| Package | Purpose |
|---|---|
| `demucs` | Voice isolation model |
| `fastapi` | Backend web framework |
| `uvicorn` | ASGI server to run FastAPI |
| `python-multipart` | Required for file uploads in FastAPI |
| `torch` | Demucs dependency (auto-installed) |

---

## Common Pitfalls

- **Demucs is slow on CPU** — expect 1–3 minutes per track without a GPU. That's fine for a demo; just show a loading indicator.
- **File size limits** — set a max upload size in FastAPI (`UploadFile` has no limit by default).
- **CORS errors** — add `CORSMiddleware` in FastAPI or the browser will block frontend requests.
- **Temp file cleanup** — delete files from `uploads/` after processing so the server doesn't fill up.

---

## CV Skills This Covers

| Skill | Where it shows up |
|---|---|
| Python | Demucs runner, FastAPI backend |
| REST API design | `/upload` and `/download` endpoints |
| ML model integration | Running a pretrained model in a pipeline |
| Full-stack thinking | Frontend talking to backend |
| Deployment / MLOps | Hugging Face Spaces, Docker |

---

*Last updated: 2026-05-01*