Background
A CDJ does not care what prepared the drive it is reading. It cares that the files on it are the ones it expects, laid out the way it expects. That is a format question, and a format question has an answer.
Every DJ playing club hardware has the same workflow bolted to the same application, not because it is the one they would choose but because it is the one that writes the drive. Change anything about how you want to prepare music and the answer is the same: rekordbox does it that way.
The interesting part is that this is not really an application problem. The databases a player reads are files on a FAT32 or HFS+ volume. They have been read, parsed and documented by other people for years — Deep Symmetry's work on the legacy format and rekordcrate's parser are both public, and the players themselves are the ultimate specification: a drive either loads or it does not.
So the project is not “re-implement rekordbox”. It is: build the library you actually want, write the drive yourself, and then do the things the official tool cannot — stems on a standalone player, cues placed from the words, a copy of every stick you have ever written.
A prepared drive carries its music, and under a PIONEER directory it
carries everything the player knows about that music. There is more than one generation of it
on the same stick, because there is more than one generation of player in the world.
| On the drive | What it is |
|---|---|
export.pdb |
The legacy browse database — a DeviceSQL file, fixed 4 KB pages, with its own string encoding and its own ideas about indexes. Everything from 2009 onwards reads it. It is the format the public research covers best. |
exportLibrary.db |
The newer OneLibrary database — SQLite, encrypted. Every player sold since 2023 needs it, and when Booth started, no other free tool had been seen to write one. |
.DAT / .EXT / .2EX |
One analysis file per track per generation: beat grid, cue points, waveforms — monochrome, colour and the three-band kind the newest players draw — and the phrase structure. Booth writes all three so one stick works from a 2009 deck to a CDJ-3000X. |
| The history | What the player actually loaded, in order, one session a night. It is the only thing on a drive a library cannot produce for itself, which is why Booth reads it back. |
The two databases have to agree with each other. A track present in one and missing from the other, or carrying a different id, is a drive that browses strangely or not at all — so Booth writes both from one collection in one pass, rather than treating the newer one as an export of the older.
The legacy format was mostly already documented. The newer one was not, and what
this project learned about it is written down in
docs/onelibrary.md
— including the parts that turned out to be wrong, which are left in deliberately. A format
note that records only the correct conclusions is a note you cannot tell apart from a guess.
Some of what that took is unglamorous and worth saying out loud. A row that is one byte too long for a page does not fail loudly; it writes a database a parser will happily read back and a player may refuse. A string under 127 bytes is encoded one way, a longer ASCII one another, and anything non-ASCII a third. A count read from the wrong offset comes back as 65,535 and looks like corruption rather than a mistake in the reader. None of that is visible from a diff: it is visible from writing a file, reading it with somebody else's parser, and then putting the stick in a player.
The original pitch for all this — written before the code, including the parts it got wrong — is still here: the specification page.
The dangerous failure here is not a crash. It is writing a file that is confidently, consistently wrong — because the program that writes it and the program that reads it back are both yours, and they agree.
So the drive writer's output is read back by rekordcrate, a separate implementation by other people, written from the same public research but not from this code. A misunderstanding of the format cannot be symmetrical and invisible across both.
The window is tested the same way round: its tests drive it through its own accessibility tree, so they click the real buttons and read the real labels rather than calling the functions underneath and assuming a person could have reached them.
Everything in the suite is offline. What would talk to AcoustID, MusicBrainz or a lyrics server is marked ignored and run deliberately, so a green test run never depends on somebody else's service being up — and a service being down is never mistaken for a bug.
| Where | What |
|---|---|
booth/ |
The library window. This is the program, and what cargo build
builds. |
proto/musicai/ |
booth-cli: the engine — analysis, loudness, stems, tagging, the drive
writer — and a command-line tool around it. It came first, which is all the directory's
old name means. |
gui/ |
The older batch window: pick files, pick a task, run it. It is a front end to the engine's own argument types, not a second implementation, so an option cannot drift between the two. |
docs/ |
The specification this was built to, and what is known about the newer format. |
No account, no telemetry, no upload. The one thing that reaches the network is asking AcoustID and MusicBrainz what a recording is — a feature you turn on with a free key — and, since 0.0.7, asking a lyrics server for words rather than spending minutes listening for them. Both are optional and both are off until you say otherwise.
The Booth Public Source License: free to download, run and modify for personal, educational and internal use, and free to redistribute through non-commercial and open-source channels. Putting it inside a proprietary commercial product needs a separate licence. It is not an OSI-approved licence, so GitHub shows it as “Other”.
Not affiliated with AlphaTheta or Pioneer DJ.