MBXHub

List all images in the track's album folder and one level of subfolders. Returns folder path, image paths, and count. Excludes: canonical primary-cover filenames (folder.jpg, cover.jpg, front.jpg, album.jpg + .jpeg/.png siblings — these are duplicates of the primary artwork served by /artwork); all Windows Media Player cache files (AlbumArtSmall*, AlbumArt_*); thumbnail artifacts (<5KB); Thumbs.db; desktop.ini.

Security: track must be in the MusicBee library.

Serve a single fan art image by absolute path (binary). Returns image with appropriate content-type. Cache-Control: max-age=3600.

Security: image must reside in a directory that contains at least one MusicBee library file.

Get current party state (active, request count).

Start a party session.

// Request body:
{"guestPin": "1234", "djPin": "5678"}
// djPin is optional - defaults to guestPin

End the current party session.

Validate PIN and get role. If nickname provided, announces join in feed.

// Response:
{"success": true, "data": {"valid": true, "role": "guest"}}
// role: "guest" or "dj"

Verify if a PIN grants DJ access. Used by DJ page login.

// Request body:
{"pin": "5678"}
// Response:
{"success": true, "data": {"valid": true}}
// valid is true only if PIN matches DJ PIN

Submit a vote (thumbs up/down) with guest attribution. Records in feed and forwards to influences if AutoQ available.

// Request body:
{"type": "++", "target": "Artist", "value": "Daft Punk", "nickname": "Haro"}
// type: "++"=more, "--"=less; target: "Artist" or "Genre"

Submit a song request (adds to queue).

// Request body:
{"url": "C:\\Music\\song.mp3", "nickname": "Haro"}
// Response includes requestId, title, artist

Get party feed (joins, requests, votes, reactions - newest first).

// Response:
{"success": true, "data": {
  "items": [
    {"type": "join", "nickname": "Haro", "timestamp": "..."},
    {"type": "request", "nickname": "Haro", "title": "Song", "artist": "Artist", "timestamp": "..."},
    {"type": "voteup", "nickname": "Haro", "artist": "Daft Punk", "timestamp": "..."},
    {"type": "votedown", "nickname": "Haro", "artist": "Nickelback", "timestamp": "..."},
    {"type": "reaction", "nickname": "Haro", "emoji": "🔥", "title": "Song", "artist": "Artist", "timestamp": "..."}
  ]
}}

Get recent song requests only (for DJ page).

Generate QR code PNG image. Auto-includes PIN if party is active.

Returns the caller's role based on IP: host (loopback), dj (verified DJ PIN), or guest.

Get AutoQ status and configuration.

// Response:
{
  "success": true,
  "data": {
    "enabled": true,
    "mode": "autopilot",
    "soloMode": false,
    "vibeListCount": 10,
    "vibeListPreview": [
      { "title": "Uptown Funk", "artist": "Mark Ronson", "score": 12.5 }
    ]
  }
}

Start AutoQ. Begins monitoring queue and adding tracks when needed.

// Optional request body:
{ "mode": "autopilot" }
// Modes: "autopilot" (default), "djassist" (aliases: "dj", "assist", "auto")

Stop AutoQ. Queue continues playing but no new tracks are added automatically.

Reset AutoQ session state (clears reactions, taste vector, ban list). DJ-only in party mode.

Force refresh vibe list. Returns updated track count.

// Response:
{
  "success": true,
  "data": { "message": "Vibe list refreshed", "count": 100 }
}

Pick the next track from the vibe list without queueing it.

// Response:
{
  "success": true,
  "data": { "url": "C:\\Music\\track.mp3", "title": "Uptown Funk", "artist": "Mark Ronson" }
}

Unban a track, allowing it back into the vibe list.

// Request:
{ "url": "C:\\Music\\track.mp3" }

// Response:
{
  "success": true,
  "data": { "result": true, "url": "C:\\Music\\track.mp3" }
}

Check if the currently playing track is banned.

// Response:
{
  "success": true,
  "data": { "url": "C:\\Music\\track.mp3", "isBanned": false }
}

