alphatheta-connect 0.23.2 → 0.25.1

package/lib/index.js

@@ -631,8 +631,10 @@ exports.MAX_CDJ_DEVICE_ID = exports.MIN_CDJ_DEVICE_ID = exports.VIRTUAL_CDJ_FIRM
 /**
  * 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.
+ * Out of the 1-6 player range, so it can never collide with a real CDJ.
+ * Remotedb metadata still works from here: the 1-6 restriction applies to the
+ * device-ID byte inside remotedb messages, which RemoteDatabase picks
+ * per-connection independently of the announced ID.
  */
 exports.DEFAULT_VCDJ_ID = 0x07;
 /**
@@ -1266,25 +1268,24 @@ async function viaRemote(remote, opts) {
     return track;
 }
 async function viaLocal(local, device, opts) {
-    const { deviceId, trackSlot, trackId } = opts;
+    const { deviceId, trackSlot, trackId, trackBPM } = opts;
     if (trackSlot !== types_1.MediaSlot.USB && trackSlot !== types_1.MediaSlot.SD) {
         throw new Error('Expected USB or SD slot for local database query');
     }
-    const adapter = await local.get(deviceId, trackSlot);
-    if (adapter === null) {
-        return { track: null, miss: 'no-database' };
+    const lookup = await local.findTrack(deviceId, trackSlot, trackId, { trackBPM });
+    if (lookup.adapter === null) {
+        return { track: null, miss: 'no-database', switchedTo: null };
     }
-    const dbTrack = adapter.findTrack(trackId);
-    if (dbTrack === null) {
-        return { track: null, miss: 'track-absent' };
+    if (lookup.track === null) {
+        return { track: null, miss: 'track-absent', switchedTo: null };
     }
-    const anlz = await (0, rekordbox_1.loadAnlz)(dbTrack, 'DAT', (0, utils_1.anlzLoader)({ device, slot: trackSlot }));
+    const anlz = await (0, rekordbox_1.loadAnlz)(lookup.track, 'DAT', (0, utils_1.anlzLoader)({ device, slot: trackSlot }));
     const track = {
-        ...dbTrack,
+        ...lookup.track,
         beatGrid: anlz.beatGrid,
         waveformHd: null,
     };
-    return { track, miss: null };
+    return { track, miss: null, switchedTo: lookup.switchedTo };
 }
 
 
@@ -1536,7 +1537,6 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 };
 var _Database_instances, _Database_deviceManager, _Database_localDatabase, _Database_remoteDatabase, _Database_logger, _Database_getTrackLookupStrategy, _Database_getMediaLookupStrategy, _Database_metadataViaRemoteFallback;
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-const constants_1 = __webpack_require__(/*! src/constants */ "./src/constants.ts");
 const logger_1 = __webpack_require__(/*! src/logger */ "./src/logger.ts");
 const types_1 = __webpack_require__(/*! src/types */ "./src/types.ts");
 const utils_1 = __webpack_require__(/*! src/utils */ "./src/utils/index.ts");
