djay-connect 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chris Le
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# djay-connect
+
+Library to read djay Pro's `MediaLibrary.db` and emit track change events.
+Supports djay Pro on macOS and Windows.
+
+## Installation
+
+```bash
+npm install djay-connect
+```
+
+## Usage
+
+```typescript
+import { DjayConnect } from 'djay-connect';
+
+const djay = new DjayConnect({
+  pollIntervalMs: 2000,
+});
+
+djay.on('ready', (info) => {
+  console.log(`Watching: ${info.databasePath}`);
+});
+
+djay.on('track', (payload) => {
+  const { track } = payload;
+  console.log(`Now playing: ${track.artist} - ${track.title} [deck ${track.deckNumber}]`);
+  if (track.filePath) console.log(`File: ${track.filePath}`);
+  if (track.originSourceID) console.log(`Source: ${track.originSourceID}`);
+});
+
+djay.on('error', (err) => {
+  console.error('Error:', err);
+});
+
+djay.start();
+
+// Later...
+djay.stop();
+```
+
+## API
+
+### `new DjayConnect(options?)`
+
+- `pollIntervalMs` — Polling interval in milliseconds (minimum 2000, default 2000)
+- `databasePath` — Custom path to `MediaLibrary.db`. If omitted, uses the default per-platform path.
+- `logger` — Logger instance implementing `{ trace, debug, info, warn, error }`
+
+### Track fields
+
+Every `track` event carries a `DjayNowPlayingTrack` with:
+
+- `title`, `artist`, `duration`, `deckNumber`, `startTime`
+- `uuid`, `sessionUUID` — history entry and session identifiers
+- `titleID` — 32-hex id joining the track to location and analysis tables
+- `originSourceID` — where the track came from (`explorer`, `music`, `beatport`,
+  `soundcloud`, `spotify`, `tidal`, `beatsource`, `applemusic`)
+- `isrc` — International Standard Recording Code (streaming tracks)
+- `filePath` — absolute path for local files, decoded from djay's URL-encoded
+  `file://` URIs
+- `sourceURIs` — raw source URIs; may contain multiple entries when a track is
+  available on more than one streaming service
+
+### Events
+
+- `ready` — Emitted when monitoring starts
+- `poll` — Emitted on each poll cycle
+- `track` — Emitted when a new track is detected
+- `error` — Emitted on errors
+
+### Detection utilities
+
+- `getDefaultDjayInstallPath()` — Returns the default djay Pro data folder
+- `getDefaultDatabasePath()` — Returns the default `MediaLibrary.db` path for
+  the current platform
+- `getDefaultDatabasePaths()` — Returns all candidate paths for the current
+  platform
+- `detectDjayInstallation()` — Checks whether djay Pro is installed
+
+### Source helpers
+
+- `DJAY_SOURCES` — Catalog of every known `originSourceID` with `kind`,
+  `label`, and URI scheme prefix
+- `isStreamingSource(id)` — True if the given source is a streaming service
+- `toNowPlayingStreamingSource(id)` — Maps a djay Pro source to the
+  nowplaying streaming enum
+
+### TSAF parser (advanced)
+
+- `parseHistorySessionItem(blob)` — Parse a raw `historySessionItems` BLOB
+- `extractTitleID(blob)` — Extract the nested `ADCMediaItemTitleID`
+- `extractSourceURIs(blob)` — Extract all source URIs from a location blob
+- `extractString`, `extractDouble`, `extractDate` — Low-level field readers
+
+See [`docs/FORMAT.md`](docs/FORMAT.md) for the full on-disk format reference.
+
+## License
+
+MIT

package/dist/detect.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Detection utilities for djay Pro installation and database path.
+ *
+ * djay Pro stores its entire library (including a running history of played
+ * tracks) in a YapDatabase-backed SQLite file named `MediaLibrary.db`. The
+ * folder that contains it is named differently on macOS and Windows:
+ *
+ *   macOS:   ~/Music/djay/djay Media Library.djayMediaLibrary/MediaLibrary.db
+ *   Windows: %USERPROFILE%\Music\djay\djay Media Library\MediaLibrary.db
+ *
+ * Both paths sit under `~/Music/djay`, which is what we return as the install
+ * path for presence detection.
+ */
+/** Top-level djay Pro data folder (`~/Music/djay`). */
+export declare function getDefaultDjayInstallPath(): string;
+/** Candidate MediaLibrary.db paths, in priority order for the current platform. */
+export declare function getDefaultDatabasePaths(): string[];
+/** Resolve the MediaLibrary.db path for the current platform, picking the first that exists. */
+export declare function getDefaultDatabasePath(): string;
+/** Detect if djay Pro is installed by checking for the djay data folder. */
+export declare function detectDjayInstallation(): {
+    found: boolean;
+    path: string;
+};

package/dist/detect.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * @fileoverview Detection utilities for djay Pro installation and database path.
+ *
+ * djay Pro stores its entire library (including a running history of played
+ * tracks) in a YapDatabase-backed SQLite file named `MediaLibrary.db`. The
+ * folder that contains it is named differently on macOS and Windows:
+ *
+ *   macOS:   ~/Music/djay/djay Media Library.djayMediaLibrary/MediaLibrary.db
+ *   Windows: %USERPROFILE%\Music\djay\djay Media Library\MediaLibrary.db
+ *
+ * Both paths sit under `~/Music/djay`, which is what we return as the install
+ * path for presence detection.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultDjayInstallPath = getDefaultDjayInstallPath;
+exports.getDefaultDatabasePaths = getDefaultDatabasePaths;
+exports.getDefaultDatabasePath = getDefaultDatabasePath;
+exports.detectDjayInstallation = detectDjayInstallation;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const DJAY_ROOT_FOLDER = 'djay';
+const DATABASE_FILE = 'MediaLibrary.db';
+const DARWIN_LIBRARY_FOLDER = 'djay Media Library.djayMediaLibrary';
+const WIN32_LIBRARY_FOLDER = 'djay Media Library';
+/** Top-level djay Pro data folder (`~/Music/djay`). */
+function getDefaultDjayInstallPath() {
+    return (0, path_1.join)((0, os_1.homedir)(), 'Music', DJAY_ROOT_FOLDER);
+}
+/** Candidate MediaLibrary.db paths, in priority order for the current platform. */
+function getDefaultDatabasePaths() {
+    const root = getDefaultDjayInstallPath();
+    if (process.platform === 'darwin') {
+        return [(0, path_1.join)(root, DARWIN_LIBRARY_FOLDER, DATABASE_FILE)];
+    }
+    if (process.platform === 'win32') {
+        return [(0, path_1.join)(root, WIN32_LIBRARY_FOLDER, DATABASE_FILE)];
+    }
+    return [];
+}
+/** Resolve the MediaLibrary.db path for the current platform, picking the first that exists. */
+function getDefaultDatabasePath() {
+    const candidates = getDefaultDatabasePaths();
+    for (const candidate of candidates) {
+        if ((0, fs_1.existsSync)(candidate))
+            return candidate;
+    }
+    return candidates[0] ?? '';
+}
+/** Detect if djay Pro is installed by checking for the djay data folder. */
+function detectDjayInstallation() {
+    const path = getDefaultDjayInstallPath();
+    return {
+        found: (0, fs_1.existsSync)(path),
+        path,
+    };
+}
+//# sourceMappingURL=detect.js.map

