onelibrary-connect 1.1.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,112 @@
+# onelibrary-connect
+
+Read and query rekordbox **OneLibrary** (`exportLibrary.db`) SQLCipher databases
+from Pioneer DJ / AlphaTheta devices. Useful for inspecting USB exports, CDJ
+SD cards, and the OneLibrary databases used by modern rekordbox versions.
+
+## Installation
+
+```bash
+npm install onelibrary-connect
+```
+
+This package depends on `better-sqlite3-multiple-ciphers` for SQLCipher
+decryption. It will be built as a native module on install.
+
+## Usage
+
+```typescript
+import { OneLibraryAdapter } from 'onelibrary-connect';
+
+const db = new OneLibraryAdapter('/path/to/exportLibrary.db');
+
+// Look up a single track
+const track = db.findTrack(1);
+console.log(`${track.artist?.name} - ${track.title}`);
+
+// Iterate every track
+for (const t of db.findAllTracks()) {
+  console.log(t.id, t.title, t.tempo, t.key?.name);
+}
+
+// Walk the playlist tree
+const { folders, playlists, trackEntries } = db.findPlaylist();
+for (const playlist of playlists) {
+  const trackIds = db.findPlaylistContents(playlist.id);
+  console.log(`${playlist.name}: ${trackIds.length} tracks`);
+}
+
+// History sessions (one per DJ set recorded on the device)
+for (const session of db.findHistorySessions()) {
+  const trackIds = db.findHistoryContents(session.id);
+  console.log(`${session.name}: ${trackIds.length} tracks`);
+}
+
+db.close();
+```
+
+## API
+
+### `new OneLibraryAdapter(dbPath: string)`
+
+Open a OneLibrary database. The file is opened read-only and decrypted with the
+built-in SQLCipher key used by Pioneer DJ devices.
+
+### Track queries
+
+- `findTrack(id)` — Find a track by `content_id`, with joined artist, album,
+  genre, key, color, label, artwork, remixer, original artist, and composer
+- `findAllTracks()` — Return every track in the library
+
+### Cue queries
+
+- `findCues(trackId)` — Return all cue points, loops, hot cues, and hot loops
+  for a track as a unified `CueAndLoop[]`
+
+### Playlist queries
+
+- `findPlaylist(playlistId?)` — Return `{ folders, playlists, trackEntries }`
+  for a given playlist ID, or the root if omitted
+- `findPlaylistById(id)` — Fetch a single playlist row
+- `findPlaylistContents(id)` — Track IDs in order for a playlist
+
+### MyTag queries
+
+- `findMyTags(parentId?)` — Return `{ folders, tags }` for MyTags
+- `findMyTagById(id)` / `findMyTagContents(id)` / `findMyTagsForTrack(trackId)`
+
+### History queries
+
+- `findHistorySessions()` — All history sessions on the device
+- `findHistoryContents(historyId)` — Track IDs in a session
+
+### Hot cue bank lists
+
+- `findHotCueBankLists()` — All hot cue bank lists
+- `findHotCueBankListCues(bankListId)` — Cue IDs in a bank list
+
+### Menu / sort configuration
+
+- `findMenuItems()` — All browse menu items
+- `findVisibleCategories()` — Categories the user has enabled
+- `findVisibleSortOptions()` — Sort options the user has enabled
+
+### Reference tables
+
+- `findArtist(id)`, `findAlbum(id)`, `findGenre(id)`, `findKey(id)`,
+  `findColor(id)`, `findLabel(id)`, `findArtwork(id)`
+
+### Device properties
+
+- `getProperty()` — Returns `{ deviceName, dbVersion, numberOfContents,
+  createdDate, backgroundColorType }`
+
+### Low-level
+
+- `openOneLibraryDb(path)` — Open the SQLCipher database directly without the
+  adapter wrapper
+- `getEncryptionKey()` — Returns the SQLCipher key
+
+## License
+
+MIT

package/dist/adapter.d.ts

