alphatheta-connect 0.15.0

package/lib/localdb/rekordbox.d.ts

@@ -0,0 +1,112 @@
+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.
+ */
+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 {};

package/lib/localdb/schema.d.ts

@@ -0,0 +1 @@
+export declare const generateSchema: () => string;

package/lib/localdb/utils.d.ts

@@ -0,0 +1,5 @@
+import { CueAndLoop, HotcueButton } from "../types";
+/**
+ * Create a CueAndLoop entry given common parameters
+ */
+export declare const makeCueLoopEntry: (isCue: boolean, isLoop: boolean, offset: number, length: number, button: false | HotcueButton) => null | CueAndLoop;

package/lib/mixstatus/index.d.ts

@@ -0,0 +1,109 @@
+import StrictEventEmitter from 'strict-event-emitter-types';
+import { EventEmitter } from 'events';
+import { CDJStatus, DeviceID, MixstatusMode } from "../types";
+export interface MixstatusConfig {
+    /**
+     * Selects the mixstatus reporting mode
+     */
+    mode: MixstatusMode;
+    /**
+     * Specifies the duration in seconds that no tracks must be on air. This can
+     * be thought of as how long 'air silence' is reasonable in a set before a
+     * separate one is considered have begun.
+     *
+     * @default 30 (half a minute)
+     */
+    timeBetweenSets: number;
+    /**
+     * Indicates if the status objects reported should have their on-air flag
+     * read. Setting this to false will degrade the functionality of the processor
+     * such that it will not consider the value of isOnAir and always assume CDJs
+     * are live.
+     *
+     * @default true
+     */
+    useOnAirStatus: boolean;
+    /**
+     * Configures how many beats a track may not be live or playing for it to
+     * still be considered active.
+     *
+     * @default 8 (two bars)
+     */
+    allowedInterruptBeats: number;
+    /**
+     * Configures how many beats the track must consecutively be playing for
+     * (since the beat it was cued at) until the track is considered to be
+     * active.
+     *
+     * Used for MixstatusMode.SmartTiming
+     *
+     * @default 128 (2 phrases)
+     */
+    beatsUntilReported: number;
+}
+/**
+ * The interface the mix status event emitter should follow
+ */
+interface MixstatusEvents {
+    /**
+     * Fired when a track is considered to be on-air and is being heard by the
+     * audience
+     */
+    nowPlaying: (state: CDJStatus.State) => void;
+    /**
+     * Fired when a track has stopped and is completely offair
+     */
+    stopped: (opt: {
+        deviceId: DeviceID;
+    }) => void;
+    /**
+     * Fired when a DJ set first starts
+     */
+    setStarted: () => void;
+    /**
+     * Fired when tracks have been stopped
+     */
+    setEnded: () => void;
+}
+type Emitter = StrictEventEmitter<EventEmitter, MixstatusEvents>;
+/**
+ * MixstatusProcessor is a configurable processor which when fed device state
+ * will attempt to accurately determine events that happen within the DJ set.
+ *
+ * The following events are fired:
+ *
+ * - nowPlaying: The track is considered playing and on air to the audience.
+ * - stopped:    The track was stopped / paused / went off-air.
+ *
+ * Additionally the following non-track status are reported:
+ *
+ * - setStarted: The first track has begun playing.
+ * - setEnded:   The TimeBetweenSets has passed since any tracks were live.
+ *
+ * See Config for configuration options.
+ *
+ * Config options may be changed after the processor has been created and is
+ * actively receiving state updates.
+ */
+export declare class MixstatusProcessor {
+    #private;
+    constructor(config?: Partial<MixstatusConfig>);
+    /**
+     * Update the configuration
+     */
+    configure(config?: Partial<MixstatusConfig>): void;
+    on: Emitter['on'];
+    off: Emitter['off'];
+    once: Emitter['once'];
+    removeAllListeners: (event?: keyof MixstatusEvents) => EventEmitter<[never]>;
+    /**
+     * Feed a CDJStatus state object to the mix state processor
+     */
+    handleState(state: CDJStatus.State): void;
+    /**
+     * Manually reports the track that has been playing the longest which has not
+     * yet been reported as live.
+     */
+    triggerNextTrack(): void;
+}
+export {};

