alphatheta-connect 0.15.0

package/lib/constants.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The default virtual CDJ ID to use.
+ *
+ * This particular ID is out of the 1-6 range, thus will not be able to request
+ * metadata via the remotedb for CDJs.
+ */
+export declare const DEFAULT_VCDJ_ID = 7;
+/**
+ * The port on which devices on the prolink network announce themselves.
+ */
+export declare const ANNOUNCE_PORT = 50000;
+/**
+ * The port on which devices on the prolink network send beat timing information.
+ */
+export declare const BEAT_PORT = 50001;
+/**
+ * The port on which devices on the prolink network announce themselves.
+ */
+export declare const STATUS_PORT = 50002;
+/**
+ * The amount of time in ms between sending each announcement packet.
+ */
+export declare const ANNOUNCE_INTERVAL = 1500;
+/**
+ * The interval in ms between startup stage packets (0x0a, 0x00, 0x02, 0x04).
+ */
+export declare const STARTUP_STAGE_INTERVAL = 300;
+/**
+ * All UDP packets on the PRO DJ LINK network start with this magic header.
+ */
+export declare const PROLINK_HEADER: Uint8Array<ArrayBuffer>;
+/**
+ * VirtualCDJName is the name given to the Virtual CDJ device.
+ */
+export declare const VIRTUAL_CDJ_NAME = "ProLink-Connect";
+/**
+ * VirtualCDJFirmware is a string indicating the firmware version reported with
+ * status packets.
+ */
+export declare const VIRTUAL_CDJ_FIRMWARE = "1.43";

package/lib/control/index.d.ts

@@ -0,0 +1,20 @@
+import { Socket } from 'dgram';
+import { CDJStatus, Device } from "../types";
+interface Options {
+    hostDevice: Device;
+    device: Device;
+    playState: CDJStatus.PlayState.Cued | CDJStatus.PlayState.Playing;
+}
+/**
+ * Generates the packet used to control the playstate of CDJs
+ */
+export declare const makePlaystatePacket: ({ hostDevice, device, playState }: Options) => Uint8Array<ArrayBuffer>;
+export default class Control {
+    #private;
+    constructor(beatSocket: Socket, hostDevice: Device);
+    /**
+     * Start or stop a CDJ on the network
+     */
+    setPlayState(device: Device, playState: Options['playState']): Promise<void>;
+}
+export {};

package/lib/db/getArtworkFromFile.d.ts

@@ -0,0 +1,13 @@
+import { Track } from "../entities";
+import { Device, DeviceID, MediaSlot } from "../types";
+import { TelemetrySpan as Span } from "../utils/telemetry";
+export interface Options {
+    deviceId: DeviceID;
+    trackSlot: MediaSlot;
+    track: Track;
+    span?: Span;
+}
+/**
+ * Extract artwork directly from an audio file via NFS.
+ */
+export declare function viaFileExtraction(device: Device, opts: Options): Promise<Buffer | null>;

package/lib/db/getArtworkThumbnail.d.ts

@@ -0,0 +1,29 @@
+import { Track } from "../entities";
+import LocalDatabase from "../localdb";
+import RemoteDatabase from "../remotedb";
+import { Device, DeviceID, MediaSlot, TrackType } from "../types";
+import { TelemetrySpan as Span } from "../utils/telemetry";
+export interface Options {
+    /**
+     * The device to query the track artwork off of
+     */
+    deviceId: DeviceID;
+    /**
+     * The media slot the track is present in
+     */
+    trackSlot: MediaSlot;
+    /**
+     * The type of track we are querying artwork for
+     */
+    trackType: TrackType;
+    /**
+     * The track to lookup artwork for
+     */
+    track: Track;
+    /**
+     * The Sentry transaction span
+     */
+    span?: Span;
+}
+export declare function viaRemote(remote: RemoteDatabase, opts: Required<Options>): Promise<Buffer<ArrayBufferLike> | null>;
+export declare function viaLocal(local: LocalDatabase, device: Device, opts: Required<Options>): Promise<Buffer<ArrayBuffer> | null>;

package/lib/db/getFile.d.ts

@@ -0,0 +1,29 @@
+import { Track } from "../entities";
+import LocalDatabase from "../localdb";
+import RemoteDatabase from "../remotedb";
+import { Device, DeviceID, MediaSlot, TrackType } from "../types";
+import { TelemetrySpan as Span } from "../utils/telemetry";
+export interface Options {
+    /**
+     * The device to query the file off of
+     */
+    deviceId: DeviceID;
+    /**
+     * The media slot the track is present in
+     */
+    trackSlot: MediaSlot;
+    /**
+     * The type of track we are querying file for
+     */
+    trackType: TrackType;
+    /**
+     * The track to get track for
+     */
+    track: Track;
+    /**
+     * The Sentry transaction span
+     */
+    span?: Span;
+}
+export declare function viaRemote(_remote: RemoteDatabase, _device: Device, _opts: Required<Options>): null;
+export declare function viaLocal(local: LocalDatabase, device: Device, opts: Required<Options>): Promise<Buffer<ArrayBuffer> | null>;

