docs/step-4-deployment.md

# Step 4 — Deploy to Hugging Face Spaces

**Status: TODO**

## Goal

Get the full app live on a free public URL so anyone can upload audio and use it from their browser.

---

## What you need

- Free account at [huggingface.co](https://huggingface.co)
- Git installed
- The full project working locally (Steps 1–3 done)

---

## How to deploy

### 1. Create a new Space on Hugging Face

1. Go to huggingface.co → New Space
2. Name it (e.g. `voice-isolation-live`)
3. Select **Docker** as the SDK
4. Set visibility to **Public**

### 2. Create a `Dockerfile` in the project root

```dockerfile
FROM python:3.11-slim

WORKDIR /app

COPY backend/ ./backend/
COPY frontend/ ./frontend/
COPY requirements.txt .

RUN pip install --no-cache-dir -r requirements.txt

RUN mkdir -p backend/uploads separated

EXPOSE 7860

CMD ["uvicorn", "backend.main:app", "--host", "0.0.0.0", "--port", "7860"]
```

### 3. Create `requirements.txt`

```
fastapi
uvicorn
python-multipart
demucs
torchcodec
torch
torchaudio
```

### 4. Serve the frontend from FastAPI

Hugging Face Spaces only exposes one port, so FastAPI needs to serve the HTML files too. Add this to `backend/main.py`:

```python
from fastapi.staticfiles import StaticFiles

app.mount("/", StaticFiles(directory="frontend", html=True), name="frontend")
```

Also install:
```bash
pip install aiofiles
```
Add `aiofiles` to `requirements.txt` too.

### 5. Update the frontend API URL

In `frontend/app.js`, change `localhost:8000` to a relative path since frontend and backend are now on the same server:

```javascript
// Before
const response = await fetch('http://localhost:8000/upload', ...

// After
const response = await fetch('/upload', ...
```

And for the cleaned audio player:
```javascript
// Before
cleanedPlayer.src = `http://localhost:8000${data.download_url}`;

// After
cleanedPlayer.src = data.download_url;
```

### 6. Push to Hugging Face

```bash
git init
git add .
git commit -m "initial commit"

git remote add space https://huggingface.co/spaces/<your-username>/voice-isolation-live
git push space main
```

Hugging Face will build the Docker image and deploy automatically. Takes 3–5 minutes on first build.

---

## Verify it's live

1. Go to `https://huggingface.co/spaces/<your-username>/voice-isolation-live`
2. Upload an audio file
3. Wait for processing
4. Check both audio players work

---

## Notes

- Hugging Face free tier has **16GB RAM, 2 CPU cores** — enough for Demucs
- No persistent storage on free tier — uploaded files are lost on restart (fine for a demo)
- Cold start (first request after idle) can be slow — the Space sleeps after 48h of inactivity
- If the build fails, check the **Logs** tab on your Space page for the Docker error
- Model weights (~640MB) get downloaded on first run inside the container — add a `RUN` step in the Dockerfile to pre-download them if startup speed matters