MBXHub

Full web dashboard with library search, now playing, controls, volume, ratings, shuffle/autodj/repeat toggles. Panel visibility, order, and collapsible grouping are configurable via dashboardLayout in settings.

Search: client-side fuzzy album/artist matching + server-side track search. Albums containing matching tracks are boosted (e.g. “wonderwall” surfaces its album). Inline track expansion on album results. Explore button seeds explore.html?album=&artist=.

UPnP device description XML. Contains device info, service URLs, and presentation URL.

WS-Discovery metadata exchange endpoint. Windows sends a SOAP GetMetadata request after discovering MBXHub via UDP Probe; response includes PresentationUrl pointing to /dashboard.

HTML status dashboard with live stats: system info (version, uptime, host, modules), library counts (tracks, albums, artists, genres, playlists, podcasts), AutoQ state (status, vibe list, mood cache, auto scan), and feature flags. All data fetched client-side from existing API endpoints.

Returns system status and the hub’s modules (JSON): {status, modules:[{name, status, detail}]}. modules lists what the plugin registered — REST, WebSocket, Discovery — with status running, off or failed to start, then Shell, connected or not connected (whether the Shell has announced itself to this hub). detail adds this PC only for a REST listener that fell back to localhost, or the WebSocket client count; null otherwise.

Where truedat resolves each of its artifacts — asked of truedat itself (--paths --json), never derived by the hub, since its resolution order and host-suffixed naming are its own convention. Response: {resolvedFrom, paths:[{key,label,path,present,note}], capturedUtc, stale, staleReason}. resolvedFrom names which step chose the catalog — --moods argument means the hub pinned it via the moodsFilePath setting, anything else means truedat discovered it — which is the distinction a wrong-catalog report turns on. Absent artifacts keep their entry (present:false) rather than being omitted. truedat holds one run slot, so during a scan this returns the last good answer with stale:true and its capture time; 503 when truedat cannot be resolved and nothing is cached, 502 when its output cannot be read. Rendered as the Truedat Paths panel at the bottom of /status.

Diagnostic surface — a live “Geiger counter” for steady-state activity. Off by default; gated on diagnostics.diagEndpointEnabled = true in mbxhub.json. Returns 404 when disabled, with explanatory body.

/diag serves a self-contained HTML page that polls /diag/perf at 1 Hz from the browser and renders inline-SVG sparklines for: process CPU %, network bytes in/out, working-set / private bytes, thread count, handle count, GC gen0/1/2 collection rate. Last 120 samples (~2 min) held client-side. Server is stateless — no background timer, no ring buffer, no allocation while the page is closed.

/diag/perf returns an instant snapshot of public process counters via System.Diagnostics.Process, System.Net.NetworkInformation, and GC.CollectionCount. Fields: ts, processorMs, workingSetMB, privateMB, threadCount, handleCount, gen0/gen1/gen2, bytesIn, bytesOut, logicalProcessors. Cumulative counters; the page diffs them client-side to derive per-second rates.

/diag/mbxhub returns a per-MBXHub instrumentation snapshot — counters specific to this plugin (request rates, broadcaster fan-out, lock waits, etc.) rather than the OS-level metrics in /diag/perf. The /diag page renders this as a second tile row. Same diagEndpointEnabled gate.

/diag/autoq/picks returns the last 20 AutoQ decision records, newest first — one per pick. Each names which entry point ran (fill, pick, generate, journey, preview, connect, station-play, send), what each eligibility gate removed, where the pick aimed and how far it reached, the top scorers with the components that produced them, what a quota cut, the ordering, and what reached the queue. Double-gated: needs diagEndpointEnabled and diagnostics.pickJournalEnabled. With the journal on, the same records are also appended one JSON object per line to autoq-picks.log beside mbxhub.log (5 MB, 2 archives), so a bug report carries them; the wire and the file use the same formatter and are byte-identical. Two shapes a reader must handle: a normally-numeric field is the string "NaN" / "Infinity" / "-Infinity" when non-finite, and on a send record sentUrls/sentQueued are the listener’s own tracks while queued is AutoQ’s fill — they are never combined into one number. A send record also carries sendMode (shown as mode= on the summary line): the steer variant that applied (refresh/reuse/restart), the same value the send’s response reports as mode, so the toast a listener saw and the journal line a triager reads cannot tell two different stories. sentUrls itself is capped at 50 entries so one huge multi-select cannot write an unbounded line; sentTotal carries the uncapped count of what was sent. A record with no poolRecorded never drew a pool at all — distinct from a draw that came back empty. Every record carries waypoints; it is non-empty only when the pick built a journey, and then holds the route in order — first = start and last = end — beside sequence, the arc actually produced through it. That can be a journey, preview, connect or send record, or a station-play of a saved journey station: the route is recorded on whichever entry point opened the pick. The summary line shows route=N only when there is a route, so route=3 against a two-track request is a journey that picked up a waypoint nobody asked for.

Edges in the journal. An ordered pick record carries edges — on (edge segments shaped the joins), off (edge data is present but Edge transitions is switched off), building or none — and the summary line says it out loud: edges=on, edges=OFF(unused), edges=none, and names the join into the fill in words: join=9A/122->8A/120(edge) is the queued track’s end into the first pick’s start, key/BPM each side, and whether the incoming side was its edge segment. joins lists what met at each adjacent pair of sequence, aligned with pairKeyDistance: fromKey/fromBpm (the outgoing track’s end), toKey/toBpm (the incoming track’s start), and fromSource/toSource — edge when that side was the track’s edge segment, whole when it was the whole track. join is the same for the step into the fill that joinKeyDistance measures; its outgoing side has no source.

/diag/snapshot (v0.5.2.6+) takes a JSON body containing the page’s client-side ring (samples + derived rates + small header) and appends a formatted text block to diag-snapshots.log next to mbxhub.log. Each snapshot is delimited by “=” rules with a per-metric min/avg/max/latest table and the raw samples JSON below for forensic re-processing. Triggered by the Snapshot button on the /diag page; same diagEndpointEnabled gate. Response: { success, path, bytes, at }.

/diag/search (v0.5.3.0) returns a rolling p50/p90/p95/p99 summary over the last 256 search calls (in-memory ring, ~28 KB, server-wide singleton). Summary is segregated by endpoint: library (calls into /library/search), federated (calls into /search), and combined. Each block carries totalMs {p50,p90,p95,p99,max,mean}, candidates {p50,p95,max}, and mbCalls {p50,p95,max}. The recent array (default 50, override with ?recent=N, capped at ring capacity) lists the newest entries with per-stage timings (mb / cue / am / pf / sort / pg) and per-family MB-call counts (qf / ql / qlr / gt / gts / gp / gb / pl). POST /diag/search/reset clears the ring (operator-triggered flush; empty body, send Content-Length: 0). Same diagEndpointEnabled gate. Returns 403 FORBIDDEN when ApiReadOnlyMode is set — kiosk deployments can’t have their perf history wiped by remote clients.

// Enable in mbxhub.json:
{
  "diagnostics": {
    "diagEndpointEnabled": true
  }
}
// Then visit:
//   http://host:8080/diag         → live page
//   http://host:8080/diag/perf    → JSON snapshot

Returns API version information. Includes host field with the configured discovery name (or machine name if not set), and branch — the git line this build came from (master, release, a feature branch, or unknown outside a repo). The branch is deliberately absent from displayVersion for the lines we ship from: a bare version number IS the release, and a suffix marks something as not one. It is reported here instead, because a version string is identity and this endpoint is diagnostics — without it, answering “which line is this build on” means having the repo to hand and running git branch --contains. Also signature and signatureVerified: the running plugin is checked against the Halrad signing certificate (a valid signature AND our certificate, since either alone can be satisfied by a file that should not pass); signatureVerified is true only for a shipped, unaltered build. “Could not determine” is reported as its own state, never as verified. The Diag page shows the same.

Returns this node's capabilities for cross-channel SSDP discovery. Used by Shell and other MBXHub nodes to identify what this instance offers.

// Response:
{
  "node": "plugin",
  "version": "0.5.5.3",
  "capabilities": ["rest-api", "websocket", "player-control", "autoq", "discovery"],
  "endpoints": {
    "rest": "http://host:8080",
    "ws": "ws://host:8080/ws"
  }
}

Health check endpoint (alias: /system/ping). Returns status, service and apiVersion.

apiVersion is the extension contract's version, not the product's. It is a string, currently "1". Under a fixed value no field is removed from a response and no response type changes; fields may be added, so a client must tolerate members it does not know. A change to the contract bumps the value, and the bump is announced. The product version moves every release and is reported by GET /system/version — pin an integration against apiVersion, never against that. It is on /ping because /ping is the first response most integrators read, so the contract is known before anything else is.

// GET /ping
{
  "success": true,
  "data": {
    "status": "ok",
    "service": "MBXHub",
    "apiVersion": "1"
  }
}

Returns enabled feature flags: banlist, ratings, loved, reactions, streaming, playReporting (false when apiDisablePlayReporting or apiDisablePlayCountUpdates is on — clients watching this flag stop sending play reports under either), partymode, autoq, cast (the cast.enabled switch: false means every /cast route answers 503 CAST_DISABLED; whether a Shell is up to carry a cast is the route’s own answer), transcode (true only when transcode.enabled AND ffmpeg actually resolves — the capability statement clients key the ?compat=1 ask on), transcodeFormat (what a ?compat=1 answer is converted to, the transcode.format setting, e.g. "flac"; present only while transcode is true; a Cast sender takes the converted item’s content type from it, and an older hub without the field converts to flac), diag (v0.5.3.4 — mirrors diagnostics.diagEndpointEnabled). Clients use these to show/hide UI elements.

Also carries libraryTagsWritable — whether a library-tag write (POST /dashboard/love, POST /dashboard/rate/{n}) can actually succeed right now. This is a different question from ratings/loved, which say whether the feature exists at all: a hub can have ratings enabled and still refuse every write, which is the stock configuration (apiReadOnlyLibraryTags defaults true). Effective, like streaming beside it: false when any of apiReadOnlyMode / apiReadOnlyLibrary / apiReadOnlyLibraryTags is on, and false while a party is active (tag writes are refused for every role during a party, DJ included). Render the stars and heart either way — reading a rating always works; what this flag governs is whether to offer to change it. It is a snapshot, so treat the verb’s own 403 as the authority.

And tagEditNotice — whether a client may explain that refusal. Independent of libraryTagsWritable: that one says the write is refused, this one says whether to say so out loud. False when disableTagEditNotice is on, which exists for a hub deliberately run read-only, where the block is the intended behavior and being told about it is noise. When false, still retire the control and still carry the reason on hover — only the transient notice is suppressed, never the explanation itself. An older hub omits the field entirely; treat absent as true, because a needless toast is a smaller failure than a control that silently does nothing.

Also carries webSocketAuth — "clear" or "restricted", the resolved credential mode of the /ws feed (never the stored “follow profile” value). restricted means a remote page must mint a ticket at POST /ws/ticket before each connect and a program must send its key on the handshake; see WebSocket Events → Credentials. An older hub omits the field; treat absent as clear.

