HUGGINGFACE_SETUP.md

🤗 Hugging Face Token Setup Guide

Why You Need This

AudioForge uses AI models from Hugging Face:

• MusicGen (Facebook) - Music generation
• Bark (Suno) - Vocal synthesis
• Demucs (Facebook) - Audio separation

These models require a Hugging Face token to download.

---

🚀 Quick Setup (Automated)

Option 1: Interactive Setup Script (Recommended)

# Run the interactive setup
python scripts/setup_env.py

This will:

1. ✅ Prompt you for your Hugging Face token
2. ✅ Configure all environment variables
3. ✅ Generate a secure secret key
4. ✅ Create your .env file automatically

---

🔑 Get Your Hugging Face Token

Step 1: Create Account (if needed)

1. Go to https://huggingface.co/join
2. Sign up (it's free!)

Step 2: Generate Token

1. Go to https://huggingface.co/settings/tokens
2. Click "New token"
3. Give it a name (e.g., "AudioForge")
4. Select "Read" permissions (sufficient for model downloads)
5. Click "Generate token"
6. Copy the token (you won't see it again!)

---

📝 Manual Setup

If you prefer to configure manually:

1. Create .env file

cd backend
cp .env.example .env

2. Edit .env and add your token

# Open in your editor
code .env  # VS Code
# or
notepad .env  # Windows
# or
nano .env  # Linux/Mac

3. Add these lines (minimum required):

# Hugging Face Token (REQUIRED)
HUGGINGFACE_TOKEN=hf_your_token_here
HF_TOKEN=hf_your_token_here

# Device (cpu or cuda)
MUSICGEN_DEVICE=cpu
BARK_DEVICE=cpu
DEMUCS_DEVICE=cpu

# Database
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/audioforge

# Redis
REDIS_URL=redis://localhost:6379/0

# Secret Key (generate with: python -c "import secrets; print(secrets.token_urlsafe(32))")
SECRET_KEY=your-generated-secret-key

# CORS
ALLOWED_ORIGINS=http://localhost:3000

---

✅ Verify Setup

Check if token is configured:

cd backend
python -c "from app.core.config import settings; print('✅ Token configured!' if settings.HUGGINGFACE_TOKEN else '❌ Token missing!')"

Test model download:

cd backend
python -c "
from transformers import AutoProcessor
processor = AutoProcessor.from_pretrained('facebook/musicgen-small')
print('✅ Models can be downloaded!')
"

---

🖥️ GPU Acceleration (Optional)

If you have an NVIDIA GPU with CUDA:

1. Check CUDA availability:

python -c "import torch; print('✅ CUDA available!' if torch.cuda.is_available() else '❌ CUDA not available')"

2. Update .env to use GPU:

MUSICGEN_DEVICE=cuda
BARK_DEVICE=cuda
DEMUCS_DEVICE=cuda

Benefits:

• ⚡ 10-50x faster generation
• 🎵 Can generate longer audio
• 🚀 Better for production

---

🔒 Security Best Practices

✅ DO:

• Keep your token private
• Add .env to .gitignore (already done)
• Use read-only tokens
• Rotate tokens periodically

❌ DON'T:

• Commit .env to git
• Share your token publicly
• Use tokens with write permissions
• Hardcode tokens in code

---

🐛 Troubleshooting

Problem: "401 Unauthorized" when downloading models

Solution: Check your token is valid

curl -H "Authorization: Bearer YOUR_TOKEN" https://huggingface.co/api/whoami

Problem: "Token not found"

Solution: Make sure .env file exists and has the token

cat backend/.env | grep HF_TOKEN

Problem: Models downloading to wrong location

Solution: Set cache directory in .env

TRANSFORMERS_CACHE=/path/to/cache
HF_HOME=/path/to/huggingface

Problem: Out of memory when loading models

Solutions:

1. Use smaller models:

   MUSICGEN_MODEL=facebook/musicgen-small
   BARK_MODEL=suno/bark-small
   

2. Use CPU instead of GPU:

   MUSICGEN_DEVICE=cpu
   

3. Increase system swap space

---

📊 Model Sizes

Model	Size	Device	RAM Required
MusicGen Small	~1.5GB	CPU	4GB+
MusicGen Small	~1.5GB	CUDA	6GB+ VRAM
Bark Small	~2GB	CPU	4GB+
Bark Small	~2GB	CUDA	8GB+ VRAM
Demucs	~300MB	CPU	2GB+

Recommendation: Start with small models on CPU for testing, then upgrade to GPU for production.

---

🚀 Quick Start After Setup

# 1. Verify setup
python scripts/setup_env.py

# 2. Install dependencies
cd backend
pip install -e ".[dev]"

# 3. Initialize database
python scripts/init_db.py

# 4. Start backend
uvicorn app.main:app --reload

# 5. Test generation
curl -X POST http://localhost:8000/api/v1/generations \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A calm acoustic guitar melody", "duration": 10}'

---

📚 Additional Resources

• Hugging Face Docs: https://huggingface.co/docs
• MusicGen Model: https://huggingface.co/facebook/musicgen-small
• Bark Model: https://huggingface.co/suno/bark-small
• Transformers Library: https://huggingface.co/docs/transformers

---

🆘 Still Need Help?

1. Check the main SETUP.md guide
2. Run the verification script: python backend/scripts/verify_setup.py
3. Check logs: tail -f backend/logs/app.log
4. Review LAUNCH_GUIDE.md for detailed troubleshooting

---

🐼⚡ Once configured, models will download automatically on first use. Be patient—the first download takes a few minutes!