package/lib/mixstatus/utils.d.ts

@@ -0,0 +1,9 @@
+import { CDJStatus } from "../types";
+/**
+ * Returns true if the the status reports a playing state.
+ */
+export declare const isPlaying: (s: CDJStatus.State) => boolean;
+/**
+ * Returns true if the status reports a stopping state.
+ */
+export declare const isStopping: (s: CDJStatus.State) => boolean;

package/lib/network.d.ts

@@ -0,0 +1,201 @@
+import { Socket } from 'dgram';
+import { NetworkInterfaceInfoIPv4 } from 'os';
+import Control from "./control";
+import Database from "./db";
+import DeviceManager from "./devices";
+import LocalDatabase from "./localdb";
+import { DatabasePreference } from "./localdb/database-adapter";
+import { MixstatusProcessor } from "./mixstatus";
+import RemoteDatabase from "./remotedb";
+import StatusEmitter from "./status";
+import PositionEmitter from "./status/position";
+import { NetworkState } from "./types";
+export interface NetworkConfig {
+    /**
+     * The network interface to listen for devices on the network over
+     */
+    iface: NetworkInterfaceInfoIPv4;
+    /**
+     * The ID of the virtual CDJ to pose as.
+     *
+     * IMPORTANT:
+     *
+     * You will likely want to configure this to be > 6, however it is important to
+     * note, if you choose an ID within the 1-6 range, no other CDJ may exist on the
+     * network using that ID. you CAN NOT have 6 CDJs if you're using one of their slots.
+     *
+     * However, should you want to make metadata queries to a unanalized media
+     * device connected to the CDJ, or metadata queries for CD disc data, you MUST
+     * use a ID within the 1-6 range, as the CDJs will not respond to metadata
+     * requests outside of the range of 1-6
+     *
+     * Note that rekordbox analyzed media connected to the CDJ is accessed out of
+     * band of the networks remote database protocol, and is not limited by this
+     * restriction.
+     */
+    vcdjId: number;
+    /**
+     * The name to announce the virtual CDJ as on the network.
+     *
+     * This name will appear in device lists on other Pro DJ Link equipment.
+     *
+     * @default 'ProLink-Connect'
+     */
+    vcdjName?: string;
+    /**
+     * Enable full startup protocol for robust device negotiation.
+     * When enabled, the virtual CDJ will go through the complete startup
+     * sequence (stages 0x0a → 0x00 → 0x02 → 0x04 → 0x06) before regular
+     * keep-alive announcements.
+     *
+     * This is recommended for production setups with CDJ-3000 and DJM-V10
+     * hardware to ensure proper device discovery and network stability.
+     */
+    fullStartup?: boolean;
+    /**
+     * 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)
+     *
+     * @default 'auto'
+     */
+    databasePreference?: DatabasePreference;
+}
+interface ConstructOpts {
+    config?: NetworkConfig;
+    announceSocket: Socket;
+    beatSocket: Socket;
+    statusSocket: Socket;
+    deviceManager: DeviceManager;
+    statusEmitter: StatusEmitter;
+    positionEmitter: PositionEmitter;
+}
+/**
+ * Services that are not accessible until connected
+ */
+type ConnectedServices = 'statusEmitter' | 'positionEmitter' | 'control' | 'db' | 'localdb' | 'remotedb' | 'mixstatus';
+export type ConnectedProlinkNetwork = ProlinkNetwork & {
+    [P in ConnectedServices]: NonNullable<ProlinkNetwork[P]>;
+} & {
+    state: NetworkState.Connected;
+    isConfigured: true;
+};
+/**
+ * Brings the Prolink network online.
+ *
+ * This is the primary entrypoint for connecting to the prolink network.
+ */
+export declare function bringOnline(config?: NetworkConfig): Promise<ProlinkNetwork>;
+export declare class ProlinkNetwork {
+    #private;
+    /**
+     * @internal
+     */
+    constructor({ config, announceSocket, beatSocket, statusSocket, deviceManager, statusEmitter, positionEmitter, }: ConstructOpts);
+    /**
+     * Configure / reconfigure the network with an explicit configuration.
+     *
+     * You may need to disconnect and re-connect the network after making a
+     * networking configuration change.
+     */
+    configure(config: Partial<NetworkConfig>): void;
+    /**
+     * Wait for another device to show up on the network to determine which network
+     * interface to listen on.
+     *
+     * Defaults the Virtual CDJ ID to 7.
+     */
+    autoconfigFromPeers(): Promise<void>;
+    /**
+     * Connect to the network.
+     *
+     * The network must first have been configured (either with autoconfigFromPeers
+     * or manual configuration). This will then initialize all the network services.
+     */
+    connect(): void;
+    /**
+     * Disconnect from the network
+     */
+    disconnect(): () => Promise<[unknown, unknown, unknown]>;
+    /**
+     * Close UDP sockets.
+     */
+    close(): Promise<[unknown, unknown, unknown]>;
+    /**
+     * Get the current NetworkState of the network.
+     *
+     * When the network is Online you may use the deviceManager to list and react to
+     * devices on the nettwork
+     *
+     * Once the network is Connected you may use the statusEmitter to listen for
+     * player status events, query the media databases of devices using the db
+     * service (or specifically query the localdb or remotedb).
+     */
+    get state(): NetworkState;
+    /**
+     * Check if the network has been configured. You cannot connect to the network
+     * until it has been configured.
+     */
+    get isConfigured(): boolean;
+    /**
+     * Typescript discriminate helper. Refines the type of the network to one
+     * that reflects the connected status. Useful to avoid having to gaurd the
+     * service getters from nulls.
+     */
+    isConnected(): this is ConnectedProlinkNetwork;
+    /**
+     * Get the {@link DeviceManager} service. This service is used to monitor and
+     * react to devices connecting and disconnecting from the prolink network.
+     */
+    get deviceManager(): DeviceManager;
+    /**
+     * Get the {@link StatusEmitter} service. This service is used to monitor
+     * status updates on each CDJ.
+     */
+    get statusEmitter(): StatusEmitter | null;
+    /**
+     * Get the {@link PositionEmitter} service. This service provides events with
+     * absolute playhead position updates from CDJ-3000+ devices.
+     *
+     * Position packets are sent approximately every 30ms while a track is loaded,
+     * providing precise position tracking independent of beat grids. This enables
+     * accurate timecode/video sync even during scratching, reverse play, and loops.
+     */
+    get positionEmitter(): PositionEmitter | null;
+    /**
+     * Get the {@link Control} service. This service can be used to control the
+     * Playstate of CDJs on the network.
+     */
+    get control(): Control | null;
+    /**
+     * Get the {@link Database} service. This service is used to retrieve
+     * metadata and listings from devices on the network, automatically choosing the
+     * best strategy to access the data.
+     */
+    get db(): Database | null;
+    /**
+     * Get the {@link LocalDatabase} service. This service is used to query and sync
+     * metadata that is downloaded directly from the rekordbox database present
+     * on media connected to the CDJs.
+     */
+    get localdb(): LocalDatabase | null;
+    /**
+     * Get the {@link RemoteDatabase} service. This service is used to query
+     * metadata directly from the database service running on Rekordbox and the CDJs
+     * themselves.
+     *
+     * NOTE: To use this service to access the CDJ remote database service, the
+     *       Virtual CDJ must report itself as an ID between 1 and 6. This means
+     *       there cannot be four physical CDJs on the network to access any CDJs
+     *       remote database.
+     */
+    get remotedb(): RemoteDatabase | null;
+    /**
+     * Get (and initialize) the {@link MixstatusProcessor} service. This service can
+     * be used to monitor the 'status' of devices on the network as a whole.
+     */
+    get mixstatus(): MixstatusProcessor | null;
+}
+export {};