@@ -1609,6 +1609,7 @@ class Database {
      * Retrieve metadata for a track on a specific device slot.
      */
     async getMetadata(opts) {
+        var _a;
         const { deviceId, trackType, trackSlot, span } = opts;
         const tx = span
             ? span.startChild({ op: 'dbGetMetadata' })
@@ -1616,7 +1617,7 @@ class Database {
         tx.setTag('deviceId', deviceId.toString());
         tx.setTag('trackType', (0, utils_1.getTrackTypeName)(trackType));
         tx.setTag('trackSlot', (0, utils_1.getSlotName)(trackSlot));
-        const callOpts = { ...opts, span: tx };
+        const callOpts = { ...opts, trackBPM: (_a = opts.trackBPM) !== null && _a !== void 0 ? _a : null, span: tx };
         const device = await __classPrivateFieldGet(this, _Database_deviceManager, "f").getDeviceEnsured(deviceId);
         if (device === null) {
             return null;
@@ -1629,6 +1630,12 @@ class Database {
         if (strategy === LookupStrategy.Local) {
             const local = await GetMetadata.viaLocal(__classPrivateFieldGet(this, _Database_localDatabase, "f"), device, callOpts);
             track = local.track;
+            if (local.switchedTo !== null) {
+                __classPrivateFieldGet(this, _Database_logger, "f").info(`Device ${deviceId} ${(0, utils_1.getSlotName)(trackSlot)} is now read from the ` +
+                    `${local.switchedTo === 'pdb' ? 'legacy PDB' : 'OneLibrary'} database: ` +
+                    `it is the one that holds track ${opts.trackId} as the player reports it ` +
+                    `(NP3-399)`);
+            }
             // A local miss used to end the lookup, so the DJ's track silently never
             // reached the overlay for the rest of the set (NP3-361). Say what was
             // missed, then give the CDJ's own database a chance to answer.
@@ -1836,20 +1843,14 @@ _Database_deviceManager = new WeakMap(), _Database_localDatabase = new WeakMap()
 /**
  * Second chance for a track the local database could not answer for.
  *
- * CDJs only answer remote database queries from a host announcing a device
- * ID in the 1-6 range, so this is unavailable whenever the virtual CDJ sits
- * outside it (the package default is 7). That is a real configuration, not
- * an error — log why the fallback was skipped rather than throwing, so the
- * next report says which of the two happened.
+ * Available regardless of the virtual CDJ's announced ID: CDJs restrict
+ * remote database queries to a device-ID byte in the 1-6 range, but that
+ * byte lives inside the remotedb messages and RemoteDatabase picks an
+ * in-range one per connection — the announced ID never constrains this
+ * lookup. A failure here is logged rather than thrown, so a field report
+ * says what actually went wrong.
  */
 async function _Database_metadataViaRemoteFallback(opts) {
-    const hostId = __classPrivateFieldGet(this, _Database_remoteDatabase, "f").hostDevice.id;
-    if (hostId < constants_1.MIN_CDJ_DEVICE_ID || hostId > constants_1.MAX_CDJ_DEVICE_ID) {
-        __classPrivateFieldGet(this, _Database_logger, "f").warn(`No remote fallback for track ${opts.trackId}: this player is device ` +
-            `${hostId}, and CDJs only answer remote database queries from ` +
-            `devices ${constants_1.MIN_CDJ_DEVICE_ID}-${constants_1.MAX_CDJ_DEVICE_ID}`);
-        return null;
-    }
     try {
         const track = await GetMetadata.viaRemote(__classPrivateFieldGet(this, _Database_remoteDatabase, "f"), opts);
         if (track === null) {
@@ -2134,7 +2135,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.noopLogger = exports.REMOTEDB_MAX_DEVICE_ID = exports.playerNumberCeiling = exports.pickAvailableDeviceId = exports.MIXER_PLAYER_CEILING = exports.MAX_DEVICE_ID = exports.DEFAULT_MIXER_PLAYER_CEILING = exports.OneLibraryAdapter = exports.fetchFile = exports.loadAnlz = exports.isMetadataExtractionSupported = exports.extractMetadataFromDevice = exports.extractFullMetadata = exports.PictureType = exports.isArtworkExtractionSupported = exports.extractArtworkFromDevice = exports.extractArtwork = exports.PositionEmitter = void 0;
+exports.noopLogger = exports.REMOTEDB_MAX_DEVICE_ID = exports.playerNumberCeiling = exports.pickRemoteDbQueryId = exports.pickAvailableDeviceId = exports.MIXER_PLAYER_CEILING = exports.MAX_DEVICE_ID = exports.DEFAULT_MIXER_PLAYER_CEILING = exports.OneLibraryAdapter = exports.fetchFile = exports.loadAnlz = exports.isMetadataExtractionSupported = exports.extractMetadataFromDevice = exports.extractFullMetadata = exports.PictureType = exports.isArtworkExtractionSupported = exports.extractArtworkFromDevice = exports.extractArtwork = exports.PositionEmitter = void 0;
 __exportStar(__webpack_require__(/*! ./entities */ "./src/entities.ts"), exports);
 __exportStar(__webpack_require__(/*! ./mixstatus */ "./src/mixstatus/index.ts"), exports);
 __exportStar(__webpack_require__(/*! ./network */ "./src/network.ts"), exports);
@@ -2162,6 +2163,7 @@ Object.defineProperty(exports, "DEFAULT_MIXER_PLAYER_CEILING", ({ enumerable: tr
 Object.defineProperty(exports, "MAX_DEVICE_ID", ({ enumerable: true, get: function () { return device_id_1.MAX_DEVICE_ID; } }));
 Object.defineProperty(exports, "MIXER_PLAYER_CEILING", ({ enumerable: true, get: function () { return device_id_1.MIXER_PLAYER_CEILING; } }));
 Object.defineProperty(exports, "pickAvailableDeviceId", ({ enumerable: true, get: function () { return device_id_1.pickAvailableDeviceId; } }));
+Object.defineProperty(exports, "pickRemoteDbQueryId", ({ enumerable: true, get: function () { return device_id_1.pickRemoteDbQueryId; } }));
 Object.defineProperty(exports, "playerNumberCeiling", ({ enumerable: true, get: function () { return device_id_1.playerNumberCeiling; } }));
 Object.defineProperty(exports, "REMOTEDB_MAX_DEVICE_ID", ({ enumerable: true, get: function () { return device_id_1.REMOTEDB_MAX_DEVICE_ID; } }));
 var logger_1 = __webpack_require__(/*! ./logger */ "./src/logger.ts");
@@ -2224,7 +2226,7 @@ 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 _LocalDatabase_hostDevice, _LocalDatabase_deviceManager, _LocalDatabase_statusEmitter, _LocalDatabase_emitter, _LocalDatabase_slotLocks, _LocalDatabase_dbs, _LocalDatabase_preference, _LocalDatabase_handleDeviceRemoved, _LocalDatabase_fetchFileWithFallback, _LocalDatabase_tryLoadOneLibrary, _LocalDatabase_loadPdbDatabase, _LocalDatabase_hydrateDatabase;
+var _LocalDatabase_instances, _LocalDatabase_hostDevice, _LocalDatabase_deviceManager, _LocalDatabase_statusEmitter, _LocalDatabase_emitter, _LocalDatabase_slotLocks, _LocalDatabase_dbs, _LocalDatabase_preference, _LocalDatabase_handleDeviceRemoved, _LocalDatabase_closeLoaded, _LocalDatabase_fetchFileWithFallback, _LocalDatabase_tryLoadOneLibrary, _LocalDatabase_loadPdbDatabase, _LocalDatabase_hydrateDatabase, _LocalDatabase_loadAlternate, _LocalDatabase_getItem;
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 const async_mutex_1 = __webpack_require__(/*! async-mutex */ "async-mutex");
 const onelibrary_connect_1 = __webpack_require__(/*! onelibrary-connect */ "onelibrary-connect");
@@ -2240,6 +2242,18 @@ const utils_1 = __webpack_require__(/*! src/utils */ "./src/utils/index.ts");
 const Telemetry = __importStar(__webpack_require__(/*! src/utils/telemetry */ "./src/utils/telemetry.ts"));
 const orm_1 = __webpack_require__(/*! ./orm */ "./src/localdb/orm.ts");
 const rekordbox_1 = __webpack_require__(/*! ./rekordbox */ "./src/localdb/rekordbox.ts");
+/**
+ * A row is only trusted when the player's reported BPM agrees with it. Either
+ * side missing (unanalysed track, or a player that reports no BPM) is
+ * inconclusive and counts as agreement.
+ */
+const trackAgreesWithPlayer = (track, hint) => {
+    const reported = hint.trackBPM;
+    if (reported === null || reported === undefined || !track.tempo) {
+        return true;
+    }
+    return Math.abs(track.tempo - reported) < 0.05;
+};
 /**
  * Compute the identifier for media device in a CDJ. This is used to determine
  * if we have already hydrated the device or not into our local database.
@@ -2266,6 +2280,7 @@ const getMediaId = (info) => {
  */
 class LocalDatabase {
     constructor(hostDevice, deviceManager, statusEmitter, preference = 'auto') {
+        _LocalDatabase_instances.add(this);
         _LocalDatabase_hostDevice.set(this, void 0);
         _LocalDatabase_deviceManager.set(this, void 0);
         _LocalDatabase_statusEmitter.set(this, void 0);
@@ -2297,19 +2312,25 @@ class LocalDatabase {
         _LocalDatabase_handleDeviceRemoved.set(this, (device) => {
             const db = __classPrivateFieldGet(this, _LocalDatabase_dbs, "f").find(db => db.media.deviceId === device.id);
             if (db) {
-                db.adapter.close();
-                // Clean up temp file if it exists (OneLibrary databases)
-                if (db.tempFile) {
-                    try {
-                        fs.unlinkSync(db.tempFile);
-                    }
-                    catch {
-                        // Ignore cleanup errors
-                    }
+                __classPrivateFieldGet(this, _LocalDatabase_closeLoaded, "f").call(this, db);
+                if (db.alternate) {
+                    __classPrivateFieldGet(this, _LocalDatabase_closeLoaded, "f").call(this, db.alternate);
                 }
             }
             __classPrivateFieldSet(this, _LocalDatabase_dbs, __classPrivateFieldGet(this, _LocalDatabase_dbs, "f").filter(db => db.media.deviceId !== device.id), "f");
         });
+        _LocalDatabase_closeLoaded.set(this, (loaded) => {
+            loaded.adapter.close();
+            // Clean up temp file if it exists (OneLibrary databases)
+            if (loaded.tempFile) {
+                try {
+                    fs.unlinkSync(loaded.tempFile);
+                }
+                catch {
+                    // Ignore cleanup errors
+                }
+            }
+        });
         /**
          * Helper to fetch a file from device, trying both dotted and non-dotted paths
          */
@@ -2416,11 +2437,54 @@ class LocalDatabase {
                 }
             }
             __classPrivateFieldGet(this, _LocalDatabase_emitter, "f").emit('hydrationDone', { device, slot });
-            const db = { adapter, media, id: getMediaId(media), tempFile };
+            const db = {
+                adapter,
+                media,
+                device,
+                slot,
+                id: getMediaId(media),
+                tempFile,
+                alternateLock: new async_mutex_1.Mutex(),
+            };
             __classPrivateFieldGet(this, _LocalDatabase_dbs, "f").push(db);
             tx.finish();
             return db;
         });
+        /**
+         * Loads the database format the slot is *not* currently served from, so a
+         * lookup can be checked against it. Only meaningful under the 'auto'
+         * preference: a forced format has no alternate. The result (or its absence)
+         * is remembered so the media is never downloaded twice.
+         */
+        _LocalDatabase_loadAlternate.set(this, (db) => db.alternateLock.runExclusive(async () => {
+            if (db.alternate !== undefined) {
+                return db.alternate;
+            }
+            if (__classPrivateFieldGet(this, _LocalDatabase_preference, "f") !== 'auto') {
+                db.alternate = null;
+                return null;
+            }
+            const tx = Telemetry.startTransaction({ name: 'hydrateAlternateDatabase' });
+            tx.setTag('slot', (0, utils_1.getSlotName)(db.media.slot));
+            tx.setTag('activeDbType', db.adapter.type);
+            try {
+                if (db.adapter.type === 'oneLibrary') {
+                    const adapter = await __classPrivateFieldGet(this, _LocalDatabase_loadPdbDatabase, "f").call(this, db.device, db.slot, tx);
+                    db.alternate = { adapter };
+                    tx.setTag('dbType', 'pdb');
+                }
+                else {
+                    db.alternate = await __classPrivateFieldGet(this, _LocalDatabase_tryLoadOneLibrary, "f").call(this, db.device, db.slot, tx);
+                    tx.setTag('dbType', db.alternate ? 'oneLibrary' : 'none');
+                }
+            }
+            catch {
+                // The media simply has no such file (or it could not be read).
+                db.alternate = null;
+            }
+            tx.finish();
+            return db.alternate;
+        }));
         __classPrivateFieldSet(this, _LocalDatabase_hostDevice, hostDevice, "f");
         __classPrivateFieldSet(this, _LocalDatabase_deviceManager, deviceManager, "f");
         __classPrivateFieldSet(this, _LocalDatabase_statusEmitter, statusEmitter, "f");
@@ -2445,6 +2509,45 @@ class LocalDatabase {
     disconnectForDevice(device) {
         __classPrivateFieldGet(this, _LocalDatabase_handleDeviceRemoved, "f").call(this, device);
     }
+    /**
+     * Looks a track up in the databases of a device slot, checking the answer
+     * against what the player reports.
+     *
+     * A Device Library Plus export carries both `exportLibrary.db` and the
+     * legacy `export.pdb`, and their track IDs are different number spaces. A
+     * player that reads one while we loaded the other resolves most IDs to a
+     * different track and some to nothing at all (NP3-399). So when the active
+     * database has no such row, or its row's BPM is not the BPM the player is
+     * showing, the other format is loaded and asked. If it agrees with the
+     * player, the slot switches to it for every later lookup — artwork,
+     * analysis and the next track all follow the database the player is using.
+     *
+     * When neither database can be confirmed, the active database's row (if any)
+     * is returned as before.
+     */
+    async findTrack(deviceId, slot, trackId, hint = {}) {
+        const db = await __classPrivateFieldGet(this, _LocalDatabase_instances, "m", _LocalDatabase_getItem).call(this, deviceId, slot);
+        if (db === null) {
+            return { adapter: null, track: null, switchedTo: null };
+        }
+        const active = db.adapter.findTrack(trackId);
+        if (active !== null && trackAgreesWithPlayer(active, hint)) {
+            return { adapter: db.adapter, track: active, switchedTo: null };
+        }
+        const alternate = await __classPrivateFieldGet(this, _LocalDatabase_loadAlternate, "f").call(this, db);
+        if (alternate !== null) {
+            const other = alternate.adapter.findTrack(trackId);
+            if (other !== null && trackAgreesWithPlayer(other, hint)) {
+                db.alternate = { adapter: db.adapter, tempFile: db.tempFile };
+                db.adapter = alternate.adapter;
+                db.tempFile = alternate.tempFile;
+                return { adapter: db.adapter, track: other, switchedTo: db.adapter.type };
+            }
+        }
+        return active === null
+            ? { adapter: db.adapter, track: null, switchedTo: null }
+            : { adapter: db.adapter, track: active, switchedTo: null };
+    }
     /**
      * Gets the database adapter for the media metadata in the provided device slot.
      *
@@ -2455,43 +2558,8 @@ class LocalDatabase {
      */
     async get(deviceId, slot) {
         var _a;
-        const lockKey = `${deviceId}-${slot}`;
-        const lock = (_a = __classPrivateFieldGet(this, _LocalDatabase_slotLocks, "f").get(lockKey)) !== null && _a !== void 0 ? _a : __classPrivateFieldGet(this, _LocalDatabase_slotLocks, "f").set(lockKey, new async_mutex_1.Mutex()).get(lockKey);
-        const device = __classPrivateFieldGet(this, _LocalDatabase_deviceManager, "f").devices.get(deviceId);
-        if (device === undefined) {
-            return null;
-        }
-        if (device.type !== types_1.DeviceType.CDJ ||
-            device.id < constants_1.MIN_CDJ_DEVICE_ID ||
-            device.id > constants_1.MAX_CDJ_DEVICE_ID) {
-            return null;
-        }
-        let media;
-        try {
-            media = await __classPrivateFieldGet(this, _LocalDatabase_statusEmitter, "f").queryMediaSlot({
-                hostDevice: __classPrivateFieldGet(this, _LocalDatabase_hostDevice, "f"),
-                device,
-                slot,
-            });
-        }
-        catch {
-            // Timeout or other error - treat as no media
-            return null;
-        }
-        if (media.tracksType !== types_1.TrackType.RB) {
-            return null;
-        }
-        const id = getMediaId(media);
-        // Acquire a lock for this device slot that will not release until we've
-        // guaranteed the existence of the database.
-        const db = await lock.runExclusive(() => {
-            const cached = __classPrivateFieldGet(this, _LocalDatabase_dbs, "f").find(db => db.id === id);
-            if (cached) {
-                return cached;
-            }
-            return __classPrivateFieldGet(this, _LocalDatabase_hydrateDatabase, "f").call(this, device, slot, media);
-        });
-        return db.adapter;
+        const db = await __classPrivateFieldGet(this, _LocalDatabase_instances, "m", _LocalDatabase_getItem).call(this, deviceId, slot);
+        return (_a = db === null || db === void 0 ? void 0 : db.adapter) !== null && _a !== void 0 ? _a : null;
     }
     /**
      * Get the database type for an already-loaded device slot.
@@ -2517,7 +2585,50 @@ class LocalDatabase {
         await Promise.all(loaders);
     }
 }
-_LocalDatabase_hostDevice = new WeakMap(), _LocalDatabase_deviceManager = new WeakMap(), _LocalDatabase_statusEmitter = new WeakMap(), _LocalDatabase_emitter = new WeakMap(), _LocalDatabase_slotLocks = new WeakMap(), _LocalDatabase_dbs = new WeakMap(), _LocalDatabase_preference = new WeakMap(), _LocalDatabase_handleDeviceRemoved = new WeakMap(), _LocalDatabase_fetchFileWithFallback = new WeakMap(), _LocalDatabase_tryLoadOneLibrary = new WeakMap(), _LocalDatabase_loadPdbDatabase = new WeakMap(), _LocalDatabase_hydrateDatabase = new WeakMap();
+_LocalDatabase_hostDevice = new WeakMap(), _LocalDatabase_deviceManager = new WeakMap(), _LocalDatabase_statusEmitter = new WeakMap(), _LocalDatabase_emitter = new WeakMap(), _LocalDatabase_slotLocks = new WeakMap(), _LocalDatabase_dbs = new WeakMap(), _LocalDatabase_preference = new WeakMap(), _LocalDatabase_handleDeviceRemoved = new WeakMap(), _LocalDatabase_closeLoaded = new WeakMap(), _LocalDatabase_fetchFileWithFallback = new WeakMap(), _LocalDatabase_tryLoadOneLibrary = new WeakMap(), _LocalDatabase_loadPdbDatabase = new WeakMap(), _LocalDatabase_hydrateDatabase = new WeakMap(), _LocalDatabase_loadAlternate = new WeakMap(), _LocalDatabase_instances = new WeakSet(), _LocalDatabase_getItem = 
+/**
+ * The loaded database entry for a device slot, hydrating it first if needed.
+ */
+async function _LocalDatabase_getItem(deviceId, slot) {
+    var _a;
+    const lockKey = `${deviceId}-${slot}`;
+    const lock = (_a = __classPrivateFieldGet(this, _LocalDatabase_slotLocks, "f").get(lockKey)) !== null && _a !== void 0 ? _a : __classPrivateFieldGet(this, _LocalDatabase_slotLocks, "f").set(lockKey, new async_mutex_1.Mutex()).get(lockKey);
+    const device = __classPrivateFieldGet(this, _LocalDatabase_deviceManager, "f").devices.get(deviceId);
+    if (device === undefined) {
+        return null;
+    }
+    if (device.type !== types_1.DeviceType.CDJ ||
+        device.id < constants_1.MIN_CDJ_DEVICE_ID ||
+        device.id > constants_1.MAX_CDJ_DEVICE_ID) {
+        return null;
+    }
+    let media;
+    try {
+        media = await __classPrivateFieldGet(this, _LocalDatabase_statusEmitter, "f").queryMediaSlot({
+            hostDevice: __classPrivateFieldGet(this, _LocalDatabase_hostDevice, "f"),
+            device,
+            slot,
+        });
+    }
+    catch {
+        // Timeout or other error - treat as no media
+        return null;
+    }
+    if (media.tracksType !== types_1.TrackType.RB) {
+        return null;
+    }
+    const id = getMediaId(media);
+    // Acquire a lock for this device slot that will not release until we've
+    // guaranteed the existence of the database.
+    const db = await lock.runExclusive(() => {
+        const cached = __classPrivateFieldGet(this, _LocalDatabase_dbs, "f").find(db => db.id === id);
+        if (cached) {
+            return cached;
+        }
+        return __classPrivateFieldGet(this, _LocalDatabase_hydrateDatabase, "f").call(this, device, slot, media);
+    });
+    return db;
+};
 exports["default"] = LocalDatabase;
 
 
@@ -6793,7 +6904,7 @@ class MixstatusProcessor {
         // able to report it as live
         const startedAt = __classPrivateFieldGet(this, _MixstatusProcessor_lastStartTime, "f").get(deviceId);
         const requiredPlayTime = __classPrivateFieldGet(this, _MixstatusProcessor_config, "f").beatsUntilReported *
-            (0, utils_1.bpmToSeconds)(state.trackBPM, state.sliderPitch) *
+            (0, utils_1.bpmToSeconds)(state.trackBPM, state.effectivePitch) *
             1000;
         if (__classPrivateFieldGet(this, _MixstatusProcessor_config, "f").mode === types_1.MixstatusMode.SmartTiming &&
             startedAt !== undefined &&
@@ -6804,7 +6915,7 @@ class MixstatusProcessor {
         // we can mark the track as truly stopped.
         const stoppedAt = __classPrivateFieldGet(this, _MixstatusProcessor_lastStoppedTimes, "f").get(deviceId);
         const requiredStopTime = __classPrivateFieldGet(this, _MixstatusProcessor_config, "f").allowedInterruptBeats *
-            (0, utils_1.bpmToSeconds)(state.trackBPM, state.sliderPitch) *
+            (0, utils_1.bpmToSeconds)(state.trackBPM, state.effectivePitch) *
             1000;
         if (stoppedAt !== undefined && requiredStopTime <= Date.now() - stoppedAt) {
             __classPrivateFieldGet(this, _MixstatusProcessor_markPlayerStopped, "f").call(this, state);
@@ -7095,6 +7206,14 @@ class ProlinkNetwork {
             announcer = new virtualcdj_1.Announcer(vcdj, __classPrivateFieldGet(this, _ProlinkNetwork_announceSocket, "f"), this.deviceManager, __classPrivateFieldGet(this, _ProlinkNetwork_config, "f").iface, (_d = __classPrivateFieldGet(this, _ProlinkNetwork_config, "f").fullStartup) !== null && _d !== void 0 ? _d : false, (_e = __classPrivateFieldGet(this, _ProlinkNetwork_config, "f").announceToStagehand) !== null && _e !== void 0 ? _e : false, __classPrivateFieldGet(this, _ProlinkNetwork_logger, "f"));
         }
         announcer.start();
+        // In Stagehand mode, unicast keep-alives to discovered players and the
+        // mixer so they push live state to us (mixer 0x39/0x58, CDJ 0x69/waveforms).
+        // Broadcast presence alone does not bootstrap that stream.
+        let heartbeat = null;
+        if (connectMethod === 'stagehand') {
+            heartbeat = new virtualcdj_1.StagehandHeartbeat(vcdj, __classPrivateFieldGet(this, _ProlinkNetwork_statusSocket, "f"), __classPrivateFieldGet(this, _ProlinkNetwork_deviceManager, "f"), __classPrivateFieldGet(this, _ProlinkNetwork_logger, "f"));
+            heartbeat.start();
+        }
         // Create remote and local databases
         const remotedb = new remotedb_1.default(__classPrivateFieldGet(this, _ProlinkNetwork_deviceManager, "f"), vcdj);
         const localdb = new localdb_1.default(vcdj, __classPrivateFieldGet(this, _ProlinkNetwork_deviceManager, "f"), __classPrivateFieldGet(this, _ProlinkNetwork_statusEmitter, "f"), (_f = __classPrivateFieldGet(this, _ProlinkNetwork_config, "f").databasePreference) !== null && _f !== void 0 ? _f : 'auto');
@@ -7103,23 +7222,24 @@ class ProlinkNetwork {
         // Create controller service
         const control = new control_1.default(__classPrivateFieldGet(this, _ProlinkNetwork_beatSocket, "f"), vcdj);
         __classPrivateFieldSet(this, _ProlinkNetwork_state, types_1.NetworkState.Connected, "f");
-        __classPrivateFieldSet(this, _ProlinkNetwork_connection, { announcer, control, remotedb, localdb, database }, "f");
+        __classPrivateFieldSet(this, _ProlinkNetwork_connection, { announcer, heartbeat, control, remotedb, localdb, database }, "f");
         tx.finish();
     }
     /**
      * Disconnect from the network
      */
     disconnect() {
-        var _a, _b, _c;
+        var _a, _b, _c, _d, _e;
         if (__classPrivateFieldGet(this, _ProlinkNetwork_config, "f") === null) {
             throw new Error(connectErrorHelp);
         }
         // Stop announcing ourself
         (_a = __classPrivateFieldGet(this, _ProlinkNetwork_connection, "f")) === null || _a === void 0 ? void 0 : _a.announcer.stop();
+        (_c = (_b = __classPrivateFieldGet(this, _ProlinkNetwork_connection, "f")) === null || _b === void 0 ? void 0 : _b.heartbeat) === null || _c === void 0 ? void 0 : _c.stop();
         // Disconnect devices from the remote and local databases
         for (const device of this.deviceManager.devices.values()) {
-            (_b = this.remotedb) === null || _b === void 0 ? void 0 : _b.disconnectFromDevice(device);
-            (_c = this.localdb) === null || _c === void 0 ? void 0 : _c.disconnectForDevice(device);
+            (_d = this.remotedb) === null || _d === void 0 ? void 0 : _d.disconnectFromDevice(device);
+            (_e = this.localdb) === null || _e === void 0 ? void 0 : _e.disconnectForDevice(device);
         }
         return this.close;
     }
@@ -10649,15 +10769,17 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
-var _Connection_socket, _Connection_txId, _Connection_lock, _QueryInterface_conn, _QueryInterface_hostDevice, _QueryInterface_lock, _RemoteDatabase_hostDevice, _RemoteDatabase_deviceManager, _RemoteDatabase_connections, _RemoteDatabase_deviceLocks;
+var _Connection_socket, _Connection_txId, _Connection_lock, _QueryInterface_conn, _QueryInterface_hostDevice, _QueryInterface_lock, _RemoteDatabase_instances, _RemoteDatabase_hostDevice, _RemoteDatabase_deviceManager, _RemoteDatabase_connections, _RemoteDatabase_deviceLocks, _RemoteDatabase_queryIds, _RemoteDatabase_pickQueryId, _RemoteDatabase_queryIdFor;
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.QueryInterface = exports.Connection = exports.Query = exports.MenuTarget = void 0;
 exports.getQueryName = getQueryName;
 const async_mutex_1 = __webpack_require__(/*! async-mutex */ "async-mutex");
 const promise_socket_1 = __importDefault(__webpack_require__(/*! promise-socket */ "promise-socket"));
 const net_1 = __webpack_require__(/*! net */ "net");
+const types_1 = __webpack_require__(/*! src/types */ "./src/types.ts");
 const Telemetry = __importStar(__webpack_require__(/*! src/utils/telemetry */ "./src/utils/telemetry.ts"));
-const types_1 = __webpack_require__(/*! ./message/types */ "./src/remotedb/message/types.ts");
+const device_id_1 = __webpack_require__(/*! src/virtualcdj/device-id */ "./src/virtualcdj/device-id.ts");
+const types_2 = __webpack_require__(/*! ./message/types */ "./src/remotedb/message/types.ts");
 const constants_1 = __webpack_require__(/*! ./constants */ "./src/remotedb/constants.ts");
 const fields_1 = __webpack_require__(/*! ./fields */ "./src/remotedb/fields.ts");
 const message_1 = __webpack_require__(/*! ./message */ "./src/remotedb/message/index.ts");
@@ -10670,7 +10792,7 @@ var MenuTarget;
 (function (MenuTarget) {
     MenuTarget[MenuTarget["Main"] = 1] = "Main";
 })(MenuTarget || (exports.MenuTarget = MenuTarget = {}));
-exports.Query = types_1.Request;
+exports.Query = types_2.Request;
 const QueryInverse = Object.fromEntries(Object.entries(exports.Query).map(e => [e[1], e[0]]));
 /**
  * Returns a string representation of a remote query
@@ -10716,7 +10838,7 @@ class Connection {
         var _a;
         const tx = span.startChild({
             op: 'writeMessage',
-            description: (0, types_1.getMessageName)(message.type),
+            description: (0, types_2.getMessageName)(message.type),
         });
         message.transactionId = __classPrivateFieldSet(this, _Connection_txId, (_a = __classPrivateFieldGet(this, _Connection_txId, "f"), ++_a), "f");
         await __classPrivateFieldGet(this, _Connection_socket, "f").write(message.buffer);
@@ -10777,7 +10899,8 @@ _QueryInterface_conn = new WeakMap(), _QueryInterface_hostDevice = new WeakMap()
  * Service that maintains remote database connections with devices on the network.
  */
 class RemoteDatabase {
-    constructor(deviceManager, hostDevice) {
+    constructor(deviceManager, hostDevice, { pickQueryId = true } = {}) {
+        _RemoteDatabase_instances.add(this);
         _RemoteDatabase_hostDevice.set(this, void 0);
         _RemoteDatabase_deviceManager.set(this, void 0);
         /**
@@ -10788,6 +10911,17 @@ class RemoteDatabase {
          * Locks for each device when locating the connection
          */
         _RemoteDatabase_deviceLocks.set(this, new Map());
+        /**
+         * The device ID each connection introduced itself with. Queries on that
+         * connection must carry the same ID.
+         */
+        _RemoteDatabase_queryIds.set(this, new Map());
+        /**
+         * Whether to substitute an in-range query ID when the host device sits
+         * outside 1-6. Disabled only by protocol probes that need to observe how a
+         * device treats the raw announced ID (see examples/remotedb-id-probe.ts).
+         */
+        _RemoteDatabase_pickQueryId.set(this, void 0);
         /**
          * Open a connection to the specified device for querying
          */
@@ -10812,20 +10946,22 @@ class RemoteDatabase {
                 throw new Error(`Expected 0x01 during preamble handshake. Got ${data.value}`);
             }
             // Send introduction message to set context for querying
+            const queryId = __classPrivateFieldGet(this, _RemoteDatabase_instances, "m", _RemoteDatabase_queryIdFor).call(this, device);
             const intro = new message_1.Message({
                 transactionId: 0xfffffffe,
-                type: types_1.MessageType.Introduce,
-                args: [new fields_1.UInt32(__classPrivateFieldGet(this, _RemoteDatabase_hostDevice, "f").id)],
+                type: types_2.MessageType.Introduce,
+                args: [new fields_1.UInt32(queryId)],
             });
             await socket.write(intro.buffer);
-            const resp = await message_1.Message.fromStream(socket, types_1.MessageType.Success, tx);
-            if (resp.type !== types_1.MessageType.Success) {
+            const resp = await message_1.Message.fromStream(socket, types_2.MessageType.Success, tx);
+            if (resp.type !== types_2.MessageType.Success) {
                 throw new Error(`Failed to introduce self to device ID: ${device.id}`);
             }
             // Clear socket timeout after successful connection — the per-device mutex
             // and application-level Promise.race timeouts handle query timeouts
             socket.stream.setTimeout(0);
             __classPrivateFieldGet(this, _RemoteDatabase_connections, "f").set(device.id, new Connection(device, socket));
+            __classPrivateFieldGet(this, _RemoteDatabase_queryIds, "f").set(device.id, queryId);
             tx.finish();
         };
         /**
@@ -10839,22 +10975,26 @@ class RemoteDatabase {
             }
             const goodbye = new message_1.Message({
                 transactionId: 0xfffffffe,
-                type: types_1.MessageType.Disconnect,
+                type: types_2.MessageType.Disconnect,
                 args: [],
             });
             await conn.writeMessage(goodbye, tx);
             conn.close();
             __classPrivateFieldGet(this, _RemoteDatabase_connections, "f").delete(device.id);
+            __classPrivateFieldGet(this, _RemoteDatabase_queryIds, "f").delete(device.id);
             tx.finish();
         };
         __classPrivateFieldSet(this, _RemoteDatabase_deviceManager, deviceManager, "f");
         __classPrivateFieldSet(this, _RemoteDatabase_hostDevice, hostDevice, "f");
+        __classPrivateFieldSet(this, _RemoteDatabase_pickQueryId, pickQueryId, "f");
     }
     /**
-     * The device we introduce ourselves as when opening a remote database
-     * connection. CDJs only answer queries from a host announcing an ID in the
-     * 1-6 range, so callers need to read this before deciding a remote lookup is
-     * even possible.
+     * The device this service belongs to — the virtual CDJ announced on the
+     * network. Note that this is NOT necessarily the ID carried inside remotedb
+     * messages: CDJs only answer queries whose in-protocol device-ID byte is
+     * 1-6, so when this device sits outside that range (announced above the
+     * player range to avoid collisions), each connection picks an in-range
+     * query ID via {@link pickRemoteDbQueryId} instead.
      */
     get hostDevice() {
         return __classPrivateFieldGet(this, _RemoteDatabase_hostDevice, "f");
@@ -10868,7 +11008,7 @@ class RemoteDatabase {
      * @returns null if the device does not export a remote database service
      */
     async get(deviceId) {
-        var _a;
+        var _a, _b;
         const device = __classPrivateFieldGet(this, _RemoteDatabase_deviceManager, "f").devices.get(deviceId);
         if (device === undefined) {
             return null;
@@ -10883,14 +11023,28 @@ class RemoteDatabase {
             conn = __classPrivateFieldGet(this, _RemoteDatabase_connections, "f").get(deviceId);
             // NOTE: We pass the same lock we use for this device to the query
             // interface to ensure all query interfaces use the same lock.
-            return new QueryInterface(conn, lock, __classPrivateFieldGet(this, _RemoteDatabase_hostDevice, "f"));
+            // Queries must carry the same device ID the connection introduced
+            // itself with, which is not always the announced host ID.
+            const queryId = (_b = __classPrivateFieldGet(this, _RemoteDatabase_queryIds, "f").get(device.id)) !== null && _b !== void 0 ? _b : __classPrivateFieldGet(this, _RemoteDatabase_hostDevice, "f").id;
+            return new QueryInterface(conn, lock, { ...__classPrivateFieldGet(this, _RemoteDatabase_hostDevice, "f"), id: queryId });
         }
         finally {
             releaseLock();
         }
     }
 }
-_RemoteDatabase_hostDevice = new WeakMap(), _RemoteDatabase_deviceManager = new WeakMap(), _RemoteDatabase_connections = new WeakMap(), _RemoteDatabase_deviceLocks = new WeakMap();
+_RemoteDatabase_hostDevice = new WeakMap(), _RemoteDatabase_deviceManager = new WeakMap(), _RemoteDatabase_connections = new WeakMap(), _RemoteDatabase_deviceLocks = new WeakMap(), _RemoteDatabase_queryIds = new WeakMap(), _RemoteDatabase_pickQueryId = new WeakMap(), _RemoteDatabase_instances = new WeakSet(), _RemoteDatabase_queryIdFor = function _RemoteDatabase_queryIdFor(device) {
+    const hostId = __classPrivateFieldGet(this, _RemoteDatabase_hostDevice, "f").id;
+    // An announced ID already inside the answered range keeps working exactly
+    // as it always has. Rekordbox (which numbers itself far above 6) answers
+    // queries regardless, so only CDJ targets need an in-range stand-in.
+    if (!__classPrivateFieldGet(this, _RemoteDatabase_pickQueryId, "f") ||
+        hostId <= device_id_1.REMOTEDB_MAX_DEVICE_ID ||
+        device.type !== types_1.DeviceType.CDJ) {
+        return hostId;
+    }
+    return (0, device_id_1.pickRemoteDbQueryId)(device.id, __classPrivateFieldGet(this, _RemoteDatabase_deviceManager, "f").devices.values());
+};
 exports["default"] = RemoteDatabase;
 
 
@@ -12184,10 +12338,29 @@ exports["default"] = PositionEmitter;
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.PlayState = exports.StatusFlag = void 0;
 /**
- * Status flag bitmasks
+ * Status flag bitmasks (byte 0x89 of the CDJ status packet).
+ *
+ * Verified against CDJ-3000 firmware (EP122 FW3.20): the deck assembles this
+ * byte in `sub_d7d3c8` (0xd7d3c8) from the BeatSyncMaster state struct, one
+ * source boolean per bit. The bits not named here:
+ *
+ * - bit 0 (0x01): structurally unused — no code path ever sets it (always 0).
+ * - bit 2 (0x04): a real, dedicated beat-sync boolean (struct +5), but its
+ *   name did not survive in the stripped `usecase::sync` async-task code. It
+ *   is normally 0, which is why it has never been observed on the wire.
+ * - bit 7 (0x80): a real bit (struct +0xa) that is default-set at init and
+ *   whose de-assertion itself triggers a state-change notification — best read
+ *   as a "sync-master active / handoff-in-progress" toggle. Also normally 0 in
+ *   steady state.
  */
 var StatusFlag;
 (function (StatusFlag) {
+    /**
+     * Degraded to BPM Sync: the player is still tracking the master's tempo, but
+     * beat alignment was dropped after a pitch-bend / jog nudge. Firmware sources
+     * this from BeatSyncMaster struct +4.
+     */
+    StatusFlag[StatusFlag["BpmSync"] = 2] = "BpmSync";
     StatusFlag[StatusFlag["OnAir"] = 8] = "OnAir";
     StatusFlag[StatusFlag["Sync"] = 16] = "Sync";
     StatusFlag[StatusFlag["Master"] = 32] = "Master";
@@ -12260,14 +12433,24 @@ function statusFromPacket(packet) {
         playState: packet[0x7b],
         isOnAir: (packet[0x89] & types_1.CDJStatus.StatusFlag.OnAir) !== 0,
         isSync: (packet[0x89] & types_1.CDJStatus.StatusFlag.Sync) !== 0,
+        isBpmSync: (packet[0x89] & types_1.CDJStatus.StatusFlag.BpmSync) !== 0,
         isMaster: (packet[0x89] & types_1.CDJStatus.StatusFlag.Master) !== 0,
         isEmergencyMode: !!packet[0xba],
         trackBPM,
-        sliderPitch: calcPitch(packet.slice(0x8d, 0x8d + 3)),
-        effectivePitch: calcPitch(packet.slice(0x99, 0x99 + 3)),
+        // The CDJ status packet carries four pitch values (firmware CDJ-3000 FW3.20,
+        // sub_d7d610): Pitch1@0x8c and Pitch3@0xc0 are the *effective* pitch (in
+        // effect / on the BPM display, from the fader or a synced master), while
+        // Pitch2@0x98 and Pitch4@0xc4 track the *local fader* position. We expose
+        // Pitch1 as `effectivePitch` and Pitch2 as `sliderPitch`.
+        effectivePitch: calcPitch(packet.slice(0x8d, 0x8d + 3)),
+        sliderPitch: calcPitch(packet.slice(0x99, 0x99 + 3)),
         beatInMeasure: packet[0xa6],
         beatsUntilCue,
         beat,
+        // Player-type / capability byte (dysentery's "nx"). Guarded because the
+        // length check above only guarantees 0xc8; older/short packets may not
+        // reach 0xcc, in which case the field reads as 0 (version-gated to 0 anyway).
+        deviceType: packet.length > 0xcc ? packet[0xcc] : 0,
         packetNum: packet.readUInt32BE(0xc8),
     };
     return status;
@@ -13012,11 +13195,17 @@ Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.DEFAULT_MIXER_PLAYER_CEILING = exports.MIXER_PLAYER_CEILING = exports.MAX_DEVICE_ID = exports.REMOTEDB_MAX_DEVICE_ID = void 0;
 exports.playerNumberCeiling = playerNumberCeiling;
 exports.pickAvailableDeviceId = pickAvailableDeviceId;
+exports.pickRemoteDbQueryId = pickRemoteDbQueryId;
 /**
  * The highest device ID a CDJ will answer remotedb queries from.
  *
- * CDJs ignore metadata requests from devices numbered above this, which is why
- * the 1-6 range is worth preferring even though real players live there too.
+ * This limit applies to the device-ID byte inside the remotedb protocol (the
+ * Introduce message and every query header), NOT to the ID we announce on the
+ * network. Hardware-verified on a CDJ-3000 (2026-08-30, two players + DJM-V5,
+ * announced as VCDJ 7 throughout): queries carrying 1-6 are all answered —
+ * including IDs of absent players and the target's own ID — while 7 and above
+ * are silently ignored (the TCP connection and Introduce succeed, the query
+ * never gets a response). See {@link pickRemoteDbQueryId}.
  */
 exports.REMOTEDB_MAX_DEVICE_ID = 6;
 /**
@@ -13024,11 +13213,13 @@ exports.REMOTEDB_MAX_DEVICE_ID = 6;
  */
 exports.MAX_DEVICE_ID = 32;
 /**
- * `DeviceType.Mixer`, inlined so this module stays free of runtime imports —
- * it is re-exported into consumers' test environments, where pulling in the
- * whole type module (and its ip-address dependency) is dead weight.
+ * `DeviceType.Mixer` and `DeviceType.CDJ`, inlined so this module stays free
+ * of runtime imports — it is re-exported into consumers' test environments,
+ * where pulling in the whole type module (and its ip-address dependency) is
+ * dead weight.
  */
 const MIXER_DEVICE_TYPE = 0x03;
+const CDJ_DEVICE_TYPE = 0x01;
 /**
  * How many player numbers each mixer can hand out.
  *
@@ -13127,24 +13318,233 @@ const ascending = (from, to) => {
  * Returns null when every ID from 1 to 32 is occupied, in which case there is
  * no safe ID and the caller must not join the network.
  */
-function pickAvailableDeviceId(usedIds, { preferRemoteDb = false, playerCeiling } = {}) {
+function pickAvailableDeviceId(usedIds, { preferPlayerRange = false, playerCeiling } = {}) {
     var _a;
     const used = new Set(usedIds);
     const aboveThePlayers = playerCeiling === undefined
         ? descending(exports.REMOTEDB_MAX_DEVICE_ID, 1)
         : ascending(playerCeiling + 1, exports.REMOTEDB_MAX_DEVICE_ID);
-    const outsideRemoteDb = ascending(exports.REMOTEDB_MAX_DEVICE_ID + 1, exports.MAX_DEVICE_ID);
+    const outsidePlayerRange = ascending(exports.REMOTEDB_MAX_DEVICE_ID + 1, exports.MAX_DEVICE_ID);
     // Numbers a player on this rig could be assigned. Last resort: better to
     // contend for a slot than not to join at all, and the announcer moves us if
     // the player that owns it shows up.
     const amongThePlayers = playerCeiling === undefined
         ? []
         : descending(Math.min(playerCeiling, exports.REMOTEDB_MAX_DEVICE_ID), 1);
-    const search = preferRemoteDb
-        ? [...aboveThePlayers, ...outsideRemoteDb, ...amongThePlayers]
-        : [...outsideRemoteDb, ...aboveThePlayers, ...amongThePlayers];
+    const search = preferPlayerRange
+        ? [...aboveThePlayers, ...outsidePlayerRange, ...amongThePlayers]
+        : [...outsidePlayerRange, ...aboveThePlayers, ...amongThePlayers];
     return (_a = search.find(id => !used.has(id))) !== null && _a !== void 0 ? _a : null;
 }
+/**
+ * Choose the device ID to carry inside remotedb messages when querying a CDJ.
+ *
+ * CDJs only answer remotedb queries whose in-protocol device-ID byte is in
+ * 1-6, but that byte is independent of the ID we announce on the network — so
+ * a virtual CDJ announced safely above the player range (say 7 behind a
+ * DJM-V10) can still query metadata by carrying an in-range ID here. Verified
+ * on a CDJ-3000 (2026-08-30): absent IDs and even the target's own ID are
+ * answered; 7+ is silently dropped.
+ *
+ * Older players are documented (dysentery, nexus era) as stricter: the byte
+ * had to be 1-4, belong to a player actually on the network, and not be the
+ * player being queried. The preference order below satisfies those rules
+ * whenever the rig makes it possible, then falls back through choices newer
+ * players accept.
+ */
+function pickRemoteDbQueryId(targetId, devices) {
+    const playerIds = new Set();
+    for (const device of devices) {
+        if (device.type === CDJ_DEVICE_TYPE && device.id <= exports.REMOTEDB_MAX_DEVICE_ID) {
+            playerIds.add(device.id);
+        }
+    }
+    // A live player that isn't the target, lowest first — 1-4 satisfies every
+    // documented era of the restriction.
+    const otherPlayers = [...playerIds].filter(id => id !== targetId).sort((a, b) => a - b);
+    if (otherPlayers.length > 0) {
+        return otherPlayers[0];
+    }
+    // No other player on the rig: take the lowest 1-6 ID no player holds.
+    for (let id = 1; id <= exports.REMOTEDB_MAX_DEVICE_ID; id++) {
+        if (id !== targetId && !playerIds.has(id)) {
+            return id;
+        }
+    }
+    // Six players and every one of them is the target? Impossible, but the
+    // target's own ID is answered too, so it is a safe closing fallback.
+    return targetId;
+}
+
+
+/***/ },
+
+/***/ "./src/virtualcdj/heartbeat.ts"
+/*!*************************************!*\
+  !*** ./src/virtualcdj/heartbeat.ts ***!
+  \*************************************/
+(__unused_webpack_module, exports, __webpack_require__) {
+
+"use strict";
+
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    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 _StagehandHeartbeat_instances, _StagehandHeartbeat_statusSocket, _StagehandHeartbeat_vcdj, _StagehandHeartbeat_deviceManager, _StagehandHeartbeat_logger, _StagehandHeartbeat_intervalHandle, _StagehandHeartbeat_sendHeartbeats;
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.StagehandHeartbeat = exports.STAGEHAND_HEARTBEAT_INTERVAL = void 0;
+exports.makeStagehandMixerHeartbeat = makeStagehandMixerHeartbeat;
+exports.makeStagehandPlayerHeartbeat = makeStagehandPlayerHeartbeat;
+const constants_1 = __webpack_require__(/*! src/constants */ "./src/constants.ts");
+const logger_1 = __webpack_require__(/*! src/logger */ "./src/logger.ts");
+const types_1 = __webpack_require__(/*! src/types */ "./src/types.ts");
+/**
+ * Cadence of the Stagehand unicast keep-alive, in milliseconds.
+ *
+ * The real iOS Stagehand app heartbeats every discovered player and the mixer
+ * at ~4 Hz (250ms median inter-packet gap in captured traffic). This is the
+ * stream that keeps AlphaTheta hardware unicasting live state (`0x39` mixer
+ * fader/EQ, `0x58` VU on the mixer; `0x69` slim status, waveform families on
+ * the CDJs) to our IP — subnet-broadcast presence alone (the `0x06` keep-alive)
+ * is not enough to bootstrap it.
+ */
+exports.STAGEHAND_HEARTBEAT_INTERVAL = 250;
+/**
+ * Builds a Stagehand name field for a unicast frame.
+ *
+ * Unlike the 20-byte {@link buildName} used by the broadcast announce/claim
+ * frames, unicast frames carry a 19-byte name field (offsets 11..29) with the
+ * device type / model bytes beginning at offset 30. The name is ASCII, NUL
+ * padded.
+ */
+function buildUnicastName(name) {
+    const field = new Uint8Array(19);
+    field.set(Buffer.from(name, 'ascii').subarray(0, 19));
+    return field;
+}
+/**
+ * Build the Stagehand mixer keep-alive (`0x3a`, 40 bytes).
+ *
+ * Verified byte-for-byte against the real iOS Stagehand app unicasting to a
+ * DJM-A9 at 4 Hz (Phase 4/5 captures §4.14.2). The 10-byte trailer
+ * `21 02 00 fe 00 04 00 1c 00 00` is constant across every observed sample —
+ * byte 33 (`0xfe`) is a VCDJ sentinel, not our runtime device number, so no
+ * per-device bytes vary here.
+ */
+function makeStagehandMixerHeartbeat(vcdj) {
+    const parts = [
+        ...constants_1.PROLINK_HEADER, // 0-9: magic
+        0x3a, // 10: type 0x3a (mixer keep-alive)
+        ...buildUnicastName(vcdj.name), // 11-29: name (19 bytes)
+        0x21,
+        0x02,
+        0x00,
+        0xfe,
+        0x00,
+        0x04,
+        0x00,
+        0x1c,
+        0x00,
+        0x00, // 30-39: constant trailer
+    ];
+    return Uint8Array.from(parts);
+}
+/**
+ * Build the Stagehand player keep-alive (`0x68`, 36 bytes).
+ *
+ * Verified byte-for-byte against the real iOS Stagehand app unicasting to a
+ * CDJ-3000 at ~2-4 Hz. Body (offsets 30-35) is `03 01 00 3a 00 00`: `0x03`
+ * persona/channel, `0x01` device subkind, `0x00` flag, `0x3a` Stagehand
+ * model-code stamp, two reserved bytes. Constant across every observed sample.
+ */
+function makeStagehandPlayerHeartbeat(vcdj) {
+    const parts = [
+        ...constants_1.PROLINK_HEADER, // 0-9: magic
+        0x68, // 10: type 0x68 (player keep-alive)
+        ...buildUnicastName(vcdj.name), // 11-29: name (19 bytes)
+        0x03,
+        0x01,
+        0x00,
+        0x3a,
+        0x00,
+        0x00, // 30-35: constant body
+    ];
+    return Uint8Array.from(parts);
+}
+/**
+ * Unicasts Stagehand keep-alive frames to every discovered player and mixer so
+ * that AlphaTheta hardware begins (and keeps) pushing live state to our IP.
+ *
+ * The {@link StagehandAnnouncer} makes us *visible* on the network via subnet
+ * broadcast; this heartbeat is what makes hardware actually *talk back*. It
+ * targets the mixer with `0x3a` and each CDJ with `0x68`, mirroring the real
+ * iOS Stagehand app. Frames are sent from the status socket (port 50002) to
+ * each device's port 50002, which is where their unicast state replies land and
+ * where {@link StatusEmitter} listens for them.
+ */
+class StagehandHeartbeat {
+    constructor(vcdj, statusSocket, deviceManager, logger = logger_1.noopLogger) {
+        _StagehandHeartbeat_instances.add(this);
+        _StagehandHeartbeat_statusSocket.set(this, void 0);
+        _StagehandHeartbeat_vcdj.set(this, void 0);
+        _StagehandHeartbeat_deviceManager.set(this, void 0);
+        _StagehandHeartbeat_logger.set(this, void 0);
+        _StagehandHeartbeat_intervalHandle.set(this, void 0);
+        __classPrivateFieldSet(this, _StagehandHeartbeat_vcdj, vcdj, "f");
+        __classPrivateFieldSet(this, _StagehandHeartbeat_statusSocket, statusSocket, "f");
+        __classPrivateFieldSet(this, _StagehandHeartbeat_deviceManager, deviceManager, "f");
+        __classPrivateFieldSet(this, _StagehandHeartbeat_logger, logger, "f");
+    }
+    start() {
+        if (__classPrivateFieldGet(this, _StagehandHeartbeat_intervalHandle, "f") !== undefined) {
+            return;
+        }
+        __classPrivateFieldGet(this, _StagehandHeartbeat_logger, "f").info('Starting Stagehand heartbeat (unicast keep-alive)');
+        __classPrivateFieldGet(this, _StagehandHeartbeat_instances, "m", _StagehandHeartbeat_sendHeartbeats).call(this);
+        __classPrivateFieldSet(this, _StagehandHeartbeat_intervalHandle, setInterval(() => __classPrivateFieldGet(this, _StagehandHeartbeat_instances, "m", _StagehandHeartbeat_sendHeartbeats).call(this), exports.STAGEHAND_HEARTBEAT_INTERVAL), "f");
+    }
+    stop() {
+        __classPrivateFieldGet(this, _StagehandHeartbeat_logger, "f").info('Stopping Stagehand heartbeat');
+        if (__classPrivateFieldGet(this, _StagehandHeartbeat_intervalHandle, "f") !== undefined) {
+            clearInterval(__classPrivateFieldGet(this, _StagehandHeartbeat_intervalHandle, "f"));
+            __classPrivateFieldSet(this, _StagehandHeartbeat_intervalHandle, undefined, "f");
+        }
+    }
+}
+exports.StagehandHeartbeat = StagehandHeartbeat;
+_StagehandHeartbeat_statusSocket = new WeakMap(), _StagehandHeartbeat_vcdj = new WeakMap(), _StagehandHeartbeat_deviceManager = new WeakMap(), _StagehandHeartbeat_logger = new WeakMap(), _StagehandHeartbeat_intervalHandle = new WeakMap(), _StagehandHeartbeat_instances = new WeakSet(), _StagehandHeartbeat_sendHeartbeats = function _StagehandHeartbeat_sendHeartbeats() {
+    for (const device of __classPrivateFieldGet(this, _StagehandHeartbeat_deviceManager, "f").devices.values()) {
+        // Never heartbeat ourselves.
+        if (device.id === __classPrivateFieldGet(this, _StagehandHeartbeat_vcdj, "f").id) {
+            continue;
+        }
+        let packet = null;
+        switch (device.type) {
+            case types_1.DeviceType.Mixer:
+                packet = makeStagehandMixerHeartbeat(__classPrivateFieldGet(this, _StagehandHeartbeat_vcdj, "f"));
+                break;
+            case types_1.DeviceType.CDJ:
+                packet = makeStagehandPlayerHeartbeat(__classPrivateFieldGet(this, _StagehandHeartbeat_vcdj, "f"));
+                break;
+            default:
+                // Rekordbox / other Stagehand peers are not heartbeat targets.
+                continue;
+        }
+        __classPrivateFieldGet(this, _StagehandHeartbeat_statusSocket, "f").send(packet, constants_1.STATUS_PORT, device.ip.address, err => {
+            if (err) {
+                __classPrivateFieldGet(this, _StagehandHeartbeat_logger, "f").debug(`Stagehand heartbeat to ${device.name} (${device.ip.address}) failed: ${err.message}`);
+            }
+        });
+    }
+};
 
 
 /***/ },
@@ -13573,16 +13973,16 @@ _Announcer_announceSocket = new WeakMap(), _Announcer_deviceManager = new WeakMa
 }, _Announcer_handleConflict = function _Announcer_handleConflict() {
     // Stop announcing under the contested ID
     __classPrivateFieldGet(this, _Announcer_instances, "m", _Announcer_clearTimer).call(this);
-    // Stay in whichever range we were already in. Dropping out of 1-6 would
-    // silently lose remotedb metadata for unanalyzed and streaming tracks, so
-    // a conflict on player 5 looks for another free player number first.
+    // Stay in whichever range we were already in, so a conflict on player 5
+    // looks for another free player number first rather than jumping the
+    // whole device out of the range the DJ configured it into.
     //
     // The mixer decides which of those numbers are actually safe: a player can
     // only be assigned a number its mixer has a channel for, so anything above
     // that is out of reach of the rig that just contested us.
     const devices = [...__classPrivateFieldGet(this, _Announcer_deviceManager, "f").devices.values()];
     const newId = (0, device_id_1.pickAvailableDeviceId)(devices.map(d => d.id), {
-        preferRemoteDb: __classPrivateFieldGet(this, _Announcer_vcdj, "f").id <= device_id_1.REMOTEDB_MAX_DEVICE_ID,
+        preferPlayerRange: __classPrivateFieldGet(this, _Announcer_vcdj, "f").id <= device_id_1.REMOTEDB_MAX_DEVICE_ID,
         playerCeiling: (0, device_id_1.playerNumberCeiling)(devices),
     });
     if (newId === null) {
@@ -13685,6 +14085,7 @@ _Announcer_announceSocket = new WeakMap(), _Announcer_deviceManager = new WeakMa
     __classPrivateFieldSet(this, _Announcer_intervalHandle, setInterval(sendKeepAlive, constants_1.ANNOUNCE_INTERVAL), "f");
 };
 __exportStar(__webpack_require__(/*! ./device-id */ "./src/virtualcdj/device-id.ts"), exports);
+__exportStar(__webpack_require__(/*! ./heartbeat */ "./src/virtualcdj/heartbeat.ts"), exports);
 __exportStar(__webpack_require__(/*! ./stagehand */ "./src/virtualcdj/stagehand.ts"), exports);