Also carries lanBase — the http://<ip>:<restPort> a device elsewhere on this network uses to reach this hub. The field is absent when nothing qualifies, because responses omit null properties — read a missing key exactly as you would read null — and nothing qualifies when either no adapter carries a usable address or allowRemoteConnections is off, in which case the hub refuses every LAN caller anyway and a URL here would name a door that is closed. A page opened at 127.0.0.1 must use this, not location.host, when it hands a URL to something that will fetch the URL itself — a Cast receiver resolves a loopback address to the receiver, not to the hub. The address is read from the live adapters each time the endpoint is called: the adapter must be up and must not be loopback or a tunnel, and its IPv4 must be in a private range and not APIPA (169.254.x.x) — which is why a VPN or a public address is never published. A default gateway only breaks ties between addresses that already qualify; it is not a requirement. A non-null value is not a promise of reachability — the URL ACL, the Windows Firewall and IP filtering can each still refuse a given peer.

Also carries shellBridge — { port, binding, seenUtc } when the MBXHub Shell has announced its overlay bridge this hub run, otherwise null. A page offering “open this as a desktop window” should use that port rather than assuming restPort + 1; null means fall back to the convention. binding is wildcard (the normal case: the bridge binds under the Shell port’s http://+: reservation) or loopback (a box with no such reservation); loopback-only is enforced per request either way. It is not a liveness claim — it says where the Shell said it was listening, so probe before drawing anything.

The Shell announcing where its overlay bridge listens: { "port": 8081, "binding": "loopback" }. An empty body clears the announcement, which is a clean Shell shutdown saying so. Read back through GET /system/features.

Local callers only (403 otherwise): this is one process on this machine telling another where it is, and a page that believed a remote announcement would send pop-out requests at a port somebody else chose. Held in memory, never persisted — a bridge that is not running should stop being advertised when the hub restarts, and the Shell re-announces on every start.

The machine audited against the configured setup mode: which URL reservations and firewall rule this mode needs, and which of them are actually there. mode is local, private or shared; each entry’s verdict is fine, wrong (needed and missing) or extra (present and not needed — what a hub left behind after moving down to This computer only). consistent is true when nothing the mode needs is missing; extra entries never break it. wrong and extra list entry names, and may also contain Firewall rule — the rule is audited alongside the entries but is not a row in entries[], so do not expect to find every name there.

discovery[] holds the two discovery UDP rows, Advertising (1900, 3702) and Cast discovery (5353), each with name, ports, purpose, needed, present, verdict and notNeededReason. notNeededReason says why a row is not needed, in the Network Status tab’s words (remote access is off, advertising is off, Cast is not in use), and is absent when the row is needed. Advertising is needed when the hub advertises itself, Cast discovery when Cast is in use, and nothing is needed under local. An enabled inbound allow rule covering the row’s ports counts as present whatever its name, provided it is not scoped to a Windows service and, if scoped to a program, that program is the one listening (MusicBee for the advertising ports, the Shell for Cast discovery). With Cast not in use nothing listens on 5353, and a rule for either program counts. An enabled block that applies to the listening program wins, and Windows’ own built-in discovery rules are service-scoped, so they do not count. A discovery row’s name joins wrong or extra the same way, except that a needed, missing row is wrong only while Windows Firewall is on; with it off the verdict is fine. repairUdpPorts is the ports of the rows the audit says are needed, comma-separated ("" when none, which includes local even with Cast on); Fix passes --udp none when it is empty.

Local callers only (403 LOCAL_ONLY otherwise), and read-only: it exposes nothing a local netsh http show urlacl does not, and repair stays a console act — MusicBee → MBXHub Settings → Network Status → Fix. This endpoint offers no write. 503 NOT_AVAILABLE when the audit is not wired in this host.

// GET /system/network-setup
{
  "success": true,
  "data": {
    "mode": "private",
    "entries": [
      { "url": "http://+:8080/", "name": "REST API", "needed": true, "present": true, "verdict": "fine" }
    ],
    "firewallRule": { "needed": true, "present": true, "firewallOn": true },
    "discovery": [
      { "name": "Advertising", "ports": "1900,3702", "purpose": "SSDP and WS-Discovery: phones and the Shell find this hub; it appears in the Windows Network folder. The hub's mDNS announcement is served by Windows' DNS Client service, under that service's own rule", "needed": false, "present": false, "verdict": "fine", "notNeededReason": "advertising is off" },
      { "name": "Cast discovery", "ports": "5353", "purpose": "mDNS: the Shell finds Cast receivers", "needed": true, "present": true, "verdict": "fine" }
    ],
    "repairUdpPorts": "5353",
    "wrong": [],
    "extra": [],
    "consistent": true
  }
}

The hub’s own route table: one entry per method and path it registers. kind is static (exact path), pattern (path is the regular expression the request path is matched against), prefix (path is the bare prefix, e.g. /pages/, and any longer path under it matches) or template (path is a {name} template such as /playlists/{url}, matched by its own code). action is the access-profile class the route is registered under. Static routes come first, then dynamic routes in the order they are tried. The API validator measures its coverage against this list.

Local callers only (403 LOCAL_ONLY otherwise), and read-only. 503 NOT_AVAILABLE when the route table is not wired in this host.

// GET /system/routes
{
  "success": true,
  "data": {
    "count": 4,
    "routes": [
      { "method": "GET", "path": "/system/status", "kind": "static", "action": "Read" },
      { "method": "GET", "path": "^/playlists/(.+)/files$", "kind": "pattern", "action": "Read" },
      { "method": "GET", "path": "/stream/", "kind": "prefix", "action": "Read" },
      { "method": "GET", "path": "/playlists/{url}", "kind": "template", "action": "Unclassified" }
    ]
  }
}

v0.5.3.4. Returns the friendly display-name MB has configured for each of the 48 tags exposed by browse.customSorts (Custom1..Custom16, Virtual1..Virtual25, Year, OriginalYear, SortAlbum, SortAlbumArtist, SortArtist, SortTitle, SortComposer). Server reads Setting_GetFieldName for each; only entries whose user-set name differs from the raw enum are returned. Used by settings.html's customSorts tag-picker to render AutoQ Moods (Custom1) instead of just Custom1.

// GET /system/custom-tag-names
{
  "success": true,
  "data": {
    "names": {
      "Custom1": "AutoQ Moods",
      "Custom2": "Mood Rating",
      "Virtual1": "Energy"
    }
  }
}

Get or update hub configuration (ports, enabled modules, log verbosity, library behavior). restPort and restEnabled changes require localhost (403 for remote). All changes blocked for remote clients during party mode.

Beyond the network fields (restPort, restEnabled, wsEnabled, defaultPage), GET and PUT also surface (MBRC was cut; mbrcPort / mbrcEnabled no longer exist):

{
  "logLevel": "Info",                              // trace/debug/info/warn/error, case-insensitive; propagates to Shell
  "effectiveLogLevel": "Info",                     // GET only, read-only: the level actually in force, which a Shell
                                                 //   with followHubLogLevel on follows
  "library": { "disableStrictSearch": false }    // v0.5.2.4+: disables phrase-per-field strict search
}

GET additionally returns a read-only dashboardLayout block. Static pages have no other route to these values — the dashboard is server-rendered and reads settings directly, but browse.html and the injected command palette are plain assets, so this response is their config channel. Write these through PUT /system/config (or the settings page), not here:

{
  "dashboardLayout": {
    "disableVirtualTracklistBadge": false,       // the CUE / SET LIST badge: browse.html's chip,
                                                 //   and the HUD's over the artwork
    "liveSetBadgeTarget": "nowplaying",         // where that badge goes: "nowplaying" | "play"
    "hideFileInfo": false,                       // the codec / rate line. Lives on HubSettings, not
                                                 //   inside DashboardLayout; carried here because it is
                                                 //   a Dashboard knob and this is the block clients read
    "commandPalette": {
      "enabled": true,                           // the ONLY off switch on play/explore/nowplaying/browse/hud,
                                                 //   which include the palette bootstrap unconditionally
      "openShortcut": "Ctrl+K",
      "recentLimit": 8,                          // clamped 1..50 client-side
      "bucketLimit": 100,                        // clamped 1..500 client-side
      "actions": []                              // empty = curated defaults
    }
  }
}

GET also returns a read-only dice block, { "scope": "library", "onPress": "play", "rolls": "album" } — the hub’s autoQ.diceScope / autoQ.diceOnPress / autoQ.diceRolls, which the dice page reads when a device follows the hub (see POST /autoq/dice). Written through PUT /system/config.

GET also returns a read-only hud block, for the same reason — browse.html has to know these before it sizes its album fetch. Write them through PUT /system/config or the settings page:

{
  "hud": {
    "recentAlbumViewLimit": 0,                   // albums shown when Browse is sorted by Recently Added
    "randomAlbumViewLimit": 0,                   // albums shown when Browse is sorted by Random
    "presentation": {                          // system defaults; HUD device overrides are local
      "backgroundMode": "immersive",          // solid (Low power), small, immersive
      "artworkSizePercent": 0,                 // 0 keeps preset; 25 to 100 scales artwork
      "backgroundDimPercent": 40,
      "bottomBarStyle": "filled",              // filled, transparent
      "metadataVisibility": "auto",            // auto, always, hidden
      "metadataPlacement": "below",           // below (between artwork and transport; normal HUD only), overlay (on the artwork)
      "metadataDetail": "full",               // full, compact (title and artist only)
      "transportSize": "m",                   // s, m, l, xl, xxl: the HUD's own button size, not the dashboard's controlsSize
      "controlsVisibility": "auto",
      "fadeDelayMs": 4000,                        // 2000, 4000, 6000, 10000
      "alwaysShowProgress": false,
      "listenHerePlacement": "titlebar",        // titlebar, services, neither
      "castPlacement": "titlebar",
      "volumeControls": "shown",               // shown, hidden: the whole title-bar volume cluster
      "volumePull": false,                       // drag the speaker for volume; tap-mute and - / + work either way
      "queueOpen": false,
      "lyricsOpen": false
    }
  }
}

Both album limits are 0 = unlimited, which is the shipped behavior. They cap only the two discovery sorts: A–Z, Album Artist and Year are lookup orders whose completeness the A–Z rail depends on, and are never capped. Random additionally bypasses the browse page's per-sort memoize cache so each visit is a fresh shuffle — at 25 albums the cached order would otherwise be the same 25 for the whole session.

Only fields a client actually reads are carried. commandPalette.showChip is deliberately absent because the chip is rendered server-side. Added v0.5.5.0 — before it, every palette knob above was declared, validated and read at the right name but never traveled, so changing one did nothing.

logLevel is validated against the same vocabulary as HubLogger.ParseLevel/ShellLog.ParseLevel; invalid values are silently ignored (same soft-skip pattern used for restPort range checks). library.disableStrictSearch takes a nested object — the parent object is created if missing. Neither requires localhost; both are UX-level settings safe to change remotely. Everything else in mbxhub.json, including search.live.minQueryLength and the dashboardLayout values above, is written through PUT /system/config and listed by GET /system/settings/schema; this endpoint carries a hand-picked subset and is not a general settings writer.

Returns schema for all configurable settings. Each entry includes:

Security: blocked when disableRemoteConfig is true (403) or during party mode (403). The /pages/settings.html page consumes this endpoint.

Also lists one charm.<id>.<key> row per setting of each charm holding the settings grant, under that charm’s category — see Charms, Verbs, the store and settings.

Update configurable settings via dotted key paths. Only properties decorated with [ConfigSetting] can be modified, and only those in a category the schema offers — the keys this route writes are exactly the keys GET /system/settings/schema lists.

Body: JSON object with dotted keys:

{"autoQ.batchSize": 10, "debugMode": true}

Console-only categories are refused. A key in Network, Features, Security or RateLimit is answered at the machine, in MBXHub's settings dialog in MusicBee, and this route replies 403 SETTING_CONSOLE_ONLY naming the offending keys — and applies nothing at all, so pairing a protected key with an ordinary one writes neither. A security control you can change over the network is not a security control.

charm.<id>.<key> keys are a charm’s settings: they are written to that charm’s store, never to mbxhub.json, and an undeclared key or a value the setting does not accept is 400 CHARM_SETTING_UNDECLARED / 400 CHARM_SETTING_INVALID, naming the keys, with nothing applied — see Charms, Verbs, the store and settings.

Security: blocked by apiReadOnlyMode (403), disableRemoteConfig (403), and party mode (403). POST is an alias for PUT.

Get or set the default redirect page (body: {"defaultPage":"/pages/player.html"})

Security: PUT is blocked by disableRemoteConfig (403) for a caller that is not on the loopback interface.

Get the theme THIS caller renders with, or update the hub's own theme. GET answers the caller's resolved theme — its own values if the device carries a mbxh_device_theme cookie (see /device/theme), otherwise the hub's. ?scope=hub answers the hub's own values regardless of the caller's cookie. PUT always writes the hub.

Two configurable mode slots (mode1, mode2) each with 13 HSL fields: accentHue (0–360), accentSaturation (0–100), accentLightness (0–100), bgHue (0–360), bgSaturation (0–100), bgLightness (0–100), surfaceHue (0–360), surfaceSaturation (0–100), surfaceLightness (0–100), textHue (0–360), textSaturation (0–100), textLightness (0–100), intensity (0–100, saturation multiplier: 0 = grayscale, 100 = full color). Partial updates supported — only include the fields you want to change.

// GET response:
{
  "activeMode": 1,
  "mode1": {
    "accentHue": 197, "accentSaturation": 80, "accentLightness": 55,
    "bgHue": 203, "bgSaturation": 30, "bgLightness": 94,
    "surfaceHue": 203, "surfaceSaturation": 30, "surfaceLightness": 96,
    "textHue": 203, "textSaturation": 50, "textLightness": 13,
    "intensity": 100
  },
  "mode2": {
    "accentHue": 197, "accentSaturation": 80, "accentLightness": 55,
    "bgHue": 203, "bgSaturation": 30, "bgLightness": 7,
    "surfaceHue": 203, "surfaceSaturation": 30, "surfaceLightness": 10,
    "textHue": 203, "textSaturation": 50, "textLightness": 90,
    "intensity": 100
  },
  "active": {
    "accentHue": 197, "accentSaturation": 80, "accentLightness": 55,
    "bgHue": 203, "bgSaturation": 30, "bgLightness": 94,
    "surfaceHue": 203, "surfaceSaturation": 30, "surfaceLightness": 96,
    "textHue": 203, "textSaturation": 50, "textLightness": 13,
    "intensity": 100
  },
  "disablePinchZoomLock": false,
  "deviceOverride": false,   // true when these values came from this device's own cookie
  "canWriteHub": true        // whether a PUT /system/theme from this caller would be accepted
}

// PUT examples:
{"activeMode": 2}                                     // Switch to mode 2
{"mode1": {"accentHue": 180}}                         // Update just accent hue on mode 1
{"mode1": {"bgLightness": 10, "textLightness": 90}}     // Make mode 1 dark
{"mode1": {"intensity": 0}}                           // Desaturate mode 1 to grayscale

deviceOverride says whether the values returned are this device's own rather than the hub's; it is reported under ?scope=hub too, where the values are the hub's but the device's state is still what the caller needs to know. canWriteHub says whether a PUT /system/theme from this caller would be accepted, so an editor can show the right affordance instead of discovering a 403 on save.

PUT broadcasts a ThemeChanged WebSocket event and sets the mbxh_theme cookie for dashboard SSR.

Security: PUT is blocked by disableRemoteConfig (403) for a caller that is not on the loopback interface.

Set, or give up, THIS device's own theme. PUT takes the same body as PUT /system/theme and starts from the theme this caller currently renders with, so a body naming one field changes one field. DELETE is how a device goes back to following the hub.

The whole effect is a cookie on the caller — mbxh_device_theme, a year long, path /, SameSite=Lax. Nothing on the hub changes: no setting is written, no ThemeChanged event is broadcast, and other devices see nothing. disableRemoteConfig therefore does not apply — it guards the hub's settings, and this is not one, so a phone that could never change the hub's theme can change its own.

A device with no cookie follows the hub, and every page it is served is rendered with the hub's theme. DELETE expires the cookie rather than writing the hub's current values into it: a device holding a copy of today's hub theme looks right and has silently stopped tracking every later change.

Both answer the same payload as GET /system/theme — PUT with deviceOverride: true and the device's new values, DELETE with deviceOverride: false and the hub's.

The theme editor — the dashboard's theme drawer, behind the gear, and /pages/theme.html — carries an Apply to: This device | All devices choice. This device saves through PUT /device/theme, which disableRemoteConfig does not gate. All devices saves through PUT /system/theme, and where the hub will not accept that from this caller it is shown disabled with the reason. All devices includes THIS device: saving there from a device that had a theme of its own gives that theme up (the same DELETE /device/theme), so the screen shows what was just published and the device follows the hub again — otherwise it would publish a change it could not see. Follow the hub (DELETE /device/theme) is offered while the device has a theme of its own. A device with its own theme ignores the hub's ThemeChanged broadcast.

Not on the party surface: while a party is running, a remote guest's device cannot set a theme of its own.

// PUT examples (same body as PUT /system/theme):
{"activeMode": 2}                                     // This device uses mode 2
{"mode1": {"bgLightness": 10, "textLightness": 90}}     // Dark, on this device only

// Response header on PUT:
Set-Cookie: mbxh_device_theme=v1.2.0.197-80-55-...; Path=/; Max-Age=31536000; SameSite=Lax

// Response header on DELETE (the cookie is expired, not overwritten):
Set-Cookie: mbxh_device_theme=; Path=/; Max-Age=0; SameSite=Lax

Process metrics for the MusicBee host process. Used by MBXHVAL for remote monitoring.

// Response:
{
  "success": true,
  "data": {
    "process": {
      "name": "MusicBee",
      "cpuPercent": 2.15,
      "memoryMB": 185.3,
      "privateMemoryMB": 210.5,
      "threadCount": 42,
      "handleCount": 1250
    },
    "gc": {
      "gen0": 150,
      "gen1": 30,
      "gen2": 5,
      "totalMemoryMB": 45.2
    },
    "timestamp": "2026-03-10T12:00:00.0000000Z"
  }
}

Server start time and uptime. Used by dashboard to detect restarts.

// Response:
{
  "success": true,
  "data": {
    "startedAt": "2026-03-10T20:30:00.0000000Z",
    "uptimeSeconds": 3600,
    "uptime": "1h 0m"
  }
}

Generate QR code PNG image for the MBXHub base URL. Optional ?url= for custom target.

Open the plugin's Settings dialog on MusicBee's UI thread — used by the first-run setup screen's Settings link. Local, or a paired Shell: a remote caller must carry a valid X-MBXHub-SAC signature (see Signed calls from a paired Shell under Charms & Capabilities). With no signature at all: on a paired hub 403 SAC_REQUIRED, and on a hub that has never paired the unchanged 403 FORBIDDEN. With a signature that does not hold up — including on a hub with no secret to check it against — 403 SAC_INVALID. 404 when disabled via disableOpenSettings — the kill switch outranks a caller that authenticated — and 503 when the plugin UI isn't available. The dialog opens on the hub's screen, which on a headless jukebox is a screen nobody is standing at.

Redeem a pairing code for the Secure Access Channel secret — the exchange that makes a Shell a paired Shell. Body {"token":"ABCDE-FGHIJ"}, in the body and never a query string. Answers {"secret":"<base64url>","hubId":"<hub id>"}; the Shell keys its copy of the secret by that hubId, so both fields are needed. Closed unless a window is armed at the hub's console. A person clicks Pair a Shell in the MBXHub settings dialog on the hub's own machine; that click is the only thing that opens this endpoint, and there is no way to arm one remotely. The window lasts five minutes, is good for one redemption, and closes after five wrong codes. Refusals: 403 SAC_PAIRING_CLOSED when no window is open (the state of every install nearly all of the time), 403 SAC_PAIRING_REFUSED for a wrong code or a spent budget, 500 SAC_PAIRING_UNAVAILABLE when the hub has nowhere per-user to keep a secret — that last one leaves the window open, because nothing was handed out. The code is Crockford base32 and is read forgivingly: the hyphen is optional, case does not matter, and O/0 and I/l/1 are the same character. The 32-byte secret crosses the network once, in this one response, in the clear — there is no TLS, and a five-minute window a person opened by hand with somebody watching is what bounds that. Every attempt is logged with the caller's address; the code and the secret are not. When no window is armed, the optional REST password stands in front of this route like any other non-local call. One secret per hub. Pairing replaces any previous pairing — a Shell paired earlier will need to be paired again (a Shell on the hub's own machine is re-paired automatically).