package/lib/db/getMetadata.d.ts

@@ -0,0 +1,28 @@
+import LocalDatabase from "../localdb";
+import RemoteDatabase from "../remotedb";
+import { Device, DeviceID, MediaSlot, TrackType } from "../types";
+import { TelemetrySpan as Span } from "../utils/telemetry";
+export interface Options {
+    /**
+     * The device to query the track metadata from
+     */
+    deviceId: DeviceID;
+    /**
+     * The media slot the track is present in
+     */
+    trackSlot: MediaSlot;
+    /**
+     * The type of track we are querying for
+     */
+    trackType: TrackType;
+    /**
+     * The track id to retrieve metadata for
+     */
+    trackId: number;
+    /**
+     * The Sentry transaction span
+     */
+    span?: Span;
+}
+export declare function viaRemote(remote: RemoteDatabase, opts: Required<Options>): Promise<import("../types").Track<import("..").EntityFK.WithRelations> | null>;
+export declare function viaLocal(local: LocalDatabase, device: Device, opts: Required<Options>): Promise<import("../types").Track | null>;

package/lib/db/getPlaylist.d.ts

@@ -0,0 +1,26 @@
+import { Playlist } from "../entities";
+import LocalDatabase from "../localdb";
+import RemoteDatabase from "../remotedb";
+import { DeviceID, MediaSlot, PlaylistContents } from "../types";
+import { TelemetrySpan as Span } from "../utils/telemetry";
+export interface Options {
+    /**
+     * The playlist or folder to query the entries of. This may be left as
+     * undefined to retrieve the root playlist.
+     */
+    playlist?: Playlist;
+    /**
+     * The device to query the track metadata from
+     */
+    deviceId: DeviceID;
+    /**
+     * The media slot the track is present in
+     */
+    mediaSlot: MediaSlot;
+    /**
+     * The Sentry transaction span
+     */
+    span?: Span;
+}
+export declare function viaRemote(remote: RemoteDatabase, opts: Options): Promise<PlaylistContents | null>;
+export declare function viaLocal(local: LocalDatabase, opts: Options): Promise<PlaylistContents | null>;

package/lib/db/getWaveforms.d.ts

@@ -0,0 +1,29 @@
+import { Track } from "../entities";
+import LocalDatabase from "../localdb";
+import RemoteDatabase from "../remotedb";
+import { Device, DeviceID, MediaSlot, TrackType, Waveforms } from "../types";
+import { TelemetrySpan as Span } from "../utils/telemetry";
+export interface Options {
+    /**
+     * The device to query the track waveforms off of
+     */
+    deviceId: DeviceID;
+    /**
+     * The media slot the track is present in
+     */
+    trackSlot: MediaSlot;
+    /**
+     * The type of track we are querying waveforms for
+     */
+    trackType: TrackType;
+    /**
+     * The track to lookup waveforms for
+     */
+    track: Track;
+    /**
+     * The Sentry transaction span
+     */
+    span?: Span;
+}
+export declare function viaRemote(remote: RemoteDatabase, opts: Required<Options>): Promise<Waveforms | null>;
+export declare function viaLocal(local: LocalDatabase, device: Device, opts: Required<Options>): Promise<Waveforms | null>;

package/lib/db/index.d.ts