package/lib/nfs/index.d.ts

@@ -0,0 +1,63 @@
+import { Device } from "../types";
+import { TelemetrySpan as Span } from "../utils/telemetry";
+import { fetchFile as fetchFileCall, FileInfo } from './programs';
+export type { FileInfo } from './programs';
+import { RetryConfig } from './rpc';
+export interface FetchProgress {
+    read: number;
+    total: number;
+}
+/**
+ * The slot <-> mount name mapping is well known.
+ */
+declare const slotMountMapping: {
+    readonly 3: "/C/";
+    readonly 2: "/B/";
+    readonly 4: "/";
+};
+/**
+ * Media slots that support NFS access.
+ */
+export type NfsMediaSlot = keyof typeof slotMountMapping;
+interface FetchFileOptions {
+    device: Device;
+    slot: keyof typeof slotMountMapping;
+    path: string;
+    onProgress?: Parameters<typeof fetchFileCall>[2];
+    span?: Span;
+    chunkSize?: number;
+}
+interface FetchFileRangeOptions {
+    device: Device;
+    slot: keyof typeof slotMountMapping;
+    path: string;
+    offset: number;
+    length: number;
+    span?: Span;
+}
+/**
+ * Fetch a range of bytes from a file on a device's NFS server.
+ * Optimized for partial reads (e.g., reading file headers for metadata extraction).
+ */
+export declare function fetchFileRange({ device, slot, path, offset, length, span, }: FetchFileRangeOptions): Promise<Buffer>;
+/**
+ * Get file info (size, handle) without fetching the file content.
+ */
+export declare function getFileInfo({ device, slot, path, span, }: Omit<FetchFileOptions, 'onProgress' | 'chunkSize'>): Promise<FileInfo>;
+/**
+ * Fetch a file from a devices NFS server.
+ *
+ * NOTE: The connection and root filehandle (The 'mounted' NFS export on the
+ *       device) is cached to improve subsequent fetching performance. It's
+ *       important that when the device disconnects you call the {@link
+ *       resetDeviceCache} function.
+ */
+export declare function fetchFile({ device, slot, path, onProgress, span, chunkSize, }: FetchFileOptions): Promise<Buffer<ArrayBuffer>>;
+/**
+ * Clear the cached NFS connection and root filehandle for the given device
+ */
+export declare function resetDeviceCache(device: Device): void;
+/**
+ * Configure the retry strategy for making NFS calls using this module
+ */
+export declare function configureRetryStrategy(config: RetryConfig): void;

