🎧 CleanCue - Professional DJ Library Manager

Professional Audio Analysis & Normalization for DJs

CleanCue is a comprehensive DJ library management tool that provides professional-grade audio analysis and normalization, helping DJs organize and prepare their music collections for seamless mixing across all major DJ software platforms.

🚀 v0.4.0 - DJ Deck with MIDI Support: Professional dual-deck mixing interface with Web MIDI controller support, real-time waveforms, and hot cues!

✨ Key Features

🎵 Professional Audio Analysis

Multi-Engine Analysis System: Choose from Librosa (scientific), KeyFinder (DJ-focused), or Essentia.js (research-grade)
Dramatically Improved Accuracy: Professional analysis algorithms provide diverse, accurate results
Camelot Wheel Integration: Professional DJ notation (8A, 9A, 4A) alongside traditional keys
Scientific BPM Detection: Onset-based tempo analysis using professional algorithms
Energy Analysis: Spectral feature extraction for accurate energy ratings (3.0-7.0 range)
Engine Transparency: See which analysis engine was used for each track

🎛️ Professional Audio Normalization

EBU R128 Compliant: Industry-standard loudness measurement and normalization
Dual Normalization Modes:
- Metadata-Only: Non-destructive ReplayGain tags compatible with all DJ software
- Export Mode: Creates normalized copies while preserving your originals
DJ-Optimized Targets: -14 LUFS standard with professional headroom management
Advanced Options: Two-pass limiting for hot tracks, custom LUFS/Peak/LRA controls
Professional Workflow: Separate analysis and normalization phases for fast library scanning

🔍 Smart Library Management

Lightning-Fast Scanning: JSON-based storage eliminates database complexity
Multi-Format Support: MP3, WAV, FLAC, M4A, AIFF, OGG
Real-Time Progress: Live analysis job monitoring with detailed progress tracking
Audio Preview: Built-in player with volume controls for track sampling
Health Dashboard: Library health monitoring and duplicate detection

🎛️ Universal Export System

USB Export: Copy tracks to USB/external drives with custom templates
Multiple Formats: M3U, Serato DJ, Engine DJ, Rekordbox, Traktor Pro
Custom Filename Templates: {artist} - {title} [{bpm}] ({key})
Character Normalization: Filesystem-safe filenames with accent removal
Export Profiles: Pre-configured templates for different DJ setups

🏗️ Architecture Highlights

Simplified & Fast

No Database Required: Lightweight JSON storage for instant startup
Event-Driven: Real-time updates and progress tracking
TypeScript Throughout: Type-safe development with comprehensive testing
Monorepo Structure: Organized packages with shared components

Professional Analysis Scripts

scripts/analyze_audio.py: Librosa-based scientific analysis
scripts/keyfinder_analysis.py: Circle of Fifths key detection
scripts/loudness_analysis.py: EBU R128 loudness measurement
scripts/normalize_metadata.py: ReplayGain tag application
scripts/normalize_export.py: Export mode normalization

📊 Before vs After Analysis

