SoundEx - Audio Source Separation

Web-based audio source separation application. Upload your audio file and separate it into individual stems: vocals, drums, bass, and other instruments.

Features

• Upload audio files (MP3, WAV, FLAC, OGG, M4A, AAC, WMA)
• Separate audio into 4 stems using Demucs ML model
• Real-time progress tracking via WebSocket
• Multi-track player with individual volume controls
• Download stems individually or as ZIP archive
• JWT-based authentication

Tech Stack

Component	Technology
Backend	Go 1.22 (Chi router)
Frontend	React 18 + TypeScript + Vite + TailwindCSS
Audio Processing	Python 3.11 + Demucs + FFmpeg
Database	PostgreSQL 16
Queue	Redis 7
Container	Docker + Kubernetes
Monitoring	Prometheus + Grafana

Quick Start

Prerequisites

• Docker & Docker Compose
• Make (optional)

Development

# Clone the repository
git clone https://gitea.mynodes.xyz/soundex/soundex.git
cd soundex

# Copy environment file
cp .env.example .env

# Start all services
docker-compose up

# Or use make
make dev

Access

• Web UI: http://localhost:3000
• API: http://localhost:8080
• API Health: http://localhost:8080/api/health

Production Deployment

Docker Compose (Recommended for single server)

# Copy and configure production environment
cp .env.production.example .env.production
# Edit .env.production with secure values (JWT_SECRET, DB_PASSWORD, etc.)

# Build production images
make prod

# Deploy
make deploy

# Or manually:
docker-compose -f docker-compose.prod.yml up -d

Kubernetes

# Configure secrets
kubectl create secret generic soundex-secrets \
  --from-literal=jwt-secret=your-secure-secret \
  --from-literal=db-password=your-db-password \
  -n soundex

# Deploy with Kustomize
kubectl apply -k k8s/overlays/production

# Or use the deploy script
make deploy-k8s

Monitoring

# Start Prometheus + Grafana
make monitoring

# Access:
# - Prometheus: http://localhost:9090
# - Grafana: http://localhost:3001 (admin/admin)

Project Structure

soundex/
├── api/                      # Go backend
│   ├── cmd/api/              # Entry point
│   └── internal/             # Internal packages
│       ├── handler/          # HTTP handlers
│       ├── middleware/       # Middleware (auth, cors, etc.)
│       ├── model/            # Data models
│       ├── repository/       # Database layer
│       └── service/          # Business logic
├── web/                      # React frontend
│   ├── src/
│   │   ├── components/       # Reusable components
│   │   ├── contexts/         # React contexts
│   │   ├── pages/            # Page components
│   │   └── services/         # API client
│   └── e2e/                  # Playwright tests
├── worker/                   # Python audio processor
│   ├── src/
│   │   ├── converter.py      # FFmpeg wrapper
│   │   ├── processor.py      # Demucs wrapper
│   │   └── worker.py         # Job processor
│   └── tests/                # Unit tests
├── docker/                   # Dockerfiles
├── k8s/                      # Kubernetes manifests
│   ├── base/                 # Base configs
│   └── overlays/             # Environment overlays
├── monitoring/               # Prometheus/Grafana configs
├── scripts/                  # Deployment scripts
├── docs/                     # Documentation
└── docker-compose.yml        # Development environment

Available Commands

# Development
make help             # Show all commands
make dev              # Start development environment
make dev-detached     # Start in background

# Build
make build            # Build all services
make prod             # Build production images

# Testing
make test             # Run all tests
make test-coverage    # Run with coverage reports

# Deployment
make deploy           # Deploy to production (Docker)
make deploy-k8s       # Deploy to Kubernetes
make monitoring       # Start monitoring stack

# Cleanup
make clean            # Clean build artifacts
make docker-clean     # Remove all containers/volumes

API Endpoints

Method	Endpoint	Description	Auth
GET	/api/health	Health check	No
GET	/api/metrics	Prometheus metrics	No
POST	/api/auth/register	Register user	No
POST	/api/auth/login	Login	No
GET	/api/auth/me	Current user	Yes
POST	/api/upload	Upload audio file	Yes
GET	/api/jobs	List jobs	Yes
GET	/api/jobs/:id	Get job details	Yes
DELETE	/api/jobs/:id	Delete job	Yes
GET	/api/ws	WebSocket connection	Yes

See API Documentation for full details.

Documentation

• API Documentation - API endpoints and usage
• Architecture - System design and components
• Development Guide - Local development setup

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Changelog

See CHANGELOG.md for version history.