alphatheta-connect 0.26.1 → 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)
@@ -7176,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();
     }
     /**
@@ -7265,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.