alphatheta-connect 0.15.0

package/lib/localdb/database-adapter.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Common interface for database adapters.
+ *
+ * Both MetadataORM (for PDB files) and OneLibraryAdapter (for exportLibrary.db)
+ * implement this interface, allowing LocalDatabase to use either transparently.
+ */
+import { EntityFK, Playlist, PlaylistEntry, Track } from "../entities";
+/**
+ * Database format preference for loading rekordbox databases.
+ *
+ * - 'auto': Try OneLibrary first (rekordbox 7.x+), fall back to PDB (rekordbox 6.x)
+ * - 'oneLibrary': Only use OneLibrary format (exportLibrary.db)
+ * - 'pdb': Only use PDB format (export.pdb)
+ */
+export type DatabasePreference = 'auto' | 'oneLibrary' | 'pdb';
+/**
+ * Result of a playlist query
+ */
+export interface PlaylistQueryResult {
+    folders: Playlist[];
+    playlists: Playlist[];
+    trackEntries: PlaylistEntry<EntityFK.WithFKs>[];
+}
+/**
+ * Database type identifier
+ */
+export type DatabaseType = 'oneLibrary' | 'pdb';
+/**
+ * Common interface for database adapters
+ */
+export interface DatabaseAdapter {
+    /**
+     * The type of database (oneLibrary or pdb)
+     */
+    readonly type: DatabaseType;
+    /**
+     * Find a track by ID
+     */
+    findTrack(id: number): Track | 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): PlaylistQueryResult;
+    /**
+     * Close the database connection
+     */
+    close(): void;
+}

package/lib/localdb/index.d.ts

@@ -0,0 +1,104 @@
+import StrictEventEmitter from 'strict-event-emitter-types';
+import { EventEmitter } from 'events';
+import DeviceManager from "../devices";
+import { FetchProgress } from "../nfs";
+import StatusEmitter from "../status";
+import { Device, DeviceID, MediaSlot } from "../types";
+import { DatabaseAdapter, DatabasePreference, DatabaseType } from './database-adapter';
+import { HydrationProgress } from './rekordbox';
+/**
+ * Rekordbox databases will only exist within these two slots
+ */
+type DatabaseSlot = MediaSlot.USB | MediaSlot.SD;
+interface CommonProgressOpts {
+    /**
+     * The device progress is being reported for
+     */
+    device: Device;
+    /**
+     * The media slot progress is being reported for
+     */
+    slot: MediaSlot;
+}
+type DownloadProgressOpts = CommonProgressOpts & {
+    /**
+     * The current progress of the fetch
+     */
+    progress: FetchProgress;
+};
+type HydrationProgressOpts = CommonProgressOpts & {
+    /**
+     * The current progress of the database hydration
+     */
+    progress: HydrationProgress;
+};
+type HydrationDoneOpts = CommonProgressOpts;
+/**
+ * Events that may be triggered  by the LocalDatabase emitter
+ */
+interface DatabaseEvents {
+    /**
+     * Triggered when we are fetching a database from a CDJ
+     */
+    fetchProgress: (opts: DownloadProgressOpts) => void;
+    /**
+     * Triggered when we are hydrating a rekordbox database into the in-memory
+     * sqlite database.
+     */
+    hydrationProgress: (opts: HydrationProgressOpts) => void;
+    /**
+     * Triggered when the database has been fully hydrated.
+     *
+     * There is a period of time between hydrationProgress reporting 100% copletion,
+     * and the database being flushed, so it may be useful to wait for this event
+     * before considering the database to be fully hydrated.
+     */
+    hydrationDone: (opts: HydrationDoneOpts) => void;
+}
+type Emitter = StrictEventEmitter<EventEmitter, DatabaseEvents>;
+/**
+ * The local database is responsible for syncing the remote rekordbox databases
+ * of media slots on a device into in-memory sqlite databases.
+ *
+ * This service will attempt to ensure the in-memory databases for each media
+ * device that is connected to a CDJ is locally kept in sync. Fetching the
+ * database for any media slot of it's not already cached.
+ */
+declare class LocalDatabase {
+    #private;
+    constructor(hostDevice: Device, deviceManager: DeviceManager, statusEmitter: StatusEmitter, preference?: DatabasePreference);
+    /**
+     * Get the current database preference
+     */
+    get preference(): DatabasePreference;
+    /**
+     * Set the database preference. Only affects newly loaded databases.
+     */
+    set preference(value: DatabasePreference);
+    on: Emitter['on'];
+    off: Emitter['off'];
+    once: Emitter['once'];
+    /**
+     * Disconnects the local database connection for the specified device
+     */
+    disconnectForDevice(device: Device): void;
+    /**
+     * Gets the database adapter for the media metadata in the provided device slot.
+     *
+     * If the database has not already been loaded this will first fetch and load the
+     * database, which may take some time depending on the size of the database.
+     *
+     * @returns null if no rekordbox media present
+     */
+    get(deviceId: DeviceID, slot: DatabaseSlot): Promise<DatabaseAdapter | null>;
+    /**
+     * Get the database type for an already-loaded device slot.
+     * Returns null if no database is loaded for that device/slot.
+     */
+    getDatabaseType(deviceId: DeviceID, slot: DatabaseSlot): DatabaseType | null;
+    /**
+     * Preload the databases for all connected devices.
+     */
+    preload(): Promise<void>;
+}
+export default LocalDatabase;

