alphatheta-connect 0.15.0 → 0.18.0

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

@@ -1,49 +1,4 @@
 /**
- * Common interface for database adapters.
- *
- * Both MetadataORM (for PDB files) and OneLibraryAdapter (for exportLibrary.db)
- * implement this interface, allowing LocalDatabase to use either transparently.
+ * Re-export database adapter types from onelibrary-connect.
  */
-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;
-}
+export type { DatabaseAdapter, DatabasePreference, DatabaseType, PlaylistQueryResult, } from 'onelibrary-connect';

package/lib/localdb/index.d.ts

@@ -1,10 +1,10 @@
+import { type DatabaseAdapter, type DatabasePreference, type DatabaseType } from 'onelibrary-connect';
 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

package/lib/localdb/onelibrary/adapter.d.ts

@@ -0,0 +1,110 @@
+/**
+ * OneLibrary Database Adapter
+ *
+ * Provides an interface for reading the OneLibrary (exportLibrary.db) SQLite database
+ * used by modern rekordbox versions and Pioneer DJ devices.
+ */
+import { Album, Artist, Artwork, Color, EntityFK, Genre, Key, Label, Playlist, PlaylistEntry, Track } from "../../entities";
+import { CueAndLoop } from "../../types";
+import { DatabaseAdapter, DatabaseType } from '../database-adapter';
+import type { Category, DeviceProperty, HistorySession, HotCueBankList, MenuItem, MyTag, SortOption } from './types';
+/**
+ * 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;
+}

package/lib/localdb/onelibrary/connection.d.ts

@@ -0,0 +1,8 @@
+/**
+ * OneLibrary Database Connection
+ */
+import Database from 'better-sqlite3-multiple-ciphers';
+/**
+ * Open a OneLibrary database with SQLCipher decryption
+ */
+export declare function openOneLibraryDb(dbPath: string): Database.Database;

package/lib/localdb/onelibrary/encryption.d.ts

@@ -0,0 +1,10 @@
+/**
+ * OneLibrary Database Encryption
+ *
+ * The database is encrypted with SQLCipher 4. The encryption key is derived from
+ * a hardcoded obfuscated blob.
+ */
+/**
+ * Get the SQLCipher encryption key for OneLibrary databases
+ */
+export declare function getEncryptionKey(): string;

package/lib/localdb/onelibrary/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Re-exports from onelibrary-connect
+ */
+export { getEncryptionKey, openOneLibraryDb, OneLibraryAdapter, } from 'onelibrary-connect';
+export type { Category, DeviceProperty, HistorySession, HotCueBankList, MenuItem, MyTag, SortOption, } from 'onelibrary-connect';

package/lib/localdb/onelibrary/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * OneLibrary Entity Types
+ */
+/**
+ * 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/onelibrary.d.ts

@@ -1,185 +1,7 @@
 /**
  * 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
+ * Re-exports from onelibrary-connect for backward compatibility.
  */
-export interface DeviceProperty {
-    deviceName: string;
-    dbVersion: string;
-    numberOfContents: number;
-    createdDate: string;
-    backgroundColorType: number;
-}
+export type { Category, DeviceProperty, HistorySession, HotCueBankList, MenuItem, MyTag, SortOption, } from 'onelibrary-connect';
+export { getEncryptionKey, OneLibraryAdapter, openOneLibraryDb } from 'onelibrary-connect';

package/lib/localdb/rekordbox/anlz-parsers.d.ts

@@ -0,0 +1,37 @@
+import { BeatGrid, CueAndLoop, ExtendedCue, SongStructure, VocalConfig, Waveform3BandDetail, Waveform3BandPreview, WaveformHD, WaveformPreviewData } from "../../types";
+/**
+ * Fill beatgrid data from the ANLZ section
+ */
+export declare function makeBeatGrid(data: any): BeatGrid;
+/**
+ * Fill cue and loop data from the ANLZ section
+ */
+export declare function makeCueAndLoop(data: any): CueAndLoop[];
+/**
+ * Fill waveform HD data from the ANLZ section
+ */
+export declare function makeWaveformHd(data: any): WaveformHD;
+/**
+ * Parse extended cues (PCO2) with colors and comments
+ */
+export declare function makeExtendedCues(data: any): ExtendedCue[];
+/**
+ * Parse song structure (PSSI) with phrase analysis
+ */
+export declare function makeSongStructure(data: any): SongStructure;
+/**
+ * Parse waveform preview data (PWAV/PWV2)
+ */
+export declare function makeWaveformPreview(data: any): WaveformPreviewData;
+/**
+ * Parse 3-band color waveform preview (PWV6 from .2EX files)
+ */
+export declare function makeWaveform3BandPreview(data: any): Waveform3BandPreview;
+/**
+ * Parse 3-band color detail waveform (PWV7 from .2EX files)
+ */
+export declare function makeWaveform3BandDetail(data: any): Waveform3BandDetail;
+/**
+ * Parse vocal detection config (PWVC from .2EX files)
+ */
+export declare function makeVocalConfig(data: any): VocalConfig;