Returns the client's IP address as seen by the server. Used by the SMTC Link Charm to discover the client's local Shell when accessing a remote dashboard.

Other MBXHub instances on the LAN, as discovered by the Shell's SSDP scan. The plugin reads the shared file %LOCALAPPDATA%\MBXHub\hub-neighbors.json (written by the Shell) and returns its contents; shared.js calls this on every page load and merges the result into the browser list that /pages/hubs.html renders. Returns an empty array when the file is missing — Shell not running, nothing discovered yet, or a different user profile. Never errors: hub-neighbors is a hint, not a contract.

The canonical list of registered sorts (built-ins plus customs), so callers don't have to guess sort ids. Direction is request-side only — never a property of an entry; directionApplies says whether asc/desc is meaningful for that sort at all. Returns {sorts: []} rather than an error when the registry isn't wired.

// Response:
{
  "success": true,
  "data": {
    "sorts": [
      { "id": "album", "label": "Album", "kind": "builtin",
        "directionApplies": true, "valueKind": "text" }
    ]
  }
}

Diagnostic probe over the sort index: returns the first 20 album names in the requested order. Exists to smoke-test sort wiring on its own, without going through a /library/* endpoint. sort is required. dir defaults to asc.

Errors: 400 MISSING_SORT (no sort parameter), 400 UNKNOWN_SORT (id doesn't resolve against /system/sort-registry), 503 SORT_INDEX_UNAVAILABLE (index not wired).

Push a named event into the WebSocket broadcaster from sub-process components (Shell, scripts, automations). It goes out as the SystemEvent type, carrying {name, payload} — the pushed name and the request body — so a client subscribes to SystemEvent, never to the pushed name: only the types in EventTypes.All can be subscribed to, and a client with no subscriptions receives it either way. A body that is empty or not JSON leaves payload null and the event still goes out. Used to fan out signals that originate outside the plugin process. CastStatus is the one name the hub also acts on: from this machine, or signed by the paired Shell (X-MBXHub-SAC over the method, path and body), it sets or clears the speaker admitted for its audio and artwork (see Cast); unsigned from elsewhere it is fanned out but changes nothing. A signature that does not verify changes nothing either: where the caller would have been let in without the header, the push is still fanned out and the hub logs a warning; where the header is what got it past the password, API keys or Shared LAN, it is 403 SAC_INVALID and is not fanned out.

Answer: {success: true, data: {name, accepted: true}}. A CastStatus answer's data also carries speakerAdmitted: true only when the push was believed (from this machine, or signed by the paired Shell), it says the cast is active with a usable receiver.address, and that speaker is the one admitted once the push has been applied — a repeat for the speaker already admitted is true too. Otherwise false: an unsigned push from elsewhere is still answered 200, so the status alone does not say the speaker was let in.

Force re-extract all embedded resources (pages and charms) to disk. Overwrites existing files.

// Response:
{
  "success": true,
  "data": {
    "pagesUpdated": 8,
    "charmsUpdated": 3,
    "userModified": []
  }
}

Accepts browser-side log events and writes them to mbxhub.log. Use this instead of console.log for operational telemetry from dashboard pages so problems in guest browsers land in the server-side log where the operator can see them. Accepts either a single event or a batch via events[]. Silent on empty body (returns {success:true, data:{accepted:0}}); accepted counts events that passed validation and reached the log. Invalid JSON returns 400 INVALID_REQUEST (not INVALID_JSON — this endpoint predates the topology handler’s specific code). Access: ActionCategory.System — admin-gated. PartyMode guests are rejected (they lack System) so guest-sourced log entries can’t mix into operator telemetry.

// Single event:
POST /system/client-log
{ "level": "warn", "msg": "Retry #3 on /queue/add" }

// With page context (prefixes the log line as "[page] msg"):
POST /system/client-log
{ "level": "info", "msg": "Charm bar rendered", "page": "dashboard" }

// Batch:
POST /system/client-log
{ "events": [
  { "level": "info",  "msg": "Charm bar rendered" },
  { "level": "error", "msg": "ThemeChanged handler threw" }
] }

// Response:
{ "success": true, "data": { "accepted": 2 } }

Recognized fields: msg (required; empty or missing drops the event), level (optional, defaults to info; free-form string mapped to server log levels, unknown values log as info), and page (optional; wraps the output as [page] msg). Any other fields on the event object are silently dropped — if you need to capture a stack trace or structured data, concatenate it into msg. Both msg and page are sanitized: CR/LF/NUL stripped (blocks log-line forgery) and length-capped (4096 chars for msg, 256 for page).

Report a client-side (Listen Here) playback exit. The server applies MusicBee's own play-count thresholds (PlayCountTriggerPercent / PlayCountTriggerSeconds) to decide played vs skipped, then updates play statistics — so browser-streamed plays count exactly like speaker plays. For CUE virtual sub-tracks, send the raw file position plus cueStartMs; the listened window is measured against durationMs (the sub-track duration).

POST /player/report-play
{ "url": "C:\\Music\\track.mp3", "positionMs": 185000, "durationMs": 240000, "cueStartMs": 0 }

// Response:
{ "success": true, "data": { "url": "...", "counted": true, "countType": "IncreasePlayCount",
    "playedPercent": 77.1, "playedSeconds": 185, "result": true } }

countType is IncreasePlayCount (past threshold), IncreaseSkipCount (exited early), or NoChange (position 0 — nothing recorded), or native-owned (acknowledged, nothing marked: counted: false, result: false). native-owned answers only while all three hold: the hub setting cast.dedicatedAccounting is exactly native (default cast; any other value reads as cast), the current cast is MusicBee-owned (casting enabled, no queue-configuration change pending; Shared contributions may be enabled), and MusicBee's active output is MBXCast. It replaces marks only: a report that would record nothing still answers NoChange, refusals keep their answers, and an unreadable output marks as before. A native-owned answer holds the duplicate window like a counted play. Under the default nothing changes: the MBXHub Shell's per-item Cast reports mark as they always have. Optional abandoned: true marks a non-deliberate exit (tab close, output toggle, external track change): past threshold it still counts a play, below it nothing is recorded — never a fabricated skip. Optional cue: true marks a CUE-backed source — required for a sheet's FIRST sub-track, whose cueStartMs is 0. When durationMs is omitted or 0, the server derives it from the CUE sheet for sub-tracks (next track start − this start; the sheet's last track has no derivable end, so only the seconds rule can count it as a play and no skip is ever fabricated) or the library's duration for whole files, so the percent threshold still applies. Counted plays also feed the AutoQ session signal and, when TrueShuffle is enabled, the shuffle played-set and AutoReset completion check — neither feature is required for counting. Duplicate reports from the same client for the same track (keyed url + cueStartMs, so CUE sub-tracks never collide) are absorbed within an adaptive window (deduped: true), and play-statistic updates share a per-IP rate limit (rateLimitPlayStatsPerMinute, 429 when exceeded; loopback exempt). Optional disableScrobble: true suppresses Last.fm scrobbling for this report. 404 if the file is not in the library or apiDisablePlayReporting/apiDisablePlayCountUpdates is enabled.

Returns current track info with full metadata

// Response:
{
  "success": true,
  "data": {
    "playing": true,
    "url": "C:\\Music\\Artist\\Album\\track.mp3",
    "title": "Love Don't Live Here",
    "artist": "Breaking Rust",
    "album": "Greatest Hits",
    "albumArtist": "Breaking Rust",
    "year": "2024",
    "genre": "Rock",
    "trackNo": "3",
    "discNo": "1",
    "rating": "4.5",
    "love": true,
    "duration": 234000,
    "position": 45000
  }
}

Returns the now playing list. Supports ?offset=0&limit=50; limit=0 returns every row from the offset. To read Up Next, start AT the cursor (GET /queue/current, then ?offset=<currentIndex>&limit=0) — a default page stops at row 50 while upcomingTotal counts the whole list, and past that point the two describe different things. MusicBee keeps ONE now-playing list and shows two views of it: Playing Tracks (every row) and Up Next (what will actually play, in play order). Removing a track from Up Next leaves its row in the list and does not mark it played, so the raw list contains rows that will never play. Each track therefore carries upcoming — true when MusicBee's own play order still includes it. Render Up Next by keeping upcoming: true rows; upcomingTotal is the count of those across the WHOLE list, which is not derivable from total - currentIndex - 1 (that counts removed rows) nor from a filtered page. Each track carries an optional provenance object — who filled it and why (driver: AutoQ | TrueShuffle | Journey | Station | Manual, a short reason, and whenUtc). Omitted for tracks with no stamp (older fills or direct MusicBee queue adds). playOrder lists the indices MusicBee will play in the order it will play them, shuffle and Up Next order included: upcoming says whether a row plays, playOrder says when. It always covers the whole queue whatever limit pages, because order cannot be read off one page, and it is the same walk as upcoming, so the two never disagree — a row whose file cannot be read still counts, because it is still queued. A Listen Here takeover copies it to carry the room’s queue onto this device.

// Response:
{
  "success": true,
  "data": {
    "currentIndex": 5,
    "total": 150,
    "upcomingTotal": 142,
    "playOrder": [6, 7, 8, 9],
    "offset": 0,
    "limit": 50,
    "tracks": [
      {
        "index": 0,
        "url": "C:\\Music\\track1.mp3",
        "title": "First Track",
        "artist": "Artist Name",
        "album": "Album Name",
        "duration": 234000,
        "upcoming": true,
        "provenance": {
          "driver": "AutoQ",
          "reason": "mood:Energetic magnet",
          "whenUtc": "2026-07-26T12:00:00.0000000Z"
        }
      },
      // ... more tracks (provenance omitted when unknown)
    ]
  }
}

?view=play — the rows in MusicBee’s play order, opt-in. Only the exact value play selects it: no view, an empty one or any other value (Play included) is the list view above, byte for byte, and never carries view or viewTotal. The sequence is the current row, then each playOrder index once — indices are de-duplicated, never paths, so a file queued twice is two rows; currentIndex below 0 is an empty sequence. offset/limit page positions in that sequence by the list’s rules (default 50, limit=0 = every row from the offset, at most 10000 rows per page — the same cap; an offset past the end is an empty page). from=<index> instead of offset starts the page at that MusicBee row’s place in the sequence, that row first; from with offset is 400 INVALID_REQUEST. The answer adds view: "play" and viewTotal (the sequence’s length before paging); total stays the list’s length, offset is the position the page starts at, and currentIndex, playOrder, upcomingTotal and each row’s upcoming keep their meanings. Every row keeps its original list index (what /queue/play, /queue/move and DELETE /queue/{index} take) and, in this view only, carries kind (MusicBee’s codec name, e.g. ALAC audio file; "" when unknown). CUE rows keep their own cueTrack and cueStartMs in any order. 409 QUEUE_CHANGED when a native read is incomplete, its version/current track changes during capture or metadata collection, an index is outside the captured list, or from is not in the sequence: read it again — the answer is never shortened to hide it. 409 QUEUE_CURRENT_MISMATCH when MusicBee is playing a different file than its list’s current row (not while stopped): reading again does not clear it; it clears when MusicBee changes track. The MBXHub Shell’s cast reads MusicBee’s queue this way, so a Shell of this version needs a hub that has this view.

Complete native identity: GET /queue?view=play&identity=complete&limit=80 adds data.identity with schemaVersion: 1, complete: true, an opaque observation, nullable queueVersion, and rows containing every physical row's rawUrl and nullable rawTrackNo. Array position is the native index; duplicate paths remain distinct rows. The manifest is uncapped; only selected track metadata is paged. Start at offset zero. A later from or nonzero offset requires expectedObservation; it is also allowed at zero. Invalid combinations return 400 INVALID_REQUEST; changed context returns 409 QUEUE_CHANGED. Never combine pages from different observations. The token is equality context, not authorization or durable occurrence identity. Selected tracks echo both raw fields and explicitly include cueTrack and cueStartMs (both zero for ordinary files). CUE identity must resolve from exact source membership and native track number; ambiguity or invalid CUE metadata returns 409 CUE_IDENTITY_UNRESOLVED. The resolved url may differ from rawUrl. Native descriptors, current row and play order are rechecked after metadata hydration. Without this opt-in, existing response fields are unchanged.

// GET /queue?view=play&limit=3 - 30,001 rows, MusicBee at row 9999, shuffled (rows abbreviated)
{
  "success": true,
  "data": {
    "view": "play",
    "viewTotal": 4,
    "currentIndex": 9999,
    "total": 30001,
    "upcomingTotal": 3,
    "playOrder": [25000, 10000, 30000],
    "offset": 0,
    "limit": 3,
    "tracks": [
      { "index": 9999, "url": "C:\\Music\\current.mp3", "upcoming": false, "kind": "MPEG audio file" },
      { "index": 25000, "url": "C:\\Music\\next.flac", "upcoming": true, "kind": "FLAC audio file" },
      { "index": 10000, "url": "C:\\Music\\after-next.m4a", "upcoming": true, "kind": "ALAC audio file" }
    ]
  }
}

What one Undo would reverse right now. A read: needs no write permission and changes nothing; returns 404 when Undo History API access is disabled. Returns available; when it is true, also id, kind (queue | volume | mute | ban | rating | love | skip) and description. Send the id back as expectedId so the POST can only reverse what you showed.

// Nothing to undo:
{"success": true, "data": {"available": false}}

// Something to undo:
{
  "success": true,
  "data": {
    "available": true,
    "id": 42,
    "kind": "volume",
    "description": "volume 40 → 12"
  }
}

Reverse the entry on offer. Optional body {"expectedId": n}: when present, only that entry may be reversed. No body means the newest entry on offer. Each kind is gated by the permissions needed for its reversal: queue requires all three Add, Remove and Reorder permissions because restoration rebuilds the upcoming queue; volume and mute require player volume, skip requires player playback, ban requires shuffle (as POST /banlist), and rating and love require the library tag-edit switch. Refusals leave the entry on offer.

// POST /undo
{"expectedId": 42}

// Response:
{"success": true, "data": {"message": "Volume back to 40", "kind": "volume"}}

The action journal, newest first, automatic and undone entries included. A read: needs no write permission; returns 404 when Undo History API access is disabled. Query: ?limit= 1–200 (default 50; anything else answers 400 INVALID_LIMIT), ?address= only the entries made from that client address. Each entry: id, kind, origin (user | automatic), source (unknown | webApp | workbench | api | musicBee | autoQ | undo), clientAddress, clientName, description, undone, at (UTC). clientAddress and clientName are absent when the client is not known — changes made in MusicBee’s own window carry none, and a name is only ever one the hub has observed. Descriptions only: no track paths or file URLs. Answers 503 NOT_READY while MBXHub is starting up.

// GET /actions?limit=2
{
  "success": true,
  "data": {
    "actions": [
      {
        "id": 43,
        "kind": "queue",
        "origin": "automatic",
        "source": "autoQ",
        "description": "AutoQ added 3 to the queue",
        "undone": false,
        "at": "2026-09-22T18:04:11Z"
      },
      {
        "id": 42,
        "kind": "volume",
        "origin": "user",
        "source": "webApp",
        "clientAddress": "192.168.1.20",
        "clientName": "Living room tablet",
        "description": "volume 40 → 12",
        "undone": true,
        "at": "2026-09-22T18:04:02Z"
      }
    ]
  }
}

Query library with ?query=, ?artist=, ?albumArtist=, ?album=, ?genre=, ?people=, ?sort=, ?include=, ?roles=.

The url field is the track's identifier. It is the file path as MusicBee holds it on the host — a Windows path such as C:\Music\Artist\track.mp3, not a file:// URI — resolved on the host and never opened by the client. Pass it back verbatim wherever a track is named (/stream/, /queue/add, /playlists), percent-encoded in a path segment. total counts tracks after CUE expansion and is the same for every page size, ?limit=1 included.

v0.5.3.4 — ?people= on album expansion. When ?album=Y&people=X is set the post-filter probes MB's full role-union per track — Artists (144 — Artist + Performer + Guest + Remixer), Composer (43), and Conductor (45) — rather than relying on the ArtistPeople XmlFilter alone. The XmlFilter omits the GuestArtist role bucket, so a track tagged with the queried person as guest (e.g. David Guetta — The Whisperer (feat. Sia)) was previously dropped from expansion even though the album-by-artist count showed it. Whole-library ?people= (no ?album=) still uses the fast ArtistPeople XmlFilter path; pure-guest credits won't surface there but are reachable by drilling into the specific album.

v0.5.3.4 — ?include=<TagName>. Each returned track row carries extraField + extraValue with the per-track value of the requested tag. Accepts any tag from the 48-tag customSorts allowlist: Custom1..Custom16, Virtual1..Virtual25, Year, OriginalYear, SortAlbum, SortAlbumArtist, SortArtist, SortTitle, SortComposer. Unknown values are silently ignored. Used by browse.html to surface the active custom sort's per-track value when expanding an album under a custom-* sort.

v0.5.3.4 — ?roles=true. Adds every per-track role-credit field MB tracks separately: artistsRole (145), performers (146), guests (147), remixers (148), composers (43), conductors (45), artistsUnion (144 — the full role-union). Raw strings preserved (mixed separators across tag implementations). Default off so regular dashboard queries don't pay for the extra Library_GetFileTag reads; only paid for when explicitly requested.

// GET /library/files?artist=Breaking%20Rust&limit=10
{
  "success": true,
  "data": {
    "total": 42,
    "offset": 0,
    "limit": 10,
    "tracks": [
      {
        "url": "C:\\Music\\Breaking Rust\\track.mp3",
        "title": "Love Don't Live Here",
        "artist": "Breaking Rust",
        "album": "Greatest Hits",
        "duration": 234000
      },
      // ... more tracks
    ]
  }
}

Full-text search: ?q=search+term&sort=alpha (searches title, artist, album, genre; diacritic and punctuation normalized so "cafe" matches "Café" and "acdc" matches "AC/DC"). Two matching modes:

• strict (default) — the typed phrase must appear as a contiguous run of whole words in a single field (title, artist, album, or genre). "st anger" matches the album "St. Anger" (normalizes to the same phrase) but NOT "Stranger", "Strange Anger", or a track whose title contains "Anger" while its album contains "Story."
• substring — loose matching, any query word appearing anywhere as a substring passes. "anger" matches "Stranger."

The default mode is controlled by the Library.DisableStrictSearch setting (false by default = strict). Override per-call with ?substring=true|false. The response payload includes a mode field echoing which mode was used.

v0.5.3.0: DSL auto-detection is on by default (library.search.dsl.enabled = true). Qualifier syntax (artist:, album:, genre:, year:, rating:, fmt:, range / boolean / grouping operators) routes through SearchDslParser automatically when detected; plain free-text queries take the strict/substring path as before. Force per-call with ?dsl=true; set library.search.dsl.enabled = false to require the explicit opt-in. Cheat sheet at GET /library/search/syntax.

Unreleased — any-field search. The DSL field registry now covers every MusicBee custom slot: custom1:…custom20: translate to a Field="CustomN" condition (e.g. custom7:live; Custom17–20 arrived with MusicBee 3.5). Combine with existing qualifiers as usual (albumartist:"various" custom7:live). Mood-position filtering uses the first-class arousal:/valence: range qualifiers (0–1, e.g. arousal:>0.7) — see the qualifier table above.

v0.5.3.0 backstop: queries shorter than search.live.minQueryLength (default 2) return 400 QUERY_TOO_SHORT with body { "error": "Query must be at least N characters (got M)." }. Single-char walks visit every track on a 200k library (~4 s) and stall every other MB-API consumer for the duration of the cursor lock; the backstop protects fleet-wide responsiveness from runaway non-conforming clients (curl, scripts). Set search.live.minQueryLength = 0 to disable.

v0.5.3.0. Returns the DSL grammar as JSON (qualifiers, operators, worked examples). Authoritative source — the reference below is rendered from the same data shape. Used by Cmd+K's cheatsheet and any other client surfacing DSL syntax to users.

Response shape: { version, qualifiers: [{ name, type, allowsRange, allowsOperators, filterable, mapping, enumValues }], operators: [{ symbol, description }], examples: [{ query, description }] }. filterable (bool) marks the qualifiers the AutoQ candidate filter can evaluate — a filter-scoped client derives its allow-list from this flag rather than hardcoding one.

Query DSL Reference

The DSL layers on top of free-text search: every plain word still matches normally, qualifiers narrow the result, operators compose. Auto-detected on /library/search and /search when library.search.dsl.enabled = true (default); force per-call with ?dsl=true.

Qualifiers

Operators

Examples

Notes

• Default composition is AND between terms. Use OR (or lowercase or) for disjunction; parentheses for grouping.
• Where a grouped query runs. A query that is only a group — genre:rock OR genre:metal — runs entirely in MusicBee's own engine. Put a group beside another condition — artist:davis (genre:rock OR genre:jazz) — and the group is evaluated here instead, because MusicBee silently drops the sibling condition when a group sits next to it (measured 2026-08-18: artist:davis matched nothing on its own, yet the combined query returned 3385 tracks). The results are the same either way; the difference is that the second shape is capped, and a query producing more candidates than library.search.dsl.maxPostFilterCandidates answers 413 POST_FILTER_CAP_EXCEEDED rather than quietly returning the wrong set. Add a selective condition, or write the group on its own.
• Free-text terms still work alongside qualifiers — radiohead year:>=2000 filters Radiohead tracks from 2000 onward.
• Post-filter qualifiers (mood, playlist, lyric) run after the candidate set is fetched, so they're capped by library.search.dsl.maxPostFilterCandidates (default 5000).
• Unknown qualifiers return 422 INVALID_DSL with a parse position and Levenshtein-based “did you mean” suggestions.
• Date format: ISO (2025-01-01), relative (now-7d, now-30d), or named alias from search.dsl.dateAliases (defaults: lastweek = now-7d, lastmonth = now-30d, thisyear = now-365d; hand-editable, read on every query). Relative dates and aliases are resolved to a calendar date before MusicBee sees them. Any other spelling MusicBee reads as a date is passed through (2026/09/11, 9/11/2026, Sep 11 2026 — the machine’s own date format decides day-first or month-first). A value that is not a date (lastwek, 20260911) answers 422 INVALID_DSL naming it; before 2026-10-23 such a value, and every now-Nd or alias, silently matched the whole library.
• DSL result rows carry dateAdded and dateAddedSort — the raw MusicBee DateAdded string (the same value GET /library/file/{url} returns) and the same moment as yyyy-MM-ddTHH:mm:ss, or "" when it could not be read — so a client can order query-backed rows newest-first without a second call per track, and without running Date.parse over a locale string it cannot interpret the same way in every browser. On /library/search?dsl=true only; the non-DSL search rows and /library/files keep the shape they have.

v0.5.3.0 federated search. Runs typed buckets (tracks / albums / artists / playlists / saved) in parallel and returns a unified response with cursor pagination on the tracks bucket, facet counts, and a top-hit. Backs the Cmd+K palette and (v0.5.3.0+) the dashboard search bar, player.html, browse.html, and explore.html.

DSL routing (v0.5.3.0 post-launch): /search auto-detects DSL queries the same way /library/search does — qualifier colons (year:, rating:, etc.), .. ranges, >/< comparisons, OR , leading - exclusion. When detected and Search.Dsl.Enabled=true (default), the query routes through the DSL pipeline and the response carries mode: "dsl". Per-call ?dsl=true still works as an explicit opt-in. Plain free-text queries continue to use strict/substring mode as before. Tracks bucket is sorted by match-strength score (title > album > artist, with prefix-match bonus) so the most-relevant result appears first regardless of mode.

Params: ?q=&buckets=tracks,albums,artists,playlists,saved&limit=N&cursor=opaque. Cursors are opaque and TTL-checked; stale → 410, malformed → 400, query-mismatch → 400. Opaque is not signed — the payload is base64url JSON any caller can read and mint, and nothing checks that it came from here. That is deliberate: the cursor is advisory, ?offset= reaches exactly the same rows, and pagination is not an access boundary. Treat a cursor as a position, never as a permission. Same QUERY_TOO_SHORT backstop as /library/search. v0.5.3.0: per-bucket ?limit= hard cap raised from 200 to 500 (browse.html aggregates client-side over the tracks bucket and needs the headroom).

Artists bucket (2026-10-29). The artists bucket is always one row per person: rows come from MusicBee’s artists collection (the artists key tag), split on ; and merged case-insensitively with trackCount summed — timbaland finds Timbaland on every install, whatever the Browse setting splitArtists says (that switch governs /library/artists and /library/genres only; a search names a term). A split part is kept only when its name matches the query by the same word-prefix rule as the rest of search — strict by default, so timb finds Timbaland and ranger does not find Stranger; ?substring=true loosens it — a track that matched by title does not put its people in this bucket, and nothing is regex-split; MusicBee’s Multiple Artist Splitter decides where a name ends. Every consumer of the bucket (the Cmd+K palette included) sees the same rows. The bucket has its own page size: ?artistsLimit=N (optional; default = limit; same clamp; artists bucket only), because each kept row costs one album lookup — browse.html asks artistsLimit=50 beside limit=500, and every bucket’s limit field echoes the page size it ran with. The envelope carries splitArtists (boolean, always true: the shape this payload carries, kept because clients read it), and every tracks-bucket row carries artists (string array: the people on the track per MusicBee’s own collection — MultiArtist, else Artists, else the displayed artist) beside the unchanged artist string. Both ride the DSL path too. browse.html builds its search Artists section as the artists bucket plus the people of the matched tracks (their artists), so a track that matched by title still credits its people, one row each — a search never shows a composite row beside a split one.

v0.5.3.0. Live engine + index state snapshot. Currently reports engine: "mb" (FTS5 substrate dropped during the post-decouple harvest; seam preserved for future engines).

One row per value of a field, largest first — the view behind /pages/slices.html. Params: ?by=genre|year|decade|rating|mood (required; anything else is 400 BAD_FIELD), &top= how many values get a preview row (defaults to slices.topN, clamped to 1–200), &preview= covers per row (defaults to slices.rowLength, clamped to 0–200, where 0 means every album in the value). top and preview come back clamped, not as they were sent. total is the number of distinct values, i.e. values.length + more.length; everything past top lands in more as name+count for the page’s More… list. Each preview row is exactly a /library/albums/detailed row, so artwork and verbs are the existing ones. Computed over the in-memory album index.

Which row an album lands in. genre: every genre tagged on the album, so a multi-genre album is in several rows — and an album with no genre is in no row, because genre has no missing bucket. year: the first four digits of the album’s Year tag, or "Unknown". decade: that year floored to ten and suffixed, e.g. "1990s", or "Unknown". rating: the album-rating tag when it is set, otherwise the mean of the album’s rated tracks rounded half-up, otherwise "Unrated". mood: the mood channel most of the album’s analyzed tracks fall in (ties break by channel name), or "No mood data" when none is analyzed. Values sort by album count descending, then by name; the missing bucket ("Unknown" / "Unrated" / "No mood data") always sorts last. Preview albums are newest-added first, then by name.

by=mood is the one expensive field — one channel lookup per track — so the per-album tally is cached and thrown away when the album index publishes a new snapshot. A mood source that throws answers 500 rather than reporting the whole library as having no mood data.

// GET /library/slices?by=genre&top=2&preview=1
{
  "success": true,
  "data": {
    "by": "genre",
    "total": 87,
    "top": 2,
    "preview": 1,
    "values": [
      {
        "value": "Rock",
        "albums": 412,
        "preview": [
          {
            "name": "The Dark Side of the Moon",
            "count": 10,
            "firstTrackUrl": "C:\\Music\\Pink Floyd\\Dark Side\\01.flac",
            "year": "1973",
            "dateAdded": "12/15/2025 2:32 PM",
            "dateAddedSort": "2025-12-15T14:32:00",
            "albumArtist": "Pink Floyd",
            "sortAlbumArtist": "Pink Floyd",
            "virtualKind": null
          }
        ]
      },
      { "value": "Jazz", "albums": 188, "preview": [ /* ... */ ] }
    ],
    "more": [
      { "value": "Ska", "albums": 7 }
    ]
  }
}

