stemx 🎵

Open-source AI-powered audio stem separation SaaS. Separate vocals and instrumentals from any audio track using state-of-the-art machine learning models running on GPU.

✨ Features

• AI Stem Separation - Extract vocals and instrumentals using BS-Roformer model
• Producer Mode - Advanced settings for music producers (vocal modes, de-reverb, noise gate, de-esser)
• BPM & Key Detection - Automatic audio analysis
• Credit System - Built-in billing with Stripe integration
• Serverless GPU - RunPod serverless for cost-effective GPU processing
• Real-time Status - Live job status updates

🏗️ Architecture

apps/
├── api/        # FastAPI backend (REST API, auth, job management)
├── worker/     # Job processor (polls jobs, calls RunPod, post-processing)
├── runpod/     # RunPod serverless handler (GPU stem separation)
├── web/        # Next.js frontend (dashboard, auth, payments)
└── infra/      # Docker Compose for local development

How it works

1. User uploads audio file → API validates and stores in Supabase Storage
2. Worker polls for pending jobs and sends audio to RunPod
3. RunPod runs BS-Roformer on GPU for stem separation
4. Results uploaded to Supabase Storage, user downloads stems

🛠️ Tech Stack

Frontend

• Next.js 16 - React framework with App Router
• TailwindCSS - Utility-first CSS
• Radix UI - Accessible UI components
• Framer Motion - Animations
• Supabase Auth - Authentication

Backend

• FastAPI - Modern Python API framework
• Supabase - PostgreSQL database & storage
• Stripe - Payments & subscriptions

AI/GPU Processing

• RunPod Serverless - GPU-as-a-Service (scale to zero)
• BS-Roformer - State-of-the-art audio separation model
• audio-separator - Python library for model inference

Infrastructure

• Railway - Deploy API, Worker, and Web services
• RunPod - Serverless GPU workers
• Supabase - Managed PostgreSQL & Storage
• Docker - Containerization

🚀 Getting Started

Prerequisites

• Docker & Docker Compose
• Node.js 18+
• Python 3.11+
• Supabase account
• RunPod account
• Stripe account (for payments)

Local Development

1. Clone the repository

   git clone https://github.com/iamhmh/stemx.git
   cd stemx

2. Set up environment variables

   cp .env.example apps/infra/.env
   # Edit apps/infra/.env with your credentials

3. Start services with Docker Compose

   cd apps/infra
   docker compose up --build

4. Access the app

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

Environment Variables

Create apps/infra/.env with:

# Supabase
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
SUPABASE_JWT_SECRET=your-jwt-secret

# RunPod
RUNPOD_API_KEY=your-runpod-api-key
RUNPOD_ENDPOINT_ID=your-endpoint-id

# Stripe
STRIPE_SECRET_KEY=sk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxx

☁️ Deployment

Railway (API, Worker, Web)

1. Create a new Railway project
2. Add services from the apps/ directories:
   • apps/api → FastAPI service
   • apps/worker → Python worker service
   • apps/web → Next.js frontend
3. Configure environment variables for each service
4. Deploy!

Each service includes nixpacks.toml for Railway auto-detection.

RunPod (GPU Serverless)

1. Build and push Docker image

   cd apps/runpod
   docker build -t your-username/stemx-runpod:latest .
   docker push your-username/stemx-runpod:latest

2. Create RunPod Serverless Endpoint

   • Go to RunPod → Serverless → Deploy
   • Image: your-username/stemx-runpod:latest
   • GPU: A40 (48GB) recommended
   • Active Workers: 0 (scale to zero)
   • Max Workers: 3
   • Idle Timeout: 5 seconds

3. Configure environment variables

   • SUPABASE_URL
   • SUPABASE_SERVICE_ROLE_KEY

📁 Project Structure

stemx/
├── apps/
│   ├── api/                 # FastAPI backend
│   │   ├── main.py          # API endpoints
│   │   ├── Dockerfile
│   │   └── requirements.txt
│   │
│   ├── worker/              # Job processor
│   │   ├── main.py          # Job polling & orchestration
│   │   ├── audio_analyzer.py # BPM/Key detection
│   │   ├── audio_processing.py # Post-processing effects
│   │   └── Dockerfile
│   │
│   ├── runpod/              # GPU serverless handler
│   │   ├── handler.py       # RunPod entry point
│   │   └── Dockerfile
│   │
│   ├── web/                 # Next.js frontend
│   │   ├── src/
│   │   │   ├── app/         # App Router pages
│   │   │   ├── components/  # React components
│   │   │   └── lib/         # Utilities
│   │   └── package.json
│   │
│   └── infra/               # Docker Compose
│       └── docker-compose.yml
│
├── .env.example             # Environment template
└── README.md

🔧 API Endpoints

Method	Endpoint	Description
GET	/health	Health check
GET	/users/me	Get current user
POST	/upload	Upload audio for processing
GET	/jobs	List user's jobs
GET	/jobs/{id}/download	Get download URLs

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• BS-Roformer - Audio separation model
• audio-separator - Python inference library
• Supabase - Backend-as-a-Service
• RunPod - GPU cloud platform
• Railway - Deployment platform