Aspect	Before v0.2.4	After v0.2.4
Key Detection	Limited accuracy with repetitive results	Diverse keys (F# minor 11A, C# major 3B, etc.)
Energy Values	Identical 0.4-0.5 range	Professional 3.0-7.0 range
BPM Accuracy	Basic estimation	Scientific onset detection
Engine Choice	Hidden algorithms	User-selectable (Librosa/KeyFinder/Essentia)
Normalization	None	EBU R128 professional workflow

🚀 Quick Start

Download & Install

macOS

Download:
- Intel Macs (126 MB)
- Apple Silicon (126 MB)
Install: Open the DMG and drag CleanCue to Applications
Launch: Open CleanCue and add your music folders

Windows

Download:
- Installer (96 MB)
- Portable (96 MB)
Install: Run installer or extract portable version
Launch: Open CleanCue and add your music folders

Linux

Download:
- AppImage (122 MB)
- Debian Package (81 MB)
Install: Make AppImage executable (chmod +x) or install deb package (sudo dpkg -i)
Launch: Run AppImage or launch from applications menu

Professional Analysis (Optional)

For the most accurate analysis results, install Python dependencies:

# Install professional analysis engines
pip3 install --user librosa numpy scipy scikit-learn matplotlib soundfile

# Then uncomment professional analysis code in packages/simple-engine/src/ui-service.ts
# and rebuild: pnpm run build

Basic Workflow

Scan Library: Add your music folders for automatic discovery
Analyze Tracks: Run analysis on your collection (automatic with fallback)
Configure Normalization: Choose metadata-only or export mode in Settings
Export: Create playlists or USB drives for your DJ software

⚙️ Settings & Configuration

Analysis Settings

Engine Selection: Auto, Librosa, KeyFinder, or Essentia
Engine Fallback: Automatic fallback if preferred engine fails
Transparency: Show which engine analyzed each track

Normalization Settings

Mode Selection:
- Metadata Only: ReplayGain tags (recommended for most DJs)
- Export Mode: Creates normalized copies
- Both: Apply tags AND create copies
Presets: DJ (-14 LUFS), Streaming, Broadcast, Custom
Advanced Controls: Custom LUFS/Peak/LRA values, limiter options

📁 Project Structure

cleancue/
├── apps/desktop/           # Electron desktop app
├── packages/
│   ├── simple-engine/      # Core analysis & normalization engine
│   ├── ui/                # React UI components
│   ├── cli/               # Command-line interface
│   └── shared/            # Shared utilities
├── scripts/               # Professional analysis scripts
│   ├── analyze_audio.py   # Librosa analysis
│   ├── keyfinder_analysis.py  # Key detection
│   ├── loudness_analysis.py   # EBU R128 loudness
│   ├── normalize_metadata.py  # ReplayGain tags
│   └── normalize_export.py    # Export normalization
└── docs/                  # Documentation

🧪 Development

Prerequisites

Node.js: 18+ with pnpm
Python: 3.8+ (optional, for professional analysis)
macOS: 10.14+ (Intel) or 11.0+ (Apple Silicon)

Quick Development Setup

# Clone and install
git clone https://github.com/CommmandrCody/CleanCue.git
cd CleanCue
pnpm install

# Start development
pnpm run dev

# Run tests
pnpm run test:all

# Build release
pnpm run build

Professional Analysis Setup

# Install Python dependencies
pip3 install librosa numpy scipy scikit-learn matplotlib soundfile

# Uncomment analysis code in packages/simple-engine/src/ui-service.ts
# lines 1833-1870 (remove /* and */ comment blocks)

# Rebuild
pnpm run build

📈 Performance

Analysis Speed

Library Scan: 96 tracks in <30 seconds
Professional Analysis: 2-3 seconds per track (with Python deps)
Fallback Analysis: <0.5 seconds per track

System Requirements

Storage: 200MB for app + space for analysis results
Memory: 512MB+ for large libraries (10,000+ tracks)
Startup: <1 second (no database initialization required)

🎯 Professional DJ Features

Normalization Workflow Results

Original Track:  -10.9 LUFS, -0.3 dBFS peak, 11.6 LRA
Normalized:      -12.6 LUFS, -1.5 dBFS peak ✅ Excellent!

Supported DJ Software Integration

✅ Serato DJ: ReplayGain tag support + crate export
✅ Rekordbox: Metadata import + XML playlists
✅ Engine DJ: Full metadata support
✅ Traktor Pro: NML format with key/BPM
✅ VirtualDJ: Standard tag support
✅ djay: ReplayGain normalization

🔧 Advanced Features

CLI Interface

# Standalone CLI commands
cleancue scan ~/Music
cleancue analyze --engine librosa
cleancue stats --format json
cleancue export --format serato

API Integration

IPC Bridge: Electron renderer ↔ main process
Event System: Real-time progress and job tracking
Plugin Architecture: Extensible command registry

🐛 Troubleshooting

Common Issues

Analysis shows fallback results: Install Python dependencies for professional analysis
Slow library scanning: Exclude network drives and temporary folders
Missing metadata: Ensure files have proper ID3/metadata tags

Debug Mode

Enable debug logging in Settings → Advanced → Enable Debug Logging

🤝 Contributing

We welcome contributions! Please see our Development Guide for details.

Key Areas for Contribution

Analysis Engines: New engine integrations
Export Formats: Additional DJ software support
UI/UX: Interface improvements and testing
Documentation: User guides and API documentation

📜 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Professional Analysis Libraries

Librosa: Scientific audio analysis (McFee et al.)
Essentia.js: Research-grade MIR algorithms (Music Technology Group, UPF)
KeyFinder: DJ-focused key detection algorithms
ffmpeg: Professional audio processing and normalization

Built With

Electron: Cross-platform desktop framework
React: UI component library
TypeScript: Type-safe JavaScript
pnpm: Fast, efficient package manager

🚀 What's Next?

v0.5.0 Roadmap

Stem Separation: AI-powered track separation
Advanced Playlists: Smart playlist generation based on energy/BPM
Cloud Sync: Library synchronization across devices
Enhanced DJ Deck: Advanced effects, loops, and automation

Made with ❤️ for the DJ community

CleanCue: Professional tools for professional DJs

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
apps/desktop		apps/desktop
docs		docs
packages		packages
scripts		scripts
.env.production		.env.production
.env.test		.env.test
.gitignore		.gitignore
LICENSE		LICENSE
MIDI_CONTROLLER_GUIDE.md		MIDI_CONTROLLER_GUIDE.md
README.md		README.md
RELEASE_NOTES_v0.2.4.md		RELEASE_NOTES_v0.2.4.md
cleancue.code-workspace		cleancue.code-workspace
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation