Hercules DJControl Starlight mapping for Mixxx

This repository contains a two-deck MIDI mapping for the Hercules DJControl Starlight. It maps the controller's transport, mixer, jog wheels, performance pads, headphone controls, and LEDs to Mixxx.

The preset declares compatibility with Mixxx 2.2's controller schema and uses Mixxx's bundled lodash.mixxx.js and midi-components-0.0.js libraries.

Files

• Hercules DJControl Starlight.midi.xml defines the MIDI input and LED output bindings.
• Hercules-DJControl-Starlight-scripts.js implements scratching, seeking, shifted headphone controls, loops, and base-light behavior.

Both files are required and must remain in the same controller mapping directory.

Installation

1. Close Mixxx.

2. Copy both mapping files into your user controller directory:

   Operating system	Directory
   Linux	~/.mixxx/controllers/
   macOS	~/Library/Application Support/Mixxx/controllers/
   Windows	%LOCALAPPDATA%\Mixxx\controllers\

3. Connect the DJControl Starlight and start Mixxx.

4. Open Preferences > Controllers.

5. Select the DJControl Starlight MIDI device, enable it, and choose Hercules DJControl Starlight as its mapping.

Installing into the user directory is preferable to replacing Mixxx's system copy (for example, /usr/share/mixxx/controllers/ on Linux), because application updates may overwrite system files.

Controller mapping and audio routing are configured separately. If the controls work but no sound is heard, configure the Starlight's master and headphone outputs under Preferences > Sound Hardware.

Controls

Deck A controls Mixxx deck 1; Deck B controls Mixxx deck 2.

Transport and mixer

Control	Normal	With Shift
Play	Play/pause	Stutter play
Cue	Default cue behavior	Return to the start of the track
Sync	Toggle sync	Toggle sync master
Headphones, Deck A	Toggle deck 1 PFL	Toggle master monitoring
Headphones, Deck B	Toggle deck 2 PFL	Toggle split-cue mode
Vinyl	Toggle scratching for both jog wheels	Cycle the base lights through VU meter, beat pulse, and off
Jog-wheel edge	Pitch bend	Pitch bend
Jog-wheel top	Scratch when Vinyl is enabled; otherwise bend while playing	Fast seek through the track
Deck volume	Channel volume	—
Bass/Filter	Low EQ / quick-effect filter	—
Tempo fader	Deck rate, with 14-bit resolution and soft takeover	—
Crossfader	Master crossfader	—

When Vinyl mode is disabled, touching a stopped deck's jog wheel still scratches so that the play position can be adjusted.

Performance pads

The four pads follow the hardware's selected pad mode.

Mode	Pads 1–4	Shift + Pads 1–4
Hot Cue	Set or trigger hot cues 1–4	Clear hot cues 1–4
Loop	Toggle 1, 2, 4, or 8-beat loops	Toggle 1/2, 1/4, 16, or 32-beat loops
FX	Toggle effects 1–3; pad 4 routes the effect unit to the deck	Select the effect in slots 1–3; pad 4 is unused
Sampler	Deck A triggers samplers 1–4; Deck B triggers samplers 5–8	—

The mapping also drives transport, sync, PFL, hot-cue, loop, effect, sampler, Vinyl, and base-light LEDs.

Customization

The user-adjustable values are near the top of Hercules-DJControl-Starlight-scripts.js:

DJCStarlight.scratchScale = 1.0;
DJCStarlight.scratchShiftMultiplier = 4;
DJCStarlight.bendScale = 1.0;

• scratchScale changes scratch sensitivity.
• scratchShiftMultiplier changes how much faster Shift + jog seeking is than scratching.
• bendScale changes pitch-bend sensitivity.

The base lights start off by default. To choose a different startup mode, change this line:

DJCStarlight.baseLedChoice = DJCStarlight.baseLedChoices.None;

Use None, VUMeter, or Beat, then restart Mixxx (or disable and re-enable the controller) after editing the script.

Troubleshooting

• The mapping is not listed: confirm that both files are in the same controllers directory, then restart Mixxx.
• The controller does nothing: enable its MIDI device in Preferences > Controllers and assign this mapping to it.
• Jog behavior feels too fast or slow: adjust the three sensitivity values described above.
• A tempo fader does not immediately move the on-screen control: soft takeover is enabled. Move the physical fader through the current software value to pick it up.
• Changes disappear after a Mixxx update: keep the customized files in the user controller directory rather than editing the system-installed copies.

Credits

Original mapping by DJ Phatso for Hercules Technical Support, with contributions from Kerrick Staley and KnightHill.

Discussion: https://mixxx.discourse.group/t/hercules-djcontrol-starlight/17833