Stijn-Jacobs/cdj-nxs2-qemu

The CDJ-2000NXS2 boots, mounts a virtual USB stick, and loads and plays tracks from it. The waveform scrolls, the time counts down, and the sound you hear is computed by the player's own DSP program on an emulated DSP. Start two and they find each other on an emulated Pro DJ Link network, where MASTER and SYNC work between them. Plug in a MIDI controller and it plays them, or use the virtual deck.

Seven older players have experimental emulation, with further models in development. The status table separates usable features from ongoing work.

These are the CDJ-2000NXS2's; the older players are covered under Supported players.

More Pro DJ Link screens

Deck 2 tracks the master's beat over Pro DJ Link	MASTER TEMPO and SYNC, colour waveform
Browsing the other player's USB over the link	...and playing a track loaded from it

The CDJ-2000NXS2 is the fully supported player; the older models are experimental. Sound is on by default (NOSOUND=1 turns it off). Screenshots show the firmware interface, not a claim of feature parity.

Everything below describes the CDJ-2000NXS2 unless it says otherwise.

This repository distributes no firmware, no ROM or flash images, no fonts, no artwork files and no manuals or schematics. Everything here was written for this project. To run it you supply your own copy of the public firmware update file for the player, which the setup unpacks on your machine, into a folder that is never committed.

The screenshots in this README show the emulated firmware's own interface, running in this emulator, for illustration.

This project is not affiliated with, endorsed by or supported by Pioneer DJ or AlphaTheta. Pioneer DJ, CDJ, rekordbox and PRO DJ LINK are trademarks of their respective owners.

You will need a recent multi-core CPU (see Limits), about 3 GB of disk for the build trees and the DSP module, Python 3.11 or newer, the update file for your player, and your own music. For the CDJ-2000NXS2 that is C2KNXS2.UPD version 1.87; every address in the model is for that version.

1. Get a shell for your system (only your own line applies):

2. Clone and run setup (the same on every system):

git clone https://github.com/Stijn-Jacobs/cdj-nxs2-qemu.git cdj-nxs2
cd cdj-nxs2
./setup.sh

setup.sh walks you through seven steps. Every one is safe to re-run and is skipped when it is already done:

1. Prerequisites: checks compilers, libraries and Python packages, and prints the exact pacman, apt or brew command for whatever is missing.
2. Build: fetches QEMU 9.1.0, applies this project's patches and builds the MAIN emulator, the display-board emulator and the DSP library, with a progress line per phase and full logs in logs/ (10–40 minutes).
3. Firmware: asks for your update file (C2KNXS2.UPD for the CDJ-2000NXS2) and turns it into the images the emulator boots, checking each against a known SHA-256.
4. USB stick: either a folder of your own music exported by rekordbox (the folder that holds PIONEER/), or a plain folder of music files (MP3, FLAC, AAC/M4A, WAV, AIFF, ALAC), which baken analyses instead, so no rekordbox is needed. Either way, a disk image is built from the result.
5. DSP module: asks whether to build the DSP module now (about 20-40 minutes, about 2 GB of free disk while it runs; the default is yes). --skip-dsp, or answering no, leaves it for later.
6. Your setup: one deck or two, Pro DJ Link, sound, a MIDI controller; saved to cdj.conf.
7. Mods: small on/off tweaks to how the deck behaves. Take the defaults in one answer or choose each (see Mods); saved alongside your setup.

3. Play:

./start.sh          # Ctrl-C stops everything

The deck window opens and the CDJ-2000NXS2 boots to its screen. Click the window, press U for the USB stick, ↓ to a track, Enter to load it and Space to play (every key: Keyboard). Click the screen to touch it.

Updating: git pull, then ./start.sh as usual. The emulator is compiled, so when a pull changed its code start.sh notices and offers to rebuild (./build.sh main display does the same by hand). A pull that changed the DSP module's generator also needs the module built again (see DSP module).