package/lib/localdb/onelibrary-schema.d.ts

@@ -0,0 +1,250 @@
+/**
+ * TypeScript interfaces for the OneLibrary (exportLibrary.db) SQLite schema.
+ *
+ * These match the actual column names in the SQLite database,
+ * which differ from the legacy PDB format.
+ *
+ * Note: Column names use camelCase in the database (e.g., bpmx100, titleForSearch)
+ */
+export interface ContentRow {
+    content_id: number;
+    title: string | null;
+    titleForSearch: string | null;
+    subtitle: string | null;
+    bpmx100: number | null;
+    length: number | null;
+    trackNo: number | null;
+    discNo: number | null;
+    artist_id_artist: number | null;
+    artist_id_remixer: number | null;
+    artist_id_originalArtist: number | null;
+    artist_id_composer: number | null;
+    artist_id_lyricist: number | null;
+    album_id: number | null;
+    genre_id: number | null;
+    label_id: number | null;
+    key_id: number | null;
+    color_id: number | null;
+    image_id: number | null;
+    djComment: string | null;
+    rating: number | null;
+    releaseYear: number | null;
+    releaseDate: string | null;
+    dateCreated: string | null;
+    dateAdded: string | null;
+    path: string | null;
+    fileName: string | null;
+    fileSize: number | null;
+    fileType: number | null;
+    bitrate: number | null;
+    bitDepth: number | null;
+    samplingRate: number | null;
+    isrc: string | null;
+    djPlayCount: number | null;
+    isHotCueAutoLoadOn: number | null;
+    isKuvoDeliverStatusOn: number | null;
+    kuvoDeliveryComment: string | null;
+    masterDbId: number | null;
+    masterContentId: number | null;
+    analysisDataFilePath: string | null;
+    analysedBits: number | null;
+    contentLink: number | null;
+    hasModified: number | null;
+    cueUpdateCount: number | null;
+    analysisDataUpdateCount: number | null;
+    informationUpdateCount: number | null;
+}
+export interface ArtistRow {
+    artist_id: number;
+    name: string | null;
+    nameForSearch: string | null;
+}
+export interface AlbumRow {
+    album_id: number;
+    name: string | null;
+    artist_id: number | null;
+    image_id: number | null;
+    isComplation: number | null;
+    nameForSearch: string | null;
+}
+export interface GenreRow {
+    genre_id: number;
+    name: string | null;
+}
+export interface KeyRow {
+    key_id: number;
+    name: string | null;
+}
+export interface ColorRow {
+    color_id: number;
+    name: string | null;
+}
+export interface LabelRow {
+    label_id: number;
+    name: string | null;
+}
+export interface ImageRow {
+    image_id: number;
+    path: string | null;
+}
+export interface CueRow {
+    cue_id: number;
+    content_id: number | null;
+    kind: number | null;
+    colorTableIndex: number | null;
+    cueComment: string | null;
+    isActiveLoop: number | null;
+    beatLoopNumerator: number | null;
+    beatLoopDenominator: number | null;
+    inUsec: number | null;
+    outUsec: number | null;
+    in150FramePerSec: number | null;
+    out150FramePerSec: number | null;
+    inMpegFrameNumber: number | null;
+    outMpegFrameNumber: number | null;
+    inMpegAbs: number | null;
+    outMpegAbs: number | null;
+    inDecodingStartFramePosition: number | null;
+    outDecodingStartFramePosition: number | null;
+    inFileOffsetInBlock: number | null;
+    OutFileOffsetInBlock: number | null;
+    inNumberOfSampleInBlock: number | null;
+    outNumberOfSampleInBlock: number | null;
+}
+export interface PlaylistRow {
+    playlist_id: number;
+    sequenceNo: number | null;
+    name: string | null;
+    image_id: number | null;
+    attribute: number | null;
+    playlist_id_parent: number | null;
+}
+export interface PlaylistContentRow {
+    playlist_id: number;
+    content_id: number;
+    sequenceNo: number;
+}
+export interface PropertyRow {
+    deviceName: string | null;
+    dbVersion: string | null;
+    numberOfContents: number | null;
+    createdDate: string | null;
+    backGroundColorType: number | null;
+    myTagMasterDBID: number | null;
+}
+/**
+ * Cue point types based on the 'kind' field in the cue table.
+ *
+ * Note: These values may vary. Verify with actual data.
+ */
+export declare const CueKind: {
+    readonly MEMORY_CUE: 0;
+    readonly HOT_CUE: 1;
+};
+/**
+ * Playlist attribute types based on the 'attribute' field.
+ */
+export declare const PlaylistAttribute: {
+    readonly PLAYLIST: 0;
+    readonly FOLDER: 1;
+};
+export interface MyTagRow {
+    myTag_id: number;
+    sequenceNo: number | null;
+    name: string | null;
+    attribute: number | null;
+    myTag_id_parent: number | null;
+}
+export interface MyTagContentRow {
+    myTag_id: number;
+    content_id: number;
+}
+/**
+ * MyTag attribute types based on the 'attribute' field.
+ */
+export declare const MyTagAttribute: {
+    readonly TAG: 0;
+    readonly FOLDER: 1;
+};
+export interface HistoryRow {
+    history_id: number;
+    sequenceNo: number | null;
+    name: string | null;
+    attribute: number | null;
+    history_id_parent: number | null;
+}
+export interface HistoryContentRow {
+    history_id: number;
+    content_id: number;
+    sequenceNo: number;
+}
+export interface HotCueBankListRow {
+    hotCueBankList_id: number;
+    sequenceNo: number | null;
+    name: string | null;
+    image_id: number | null;
+    attribute: number | null;
+    hotCueBankList_id_parent: number | null;
+}
+export interface HotCueBankListCueRow {
+    hotCueBankList_id: number;
+    cue_id: number;
+    sequenceNo: number;
+}
+export interface MenuItemRow {
+    menuItem_id: number;
+    kind: number | null;
+    name: string | null;
+}
+export interface CategoryRow {
+    category_id: number;
+    menuItem_id: number | null;
+    sequenceNo: number | null;
+    isVisible: number | null;
+}
+export interface SortRow {
+    sort_id: number;
+    menuItem_id: number | null;
+    sequenceNo: number | null;
+    isVisible: number | null;
+    isSelectedAsSubColumn: number | null;
+}
+export interface RecommendedLikeRow {
+    content_id_1: number;
+    content_id_2: number;
+    rating: number | null;
+    createdDate: number | null;
+}
+/**
+ * Menu item kinds for browsing categories.
+ * These match the 'kind' field in the menuItem table.
+ */
+export declare const MenuItemKind: {
+    readonly GENRE: 128;
+    readonly ARTIST: 129;
+    readonly ALBUM: 130;
+    readonly TRACK: 131;
+    readonly PLAYLIST: 132;
+    readonly BPM: 133;
+    readonly RATING: 134;
+    readonly YEAR: 135;
+    readonly REMIXER: 136;
+    readonly LABEL: 137;
+    readonly ORIGINAL_ARTIST: 138;
+    readonly KEY: 139;
+    readonly DATE_ADDED: 140;
+    readonly CUE: 141;
+    readonly COLOR: 142;
+    readonly FOLDER: 144;
+    readonly SEARCH: 145;
+    readonly TIME: 146;
+    readonly BITRATE: 147;
+    readonly FILE_NAME: 148;
+    readonly HISTORY: 149;
+    readonly COMMENTS: 150;
+    readonly DJ_PLAY_COUNT: 151;
+    readonly HOT_CUE_BANK: 152;
+    readonly DEFAULT: 161;
+    readonly ALPHABET: 162;
+    readonly MATCHING: 170;
+};

