Skip to content

Pro DJ Link

Jump to bottom
Troy edited this page Dec 11, 2025 · 1 revision

Usermod: Pro DJ Link (🎵 Beta Release 🎵)

Connect your WLED instance directly to the Pioneer Pro DJ Link ecosystem.

⚠️ Note: This is currently experimental and has only been tested with WLED-MM-P4

This usermod allows an ESP32 running WLED to act as a virtual CDJ on a Pioneer DJ network. It synchronizes lighting effects to the Master Player's BPM and Beat Grid, and provides advanced data such as Track Metadata, Phrase analysis (Verse, Chorus, Build-up), and real-time Waveforms.

Features

  • BPM & Beat Sync: Accurate, quantized synchronization with the Master Deck.
  • Phrase Automator: Automatically switch WLED Presets when the song structure changes (e.g., switch presets when the track moves from "Intro" to "Verse" or "Chorus").
  • Metadata Display: Reads Track Title, Artist, Album, Key, and Genre.
  • Visuals:
    • Album Artwork: Downloads and buffers album art (requires PSRAM).
    • Waveforms: Real-time extraction of the tricolor frequency waveform.
  • CDJ Status: Displays current Master Deck, BPM, and Phrase info in the WLED Info UI.

Hardware Requirements

  • Microcontroller: ESP32 (Original, S3, or P4). ⚠️ Only tested on the ESP32-P4!
    • Note: PSRAM (SPIRAM) is highly recommended. The waveform and artwork buffers are large; without PSRAM, these features may fail to allocate memory or cause instability.
  • Network: The ESP32 must be on the same Local Area Network (LAN) as the CDJs/XDJs.
    • Tip: A wired Ethernet connection (using an ETH01 or similar) is recommended for Pro DJ Link due to the high volume of UDP broadcast traffic, but strong WiFi can work.

Installation

  1. Copy usermod_v2_pioneer_prolink.h to your WLED usermods/usermod_v2_pioneer_prolink/usermod_v2_pioneer_prolink.h folder.
  2. Add the compile-time define to your platformio.ini or my_config.h: 
    build_flags =
  -D USERMOD_PIONEER_PROLINK
  3. Ensure your build environment includes the AsyncUDP library. (It already should!)

Configuration

Navigate to Config > Usermods in the WLED web interface to configure the settings.

General Settings

  • Enabled: Toggles the usermod on or off.
  • Enable Debug: Outputs detailed protocol information to the Serial Monitor (115200 baud). Use this for troubleshooting connection issues.
  • Virtual Deck Number: (Default: 3) The Player ID WLED will claim on the network.
    • Range: 1-4 (usually 3). Ensure this does not conflict with physical CDJs (which are usually 1 and 2).
  • Player IP Override: (Optional) If WLED cannot automatically discover the Master Deck via UDP broadcast, enter the IP address of the CDJ manually here - or if you have a network with more than one DJ setup (unlikely).

This was tested with the new XDJ-AZ in "PRO DJ LINK mode" (2 decks) but should theoretically work with any CDJ/XDJ ecosystem - I just don't have the budget to test $100,000 worth of gear. Patches are welcome!