@@ -0,0 +1,70 @@
+import DeviceManager from "../devices";
+import { Track } from "../entities";
+import LocalDatabase from "../localdb";
+import { DatabaseType } from "../localdb/database-adapter";
+import RemoteDatabase from "../remotedb";
+import { Device, MediaSlot, PlaylistContents, Waveforms } from "../types";
+import * as GetArtworkFromFile from './getArtworkFromFile';
+import * as GetArtworkThumbnail from './getArtworkThumbnail';
+import * as GetMetadata from './getMetadata';
+import * as GetPlaylist from './getPlaylist';
+/**
+ * A Database is the central service used to query devices on the prolink
+ * network for information from their databases.
+ */
+declare class Database {
+    #private;
+    constructor(hostDevice: Device, local: LocalDatabase, remote: RemoteDatabase, deviceManager: DeviceManager);
+    /**
+     * Reports weather or not the CDJs can be communicated to over the remote
+     * database protocol. This is important when trying to query for unanalyzed or
+     * compact disc tracks.
+     */
+    get cdjSupportsRemotedb(): boolean;
+    /**
+     * Get the database type (oneLibrary or pdb) for a loaded device slot.
+     * Returns null if the slot uses remote database or no database is loaded.
+     */
+    getDatabaseType(deviceId: number, slot: MediaSlot.USB | MediaSlot.SD): DatabaseType | null;
+    /**
+     * Retrieve metadata for a track on a specific device slot.
+     */
+    getMetadata(opts: GetMetadata.Options): Promise<Track | null>;
+    /**
+     * Retrieves the file off a specific device slot.
+     */
+    getFile(opts: GetArtworkThumbnail.Options): Promise<Buffer<ArrayBufferLike> | null>;
+    /**
+     * Retrieves the low-resolution artwork thumbnail from the rekordbox database.
+     *
+     * This returns the pre-generated thumbnail stored in the rekordbox database,
+     * which is typically small (around 80x80 pixels).
+     *
+     * For full-resolution artwork extracted from the audio file, use getArtwork().
+     */
+    getArtworkThumbnail(opts: GetArtworkThumbnail.Options): Promise<Buffer<ArrayBufferLike> | null>;
+    /**
+     * Retrieves artwork for a track by extracting it from the audio file via NFS.
+     *
+     * This is the primary method for getting artwork. It reads embedded artwork
+     * from the audio file (ID3 tags for MP3, metadata atoms for M4A, PICTURE
+     * blocks for FLAC, etc.) using partial file reads to minimize data transfer.
+     *
+     * For low-resolution thumbnails from the rekordbox database, use
+     * getArtworkThumbnail() instead.
+     */
+    getArtwork(opts: GetArtworkFromFile.Options): Promise<Buffer<ArrayBufferLike> | null>;
+    /**
+     * Retrieves the waveforms for a track on a specific device slot.
+     */
+    getWaveforms(opts: GetArtworkThumbnail.Options): Promise<Waveforms | null>;
+    /**
+     * Retrieve folders, playlists, and tracks within the playlist tree. The id
+     * may be left undefined to query the root of the playlist tree.
+     *
+     * NOTE: You will never receive a track list and playlists or folders at the
+     * same time. But the API is simpler to combine the lookup for these.
+     */
+    getPlaylist(opts: GetPlaylist.Options): Promise<PlaylistContents | null>;
+}
+export default Database;

package/lib/db/utils.d.ts

@@ -0,0 +1,7 @@
+import { Device, MediaSlot } from "../types";
+interface AnlzLoaderOpts {
+    device: Device;
+    slot: MediaSlot.RB | MediaSlot.USB | MediaSlot.SD;
+}
+export declare function anlzLoader(opts: AnlzLoaderOpts): (path: string) => Promise<Buffer<ArrayBuffer>>;
+export {};

package/lib/devices/index.d.ts

@@ -0,0 +1,66 @@
+import StrictEventEmitter from 'strict-event-emitter-types';
+import { Socket } from 'dgram';
+import { EventEmitter } from 'events';
+import { Device, DeviceID } from "../types";
+interface Config {
+    /**
+     * Time in milliseconds after which a device is considered to have
+     * disconnected if it has not broadcast an announcement.
+     *
+     * @default 10000 ms
+     */
+    deviceTimeout?: number;
+    /**
+     * The name of the virtual CDJ to filter out from device announcements.
+     * This prevents our own device from appearing in the device list.
+     *
+     * @default VIRTUAL_CDJ_NAME constant
+     */
+    vcdjName?: string;
+}
+/**
+ * The configuration object that may be passed to reconfigure the manager
+ */
+type ConfigEditable = Omit<Config, 'announceSocket'>;
+/**
+ * The interface the device manager event emitter should follow
+ */
+interface DeviceEvents {
+    /**
+     * Fired when a new device becomes available on the network
+     */
+    connected: (device: Device) => void;
+    /**
+     * Fired when a device has not announced itself on the network for the
+     * specified timeout.
+     */
+    disconnected: (device: Device) => void;
+    /**
+     * Fired every time the device announces itself on the network
+     */
+    announced: (device: Device) => void;
+}
+type Emitter = StrictEventEmitter<EventEmitter, DeviceEvents>;
+/**
+ * The device manager is responsible for tracking devices that appear on the
+ * prolink network, providing an API to react to devices livecycle events as
+ * they connect and disconnect form the network.
+ */
+declare class DeviceManager {
+    #private;
+    constructor(announceSocket: Socket, config?: Config);
+    on: Emitter['on'];
+    off: Emitter['off'];
+    once: Emitter['once'];
+    /**
+     * Get active devices on the network.
+     */
+    get devices(): Map<number, Device>;
+    /**
+     * Waits for a specific device ID to appear on the network, with a
+     * configurable timeout, in which case it will resolve with null.
+     */
+    getDeviceEnsured(id: DeviceID, timeout?: number): Promise<Device | null>;
+    reconfigure(config: ConfigEditable): void;
+}
+export default DeviceManager;