Get available mood channels with arousal/valence coordinates. Channels are customizable via autoQ.moodChannels in mbxhub.json.

// Response:
{
  "success": true,
  "data": {
    "currentMood": "Energetic",
    "channels": [
      { "name": "Energetic", "emoji": "🔥", "arousal": 0.90, "valence": 0.80 },
      { "name": "Chill", "emoji": "😌", "arousal": 0.35, "valence": 0.65 }
    ]
  }
}

Browse tracks matching a mood channel. Returns scored tracks sorted by mood similarity.

// GET /autoq/moods/browse?channel=Energetic&limit=50
// Response:
{
  "success": true,
  "data": {
    "channel": "Energetic",
    "emoji": "🔥",
    "total": 50,
    "tracks": [
      { "url": "...", "title": "...", "artist": "...", "album": "...", "trackNo": "3", "moodMatch": 0.92 }
    ]
  }
}

Raw mood data for the current track (or any track via ?url=). Returns file, album, Essentia features, percentile ranks, computed valence/arousal, and best mood channel match.

// Response (Essentia-analyzed track):
{
  "success": true,
  "data": {
    "file": "C:\\Music\\Artist\\Album\\Track.mp3",
    "album": "Album",
    "valence": 0.5003,
    "arousal": 0.5794,
    "source": "essentia",
    "hasEssentiaData": true,
    "moodChannel": "Upbeat",
    "moodEmoji": "😊",
    "raw": {
      "bpm": 119.95,
      "mode": "major",
      "loudness": -10.23,
      "spectralCentroid": 1284.56,
      "spectralFlux": 0.000342,
      "spectralRms": 0.001245,
      "spectralFlatness": 0.000089,
      "danceability": 1.45,
      "onsetRate": 2.87,
      "zeroCrossingRate": 0.058,
      "dissonance": 0.4123,
      "pitchSalience": 0.3856,
      "chordsChangesRate": 0.0312,
      "mfcc": 142.56
    },
    "percentiles": {
      "bpm": 0.52, "loudness": 0.61, "centroid": 0.48,
      "flux": 0.35, "dance": 0.67, "onset": 0.55,
      "zcr": 0.42, "rms": 0.58, "dissonance": 0.44,
      "salience": 0.39, "chords": 0.51, "mfcc": 0.63
    },
    "confidence": 0.82,
    "confidenceLabel": "high",
    "genreProfile": "electronic"
  }
}

// Response (fallback — no Essentia data):
{
  "success": true,
  "data": {
    "file": "C:\\Music\\Artist\\Album\\Track.mp3",
    "album": "Album",
    "valence": 0.65,
    "arousal": 0.70,
    "source": "fallback",
    "hasEssentiaData": false,
    "moodChannel": "Energetic",
    "moodEmoji": "🔥",
    "confidence": 0.45,
    "confidenceLabel": "medium",
    "genreProfile": null
  }
}

Set target mood for Mood mode. Pass empty channel to disable mood mode.

// Request:
{ "channel": "Energetic" }

// Response:
{
  "success": true,
  "data": {
    "message": "Mood set to Energetic",
    "mode": "mood",
    "mood": { "name": "Energetic", "emoji": "🔥", "arousal": 0.90, "valence": 0.80 }
  }
}

Reload the mood channel cache from disk (re-reads Essentia data).

MetaServer mood-cache warm-up visibility. Returns current cache totals plus the most recent warm-up summary. lastWarmup is null when no warm-up has run yet (e.g. MetaServer disabled). For push updates, subscribe to the MoodCacheWarmed WebSocket event instead of polling.

// Response:
{
  "success": true,
  "data": {
    "total": 12480,
    "essentia": 9812,
    "fallback": 2668,
    "warmupInProgress": false,
    "lastWarmup": {
      "at": "2026-04-18T00:15:42Z",
      "ran": true,
      "skipReason": null,
      "librarySize": 12480,
      "fromLocalFile": 0,
      "fromMetaServer": 9812,
      "stillMissing": 2668,
      "durationMs": 1843
    }
  }
}

