Auto DJ System

Auto DJ System

An intelligent automatic DJ system that analyzes tracks, selects optimal transitions, applies effects, and creates seamless mixes with beat matching and harmonic mixing.

Features

• Intelligent Track Selection: Uses harmonic mixing, BPM matching, and energy analysis to select compatible tracks
• Automatic Transitions: Detects optimal transition points based on track analysis (drops, breakdowns, builds)
• Effect Application: Applies transition effects (censor, filter, echo, reverb) synchronized to beats
• Multiple Mixing Strategies: Choose from harmonic, BPM, energy, composite, or random strategies
• Queue Management: Add tracks to queue with automatic analysis
• Voice Control: All Auto DJ features accessible via voice commands

Architecture

The Auto DJ system consists of several modular components:

Core Modules

• `queue_manager.py`: Manages track queue with analysis metadata
• `mix_strategies.py`: Provides mixing strategies (harmonic, BPM, energy, composite)
• `effect_controller.py`: Handles effect application and timing
• `auto_dj.py`: Main orchestrator that coordinates all components

Integration

The Auto DJ is integrated into the voice control system (`voice_controller.py`) and can be controlled via voice commands.

Usage

Starting Auto DJ

1. Start Voice Control:

   python3 dj_agent/run_voice_control_gemini.py

2. Add Tracks to Queue:
- Programmatically: Use `VoiceController.add_track_to_queue(track_path)`
- Via Serato: Load tracks in Serato library (future integration)

3. Start Auto DJ:
Say: "start auto dj" or "auto dj on"

Voice Commands

• Start: "start auto dj", "auto dj on", "enable auto dj"
• Stop: "stop auto dj", "auto dj off", "disable auto dj"
• Pause/Resume: "pause auto dj", "resume auto dj"
• Skip Track: "skip track", "next track"
• Change Strategy: "set auto dj mode harmonic" (or bpm, energy, composite, random)
• View Queue: "show queue", "queue"
• Clear Queue: "clear queue"

Mixing Strategies

1. Harmonic (`harmonic`): Selects tracks based on key compatibility using Camelot wheel
- Perfect match: Same key
- Relative: Same number, different letter (major/minor)
- Compatible: Adjacent numbers
- Perfect fifth: Same letter, +/- 7

2. BPM (`bpm`): Matches tracks with similar BPM
- Prefers tracks within 5 BPM
- Penalizes larger differences

3. Energy (`energy`): Matches tracks with similar energy levels
- Uses RMS energy analysis
- Prefers tracks with similar average energy

4. Composite (`composite`): Combines harmonic, BPM, and energy strategies
- Default weights: 50
- Provides balanced selection

5. Random (`random`): Random track selection (for variety)

Configuration

Configure Auto DJ behavior via the `config` dictionary:

config = {
    'auto_dj': {
        'transition_style': 'composite',  # harmonic, bpm, energy, composite, random
        'transition_length': 32,  # beats
        'auto_effects': True,
        'beat_match': True,
        'crossfade_enabled': True,
        'min_compatibility_score': 0.6,
        'queue_size': 10,
    }
}

How It Works

Track Analysis

When tracks are added to the queue, they are automatically analyzed to extract:

• BPM: Tempo detection
• Key: Musical key in Camelot notation (e.g., "8A", "5B")
• Beat Grid: Beat positions for synchronization
• Energy Levels: RMS and spectral energy over time
• Drops: Energy drop points (good for transitions)
• Breakdowns: Breakdown sections (good for filter/crossfade)
• Builds: Build-up sections

Track Selection

When transitioning, the Auto DJ:

1. Scores all candidate tracks using the selected mixing strategy
2. Selects the track with the highest compatibility score
3. Falls back to sequential selection if no suitable match

Transition Execution

1. Calculate Transition Time: Finds optimal point (drops, breakdowns, or 75
2. Select Effects: Chooses appropriate effects based on track sections
3. Load Next Track: Loads track on alternate deck
4. Apply Effects: Applies effects with proper timing
5. Play Next Track: Starts playback on new deck

Effect Application

Effects are applied based on track analysis:

• Breakdown Sections: Filter + crossfade for smooth transitions
• Drop Points: Censor for quick cuts
• Default: Crossfade for smooth transitions

Example Usage

from dj_agent.voice_control import VoiceController

# Initialize voice controller
config = {
    'analysis_cache_dir': './.track_analysis_cache',
    'auto_dj': {
        'transition_style': 'composite',
        'auto_effects': True,
    }
}

controller = VoiceController(config=config)

# Add tracks to queue
controller.add_track_to_queue("/path/to/track1.mp3")
controller.add_track_to_queue("/path/to/track2.mp3")
controller.add_track_to_queue("/path/to/track3.mp3")

# Start voice control (Auto DJ can be started via voice)
await controller.start()

Requirements

• `librosa`: Audio analysis
• `numpy`: Numerical operations
• `pynput`: Keyboard control
• `google-genai`: Gemini API (for transition advisor, optional)

Future Enhancements

• Serato Integration: Automatic track detection from Serato library
• Playback Position Monitoring: Real-time position tracking for precise transitions
• Machine Learning: Learn user preferences for track selection
• Advanced Effects: More sophisticated effect chains
• Visual Feedback: Waveform analysis display
• Recording: Record auto mixes
• Playlist Generation: Generate playlists from successful mixes

Troubleshooting

Auto DJ Not Starting

• Ensure track analysis is enabled: `enable_track_analysis=True`
• Check that tracks are added to queue before starting
• Verify Serato DJ is running and tracks are loaded

Poor Track Selection

• Try different mixing strategies: "set auto dj mode composite"
• Ensure tracks are analyzed (check queue with "show queue")
• Adjust `min_compatibility_score` in config

Transitions Not Smooth

• Enable effects: `auto_effects=True`
• Check track analysis quality (BPM, key detection)
• Ensure beat matching is enabled: `beat_match=True`

See Also

• `dj_agent/voice_control/QUICK_START.md`: Quick start guide for voice control
• `dj_agent/GEMINI_VOICE_CONTROL_README.md`: Voice control documentation
• `dj_agent/HIGHER_ORDER_COMMANDS.md`: Higher-order command documentation