Rekordbox Integration Guide

Rekordbox Integration Guide

Complete guide for integrating motion-driven auto-DJ control with Rekordbox using keyboard shortcuts and MIDI.

Table of Contents

1. [Overview](#overview)
2. [Prerequisites](#prerequisites)
3. [Setup Methods](#setup-methods)
4. [Keyboard Control](#keyboard-control)
5. [MIDI Control](#midi-control)
6. [Library Management](#library-management)
7. [Troubleshooting](#troubleshooting)
8. [Advanced Features](#advanced-features)

---

Overview

This integration allows the DJ Agent to control Rekordbox through:

• Keyboard shortcuts (218 shortcuts available, no subscription required)
• MIDI Learn (requires subscription, comprehensive control)
• Library access via XML export or encrypted database (pyrekordbox)

Architecture

Motion Input → DELL Model → DJ Agent → Rekordbox Bridge → Rekordbox
                                            ↓
                                    Keyboard/MIDI Events

Control Methods Comparison

---

Prerequisites

1. Install Rekordbox

• Version: Rekordbox 6 or 7 (Performance mode)
• Subscription: Free (Core) for keyboard, paid plan for MIDI
• Download: [rekordbox.com](https://rekordbox.com/)

2. Install Python Dependencies

# Required for keyboard control
pip install pynput

# Required for MIDI control (optional)
pip install mido python-rtmidi

# Required for library access (optional)
pip install pyrekordbox

3. System Permissions

#### macOS
1. Go to System Preferences → Security & Privacy → Accessibility
2. Add your Python interpreter or Terminal app to the allowed list
3. Restart your terminal

#### Windows
- No special permissions needed for keyboard control
- May need to run as Administrator for global keyboard hooks

---

Setup Methods

Method 1: Keyboard Control (Recommended for Getting Started)

Advantages: Simple, no configuration needed, works immediately

Setup Steps:

1. Configure DJ Agent:

   # configs/rekordbox.yaml
   rekordbox:
     mode: "keyboard"
     decks_layout: "2player"
     auto_focus: true

2. Launch Rekordbox:
- Open Rekordbox in Performance mode
- Load tracks to both decks
- Keep Rekordbox as the active window (or enable `auto_focus`)

3. Test the Integration:

   cd studio/dj_agent
   python scripts/test_rekordbox_bridge.py

4. Verify Shortcuts:
- Press `z` → Deck 1 should play/pause
- Press `q` → Deck 1 should sync
- Press `7` → 4-beat loop on Deck 1

Method 2: MIDI Control (Advanced)

Advantages: More reliable, continuous controls, no window focus needed

Requirements:
- Rekordbox subscription (Core plan or higher)
- Virtual MIDI device

Setup Steps:

Step 1: Create Virtual MIDI Port

macOS:
1. Open Audio MIDI Setup (Applications → Utilities)
2. Go to Window → Show MIDI Studio
3. Double-click IAC Driver
4. Check "Device is online"
5. Add a port named "Bus 1" (if not already present)

Windows:
1. Download and install [loopMIDI](https://www.tobias-erichsen.de/software/loopmidi.html)
2. Create a new port named "loopMIDI Port 1"

Step 2: Configure Rekordbox MIDI Learn

1. Open Rekordbox → Preferences → MIDI
2. Click MIDI button in Rekordbox toolbar (appears when MIDI device detected)
3. Enable LEARN mode
4. For each control:
- Operate the control in Rekordbox (e.g., click Play button)
- Send MIDI message from Python (the bridge will send automatically)
- Rekordbox will map the MIDI to that control

Example MIDI Mapping:

PLAY_A:
  type: note
  ch: 0
  note: 60  # Middle C
  velocity: 127

SYNC_A:
  type: note
  ch: 0
  note: 62  # D

LOOP_4_A:
  type: cc
  ch: 0
  cc: 20
  value: 64

Step 3: Update Configuration

# configs/rekordbox.yaml
rekordbox:
  mode: "midi"
  midi_port: "IAC Driver Bus 1"  # macOS
  # midi_port: "loopMIDI Port 1"  # Windows

---

Keyboard Control

Default Rekordbox Keyboard Shortcuts

#### Transport (Deck 1 / Deck 2)
- Play/Pause: `Z` / `N`
- Cue: `A` / `H`
- Sync: `Q` / `/`
- Pitch Bend +: `E` / `O`
- Pitch Bend -: `W` / `I`

#### Loops
- Loop In: `D` (Deck 1), `J` (Deck 2)
- Loop Out: `F` (Deck 1), `K` (Deck 2)
- Exit/Reloop: `G` (Deck 1), `L` (Deck 2)
- Halve Loop: `Shift+D` / `Shift+J`
- Double Loop: `Shift+G` / `Shift+L`
- Beat Loops: `4` (0.5), `5` (1), `6` (2), `7` (4), `8` (8 beats)

#### Hot Cues
- Set/Jump Hot Cue 1-8: `1`-`8`
- Clear Hot Cue: `Ctrl+1` to `Ctrl+8` (Windows) / `Cmd+1` to `Cmd+8` (macOS)

#### Library
- Navigate: Arrow keys (`Up`, `Down`, `Left`, `Right`)
- Load to Deck 1: `Alt+A`
- Load to Deck 2: `Alt+N`
- Next Track: `Alt+A`
- Previous Track: `Alt+Q`

#### Tempo
- Tempo Up: `Shift+E`
- Tempo Down: `Shift+W`
- Tempo Reset: `F3`
- Master Tempo: `F2`
- Sync: `F1`

#### View
- Toggle Layout: `Space`
- Fullscreen: `Ctrl+Shift+F` (Windows) / `Cmd+Shift+F` (macOS)
- 1 Player View: `Ctrl+7` / `Cmd+7`
- 2 Player View: `Ctrl+8` / `Cmd+8`

Customizing Keyboard Shortcuts

1. Open Rekordbox → Preferences → Keyboard
2. Search for functions (e.g., "Play", "Loop", "Hot Cue")
3. Click on the shortcut field and press your desired key combination
4. Update `configs/rekordbox.yaml` to match your custom mapping

---

MIDI Control

MIDI Mappable Functions

Rekordbox MIDI Learn supports:

✅ Supported:
- Deck transport (Play, Cue, Sync)
- Hot cues (1-8)
- Loops (In/Out, Resize, Beat loops)
- Effects (FX toggle, parameters)
- Sampler triggers
- Mixer (EQ, Volume, Crossfader)
- Browser navigation
- Tempo/Pitch adjustment

❌ Not Supported (Pioneer Hardware Only):
- Jogwheel scratch/pitch bend
- Shift layers
- VU meters
- Some advanced performance pads

MIDI Workarounds

Problem: Jogwheel control restricted to Pioneer hardware

Solution: Use [Bome's MIDI Translator Pro](https://www.bome.com/products/miditranslator)
1. Translate your MIDI messages to Pioneer DDJ format
2. Rename your virtual port to match a Pioneer controller
3. Map jogwheel values to Pioneer ranges (70-83 clockwise, 58-45 counter-clockwise)

MIDI Message Types

Note On/Off (for buttons):

# Play button
midi_msg = mido.Message('note_on', channel=0, note=60, velocity=127)
midi_out.send(midi_msg)
time.sleep(0.05)
midi_msg = mido.Message('note_off', channel=0, note=60, velocity=0)
midi_out.send(midi_msg)

Control Change (for knobs/faders):

# Crossfader position (0-127)
midi_msg = mido.Message('control_change', channel=0, control=8, value=64)
midi_out.send(midi_msg)

---

Library Management

Method 1: XML Export (Recommended)

Advantages: Official format, complete data, no encryption issues

Steps:

1. Export from Rekordbox:
- Go to FILE → EXPORT COLLECTION IN XML FORMAT
- Save to a known location (e.g., `[home-path]`)

2. Configure DJ Agent:

   rekordbox:
     xml_export_path: "[home-path]

3. Use in Python:

   from dj_agent.voice_control.core.rekordbox_library import RekordboxLibraryReader

   reader = RekordboxLibraryReader(xml_path="[home-path])

   # Get all tracks
   tracks = reader.get_all_tracks()
   for track in tracks[:5]:
       print(f"{track['artist']} - {track['title']} ({track['bpm']} BPM, {track['key']})")

   # Search tracks
   results = reader.search_tracks("house", field="genre")
   print(f"Found {len(results)} house tracks")

   # Get playlists
   playlists = reader.get_playlists()
   for playlist in playlists:
       print(f"Playlist: {playlist['name']} ({playlist['count']} tracks)")

Method 2: Direct Database Access (Advanced)

Advantages: Real-time access, no export needed

Disadvantages: Requires pyrekordbox, database is encrypted (SQLCipher)

Steps:

1. Install pyrekordbox:

   pip install pyrekordbox

2. Use in Python:

   from dj_agent.voice_control.core.rekordbox_library import RekordboxLibraryReader

   # Auto-detect database location
   reader = RekordboxLibraryReader()

   # Get all tracks
   tracks = reader.get_all_tracks()

Database Location:
- macOS: `[home-path]`
- Windows: `

XML Format Structure

<?xml version="1.0" encoding="UTF-8" ?>
<DJ_PLAYLISTS Version="1.0.0">
  <PRODUCT Name="rekordbox" Version="7.0.0" Company="Pioneer DJ"/>

  <COLLECTION Entries="1234">
    <TRACK TrackID="1" Name="Track Title" Artist="Artist Name"
           Album="Album Name" Genre="House"
           AverageBpm="128.00" Tonality="Am"
           Location="file://localhost/path/to/track.mp3"
           TotalTime="300" BitRate="320" Rating="5">
      <TEMPO Inizio="0.123" Bpm="128.00" Metro="4/4" Battito="1"/>
      <POSITION_MARK Name="Hot Cue 1" Type="0" Start="10.5" Num="0"/>
    </TRACK>
  </COLLECTION>

  <PLAYLISTS>
    <NODE Type="0" Name="ROOT">
      <NODE Type="1" Name="My Playlist" Entries="50">
        <TRACK Key="1"/>
        <TRACK Key="2"/>
      </NODE>
    </NODE>
  </PLAYLISTS>
</DJ_PLAYLISTS>

---

Troubleshooting

Keyboard Control Issues

Problem: Shortcuts not working

Solutions:
1. ✅ Ensure Rekordbox is in Performance mode (not Export mode)
2. ✅ Rekordbox window must be active/focused (or enable `auto_focus: true`)
3. ✅ Check Accessibility permissions (macOS)
4. ✅ Verify shortcuts in Preferences → Keyboard
5. ✅ Try manually pressing the shortcut to verify it works

Problem: Some keys trigger multiple actions

Solution: Disable conflicting system shortcuts (e.g., Mission Control, Spotlight)

MIDI Control Issues

Problem: MIDI port not found

Solutions:
1. ✅ Verify virtual MIDI device is running:
- macOS: Audio MIDI Setup → IAC Driver online
- Windows: loopMIDI running in system tray
2. ✅ Check port name matches configuration
3. ✅ List available ports:

   import mido
   print(mido.get_output_names())

Problem: MIDI Learn not responding

Solutions:
1. ✅ Ensure Rekordbox subscription is active (Core plan or higher)
2. ✅ Click MIDI button in Rekordbox toolbar (top right)
3. ✅ Enable LEARN mode (button should be lit)
4. ✅ Try mapping a different control first (e.g., Play button)

Problem: Jogwheel not working

Expected: Jogwheel control via MIDI requires Pioneer hardware

Workaround: Use Bome's MIDI Translator Pro to convert MIDI to Pioneer DDJ format

Library Access Issues

Problem: Database not found

Solutions:
1. ✅ Check database path:
- macOS: `[home-path]`
- Windows: `
2. ✅ Ensure Rekordbox has been launched at least once
3. ✅ Use XML export instead (more reliable)

Problem: Cannot read encrypted database

Solution: Install pyrekordbox with SQLCipher support:

pip install pyrekordbox[db]

Or use XML export (recommended).

---

Advanced Features

1. Composite Actions (Keyboard Sequences)

Create complex actions by combining multiple keyboard shortcuts:

BACKSPIN_A:
  type: sequence
  steps:
    - key: "a"       # Cue
      delay: 0.05
    - key: "w"       # Pitch down
      delay: 0.05
    - key: "w"       # Pitch down again
      delay: 0.05

2. Auto-Focus Rekordbox

Automatically bring Rekordbox to foreground before sending commands:

rekordbox:
  auto_focus: true

Or manually:

bridge = RekordboxBridge(config)
bridge.focus_rekordbox()

3. Real-Time Monitoring with rkbx_link

For read-only monitoring of playback state:

1. Download [rkbx_link](https://github.com/grufkork/rkbx_link)
2. Run alongside Rekordbox
3. Receive OSC/Ableton Link data with:
- BPM (pitched + original)
- Track position
- Beat timing
- Phrase info (intro, verse, chorus, bridge, outro)

4. Track Analysis with pyrekordbox

Access detailed track analysis:

reader = RekordboxLibraryReader()
analysis = reader.get_track_analysis(track_id="123")

print(analysis['beatgrid'])     # Beat positions
print(analysis['hot_cues'])     # Hot cue points
print(analysis['memory_cues'])  # Memory cues
print(analysis['phrases'])      # Song structure

5. Playlist Management

Automate playlist creation via XML:

# 1. Export current library
# 2. Modify XML (add tracks to playlists)
# 3. Re-import via FILE → IMPORT COLLECTION FROM XML

6. Integration with Motion Control

Connect motion input to DJ control:

from dj_agent.core.rekordbox_bridge import RekordboxBridge
from dj_agent.core.action_space import ActionSpace

# Initialize
config = load_config('configs/rekordbox.yaml')
bridge = RekordboxBridge(config['rekordbox'])
action_space = ActionSpace(config['dj'], config['rekordbox']['map'])

# Get motion data → action
motion_state = get_motion_from_camera()
action = action_space.select_action(motion_state)

# Execute
message = action_space.hotkey_or_midi(action)
bridge.send(message)

---

Performance Tips

1. Optimize Latency

• Use MIDI mode (lower latency than keyboard)
• Reduce `delay` in keyboard sequences
• Enable `auto_focus: false` if Rekordbox is always active

2. Prevent Command Spam

• Use cooldown periods (configured in `dj.yaml`)
• Implement beat quantization (only send commands at beat boundaries)
• Rate-limit continuous controls (filters, crossfader)

3. Reliability

• Test keyboard shortcuts manually first
• Use MIDI for production (more reliable)
• Export XML library periodically (backup + faster access)
• Keep Rekordbox updated (newer versions may have better MIDI support)

---

Comparison: Rekordbox vs Serato

Recommendation:
- Rekordbox: Best for comprehensive keyboard control, structured library management
- Serato: Best if you need full MIDI without subscription

---

Further Resources

• Rekordbox Manual: [rekordbox.com/en/support/manual/](https://rekordbox.com/en/support/manual/)
• Keyboard Shortcuts: Preferences → Keyboard in Rekordbox
• MIDI Learn Guide: [rekordbox.com/en/support/faq/](https://rekordbox.com/en/support/faq/)
• pyrekordbox Docs: [pyrekordbox.readthedocs.io](https://pyrekordbox.readthedocs.io/)
• rkbx_link: [github.com/grufkork/rkbx_link](https://github.com/grufkork/rkbx_link)

---

Next Steps

1. ✅ Choose control method (keyboard or MIDI)
2. ✅ Run test script: `python scripts/test_rekordbox_bridge.py`
3. ✅ Export XML library for track access
4. ✅ Customize keyboard shortcuts or MIDI mapping
5. ✅ Integrate with motion control pipeline
6. ✅ Test with real DJ session

Need help? Check the [Troubleshooting](#troubleshooting) section or open an issue.