Evaluate a MusicBee expression: ?expression=<Artist> - <Title>&fileUrl=C:\Music\track.mp3. If fileUrl is omitted, evaluates against the currently playing track. Returns {expression, fileUrl, result}. Supports MusicBee template syntax (<Artist>, $If(), virtual tags).

MusicBee’s built-in placeholder image for tracks with no artwork. Returns binary image data with appropriate content type. Cache-Control: 24h.

Albums for an artist with year, track count, firstTrackUrl for artwork, and virtualKind ("cue" | "setlist" | null). Params: ?albumArtist= or ?artist= (one required), ?sort=alpha|year|year-asc. ?artist= queries ArtistPeople (broader match), ?albumArtist= queries AlbumArtist (exact album credit).

// GET /library/albums/by-artist?albumArtist=Pink%20Floyd&sort=year
{
  "success": true,
  "data": {
    "albumArtist": "Pink Floyd",
    "total": 3,
    "sort": "year",
    "albums": [
      {
        "name": "The Dark Side of the Moon",
        "year": "1973",
        "count": 10,
        "firstTrackUrl": "C:\\Music\\Artist\\Album\\track.mp3"
      }
    ]
  }
}

List radio stations from MusicBee’s Radio node.

// Response:
{
  "success": true,
  "data": {
    "total": 5,
    "stations": [
      {"url": "http://stream.example.com/radio", "name": "Jazz FM"},
      // ...
    ]
  }
}