Bulk write mood tags to a MusicBee custom field. Only processes Essentia-analyzed tracks. Requires autoQ.moodTagField to be configured (e.g. "Custom1").

// Response:
{
  "success": true,
  "data": { "updated": 342 }
}

Get current vibe list (candidate tracks with scores). Query: ?count=50

// Response:
{
  "success": true,
  "data": {
    "count": 50,
    "tracks": [
      {
        "url": "C:\\Music\\track.mp3",
        "title": "Uptown Funk",
        "artist": "Mark Ronson",
        "genre": "Funk",
        "score": 12.5
      }
    ]
  }
}

Discover tracks adjacent to the current taste profile, grouped by category. Query: ?limit=100&groupBy=auto|genre|artist|mood

// Response:
{
  "success": true,
  "data": {
    "profile": {
      "topGenres": [{ "name": "Rock", "weight": 1.0 }],
      "topArtists": [{ "name": "Foo Fighters", "weight": 0.85 }],
      "bpmRange": [90, 160],
      "mood": "Energetic",
      "influenceCount": 3,
      "reactionCount": 12
    },
    "groupBy": "genre",
    "groups": [{
      "label": "Rock",
      "reason": "genre",
      "count": 15,
      "tracks": [{
        "url": "C:\\Music\\track.mp3",
        "title": "Everlong",
        "artist": "Foo Fighters",
        "genre": "Rock",
        "score": 8.2,
        "reasons": ["genre match", "artist match"]
      }]
    }],
    "total": 45
  }
}

Find tracks similar to a seed track by metadata and feature distance. Query: ?url={trackUrl}&limit=20

// Response:
{
  "success": true,
  "data": {
    "seed": {
      "url": "C:\\Music\\seed.mp3",
      "title": "Everlong",
      "artist": "Foo Fighters",
      "genre": "Rock"
    },
    "tracks": [{
      "url": "C:\\Music\\similar.mp3",
      "title": "Learn to Fly",
      "artist": "Foo Fighters",
      "genre": "Rock",
      "similarity": 0.6,
      "reasons": ["same genre", "same artist", "similar BPM"]
    }]
  }
}

Submit a reaction for a track. Reactions appear as floating emojis on the Display page.

// Request body (always reacts to currently playing track):
{
  "emoji": "🔥",
  "nickname": "Mike"
}
// emoji: "🔥", "❤️", "👍", "👎", "🚫" or "fire", "heart", "like", "dislike", "ban"

// Response:
{
  "success": true,
  "data": {
    "recorded": true,
    "emoji": "🔥",
    "trackUrl": "C:\\Music\\track.mp3",
    "trackTitle": "Uptown Funk",
    "trackArtist": "Mark Ronson",
    "nickname": "Mike"
  }
}

Get reaction history. Query: ?trackUrl= for specific track, ?limit=100

// Response:
{
  "success": true,
  "data": {
    "count": 25,
    "trackUrl": null,
    "reactions": [
      {
        "emoji": "🔥",
        "type": "fire",
        "trackUrl": "C:\\Music\\track.mp3",
        "trackTitle": "Uptown Funk",
        "trackArtist": "Mark Ronson",
        "nickname": "Haro",
        "timestamp": "2026-02-01T20:45:00Z"
      }
    ]
  }
}

Get party leaderboard data: guest activity, top tracks, reaction breakdown.

// Response:
{
  "success": true,
  "data": {
    "totalReactions": 156,
    "topTracks": [
      { "url": "...", "title": "Uptown Funk", "artist": "Mark Ronson", "score": 15 }
    ],
    "guests": [
      { "nickname": "Haro", "totalReactions": 42, "fire": 10, "heart": 15, "like": 12, "dislike": 3, "ban": 2 }
    ]
  }
}

Get all tunable AutoQ parameters: scoring weights, reaction scores, influence scores, estimation weights, and normalization ranges. Use with Tuning Console.

Partial update of AutoQ parameters. Only provided fields are changed. Changes take effect on the next scoring pass — no restart needed. Nested objects are merged, not replaced.