package/lib/localdb/onelibrary.d.ts

@@ -0,0 +1,185 @@
+/**
+ * OneLibrary Database Adapter
+ *
+ * Provides an interface for reading the OneLibrary (exportLibrary.db) SQLite database
+ * used by modern rekordbox versions and Pioneer DJ devices.
+ *
+ * The database is encrypted with SQLCipher 4. The encryption key is derived from
+ * a hardcoded obfuscated blob.
+ */
+import Database from 'better-sqlite3-multiple-ciphers';
+import { Album, Artist, Artwork, Color, EntityFK, Genre, Key, Label, Playlist, PlaylistEntry, Track } from "../entities";
+import { CueAndLoop } from "../types";
+import { DatabaseAdapter, DatabaseType } from './database-adapter';
+/**
+ * Get the SQLCipher encryption key for OneLibrary databases
+ */
+export declare function getEncryptionKey(): string;
+/**
+ * Open a OneLibrary database with SQLCipher decryption
+ */
+export declare function openOneLibraryDb(dbPath: string): Database.Database;
+/**
+ * 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;
+}
+/**
+ * User-created tag (MyTag)
+ */
+export interface MyTag {
+    id: number;
+    name: string;
+    isFolder: boolean;
+    parentId: number | null;
+}
+/**
+ * History session
+ */
+export interface HistorySession {
+    id: number;
+    name: string;
+    parentId: number | null;
+}
+/**
+ * Hot cue bank list
+ */
+export interface HotCueBankList {
+    id: number;
+    name: string;
+    parentId: number | null;
+}
+/**
+ * Menu item for browsing
+ */
+export interface MenuItem {
+    id: number;
+    kind: number;
+    name: string;
+}
+/**
+ * Browse category
+ */
+export interface Category {
+    id: number;
+    menuItemId: number;
+    name: string;
+    kind: number;
+    isVisible: boolean;
+}
+/**
+ * Sort option
+ */
+export interface SortOption {
+    id: number;
+    menuItemId: number;
+    name: string;
+    kind: number;
+    isVisible: boolean;
+    isSelectedAsSubColumn: boolean;
+}
+/**
+ * Device property
+ */
+export interface DeviceProperty {
+    deviceName: string;
+    dbVersion: string;
+    numberOfContents: number;
+    createdDate: string;
+    backgroundColorType: number;
+}

