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:

   python -m venv venv
   source venv/bin/activate      # Linux/Mac
   venv\Scripts\activate         # Windows
   

2. Install Demucs:

   pip install demucs
   

3. Test it on any .mp3 or .wav file:

   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:

   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:

   uvicorn backend.main:app --reload
   

5. Test with curl or Postman:

   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

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:

   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