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
• 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

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:

from fastapi.staticfiles import StaticFiles

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

Also install:

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:

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

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

And for the cleaned audio player:

// Before
cleanedPlayer.src = `http://localhost:8000${data.download_url}`;

// After
cleanedPlayer.src = data.download_url;

6. Push to Hugging Face

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