package/lib/nfs/programs.d.ts

@@ -0,0 +1,61 @@
+import { TelemetrySpan as Span } from "../utils/telemetry";
+import { RpcConnection, RpcProgram } from './rpc';
+import { FetchProgress } from '.';
+interface Program {
+    id: number;
+    version: number;
+}
+/**
+ * Queries for the listening port of a RPC program
+ */
+export declare function makeProgramClient(conn: RpcConnection, program: Program): Promise<RpcProgram>;
+/**
+ * Export represents a NFS export on a remote system
+ */
+interface Export {
+    /**
+     * The name of the exported filesystem
+     */
+    filesystem: string;
+    /**
+     * The groups allowed to mount this filesystem
+     */
+    groups: string[];
+}
+/**
+ * Attributes a remote file
+ */
+export interface FileInfo {
+    handle: Buffer;
+    name: string;
+    size: number;
+    type: 'null' | 'regular' | 'directory' | 'block' | 'char' | 'link';
+}
+/**
+ * Request a list of export entries.
+ */
+export declare function getExports(conn: RpcProgram, span?: Span): Promise<Export[]>;
+/**
+ * Mount the specified export, returning the file handle.
+ */
+export declare function mountFilesystem(conn: RpcProgram, { filesystem }: Export, span?: Span): Promise<Buffer<ArrayBufferLike>>;
+/**
+ * Lookup a file within the directory of the provided file handle, returning
+ * the FileInfo object if the file can be located.
+ */
+export declare function lookupFile(conn: RpcProgram, handle: Buffer, filename: string, span?: Span): Promise<FileInfo>;
+/**
+ * Lookup the absolute path to a file, given the root file handle and path,
+ */
+export declare function lookupPath(conn: RpcProgram, rootHandle: Buffer, filepath: string, span?: Span): Promise<FileInfo>;
+/**
+ * Fetch the specified file the remote NFS server. This will read the entire
+ * file into memory.
+ */
+export declare function fetchFile(conn: RpcProgram, file: FileInfo, onProgress?: (progress: FetchProgress) => void, span?: Span, readSize?: number): Promise<Buffer<ArrayBuffer>>;
+/**
+ * Fetch a range of bytes from a file on the remote NFS server.
+ * Unlike fetchFile, this only reads the specified range.
+ */
+export declare function fetchFileRange(conn: RpcProgram, file: FileInfo, offset: number, length: number, span?: Span): Promise<Buffer>;
+export {};