package/lib/localdb/orm.d.ts

@@ -0,0 +1,60 @@
+import { EntityFK, Playlist, PlaylistEntry, Track } from "../entities";
+import { DatabaseAdapter, DatabaseType } from './database-adapter';
+/**
+ * Table names available
+ */
+export declare enum Table {
+    Artist = "artist",
+    Album = "album",
+    Genre = "genre",
+    Color = "color",
+    Label = "label",
+    Key = "key",
+    Artwork = "artwork",
+    Playlist = "playlist",
+    PlaylistEntry = "playlist_entry",
+    Track = "track"
+}
+/**
+ * Object Relation Mapper as an abstraction ontop of a local database
+ * connection.
+ *
+ * May be used to populate a metadata database and query objects.
+ */
+export declare class MetadataORM implements DatabaseAdapter {
+    #private;
+    readonly type: DatabaseType;
+    constructor();
+    close(): void;
+    /**
+     * Begin a transaction for bulk inserts. Call commit() when done.
+     */
+    beginTransaction(): void;
+    /**
+     * Commit the current transaction.
+     */
+    commit(): void;
+    /**
+     * Insert a entity object into the database.
+     * For bulk inserts, call beginTransaction() first and commit() when done.
+     */
+    insertEntity(table: Table, object: Record<string, any>): void;
+    /**
+     * Locate a track by ID in the database
+     */
+    findTrack(id: number): Track | null;
+    /**
+     * Query for a list of {folders, playlists, tracks} given a playlist ID. If
+     * no ID is provided the root list is queried.
+     *
+     * Note that when tracks are returned there will be no folders or playslists.
+     * But the API here is simpler to assume there could be.
+     *
+     * Tracks are returned in the order they are placed on the playlist.
+     */
+    findPlaylist(playlistId?: number): {
+        folders: Playlist[];
+        playlists: Playlist[];
+        trackEntries: PlaylistEntry<EntityFK.WithFKs>[];
+    };
+}