// Example: change just the BPM arousal weight
PUT /autoq/settings
{"estimation": {"arousalWeightBpm": 0.30}}

Full system health. Returns shell version, service status, feature readiness, tool discovery results, MetaServer database state, peer sync state, and scan queue depth. Tool entries include path and version when found, or searchedPaths when not found. Scan section includes mode, batchSize, healthy, and queueDepth.

Response: {
  "status": "ok", "version": "1.0", "database": "ready",
  "nodeId": "mbxhub-DF60-8080", "name": "PANDABOX",
  "core": { "shellVersion": "0.5.2.4", "uptime": "00:05:32", "pluginConnected": true },
  "services": { "metaServer": "running", "metaPort": 8081, "trackCount": 68500 },
  "features": { "scan": "ready", "peerSync": "enabled" },
  "scan": { "mode": "auto", "batchSize": 1, "healthy": true, "queueDepth": 3 },
  "tools": {
    "truedat": { "status": "found", "path": "C:\\...\\truedat.exe", "version": "1.2.0" },
    "ffmpeg":  { "status": "not_found", "searchedPaths": ["C:\\...\\ffmpeg.exe", "..."] },
    "essentia": { "status": "found", "path": "C:\\...\\streaming_extractor_music.exe" }
  }
}

Re-run tool discovery and refresh health status. No request body needed.

Response: { "status": "ok", "message": "Discovery refreshed" }

Node capabilities for cross-instance SSDP discovery. Used by PeerSync and the plugin to identify what this Shell instance offers. Capabilities include meta-server, scanner (if Truedat/Essentia found), smtc, and peer-sync. Also returns scan details: mode, batchSize, healthy, queueDepth.

Response: {
  "node": "shell", "version": "0.5.2.4.0",
  "capabilities": ["meta-server", "scanner", "smtc", "peer-sync"],
  "endpoints": { "meta": "http://pandabox:8081" },
  "scan": { "mode": "auto", "batchSize": 1, "healthy": true, "queueDepth": 0 }
}

Database statistics: track counts, mood feature coverage by source, identity signal counts, average confidence, database size, and last import info. The bySource dictionary keys depend on what's ingested your DB: essentia (Truedat scan), essentia-local (older Truedat), peer-sync (federated from another MBXHub), ab-catalog (AcousticBrainz import), metadata-match (identity-only record, no features). Clients should sum any non-peer-sync + non-ab-catalog keys for a “local-scan” rollup.

Response: {
  "success": true,
  "data": {
    "totalTracks": 72115,
    "withMoodFeatures": 70881,
    "bySource": { "essentia": 609, "peer-sync": 70272 },
    "identitySignals": { "audioMd5": 0, "chromaprint": 0, "metadataKey": 70271 },
    "averageConfidence": 0.95,
    "databaseSizeMb": 155.2,
    "lastImport": { "source": "mbxmoods.json", "completedAt": "2026-04-18T12:05:00Z", "tracksImported": 609 }
  }
}

Snapshot of pending ScanWorker items in priority order. Operator visibility — Fleet panel consumes this via the /system/fleet/queue proxy. Returns 200 with empty array when the worker is absent or idle; never 503 (“no worker” and “empty queue” render the same way). limit default 20, max 100.

Response: {
  "workerStarted": true, "queueDepth": 147, "returned": 20,
  "items": [
    { "file": "C:\\Music\\A\\1.mp3", "basename": "1.mp3", "share": null, "priority": "high" },
    { "file": "C:\\Music\\A\\2.mp3", "basename": "2.mp3", "share": "\\\\NAS\\Music", "priority": "normal" }
  ]
}

Recent scan start/complete/failed events newer than since. 200-event ring buffer with monotonic sequence cursor; clients advance since = currentSeq each poll to receive only new events. First poll with since=0 seeds the cursor AND returns the last N events. limit default 50, max 200. Each event includes dispatchedTo (Environment.MachineName of the executing worker) so fleet-aggregated feeds show which node actually ran each scan. Proxied plugin-side via /system/fleet/activity.