Lighting & Automation

  • Beat Flash: A simple, built-in effect that flashes the LEDs white at the top of every beat. Useful for testing sync without setting up complex effects. (Note: This does nothing on its own, needs to be integrated into an effect, see the example "Pro Link" effect.
  • Advance Preset on Phrase: (Powerful Feature)
    • When enabled, WLED will automatically cycle your presets whenever the song enters a new "Phrase" (e.g., Intro, Up, Down, Chorus).
    • This currently skips playlists and also resets segments before changes.
    • Requirement: Tracks must be analyzed in Rekordbox with "Phrase Analysis" enabled.

Graphics (Waveform & Art)

  • High-Res Artwork 240x240:
    • On: Fetches higher quality cover art (larger memory usage). Not recommended unless you need more than 80x80 artwork displays
    • Off: Fetches smaller thumbnails.
    • You will need a way to decode the JPEG data - the ESP32-P4 has a hardware JPEG decoder, other ESP32 boards have software libraries.
  • Use Alt Waveform Colors:
    • Off: Uses the standard Pioneer tricolor scheme (Blue=Low, Amber=Mid, White=High).
    • On: Uses the specific RGB color index provided by the CDJ (matches the "RGB" waveform setting on newer CDJs).

Usage Guide

  1. Network Setup: Ensure your CDJs are linked (via Switch / Router) and your ESP32 is connected to that same network. This requires DHCP to be enabled so the Pioneer gear receives IPs in the same scope as your ESP32.
  2. Rekordbox Analysis: Ensure your music USBs have been analyzed in Rekordbox. Phrase Analysis is required for the "Advance Preset on Phrase" feature to work.
  3. Power Up: Turn on the CDJs first, then WLED.
  4. Wait for Link: WLED sends "Keep Alive" packets. It should appear on your CDJ meters or utility menu as a linked player.
  5. Play: Start playing on the Master Deck. WLED will lock onto the BPM.

In theory it will wait for a player to join the network, or leave the network and rejoin - but more testing is requited.

Interfacing (For Developers & Effect Writers)

This usermod exposes several volatile variables that can be used within WLED effects (FX.cpp) or other usermods:

Timing & Synchronization

Variable Type Description
prolink_bpm_public volatile float Current effective BPM (pitch adjusted).
prolink_beat_public volatile uint8_t Current Beat in measure (1-4).
prolink_beat_number_public volatile uint32_t Global continuous beat counter from the CDJ.
prolink_beat_progress_public volatile float 0.0 to 1.0 progress through current beat.
prolink_pitchPercent volatile float Current pitch slider position (e.g., +6.0%).

Track Structure (Phrases & Bars)

Variable Type Description
prolink_phrase_index_public volatile int Index of current phrase in the list (-1 if none).
prolink_phrase_name_public String Human readable name (e.g., "Intro", "Chorus").
prolink_phrase_beats_public volatile uint16_t Total beat length of the current phrase.
prolink_phrase_progress_public volatile float 0.0 to 1.0 progress through current phrase.
prolink_mood_public String Energy level: "High", "Mid", or "Low".
prolink_total_phrases_public volatile uint16_t Total number of phrases in current track.
prolink_bars_elapsed_public volatile uint8_t Number of bars played.
prolink_bars_remaining_public volatile uint8_t Number of bars until end of track/cue.
prolink_beats_elapsed_public volatile uint32_t Total beats played.

Track Information

Variable Type Description
prolink_track_id_public volatile uint32_t Rekordbox ID of the current track.
prolink_track_duration_ms volatile uint32_t Total track duration in milliseconds.
prolink_track_progress volatile float 0.0 to 1.0 progress through the whole track.
prolink_total_beats volatile uint32_t Total number of beats in the track.

Metadata Strings

Variable Type Description
prolink_track_title String Track Title.
prolink_track_artist String Track Artist.
prolink_track_album String Album Name.
prolink_track_key String Musical Key (e.g., "1A", "Cmin").
prolink_track_genre String Genre.
prolink_track_label String Record Label.
prolink_metadata_valid volatile bool True if metadata has been successfully fetched.

Visual Data (Waveform & Art)

Variable Type Description
prolink_waveform_data WaveformPoint* Pointer to array of struct {height, color, r, g, b}.
prolink_waveform_length volatile uint16_t Number of valid points in the waveform buffer.
prolink_waveform_valid volatile bool True if waveform data is ready.
prolink_artwork_data uint8_t* Pointer to raw JPEG image buffer.
prolink_artwork_size volatile uint32_t Size of the JPEG buffer in bytes.
prolink_artwork_valid volatile bool True if artwork is ready.
altWaveformColors bool True if using RGB index instead of Blue/Amber/White.

Connection & Status

Variable Type Description
prolink_connected_public volatile bool True if connected and acting as a Virtual Deck.
prolink_beat_flash_active volatile bool True if the internal beat flash effect is firing.
prolink_beat_flash_brightness volatile uint8_t Current brightness (0-255) of beat flash.

Use in an Effect:

#ifdef USERMOD_PIONEER_PROLINK
// Use 'extern' to declare that these variables are defined elsewhere
extern volatile float     prolink_bpm_public;
extern volatile uint8_t   prolink_beat_public;
#endif

Troubleshooting

WLED sees the CDJ, but Metadata/Waveforms are empty.

  • Ensure the CDJ is playing from a Rekordbox-analyzed source (USB/SD).
  • Tracks played via Link from a laptop (Export mode) may behave differently regarding database ports.
  • Check if Enable Debug shows "Timeout" or "Connection Refused". This usually indicates a firewall or subnet issue.

**Not detecting Pioneer devices

  • This was only tested on the XDJ-AZ, so other systems may require patching.
  • Much of the Pioneer network communications requires boradcast packets - make sure those are working.
  • A cheap smart network swith with "port mirroring", a USB network card, and WireShark are your friends in debugging.
  • Packet decoders for Pioneer gear can be found here: https://github.com/nudge/wireshark-prodj-dissectors

The LEDs flash erratically.

  • Check your network connection. UDP packets are "fire and forget." If WiFi signal is poor, beat packets will be dropped, causing sync jitter.

Bootloop / Crash on Startup.

  • If you enabled High-Res Artwork or Waveforms on a standard ESP32 (non-PSRAM), the chip may be running out of RAM. Disable these features in the standard WLED config file before compiling, or upgrade to an ESP32-S3/P4 with PSRAM.

Clone this wiki locally