# 🤗 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)

```bash
# 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

```bash
cd backend
cp .env.example .env
```

### 2. Edit `.env` and add your token

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

### 3. Add these lines (minimum required):

```env
# 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:

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

### Test model download:

```bash
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:

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

### 2. Update `.env` to use GPU:

```env
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
```bash
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
```bash
cat backend/.env | grep HF_TOKEN
```

### Problem: Models downloading to wrong location

**Solution**: Set cache directory in `.env`
```env
TRANSFORMERS_CACHE=/path/to/cache
HF_HOME=/path/to/huggingface
```

### Problem: Out of memory when loading models

**Solutions**:
1. Use smaller models:
   ```env
   MUSICGEN_MODEL=facebook/musicgen-small
   BARK_MODEL=suno/bark-small
   ```

2. Use CPU instead of GPU:
   ```env
   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

```bash
# 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!**