Response: {
  "workerStarted": true, "currentSeq": 1847, "returned": 3,
  "events": [
    { "seq": 1845, "at": "2026-04-19T23:55:22Z", "kind": "complete", "file": "...", "basename": "1.mp3", "elapsedMs": 412, "error": null, "dispatchedTo": "ATOM" },
    { "seq": 1846, "at": "2026-04-19T23:55:23Z", "kind": "start",    "file": "...", "basename": "2.mp3", "dispatchedTo": "ZIGGY25" },
    { "seq": 1847, "at": "2026-04-19T23:55:26Z", "kind": "failed",   "file": "...", "basename": "3.mp3", "elapsedMs": 2103, "error": "truedat timeout", "dispatchedTo": "ZIGGY25" }
  ]
}

Returns current scan configuration keys. All keys are prefixed with scan. for namespace clarity. Does not require MetaServer database to be initialized.

Response: {
  "scan.mode": "auto",
  "scan.includeLocal": true,
  "scan.preferredUrl": null,
  "scan.batchSize": 1,
  "scan.cpuLimit": 25
}

Updates one or more scan config keys and persists to mbxhub-shell.json. Send only the keys you want to change. scan.mode accepts off, local, or auto. Unknown keys are returned in ignored.

Body: { "scan.mode": "local", "scan.batchSize": 4 }
Response: { "status": "ok", "applied": { "scan.mode": "local", "scan.batchSize": 4 } }

Returns SchemaEntry-format metadata for all Shell scan settings. Used by the settings UI to build dynamic config panels. Each entry includes key, type, category, tier (0=basic, 1=advanced), description, current, default, and optional min/max/options.

Response: {
  "settings": [
    { "key": "shell.scan.mode", "type": "string", "tier": 0,
       "description": "Scan mode: off disables scanning, local uses this machine, auto discovers peers",
       "current": "auto", "default": "auto", "options": ["off", "local", "auto"] },
    { "key": "shell.scan.includeLocal", "type": "bool", "tier": 0,
       "description": "Include this machine in the auto scanner pool",
       "current": true, "default": true },
    { "key": "shell.scan.preferredUrl", "type": "string", "tier": 0,
       "description": "Preferred remote scanner MetaServer URL (gets priority in auto mode)",
       "current": null, "default": null },
    { "key": "shell.scan.batchSize", "type": "int", "tier": 1,
       "current": 1, "default": 1, "min": 1, "max": 32 },
    { "key": "shell.scan.cpuLimit", "type": "int", "tier": 1,
       "current": 25, "default": 25, "min": 1, "max": 100 }
  ]
}

Single track mood feature lookup. Parameters: path, audioMd5, or metadata (artist+title+optional album+duration). Server walks the full identity chain in fall-through order: exact-path → path-tail → audioMd5 → metadataKey, regardless of which fields the caller supplied. Each query slot that fails moves on to the next; a single request can resolve a track even when only one identifier is present. Response features block carries the 15 base fields plus the 39 nullable extended-Essentia fields (loudnessMomentary, spectralRolloff, hfc, Bark/ERB/Mel band stats, etc.) — fields the original scan didn't capture stay null. Legacy peer-sync rows stored their metadataKey with duration=0; on metadata miss the server retries the lookup with duration=0, but only accepts the resulting candidate when its stored DurationSeconds is non-zero, which avoids 0.50-confidence false positives against placeholder rows.

Match response (200): {
  "success": true, "matched": true, "confidence": 0.95, "matchType": "audioMd5",
  "features": { "bpm": 128.0, "key": "C", "mode": "major", "danceability": 0.78, ... },
  "identity": { "mediaItemId": "a1b2c3d4-...", "source": "essentia-local", "analyzedAt": "2026-02-15T10:00:00Z" }
}

No match (200): { "success": true, "matched": false, "confidence": 0.0, "matchType": "none" }