@@ -0,0 +1,111 @@
+/**
+ * OneLibrary Database Adapter
+ *
+ * Provides an interface for reading the OneLibrary (exportLibrary.db) SQLite database
+ * used by modern rekordbox versions and Pioneer DJ devices.
+ */
+import type { Album, Artist, Artwork, Color, EntityFK, Genre, Key, Label, Playlist, PlaylistEntry, Track } from './entities.js';
+import type { CueAndLoop } from './types.js';
+import type { Category, DeviceProperty, HistorySession, HotCueBankList, MenuItem, MyTag, SortOption } from './types.js';
+import type { DatabaseAdapter, DatabaseType } from './database-adapter.js';
+/**
+ * Adapter for OneLibrary database that matches the ORM interface.
+ * Queries the SQLite file directly instead of hydrating into memory.
+ */
+export declare class OneLibraryAdapter implements DatabaseAdapter {
+    #private;
+    readonly type: DatabaseType;
+    constructor(dbPath: string);
+    /**
+     * Close the database connection
+     */
+    close(): void;
+    /**
+     * Find a track by ID
+     */
+    findTrack(id: number): Track | null;
+    /**
+     * Find all tracks in the database
+     */
+    findAllTracks(): Track[];
+    /**
+     * Find cue points for a track
+     */
+    findCues(trackId: number): CueAndLoop[];
+    /**
+     * Find a playlist by ID
+     */
+    findPlaylistById(playlistId: number): Playlist | null;
+    /**
+     * Query for a list of {folders, playlists, tracks} given a playlist ID.
+     * If no ID is provided the root list is queried.
+     */
+    findPlaylist(playlistId?: number): {
+        folders: Playlist[];
+        playlists: Playlist[];
+        trackEntries: PlaylistEntry<EntityFK.WithFKs>[];
+    };
+    /**
+     * Get track IDs for a playlist in order
+     */
+    findPlaylistContents(playlistId: number): number[];
+    findArtist(artistId: number): Artist | null;
+    findAlbum(albumId: number): Album | null;
+    findGenre(genreId: number): Genre | null;
+    findKey(keyId: number): Key | null;
+    findColor(colorId: number): Color | null;
+    findLabel(labelId: number): Label | null;
+    findArtwork(imageId: number): Artwork | null;
+    /**
+     * Find all root-level MyTags (folders and tags with no parent)
+     */
+    findMyTags(parentId?: number): {
+        folders: MyTag[];
+        tags: MyTag[];
+    };
+    /**
+     * Find a MyTag by ID
+     */
+    findMyTagById(myTagId: number): MyTag | null;
+    /**
+     * Get track IDs for a MyTag
+     */
+    findMyTagContents(myTagId: number): number[];
+    /**
+     * Get all MyTags assigned to a track
+     */
+    findMyTagsForTrack(trackId: number): MyTag[];
+    /**
+     * Find all history sessions
+     */
+    findHistorySessions(): HistorySession[];
+    /**
+     * Get track IDs for a history session in order
+     */
+    findHistoryContents(historyId: number): number[];
+    /**
+     * Find all hot cue bank lists
+     */
+    findHotCueBankLists(): HotCueBankList[];
+    /**
+     * Get cue IDs for a hot cue bank list
+     */
+    findHotCueBankListCues(bankListId: number): number[];
+    /**
+     * Get all menu items (browse categories)
+     */
+    findMenuItems(): MenuItem[];
+    /**
+     * Get visible categories with their menu item info
+     */
+    findVisibleCategories(): Category[];
+    /**
+     * Get visible sort options
+     */
+    findVisibleSortOptions(): SortOption[];
+    /**
+     * Get device properties
+     */
+    getProperty(): DeviceProperty | null;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EACV,KAAK,EACL,MAAM,EACN,OAAO,EACP,KAAK,EACL,QAAQ,EACR,KAAK,EACL,GAAG,EACH,KAAK,EACL,QAAQ,EACR,aAAa,EACb,KAAK,EACN,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAC,UAAU,EAAyB,MAAM,YAAY,CAAC;AACnE,OAAO,KAAK,EACV,QAAQ,EACR,cAAc,EACd,cAAc,EACd,cAAc,EACd,QAAQ,EACR,KAAK,EACL,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAC,eAAe,EAAE,YAAY,EAAC,MAAM,uBAAuB,CAAC;AAoBzE;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,eAAe;;IACvD,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAgB;gBAK/B,MAAM,EAAE,MAAM;IAI1B;;OAEG;IACH,KAAK,IAAI,IAAI;IAqBb;;OAEG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IAoCnC;;OAEG;IACH,aAAa,IAAI,KAAK,EAAE;IAyGxB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE;IAmEvC;;OAEG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAUrD;;;OAGG;IACH,YAAY,CAAC,UAAU,CAAC,EAAE,MAAM;;;;;IA6ChC;;OAEG;IACH,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;IA2BlD,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAU3C,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IAUxC,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IAUxC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI;IAUlC,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IAUxC,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IAUxC,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI;IAc5C;;OAEG;IACH,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG;QAAC,OAAO,EAAE,KAAK,EAAE,CAAC;QAAC,IAAI,EAAE,KAAK,EAAE,CAAA;KAAC;IA+BhE;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IAU5C;;OAEG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAU5C;;OAEG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE;IAyB5C;;OAEG;IACH,mBAAmB,IAAI,cAAc,EAAE;IAcvC;;OAEG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE;IAehD;;OAEG;IACH,mBAAmB,IAAI,cAAc,EAAE;IAcvC;;OAEG;IACH,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;IAepD;;OAEG;IACH,aAAa,IAAI,QAAQ,EAAE;IAc3B;;OAEG;IACH,qBAAqB,IAAI,QAAQ,EAAE;IAoBnC;;OAEG;IACH,sBAAsB,IAAI,UAAU,EAAE;IAyBtC;;OAEG;IACH,WAAW,IAAI,cAAc,GAAG,IAAI;CAmBrC"}