Skip to main content

prolink_rekordbox/
lib.rs

1// SPDX-License-Identifier: GPL-3.0-only
2
3//! Readers for the files on a rekordbox device export.
4//!
5//! What rekordbox writes to a USB stick or SD card, and what a Pro DJ Link
6//! server has to read back in order to browse and serve it. No network and no
7//! I/O policy: every entry point here takes bytes a caller has already obtained,
8//! because on this protocol they usually arrive over NFS from a device we do not
9//! control rather than from a local file.
10//!
11//! | Module | File | |
12//! |---|---|---|
13//! | [`pdb`] | `PIONEER/rekordbox/export.pdb` | tracks, artists, playlists — the DeviceSQL database |
14//! | [`anlz`] | `PIONEER/USBANLZ/**/ANLZ####.DAT`, `.EXT` | beat grid, cues, waveforms, VBR seek index |
15//! | [`settings`] | `PIONEER/*SETTING*.DAT` | the utility settings a deck adopts from a medium |
16//! | [`library`] | — | the pdb's foreign keys joined into browsable tracks |
17//!
18//! # Endianness is not uniform, and that is the point
19//!
20//! `export.pdb` is **little**-endian. The ANLZ files it points at are
21//! **big**-endian. A path is UTF-16BE inside an ANLZ file and UTF-16LE inside
22//! the pdb, and both differ from how the same path travels over the wire. These
23//! must never share a helper; the one time two of them were conflated, the two
24//! errors cancelled exactly for ASCII and the bug surfaced months later, on
25//! someone's non-ASCII album name, as a failed track load (O6).
26//!
27//! # Three things that have cost this project sessions
28//!
29//! - **The UTF-16 string form starts at `offset + 4` and is little-endian.**
30//!   See [`string`]. A round-trip test cannot catch getting this wrong.
31//! - **Row offset `0x5a` of a track is the container**, not padding. See
32//!   [`pdb::Container`] and F34.
33//! - **The pdb header's sequence counter changes under you.** See
34//!   [`pdb::stable_digest`] and F13.
35//!
36//! # Provenance
37//!
38//! Non-obvious constants carry the finding that establishes them — `F<n>` for a
39//! finding, `C<n>` for a correction to the pre-hardware literature, `O<n>` for
40//! an observation. Where a value is reproduced without being understood, or
41//! inferred rather than measured, the doc comment says so in those words.
42//!
43//! The pdb reader is pinned against a real 675 KB, 165-page export; the ANLZ
44//! and settings readers are not, because no such file was available, and their
45//! module docs say so.
46
47// Tests are allowed to panic: an assertion *is* the failure mode, and a test
48// that carefully propagated errors would report them as passes.
49#![cfg_attr(
50    test,
51    allow(
52        clippy::unwrap_used,
53        clippy::expect_used,
54        clippy::panic,
55        clippy::indexing_slicing,
56        clippy::as_conversions
57    )
58)]
59// docs.rs builds with `--cfg docsrs` (see `package.metadata.docs.rs`) so that
60// the items behind `settings-detail` are documented with the feature they need
61// shown beside them. `doc_cfg` is nightly-only, which is why it is gated: an
62// ordinary `cargo doc` never sees this.
63#![cfg_attr(docsrs, feature(doc_cfg))]
64
65pub mod anlz;
66pub mod library;
67pub mod pdb;
68pub mod settings;
69pub mod string;
70
71mod error;
72
73pub use anlz::{AnlzFile, FourCc, Tag};
74pub use error::{Error, HexBytes, Result};
75pub use library::{HistoryPlaylist, Library, Playlist, Summary, Track};
76pub use pdb::{Container, PageType, Pdb, StableDigest, stable_digest};
77pub use settings::SettingsFile;
78pub use string::DeviceSqlString;