Batch lookup, max 500 queries per request. Each query uses the same parameter options as the single lookup; the plugin's startup warm-up sends {path, artist, title, album, duration} for every track so the server can fall through to metadataKey for peer-sync rows whose synthetic peer://{bestId} path won't match. Returns results in the same order as queries; each result includes the 39 nullable extended fields when the matched row has them.

Body: {
  "queries": [
    { "path": "C:\\Music\\Artist\\Song.mp3", "artist": "Artist", "title": "Song", "album": "Album", "duration": 245 },
    { "audioMd5": "abc123..." },
    { "artist": "Artist", "title": "Song", "duration": 245 }
  ]
}
Response: { "success": true, "results": [...] }
Over 500: 400 { "error": { "code": "BATCH_TOO_LARGE" } }

Phase 2 bulk identity coverage probe. For each path, reports which identity signals are present (fingerprint.v1, audioStreamSha256) and whether features exist. Used by the plugin’s /scan/fingerprints sweep to find gaps without issuing N single-path queries. Limit: 500 paths per call.

Body: { "paths": ["C:\\Music\\A\\1.mp3", "C:\\Music\\A\\2.mp3"] }
Response: {
  "success": true,
  "coverage": [
    { "path": "C:\\Music\\A\\1.mp3", "known": true,  "hasFingerprint": true,  "hasStreamSha": false, "hasFeatures": true },
    { "path": "C:\\Music\\A\\2.mp3", "known": false, "hasFingerprint": false, "hasStreamSha": false, "hasFeatures": false }
  ]
}

Phase 2 ms-scale probe. Answers do you have this file? using only the cheap fingerprint.v1.audioHead64kMd5 (32-char hex, MD5 of the first 64 KB at TagLib InvariantStartPosition). A hit lets a caller short-circuit the expensive Essentia scan and pull features from this peer. Miss → 404 so the caller can fall through to the next peer or enqueue a local scan. Returns the sibling audioStreamSha256 (if this peer has one) so callers can escalate to the durable byte-identity tier when they want certainty.

Hit (200): { "match": true, "audioStreamSha256": "a4b9…" | null, "hasFeatures": true, "peerId": "PANDABOX" }
Miss (404): { "error": { "code": "NOT_FOUND" } }
Invalid (400): { "error": { "code": "BAD_REQUEST", "message": "audioHead must be 32-char hex" } }

Phase 2 fingerprint-keyed feature pull. Sibling of /meta/by-fingerprint — after that endpoint confirms a match, this one returns the full feature payload without needing the peer’s local path. matchType = fingerprint.v1, confidence 0.90. Miss → 404.

Hit (200): {
  "success": true, "matched": true, "matchType": "fingerprint.v1", "confidence": 0.90,
  "features": { "bpm": 128.0, "key": "C", ... },
  "identity": { "mediaItemId": "a1b2…", "source": "essentia", "analyzedAt": "2026-04-19T23:55:22Z" },
  "peerId": "PANDABOX"
}
Miss (404): { "error": { "code": "NOT_FOUND" } }

Phase 2 durable byte-identity feature pull. audioStreamSha256 is the SHA-256 of the metadata-stripped audio region (64-char hex). On hit, returns the full feature payload with matchType="audioStreamSha256" and confidence 0.99 — callers can ingest directly. Miss → 404.

Hit (200): {
  "success": true, "matched": true, "matchType": "audioStreamSha256", "confidence": 0.99,
  "features": { "bpm": 128.0, "key": "C", ... },
  "identity": { "mediaItemId": "a1b2…", "source": "essentia", "analyzedAt": "2026-04-19T23:55:22Z" },
  "peerId": "PANDABOX"
}
Miss (404): { "error": { "code": "NOT_FOUND" } }

Phase 2 paginated identity.fingerprint.v1.audioHead index dump. Used by joining peers and content-addressed dispatch to learn which tracks this node has cataloged. Filter by MediaItem.ImportedAt via ?since= (ISO 8601). limit default 500, max 5000. Paginate by feeding the returned next back as the new since until done:true. Skips synthetic peer:// paths.

