A revolutionary DJ platform with terminal aesthetics and gesture control via webcam hand tracking.
⚠️ Pre-MVP Status: OX Board is currently in active development (v0.9.0-pre-mvp). Some features are functional prototypes, while others use mock implementations. See Feature Status below.
# Install dependencies
npm install
# Run development server
npm run dev
# Open http://localhost:3000OX Board uses a retro terminal UI as its primary interface, featuring:
- 🖥️ CRT Aesthetic: Green-on-black display with scanlines and flicker effects
- 🎹 Full DJ Functionality: Dual decks, mixer, effects, stem separation
- 👋 Gesture Control: Control everything with hand gestures via webcam
- 🎵 Professional Audio: Powered by Tone.js and Web Audio API
ox-board/
├── app/
│ ├── components/
│ │ ├── terminal/ # 🎮 ACTIVE UI - Terminal interface
│ │ ├── offline/ # PWA & offline support
│ │ └── Camera/ # Gesture recognition
│ ├── lib/
│ │ ├── audio/ # Audio processing libraries
│ │ ├── gestures/ # Gesture detection & mapping
│ │ └── optimization/ # Performance utilities
│ ├── services/ # Core services
│ │ ├── audioService.ts # Audio context management
│ │ ├── deckManager.ts # Deck control system
│ │ └── aiStemService.ts # AI-powered features
│ ├── stores/ # State management (Zustand)
│ └── hooks/ # React hooks
├── backend/ # Python FastAPI backend (planned - see specs/003)
│ ├── api/ # API endpoints
│ ├── core/ # Core backend logic
│ └── Dockerfile # Container configuration
├── docs/ # 📚 Comprehensive documentation
│ ├── OPTIMAL-VISION.md # Product roadmap & feature plan
│ ├── ANALYSIS-SUMMARY.md # Codebase analysis
│ ├── domain/ # Business domain documentation
│ ├── architecture/ # System architecture
│ ├── patterns/ # Design patterns catalog
│ └── interfaces/ # API reference
├── specs/ # Feature specifications (001-004)
└── tests/ # Test suites (113 tests, 85.8% passing)
- Dashboard: System overview and quick stats
- Studio: Main DJ interface with decks and mixer
- Music Library: Track browser and management
- Settings: Configuration and preferences
- 🎚️ Dual Deck System: A/B deck architecture
- 🎛️ Professional Mixer: EQ, filters, crossfader
- 🎵 Stem Separation: Isolate drums, bass, vocals, other
- 🎹 Effects Rack: Reverb, delay, filters, and more
- 📊 BPM Detection: Automatic tempo analysis
- 🔊 Recording: Capture your mixes
- ✋ Hand Tracking: MediaPipe-powered detection
- 🎚️ Volume Control: Vertical hand movement
↔️ Crossfader: Horizontal hand position- 🎛️ EQ Control: Pinch gestures for bands
- ⏯️ Playback: Open/closed hand for play/pause
- Framework: Next.js 15 (App Router)
- Language: TypeScript
- UI: Custom Terminal UI with CSS
- State: Zustand
- Audio: Tone.js, Web Audio API
- Gestures: MediaPipe, TensorFlow.js
- Framework: FastAPI (Python)
- Deployment: Railway
- Audio Processing: Demucs (stem separation)
- API: RESTful + WebSocket
- Hosting: Vercel (frontend) + Railway (backend)
- CDN: Cloudflare
- Database: PostgreSQL (planned)
- Monitoring: Sentry
Space - Play/Pause
← → - Navigate tabs
↑ ↓ - Adjust values
Enter - Select/Confirm
Esc - Cancel/Back
Tab - Next field
Shift+Tab - Previous field
/play deck:a # Play deck A
/stop deck:b # Stop deck B
/crossfade 50 # Set crossfader to center
/effect reverb amount:30 # Apply reverb effect
/bpm sync # Sync BPM between decksnpm run dev # Start development server
npm run build # Build for production
npm run start # Run production server
npm test # Run test suite
npm run lint # Lint code
npm run type-check # Check TypeScript typesCreate a .env.local file:
# Backend API
NEXT_PUBLIC_API_URL=https://your-railway-backend.railway.app
NEXT_PUBLIC_WEBSOCKET_URL=wss://your-railway-backend.railway.app
# Optional Services
SENTRY_DSN=your-sentry-dsn
GOOGLE_ANALYTICS_ID=your-ga-id- ✅ Terminal UI with CRT aesthetic
- ✅ Gesture recognition via MediaPipe
- ✅ Audio playback with Tone.js
- ✅ Dual deck system
- ✅ Basic mixer controls
- ✅ PWA support (offline capability)
- ✅ Feature flag system (Terminal/Classic UI toggle)
- 🟡 BPM detection (client-side only)
- 🟡 Key detection (basic implementation)
- 🟡 Effects rack (limited effects)
- 🟡 Recording (browser-based)
- 🔴 Stem separation (requires Demucs backend - see
specs/003-self-hosted-demucs/) - 🔴 AI mixing suggestions (placeholder logic)
- 🔴 Harmonic compatibility (basic algorithm)
- 🔴 Music library management (local only)
- 📋 Self-hosted Demucs backend (specs/003)
- 📋 Real-time collaboration
- 📋 Cloud sync for mixes
- 📋 Mobile app (React Native)
📖 For complete roadmap, see docs/OPTIMAL-VISION.md
- Unique Identity: Stand out with retro aesthetics
- Performance: Lightweight, fast rendering
- Accessibility: Keyboard-first navigation
- Focus: Minimal distractions, maximum functionality
Previous UI implementations are preserved in ui-archive/ for:
- Reference and learning
- Future feature extraction
- Design inspiration
- Component reuse
User Input → Gesture/Keyboard → Store → Services → Audio Output
↑ ↓
State ←──────────────────┘
# Run all tests
npm test
# Run with coverage
npm run test:coverage
# Run specific test file
npm test -- path/to/test.spec.ts
# Run in watch mode
npm run test:watch# Automatic deployment on push to main
git push origin main# Deploy backend
cd backend/
railway up- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Tone.js - Web Audio framework
- MediaPipe - Hand tracking technology
- Demucs - Stem separation engine
- Next.js - React framework
- Railway - Backend hosting
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: support@ox-board.app
Built with 💚 by the OX Board Team
Making DJing accessible through gesture control and terminal aesthetics