package/lib/localdb/rekordbox/entity-creators.d.ts

@@ -0,0 +1,27 @@
+import { Album, Artist, Artwork, Color, EntityFK, Genre, Key, Label, Playlist, PlaylistEntry, Track } from "../../entities";
+interface IdAndNameEntity {
+    id: number;
+    name: string;
+}
+/**
+ * Utility to create a hydrator that hydrates the provided entity with the id
+ * and name properties from the row.
+ */
+export declare const makeIdNameHydrator: <T extends IdAndNameEntity>() => (row: any) => T;
+/**
+ * Translates a pdb track row entry to a {@link Track} entity.
+ */
+export declare function createTrack(trackRow: any): Track<EntityFK.WithFKs>;
+/**
+ * Translates a pdb playlist row entry into a {@link Playlist} entity.
+ */
+export declare function createPlaylist(playlistRow: any): Playlist;
+/**
+ * Translates a pdb playlist track entry into a {@link PlaylistTrack} entity.
+ */
+export declare function createPlaylistEntry(playlistTrackRow: any): PlaylistEntry<EntityFK.WithFKs>;
+/**
+ * Translates a pdb artwork entry into a {@link Artwork} entity.
+ */
+export declare function createArtworkEntry(artworkRow: any): Artwork;
+export type { Album, Artist, Color, Genre, Key, Label };

package/lib/localdb/rekordbox/hydrator.d.ts

@@ -0,0 +1,20 @@
+import { TelemetrySpan as Span } from "../../utils/telemetry";
+import type { HydrationOptions } from './types';
+/**
+ * This service provides utilities for translating rekordbox database (pdb_ and
+ * analysis (ANLZ) files into the common entity types used in this library.
+ */
+export declare class RekordboxHydrator {
+    #private;
+    constructor({ orm, onProgress }: Omit<HydrationOptions, 'pdbData' | 'span'>);
+    /**
+     * Extract entries from a rekordbox pdb file and hydrate the passed database
+     * connection with entities derived from the rekordbox entries.
+     */
+    hydrateFromPdb(pdbData: Buffer, span?: Span): Promise<void>;
+    /**
+     * Hydrate the database with entities from the provided RekordboxPdb table.
+     * See pdbEntityCreators for how tables are mapped into database entities.
+     */
+    hydrateFromTable(table: any, span: Span): Promise<void>;
+}

package/lib/localdb/rekordbox/index.d.ts

@@ -0,0 +1,13 @@
+import { Track } from "../../entities";
+import type { AnlzResolver, AnlzResponse, AnlzResponse2EX, AnlzResponseDAT, AnlzResponseEXT, HydrationOptions, HydrationProgress } from './types';
+export type { AnlzResolver, AnlzResponse, AnlzResponse2EX, AnlzResponseDAT, AnlzResponseEXT, HydrationOptions, HydrationProgress, };
+/**
+ * Given a rekordbox pdb file contents. This function will hydrate the provided
+ * database with all entities from the Rekordbox database. This includes all
+ * track metadata, including analyzed metadata (such as beatgrids and waveforms).
+ */
+export declare function hydrateDatabase({ pdbData, span, ...options }: HydrationOptions): Promise<void>;
+/**
+ * Loads the ANLZ data of a Track entity from the analyzePath.
+ */
+export declare function loadAnlz<T extends keyof AnlzResponse>(track: Pick<Track, 'analyzePath'>, type: T, anlzResolver: AnlzResolver): Promise<AnlzResponse[T]>;