Response: {
  "success": true, "signal": "fingerprint", "count": 500, "done": false, "next": "2026-04-19T23:55:22Z",
  "items": [{ "mediaItemId": "a1b2…", "path": "C:\\Music\\Song.mp3", "value": "abc123…", "importedAt": "2026-04-19T10:00:00Z" }, ...]
}

Phase 2 paginated identity.audioStreamSha256 index dump. Same shape as /meta/fingerprints, different key — the durable byte-identity tier.

Phase 2 one-pass convergence sweep. Walks local tracks that have identity.fingerprint.v1 but no MoodFeatures, runs peer-pull (/meta/by-fingerprint → /meta/features/by-fingerprint) against known peers, and merges any hits locally. Closes the loop between “identity cataloged” and “features present” without rescanning. Orders of magnitude cheaper than Essentia — safe to run on a schedule. 503 PEER_PULL_UNAVAILABLE if PeerSync is not active.

Query: ?limit=N        // default 500, max 5000
Response: { "success": true, "scanned": 71506, "pulled": 68211, "missed": 3295, "limit": 500 }

// Optional background scheduler in mbxhub-shell.json (off by default):
"meta": {
  "trueUp": {
    "enabled": true,
    "intervalMinutes": 60,   // floor clamped to 5 inside scheduler
    "batchLimit": 500        // clamped to [1, 5000]
  }
}

Scanner posts Essentia analysis results. Walks identity matching (hash → audioMd5 → metadataKey → new), creates or updates MediaItem + MusicDetails + MoodFeatures. Writes are serialized through a single-writer queue. Merge-on-ingest (v0.5.2.4+): when an existing row already has data, base scalar fields are first-write-wins (prevents stale rescans from clobbering good values), but any null extended feature is filled in from the new observation — so a peer rescan with the full 39-field Essentia output enriches earlier 15-field ingests without overwriting them.

Phase 2 hash-only modes: truedat --hash-only --level fingerprint|stream POSTs the same envelope with features omitted and at least one identity signal populated (fingerprint.v1 composite, audioStreamSha256, or both). The ingest is accepted; identity keys are persisted as identity.fingerprint.v1.* (8 sub-keys incl. audioHead, fileSize, pathTail, durationMs, sampleRate, channels, codec, bitrate) and identity.audioStreamSha256. No MoodFeatures row is created until a later scan produces features. This primes ms-scale peer probes (/meta/by-fingerprint) and byte-identity pulls (/meta/by-hash) without paying the Essentia cost up-front.

The features block accepts the 15 original fields (bpm, key, mode, spectralCentroid, spectralFlux, loudness, danceability, onsetRate, zeroCrossingRate, spectralRms, spectralFlatness, dissonance, pitchSalience, chordsChangesRate, mfcc) plus the 39-field extended block (v0.5.2.4+, all nullable): loudnessMomentary, loudnessShortTerm, dynamicRange (LRA in LU from Essentia loudness_ebu128.loudness_range), replayGain, silenceRate20dB, silenceRate30dB, silenceRate60dB, spectralRolloff, spectralComplexity, spectralEntropy, spectralKurtosis, spectralSkewness, spectralSpread, spectralStrongPeak, spectralDecrease, spectralEnergy, spectralEnergyLow, spectralEnergyMidLow, spectralEnergyMidHigh, spectralEnergyHigh, hfc, Bark-band (barkCrest, barkFlatness, barkKurtosis, barkSkewness, barkSpread), ERB-band (erbCrest, erbFlatness, erbKurtosis, erbSkewness, erbSpread), Mel-band (melCrest, melFlatness, melKurtosis, melSkewness, melSpread), beatsLoudness, chordsStrength, hpcpCrest, hpcpEntropy. Scanners should send whatever they computed; missing values stay null.