./setup.sh --dry-run            show every step and command, change nothing
./setup.sh --reconfigure        ask the "your setup" and "mods" questions again
./setup.sh --yes                never ask; take the defaults and the options below
./setup.sh --skip-build         leave the build out (a build tree you made yourself)
./setup.sh --rebuild            build even when the emulators are already built
./setup.sh --skip-dsp           leave the DSP module out (./start.sh says how to build it later)
  --model <id>                  the player (see Other players); asked when not given
  --firmware <file>             your update file for that player (re-installs the images)
  --music <folder>              the rekordbox USB export to image
  --tracks <folder>             a plain folder of music to image instead, analysed by baken
  --decks 1|2   --name <deck name>   --djlink on|off   --audio on|off
  --controller none|<profile>|learn  --relay-port <port>
  --build-dir <dir>             where the two QEMU build trees go

./start.sh                      start what cdj.conf describes
./start.sh --model <id>         start that player
./start.sh --app | --no-app     the virtual deck app, or the plain window
./start.sh --service | --no-service   boot into SERVICE MODE or not
./start.sh stop                 stop a running rig from another shell
./start.sh --dry-run            show what would be started
./build.sh [source|patches|main|display|dsp]   one build phase at a time

The XDJ-1000MK2, XDJ-700, XDJ-1000, CDJ-900NXS, CDJ-2000NXS, CDJ-900 and CDJ-2000 start from the same two commands with --model; plain ./setup.sh also asks which player you want (Enter keeps the CDJ-2000NXS2). Pass the update file as --firmware:

./setup.sh --model cdj2000 --firmware path/to/C2KGUI.UPD   # the other three files beside it
./start.sh --model cdj2000

Setup stores the player in cdj.conf, so ./start.sh alone starts it from then on. An older player gets the build, firmware and USB steps and opens one window with your stick; a second deck, Pro DJ Link, MIDI controllers, mods and the virtual deck app are CDJ-2000NXS2 features and are skipped. The CDJ-2000, CDJ-2000NXS, XDJ-1000, XDJ-1000MK2, XDJ-700 and CDJ-900NXS also get the DSP module step. Which players exist is whatever has a profile in models/.