package/dist/detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;AAYH,8DAEC;AAGD,0DASC;AAGD,wDAMC;AAGD,wDAMC;AA1CD,2BAAgC;AAChC,2BAA6B;AAC7B,+BAA4B;AAE5B,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAChC,MAAM,aAAa,GAAG,iBAAiB,CAAC;AACxC,MAAM,qBAAqB,GAAG,qCAAqC,CAAC;AACpE,MAAM,oBAAoB,GAAG,oBAAoB,CAAC;AAElD,uDAAuD;AACvD,SAAgB,yBAAyB;IACvC,OAAO,IAAA,WAAI,EAAC,IAAA,YAAO,GAAE,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC;AACpD,CAAC;AAED,mFAAmF;AACnF,SAAgB,uBAAuB;IACrC,MAAM,IAAI,GAAG,yBAAyB,EAAE,CAAC;IACzC,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAClC,OAAO,CAAC,IAAA,WAAI,EAAC,IAAI,EAAE,qBAAqB,EAAE,aAAa,CAAC,CAAC,CAAC;IAC5D,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,OAAO,CAAC,IAAA,WAAI,EAAC,IAAI,EAAE,oBAAoB,EAAE,aAAa,CAAC,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,gGAAgG;AAChG,SAAgB,sBAAsB;IACpC,MAAM,UAAU,GAAG,uBAAuB,EAAE,CAAC;IAC7C,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,IAAA,eAAU,EAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;IAC9C,CAAC;IACD,OAAO,UAAU,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AAC7B,CAAC;AAED,4EAA4E;AAC5E,SAAgB,sBAAsB;IACpC,MAAM,IAAI,GAAG,yBAAyB,EAAE,CAAC;IACzC,OAAO;QACL,KAAK,EAAE,IAAA,eAAU,EAAC,IAAI,CAAC;QACvB,IAAI;KACL,CAAC;AACJ,CAAC"}

package/dist/djayConnect.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview DjayConnect - SQLite-backed reader for djay Pro's MediaLibrary.db.
+ *
+ * djay Pro writes each played track into the `historySessionItems` collection
+ * inside its YapDatabase-backed SQLite library (`MediaLibrary.db`). DjayConnect
+ * polls that collection for new rows, parses each row's TSAF blob, and emits
+ * `track` events as they arrive. The same schema is used on macOS and Windows.
+ */
+import type { DjayConnectOptions, TypedEmitter } from './types.js';
+declare const DjayConnect_base: new () => TypedEmitter;
+/**
+ * DjayConnect monitors djay Pro's MediaLibrary.db for new history entries
+ * and emits events when the currently playing track changes.
+ */
+export declare class DjayConnect extends DjayConnect_base {
+    private pollIntervalMs;
+    private databasePath;
+    private logger;
+    private db;
+    private pollTimer;
+    private lastRowId;
+    private isRunning;
+    constructor(options?: DjayConnectOptions);
+    start(): void;
+    stop(): void;
+    get running(): boolean;
+    setPollInterval(intervalMs: number): void;
+    get pollInterval(): number;
+    get path(): string;
+    private openDatabase;
+    private poll;
+    private readLatestHistoryItem;
+    private toTrack;
+    /**
+     * Look up the raw `sourceURIs` for a titleID. Local files live in
+     * `localMediaItemLocations`, streaming tracks in `globalMediaItemLocations`.
+     * Returns every URI recorded for the track — can be empty, one, or many.
+     */
+    private readSourceURIs;
+}
+export {};

package/dist/djayConnect.js

