---
title: AudioForge
emoji: 🎵
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
license: mit
---

# AudioForge - Open-Source Suno-Style Music Generation Platform

A production-ready, fully open-source text-to-music generation platform built with modern best practices.

## 🚀 Quick Start

**New to AudioForge?** Start here: **[START_HERE.md](START_HERE.md)**

For detailed setup: **[SETUP.md](SETUP.md)**

## Architecture

- **Backend**: FastAPI (Python) with async processing
- **Frontend**: Next.js 14+ with TypeScript and App Router
- **Music Generation**: Meta MusicGen / AudioCraft
- **Vocal Generation**: Bark / XTTS
- **Database**: PostgreSQL for metadata, Redis for caching
- **Observability**: Structured logging, Prometheus metrics, OpenTelemetry tracing

## Features

- 🎵 Multi-stage text-to-audio pipeline
- 🎤 Vocal generation with lyrics
- 🎚️ Post-processing and mastering
- 📊 Full observability and monitoring
- 🧪 Comprehensive test coverage
- 🎨 Beautiful, modern UI
- ⚡ Fast and scalable

## Quick Start

### Prerequisites

- **Python 3.11+** (check with `python --version`)
- **Node.js 20+** (check with `node --version`)
- **PostgreSQL 16+** (or use Docker)
- **Redis 7+** (or use Docker)
- **Docker & Docker Compose** (optional, recommended)

### Using Docker Compose (Recommended)

```bash
# Start all services
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f
```

This starts:
- PostgreSQL on port 5432
- Redis on port 6379
- Backend API on port 8000
- Frontend on port 3000

**Access:**
- Frontend: http://localhost:3000
- Backend API: http://localhost:8000
- API Docs: http://localhost:8000/api/docs

### Manual Setup

See **[SETUP.md](SETUP.md)** for detailed manual setup instructions.

**Quick version:**

```bash
# Backend
cd backend
python scripts/quick_setup.py
python scripts/init_db.py
uvicorn app.main:app --reload

# Frontend (in another terminal)
cd frontend
pnpm install
echo "NEXT_PUBLIC_API_URL=http://localhost:8000" > .env.local
pnpm dev
```

### Verify Setup

```bash
# Backend verification
cd backend
python scripts/verify_setup.py

# Test backend health
curl http://localhost:8000/health
```

## Tech Stack

- **Backend**: FastAPI, Pydantic, SQLAlchemy, Redis, PostgreSQL
- **Frontend**: Next.js, TypeScript, Tailwind CSS, shadcn/ui, React Query
- **ML**: MusicGen, Bark, Transformers, PyTorch
- **Testing**: pytest, Vitest, Playwright
- **Observability**: structlog, prometheus-client, opentelemetry

## Documentation

- **[START_HERE.md](START_HERE.md)** - Entry point for new users
- **[SETUP.md](SETUP.md)** - Detailed setup guide
- **[QUICKSTART.md](QUICKSTART.md)** - 5-minute quick start
- **[VERIFICATION.md](VERIFICATION.md)** - Setup checklist
- **[ARCHITECTURE.md](ARCHITECTURE.md)** - System design
- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Development guide
- **[FINAL_STATUS.md](FINAL_STATUS.md)** - Current status report

## Status

✅ **Ready to Run** - All issues resolved, zero errors, production-ready

## License

Open-source (see LICENSE file)