alphatheta-connect 0.15.0 → 0.19.1

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/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.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;
+}

package/lib/localdb/rekordbox.d.ts

@@ -1,112 +1,8 @@
-import { Track } from "../entities";
-import { MetadataORM } from "./orm";
-import { BeatGrid, CueAndLoop, ExtendedCue, SongStructure, 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.
+ * Rekordbox Database Utilities
+ *
+ * Re-exports from the rekordbox/ folder for backward compatibility.
+ * @see ./rekordbox/index.ts for the implementation
  */
-type AnlzResolver = (path: string) => Promise<Buffer>;
-/**
- * Data returned from loading DAT anlz files
- */
-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
- */
-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;
-}
-interface AnlzResponse {
-    DAT: AnlzResponseDAT;
-    EXT: AnlzResponseEXT;
-}
-/**
- * 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
- */
-interface Options {
-    /**
-     * 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;
-}
-/**
- * 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 }: Options): Promise<void>;
-/**
- * Loads the ANLZ data of a Track entity from the analyzePath.
- */
-export declare function loadAnlz<T extends keyof AnlzResponse>(track: Track, type: T, anlzResolver: AnlzResolver): Promise<AnlzResponse[T]>;
-export {};
+export type { AnlzResolver, AnlzResponse, AnlzResponse2EX, AnlzResponseDAT, AnlzResponseEXT, HydrationOptions, HydrationProgress, } from './rekordbox/index';
+export { hydrateDatabase, loadAnlz } from './rekordbox/index';

package/lib/logger.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Logger interface for alphatheta-connect package.
+ * Consumers can supply their own logger implementation.
+ * If no logger is provided, a no-op logger is used (silent).
+ */
+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/lib/metadata.d.ts

@@ -0,0 +1,45 @@
+import type { ExtractedMetadata, FileReader } from 'metadata-connect';
+import { NfsMediaSlot } from './nfs';
+import { Device } from './types';
+export type { ExtractedMetadata } from 'metadata-connect';
+/**
+ * Extract full metadata from an audio file using a FileReader.
+ *
+ * This is the low-level API that works with any FileReader implementation.
+ * For extracting from a Pro DJ Link device, use extractMetadataFromDevice.
+ *
+ * @param reader - FileReader interface for reading file data
+ * @returns Extracted metadata, or null if extraction fails
+ */
+export declare function extractFullMetadata(reader: FileReader): Promise<ExtractedMetadata | null>;
+/**
+ * Check if metadata extraction is supported for a file extension.
+ *
+ * @param extension - File extension (with or without leading dot)
+ * @returns true if the extension is supported
+ */
+export declare function isMetadataExtractionSupported(extension: string): boolean;
+/**
+ * Extract full metadata from an audio file on a Pro DJ Link device.
+ *
+ * This function reads only the necessary bytes from the file header,
+ * avoiding the need to transfer entire audio files over the network.
+ *
+ * @param device - The Pro DJ Link device
+ * @param slot - The media slot containing the file (USB, SD, etc.)
+ * @param filePath - The file path on the device
+ * @returns Extracted metadata, or null if extraction fails
+ *
+ * @example
+ * ```typescript
+ * // Extract metadata when a track is loaded
+ * const metadata = await extractMetadataFromDevice(device, slot, filePath);
+ * if (metadata) {
+ *   console.log(metadata.title, metadata.artist, metadata.bpm);
+ *   if (metadata.artwork) {
+ *     // Display artwork
+ *   }
+ * }
+ * ```
+ */
+export declare function extractMetadataFromDevice(device: Device, slot: NfsMediaSlot, filePath: string): Promise<ExtractedMetadata | null>;