Not every key is mapped on the older players yet. On the XDJ-700, XDJ-1000 and CDJ-900NXS only U (USB), Enter (the select knob's push) and Space (PLAY) are: U and seven Enters load the first track. The CDJ-900 also has ↑ / ↓, , (TRACK back), [ / ] (SEARCH), B, T, I, M, L and D; U and four Enters load the first track. C (CUE) and Esc (BACK) are mapped, but the emulated CDJ-900 does not react to them yet.

No controller needed: click a deck's window and play it from the keyboard. Each window drives its own deck. The mouse is the touch screen.

A full player drawn around the emulated screen instead of a bare window: source and browse keys, the rotary selector, hot cue pads, the loop section, CUE and PLAY, a jog with its centre display, the tempo fader. Everything on it is drawn by the app itself; no photo, logo or artwork of the real unit is used.

./start.sh --app          # or CDJ_APP=1 in cdj.conf; --no-app for the plain window

With two decks both stand side by side in one window. Closing the window, or Ctrl-C, stops the decks.

Using one: plug the controller in before ./setup.sh. Setup recognises a controller it has a profile for (or offers to learn a new one) and saves your choice, and from then on ./start.sh starts the bridge together with the decks. With two decks the controller's left side plays deck 1 and its right side deck 2. The bridge's own output is in logs/bridge.log. On Windows it runs on a normal Windows Python (python.org or the Microsoft Store) with mido and python-rtmidi installed, because MSYS2's Python cannot open MIDI devices; setup finds it and prints the one pip command it needs if the packages are missing. On macOS the packages go into this folder's .venv/ (setup prints that command too), and the bridge reaches the controller through Core MIDI.

Any controller works as a profile (what the hardware sends, midi/controllers/<name>.json) plus a mapping (which CDJ key each control presses, midi/mappings/<name>.json). The Roland DJ-202 ships with both. For another controller:

python midi/learn.py new                          # name it, move each control, name each one
python midi/learn.py map --controller <name>      # bind controls to CDJ actions
python midi/bridge.py --controller <name> --dry-run

Every key of the player's front panel can be mapped, including ones nothing binds yet. ./setup.sh --reconfigure offers the same walk-through. Details, the mapping format and the full action catalogue: midi/README.md.

Setup asks for one deck or two (--decks 1|2, or CDJ_DECKS=2 in cdj.conf). Two decks find each other over an emulated Pro DJ Link network, and MASTER and SYNC light up between them, same as the real players.

powershell -ExecutionPolicy Bypass -File scripts\net\tap_setup.ps1

DJLINK=tap:CDJ-Link bash scripts/run/rig.sh show
# with the ableton_link mod:
DJLINK=tap:CDJ-Link CDJ_MAIN_ABLETONLINK=1 CDJ_MAIN_ABLETONLINKPONG=1 bash scripts/run/rig.sh show

Small on/off tweaks to how the deck behaves, each with its own default, listed in mods/mods.conf:

Each mod has a page of its own: its knobs, what it patches, and what has and has not been verified. osc needs a relay on the emulator (python3 scripts/net/osc_relay.py, see its page); ableton_link is reached through a TAP adapter.

./setup.sh shows the defaults (step 7) and either takes them or asks about each one, and saves your answers to cdj.conf; ./setup.sh --reconfigure asks again. You can also edit cdj.conf directly, or override any of them for one run with the environment, e.g. CDJ_GUI_FRAME_MS=0 ./start.sh (a caller's own environment always wins over cdj.conf).

SERVICE MODE is a separate boot option, not a mod: it changes what the deck boots into, not how it behaves once it is up.

three_band, phrase, osc, usb_midi and ableton_link are firmware code patches, not emulator knobs: the launcher applies the display ones to a copy of the display image at boot (mods/patch_gui.py) and the MAIN ones to a copy of the MAIN image (mods/patch_main.py), the same code a real update would carry. mods/patch_update.py makes the same patches to a real Pioneer .UPD file, so they end up on an actual player instead of a copy this emulator throws away on exit; each mod's page gives its command, for example:

python mods/patch_update.py C2KNXS2.UPD C2KNXS2-link.UPD ableton_link

MAIN has no scatter-load table of its own: it runs in place, so a mod's routine goes straight into a run of erased flash inside its own address space rather than being copied out to RAM the way a display patch is.

Only a mod that is an actual firmware code patch is offered this way. An emulator-only knob such as high_fps or live_clock has nothing to write into a real update, and does not appear. python mods/patch_update.py --list shows what is available and which firmware version it was verified against; a mismatched version is refused unless you pass --force-version.

Combining mods. Name as many as you like in one command, e.g. python mods/patch_update.py C2KNXS2.UPD out.UPD three_band osc ableton_link. Each name brings every patch its row in mods/mods.conf needs. All routines of one image are placed in a single pass into one free area, so they cannot overlap, and mods that hook the same spot in the firmware share it: the spot is replaced once by a stub that runs the original code and then each mod in turn. The launcher combines the mods you switched on the same way.

This is untested on real hardware. The container repacking and the LZSS re-encoding have been checked against the real update file byte for byte, and the patched image has been checked against patch_gui.py's/patch_main.py's own output (see tests/), but nobody has flashed a patched update into an actual player. Flashing a modified firmware update is entirely at your own risk. Keep the original file, and expect that a mistake here could mean a trip through service mode's recovery path, or worse.

./start.sh --service      # or CDJ_SERVICE=1 in cdj.conf; --no-service overrides it

This is the service manual's own diagnostic screen: on real hardware you get it by holding TEMPO RANGE and MEMORY while powering the unit on, until the Pioneer logo clears, and this flag does exactly that at boot. The screen lists BUTTON, JOG, ENCODER, NEEDLE, SLIDER VOLUME, JOG TOUCH VOLUME and JOG RELEASE VOLUME; press or move a control and its own row lights up, so it is a live test of every input rather than the player screen.

Both keys release once the logo clears, so nothing stays held down and the rest of the deck is otherwise normal.

By default every run boots from a shared, throwaway flash image, so nothing you change in SERVICE MODE (or anywhere else) survives past Ctrl-C. With PERSIST=1 a deck keeps its own flash image between runs (extract/flash-<tag>.bin), the same as a real unit's memory: a setting changed in SERVICE MODE on a persistent deck stays changed.

A deck keeps up with real time only with a native module of the DSP program's hot code. None is shipped, because it would be derived from Pioneer's code; setup builds it from your own firmware (step 5) and installs it into ~/c14gen/. A headless deck plays a track for 30 seconds, the DSP's hot code is compiled to a native module from what it ran, and a second 30-second play with that module collects the profile-guided counts for the final build. It uses 6 compile jobs (less on an idle machine). With the module, playback holds real time from the first seconds after a load.

The module is installed with a stamp naming what it was built from: the generator version, the DSP core's interface, the firmware and the player. ./start.sh compares the stamp with the current code. After a git pull that changed the generator or the core's interface it does not load the module and shows a banner that it needs building again (./setup.sh rebuilds it); the deck runs far below real time until then. If you skipped step 5, the banner says how to build the module.

Mods do not affect it: they patch the MAIN and display firmware, never the DSP program the module is built from, so turning a mod on or off later needs no rebuild. To compare without the module, start with MODULE=none ./start.sh (the DSP's hot code is then compiled as it plays).

• Speed depends on your CPU. One deck runs in real time on a fast desktop. Two decks need roughly twice that, and on a busy or modest machine they fall behind real time (the audio then has gaps).
• MASTER TEMPO is heavy. It makes the DSP program do far more work per sample, and it is currently the most demanding thing you can ask of the emulator.
• Only firmware v1.87 is supported for the CDJ-2000NXS2.
• Work in progress. The older players are experimental (see Supported players). On the NXS2 the USB stick is the only medium so far. Some panel keys are decoded by the firmware but have not been tried here; the controller tools say so when you bind one.

A CDJ-2000NXS2 is three computers in one box, and all three run here (the older players are built the same way, from their own parts):

flowchart LR
    subgraph deck1["Deck 1"]
        direction LR
        MAIN1["MAIN<br/>SH7724 (SH-4A)"] <-- "SPI link" --> GUI1["Display<br/>SH7269 (SH-2A)"]
        MAIN1 <-- "host port / McBSP" --> DSP1["DSP<br/>C66x"]
        DSP1 --> AUDIO1(["🔊 audio"])
        GUI1 --> WIN1(["🖥️ window"])
    end
    subgraph deck2["Deck 2"]
        direction LR
        MAIN2["MAIN<br/>SH7724 (SH-4A)"] <-- "SPI link" --> GUI2["Display<br/>SH7269 (SH-2A)"]
        MAIN2 <-- "host port / McBSP" --> DSP2["DSP<br/>C66x"]
    end
    MAIN1 <-- "Pro DJ Link (emulated Ethernet)" --> MAIN2
    CTRL(["🎛️ MIDI controller"]) --> BRIDGE["midi/bridge.py"] -- TCP --> RELAY["midi_relay.py"] -- "panel report" --> MAIN1
    RELAY -- "panel report" --> MAIN2

The CDJ-2000 and CDJ-2000NXS have a board model of their own (hw/cdj/boards/cdj2000/): an SH7763 MAIN, a Blackfin BF531 display processor, and a DSP behind a host port (a C6727 on the CDJ-2000, a C6747 on the CDJ-2000NXS). The XDJ-700, XDJ-1000 and CDJ-900NXS share the NXS2's SH7724 MAIN, which draws their screen itself, with a C6747 DSP (hw/cdj/boards/xdj1000/). The launcher starts each older player in one window (see Other players).

None of the three knows it is emulated. MAIN talks to the display processor over the same SPI link, to the DSP over the same host port and McBSP audio bus, and reads its front panel through the same report from the panel microcontroller as on the real board. The models were written device by device, from what the firmware actually touches.

How it was done. By reverse engineering, under QEMU, one blocked boot at a time. The firmware update was unpacked (its container, the LZSS packing of the MAIN and display images, the resource archives), and the boards were modelled wherever the firmware stopped: interrupt controllers, DMA, I²C, the USB host controller, the Ethernet MAC, the SPI link between the two processors, the DSP's boot path and command protocol. The firmware turned out to be its own best documentation: it logs to an internal ring, it names its tasks, its keys and its errors, and a trace hook at any firmware address plus a memory watch said the rest.

The NXS2's DSP needed the most work. There is no usable C66x emulator, so this project has its own: a VLIW core that issues up to eight instructions a cycle, with the SoC peripherals the program uses. Interpreted, it is far too slow for real-time audio, so a JIT compiles the hot parts of the DSP program to native code (hw/cdj/c6x/tools/); the DSP module is that code, built ahead of time. The instruction decode tables come from GNU binutils.

Running the firmware is the first step; changing what a player does is the next, and this is built for it. The emulator makes the whole machine observable and every part of it adjustable, without touching a real deck:

From here, new behaviour is a question of finding the right code and writing the right change: remapping controls, adding features to the deck, studying the Pro DJ Link protocol from a player that speaks it natively, or experimenting with the audio chain. Keep what you derive from the firmware on your own machine: the update file, and anything built from it, is Pioneer's.

MAIN_BOOT=flash ./start.sh

By default MAIN starts with its firmware already unpacked into memory (extract/main_unpacked.bin), past the point where the player's own bootloader hands over. With MAIN_BOOT=flash it starts the way the real unit does: from the reset vector, in Pioneer's bootloader. The firmware update's MAIN section carries that bootloader, an emergency updater and the packed MAIN image, at the flash addresses the player's own updater writes them to, and ./setup.sh --firmware lays them into extract/flash.bin the same way. The bootloader sets up the clocks and memory, checks the image's checksum, unpacks it and starts it; a damaged image starts the emergency updater instead, as on the real player. It adds about two seconds to MAIN's start.

A flash.bin made by an older setup holds no bootloader; MAIN then refuses to start and says so. Run ./setup.sh --firmware <C2KNXS2.UPD> again to rebuild it.

Booting a deck and loading a track takes minutes on the older players and longer on the NXS2; a test or a change to the firmware's later stages should not pay that every time. A deck can be saved while it runs and started from that moment:

SNAPSHOT=loaded ./start.sh --model xdj1000      # or idle, the settled screen

The first start boots as usual, drives the deck to the point (the model profile's MODEL_IDLE_S and MODEL_LOAD_STEPS) and saves it; every later start restores it at once. Saves live in /tmp/cdj-snap/, one folder per combination of QEMU build, firmware, USB image and MAIN_ARGS, so a rebuild or a new stick starts a fresh save by itself; delete the folder to forget them. A save only comes back into the machine that wrote it, so a device that gains state needs that state in its VMStateDescription before saves of it restore correctly. The USB image is not part of a save: the stick is attached as a read-only-in-practice snapshot and comes back as the original file.

scripts/test/quick.sh snap is the same thing as a test: with the deck table of deck_smoke.py it restores each deck's loaded point and checks that the playhead moves (deck_smoke.py --snapshot). The first run saves the points, so it takes as long as decks2; after that a deck takes a minute and a half.

This project's own files are licensed under the GNU General Public License, version 2 or (at your option) any later version (GPL-2.0-or-later); the full text is in LICENSE, and each file carries an SPDX-License-Identifier line.

QEMU, which this machine plugs into; GNU binutils, for the TI C6x opcode tables; minimp3; baken (MIT), which writes the USB export for the folder-of-music setup step.