package/lib/nfs/rpc.d.ts

@@ -0,0 +1,60 @@
+import { Mutex } from 'async-mutex';
+import { OperationOptions } from 'retry';
+import { Socket } from 'dgram';
+interface RpcCall {
+    port: number;
+    program: number;
+    version: number;
+    procedure: number;
+    data: Buffer;
+}
+/**
+ * Configuration for the retry strategy to use when making RPC calls
+ *
+ * @see https://www.npmjs.com/package/promise-retry#promiseretryfn-options
+ */
+export type RetryConfig = OperationOptions & {
+    /**
+     * Time in milliseconds to wait before a RPC transaction should timeout.
+     * @default 1000
+     */
+    transactionTimeout?: number;
+};
+/**
+ * Generic RPC connection. Can be used to make RPC 2 calls to any program
+ * specified in the RpcCall.
+ */
+export declare class RpcConnection {
+    address: string;
+    retryConfig: RetryConfig;
+    socket: Socket;
+    mutex: Mutex;
+    xid: number;
+    constructor(address: string, retryConfig?: RetryConfig);
+    connected: boolean;
+    setupRequest({ program, version, procedure, data }: Omit<RpcCall, 'port'>): any;
+    /**
+     * Execute a RPC transaction (call and response).
+     *
+     * If a transaction does not complete after the configured timeout it will be
+     * retried with the retry configuration.
+     */
+    call({ port, ...call }: RpcCall): Promise<Buffer<ArrayBufferLike>>;
+    disconnect(): Promise<void>;
+}
+type RpcProgramCall = Pick<RpcCall, 'procedure' | 'data'>;
+/**
+ * RpcProgram is constructed with specialization details for a specific RPC
+ * program. This should be used to avoid having to repeat yourself for calls
+ * made using the RpcConnection.
+ */
+export declare class RpcProgram {
+    program: number;
+    version: number;
+    port: number;
+    conn: RpcConnection;
+    constructor(conn: RpcConnection, program: number, version: number, port: number);
+    call(data: RpcProgramCall): Promise<Buffer<ArrayBufferLike>>;
+    disconnect(): void;
+}
+export {};

package/lib/nfs/utils.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Helper to flatten linked list structures into an array
+ */
+export declare const flattenLinkedList: (item: any) => any;

package/lib/nfs/xdr.d.ts

@@ -0,0 +1,17 @@
+/**
+ * RPC XDR data types. This implements nearly the entire XDR spec for the
+ * ONC-RPC protocol.
+ */
+export declare const rpc: any;
+/**
+ * Portmap RPC XDR types
+ */
+export declare const portmap: any;
+/**
+ * Mount RPC XDR types
+ */
+export declare const mount: any;
+/**
+ * NFS RPC XDR types
+ */
+export declare const nfs: any;