package/lib/localdb/rekordbox/table-mappings.d.ts

@@ -0,0 +1,10 @@
+import { Table } from "../orm";
+/**
+ * Maps rekordbox pdb table types to orm table names.
+ */
+export declare const pdbTables: Record<number, Table>;
+/**
+ * Maps rekordbox pdb table types to functions that create entity objects for
+ * the passed pdb row.
+ */
+export declare const pdbEntityCreators: Record<number, (row: any) => any>;

package/lib/localdb/rekordbox/types.d.ts

@@ -0,0 +1,118 @@
+import { MetadataORM } from "../orm";
+import { BeatGrid, CueAndLoop, ExtendedCue, SongStructure, VocalConfig, Waveform3BandDetail, Waveform3BandPreview, WaveformHD, WaveformPreviewData } from "../../types";
+import { TelemetrySpan as Span } from "../../utils/telemetry";
+/**
+ * The provided function should resolve ANLZ files into buffers. Typically
+ * you would just read the file, but in the case of the prolink network, this
+ * would handle loading the file over NFS.
+ */
+export type AnlzResolver = (path: string) => Promise<Buffer>;
+/**
+ * Data returned from loading DAT anlz files
+ */
+export interface AnlzResponseDAT {
+    /**
+     * Embedded beat grid information
+     */
+    beatGrid: BeatGrid | null;
+    /**
+     * Embedded cue and loop information
+     */
+    cueAndLoops: CueAndLoop[] | null;
+    /**
+     * Standard waveform preview (400 bytes, PWAV tag)
+     */
+    waveformPreview: WaveformPreviewData | null;
+    /**
+     * Tiny waveform preview (100 bytes, PWV2 tag)
+     */
+    waveformTiny: WaveformPreviewData | null;
+}
+/**
+ * Data returned from loading EXT anlz files
+ */
+export interface AnlzResponseEXT {
+    /**
+     * HD Waveform information (PWV5 tag)
+     */
+    waveformHd: WaveformHD | null;
+    /**
+     * Extended cues with colors and comments (PCO2 tag)
+     */
+    extendedCues: ExtendedCue[] | null;
+    /**
+     * Song structure / phrase analysis (PSSI tag)
+     */
+    songStructure: SongStructure | null;
+    /**
+     * Monochrome detailed waveform (PWV3 tag)
+     */
+    waveformDetail: Uint8Array | null;
+    /**
+     * Color waveform preview (PWV4 tag, 7200 bytes = 1200 columns × 6 bytes)
+     */
+    waveformColorPreview: Uint8Array | null;
+}
+/**
+ * Data returned from loading 2EX anlz files
+ */
+export interface AnlzResponse2EX {
+    /**
+     * 3-band color waveform preview (PWV6 tag)
+     */
+    waveform3BandPreview: Waveform3BandPreview | null;
+    /**
+     * 3-band color detail waveform (PWV7 tag)
+     */
+    waveform3BandDetail: Waveform3BandDetail | null;
+    /**
+     * Vocal detection config (PWVC tag)
+     */
+    vocalConfig: VocalConfig | null;
+}
+export interface AnlzResponse {
+    DAT: AnlzResponseDAT;
+    EXT: AnlzResponseEXT;
+    '2EX': AnlzResponse2EX;
+}
+/**
+ * Details about the current state of the hydtration task
+ */
+export interface HydrationProgress {
+    /**
+     * The specific table that progress is being reported for
+     */
+    table: string;
+    /**
+     * The total progress steps for this table
+     */
+    total: number;
+    /**
+     * The completed number of progress steps
+     */
+    complete: number;
+}
+/**
+ * Options to hydrate the database
+ */
+export interface HydrationOptions {
+    /**
+     * The metadata ORM of which the tables will be hydrated
+     */
+    orm: MetadataORM;
+    /**
+     * This buffer should contain the Rekordbox pdb file contents. It will be
+     * used to do the hydration
+     */
+    pdbData: Buffer;
+    /**
+     * Sentry tracing span for the parent transaction
+     */
+    span?: Span;
+    /**
+     * For larger music collections, it may take some time to load everything,
+     * especially when limited by IO. When hydration progresses this function
+     * will be called.
+     */
+    onProgress?: (progress: HydrationProgress) => void;
+}