alphatheta-connect 0.27.0 → 0.28.0

package/README.md

@@ -23,22 +23,22 @@ Alternative implementations of the Prolink protocol: [Java](https://github.com/D
 
 ## Features
 
-- **Streaming Service Detection** *(new)* - Detect when tracks are loaded from
+- **Streaming Service Detection** _(new)_ - Detect when tracks are loaded from
   streaming services (Beatport, Streaming Direct Play, TIDAL, Apple Music) via
   `MediaSlot` enum. Supports CDJ-3000X CloudDirectPlay streaming features.
 
-- **Support for AlphaTheta Opus Quad, XDJ-RX3, XDJ-RX2, XDJ-RX, and XDJ-XZ** *(new)* -
+- **Support for AlphaTheta Opus Quad, XDJ-RX3, XDJ-RX2, XDJ-RX, and XDJ-XZ** _(new)_ -
   Passive mode monitoring via pcap-based packet capture for all-in-one controllers
   where traditional virtual CDJ connection isn't possible.
   See [ALL_IN_ONE_UNITS.md](docs/ALL_IN_ONE_UNITS.md) for details.
 
-- **Pioneer Stagehand Connection Mode** *(new)* - Actively join the Pro DJ Link
+- **Pioneer Stagehand Connection Mode** _(new)_ - Actively join the Pro DJ Link
   network as a virtual Stagehand iPad device. Access rich, high-frequency telemetry
   events (mixer faders, EQ values, high-frequency VU level samples) and direct remote
   control over CDJs (play, pause, seek, track skip, preference writes like On-Air).
   See [STAGEHAND.md](docs/STAGEHAND.md) for details.
 
-- **OneLibrary Support** *(new)* - Full support for rekordbox 7.x's new OneLibrary
+- **OneLibrary Support** _(new)_ - Full support for rekordbox 7.x's new OneLibrary
   format (exportLibrary.db) with SQLCipher encryption, including tracks, playlists,
   cues, hot cue banks, myTags, and history.
 
@@ -56,15 +56,15 @@ Alternative implementations of the Prolink protocol: [Java](https://github.com/D
   sequence for better compatibility with certain device configurations.
   See [FULL_STARTUP.md](docs/FULL_STARTUP.md) for details.
 
-- **Metadata Extraction via NFS** *(new)* - Extract complete track metadata (title,
+- **Metadata Extraction via NFS** _(new)_ - Extract complete track metadata (title,
   artist, album, BPM, key, artwork) directly from audio files on connected media
   using partial file reads — only file headers are downloaded, not entire files.
 
-- **3-Band Waveforms & Vocal Detection** *(new)* - Parse `.2EX` analysis files for
+- **3-Band Waveforms & Vocal Detection** _(new)_ - Parse `.2EX` analysis files for
   3-band color waveform preview (PWV6), 3-band color detail waveform (PWV7), and
   vocal detection config (PWVC).
 
-- **Track Analysis API** *(new)* - Unified `getTrackAnalysis()` method that retrieves
+- **Track Analysis API** _(new)_ - Unified `getTrackAnalysis()` method that retrieves
   all analysis data (extended cues, song structure, waveforms, 3-band waveforms,
   vocal config) from both EXT and 2EX files in a single call.
 
@@ -74,6 +74,8 @@ Alternative implementations of the Prolink protocol: [Java](https://github.com/D
   - Multiple waveform formats (PWAV, PWV2, PWV3, PWV4, PWV5, PWV6, PWV7)
   - Vocal detection config (PWVC)
   - See [EXTENDED_ANLZ.md](docs/EXTENDED_ANLZ.md) for details
+  - See [USB_EXPORT.md](docs/USB_EXPORT.md) for complete USB format tables,
+    analysis paths, cue palettes, OneLibrary schema and reader limitations
 
 - **CDJ-3000 Features** - Complete support for CDJ-3000 specific features:
   - Absolute position tracking (30ms updates)

package/lib/cli.js

@@ -1443,13 +1443,51 @@ async function viaLocal(local, device, opts) {
 "use strict";
 
 Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.describeBlankMetadata = describeBlankMetadata;
 exports.viaRemote = viaRemote;
 exports.viaLocal = viaLocal;
 const rekordbox_1 = __webpack_require__(/*! src/localdb/rekordbox */ "./src/localdb/rekordbox.ts");
+const logger_1 = __webpack_require__(/*! src/logger */ "./src/logger.ts");
 const remotedb_1 = __webpack_require__(/*! src/remotedb */ "./src/remotedb/index.ts");
 const types_1 = __webpack_require__(/*! src/types */ "./src/types.ts");
-const utils_1 = __webpack_require__(/*! ./utils */ "./src/db/utils.ts");
-async function viaRemote(remote, opts) {
+const utils_1 = __webpack_require__(/*! src/utils */ "./src/utils/index.ts");
+const utils_2 = __webpack_require__(/*! ./utils */ "./src/db/utils.ts");
+/**
+ * The longest a single item is allowed to run in a blank-metadata report, so
+ * one oversized field cannot swamp the log line.
+ */
+const MAX_ITEM_REPORT_LENGTH = 200;
+/**
+ * Explain a remote lookup that came back with neither a title nor an artist:
+ * what the player was asked, how many items it sent, and each item's type and
+ * fields as they arrived. A player that files a track under an unfamiliar slot
+ * can answer this way (NP3-416), and without the raw items there is no telling
+ * an empty answer from one we do not know how to read.
+ */
+function describeBlankMetadata(opts, response, trackInfo) {
+    var _a, _b, _c;
+    const { deviceId, trackSlot, trackType, trackId } = opts;
+    const slotName = (_a = (0, utils_1.getSlotName)(trackSlot)) !== null && _a !== void 0 ? _a : 'unknown';
+    const typeName = (_b = (0, utils_1.getTrackTypeName)(trackType)) !== null && _b !== void 0 ? _b : 'unknown';
+    const itemReports = ((_c = response === null || response === void 0 ? void 0 : response.items) !== null && _c !== void 0 ? _c : []).map(({ type, ...fields }) => {
+        const hex = `0x${type.toString(16).padStart(4, '0')}`;
+        const report = `${hex} ${JSON.stringify(fields)}`;
+        return report.length > MAX_ITEM_REPORT_LENGTH
+            ? `${report.slice(0, MAX_ITEM_REPORT_LENGTH)}…`
+            : report;
+    });
+    const items = response === null
+        ? 'no response recorded'
+        : [
+            `${response.items.length} of ${response.itemsAvailable} item(s) received`,
+            ...itemReports,
+        ].join('; ');
+    return (`Device ${deviceId} answered the metadata query for track ${trackId} ` +
+        `(slot ${trackSlot} ${slotName}, type ${trackType} ${typeName}) with no ` +
+        `title or artist: ${items}; track info: ${trackInfo}`);
+}
+async function viaRemote(remote, opts, logger = logger_1.noopLogger) {
+    var _a, _b, _c;
     const { deviceId, trackSlot, trackType, trackId, span } = opts;
     const conn = await remote.get(deviceId);
     if (conn === null) {
@@ -1465,14 +1503,23 @@ async function viaRemote(remote, opts) {
     const skipLocalFileLookups = isUnanalyzed || isStreaming;
     // Unanalyzed tracks use GetGenericMetadata (reads ID3 tags from the audio file).
     // Streaming tracks (Beatport) use the regular GetMetadata query.
-    const track = await conn.query({
-        queryDescriptor,
-        query: isUnanalyzed ? remotedb_1.Query.GetGenericMetadata : remotedb_1.Query.GetMetadata,
-        args: { trackId },
-        span,
-    });
+    let response = null;
+    const track = isUnanalyzed
+        ? await conn.query({
+            queryDescriptor,
+            query: remotedb_1.Query.GetGenericMetadata,
+            args: { trackId },
+            span,
+        })
+        : await conn.query({
+            queryDescriptor,
+            query: remotedb_1.Query.GetMetadata,
+            args: { trackId, onResponse: r => (response = r) },
+            span,
+        });
     // Try to get file path — for streaming tracks this returns the Beatport track ID
     // (e.g. "/26883657.m4a") which we use for Beatport API lookups
+    let trackInfoError = null;
     try {
         track.filePath = await conn.query({
             queryDescriptor,
@@ -1485,6 +1532,13 @@ async function viaRemote(remote, opts) {
         if (!skipLocalFileLookups) {
             throw err;
         }
+        trackInfoError = err instanceof Error ? err.message : String(err);
+    }
+    if (!((_a = track.title) === null || _a === void 0 ? void 0 : _a.trim()) && !((_c = (_b = track.artist) === null || _b === void 0 ? void 0 : _b.name) === null || _c === void 0 ? void 0 : _c.trim())) {
+        const trackInfo = trackInfoError === null
+            ? JSON.stringify(track.filePath)
+            : `failed (${trackInfoError})`;
+        logger.warn(describeBlankMetadata(opts, response, trackInfo));
     }
     // Beat grid is only available for analyzed local tracks
     if (!skipLocalFileLookups) {
@@ -1509,7 +1563,7 @@ async function viaLocal(local, device, opts) {
     if (lookup.track === null) {
         return { track: null, miss: 'track-absent', switchedTo: null };
     }
-    const anlz = await (0, rekordbox_1.loadAnlz)(lookup.track, 'DAT', (0, utils_1.anlzLoader)({ device, slot: trackSlot }));
+    const anlz = await (0, rekordbox_1.loadAnlz)(lookup.track, 'DAT', (0, utils_2.anlzLoader)({ device, slot: trackSlot }));
     const track = {
         ...lookup.track,
         beatGrid: anlz.beatGrid,
@@ -1857,7 +1911,7 @@ class Database {
         const strategy = __classPrivateFieldGet(this, _Database_getTrackLookupStrategy, "f").call(this, device, trackType);
         let track = null;
         if (strategy === LookupStrategy.Remote) {
-            track = await GetMetadata.viaRemote(__classPrivateFieldGet(this, _Database_remoteDatabase, "f"), callOpts);
+            track = await GetMetadata.viaRemote(__classPrivateFieldGet(this, _Database_remoteDatabase, "f"), callOpts, __classPrivateFieldGet(this, _Database_logger, "f"));
         }
         if (strategy === LookupStrategy.Local) {
             const local = await GetMetadata.viaLocal(__classPrivateFieldGet(this, _Database_localDatabase, "f"), device, callOpts);
@@ -2084,7 +2138,7 @@ _Database_deviceManager = new WeakMap(), _Database_localDatabase = new WeakMap()
  */
 async function _Database_metadataViaRemoteFallback(opts) {
     try {
-        const track = await GetMetadata.viaRemote(__classPrivateFieldGet(this, _Database_remoteDatabase, "f"), opts);
+        const track = await GetMetadata.viaRemote(__classPrivateFieldGet(this, _Database_remoteDatabase, "f"), opts, __classPrivateFieldGet(this, _Database_logger, "f"));
         if (track === null) {
             __classPrivateFieldGet(this, _Database_logger, "f").warn(`Remote fallback found no track ${opts.trackId} on device ${opts.deviceId}`);
             return null;
@@ -9373,8 +9427,8 @@ const transformItem = {
     [ItemType.Rating]: (a) => ({ rating: a.mainId }),
     [ItemType.Tempo]: (a) => ({ bpm: a.mainId / 100 }),
     [ItemType.Duration]: (a) => ({ duration: a.mainId }),
-    [ItemType.Unknown01]: (_) => null,
-    [ItemType.Unknown02]: (_) => null,
+    [ItemType.Unknown01]: (a) => a,
+    [ItemType.Unknown02]: (a) => a,
     [ItemType.ColorNone]: mapIdName,
     [ItemType.ColorPink]: mapIdName,
     [ItemType.ColorRed]: mapIdName,
@@ -9435,9 +9489,10 @@ const fieldsToItem = (args) => {
     const { type } = itemData;
     let transformer = transformItem[type];
     // Typescript gives us safety, but it is possible there is an itemType we're
-    // not aware of yet.
+    // not aware of yet. Keep its raw fields so whoever reads the response can
+    // still see what the player sent.
     if (transformer === undefined) {
-        transformer = () => null;
+        transformer = (a) => a;
         Telemetry.captureMessage(`No item transformer registered for item type ${type}`, Telemetry.Severity.Error);
     }
     return { ...transformer(itemData), type };
@@ -9759,7 +9814,7 @@ const utils_1 = __webpack_require__(/*! ./utils */ "./src/remotedb/utils.ts");
 async function getMetadata(opts) {
     var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z;
     const { conn, lookupDescriptor, span, args } = opts;
-    const { trackId } = args;
+    const { trackId, onResponse } = args;
     const request = new message_1.Message({
         type: types_1.Request.GetMetadata,
         args: [(0, utils_1.fieldFromDescriptor)(lookupDescriptor), new fields_1.UInt32(trackId)],
@@ -9770,9 +9825,12 @@ async function getMetadata(opts) {
     // NOTE: We do a bit of any-ing here to help typescript understand we're
     // discriminating the type by our object key
     const trackItems = {};
+    const received = [];
     for await (const item of items) {
         trackItems[item.type] = item;
+        received.push(item);
     }
+    onResponse === null || onResponse === void 0 ? void 0 : onResponse({ itemsAvailable: resp.data.itemsAvailable, items: received });
     // Translate our trackItems into a (partial) Track entity.
     // Use optional chaining for all fields since streaming tracks may omit some.
     const track = {
@@ -9974,7 +10032,11 @@ async function getTrackInfo(opts) {
     for await (const item of items) {
         infoItems[item.type] = item;
     }
-    return infoItems[item_1.ItemType.Path].path;
+    const path = infoItems[item_1.ItemType.Path];
+    if (path === undefined) {
+        throw new Error(`Player sent no file path (${resp.data.itemsAvailable} item(s) available)`);
+    }
+    return path.path;
 }
 /**
  * Lookup playlist entries