Build

Build your own decks

browserdj is a starting point rather than a finished product. The code is open, the licence lets you do almost anything with it, and an AI coding assistant can now make most changes from a plain description of what you want. What follows is how to take a copy and make it yours.

Take a copy

Fork the repository on GitHub, or download it as a zip from the same page. The decks are plain HTML and JavaScript with no build step and no dependencies to install, so the folder you download is the whole thing.

Run it on your machine

In that folder run python3 serve.py and open http://localhost:8765/app/. On a Mac, double-clicking Start browserdj.command does the same. Use Chrome or Edge if you want MIDI and the USB controllers.

Describe the change

Open the folder in an AI coding assistant such as Claude Code, Cursor or GitHub Copilot, and describe what you want the way you would explain it to another DJ. Ask it to set out its plan before it edits anything, then refresh the page and listen.

Test it properly

Play a full hour on it with your own controller before it goes anywhere near a booth. Watch for clicks, drift and a laptop fan working hard. Keep an untouched copy beside your version so there is always something to fall back on.

Put it online

Any static host will serve it, and Cloudflare Pages and GitHub Pages do so for free: connect your fork, leave the build command empty and set the output to the root folder. Your version then has its own address to open from any machine.

Send it back

If the change would help other DJs, open a pull request. Controller mappings are the easiest contribution of all: map yours with the guided set-up, press Save as file, and add it to app/maps/.

Where things live

Nearly everything is in one file, app/index.html, divided into commented sections. Point your assistant at the section by name and it will find its way.

Mixer profiles	`MIXER_PROFILES`: the club isolator, shelving, four-band and battle mixers, each with its EQ, fader and crossfader laws.
Audio engine	Channel routing, headphone cue modes, effects and the master bus.
Beat grid analysis	Between `BEATGRID START` and `BEATGRID END`: tempo, beat positions and the downbeat guess.
Deck	Hot cues, loops, slip, beat jump, sync, transport, the channel strip and the waveforms.
MIDI	Every target a control can drive, the mapping table, Learn and the guided set-up, plus the Kontrol X1 and Z1 drivers.
Controller presets	`app/maps/`, with the file format documented in its README.
Controllers page	`controllers/index.html`: the `CONTROLLERS` list and Test my controller.

Places to start

Changes that are small enough to finish in an evening, each written the way you might ask for it.

Add hot cues five to eight on each deck, on the shift layer of the pads.

Make the echo's feedback climb for as long as I hold the effect button, then fall away when I let go.

When the crossfader moves, sweep a high-pass filter on the channel being faded out.

Colour each track in the library by its Camelot key, and dim the ones that clash with the playing deck.

Add a loop roll that follows the grid in triplets as well as straight beats.

Map the touch strip on my controller to a beat-synced stutter on the master deck.

The terms

The licence

browserdj is published under the MIT licence. You can use it, change it, publish your version and build something commercial on it. The one condition is that the copyright and licence notice stay with the code. It comes with no warranty.

If your version takes its own direction, give it its own name, so nobody confuses the two.

What to watch for

AI assistants are fluent with layout and controls, and less reliable with audio timing, where an error is heard rather than seen. Read what changed, test against a track you know well, and treat anything touching the audio engine or the beat grid with extra care.

Your experiments cannot damage your music: the decks only ever read your files, and they run inside your browser.