List podcast subscriptions. Query: ?query=

Flat episode listing. Query: ?id= (feed URL). Use this when the subscription ID is a URL rather than a simple ID.

Overview bundle of the most common settings in one response.

// Response:
{
  "success": true,
  "data": {
    "storagePath": "C:\\Users\\...\\MusicBee",
    "skin": "Default",
    "windowBordersSkinned": false,
    "lastFmUserId": "your-lastfm-user",
    "webProxy": null
  }
}

Gracefully close MusicBee. Requires allowRemoteExit=true in settings for remote callers; localhost (request.IsLocal) is exempt when the request carries the X-MBXHub-Local header (any non-empty value — a caller-id requirement, not a secret: it identifies deliberate local callers, keeps browser pages from firing this cross-origin (no CORS preflight is granted for it), and is the hook for future per-caller allow/deny lists). A local call without the header follows the remote rules (allowRemoteExit). The Disable Features App Restart toggle blocks this endpoint entirely, even from localhost. A paired Shell's valid X-MBXHub-SAC signature stands in for the X-MBXHub-Local header and for nothing else: a remote caller still needs allowRemoteExit, and a signature that is presented and does not hold up — including on a hub holding no secret to check it against — answers 403 SAC_INVALID rather than falling through to the rules above.

Optional body to schedule a restart via Windows Task Scheduler before closing:

