QUICK_START.md

⚡ AudioForge Quick Start

Get up and running in 5 minutes!

---

🎯 Prerequisites

• Python 3.11+
• Node.js 18+
• Docker (optional but recommended)

---

🚀 Setup (Choose One)

Option A: Automated Setup (Recommended)

# 1. Configure environment (includes HF token)
python scripts/setup_env.py

# 2. Start everything with Docker
docker-compose up -d

# Done! 🎉

Access:

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

---

Option B: Manual Setup

# 1. Get Hugging Face token
# Visit: https://huggingface.co/settings/tokens

# 2. Configure environment
python scripts/setup_env.py
# (paste your HF token when prompted)

# 3. Backend setup
cd backend
pip install -e ".[dev]"
python scripts/init_db.py

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

# 5. Frontend setup (new terminal)
cd frontend
pnpm install
pnpm dev

---

✅ Verify It Works

# Check backend health
curl http://localhost:8000/health

# Check frontend
curl http://localhost:3000

# Create 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}'

---

📚 Key Commands

Docker

docker-compose up -d      # Start all services
docker-compose ps         # Check status
docker-compose logs -f    # View logs
docker-compose down       # Stop everything

Backend

cd backend
uvicorn app.main:app --reload  # Start dev server
pytest tests/ -v               # Run tests
python scripts/verify_setup.py # Verify setup

Frontend

cd frontend
pnpm dev          # Start dev server
pnpm build        # Production build
pnpm test         # Run tests
pnpm type-check   # Check TypeScript

---

🎵 First Generation

1. Open http://localhost:3000
2. Enter prompt: "A dreamy lo-fi hip-hop beat"
3. Click "Generate Music"
4. Wait 30-60 seconds
5. Play your generated track! 🎧

---

🐛 Troubleshooting

Backend won't start?

cd backend
python scripts/verify_setup.py

Frontend won't build?

cd frontend
rm -rf .next node_modules
pnpm install

Models won't download?

• Check your Hugging Face token in backend/.env
• Ensure HUGGINGFACE_TOKEN is set
• Check internet connection

Database error?

docker-compose up -d postgres
cd backend && python scripts/init_db.py

---

📖 Full Documentation

• Setup Guide: SETUP.md
• HF Token Setup: SETUP_HUGGINGFACE.md
• Launch Guide: LAUNCH_GUIDE.md
• Architecture: ARCHITECTURE.md

---

🎉 You're Ready!

🐼⚡ Now go make some music!