Welcome to the comprehensive documentation for Mixtape, an AI-powered audio analysis platform that provides intelligent mix feedback to music producers.
Mixtape combines audio engineering expertise with large language models to deliver actionable feedback on audio mixes. The platform consists of:
- Engine – LangGraph-powered workflow orchestration (
@mixtapelabs/engine) - Main API – Authentication, session management, workflow coordination
- Microservices – Metadata extraction, DSP analysis, AI feedback generation
- Web App – React-based user interface
New to Mixtape? Start here.
- Getting Started - Installation and first workflow
- Reading Path - Recommended learning path for new engineers
- Dev Playground - Experiment with the engine
- Contributing - Code standards and review process
Core technical concepts across audio, security, and data.
- Audio Fundamentals - LUFS, dynamics, spectrum, stereo imaging
- Security Model - JWT, bcrypt, API keys, threat model
- Database Patterns - Prisma ORM, indexing, queries
- Communication Patterns - HTTP clients, error handling
High-level design and architectural decisions.
- System Overview - Component diagram and data flow
- Session Lifecycle - End-to-end session flow
- Design Decisions - Architectural rationale and trade-offs
Workflow orchestration and dependency injection.
- Session State & Schemas - Immutable state management
- LangGraph Workflow - Graph-based orchestration
- Dependency Injection & Clients - Interface abstraction
- Prompting & Feedback - LLM integration
Microservices that power the platform.
- Microservices Overview - Service landscape
- Audio Metadata Service - ffprobe wrapper (1-3s)
- Audio Analysis Service - DSP processing (5-30s)
- Audio Feedback Service - LLM integration (3-10s)
Performance characteristics, deployment, and known issues.
- Performance Characteristics - Timing, bottlenecks, optimization
- Production Deployment - Railway setup, timeout handling, async jobs
- Technical Debt - Known issues and future work
API reference and development practices.
- API Reference - Endpoints and request/response formats
- Testing Strategy - Unit and integration testing
- AI Collaboration Guidelines - Working with AI assistants
- Releasing & CI/CD - Deployment and versioning
Get the engine running in under 5 minutes:
# Clone the repository
git clone https://github.com/mixtapelabs/engine.git
cd engine
# Install dependencies
npm install
# Run tests
npm test
# Build the package
npm run buildUse in your project:
import { runMixtapeSession } from '@mixtapelabs/engine';
const deps = {
audioMetadataClient: { /* implementation */ },
audioAnalysisClient: { /* implementation */ },
feedbackClient: { /* implementation */ }
};
const engineState = await runMixtapeSession({
sessionId: 'uuid',
uploadUrl: 'https://cdn.example.com/mix.wav',
userContext: { daw: 'Ableton', genre: 'trap', experienceLevel: 'intermediate' }
}, deps);
console.log(engineState.feedback); // AI-generated mix feedbackflowchart TB
Start([User Uploads Audio]) --> Validate[Validate Input]
Validate --> Metadata[Fetch Metadata<br/>1-3 seconds]
Metadata --> Analysis[Analyze Audio<br/>5-30 seconds]
Analysis --> Feedback[Generate Feedback<br/>3-10 seconds]
Feedback --> Persist[Persist to DB]
Persist --> End([Return Results])
style Start fill:#e1f5ff
style Validate fill:#f3e5f5
style Metadata fill:#fff9c4
style Analysis fill:#ffecb3
style Feedback fill:#c8e6c9
style Persist fill:#e8f5e9
style End fill:#e1f5ff
Total Duration: 10-60 seconds (sequential execution)
✅ Consistent State Management – Zod schemas ensure type safety across services ✅ Composable Workflow – LangGraph nodes are modular and extensible ✅ Dependency Injection – Swap clients for testing (stubs) or production (HTTP) ✅ Portable Library – Use in API, CLI, batch jobs, or anywhere Node.js runs ✅ Production Ready – TypeScript, Vitest, ESLint, comprehensive test coverage
- Languages: TypeScript (API/Engine), Python (Analysis Service)
- Frameworks: Express, Next.js, LangGraph
- Database: PostgreSQL + Prisma ORM
- Audio: ffprobe, librosa, pyloudnorm, essentia
- AI: OpenAI GPT-4
- Infrastructure: Docker, Docker Compose
- 📖 Documentation: You're here! Explore the sidebar for detailed guides
- 💬 Community: Join discussions on GitHub Issues
- 🐛 Bug Reports: Create an issue
- 📧 Contact: engineering@mixtapelabs.com
- New Engineers: Start with Reading Path
- Understand Audio: Read Audio Fundamentals
- Dive into Code: Explore System Architecture
- Optimize Performance: Check Technical Debt for improvement opportunities
Documentation Version: 2.0 Last Updated: November 18, 2025 Engine Version: 1.0.0