// Request (optional):
{
  "restart": true,   // schedule restart before closing (default: false)
  "delay": 22        // seconds to wait before restarting (default: 22, range: 1-300)
}

// Response:
{
  "success": true,
  "data": {
    "message": "MusicBee restarting in 10s",
    "restart": true,
    "delay": 22
  }
}

Restart MusicBee. Convenience alias for /app/exit with restart=true. Requires allowRemoteExit=true for remote callers; localhost (request.IsLocal) is exempt when the request carries the X-MBXHub-Local header (any non-empty value — a caller-id requirement, e.g. curl -X POST -H "X-MBXHub-Local: 1" http://localhost:8080/app/restart). A local call without the header follows the remote rules (allowRemoteExit). The Disable Features App Restart toggle blocks this endpoint entirely, even from localhost. A paired Shell's valid X-MBXHub-SAC signature stands in for the X-MBXHub-Local header and for nothing else: a remote caller still needs allowRemoteExit, and a signature that is presented and does not hold up — including on a hub holding no secret to check it against — answers 403 SAC_INVALID.

// Request (optional):
{
  "delay": 22   // seconds to wait before restarting (default: 22, range: 1-300)
}

Get shuffle cycle status

// Response:
{
  "success": true,
  "data": {
    "enabled": true,
    "totalTracks": 1000,
    "playedCount": 250,
    "remainingCount": 750,
    "percentComplete": 25.0,
    "cycleStarted": "2024-01-01T00:00:00Z"
  }
}

Get list of banned tracks. Query: ?offset=&limit=

// Response:
{
  "success": true,
  "data": {
    "total": 5,
    "offset": 0,
    "limit": 50,
    "tracks": [
      {
        "url": "C:\\Music\\corrupted.mp3",
        "reason": "Audio corruption detected at 2:30",
        "bannedAt": "2024-01-01T12:00:00Z"
      }
    ]
  }
}

Get list of all influences. Query: ?offset=&limit=

// Response:
{
  "success": true,
  "data": {
    "total": 2,
    "offset": 0,
    "limit": 50,
    "influences": [
      {
        "type": "--",
        "target": "Genre",
        "value": "Audiobook",
        "timestamp": "2024-01-15T10:30:00Z"
      },
      {
        "type": "++",
        "target": "Artist",
        "value": "The Beatles",
        "timestamp": "2024-01-15T10:35:00Z"
      }
    ]
  }
}

Get current track's genre/artist and any matching influences (for UI state).

// Response:
{
  "success": true,
  "data": {
    "genre": "Rock",
    "artist": "Pink Floyd",
    "genreInfluence": null,
    "artistInfluence": "++"
  }
}

Check if ARiA input simulation is enabled

Quick wake: move mouse + send Shift key to wake sleeping/locked PC

Trigger a MusicBee library scan (built-in, like Wake PC). Sends Insert to open the scan-folders dialog, then a focus-skipped Enter to confirm it. Assumes Insert is bound to scan-folders (MusicBee default).

Send keyboard input. Body: {"keys": "^a"} (Ctrl+A). Optional: {"keys": "%{F4}", "window": "Notepad"} to focus window first. Prefix keys with ! to send to the current foreground window without refocusing MusicBee.

SendKeys format: ^=Ctrl, %=Alt, +=Shift. Special keys: {ENTER}, {TAB}, {ESC}, {F1}-{F12}, {UP}, {DOWN}, etc.

DuckyScript format: CTRL ALT V, SHIFT F1, ALT TAB. Modifiers: CTRL, ALT, SHIFT. Special: WIN/GUI (opens Start Menu, standalone only - not a modifier).

Focus a window by title. Body: {"window": "Notepad"} (partial match, case-insensitive)

Check RemoteApp status. Always accessible.

Response:

{
  "configured": false,
  "supported": true,
  "rdpEnabled": true,
  "edition": "Professional",
  "enabled": false,
  "apiDisabled": false,
  "message": "RemoteApp not configured. Run 'MBXHub.exe remoteapp setup' to configure."
}

Download a .rdp file for connecting to MusicBee as a RemoteApp. Blocked when remoteAppApiDisabled is true.

Query parameters:

• hostname - Override the hostname in the .rdp file (defaults to request Host header)
• Any other query parameter is forwarded as an .rdp setting override (e.g. audioqualitymode=0, redirectprinters=1)

Response: application/x-rdp file download (MusicBee.rdp)

403 when remoteAppApiDisabled is true.

Visibility: Dashboard footer link requires remoteAppEnabled and remoteAppApiDisabled: false. Footer links are configurable via dashboardFooterLinks in settings.

App program: On Windows Client (Pro/Enterprise), the .rdp file uses the full executable path from the registry. On Windows Server, it uses the ||AppName alias for RDS published app lookup.

Forward an HTTP or HTTPS request to a LAN device. Only private IPs are allowed (RFC 1918).

Request body:

{
  "method": "GET",
  "url": "http://192.168.10.100/ipcontrol/v1/systems/current/sources",
  "body": {}
}

• method — HTTP method to use: GET, POST, or PUT
• url — Full URL of the target device endpoint. Scheme must be http or https, and the host must be a private IP address.
• body — Optional JSON body to forward with POST/PUT requests.

HTTPS targets: some LAN gear only exposes its control API over HTTPS with a self-signed certificate — WiiM streamers serve httpapi.asp on port 443 that way. Those targets work: https://192.168.10.100/httpapi.asp?command=getPlayerStatus is forwarded like any other. The certificate is not validated for proxied requests — not the chain, not the hostname, not the expiry. The connection is encrypted but unauthenticated, so anything on the LAN path could impersonate the device. That is a deliberate trade: without it, self-signed devices are simply unreachable. The relaxation applies to the proxied request only — every other outbound connection MusicBee and MBXHub make still validates certificates normally.

Response: The target device’s response is passed through verbatim (status code and body).

Errors:

• 400 — Missing or invalid request body, missing method/url fields
• 403 — Target URL is not a private IP (public internet proxying is blocked), targets MBXHub itself, or uses a scheme other than http/https
• 405 — Only POST is accepted on this endpoint
• 502 — Target device unreachable or timed out (see below), its reply failed part way, or its response is over 2 MB, success or error status alike (“Target device response too large (>2MB)”). Otherwise a device that answers with an error status is passed through with its own status and body, as above.

Stream an audio or video file. The path must be URL-encoded and must be a file in the MusicBee library.

Path parameter: URL-encoded absolute file path (e.g. /stream/C%3A%5CMusic%5Csong.mp3).

Range support: Send Range: bytes=N-M header for partial content (required for seeking). The server responds with 206 Partial Content and Content-Range header.

Supported formats: mp3, flac, m4a, mp4, ogg, oga, wav, opus, aac, wma, aiff, aif. Actual browser playback depends on codec support — FLAC works in Firefox/Chrome/Edge, WMA is not supported by any browser. The play page’s Listen Here mode probes canPlayType, and for a format the browser reports it cannot decode it asks for the converted stream below rather than refusing outright; when no conversion is available it names the format on the output chip.

Query parameter — ?compat=1: a statement that the caller cannot play the original, not a request for a particular format — the server chooses what to convert to. When format conversion is enabled and ffmpeg is available, the file is converted and the result served with Content-Length and range support, so seeking and CUE offsets still work; the conversion is cached, so a file converts once. Otherwise the request is refused and the caller falls back to reporting the format unplayable. Without the parameter, behavior is unchanged. Requires ffmpeg — see docs/ffmpeg-and-transcoding.md.

DELETE /system/transcode-cache: drops every cached conversion and returns { cleared: <count> }. The cache is derived data that rebuilds on demand, so this is a rebuild trigger rather than destruction — your library files are never involved. Two uses: evicting a conversion you suspect, which previously meant finding the directory by hand; and forcing a cold conversion so a test actually exercises ffmpeg, since a conversion check passes against a warm cache even with ffmpeg uninstalled. Answers 200 even when conversion is switched off — the cache can still hold files from when it was on, and refusing to tidy up because the feature is off would be perverse. A file being streamed right now is left alone and counted as not removed, rather than failing the sweep.

One page holds the audio — POST /listen-here/claim and GET /listen-here/holder: every page that can play audio in the browser has its own audio element, and two pages in two browsers cannot see each other. Without a referee, one page takes the music, a second takes it again, and you are left with sound from a page you are not looking at while the controls in front of you reach a different one. The hub is the referee. A page that takes the audio posts { "holder": "<id>", "page": "<path>" } — holder is an id the page makes up for itself, 1–64 characters of letters, digits, dash or underscore (anything else is 400 INVALID_HOLDER, because the id is echoed to every client). The answer is { holder, page, changed, previous }. When the holder changes, the hub broadcasts the ListenHereClaimed WebSocket event and every other page holding the audio lets go: it stops its stream and returns to speaker output without resuming or seeking MusicBee, which the new holder has just taken over. A page re-claiming what it already holds is not a change and broadcasts nothing, so claiming on every track is free. A live hold is exclusive. While the holder is still there, a claim from a DIFFERENT page is refused — nothing changes, and the answer names who has it. The audio is held until it is released, yielded, or abandoned, and nothing else takes it. A claim from the SAME holder is never refused, so a reload or a fresh activation of a page that already has the audio keeps it. Abandoned means no proof of life for 30 seconds: a claim and an accepted check-in both count, so a page that is sitting there with nothing playing still holds it. That window is the only exit that is not a deliberate act — it is what stops a crashed tab, a sleeping phone or a dropped wifi holding the audio for good. A page that closes cleanly does not wait for it, because it posts a release on the way out. The window is listenHereAbandonAfterSeconds (advanced; default 30, range 10–600, clamped), read on every claim so a change applies to the next one without a restart. Too short and a phone that sleeps loses the audio while still in use; too long and a crashed tab keeps every other client locked out. GET /listen-here/holder answers { holder, page, since, url, positionMs, playing, ageMs } (all absent when nobody has claimed) for a page that may have missed the event — a suspended mobile socket, or the HUD, which has no socket at all and asks every few seconds while it holds the audio. The holder is kept in memory only: a hub restart forgets it and nothing breaks.

The client id — mbxh_client: an id a browser client writes for itself into a cookie, and the browser then sends on every request. Shape is c- followed by 8–32 of [a-z0-9]; anything else reads as absent. It does two jobs. It is the stable part of the Listen Here holder id, so a page that reloads is still the same holder rather than a stranger asking for audio it already has — which matters now that a live hold is exclusive. And it lets per-client activity be grouped by client rather than by address, which conflates everything behind one NAT and changes with DHCP. It is not a credential and nothing is gated on it: it is per browser profile rather than per device, it is self-asserted, and clearing site data mints a new one. A caller that never loads a page — curl, a partner integration — simply has none and is identified by address exactly as before. All three routes change nothing in MusicBee and write nothing to disk, so they are classified with the reads, the same as /stream — whoever may play audio here may say that they are.

The hand-off — where the other page had got to: a claim may also say where the claiming page is, by adding "url" (the library path it is streaming), "positionMs" (file-absolute milliseconds) and "playing". When the holder changes and another page had the audio, the answer’s previous is { holder, page, url, positionMs, playing, ageMs }: where that page was, captured under the same lock that replaced it, so the page taking over can pick the track up there in the one round trip it already makes — instead of restarting it, or asking a room that has been sitting paused the whole time. ageMs is how old that report was when the claim was served; add it to positionMs if playing. Act on it promptly or not at all: an answer that arrives seconds late describes the moment of the press, and seeking a listener who has been playing since then is a jump, not a correction (the built-in pages ignore it after 2.5 s). A report needs both a url and a usable positionMs — a finite number, 0 or more. One without the other is dropped whole: it is never stored as 0:00, which would restart the track for the next page to take over, and it is never a reason to refuse the claim.

The check-in — POST /listen-here/progress: the holder says “I am here” with { "holder": "<id>", "url": "<library path>", "positionMs": 61000, "playing": true } and is answered { accepted, holder, page }. It is recorded only when the caller still holds the audio, and it can never take it: a page with no socket learns it lost the audio a few seconds late, and a check-in that could claim would steal the audio straight back from whoever just took it. A caller that is not the holder is told who is, so this doubles as the holder check — a page that is sounding sends it every few seconds in place of GET /listen-here/holder. accepted: false alone does not mean the audio was lost (a report with no usable position is not recorded either): let go only when holder names someone else.

Ownership and observation: claims may include an opaque activation ID (letters, digits, underscore or hyphen; 1–64 characters). A new browser-output activation receives an ownershipToken in its direct claim response; repeated claims for that activation retain it. Modern progress reports carry the token. Public holder reads and events never disclose it. POST /listen-here/release accepts { "holder": "<id>", "ownershipToken": "<token>" } and returns { released, reason }. Only the exact current pair releases ownership; a stale or duplicate pair returns released: false, reason: "not-current". Malformed bodies/IDs return 400. This uses the existing playback-access gate and neither ends a transfer nor changes MusicBee or settings. Page-exit release is best effort.

Optional observation and sink (browser or cast) in stream URLs and accepted claim/progress reports correlate a logical media load with its validated original file. readiness and lanBase are controller reports, not proof of reachability. The observation ID is not authorization. It survives sink readdress and ranges, changes for a new logical load, and does not alter the server transcode cache key.

Local console: MusicBee’s Client Management window shows current/recent file transfers and reported playback separately. End transfer targets a live operation ID; it may leave buffered sound or a later receiver request. Conflicts remain ambiguous; stale reports do not prove orphanhood. A recorded release/displacement of an exact ownership instance can label an associated cast orphaned, but never cuts it automatically. Management stays in WinForms; no remote administration endpoint is added.

Security:

• Path traversal (..) is blocked
• Only whitelisted audio extensions are served
• File must exist in the MusicBee library (verified via API)

Errors:

• 400 — Invalid path or non-audio extension
• 403 — File not in MusicBee library
• 404 — File not found or streaming disabled
• 416 — Range not satisfiable

The Cast receivers on this network: {receivers:[{id, name, address, model, castBuild}], scannedAt}. The list is kept for 60 seconds; ?rescan=1 scans again (about 4 seconds).

The local controller's state, not arbitrary sessions on discovered speakers. active can be true while a start is pending; it is not proof of loaded playback. queueMode is shared or dedicated; remoteQueuePolicy is fifo, lifo or always-tail. queueModeChanging and queueConfiguration report native configuration progress; they grant no write authority. phase is what a start is doing now: Preparing, Converting, Connecting or Sending, with steps that run at the same time joined with “, ” in that order ("Converting, Connecting"); null once the cast has started and whenever no start is running. Each change of phase goes out as a CastStatus event. skipped lists the tracks this cast passed over, oldest first, as [{url, title, reason}]: reason is convert (the hub could not convert it at the start) or play (the speaker could not play it); [] when there are none, and emptied when the next start begins.

Cast MusicBee’s queue, from the current track on, to one receiver. Body: {"receiverId": "<id from /cast/receivers>"}. Answers the cast’s state once the receiver has loaded the queue. An already loaded session owned by this controller is returned without reloading; a pending start or another active receiver returns 409 CAST_ACTIVE.

The first song resumes at MusicBee’s current position. For CUE songs the receiver gets the file offset plus that track-relative position, with the song’s own playback duration. A changed source or unreadable position fails the start instead of silently starting at zero. If conversion skips the current song, the next playable song starts at its own beginning.

The guarded /queue?view=play&identity=complete&limit=1 read supplies currentPositionMs from the same native snapshot as the source identity. A track change during capture or metadata hydration returns 409 QUEUE_CHANGED.

Reconnect: after a dropped channel, select the same receiver within two minutes to resume its retained controller queue. The Shell verifies the application, transport and media-session identities before granting controls. It sends no launch or queue load and does not read or pause MusicBee. A mismatch refuses with 409 CAST_RESUME_CHANGED or the occupied-session confirmation below; it never replaces playback automatically. Expiry, a different receiver, changed queue configuration or explicit replacement discards the retained model. This memory does not survive Shell exit.

resumeUntilUtc on an inactive status names that original deadline. A trusted Shell report keeps only the already-admitted speaker's existing audio/artwork allowance, capped at two minutes by the hub. It cannot admit another address or extend an earlier deadline; normal trust, route and ban checks still apply. A transient reconnect failure preserves the original queue and deadline for another attempt. Confirmed activity removes the temporary access deadline.

Occupied receiver: before conversion, launch or loading, the Shell makes a read-only observation. An occupied or paused receiver returns 409 CAST_TAKEOVER_REQUIRED with error.takeover:{receiverId, confirmation, expiresUtc, canJoin, applications:[{appId, displayName}]}. Present Cancel and Replace session, plus Join existing queue when canJoin is true. Keep Cancel as the keyboard default; never confirm automatically. Explicit replacement repeats start with the same receiver ID and takeoverConfirmation copied from the offer. The opaque value expires after 60 seconds, is single-use, and is bound to the receiver, observed session and authenticated Hub/Shell pairing. Permissions and session identity are checked again. Expired/replayed confirmation returns 409 CAST_TAKEOVER_INVALID; a changed session returns 409 CAST_TAKEOVER_CHANGED. Select again for a new decision. Malformed confirmation is 400 BAD_REQUEST; failed observation is 502 CAST_INSPECTION_FAILED and leaves the receiver alone. Policy denial is 403 CAST_TAKEOVER_DENIED. No public force or policy switch exists.

Replacement interrupts the existing session and loads this hub's queue. To control another MBXHub controller's authored queue, point the page at that hub. Join controls the receiver queue without discovering its source hub. The fresh observation cannot reserve the speaker against independent senders. These protections require the updated Shell; an older Shell cannot enforce them.

Converting first. MusicBee’s queue is read first. An empty queue can connect a MusicBee-owned destination without loading media. A nonnative empty start still fails (503 QUEUE_EMPTY) before launch/load; occupancy is checked so an existing live queue can offer Join. When the first track goes out converted (?compat=1, see Formats above), the hub converts it after receiver admission/launch, overlapping the hub announcement, at most 30 seconds in all for the tracks the start converts; past that the track is loaded as it is, and the speaker’s own fetch waits on the conversion. A track the hub proves it cannot convert (its /stream answers 503 TRANSCODE_FAILED) is skipped (skipped, reason: "convert") and the next one is tried, until one converts or needs no conversion; any other outcome, such as no answer or a refusal, loads the track as it is. Skipped tracks stay in MusicBee’s list. When none converts, the start fails with 500 CAST_FAILED “No track at the start of MusicBee's queue could be converted (N tried).” During a party with partyAllowStreaming off the hub answers /stream only to the speaker and to the paired Shell, whose request carries a Secure Access Channel signature the hub checks, so converting ahead works during a party; a guest still cannot stream, and a Shell that is not paired is refused like a guest (every track then loads as it is). With disableStreaming on, nothing is converted ahead, for the Shell included.

Time limit. The whole start has one 60-second ceiling in the Shell, counted from when the Shell receives it, the receiver scan included; past it the start fails with 504 CAST_TIMEOUT “the start did not finish within 60 s while <phase>” and is torn down. The hub waits 62 seconds for the Shell’s answer, after a separate status/configuration pre-read of up to 10 seconds. Cast Control waits 74 seconds for both steps and their response. A failed pre-read preserves the Shell’s error and sends no start command.

The step breakdown of a failed start. A start that fails once it has begun (not a refusal such as 409 CAST_ACTIVE or 404 RECEIVER_UNKNOWN) ends its error.message with the step breakdown, whatever the code, 409 CAST_ENDED for a stop that landed during the start included; the same text ends the Shell’s log line and, unless a stop ended the start, lastError. The breakdown names the receiver scan (scan) and then each step the start reached, in order, with its measured time; a step marked still running is where the start stalled: (scan 12 ms, Preparing 40 ms, Connecting 15020 ms still running). Converting can overlap the remaining Connecting work, so their times can overlap.

Body {"receiverId":"..."}, with optional takeoverConfirmation from the occupied-speaker offer. Attach to live Default Media Receiver playback without LAUNCH or QUEUE_LOAD. The receipt binds the application and media session; expired/changed receipts require another decision. 409 CAST_JOIN_UNAVAILABLE means no matching live session could be confirmed. Status includes joined:true, receiver queue metadata and currentItem.artworkUrl. Transport, existing-row Jump, Stop and Leave work. Enqueue, Play Now and queue configuration refuse with 409 CAST_JOINED_QUEUE. The joining MusicBee is not paused, mirrored or repositioned; no Listen Here hold, play accounting or new media allowance is taken. Add tracks through the original hub. Join uses the start ceiling and signed transport but does not apply this machine’s queue configuration.

Body: {"expectedSession":"..."}, the sessionId of the cast the caller is looking at (from status). A destination-aware caller can instead supply {"expectedDestination":"<32 lowercase hex characters>"} from status. At least one identity is required; if both are supplied both must match. A stale page cannot end a different destination. Without an identity the answer is 400; when that cast is no longer the current one, 409 CAST_SESSION_CHANGED and nothing is stopped. Stop media, tear down the owned receiver application, and close both Cast connections. Pause keeps the session and queue; Seek preserves paused state. Listen Here is released, and MusicBee is left paused on the source song and position the receiver was playing, including Dedicated mode. Placement verifies the source/CUE segment, pause and seek readback but cannot prove which repeated URL occurrence MusicBee selected. During a Play Now track, which is not in MusicBee’s list, MusicBee is left on the next MusicBee track after it (or the one before it when nothing follows), not on the Play Now track, at zero within that return song.

Leave the Shell’s Cast controller without stopping the receiver or moving MusicBee. Both virtual connections close; the controller queue and reconnect state are discarded. Playback of the receiver’s loaded queue and other senders continue. Shell exit uses Leave. No new AutoQ items are supplied by the departed controller.

Signed mediaAccessUntilUtc retains only this speaker’s existing audio/artwork access for the known remaining queue duration plus 20 minutes, capped at 24 hours by the hub. Repeated reports cannot renew it or grant another address; an earlier reconnect deadline still wins. Unknown-duration songs add no time to this allowance. The source hub must remain running. Updated hub and Shell versions are required; long pauses or repeated playback past the deadline may require a new active controller.

Transport on the receiver. previous restarts the track when it is more than 3 seconds in. Idle /cast/play captures the current MusicBee occurrence and performs fresh admission/load. Send the displayed expectedSession. If occupancy requires replacement, repeat Play with that same session and the offered takeoverConfirmation; do not start a second destination or offer Join for this native queue activation. Stop/Leave remains available while activation waits.

Select an existing receiver occurrence. Body: {"sessionId":"...","requestId":"...","itemId":123}. Use the current status's opaque sessionId and a positive receiver itemId from items; never use a MusicBee index or title. IDs are scoped to this cast. Supply a fresh request ID (see Request IDs above) per deliberate selection. The same request and target are never sent twice; a changed target conflicts. Answers current Cast status, not a claim that playback has advanced. The speaker's status determines the highlighted row.

400 BAD_REQUEST for invalid fields; 409 CAST_SESSION_CHANGED, CAST_ITEM_CHANGED or CAST_NOT_READY for stale or uncertain identity; 409 CAST_REQUEST_CONFLICT for request reuse with another target; 429 CAST_REQUEST_LIMIT while too much earlier work is unresolved; 409 CAST_REQUEST_INVALID or CAST_REQUEST_EXPIRED as described under Request IDs. A retry of an unconfirmed selection returns 502 CAST_SELECTION_UNCONFIRMED; a previously refused selection returns 409 CAST_SELECTION_REFUSED. Refresh status after a timeout; the controller reads the speaker back and does not automatically resend. The usual player, read-only, party and signed-forwarding checks apply.

Admit an ordered batch to the Shared controller queue. Body: {"sessionId":"...","requestId":"...","position":"next","tracks":[{"url":"<file path>"}]}. Use the current status session and a fresh request ID (see Request IDs above) per deliberate addition. position is next or last. The tracks array has 1–10,000 sources, within the 64 KiB body limit; each uses Play Now's URL/CUE fields. Admission records order before metadata lookup. The response adds receipt:{requestId, sequence, decision, occurrenceIds, effectivePosition, remotePolicy} to status. decision is accepted or duplicate; receipt occurrence IDs belong to the controller and are not receiver item IDs for /cast/jump.

An exact retry retains the same occurrences and applied policy. Reusing the request ID with different sources, CUE options or placement returns 409 CAST_REQUEST_CONFLICT. Stale sessions return 409 CAST_SESSION_CHANGED; a connecting controller can return 409 CAST_CONTROLLER_UNAVAILABLE; capacity is 429 CAST_REQUEST_LIMIT. New requests in Dedicated return 409 CAST_DEDICATED, or 409 CAST_MODE_CHANGING during a transfer. Exact accepted retries remain readable. A receipt is admission, not receiver playback confirmation. Unavailable metadata retains the request's position; refresh status after uncertainty.

Interrupt the current speaker track and play one track now (Shared mode only). Body: {"sessionId":"...","requestId":"...","url": "<file path>", "cueTrack": 2, "cueStartMs": 60000, "cueDurMs": 240000}; sessionId and requestId are both required: a body without both is 400 (“playnow needs both sessionId and requestId from the observed cast”), and a requestId that does not start with the status's admissionSequence is 400 too. Use the current status's session and a fresh request ID (see Request IDs above) per deliberate press. Nothing is made up for a caller that sends none: a retry has to be recognizable as the same press, and only the caller knows that it is. The status every verb answers carries sessionId and admissionSequence. cueTrack, cueStartMs and cueDurMs are for a CUE track only. With cueTrack above 0, cueStartMs is required (400 without it) and cueDurMs is optional: 0 or absent plays to the file’s end, and a negative or non-integer value is 400 (“playnow’s cueDurMs is a whole number >= 0”). The track is inserted after the speaker’s current item and started; MusicBee’s list is not written; the receiver interlude keeps the existing upcoming speaker queue behind it. From then on the track is a member of the speaker’s queue: next and previous move across it, and it leaves with the played history. Answers the cast’s state, like every verb. A second Play Now while the first is playing goes after it. A format the receiver refuses takes the refusal path above (sent converted once, else lastError). 400 without a url; 404 TRACK_NOT_FOUND for a file the hub does not have; 409 NO_CAST with nothing cast; 409 CAST_NOT_READY while the speaker’s current item is not known yet or the item after it has no receiver id yet (try again in a moment); 502 TRACK_UNREADABLE when the Shell could not read the track from the hub. Gated like the other verbs (read-only mode, a party); Dedicated refuses new Play Now writes with 409 CAST_DEDICATED. Play Now on the HUD and the play page calls this while casting.

The response adds receipt:{requestId, sessionId, sequence, decision, acknowledged, itemId} to status; every other field is unchanged. decision is accepted or duplicate; itemId is the inserted receiver item and appears only once it is known. A 200 can carry acknowledged:false: the insert's outcome is not confirmed yet, so refresh status rather than sending a new request. The request is recorded in the cast's command ledger before anything is sent to the speaker. A retry with the same IDs answers from the retained receipt and sends nothing to the speaker; reusing the request ID with a different url, cueTrack, cueStartMs or cueDurMs returns 409 CAST_REQUEST_CONFLICT. A retry of a refused request returns 409 CAST_SELECTION_REFUSED; of an unconfirmed one, 502 CAST_SELECTION_UNCONFIRMED. A stale session returns 409 CAST_SESSION_CHANGED. Every Play Now takes a place in the cast's bounded command ledger, shared with enqueue, jump and native selections; settled requests leave it as new ones arrive, and 429 CAST_REQUEST_LIMIT is answered only while too much is still unresolved. 409 CAST_NOT_READY is answered before the request is recorded: it uses no place, and the same IDs may be sent again once the speaker is ready.

Body: {"positionMs": 61000}, 0 or more, within the current track. Clamped to the receiver-reported duration when known, always within the queued CUE segment. Status canSeek requires the receiver's Seek command bit and, for Join, confirmed queue-item bounds. Sparse queue replies retain previously confirmed bounds for the same item; false or unknown refuses with 409 CAST_SEEK_UNAVAILABLE. Seeking preserves playing or paused state.

The receiver’s own volume and mute. Bodies: {"level": 0.25, "expectedSession": "..."} (0 to 1) and {"muted": true, "expectedSession": "..."}. expectedSession is the sessionId of the cast the caller is looking at and is required, as on /cast/stop: 400 without it, 409 CAST_SESSION_CHANGED when that cast is no longer the current one. The check is made again immediately before the command is written to the speaker.