SETUP_HUGGINGFACE.md

🚀 Quick Setup: Hugging Face Token Configuration

⏱️ Time Required: 5 minutes
🎯 Goal: Configure your .env file with Hugging Face token for AI model access

---

🎬 TL;DR - Fastest Setup

# Run this ONE command:
python scripts/setup_env.py

Then follow the prompts! ✨

---

📋 Step-by-Step Guide

Step 1: Get Your Hugging Face Token (2 minutes)

1. Go to: https://huggingface.co/settings/tokens
2. Click: "New token"
3. Name it: "AudioForge"
4. Permission: Select "Read" (sufficient)
5. Click: "Generate token"
6. Copy: Your token (starts with hf_...)

⚠️ Important: Save this token somewhere safe! You won't see it again.

---

Step 2: Run Setup Script (3 minutes)

Windows:

cd C:\Users\Keith\AudioForge
scripts\setup_env.bat

Linux/Mac:

cd /path/to/AudioForge
python scripts/setup_env.py

What it asks:

1. ✅ Hugging Face token (paste the token you copied)
2. ✅ Environment type (press Enter for "development")
3. ✅ Device (press Enter for "cpu" or type "cuda" if you have GPU)
4. ✅ Done! Everything else is auto-configured

---

Step 3: Verify Setup

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

If you see ✅ Token configured!, you're good to go!

---

🎯 What Gets Configured

Your .env file will contain:

# ✅ Hugging Face Token (for model downloads)
HUGGINGFACE_TOKEN=hf_your_token_here
HF_TOKEN=hf_your_token_here

# ✅ Device Configuration
MUSICGEN_DEVICE=cpu  # or cuda for GPU
BARK_DEVICE=cpu
DEMUCS_DEVICE=cpu

# ✅ Database & Redis
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/audioforge
REDIS_URL=redis://localhost:6379/0

# ✅ Security
SECRET_KEY=auto-generated-secure-key

# ✅ CORS
ALLOWED_ORIGINS=http://localhost:3000

---

🚀 Next Steps After Setup

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

# 2. Initialize database
python scripts/init_db.py

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

# 4. In another terminal, start frontend
cd frontend
pnpm install
pnpm dev

Access:

• Frontend: http://localhost:3000
• Backend: http://localhost:8000
• API Docs: http://localhost:8000/docs

---

💡 Pro Tips

🚀 Use GPU for 10-50x Faster Generation

If you have NVIDIA GPU:

# Check if CUDA is available
python -c "import torch; print(torch.cuda.is_available())"

# If True, edit .env:
MUSICGEN_DEVICE=cuda
BARK_DEVICE=cuda
DEMUCS_DEVICE=cuda

📦 Model Download Info

Models download automatically on first use:

• MusicGen: ~1.5GB (takes 2-5 minutes)
• Bark: ~2GB (takes 3-7 minutes)
• Demucs: ~300MB (takes 1-2 minutes)

Total: ~4GB, one-time download

🔒 Security

Your .env file is:

• ✅ Already in .gitignore (won't be committed)
• ✅ Local to your machine only
• ✅ Contains sensitive credentials (keep it safe!)

---

🐛 Troubleshooting

"Token not found" Error

Solution: Make sure .env file exists

# Check if file exists
ls backend/.env

# If not, run setup again
python scripts/setup_env.py

"401 Unauthorized" When Downloading Models

Solution: Token might be invalid

# Test your token
curl -H "Authorization: Bearer YOUR_TOKEN" https://huggingface.co/api/whoami

If it fails, generate a new token at https://huggingface.co/settings/tokens

Models Won't Download

Solutions:

1. Check internet connection
2. Verify token in .env file
3. Try manual download:

   cd backend
   python -c "from transformers import AutoProcessor; AutoProcessor.from_pretrained('facebook/musicgen-small')"
   

Out of Memory

Solutions:

1. Close other applications
2. Use smaller models (already default)
3. Increase system RAM/swap

---

📚 Additional Documentation

• Full Setup Guide: SETUP.md
• Detailed HF Guide: HUGGINGFACE_SETUP.md
• Launch Guide: LAUNCH_GUIDE.md
• Troubleshooting: SETUP.md#troubleshooting

---

✅ Checklist

Before starting the application, ensure:

• Hugging Face token obtained
• .env file created (via setup_env.py)
• Token added to .env
• Backend dependencies installed
• Database initialized
• PostgreSQL running
• Redis running (or Docker Compose)

---

🎉 You're Ready!

Once setup is complete, you can:

1. ✅ Generate music from text
2. ✅ Add vocals with lyrics
3. ✅ Apply mastering effects
4. ✅ Download your creations

🐼⚡ Happy music generation!

---

🆘 Need Help?

1. Run verification: python backend/scripts/verify_setup.py
2. Check logs: tail -f backend/logs/app.log
3. Review docs: All .md files in project root
4. Test API: Visit http://localhost:8000/docs after starting backend

---

Last Updated: January 16, 2026
Forged By: FusionPanda 🐼⚡