alphatheta-connect 0.26.0 → 0.27.0

package/lib/cli.js

@@ -811,14 +811,17 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _Control_hostDevice, _Control_beatSocket, _Control_correlationByte;
+var _Control_hostDevice, _Control_beatSocket, _Control_statusSocket, _Control_correlationByte;
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.makePlaystatePacket = void 0;
+exports.makePlaystatePacket = exports.makeLoadTrackPacket = void 0;
 const constants_1 = __webpack_require__(/*! src/constants */ "./src/constants.ts");
 const types_1 = __webpack_require__(/*! src/types */ "./src/types.ts");
 const utils_1 = __webpack_require__(/*! src/utils */ "./src/utils/index.ts");
 const udp_1 = __webpack_require__(/*! src/utils/udp */ "./src/utils/udp.ts");
+const load_1 = __webpack_require__(/*! ./load */ "./src/control/load.ts");
 const stagehand_1 = __webpack_require__(/*! ./stagehand */ "./src/control/stagehand.ts");
+var load_2 = __webpack_require__(/*! ./load */ "./src/control/load.ts");
+Object.defineProperty(exports, "makeLoadTrackPacket", ({ enumerable: true, get: function () { return load_2.makeLoadTrackPacket; } }));
 const STATE_MAP = {
     [types_1.CDJStatus.PlayState.Cued]: 0x01,
     [types_1.CDJStatus.PlayState.Playing]: 0x00,
@@ -839,20 +842,51 @@ const makePlaystatePacket = ({ hostDevice, device, playState }) => Uint8Array.fr
 ]);
 exports.makePlaystatePacket = makePlaystatePacket;
 class Control {
-    constructor(beatSocket, hostDevice) {
+    constructor(beatSocket, hostDevice, statusSocket = null) {
         _Control_hostDevice.set(this, void 0);
         /**
          * The socket used to send control packets
          */
         _Control_beatSocket.set(this, void 0);
+        /**
+         * The socket bound to the status port, which the Load Track command must
+         * leave from: a CDJ-3000 ignores it from any other port. Absent when the
+         * control service was built without one.
+         */
+        _Control_statusSocket.set(this, void 0);
         /**
          * Randomized correlation byte per session for Stagehand commands
          */
         _Control_correlationByte.set(this, void 0);
         __classPrivateFieldSet(this, _Control_beatSocket, beatSocket, "f");
+        __classPrivateFieldSet(this, _Control_statusSocket, statusSocket, "f");
         __classPrivateFieldSet(this, _Control_hostDevice, hostDevice, "f");
         __classPrivateFieldSet(this, _Control_correlationByte, Math.floor(Math.random() * 256), "f");
     }
+    /**
+     * Send one Stagehand transport packet (0x07) carrying `op` with the press /
+     * release flag, for opcodes the named methods do not cover.
+     */
+    async transport(device, op, press) {
+        const p = (0, stagehand_1.makeStagehandTransportPacket)(__classPrivateFieldGet(this, _Control_hostDevice, "f"), op, press, __classPrivateFieldGet(this, _Control_correlationByte, "f"));
+        await (0, udp_1.udpSend)(__classPrivateFieldGet(this, _Control_beatSocket, "f"), p, constants_1.BEAT_PORT, device.ip.address);
+    }
+    /**
+     * Tell a player to load a track, as rekordbox does when a row is dragged
+     * onto a deck: the Load Track command (0x19) from our status port to the
+     * player's. The player answers 0x1a and the load shows in its next status.
+     *
+     * `source` names where the track lives: a device number and its slot (a
+     * player's USB or SD, or the rekordbox slot of a library served over the
+     * link).
+     */
+    async loadTrack(device, trackId, source) {
+        if (__classPrivateFieldGet(this, _Control_statusSocket, "f") === null) {
+            throw new Error('loadTrack needs the status socket; connect through ProlinkNetwork');
+        }
+        const p = (0, load_1.makeLoadTrackPacket)(__classPrivateFieldGet(this, _Control_hostDevice, "f"), device, trackId, source);
+        await (0, udp_1.udpSend)(__classPrivateFieldGet(this, _Control_statusSocket, "f"), p, constants_1.STATUS_PORT, device.ip.address);
+    }
     /**
      * Start or stop a CDJ on the network.
      * Delegates automatically to Stagehand-specific transport control if connected in Stagehand mode.
@@ -918,10 +952,79 @@ class Control {
         await (0, udp_1.udpSend)(__classPrivateFieldGet(this, _Control_beatSocket, "f"), p, constants_1.STATUS_PORT, device.ip.address);
     }
 }
-_Control_hostDevice = new WeakMap(), _Control_beatSocket = new WeakMap(), _Control_correlationByte = new WeakMap();
+_Control_hostDevice = new WeakMap(), _Control_beatSocket = new WeakMap(), _Control_statusSocket = new WeakMap(), _Control_correlationByte = new WeakMap();
 exports["default"] = Control;
 
 
+/***/ },
+
+/***/ "./src/control/load.ts"
+/*!*****************************!*\
+  !*** ./src/control/load.ts ***!
+  \*****************************/
+(__unused_webpack_module, exports, __webpack_require__) {
+
+"use strict";
+
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.LOAD_TRACK_LENGTH = void 0;
+exports.makeLoadTrackPacket = makeLoadTrackPacket;
+const constants_1 = __webpack_require__(/*! src/constants */ "./src/constants.ts");
+const types_1 = __webpack_require__(/*! src/types */ "./src/types.ts");
+const utils_1 = __webpack_require__(/*! src/utils */ "./src/utils/index.ts");
+/**
+ * Byte length of a Load Track command.
+ */
+exports.LOAD_TRACK_LENGTH = 0x58;
+/**
+ * Generates the Load Track command (0x19, 88 bytes), unicast to a player's
+ * status port.
+ *
+ * Byte for byte what rekordbox 7.2 sends a CDJ-3000 (captured 2026-09-13 and
+ * verified live on two CDJ-3000s): the status-style header with a 20-byte
+ * name, `01 01`, our device number, the length `0034` of what follows, our
+ * number again, then the source device, slot and track type, the track ID
+ * big-endian, `32` at 0x33, the destination player counted from zero at
+ * 0x40, and `32` at 0x4b.
+ *
+ * A player only honours the command from the address its keep-alives
+ * announced and from port 50002.
+ */
+function makeLoadTrackPacket(hostDevice, device, trackId, source) {
+    var _a;
+    const packet = new Uint8Array(exports.LOAD_TRACK_LENGTH);
+    // 0-9: magic header
+    packet.set(constants_1.PROLINK_HEADER, 0);
+    // 10: kind 0x19
+    packet[10] = 0x19;
+    // 11-30: device name (20 bytes)
+    packet.set((0, utils_1.buildName)(hostDevice), 11);
+    // 31-35: 01, subtype 01, our number, then the length 0x0034 of what follows
+    packet[31] = 0x01;
+    packet[32] = 0x01;
+    packet[33] = hostDevice.id;
+    packet[34] = 0x00;
+    packet[35] = 0x34;
+    // 36: our number again
+    packet[36] = hostDevice.id;
+    // 40-42: the source device, its slot and the track type
+    packet[40] = source.deviceId;
+    packet[41] = source.slot;
+    packet[42] = (_a = source.trackType) !== null && _a !== void 0 ? _a : types_1.TrackType.RB;
+    // 44-47: the track ID, big-endian
+    packet[44] = (trackId >>> 24) & 0xff;
+    packet[45] = (trackId >>> 16) & 0xff;
+    packet[46] = (trackId >>> 8) & 0xff;
+    packet[47] = trackId & 0xff;
+    packet[0x33] = 0x32;
+    // 0x40: the player to load onto, counted from zero; a player accepts the
+    // command by address regardless
+    packet[0x40] = Math.max(device.id - 1, 0);
+    packet[0x4b] = 0x32;
+    return packet;
+}
+
+
 /***/ },
 
 /***/ "./src/control/stagehand.ts"
@@ -938,59 +1041,75 @@ exports.makeStagehandPrefWritePacket = makeStagehandPrefWritePacket;
 const constants_1 = __webpack_require__(/*! src/constants */ "./src/constants.ts");
 const utils_1 = __webpack_require__(/*! src/utils */ "./src/utils/index.ts");
 /**
- * Generates a Stagehand transport control packet (0x07, 56 bytes)
+ * The name field of a Stagehand unicast frame: 19 bytes, one shorter than the
+ * broadcast frames' 20, so the bytes that follow it sit at offset 30.
+ */
+function buildUnicastName(device) {
+    return (0, utils_1.buildName)(device).subarray(0, 19);
+}
+/**
+ * Generates a Stagehand transport control packet (0x07, 48 bytes).
+ *
+ * Byte for byte what the iPad app sends a CDJ-3000 (captured 2026-05-23,
+ * `stagehand-allproto-20260523T142615.pcap`, pinned in the tests): the
+ * unicast header `03 01 00`, a byte that varies per command, the length
+ * `0030`, then `3a`, `01`, the opcode and the press flag each in their own
+ * 16-bit slot.
  *
  * @param hostDevice - The Stagehand device posing as sender
- * @param op - The command opcode (e.g. 0x0f, 0x14, 0x18, 0x1a, 0x1b)
+ * @param op - The command opcode (e.g. 0x0f, 0x14, 0x18, 0x19, 0x1a, 0x1b)
  * @param press - Whether the action is press (true) or release (false)
- * @param correlationByte - The randomized per-session correlation byte
+ * @param correlationByte - The per-session correlation byte
  */
 function makeStagehandTransportPacket(hostDevice, op, press, correlationByte) {
-    const packet = new Uint8Array(56);
+    const packet = new Uint8Array(48);
     // 0-9: magic header
     packet.set(constants_1.PROLINK_HEADER, 0);
     // 10: opcode 0x07
     packet[10] = 0x07;
-    // 11-30: device name
-    packet.set((0, utils_1.buildName)(hostDevice), 11);
-    // 31: 0x01
+    // 11-29: device name
+    packet.set(buildUnicastName(hostDevice), 11);
+    // 30-32: unicast header 03 01 00
+    packet[30] = 0x03;
     packet[31] = 0x01;
-    // 32: 0x03
-    packet[32] = 0x03;
+    packet[32] = 0x00;
     // 33: per-session correlation byte
     packet[33] = correlationByte;
-    // 34-35: remaining length 0x0030 (48 bytes)
+    // 34-35: packet length 0x0030 (48 bytes)
     packet[34] = 0x00;
     packet[35] = 0x30;
-    // 40: Stagehand sub-id 0x3a
-    packet[40] = 0x3a;
-    // 44: command opcode
-    packet[44] = op;
-    // 46: press/release flag
-    packet[46] = press ? 0x01 : 0x00;
+    // 39: Stagehand sub-id 0x3a
+    packet[39] = 0x3a;
+    // 41: 0x01
+    packet[41] = 0x01;
+    // 43: command opcode
+    packet[43] = op;
+    // 45: press/release flag
+    packet[45] = press ? 0x01 : 0x00;
     return packet;
 }
 /**
- * Generates a Stagehand preference write packet (0x6b, 124 bytes)
+ * Generates a Stagehand preference write packet (0x6b, 116 bytes).
+ *
+ * As captured from the iPad app (same capture as the transport packet): the
+ * unicast header `03 01 00 3a`, the length `0050`, the write flag, then the
+ * preference slots.
  *
  * @param hostDevice - The Stagehand device posing as sender
  * @param options - The preferences to write (onAir, quantize)
  */
 function makeStagehandPrefWritePacket(hostDevice, options) {
-    const packet = new Uint8Array(124);
+    const packet = new Uint8Array(116);
     // 0-9: magic header
     packet.set(constants_1.PROLINK_HEADER, 0);
     // 10: opcode 0x6b
     packet[10] = 0x6b;
-    // 11-30: device name
-    const name = (0, utils_1.buildName)(hostDevice);
-    // Trailing byte 30 (which is offset 30, meaning index 19 of name) is set to 0x03
-    name[19] = 0x03;
-    packet.set(name, 11);
-    // 31: 0x01 (subscription-id-a constant)
+    // 11-29: device name
+    packet.set(buildUnicastName(hostDevice), 11);
+    // 30-32: unicast header 03 01 00
+    packet[30] = 0x03;
     packet[31] = 0x01;
-    // 32: 0x03 (constant)
-    packet[32] = 0x03;
+    packet[32] = 0x00;
     // 33: Stagehand sub-id constant 0x3a
     packet[33] = 0x3a;
     // 34-35: body length 0x0050 (80 bytes)
@@ -1467,7 +1586,9 @@ async function viaLocal(local, opts) {
             if (!orm) {
                 break;
             }
-            yield orm.findTrack(entry.id);
+            // Playlist entries reference the track through trackId; entry.id is the
+            // entry's own row id (or its index, for OneLibrary), not a track.
+            yield orm.findTrack(entry.trackId);
         }
     };
     const tracks = { [Symbol.asyncIterator]: iterateTracks };
@@ -3285,7 +3406,9 @@ var RekordboxAnlz = (function() {
       this.time = this._io.readU4be();
       this.loopTime = this._io.readU4be();
       this.colorId = this._io.readU1();
-      this._unnamed9 = this._io.readBytes(11);
+      this._unnamed9 = this._io.readBytes(7);
+      this.loopNumerator = this._io.readU2be();
+      this.loopDenominator = this._io.readU2be();
       if (this.lenEntry > 43) {
         this.lenComment = this._io.readU4be();
       }
@@ -3305,7 +3428,7 @@ var RekordboxAnlz = (function() {
         this.colorBlue = this._io.readU1();
       }
       if ((this.lenEntry - this.lenComment) > 48) {
-        this._unnamed16 = this._io.readBytes(((this.lenEntry - 48) - this.lenComment));
+        this._unnamed18 = this._io.readBytes(((this.lenEntry - 48) - this.lenComment));
       }
     }
 
@@ -3337,6 +3460,16 @@ var RekordboxAnlz = (function() {
      * and has been assigned a color.
      */
 
+    /**
+     * The numerator of the loop size fraction for a quantized loop,
+     * e.g. 4 for a 4-beat loop. Zero when the loop is not quantized.
+     */
+
+    /**
+     * The denominator of the loop size fraction for a quantized loop,
+     * e.g. 1 for a 4-beat loop.
+     */
+
     /**
      * The comment assigned to this cue by the DJ, if any, with a trailing NUL.
      */
@@ -5767,16 +5900,20 @@ function makeBeatGrid(data) {
  * Fill cue and loop data from the ANLZ section
  */
 function makeCueAndLoop(data) {
-    return data.body.cues.map((entry) => {
+    return data.body.cues
+        .map((entry) => {
         // Cues with the status 0 are likely leftovers that were removed
-        const button = entry.hotCue === 0 ? false : entry.type;
+        // `hotCue` is the button number (1-8, A-H); zero marks a memory cue.
+        // `type` only says whether the entry is a cue point (1) or a loop (2).
+        const button = entry.hotCue === 0 ? false : entry.hotCue;
         const isCue = entry.type === 0x01;
         const isLoop = entry.type === 0x02;
         // NOTE: Unlike the remotedb, these entries are already in milliseconds.
         const offset = entry.time;
         const length = entry.loopTime - offset;
         return (0, utils_1.makeCueLoopEntry)(isCue, isLoop, offset, length, button);
-    });
+    })
+        .filter((c) => c !== null);
 }
 /**
  * Fill waveform HD data from the ANLZ section
@@ -5812,9 +5949,13 @@ function makeExtendedCues(data) {
                 b: (_c = entry.colorBlue) !== null && _c !== void 0 ? _c : 0,
             };
         }
-        // Add comment if present
+        // Add comment if present. The tag stores it with a trailing NUL, which
+        // is not part of what the DJ typed.
         if (entry.lenComment > 0 && entry.comment) {
-            cue.comment = entry.comment;
+            const comment = entry.comment.replace(/\0+$/, '');
+            if (comment.length > 0) {
+                cue.comment = comment;
+            }
         }
         // Add quantized loop information if present
         if (entry.loopNumerator !== undefined && entry.loopNumerator > 0) {
@@ -5880,19 +6021,24 @@ function makeSongStructure(data) {
         },
     };
     const mood = (_a = moodMap[data.body.mood]) !== null && _a !== void 0 ? _a : 'high';
-    const bank = (_b = bankMap[data.body.rawBank]) !== null && _b !== void 0 ? _b : 'default';
+    const bank = (_b = bankMap[data.body.bank]) !== null && _b !== void 0 ? _b : 'default';
+    // Field names follow the Kaitai-generated object (rekordbox_anlz.ksy
+    // `song_structure_entry`): `phraseNumber`, `beatNumber`, `fillIn`,
+    // `fillInBeatNumber`, and `kind` is a `phrase_high` / `phrase_mid` /
+    // `phrase_low` object whose `id` carries the raw kind value.
     const phrases = data.body.entries.map((entry) => {
         var _a;
+        const kind = typeof entry.kind === 'object' ? entry.kind.id : entry.kind;
         const phrase = {
-            index: entry.index,
-            beat: entry.beat,
-            kind: entry.kind,
-            phraseType: (_a = phraseTypeMap[mood][entry.kind]) !== null && _a !== void 0 ? _a : 'Unknown',
+            index: entry.phraseNumber,
+            beat: entry.beatNumber,
+            kind,
+            phraseType: (_a = phraseTypeMap[mood][kind]) !== null && _a !== void 0 ? _a : 'Unknown',
         };
         // Add fill-in information if present
-        if (entry.fill > 0) {
-            phrase.fill = entry.fill;
-            phrase.fillBeat = entry.beatFill;
+        if (entry.fillIn > 0) {
+            phrase.fill = entry.fillIn;
+            phrase.fillBeat = entry.fillInBeatNumber;
         }
         return phrase;
     });
@@ -7149,9 +7295,9 @@ class ProlinkNetwork {
         // Create unified database
         const database = new db_1.default(localdb, remotedb, __classPrivateFieldGet(this, _ProlinkNetwork_deviceManager, "f"), __classPrivateFieldGet(this, _ProlinkNetwork_logger, "f"));
         // Create controller service
-        const control = new control_1.default(__classPrivateFieldGet(this, _ProlinkNetwork_beatSocket, "f"), vcdj);
+        const control = new control_1.default(__classPrivateFieldGet(this, _ProlinkNetwork_beatSocket, "f"), vcdj, __classPrivateFieldGet(this, _ProlinkNetwork_statusSocket, "f"));
         __classPrivateFieldSet(this, _ProlinkNetwork_state, types_1.NetworkState.Connected, "f");
-        __classPrivateFieldSet(this, _ProlinkNetwork_connection, { announcer, heartbeat, control, remotedb, localdb, database }, "f");
+        __classPrivateFieldSet(this, _ProlinkNetwork_connection, { vcdj, announcer, heartbeat, control, remotedb, localdb, database }, "f");
         tx.finish();
     }
     /**
@@ -7238,6 +7384,15 @@ class ProlinkNetwork {
     get positionEmitter() {
         return __classPrivateFieldGet(this, _ProlinkNetwork_state, "f") === types_1.NetworkState.Connected ? __classPrivateFieldGet(this, _ProlinkNetwork_positionEmitter, "f") : null;
     }
+    /**
+     * The device this network announces itself as, once connected: the
+     * `hostDevice` the status emitter's media query and the control service
+     * send from.
+     */
+    get virtualDevice() {
+        var _a, _b;
+        return (_b = (_a = __classPrivateFieldGet(this, _ProlinkNetwork_connection, "f")) === null || _a === void 0 ? void 0 : _a.vcdj) !== null && _b !== void 0 ? _b : null;
+    }
     /**
      * Get the {@link Control} service. This service can be used to control the
      * Playstate of CDJs on the network.