Body: {
  "path": "\\\\NAS\\Music\\Artist\\Song.mp3",
  "metadata": { "artist": "Artist", "title": "Song", "album": "Album", "duration": 245 },
  "identity": { "audioMd5": "abc123...", "chromaprint": "AQADtN..." },
  "features": { "bpm": 128.0, "key": "C", "mode": "major", "dynamicRange": 11.3, "dynamicRangeSource": "essentia-lra", ... },
  "provenance": { "scannedBy": "pandabox", "tool": "essentia", "toolVersion": "2.1-beta5" }
}
Response: { "success": true, "mediaItemId": "a1b2c3d4-...", "matchType": "new", "confidence": 1.0 }

Bootstrap import from mbxmoods.json or mbxhub-fingerprints.json. Batched writes (500 per SaveChanges). Idempotent — re-import updates if newer. Returns immediately with job ID for polling.

Body: { "source": "mbxmoods.json", "path": "C:\\MusicBee\\mbxmoods.json", "libraryRoot": "C:\\MusicBee\\Music" }
Response: { "success": true, "jobId": "import-001" }

Poll import progress.

Response: {
  "success": true, "jobId": "import-001", "state": "running",
  "progress": { "processed": 35000, "total": 70000, "errors": 12 },
  "startedAt": "2026-03-16T10:00:00Z"
}

Enqueue a file for Essentia analysis on this node's local ScanWorker. Used by ScannerPool to dispatch work to remote scanners.

Body: { "file": "C:\\Music\\Artist\\Song.mp3", "share": "\\\\NAS\\Music\\Artist\\Song.mp3", "priority": "high" }
Response: { "status": "queued", "file": "C:\\Music\\Artist\\Song.mp3" }
No worker: 503 { "error": { "code": "SCANNER_UNAVAILABLE" } }

Full export of all tracks with mood features (legacy format, file download). Add ?since={iso8601} for delta export — only tracks with features added or updated since the given timestamp (v1.1 format with identity signals). Scope boundary: this endpoint backs peer-sync, and it filters on MoodFeatures != null. Phase 2/3 identity-only rows (produced by /scan/fingerprints hash-only sweeps — fingerprint.v1 + audioStreamSha256 with no features yet) are not exported here. Identity signals propagate through a different path: TrueUpScheduler + PeerPullService resolve identity-only rows against peer caches on demand (see POST /meta/true-up). Peer-sync remains the mood-data distribution channel.

Trigger immediate peer sync. Runs SSDP discovery and pulls features from all discovered peers.

Current sync state: enabled, syncing flag, last result, and known peers with names.

Collapse peer-sync duplicate rows by grouping on identity.metadataKey, keeping a canonical (prefers non-peer:// path, then latest MoodFeatures.AnalyzedAt), and deleting the rest. Also deletes orphan peer:// rows with no identity signals at all (pure bloat from the pre-B2 era when peer ingests didn't store them). Manual endpoint runs VACUUM to reclaim disk. Auto-dedup (v0.5.2.4+): MetaHost runs AutoDedupIfStale(7d) automatically on every startup right after BackfillMetadataKeySignals; skips VACUUM so startup stays snappy, idempotent via SyncMetadata['dedup.appliedAt'], errors swallowed so a dedup fault can't block MetaServer from coming up.

Response: {
  "success": true,
  "data": {
    "backfilledSignals": 42,
    "mergedDuplicates": 1248,
    "deletedOrphans": 73,
    "remainingTracks": 70885
  }
}

Current SMTC target (host:port) and connection state.

Response: { "target": "192.168.1.10:8080", "state": "Connected" }

Switch SMTC target. Tears down existing WebSocket connection, updates config, and reconnects to the new endpoint.

Body: { "target": "192.168.1.10:8080" }
Response: { "ok": true, "target": "192.168.1.10:8080" }

Cached list of discovered MBXHub endpoints on the network. Each entry includes address, name, active flag, and capabilities.

Response: { "endpoints": [
  { "address": "192.168.1.10:8080", "name": "LivingRoom", "active": true, "capabilities": ["rest-api", "websocket"] },
  { "address": "192.168.1.20:8080", "name": "Studio", "active": false, "capabilities": ["rest-api"] }
] }

Clear endpoint cache and re-scan the network via SSDP for MBXHub instances. Returns the fresh endpoint list.