CDJ USB export
Run a CDJ USB export: the drive state it expects, what the run writes, why players accept the result, and how the output is verified.
library_adapters::CdjExporter implements library_core::Exportable and writes the USB layout rekordbox writes: audio under Contents/, the DeviceSQL device database at PIONEER/rekordbox/export.pdb, and per-track analysis files under PIONEER/USBANLZ/.
User guide: Export to a CDJ USB drive. Exhaustive
per-field reference, the fidelity list and the provenance of every constant:
library-adapters README.
Before you export
- The destination is a directory, chosen in the platform’s own directory picker. On-drive paths are FAT32-safe and de-duplicated case-insensitively (
cdj/layout.rs). - One export covers one collection. The database still has to describe every track and playlist already on the drive.
- A normal re-export merges. Playlists for the selected collection are replaced, and no file on the drive is ever deleted. A rebuild from an invalidated state also drops database entries for collections no longer selected.
- Reuse beats rewrite: audio is reused when the on-drive name and size match, and analysis files are reused when both already exist. Set
ExportOptions::refresh_filesto force a rewrite. - Mixar keeps its drive state in
PIONEER/rekordbox/mixar-export.json. When that file is missing, unreadable, or invalidated by a rewrittenexport.pdb, the drive is rebuilt from the current selection.
Run an export
- Open the collection actions menu and choose the export entry (
widgets/library/collection_actions_menu.dart→widgets/library/export_cdj_usb_dialog.dart). - Pick the destination directory in the platform’s own directory picker.
- Tick Override files already on the drive to force a rewrite (
refresh_files). - Read the summary, warning and error toasts before closing the dialog. They come from
CdjExportReport.
LibraryTransport::export_cdj_usb(destination, playlists, folders, refresh_files) builds ExportOptions and calls the exporter with library::ExportSession. The session locks the manager per call, not for the whole run. Browsing and editing the library stay responsive while a long export is in flight.
What a run writes
ExportOptions { playlists, folders, refresh_files }
│
▼
cdj::plan selection → tracks, device paths, playlists
│ (folders mirror their tree; playlists keep order)
▼
cdj::mod per track: stat → copy or reuse → analysis
│ (analysis comes from ExportSource)
▼
cdj::pdb PIONEER/rekordbox/export.pdb (one write per run)
cdj::anlz PIONEER/USBANLZ/…/ANLZ0000.{DAT,EXT} (per track)
| Module | Role |
|---|---|
cdj/mod.rs |
CdjExporter: the run loop, copying, per-track reporting, Exportable impl. |
cdj/plan.rs |
Selection → PlanTrack / PlanPlaylist; folder-vs-metadata placement (reusing paths the drive already holds, reserving the rest); warnings for unknown or mistyped collection ids. |
cdj/manifest.rs |
PIONEER/rekordbox/mixar-export.json: the tracks, playlists and artwork ids the drive has accumulated, plus the export.pdb length and fingerprint that invalidate it. |
cdj/layout.rs |
FAT32-safe, case-insensitively de-duplicated on-drive paths. |
cdj/pdb.rs |
export.pdb: page allocator, row serializers, the fixed tables the hardware browses. |
cdj/anlz.rs |
ANLZ0000.DAT / .EXT section writers (path, VBR, beat grid, waveforms, cue lists). |
cdj/waveform.rs |
Mixar’s peak tiers → PWAV/PWV2/PWV3/PWV4/PWV5 encodings. |
cdj/device_sql.rs, cdj/keys.rs, cdj/path_hash.rs |
DeviceSQL strings, the 24-row key table, the analysis-directory hash. |
The three format writers are public (cdj::pdb, cdj::anlz, cdj::waveform) and take flat
inputs (CdjTrack, CdjPlaylist, AnlzInput). A tool can therefore build one artifact without
a drive. CdjExporter is the entry point that needs a library and a destination.
Placement is decided once per track. A track reachable through a selected folder collection keeps its mirrored path (Contents/<folder>/<relative tree>); everything else is Contents/<Artist>/<Album>/<file>. Folder collections also become playlists, because a player’s playlist browser cannot see the file tree.
A run merges into the drive. Each run rewrites PIONEER/rekordbox/mixar-export.json and rebuilds the database from it plus the current selection. Playlists are replaced per source collection, and every other track keeps the path it already has, so paths of unselected tracks stay reserved. Artwork ids continue after the highest id on the drive. The state file, and the cases that invalidate it, are listed under Before you export.
Artwork is scaled at the source. library_core::ExportArtwork carries a JPEG thumbnail (EXPORT_ARTWORK_EDGE_PX, 80 px, the size Rekordbox writes) produced by codec::read_file_artwork_thumbnail. The writer never decodes a cover itself. Covers are interned by content (hash plus byte compare): one file and one artwork row per distinct cover, with tracks referencing it through artwork_id.
Rules the players impose
- Analysis directories are re-derived by the player. CDJs ignore the
analyze_pathin the database and hash the on-drive audio path themselves. Analysis files must sit at exactlyPIONEER/USBANLZ/P{p:03X}/{hash:08X}/.CdjExporter::analysis_diris that function;cdj::path_hashdocuments the algorithm and pins it with vectors captured from real exports. - The
.EXTfile is not optional. CDJ-3000-class players re-analyze a track when it is missing, so the exporter always writes both files. - Analysis is rebuilt at export time. The detail waveform the players want is 150 entries per second, finer than the resolution the library keeps for its own displays. Exporting a track decodes it once (
ExportSource::export_data) and hands back the beat grid, cue points and both waveform tiers. Tracks with no analysis data are still registered and reported as a warning; the player analyzes them on load.
Verification
| Check | Where |
|---|---|
Every written file is re-parsed with rekordcrate, an independent implementation of both formats, and asserted field by field (tracks, playlist order, beat grid, waveform entry counts, cues and loops). |
crates/library-adapters/tests/cdj_export.rs |
| Layout rules, key mapping, DeviceSQL strings, path hash and the page/row writers. | unit tests in crates/library-adapters/src/cdj/ |
| A 40-track export whose tables span several database pages, re-read end to end. | same integration test |
| Artwork rows, ids and file layout, including sharing one cover across tracks, continuing ids across runs, and the no-artwork path. | unit tests in cdj/pdb.rs and cdj/tests.rs |
| Merging across runs: two exports into one drive, a re-export after a playlist entry is removed, and a database rewritten outside Mixar. | tests/cdj_export.rs, cdj/manifest.rs unit tests |
The fixed tables (keys, colors, columns, menu, table 0x12, history) byte-compare with two rekordbox-written exports. |
done while developing; noted in cdj/pdb.rs |
| Host → exporter wiring. | crates/host-flutter/tests/cdj_export.rs |
Known drops
History, My Tags (#572), stems
(#573), and the OneLibrary exportLibrary.db
(#559) plus .2EX 3-band waveforms
(#574) newer players prefer are not written.
The high-resolution _m cover variant Rekordbox writes beside the primary thumbnail is not
written either. Track rating, year, comment, track/disc number and colour label are written into
the track row; a colour label maps onto the fixed eight-row colors table, so an arbitrary RGB
value has no representation. Long path components are truncated and de-duplicated, and the
undocumented bytes rekordbox fills in extended cue entries are written zeroed. The full list
lives in the
library-adapters README.