Library to read the Rekordbox database and emit change events
npm install rekordbox-connectLibrary for reading the Rekordbox SQLCipher-encrypted database and emitting events when the library or play history changes. Built to decouple Rekordbox integration out of NowPlaying into a standalone, reusable package.
- Polls the Rekordbox database file for changes (mtime-based)
- Typed events: ready, db-changed, tracks, history, error
- Incremental history emission (only new plays after start)
- Uses better-sqlite3-multiple-ciphers for SQLCipher support
- Automatically reads database path and password from Rekordbox options.json
- Decrypts database password using Blowfish encryption
- Configurable DB path, password, polling interval, track max rows, and history max rows
``ts
import { RekordboxConnect } from 'rekordbox-connect';
const rb = new RekordboxConnect({ pollIntervalMs: 2000, maxRows: 5000, historyMaxRows: 100 });
rb.on('ready', (info) => {
console.log('Rekordbox ready:', info);
});
rb.on('db-changed', (change) => {
console.log('Database changed:', change);
});
rb.on('tracks', (payload) => {
console.log('Loaded tracks:', payload.count);
});
rb.on('history', (payload) => {
console.log('New plays:', payload.count);
});
rb.start();
// later
// rb.stop();
`
Options:
- dbPath?: string — Absolute path to the Rekordbox DB. If omitted, read from Rekordbox options.json.dbPassword?: string
- — Database password for SQLCipher decryption. If omitted, read and decrypted from Rekordbox options.json.pollIntervalMs?: number
- — Milliseconds between file mtime polls. Default 2000.maxRows?: number
- — Limit for tracks emission. Default 5000.historyMaxRows?: number
- — Limit for history emission per poll. Default 100.
Methods:
- start() — Locate/open DB, emit initial ready, load tracks/history, and begin polling.stop()
- — Stop polling and close DB handle.
Events:
- ready — { dbPath, modifiedTime } when the DB is opened.db-changed
- — { dbPath, previousModifiedTime, modifiedTime } when file mtime increases.tracks
- — { dbPath, count, rows } with a slice of tracks (schema best-effort per Rekordbox version).history
- — { dbPath, count, rows, lastRowId } with new plays since the previous poll.error
- — (error) for any recoverable errors.
- Rekordbox stores its library as a SQLCipher-encrypted SQLite database. By default, the library reads both the database path and encrypted password from Rekordbox's options.json file (located at ~/Library/Application Support/Pioneer/rekordboxAgent/storage/options.json on macOS).dbPath
- The password is decrypted using Blowfish encryption before opening the database.
- If and dbPassword are not provided, the library automatically locates and reads them from options.json.tracks
- Track schema varies across Rekordbox versions. When unknown, emits raw rows from the detected song table (e.g., djmdSong). Map to your internal types as needed.history` only emits new plays after the library starts.
- History polling is rowid-based: on startup the cursor seeds to the current max rowid, so
- alphatheta-connect — Pioneer Pro DJ Link integration
- serato-connect — Serato DJ integration
- stagelinq — Denon StageLinq integration
These libraries power Now Playing — a real-time track display app for DJs and streamers.
MIT