README.md

metadata

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

For detailed setup: 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)

# 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 for detailed manual setup instructions.

Quick version:

# 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

# 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 - Entry point for new users
• SETUP.md - Detailed setup guide
• QUICKSTART.md - 5-minute quick start
• VERIFICATION.md - Setup checklist
• ARCHITECTURE.md - System design
• CONTRIBUTING.md - Development guide
• FINAL_STATUS.md - Current status report

Status

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

License

Open-source (see LICENSE file)