package/lib/devices/utils.d.ts

@@ -0,0 +1,5 @@
+import { Device } from "../types";
+/**
+ * Converts a announce packet to a device object.
+ */
+export declare function deviceFromPacket(packet: Buffer): Device | null;

package/lib/entities.d.ts

@@ -0,0 +1,122 @@
+import { BeatGrid, CueAndLoop, WaveformHD } from "./types";
+/**
+ * Documentation type strictly for use with entities that have foreign key
+ * attributes.
+ */
+export declare enum EntityFK {
+    WithFKs = 0,
+    WithRelations = 1
+}
+export interface Artwork {
+    id: number;
+    path?: string;
+}
+export interface Key {
+    id: number;
+    name: string;
+}
+export interface Label {
+    id: number;
+    name: string;
+}
+export interface Color {
+    id: number;
+    name: string;
+}
+export interface Genre {
+    id: number;
+    name: string;
+}
+export interface Album {
+    id: number;
+    name: string;
+}
+export interface Artist {
+    id: number;
+    name: string;
+}
+export interface Playlist {
+    id: number;
+    name: string;
+    isFolder: boolean;
+    parentId: number | null;
+}
+interface PlaylistEntryRelations {
+    track: Track;
+}
+interface PlaylistEntryFks {
+    playlistId: number;
+    trackId: number;
+}
+export type PlaylistEntry<withFKs extends EntityFK = EntityFK.WithRelations> = {
+    id: number;
+    sortIndex: number;
+} & (withFKs extends EntityFK.WithFKs ? PlaylistEntryFks : PlaylistEntryRelations);
+interface TrackRelations {
+    artwork: Artwork | null;
+    artist: Artist | null;
+    originalArtist: Artist | null;
+    remixer: Artist | null;
+    composer: Artist | null;
+    album: Album | null;
+    label: Label | null;
+    genre: Genre | null;
+    color: Color | null;
+    key: Key | null;
+}
+interface TrackFks {
+    artworkId?: number;
+    artistId?: number;
+    originalArtistId?: number;
+    remixerId?: number;
+    composerId?: number;
+    albumId?: number;
+    labelId?: number;
+    genreId?: number;
+    colorId?: number;
+    keyId?: number;
+}
+/**
+ * Represents a track.
+ *
+ * Note, fields that are not optional will be set for all database request
+ * methods.
+ */
+export type Track<withFKs extends EntityFK = EntityFK.WithRelations> = {
+    id: number;
+    title: string;
+    duration: number;
+    bitrate?: number;
+    tempo: number;
+    rating: number;
+    comment: string;
+    filePath: string;
+    fileName: string;
+    trackNumber?: number;
+    discNumber?: number;
+    sampleRate?: number;
+    sampleDepth?: number;
+    playCount?: number;
+    year?: number;
+    mixName?: string;
+    autoloadHotcues?: boolean;
+    kuvoPublic?: boolean;
+    fileSize?: number;
+    analyzePath?: string;
+    releaseDate?: string;
+    analyzeDate?: Date;
+    dateAdded?: Date;
+    /**
+     * Embedded beat grid information
+     */
+    beatGrid: BeatGrid | null;
+    /**
+     * Embedded cue and loop information
+     */
+    cueAndLoops: CueAndLoop[] | null;
+    /**
+     * Embedded HD Waveform information
+     */
+    waveformHd: WaveformHD | null;
+} & (withFKs extends EntityFK.WithFKs ? TrackFks : TrackRelations);
+export {};

package/lib/index.d.ts

@@ -0,0 +1,10 @@
+export * from './entities';
+export * from './mixstatus';
+export * from './network';
+export { default as PositionEmitter } from './status/position';
+export * from './passive';
+export { extractArtwork, extractArtworkFromDevice, isArtworkExtractionSupported, PictureType, } from './artwork';
+export type { ExtractedArtwork, FileReader as ArtworkFileReader } from './artwork';
+export type { DatabaseAdapter, DatabasePreference, DatabaseType, PlaylistQueryResult, } from './localdb/database-adapter';
+export { OneLibraryAdapter } from './localdb/onelibrary';
+export * from './types';