@@ -0,0 +1,249 @@
+"use strict";
+/**
+ * @fileoverview DjayConnect - SQLite-backed reader for djay Pro's MediaLibrary.db.
+ *
+ * djay Pro writes each played track into the `historySessionItems` collection
+ * inside its YapDatabase-backed SQLite library (`MediaLibrary.db`). DjayConnect
+ * polls that collection for new rows, parses each row's TSAF blob, and emits
+ * `track` events as they arrive. The same schema is used on macOS and Windows.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DjayConnect = void 0;
+const node_events_1 = __importDefault(require("node:events"));
+const node_fs_1 = require("node:fs");
+const better_sqlite3_multiple_ciphers_1 = __importDefault(require("better-sqlite3-multiple-ciphers"));
+const detect_js_1 = require("./detect.js");
+const tsaf_js_1 = require("./tsaf.js");
+const logger_js_1 = require("./types/logger.js");
+/**
+ * Decode a djay file:// URI into an absolute OS path.
+ * djay URL-encodes backslashes (`%5C`) and spaces (`%20`) on Windows.
+ */
+function fileUriToPath(uri) {
+    if (!uri.startsWith('file://'))
+        return undefined;
+    // Strip the scheme + the authority slashes; on Windows the authority is
+    // empty and the path begins with a drive letter, e.g. "file:///D:%5C..."
+    let path = uri.slice('file://'.length);
+    if (path.startsWith('/') && /^\/[A-Za-z]:/.test(path)) {
+        path = path.slice(1);
+    }
+    try {
+        path = decodeURIComponent(path);
+    }
+    catch {
+        return undefined;
+    }
+    // On Windows, normalize forward slashes that came from URL decoding into
+    // backslashes so the path is usable by fs.readFile etc.
+    if (process.platform === 'win32') {
+        path = path.replace(/\//g, '\\');
+    }
+    return path;
+}
+const MIN_POLL_INTERVAL = 2000;
+const DEFAULT_POLL_INTERVAL = 2000;
+/**
+ * DjayConnect monitors djay Pro's MediaLibrary.db for new history entries
+ * and emits events when the currently playing track changes.
+ */
+class DjayConnect extends node_events_1.default {
+    constructor(options = {}) {
+        super();
+        this.db = null;
+        this.pollTimer = null;
+        this.lastRowId = 0;
+        this.isRunning = false;
+        this.logger = options.logger ?? logger_js_1.noopLogger;
+        this.databasePath = options.databasePath ?? (0, detect_js_1.getDefaultDatabasePath)();
+        this.pollIntervalMs = Math.max(options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL, MIN_POLL_INTERVAL);
+    }
+    start() {
+        if (this.isRunning) {
+            return;
+        }
+        try {
+            this.openDatabase();
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            this.logger.error('Failed to open djay Pro database: %s', error.message);
+            this.emit('error', error);
+            return;
+        }
+        this.isRunning = true;
+        this.logger.info(`Watching djay Pro library at ${this.databasePath}`);
+        this.emit('ready', { databasePath: this.databasePath });
+        // Seed cursor with the most-recent row and emit it as the initial "current" track.
+        const initial = this.readLatestHistoryItem();
+        if (initial) {
+            this.lastRowId = initial.rowid;
+            const track = this.toTrack(initial.fields);
+            if (track) {
+                this.logger.debug(`Initial track: ${track.artist} - ${track.title} [deck ${track.deckNumber}]`);
+                this.emit('track', { track });
+            }
+        }
+        this.pollTimer = setInterval(() => this.poll(), this.pollIntervalMs);
+    }
+    stop() {
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+        if (this.db) {
+            try {
+                this.db.close();
+            }
+            catch (err) {
+                this.logger.warn('Error closing database: %s', String(err));
+            }
+            this.db = null;
+        }
+        this.lastRowId = 0;
+        this.isRunning = false;
+        this.logger.debug('Stopped');
+    }
+    get running() {
+        return this.isRunning;
+    }
+    setPollInterval(intervalMs) {
+        this.pollIntervalMs = Math.max(intervalMs, MIN_POLL_INTERVAL);
+        if (this.isRunning && this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = setInterval(() => this.poll(), this.pollIntervalMs);
+        }
+    }
+    get pollInterval() {
+        return this.pollIntervalMs;
+    }
+    get path() {
+        return this.databasePath;
+    }
+    // ---------------------------------------------------------------------------
+    // Private
+    // ---------------------------------------------------------------------------
+    openDatabase() {
+        if (!(0, node_fs_1.existsSync)(this.databasePath)) {
+            throw new Error(`djay Pro database not found at: ${this.databasePath}`);
+        }
+        // Open read-only so we can never corrupt djay Pro's live library.
+        this.db = new better_sqlite3_multiple_ciphers_1.default(this.databasePath, { readonly: true });
+        // djay Pro keeps the database in WAL mode while running. Enabling
+        // read_uncommitted lets us observe writes that haven't been checkpointed
+        // yet, so new history rows appear in near real time.
+        this.db.pragma('read_uncommitted = true');
+    }
+    poll() {
+        if (!this.db)
+            return;
+        try {
+            this.emit('poll');
+            const rows = this.db
+                .prepare(`SELECT rowid, key, data
+             FROM database2
+            WHERE collection = 'historySessionItems'
+              AND rowid > ?
+            ORDER BY rowid ASC`)
+                .all(this.lastRowId);
+            for (const row of rows) {
+                this.lastRowId = Math.max(this.lastRowId, row.rowid);
+                const fields = (0, tsaf_js_1.parseHistorySessionItem)(row.data);
+                if (!fields) {
+                    this.logger.warn(`Could not parse historySessionItem ${row.key} (${row.data.length} bytes)`);
+                    continue;
+                }
+                const track = this.toTrack(fields);
+                if (!track)
+                    continue;
+                this.logger.debug(`New track: ${track.artist} - ${track.title} [deck ${track.deckNumber}]`);
+                this.emit('track', { track });
+            }
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            this.logger.error('Poll error: %s', error.message);
+            this.emit('error', error);
+        }
+    }
+    readLatestHistoryItem() {
+        if (!this.db)
+            return null;
+        const row = this.db
+            .prepare(`SELECT rowid, key, data
+           FROM database2
+          WHERE collection = 'historySessionItems'
+          ORDER BY rowid DESC
+          LIMIT 1`)
+            .get();
+        if (!row)
+            return null;
+        const fields = (0, tsaf_js_1.parseHistorySessionItem)(row.data);
+        if (!fields)
+            return null;
+        return { rowid: row.rowid, fields };
+    }
+    toTrack(fields) {
+        if (!fields.title && !fields.artist)
+            return null;
+        const track = {
+            title: fields.title,
+            artist: fields.artist,
+            duration: fields.duration,
+            deckNumber: fields.deckNumber,
+            startTime: fields.startTime,
+            uuid: fields.uuid,
+            sessionUUID: fields.sessionUUID,
+            titleID: fields.titleID,
+            originSourceID: fields.originSourceID,
+            isrc: fields.isrc,
+        };
+        // Enrich with location data (file path or streaming URIs) when we can
+        // resolve the titleID against the *MediaItemLocations collections.
+        if (fields.titleID) {
+            const uris = this.readSourceURIs(fields.titleID);
+            if (uris.length > 0) {
+                track.sourceURIs = uris;
+                for (const uri of uris) {
+                    if (uri.startsWith('file://')) {
+                        const decoded = fileUriToPath(uri);
+                        if (decoded) {
+                            track.filePath = decoded;
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+        return track;
+    }
+    /**
+     * Look up the raw `sourceURIs` for a titleID. Local files live in
+     * `localMediaItemLocations`, streaming tracks in `globalMediaItemLocations`.
+     * Returns every URI recorded for the track — can be empty, one, or many.
+     */
+    readSourceURIs(titleID) {
+        if (!this.db)
+            return [];
+        try {
+            const row = this.db
+                .prepare(`SELECT collection, data
+             FROM database2
+            WHERE collection IN ('localMediaItemLocations','globalMediaItemLocations')
+              AND key = ?`)
+                .get(titleID);
+            if (!row)
+                return [];
+            return (0, tsaf_js_1.extractSourceURIs)(row.data);
+        }
+        catch (err) {
+            this.logger.warn(`Failed to resolve location for titleID ${titleID}: ${String(err)}`);
+            return [];
+        }
+    }
+}
+exports.DjayConnect = DjayConnect;
+//# sourceMappingURL=djayConnect.js.map

package/dist/djayConnect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"djayConnect.js","sourceRoot":"","sources":["../src/djayConnect.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * djay-connect - Library to read djay Pro's MediaLibrary.db and emit track change events.
+ *
+ * @module djay-connect
+ */
+export { DjayConnect } from './djayConnect.js';
+export { getDefaultDjayInstallPath, getDefaultDatabasePath, getDefaultDatabasePaths, detectDjayInstallation, } from './detect.js';
+export { extractString, extractDouble, extractDate, extractTitleID, extractSourceURIs, parseHistorySessionItem, type DjayHistoryItemFields, } from './tsaf.js';
+export { DJAY_SOURCES, isStreamingSource, toNowPlayingStreamingSource, type DjayOriginSourceID, type DjaySourceInfo, } from './sources.js';
+export type { Logger } from './types/logger.js';
+export { noopLogger } from './types/logger.js';
+export type { DjayConnectOptions, DjayConnectEvents, DjayNowPlayingTrack, DjayReadyInfo, DjayTrackPayload, } from './types.js';

package/dist/index.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * djay-connect - Library to read djay Pro's MediaLibrary.db and emit track change events.
+ *
+ * @module djay-connect
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noopLogger = exports.toNowPlayingStreamingSource = exports.isStreamingSource = exports.DJAY_SOURCES = exports.parseHistorySessionItem = exports.extractSourceURIs = exports.extractTitleID = exports.extractDate = exports.extractDouble = exports.extractString = exports.detectDjayInstallation = exports.getDefaultDatabasePaths = exports.getDefaultDatabasePath = exports.getDefaultDjayInstallPath = exports.DjayConnect = void 0;
+// Main connector class
+var djayConnect_js_1 = require("./djayConnect.js");
+Object.defineProperty(exports, "DjayConnect", { enumerable: true, get: function () { return djayConnect_js_1.DjayConnect; } });
+// Detection utilities
+var detect_js_1 = require("./detect.js");
+Object.defineProperty(exports, "getDefaultDjayInstallPath", { enumerable: true, get: function () { return detect_js_1.getDefaultDjayInstallPath; } });
+Object.defineProperty(exports, "getDefaultDatabasePath", { enumerable: true, get: function () { return detect_js_1.getDefaultDatabasePath; } });
+Object.defineProperty(exports, "getDefaultDatabasePaths", { enumerable: true, get: function () { return detect_js_1.getDefaultDatabasePaths; } });
+Object.defineProperty(exports, "detectDjayInstallation", { enumerable: true, get: function () { return detect_js_1.detectDjayInstallation; } });
+// TSAF parser (exported for tests and advanced use)
+var tsaf_js_1 = require("./tsaf.js");
+Object.defineProperty(exports, "extractString", { enumerable: true, get: function () { return tsaf_js_1.extractString; } });
+Object.defineProperty(exports, "extractDouble", { enumerable: true, get: function () { return tsaf_js_1.extractDouble; } });
+Object.defineProperty(exports, "extractDate", { enumerable: true, get: function () { return tsaf_js_1.extractDate; } });
+Object.defineProperty(exports, "extractTitleID", { enumerable: true, get: function () { return tsaf_js_1.extractTitleID; } });
+Object.defineProperty(exports, "extractSourceURIs", { enumerable: true, get: function () { return tsaf_js_1.extractSourceURIs; } });
+Object.defineProperty(exports, "parseHistorySessionItem", { enumerable: true, get: function () { return tsaf_js_1.parseHistorySessionItem; } });
+// Track-source constants and helpers
+var sources_js_1 = require("./sources.js");
+Object.defineProperty(exports, "DJAY_SOURCES", { enumerable: true, get: function () { return sources_js_1.DJAY_SOURCES; } });
+Object.defineProperty(exports, "isStreamingSource", { enumerable: true, get: function () { return sources_js_1.isStreamingSource; } });
+Object.defineProperty(exports, "toNowPlayingStreamingSource", { enumerable: true, get: function () { return sources_js_1.toNowPlayingStreamingSource; } });
+var logger_js_1 = require("./types/logger.js");
+Object.defineProperty(exports, "noopLogger", { enumerable: true, get: function () { return logger_js_1.noopLogger; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,uBAAuB;AACvB,mDAA+C;AAAtC,6GAAA,WAAW,OAAA;AAEpB,sBAAsB;AACtB,yCAKqB;AAJnB,sHAAA,yBAAyB,OAAA;AACzB,mHAAA,sBAAsB,OAAA;AACtB,oHAAA,uBAAuB,OAAA;AACvB,mHAAA,sBAAsB,OAAA;AAGxB,oDAAoD;AACpD,qCAQmB;AAPjB,wGAAA,aAAa,OAAA;AACb,wGAAA,aAAa,OAAA;AACb,sGAAA,WAAW,OAAA;AACX,yGAAA,cAAc,OAAA;AACd,4GAAA,iBAAiB,OAAA;AACjB,kHAAA,uBAAuB,OAAA;AAIzB,qCAAqC;AACrC,2CAMsB;AALpB,0GAAA,YAAY,OAAA;AACZ,+GAAA,iBAAiB,OAAA;AACjB,yHAAA,2BAA2B,OAAA;AAO7B,+CAA+C;AAAtC,uGAAA,UAAU,OAAA"}

package/dist/sources.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Known `originSourceID` values and URI schemes used by djay Pro.
+ *
+ * djay Pro for Windows 5.6.4 integrates with six streaming services and two
+ * "local" source categories. Not all of these were observable in the session
+ * used to reverse-engineer the format, so entries marked `observed: false`
+ * are educated guesses based on Algoriddim's naming convention (the service
+ * name in lowercase is used as both the URI scheme and the originSourceID).
+ *
+ * Verified: explorer, music, beatport, soundcloud, spotify
+ * Inferred: beatsource, tidal, applemusic
+ */
+/** Every track source djay Pro is known (or believed) to support. */
+export type DjayOriginSourceID = 'explorer' | 'music' | 'beatport' | 'beatsource' | 'soundcloud' | 'spotify' | 'tidal' | 'applemusic';
+export interface DjaySourceInfo {
+    /** The originSourceID string as written by djay Pro. */
+    id: DjayOriginSourceID;
+    /** Whether this value was observed in a live djay Pro 5.6.4 session. */
+    observed: boolean;
+    /** `local` = file on disk; `streaming` = streaming service. */
+    kind: 'local' | 'streaming';
+    /** Human-readable display label. */
+    label: string;
+    /**
+     * URI scheme prefix for tracks from this source in `sourceURIs`.
+     * Undefined for local sources (which use `file://` URIs).
+     */
+    uriSchemePrefix?: string;
+}
+/**
+ * Map of `originSourceID` → descriptive info. Callers can iterate this to
+ * build dropdown lists, detection heuristics, or validation helpers.
+ */
+export declare const DJAY_SOURCES: Record<DjayOriginSourceID, DjaySourceInfo>;
+/**
+ * Returns true if the given `originSourceID` represents a streaming service
+ * (as opposed to a local file). Unknown values default to `false`.
+ */
+export declare function isStreamingSource(id: string | undefined): boolean;
+/**
+ * Narrow a djay Pro `originSourceID` to the nowplaying3 `streamingSource`
+ * enum (`beatport | tidal | soundcloud | streaming-direct-play`). Services
+ * that aren't in the nowplaying3 enum (Spotify, Beatsource, Apple Music)
+ * map to `streaming-direct-play` as a generic fallback. Local sources
+ * return `undefined`.
+ */
+export declare function toNowPlayingStreamingSource(id: string | undefined): 'beatport' | 'tidal' | 'soundcloud' | 'streaming-direct-play' | undefined;

package/dist/sources.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * @fileoverview Known `originSourceID` values and URI schemes used by djay Pro.
+ *
+ * djay Pro for Windows 5.6.4 integrates with six streaming services and two
+ * "local" source categories. Not all of these were observable in the session
+ * used to reverse-engineer the format, so entries marked `observed: false`
+ * are educated guesses based on Algoriddim's naming convention (the service
+ * name in lowercase is used as both the URI scheme and the originSourceID).
+ *
+ * Verified: explorer, music, beatport, soundcloud, spotify
+ * Inferred: beatsource, tidal, applemusic
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DJAY_SOURCES = void 0;
+exports.isStreamingSource = isStreamingSource;
+exports.toNowPlayingStreamingSource = toNowPlayingStreamingSource;
+/**
+ * Map of `originSourceID` → descriptive info. Callers can iterate this to
+ * build dropdown lists, detection heuristics, or validation helpers.
+ */
+exports.DJAY_SOURCES = {
+    explorer: {
+        id: 'explorer',
+        observed: true,
+        kind: 'local',
+        label: 'File Explorer',
+    },
+    music: {
+        id: 'music',
+        observed: true,
+        kind: 'local',
+        label: 'OS Music Library',
+    },
+    beatport: {
+        id: 'beatport',
+        observed: true,
+        kind: 'streaming',
+        label: 'Beatport',
+        uriSchemePrefix: 'beatport:track:',
+    },
+    beatsource: {
+        id: 'beatsource',
+        observed: false,
+        kind: 'streaming',
+        label: 'Beatsource',
+        uriSchemePrefix: 'beatsource:track:',
+    },
+    soundcloud: {
+        id: 'soundcloud',
+        observed: true,
+        kind: 'streaming',
+        label: 'SoundCloud',
+        uriSchemePrefix: 'soundcloud:tracks:',
+    },
+    spotify: {
+        id: 'spotify',
+        observed: true,
+        kind: 'streaming',
+        label: 'Spotify',
+        uriSchemePrefix: 'spotify:track:',
+    },
+    tidal: {
+        id: 'tidal',
+        observed: false,
+        kind: 'streaming',
+        label: 'TIDAL',
+        uriSchemePrefix: 'tidal:track:',
+    },
+    applemusic: {
+        id: 'applemusic',
+        observed: false,
+        kind: 'streaming',
+        label: 'Apple Music',
+        uriSchemePrefix: 'applemusic:track:',
+    },
+};
+/**
+ * Returns true if the given `originSourceID` represents a streaming service
+ * (as opposed to a local file). Unknown values default to `false`.
+ */
+function isStreamingSource(id) {
+    if (!id)
+        return false;
+    const info = exports.DJAY_SOURCES[id];
+    return info?.kind === 'streaming';
+}
+/**
+ * Narrow a djay Pro `originSourceID` to the nowplaying3 `streamingSource`
+ * enum (`beatport | tidal | soundcloud | streaming-direct-play`). Services
+ * that aren't in the nowplaying3 enum (Spotify, Beatsource, Apple Music)
+ * map to `streaming-direct-play` as a generic fallback. Local sources
+ * return `undefined`.
+ */
+function toNowPlayingStreamingSource(id) {
+    if (!id)
+        return undefined;
+    switch (id) {
+        case 'beatport':
+            return 'beatport';
+        case 'tidal':
+            return 'tidal';
+        case 'soundcloud':
+            return 'soundcloud';
+        case 'spotify':
+        case 'beatsource':
+        case 'applemusic':
+            return 'streaming-direct-play';
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=sources.js.map

package/dist/sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.js","sourceRoot":"","sources":["../src/sources.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AA8FH,8CAIC;AASD,kEAuBC;AArGD;;;GAGG;AACU,QAAA,YAAY,GAA+C;IACtE,QAAQ,EAAE;QACR,EAAE,EAAE,UAAU;QACd,QAAQ,EAAE,IAAI;QACd,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,eAAe;KACvB;IACD,KAAK,EAAE;QACL,EAAE,EAAE,OAAO;QACX,QAAQ,EAAE,IAAI;QACd,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,kBAAkB;KAC1B;IACD,QAAQ,EAAE;QACR,EAAE,EAAE,UAAU;QACd,QAAQ,EAAE,IAAI;QACd,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,UAAU;QACjB,eAAe,EAAE,iBAAiB;KACnC;IACD,UAAU,EAAE;QACV,EAAE,EAAE,YAAY;QAChB,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,YAAY;QACnB,eAAe,EAAE,mBAAmB;KACrC;IACD,UAAU,EAAE;QACV,EAAE,EAAE,YAAY;QAChB,QAAQ,EAAE,IAAI;QACd,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,YAAY;QACnB,eAAe,EAAE,oBAAoB;KACtC;IACD,OAAO,EAAE;QACP,EAAE,EAAE,SAAS;QACb,QAAQ,EAAE,IAAI;QACd,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,SAAS;QAChB,eAAe,EAAE,gBAAgB;KAClC;IACD,KAAK,EAAE;QACL,EAAE,EAAE,OAAO;QACX,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,OAAO;QACd,eAAe,EAAE,cAAc;KAChC;IACD,UAAU,EAAE;QACV,EAAE,EAAE,YAAY;QAChB,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,aAAa;QACpB,eAAe,EAAE,mBAAmB;KACrC;CACF,CAAC;AAEF;;;GAGG;AACH,SAAgB,iBAAiB,CAAC,EAAsB;IACtD,IAAI,CAAC,EAAE;QAAE,OAAO,KAAK,CAAC;IACtB,MAAM,IAAI,GAAG,oBAAY,CAAC,EAAwB,CAAC,CAAC;IACpD,OAAO,IAAI,EAAE,IAAI,KAAK,WAAW,CAAC;AACpC,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,2BAA2B,CACzC,EAAsB;IAOtB,IAAI,CAAC,EAAE;QAAE,OAAO,SAAS,CAAC;IAC1B,QAAQ,EAAE,EAAE,CAAC;QACX,KAAK,UAAU;YACb,OAAO,UAAU,CAAC;QACpB,KAAK,OAAO;YACV,OAAO,OAAO,CAAC;QACjB,KAAK,YAAY;YACf,OAAO,YAAY,CAAC;QACtB,KAAK,SAAS,CAAC;QACf,KAAK,YAAY,CAAC;QAClB,KAAK,YAAY;YACf,OAAO,uBAAuB,CAAC;QACjC;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC"}

package/dist/tsaf.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview Minimal parser for Algoriddim's TSAF serialization format used inside
+ * djay Pro's MediaLibrary.db (YapDatabase `database2.data` column).
+ *
+ * TSAF records are a stream of typed values, where each value is followed by its key:
+ *
+ *   `<value bytes> 0x08 <key-ascii> 0x00`
+ *
+ * Known value tags:
+ *   - `0x08 <utf8-bytes> 0x00`  — UTF-8 string
+ *   - `0x14` + 8-byte little-endian IEEE 754 double (present as the 8 bytes immediately
+ *     preceding the key tag, regardless of any leading padding/subtype bytes)
+ *   - `0x30` + 8-byte little-endian CFAbsoluteTime double (seconds since 2001-01-01 UTC)
+ *
+ * We only need to extract a handful of known fields (title, artist, deckNumber, etc.),
+ * so rather than fully parsing the container, we locate each key tag and read the
+ * preceding value bytes according to the expected type. This approach has been verified
+ * against real `historySessionItems` rows on djay Pro for Windows.
+ */
+/** Extract a single typed field from a TSAF blob, or return undefined if not present. */
+export declare function extractString(blob: Buffer, key: string): string | undefined;
+export declare function extractDouble(blob: Buffer, key: string): number | undefined;
+export declare function extractDate(blob: Buffer, key: string): Date | undefined;
+/**
+ * Extract the nested `ADCMediaItemTitleID` — the 32-hex string that joins a
+ * history item to its row in `localMediaItemLocations` / `globalMediaItemLocations`
+ * / `mediaItemTitleIDs` / `mediaItemAnalyzedData` etc.
+ *
+ * Inside a TSAF blob the nested class looks like:
+ *
+ *   `0x2B 0x08 'ADCMediaItemTitleID' 0x00 0x08 <32-hex chars> 0x00 ...`
+ *
+ * We locate the class marker and read the tagged string that immediately
+ * follows it.
+ */
+export declare function extractTitleID(blob: Buffer): string | undefined;
+/** Shape of the fields we extract from a historySessionItems blob. */
+export interface DjayHistoryItemFields {
+    uuid: string;
+    sessionUUID: string;
+    /** 32-char hex titleID that joins into the location / analysis tables. */
+    titleID: string | undefined;
+    title: string;
+    artist: string;
+    duration: number;
+    deckNumber: number;
+    startTime: Date;
+    /** djay Pro's source identifier (e.g. 'explorer', 'spotify', 'beatport'). */
+    originSourceID: string | undefined;
+    /** International Standard Recording Code — present on streaming tracks. */
+    isrc: string | undefined;
+}
+/**
+ * Parse a historySessionItems blob into a typed record.
+ * Returns `null` if the blob is missing required fields (title or artist).
+ */
+export declare function parseHistorySessionItem(blob: Buffer): DjayHistoryItemFields | null;
+/**
+ * Extract the `sourceURIs` strings from a `localMediaItemLocations` or
+ * `globalMediaItemLocations` blob. A single location record can carry more
+ * than one URI — e.g. *Good Catch (Black Caviar Remix)* in the test session
+ * has both `soundcloud:tracks:1150488265` and `beatport:track:15949981`.
+ *
+ * Each URI is stored as a distinctive `0x21 0x08 <utf8 bytes> 0x00` sequence,
+ * wrapped in an array header `0x0B 0x00 0x00 <count> 0x00 0x00 0x00`. The
+ * array immediately precedes a `0x08 'sourceURIs' 0x00` key tag. Rather than
+ * fully decoding the array framing, we scan forward through the blob for any
+ * `0x21 0x08 <uri> 0x00` pattern that sits *before* the key and return all
+ * matches in order.
+ */
+export declare function extractSourceURIs(blob: Buffer): string[];

package/dist/tsaf.js

@@ -0,0 +1,212 @@
+"use strict";
+/**
+ * @fileoverview Minimal parser for Algoriddim's TSAF serialization format used inside
+ * djay Pro's MediaLibrary.db (YapDatabase `database2.data` column).
+ *
+ * TSAF records are a stream of typed values, where each value is followed by its key:
+ *
+ *   `<value bytes> 0x08 <key-ascii> 0x00`
+ *
+ * Known value tags:
+ *   - `0x08 <utf8-bytes> 0x00`  — UTF-8 string
+ *   - `0x14` + 8-byte little-endian IEEE 754 double (present as the 8 bytes immediately
+ *     preceding the key tag, regardless of any leading padding/subtype bytes)
+ *   - `0x30` + 8-byte little-endian CFAbsoluteTime double (seconds since 2001-01-01 UTC)
+ *
+ * We only need to extract a handful of known fields (title, artist, deckNumber, etc.),
+ * so rather than fully parsing the container, we locate each key tag and read the
+ * preceding value bytes according to the expected type. This approach has been verified
+ * against real `historySessionItems` rows on djay Pro for Windows.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractString = extractString;
+exports.extractDouble = extractDouble;
+exports.extractDate = extractDate;
+exports.extractTitleID = extractTitleID;
+exports.parseHistorySessionItem = parseHistorySessionItem;
+exports.extractSourceURIs = extractSourceURIs;
+/** CFAbsoluteTime epoch: 2001-01-01 00:00:00 UTC in milliseconds since Unix epoch. */
+const CF_EPOCH_MS = Date.UTC(2001, 0, 1, 0, 0, 0);
+const STRING_TAG = 0x08;
+/** Maximum bytes to walk backwards when resolving a string value. */
+const MAX_STRING_SCAN = 2048;
+function findKey(blob, key) {
+    const needle = Buffer.alloc(key.length + 2);
+    needle[0] = STRING_TAG;
+    needle.write(key, 1, 'ascii');
+    needle[needle.length - 1] = 0x00;
+    return blob.indexOf(needle);
+}
+/** Read an 8-byte little-endian double that sits immediately before the given key tag. */
+function readDoubleBeforeKey(blob, keyPos) {
+    if (keyPos < 8)
+        return undefined;
+    return blob.readDoubleLE(keyPos - 8);
+}
+/**
+ * Read a UTF-8 string value that precedes the given key tag.
+ * The value is encoded as `0x08 <utf8-bytes> 0x00` immediately before the key.
+ */
+function readStringBeforeKey(blob, keyPos) {
+    if (keyPos < 2)
+        return undefined;
+    const nullPos = keyPos - 1;
+    if (blob[nullPos] !== 0x00)
+        return undefined;
+    const scanLimit = Math.max(0, nullPos - MAX_STRING_SCAN);
+    for (let i = nullPos - 1; i >= scanLimit; i--) {
+        if (blob[i] !== STRING_TAG)
+            continue;
+        const value = blob.subarray(i + 1, nullPos);
+        if (!isPrintableUtf8(value))
+            continue;
+        return value.toString('utf-8');
+    }
+    return undefined;
+}
+function isPrintableUtf8(bytes) {
+    for (const b of bytes) {
+        // Allow common UTF-8 continuation/lead bytes (>= 0x80) and printable ASCII.
+        // Reject control characters except tab (rare in titles but allow for safety).
+        if (b === 0x09)
+            continue;
+        if (b >= 0x20 && b < 0x7f)
+            continue;
+        if (b >= 0x80)
+            continue;
+        return false;
+    }
+    return true;
+}
+/** Extract a single typed field from a TSAF blob, or return undefined if not present. */
+function extractString(blob, key) {
+    const pos = findKey(blob, key);
+    if (pos < 0)
+        return undefined;
+    return readStringBeforeKey(blob, pos);
+}
+function extractDouble(blob, key) {
+    const pos = findKey(blob, key);
+    if (pos < 0)
+        return undefined;
+    return readDoubleBeforeKey(blob, pos);
+}
+function extractDate(blob, key) {
+    const pos = findKey(blob, key);
+    if (pos < 0)
+        return undefined;
+    const cfAbsolute = readDoubleBeforeKey(blob, pos);
+    if (cfAbsolute === undefined || !Number.isFinite(cfAbsolute))
+        return undefined;
+    return new Date(CF_EPOCH_MS + cfAbsolute * 1000);
+}
+/**
+ * Extract the nested `ADCMediaItemTitleID` — the 32-hex string that joins a
+ * history item to its row in `localMediaItemLocations` / `globalMediaItemLocations`
+ * / `mediaItemTitleIDs` / `mediaItemAnalyzedData` etc.
+ *
+ * Inside a TSAF blob the nested class looks like:
+ *
+ *   `0x2B 0x08 'ADCMediaItemTitleID' 0x00 0x08 <32-hex chars> 0x00 ...`
+ *
+ * We locate the class marker and read the tagged string that immediately
+ * follows it.
+ */
+function extractTitleID(blob) {
+    const marker = Buffer.concat([
+        Buffer.from([0x2b, 0x08]),
+        Buffer.from('ADCMediaItemTitleID', 'ascii'),
+        Buffer.from([0x00]),
+    ]);
+    const markerPos = blob.indexOf(marker);
+    if (markerPos < 0)
+        return undefined;
+    const stringTagPos = markerPos + marker.length;
+    if (blob[stringTagPos] !== 0x08)
+        return undefined;
+    const stringStart = stringTagPos + 1;
+    const stringEnd = blob.indexOf(0x00, stringStart);
+    if (stringEnd < 0)
+        return undefined;
+    const candidate = blob.subarray(stringStart, stringEnd).toString('ascii');
+    // Sanity check: titleIDs are 32-char lowercase hex.
+    if (!/^[0-9a-f]{32}$/.test(candidate))
+        return undefined;
+    return candidate;
+}
+/**
+ * Parse a historySessionItems blob into a typed record.
+ * Returns `null` if the blob is missing required fields (title or artist).
+ */
+function parseHistorySessionItem(blob) {
+    const title = extractString(blob, 'title');
+    const artist = extractString(blob, 'artist');
+    if (!title || !artist)
+        return null;
+    const uuid = extractString(blob, 'uuid') ?? '';
+    const sessionUUID = extractString(blob, 'sessionUUID') ?? '';
+    const titleID = extractTitleID(blob);
+    const duration = extractDouble(blob, 'duration') ?? 0;
+    const deckRaw = extractDouble(blob, 'deckNumber') ?? 0;
+    const deckNumber = Number.isFinite(deckRaw) ? Math.round(deckRaw) : 0;
+    const startTime = extractDate(blob, 'startTime') ?? new Date(0);
+    const originSourceID = extractString(blob, 'originSourceID');
+    const isrc = extractString(blob, 'isrc');
+    return {
+        uuid,
+        sessionUUID,
+        titleID,
+        title,
+        artist,
+        duration,
+        deckNumber,
+        startTime,
+        originSourceID,
+        isrc,
+    };
+}
+/**
+ * Extract the `sourceURIs` strings from a `localMediaItemLocations` or
+ * `globalMediaItemLocations` blob. A single location record can carry more
+ * than one URI — e.g. *Good Catch (Black Caviar Remix)* in the test session
+ * has both `soundcloud:tracks:1150488265` and `beatport:track:15949981`.
+ *
+ * Each URI is stored as a distinctive `0x21 0x08 <utf8 bytes> 0x00` sequence,
+ * wrapped in an array header `0x0B 0x00 0x00 <count> 0x00 0x00 0x00`. The
+ * array immediately precedes a `0x08 'sourceURIs' 0x00` key tag. Rather than
+ * fully decoding the array framing, we scan forward through the blob for any
+ * `0x21 0x08 <uri> 0x00` pattern that sits *before* the key and return all
+ * matches in order.
+ */
+function extractSourceURIs(blob) {
+    const keyNeedle = Buffer.concat([
+        Buffer.from([0x08]),
+        Buffer.from('sourceURIs', 'ascii'),
+        Buffer.from([0x00]),
+    ]);
+    const keyPos = blob.indexOf(keyNeedle);
+    if (keyPos < 0)
+        return [];
+    const uris = [];
+    const window = blob.subarray(0, keyPos);
+    // Each element starts with `0x21 0x08 <utf8 bytes> 0x00`. Scan for the
+    // two-byte prefix, then read until the next 0x00.
+    for (let i = 0; i < window.length - 2; i++) {
+        if (window[i] !== 0x21 || window[i + 1] !== 0x08)
+            continue;
+        const stringStart = i + 2;
+        const stringEnd = window.indexOf(0x00, stringStart);
+        if (stringEnd < 0)
+            break;
+        const candidate = window.subarray(stringStart, stringEnd).toString('utf-8');
+        // Must look like a URI — contain a scheme colon and be at least 5 chars.
+        if (candidate.length < 5 || candidate.indexOf(':') <= 0) {
+            i = stringEnd;
+            continue;
+        }
+        uris.push(candidate);
+        i = stringEnd;
+    }
+    return uris;
+}
+//# sourceMappingURL=tsaf.js.map

package/dist/tsaf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tsaf.js","sourceRoot":"","sources":["../src/tsaf.ts"],"names":[],"mappings":"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"}

package/dist/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../src/detect.ts","../src/djayconnect.ts","../src/index.ts","../src/sources.ts","../src/tsaf.ts","../src/types.ts","../src/types/logger.ts"],"version":"5.9.3"}

package/dist/types/logger.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Logger interface for djay-connect.
+ * Allows consumers to inject their own logger implementation.
+ */
+export interface Logger {
+    trace(msg: string, ...args: unknown[]): void;
+    debug(msg: string, ...args: unknown[]): void;
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+}
+export declare const noopLogger: Logger;

package/dist/types/logger.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * @fileoverview Logger interface for djay-connect.
+ * Allows consumers to inject their own logger implementation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noopLogger = void 0;
+exports.noopLogger = {
+    trace() { },
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+};
+//# sourceMappingURL=logger.js.map

package/dist/types/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/types/logger.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAUU,QAAA,UAAU,GAAW;IAChC,KAAK,KAAI,CAAC;IACV,KAAK,KAAI,CAAC;IACV,IAAI,KAAI,CAAC;IACT,IAAI,KAAI,CAAC;IACT,KAAK,KAAI,CAAC;CACX,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,87 @@
+import EventEmitter from 'node:events';
+import type { StrictEventEmitter } from 'strict-event-emitter-types';
+import type { Logger } from './types/logger.js';
+/**
+ * Configuration options for DjayConnect.
+ */
+export type DjayConnectOptions = {
+    /** Polling interval in milliseconds (minimum 2000). Default: 2000 */
+    pollIntervalMs?: number;
+    /** Custom path to djay Pro's MediaLibrary.db. If omitted, uses the default per-platform path. */
+    databasePath?: string;
+    /** Logger instance. If omitted, logging is disabled. */
+    logger?: Logger;
+};
+/**
+ * A parsed track from djay Pro's history session.
+ */
+export interface DjayNowPlayingTrack {
+    /** Track title */
+    title: string;
+    /** Artist name */
+    artist: string;
+    /** Duration in seconds */
+    duration: number;
+    /** Deck number the track is loaded on (1-4) */
+    deckNumber: number;
+    /** When the track was started in djay Pro */
+    startTime: Date;
+    /** UUID of this history entry */
+    uuid: string;
+    /** UUID of the containing history session */
+    sessionUUID: string;
+    /**
+     * 32-hex `titleID` that joins the track to the location / analysis tables.
+     * Present for every track but may be missing on malformed blobs.
+     */
+    titleID?: string;
+    /**
+     * djay Pro's originSourceID for this track — identifies where the track
+     * came from. Known values include local sources (`explorer`, `music`)
+     * and streaming services (`beatport`, `beatsource`, `soundcloud`,
+     * `spotify`, `tidal`, `applemusic`).
+     */
+    originSourceID?: string;
+    /** International Standard Recording Code — present on streaming tracks. */
+    isrc?: string;
+    /**
+     * Absolute file path for tracks that live on local disk. Decoded from
+     * djay's URL-encoded `file://` URIs in `localMediaItemLocations`.
+     * Undefined for streaming tracks.
+     */
+    filePath?: string;
+    /**
+     * Raw `sourceURIs` from djay's location tables. Can contain more than one
+     * URI for tracks available on multiple streaming services, and the single
+     * `file://` URI for local tracks. Never undefined — empty array instead.
+     */
+    sourceURIs?: string[];
+}
+/**
+ * Info emitted when DjayConnect is ready.
+ */
+export type DjayReadyInfo = {
+    /** Path to the MediaLibrary.db file being monitored */
+    databasePath: string;
+};
+/**
+ * Payload for track events.
+ */
+export type DjayTrackPayload = {
+    /** The track that was detected */
+    track: DjayNowPlayingTrack;
+};
+/**
+ * Events emitted by DjayConnect.
+ */
+export interface DjayConnectEvents {
+    /** Emitted when the connector is ready and monitoring has started */
+    ready: (info: DjayReadyInfo) => void;
+    /** Emitted on each poll cycle */
+    poll: () => void;
+    /** Emitted when a new track is detected */
+    track: (payload: DjayTrackPayload) => void;
+    /** Emitted on errors */
+    error: (err: Error) => void;
+}
+export type TypedEmitter = StrictEventEmitter<EventEmitter, DjayConnectEvents>;

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "djay-connect",
+  "version": "2.0.0",
+  "description": "Library to read djay Pro's MediaLibrary.db and emit track change events",
+  "license": "MIT",
+  "private": false,
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "build": "tsc --build tsconfig.json",
+    "watch": "tsc --build tsconfig.json -w",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build && npm test",
+    "release": "node .github/release.js",
+    "release:patch": "node .github/release.js --patch",
+    "release:major": "node .github/release.js --major"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "better-sqlite3-multiple-ciphers": "^11.7.1",
+    "strict-event-emitter-types": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.15.29",
+    "@vitest/coverage-v8": "^4.0.16",
+    "prettier": "^3.5.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "overrides": {
+    "rollup": ">=4.59.0"
+  }
+}