Spaces:
Sleeping
Sleeping
File size: 5,255 Bytes
0f623ae | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 | # 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*
|