MBXHub

volup/voldown - Adjust volume by 5%.
volup1/voldown1 - Adjust volume by 1% (fine control).

shuffle=enable, shuffle-off=disable both, autodj=start AutoDJ, repeat=cycle mode

love - Toggle love tag on current track.
rate/0 - Toggle bomb (don't play). Click on → click off.
rate/0.5-5 - Toggle star rating; 0.5 increments accepted (e.g. 2.5). Click to set, click same to clear.
ban - Ban track from shuffle, skip to next (undo: skip back within 10s).
setban - Set ban flag without skipping.

mood - Set AutoQ mood channel (form: mood=Energetic).
react/fire|heart|like|dislike - Submit reaction. Fire triggers queue refresh.
refresh-queue - Refresh vibe list and queue tracks.
influence/artist|genre/up|down - Thumbs up/down for artist or genre.

Play or queue a playlist (form: playlistUrl=...&action=now|next|last).

Dashboard layout, display toggles, and feature kill-switches are all configured in mbxhub.json. Full field list with defaults, types, and descriptions: GET /system/settings/schema or the config reference. Live feature state (except proxy) is exposed via GET /system/features. Section IDs for dashboardLayout.order and .hidden: status, search, nowplaying, rating, controls, volume, charms, mood, playlists, toggles, footer.

Now Playing Styles (nowPlayingStyle, default: "full"):

Client-side override: localStorage key mbxh_np_style overrides the server default per-device. Header button cycles through all styles. All styles have zoom-level overrides (67%, 50%, 27%). The compact style was removed in v0.5.2.3 — existing configs gracefully fall back to full.

Set pagesPath in mbxhub.json to customize the pages directory:

{
  "pagesPath": "C:\\MyCustomPages"
}

Default location: %APPDATA%\MusicBee\MBXHub\pages\

Set defaultPage to change the root URL redirect:

{
  "defaultPage": "/pages/player.html"
}

Options: /dashboard (default), /pages/player.html, /pages/play.html, /pages/partymode/, /pages/nowplaying.html, or any custom page.

Kiosk Mode: Lock the display to a single page/app. All navigation redirects to the default page.

{
  "defaultPage": "/pages/partymode/",
  "kioskMode": true
}

Multi-page apps work: sub-paths are allowed (e.g., /pages/partymode/ allows /pages/partymode/guest.html). API calls and resources still work. Only editable in mbxhub.json (not exposed via API).

Serves index.html from the pages directory

Serves any file from the pages directory (HTML, CSS, JS, images, fonts)

• /pages/index.html - Landing page listing available views
• /pages/player.html - Legacy (kept for bookmarks and default-page users; receives no new features — use /pages/play.html). Full-featured desktop player with:
  • Now Playing (artwork, title, artist, genre, lyrics)
  • Player controls (play/pause, prev/next, shuffle, repeat, volume, seek)
  • Browse panel (Artists, Albums, Genres, Playlists, Podcasts, Radio, Moods — empty categories auto-hidden)
  • Queue panel (Up Next with Now/Next/Last actions)
  • Vibe score badge, reaction buttons, mood channel selector
  • Influence thumbs, ARiA presets, Love/Ban buttons
  • Live WebSocket updates (including Reaction events)
  • Mobile tab bar (Now Playing / Browse / Queue), tablet 2-column, desktop 3-column with resizable panels
• /pages/nowplaying.html - Focused now-playing view with artwork, lyrics, and queue. Auto-stacks below 800px with accordion sections (Now Playing, Queue, Lyrics) — expanding one collapses the others
• /pages/browse.html - Library browser with 8 responsive tabs, drilldown navigation, fuzzy search with auto-search fallback (triggers server search when no inline matches), album art grid, video direct play, batch queue, and playlist picker
• /pages/config.html - Settings and configuration for dashboard layout and AutoQ parameters
• /pages/autoq.html - AutoQ Tuning Console with mixer-style sliders for scoring weights and normalization ranges
• /pages/mixer.html - Unified fader mixing surface: three independent faders for Player (MusicBee), Device (Windows audio), and Endpoint (network speaker) volume. Configurable default fader, mute controls, endpoint source selection
• /pages/explore.html - Album art explorer: browse albums as artwork with source filters, search, sort, image gallery, PDF booklets, play/queue. Accepts ?album=&artist= for seeding. Artist discography grid in expanded view. Expanded-view hero has paired close (×) and dashboard home (⌂) buttons — close stays on explore, home returns to /dashboard (home hidden in iframe-mode)
• /pages/play.html - Use MusicBee from a browser. Laid out like the MusicBee AMOLED skin: artist picker (left) with infinite-scroll + jump-on-letter typeahead, pluggable middle pane (Albums / Library / Now-Playing), upcoming-queue + now-playing card (right), full-width transport footer.
  • Transport: play/pause, prev/next, shuffle, repeat, AutoDJ, volume + mute, scrubber, love, 5-star rating, AutoQ mood select, AutoQ refresh, reaction buttons (fire / heart / like / dislike / ban) gated on AutoQ availability
  • + Add To Playlist dropdown beside love/stars — quick-curate the playing track to any playlist; “+ New Playlist…” creates one with the current track as seed; last-used playlist bubbles to the top
  • ARiA presets dropdown in the overflow flyout (auto-hides if ARiA isn't enabled)
  • Influence thumbs (artist + genre) on the right-column now-playing card — visible only when mbxq is reporting /influences/current
  • Global media-key shortcuts: Space = play/pause, ← = previous, → = next (skipped while typing in inputs)
  • Live WebSocket updates (TrackChanged, PlayStateChanged, PositionChanged, QueueChanged, VolumeChanged, ShuffleChanged, RepeatChanged) plus a 30s position-poll safety net that skips when the tab is hidden
  • Browser-side errors routed to mbxhub.log via /system/client-log (no console-only logging)
  • Responsive: 3-column desktop ≥1024px, slide-over drawer at 700-1023 landscape (sticky — click-outside no longer dismisses), single-column stacked <700px or portrait tablet with bottom sheet for queue/np
  • Tablet/phone overflow flyout collapses secondary controls behind a ▾ button; auto-closes after firing an action (sub-popovers like Add To and ARiA keep the flyout alive while open)
• /pages/components/dashboard.css — Dashboard stylesheet (~2,900 lines). Served as an external linked resource by /dashboard. Theme variables are injected separately in an inline <style> block ahead of this link; this file holds the bulk of dashboard styling (layout, transport, charm bar, command palette, theme designer, party banner, search results). Linked with ?v={version} for release-driven cache invalidation.
• /pages/components/dashboard.js — Dashboard client script (~2,800 lines). WebSocket lifecycle, transport handlers, theme designer, charm bar, partial-section reload, Cmd+K wiring. Loaded with defer by /dashboard after an inline <script> that defines the per-request _themeData JSON. Same ?v={version} cache-busting pattern.
• /pages/components/cmdk.html — v0.5.3.0 Cmd+K command palette. Self-mounting <style> + <dialog> + <script> fragment. XSS-safe (textContent only, no untrusted innerHTML). Federated search via /search, recents via /search/history with localStorage fallback. Actions are POSTs (Play/Pause/Skip/Volume, Start AutoQ radio) or navigations (Charms / Settings / Mixer / Player / Browse / Explore / ARiA). Settings nested under dashboardLayout.commandPalette.{enabled, openShortcut, showChip, recentLimit, bucketLimit, actions, enabledOnPages}.
• /pages/components/cmdk-bootstrap.js — v0.5.3.0 palette loader. Drop-in <script> include — loads search-shared.js then injects cmdk.html via DOMParser so embedded scripts execute. Self-mounting; degrades gracefully when search-shared.js is unreachable. Wired into dashboard, play.html, explore.html, nowplaying.html, and browse.html.
• /pages/search-shared.js — Search lifecycle helper. Provides MBXSearch.attachSearch for debounced typeahead with abort-on-keystroke (exposed as .abort() on the returned handle for v0.5.3.0+ callers that need to cancel in-flight fetches before navigation). Required by cmdk; usable standalone.
• /pages/components/shared.css — v0.5.3.0 shared frontend core. Cross-page styles consolidated from per-page duplication: CSS reset + box-sizing, prefers-reduced-motion rules, focus / focus-visible defaults, dual theme palettes (default + theme-quiet, light + dark), scrollbar styling, .album-art-placeholder, .hl highlight class, .empty-state. Linked first in each shell page's <head> so per-page styles can override.
• /pages/components/shared.js — v0.5.3.0 shared frontend core. Cross-page helpers under the MBXShared global namespace: setPageName / getPageName, clientLog (batched + sendBeacon-on-pagehide) + flushClientLog, esc (HTML-encode), DIACRITICS (char map ported from MusicBee's character map — union of the browse / explore / player maps, 1:1 char invariant preserved), normalize (iter-based: DIACRITICS lookup → lowercase → strip apostrophes → collapse non-alphanumerics to single spaces → trim; NFD form removed in the Option C foundation), findHighlightSpans(text, query) (returns Array<{start, end}> half-open ranges in ORIGINAL-text index space — walks normalized text, finds full-phrase + per-word occurrences, leaves HTML rendering to the caller so pages can wrap spans their own way), fmtDuration (ms → m:ss or h:mm:ss), connectWebSocket (subscribe + JSON parse + dispatch-by-event + auto-reconnect with capped backoff), urlHashOf(url) (22-char base64url SHA1-truncated hash of a file URL — used for /library/file/{urlHash}/* routes and ?trackUrl= deep links; byte-equivalent on secure and non-secure LAN-HTTP contexts). Loaded with defer by every shell page.
• /manifest.webmanifest — v0.5.3.2 PWA manifest. Returns application/manifest+json. Both name and short_name are templated with the host's advertised name — the discoveryName field in mbxhub.json, set via Plugin Settings → “Advertise on local network → Name”. The advertised name is independent from the machine's hostname: a host whose Windows computer name is living-room-pc but whose advertised name is “prod” serves name: "MBXHub - prod" (browser install dialogs / Manage apps UI) and short_name: "MBXHub - prod" (OS desktop / home-screen / app-drawer labels) — “living-room-pc” never appears in the install UI. If discoveryName is empty, the manifest falls back to the Windows computer name, and ultimately to the literal "host" if even that is unavailable. Trade-off: changing the advertised name updates both fields on the next manifest fetch — already-installed devices see the new label after one reinstall or manifest refresh. Standalone display, theme color matches the dashboard surface, icons array references /icons/icon-{192,512}.png plus maskable variants. Served with Cache-Control: no-cache (Chromium's installed-PWA “update on reload” path otherwise heuristically caches the manifest indefinitely). Note: PWA install itself is gated by browser policy to HTTPS or localhost; over plain LAN HTTP the manifest still drives iOS “Add to Home Screen” and Android home-screen pins (no service worker required for those), but the rich Chrome/Edge “Install as app” surface is unavailable.
• /pages/history.html — v0.5.3.2 Recently-played viewer. Day-range chips (24h / 7d / 30d / etc.) sourced from GET /library/recent?days=N. Track list shows title / artist / album / albumArtist plus playCount + skipCount columns; artist and album cells are clickable links into /pages/browse.html. Per-row P (Play Now) and L (add to MusicBee queue) buttons. Page-2 prefetch as the user scrolls. Backed by the /library/recent cache (10-min TTL, invalidated on TrackChanged). Footer link disabled by default.
• /pages/hubs.html — v0.5.3.2 Hub-switcher page. Renders the “Hub neighbors” list — other MBXHub instances this browser has reached recently, read from localStorage['mbxhub-hub-neighbors'] — plus a free-text host:port input fallback. Pure DOM, no innerHTML, no remote calls. Footer link disabled by default.
• /icons/{name} — v0.5.3.0 PWA icon set. Resolves the embedded MBXHub.Resources.icons.{name} and serves with image/png. Standard set: icon-192.png, icon-512.png, icon-maskable-192.png, icon-maskable-512.png, apple-touch-icon-180.png.

To customize pages:

1. Navigate to the pages directory (shown in MBXHub settings)
2. Edit player.html or create new HTML files
3. Refresh the browser - changes appear immediately
4. To reset to defaults, delete the pages folder and restart MusicBee

MBXHub serves /llms.txt - an AI-friendly API reference. Use it with Claude or any AI to generate custom pages:

1. Tell Claude: "Read https://mbxhub.com/llms.txt and build me a Party-On-Mode page - big artwork, guest queue requests, vibe controls"
2. Claude fetches the API cheat sheet (public URL works from any AI)
3. Claude generates code using relative URLs (/nowplaying, /player/play) that work on any MBXHub instance
4. Save to %APPDATA%\MusicBee\MBXHub\pages\
5. Open http://localhost:8080/pages/partyon.html

The generated code uses relative URLs, so it works on your local MBXHub without modification.

Plugin-managed (REST port + Shell SMTC port + UDP discovery) — one rule covers everything the plugin can see. Use the Settings → Firewall panel or CLI:

MBXHub.exe firewall add --name MBXHub --tcp 8080,8081 --udp 1900,3702,5353 --urlacl 8080,8081

Shell-only (SMTC port, added by Shell itself) — MBXHub.exe --install writes a MBXHub-Shell rule and URL ACL for smtc.port automatically; --uninstall removes it. You only need to run firewall commands manually if you skip --install.

Override the Shell SMTC port by editing smtc.port in mbxhub-shell.json. The plugin's firewall helper auto-adopts restPort + 1 as the Shell port; if you change smtc.port from that convention, open the new value manually.

Target

Endpoint Discovery

v0.5.3.6 — Setlist-aware skip. When the playing file carries a Comment-embedded setlist (the SL-TPS detector returns true on its Comment), /player/next and /player/previous navigate by setlist entry instead of by queue file. next seeks to the next entry's startMs; from the last entry it falls through to Player_PlayNextTrack. previous follows standard transport behaviour: within 2 seconds of an entry's start it seeks to the previous entry's startMs; after 2 seconds it restarts the current entry. From the first entry within the 2 second grace it falls through to Player_PlayPreviousTrack. Response carries scope: "setlist" + entryIndex (1-based) on setlist hits; falls back to the original { result: bool } shape for queue-file skips. Lookup re-parses Comment on each press with a 2 second share-window so consecutive button mashes don't re-parse but a user edit to the Comment is visible within ~2 seconds; track changes invalidate immediately.

PUT /player/volume accepts {"volume":50} (absolute) or {"delta":-5} (relative — resolved server-side against the current volume, clamped 0-100).

/player/update-play-statistics applies a caller-chosen countType (IncreasePlayCount, IncreaseSkipCount, NoChange) to a track (body: { "url", "countType"?, "disableScrobble"? }). Prefer /player/report-play below, which judges played vs skipped server-side. Returns 403 FEATURE_DISABLED when apiDisablePlayCountUpdates is on; gated by player access during party mode; shares the per-IP play-stat rate limit with /player/report-play.

Tag fields: TrackTitle, Artist, Album, AlbumArtist, Year, Genre, Rating, RatingLove, Comment, Composer, Conductor, TrackNo, DiscNo, Lyrics, Publisher

Properties: Bitrate, SampleRate, Channels, Duration, Size, DateAdded, DateModified, PlayCount, SkipCount, LastPlayed

Examples:

GET /nowplaying/tag?field=Artist        → {"value": "Breaking Rust"}
GET /nowplaying/tag?field=Album         → {"value": "Love Don't Live Here"}
GET /nowplaying/tag?field=Genre         → {"value": "Rock"}
GET /nowplaying/tag?field=TrackNo       → {"value": "3"}
GET /nowplaying/property?type=Bitrate   → {"value": "320"}
GET /nowplaying/property?type=Duration  → {"value": "234000"} (ms)
GET /nowplaying/property?type=PlayCount → {"value": "42"}

Returns album artwork as binary image or URL

Returns the current track's lyrics. Four response shapes:

• { hasLyrics: false, lyrics: null } — no lyrics and no fallback.
• { hasLyrics: true, lyrics, source: "lyrics" } — real MusicBee lyrics, no sibling comment.
• { hasLyrics: true, lyrics, source: "lyrics", comment } — real MusicBee lyrics with a sibling Comment tag. Clients can render a Lyrics/Comment toggle.
• { hasLyrics: true, lyrics, source: "comment", label } — fallback from the track Comment tag (great for concert setlists, album liner notes). label is the chip text shown above the body in the UI.

Both the sibling comment field and the fallback path are configured via the LyricsFallback section (Enabled, MaxDisplayChars, Label) and can be hard-killed via ApiDisableLyricsFallback.

/nowplaying/artist-picture-urls — returns a pictures array with src URLs (serveable via /nowplaying/artist-pictures/{index}) in addition to raw file paths.
/nowplaying/artist-pictures/{index} — serve current artist’s Nth picture as binary image (0-based). Content-Type auto-detected; Cache-Control: max-age=3600. Query: ?localOnly=true (default).

FFT spectrum and waveform data for visualizations

Current stereo peak and RMS levels (0.0–1.0). Returns {peak: [L, R], rms: [L, R]}. Requires MusicBee 3.6+ (API rev 58+).

// POST /queue/add - Add tracks to queue (position: "next" or "last")
{"urls": ["file:///C:/Music/song1.mp3", "file:///C:/Music/song2.mp3"], "position": "last"}
// or single track:
{"url": "file:///C:/Music/song.mp3", "position": "next"}
// Response: {"success": true, "data": {"result": true, "added": 2, "position": "last"}}

// POST /queue/playnow - Play track immediately
{"url": "file:///C:/Music/song.mp3"}

// POST /queue/play - Play track at index
{"index": 3}

// POST /queue/move - Move track in queue
{"from": 5, "to": 2}

Persist a query under a name and re-run on a schedule. Backed by mbxhub-search.json next to mbxhub.json. Disabled by default; enable via library.searchDsl.savedSearch.enabled. Disabled endpoints return 404 NOT_FOUND. Background SavedSearchScheduler ticks each saved search's interval, evaluates, diffs against last-match URLs, and broadcasts the SearchMatched WebSocket event when matches change.

Validation: name required (1–80 chars, unique per host case-insensitive → 409 on duplicate); query parsed via the DSL (422 INVALID_DSL on parse error with parse position).

Mutation routes (POST / PUT / DELETE / run) return 403 FORBIDDEN when ApiReadOnlyMode is set — kiosk deployments can’t have saved searches mutated by remote clients.

Server-side recent-search log shared by Cmd+K and any other search bar. Falls through to client localStorage if the endpoint is missing or returns 404.

GET ?limit=N — newest-first. limit defaults 20, caps at 200. POST body {query, source} — empty body clears (returns {cleared:true}). DELETE — wipe all entries.

POST and DELETE return 403 FORBIDDEN when ApiReadOnlyMode is set.

/library/albums/detailed returns albums with firstTrackUrl, year, dateAdded, and virtualKind ("cue" | "setlist" | null) for artwork lookups and sorting. virtualKind identifies CUE-split or setlist virtual tracklists; drives the CUE / SET LIST badge in browse and on the dashboard now-playing card. Eliminates per-album /library/files?limit=1 round-trips. Params: ?offset=&limit=

/library/album-artists returns distinct album artists. Params: ?offset=&limit=

/library/albums/unheard returns albums where all tracks have playCount=0. /library/albums/with-pdf returns albums containing PDF booklets. /library/albums/with-video returns albums whose folder contains a video file (derived from the Video library, Source Type 64, matched by folder). All support ?offset=&limit=

/library/inbox, /library/audiobooks, and /library/videos query MusicBee library categories (Source Types 4, 32, 64). Browse page shows these tabs only when non-empty (progressive reveal).

Note: URL-encode the file path in the URL (e.g., /library/file/file%3A%2F%2F%2FC%3A%2FMusic%2Ftrack.mp3)

// GET /library/file/{url} - Extended track metadata (includes playCount, lastPlayed, etc.)
{
  "success": true,
  "data": {
    "url": "file:///C:/Music/Artist/Album/track.mp3",
    "title": "Love Don't Live Here",
    "artist": "Breaking Rust",
    "album": "Greatest Hits",
    "duration": 234000,
    "albumArtist": "Breaking Rust",
    "genre": "Rock",
    "year": "2024",
    "trackNo": "3",
    "discNo": "1",
    "rating": "4.5",
    "composer": "J. Smith",
    "bitrate": "320",
    "format": "MPEG Audio",
    "sampleRate": "44100",
    "playCount": 42,
    "dateAdded": "2024-01-15",
    "lastPlayed": "2024-01-20"
  }
}

// PUT /library/file/{url} - Update metadata (fields: title, artist, album, albumArtist, genre, year, trackNo, discNo, composer, comment, rating)
{"rating": "5", "comment": "Great track!"}
// Response: {"success": true, "data": {"result": true, "updated": ["rating", "comment"]}}

// POST /library/artwork/batch - Batch artwork fetch (max 50 URLs per request)
// Request: {"urls": ["D:\\Music\\track1.mp3", "D:\\Music\\track2.flac"]}
// Response: {"success": true, "data": {"D:\\Music\\track1.mp3": "data:image/jpeg;base64,/9j/...", "D:\\Music\\track2.flac": null}}

// POST /library/commit - Commit pending tag changes to file
// Use after batching Library_SetFileTag RPC calls
// Request: {"file": "D:\\Music\\track.mp3"}
// Response: {"success": true, "data": {"result": true}}

/artwork-count returns 0 if the file has no embedded artwork, 1 otherwise. Internally probes up to 20 embedded-artwork locations (MusicBee returns the same cover at multiple locations — EmbedInFile, LinkToSource, FolderThumb —) and picks the largest byte-size as the canonical image; subsequent /artwork?index=0 requests serve that best variant. Cached per fileUrl. /pdf serves the PDF booklet from the track's album folder. /has-pdf checks existence without downloading.

v0.5.3.5. When a track's Comment tag contains a time-coded set list (≥3 monotonically increasing entries — common on bootlegs / live broadcasts / podcasts), these endpoints surface the parsed entries and let one click write a real CUE sidecar. Parsing follows a formal grammar (SL-TPS v1.0).

Accepted line formats. Each candidate line is tested independently (multiline-anchored regex, ^…$), with an optional leading bullet (- / • / *) and an optional decorative index prefix (digits, optional . or ), optional - / en-dash / em-dash). After those, the line must match one of two core shapes:

• Time-first: [HH:]MM:SS [optional separator] TITLE
• Time-last: TITLE [optional separator] [HH:]MM:SS

The optional separator between time and title accepts -, –, —, or : followed by whitespace (the colon variant is common on YouTube-comment paste-throughs, e.g. 02:46 : Last Train). The timestamp itself may also be wrapped in parens, e.g. (0:11) Live In The Moment — common on YouTube / Reddit comment setlists; title-internal parens (e.g. Don't Look Back In Anger (Oasis cover)) are preserved verbatim. Hours are optional; minutes 1-2 digits; seconds exactly 2 digits. Worked examples that all match: 0:40 - Catch These Fists, 0:00:00 Sweet Lies, 01 - The SoundMaker - 00:00, 1. Amyl And The Sniffers - Foo 00:00, Man Made Of Meat 01:09, 02:46 : Last Train, (0:11) Live In The Moment. Index prefixes in the text are decorative; the parser assigns sequential 1, 2, 3, … from match order (intrinsic ordering per spec §5). Lines that don't match (URLs, freeform notes, blank lines) are silently skipped — they don't kill detection, they just don't contribute to the count.

GET /library/file/{urlHash}/setlist returns { fileUrl, fileDurationMs, entries:[{index, startMs, title, rawTime, cueTime}], trailingNotes, parsedAt, extractedCueExists, extractedCuePath }. Each entry carries the raw matched timecode (rawTime, e.g. "0:40") and the CUE MM:SS:FF form (cueTime, e.g. "00:40:00", 75 fps) so consumers don't re-derive them. fileDurationMs is the parent file's length so the Tracklist UI can compute per-entry durations including the trailing entry — 0 when a paired CUE exists (signals: trailing-duration math unreliable). 404 NO_SETLIST if the Comment doesn't match the heuristic.

Computing {urlHash}. The input is the track's url — the url field returned by /library/files or /nowplaying. The hash is: SHA-1 of the UTF-8 bytes of that exact url string → keep the first 16 bytes → base64-encode → make URL-safe (+→-, /→_, strip trailing =). Result is a 22-char string. Example pseudocode: base64url(sha1(utf8(url))[0:16]). Browser clients can call MBXShared.urlHashOf(url) (shared.js), which returns the identical value on both secure and non-secure (LAN HTTP) contexts.

POST /library/file/{urlHash}/extract-setlist-cue, body { overwrite: bool } (default false): parses the Comment, builds a real CUE sidecar at <audio-basename>.cue (UTF-8 with BOM), written atomically (temp → replace → .bak). On success the album index is invalidated so the next browse / search / now-playing read returns the virtual tracks. Errors: 409 CUE_EXISTS when a sidecar already exists and overwrite=false (client switches CTA to “Replace existing CUE”), 400 NO_SETLIST, 500 WRITE_FAILED.

Consumers: ?setlist=hint on /library/files emits hasSetlist:bool per row (browse drilldowns surface the SET LIST badge). /nowplaying emits hasSetlist for the current track (drives the dashboard SET LIST chip, the Tracklist tab on nowplaying.html, and the wavescrubber chapter ticks on play.html — the latter pulls entries from /library/file/{urlHash}/setlist when MB is still playing the parent file as a single item, before CUE extraction virtualises it). After extraction the album's virtual tracks expose cueStartMs per row.

Duration sanity: a setlist's last timestamp must fall before the file's duration (catches Comments pasted from a different recording); otherwise detection returns false. Concurrent extracts can't race (per-call temp file) and failed writes don't leak it. Requires library-tag write access, so PartyMode guests cannot write.

Deep-link query params (no new endpoints): /pages/nowplaying.html?tab=tracklist opens the standalone page with the segmented control switched to Tracklist on first successful setlist load; used by the dashboard SET LIST badge. /pages/play.html?np-tab=tracklist opens the full-player chrome and propagates &tab=tracklist to the middle-pane NP iframe — used when DashboardLayout.liveSetBadgeTarget is set to "play" (default "nowplaying"). /pages/browse.html?album=&artist=&trackUrl=<hash> scrolls the matching row into view with a brief accent pulse after the drilldown renders; generated by the Now Playing right-click “Copy deep link”.

/library/artist/{name}/pictures — returns a pictures array with src URLs (serveable via /library/artist/{name}/pictures/{index}) in addition to raw file paths. Query: ?localOnly=false.
/library/artist/{name}/pictures/{index} — serve artist picture by 0-based index as binary image. Content-Type auto-detected (falls back to image/jpeg for MusicBee cache files); Cache-Control: max-age=3600. Query: ?localOnly=true (default).

Recently played tracks sorted by last played descending. Params: limit (1–200, default 50), offset (default 0), days (1–365, default 30). Returns tracks with lastPlayed, playCount, skipCount fields.

Video files from MusicBee’s Video library node (Source Type 64). Returns {total, videos: [{url, title, artist, album, kind, duration}]}. Title falls back to filename when tag is empty. Stream video files via /stream/{url}.

/library/files/raw — raw MusicBee file data without CUE processing. Optional ?album= filter. Max 50 results.
/library/cuetest — test CUE track resolution for a query. Param: ?query=

// GET /playlists - List all playlists
{
  "success": true,
  "data": {
    "total": 5,
    "playlists": [
      {"url": "playlist://Favorites", "name": "Favorites", "trackCount": 120},
      {"url": "playlist://Workout", "name": "Workout", "trackCount": 45},
      // ... more playlists
    ]
  }
}

// POST /playlists - Create new playlist
{"name": "New Playlist", "folder": "", "files": ["file:///C:/Music/song1.mp3"]}
// Response: {"success": true, "data": {"url": "playlist://New Playlist", "name": "New Playlist", "trackCount": 1}}

// PUT /playlists/{url} - Replace playlist contents
{"files": ["file:///C:/Music/song1.mp3", "file:///C:/Music/song2.mp3"]}

// GET /playlists/{url}/files - Get playlist tracks (supports pagination: ?offset=0&limit=50)
{
  "success": true,
  "data": {
    "total": 120,
    "offset": 0,
    "limit": 50,
    "tracks": [
      {"index": 0, "url": "file:///...", "title": "Song", "artist": "Artist", "album": "Album", "duration": 234000},
      // ... more tracks
    ]
  }
}

// POST /playlists/{url}/files - Add tracks to playlist
{"urls": ["C:\\Music\\song.mp3"]}

/podcasts/{id}/episodes/{index} — get a specific episode by numeric index.

• GET /settings/storage-path — Persistent storage path
• GET /settings/skin — Current skin name
• GET /settings/skin-element-color — Skin color. Query: ?element=SkinSubPanel&state=ElementStateDefault&component=ComponentBackground
• GET /settings/window-borders-skinned — Whether window borders are skinned
• GET /settings/lastfm-user — Last.fm user ID
• GET /settings/web-proxy — Web proxy configuration

• GET /settings/field-name?field={MetaDataType} — Display name for a metadata field (e.g. TrackTitle, Custom1)
• GET /settings/data-type?field={MetaDataType} — Data type for a metadata field
• GET /settings/value?id={SettingId} — Raw MusicBee setting by ID (e.g. CompactPlayerFlickrEnabled). 400 with the full valid-ID list if unknown.
• GET /settings/convert-command?codec=Mp3&quality=HighQuality — File-conversion command line for a codec/quality pair

Party Mode settings are configured in MusicBee via Settings → Network → Party Mode...

Protect Metadata: When enabled, blocks POST /dashboard/love, POST /dashboard/rate/{N}, and PUT /library/file/* tag edits for everyone during the party. Use this to prevent guests from permanently modifying your library ratings. The setting also blocks the DJ—toggle it off temporarily if you need to make edits.

Built-in pages at /pages/partymode/:

• index.html - PIN + nickname entry (guest join page)
• guest.html - Browse 7 tabs (Albums, Artists, Genres, Playlists, Podcasts, Radio, Moods), fuzzy search, request songs, vote on vibes
• dj.html - Start/stop party, set PINs, manage queue, see requests & vibes
• display.html - TV mode: artwork, lyrics, request feed, QR code, floating reactions
• leaderboard.html - Party stats: guest activity, top tracks, reaction counts

Reset the shuffle cycle. All tracks become unplayed.

Tracks played/remaining in shuffle cycle. Query: ?offset=&limit=

// POST /banlist - Ban a track
{"url": "file:///C:/Music/track.mp3", "reason": "Corrupted audio at 2:30"}

// DELETE /banlist/{url} - Unban a track (URL-encode the file path)

// POST /influences - Add an influence
{"type": "--", "target": "Genre", "value": "Audiobook"}
// type: "++" (more) or "--" (less/exclude)
// target: "Genre" or "Artist"

// DELETE /influences/Genre/Audiobook - Remove specific influence

// POST /influences/clear - Clear all influences (reset preferences)

Name an assembly (seeds + flow) and replay it later with one click. Backed by mbxhub-stations.json. GET list is summary-shaped (no seedUrls); GET one returns the full record (incl. seedUrls + timestamps); create returns the summary shape (id, name, flow, seedCount, genreQuotaExempt). All station shapes carry genreQuotaExempt (spec 2026-07-09-genre-quota-per-stream.md) — default true, so a saved station stays in its lane and skips the genre variety quota unless turned off — and filter, an optional per-station candidate filter in search-DSL syntax (e.g. year:1965..1979 -genre:Live). The station filter COMPOSES with the global autoQ.filter: global is the house rules, the station filter is the flavor, and a fill on that station must pass both. Applies to that station’s radio runs; it does not survive a MusicBee restart with the rest of the run detail.

Journey stations (spec 2026-07-25-bookended-fresh-journey) — a journey object replaces seedUrls on create: {"journey": {"waypoints": [2–5 track URLs], "fresh": true, "targetMinutes": 90}}. The first waypoint is the start and the last is the end (both pinned); any middle waypoints are pinned too. Every waypoint must have analyzed V/A mood data — an unknown or unscanned waypoint returns 400 WAYPOINT_NOT_SCANNED. Each play regenerates a fresh arc between the same bookends — a new random middle each time (when fresh, the default), sized to targetMinutes (works for long durations, hours). It queues that finite arc and does not arm the radio, so the end waypoint is the last track. GET /autoq/stations/{id} returns a journey field ({waypoints, fresh, targetMinutes}), null on a seed station.

Validation: create requires name and at least one seedUrls entry — or a journey object instead (400 INVALID_REQUEST otherwise; genreQuotaExempt is optional, defaults true). PUT is a partial update — name, genreQuotaExempt and/or filter, at least one required (400 INVALID_REQUEST otherwise). filter is validated strictly on create and update — a bad expression returns 400 INVALID_FILTER with the parse error; an empty string clears it. Unknown {id} on get/update/delete/play returns 404 NOT_FOUND.

play queues the station's seeds next, applies its flow, and starts the radio seeded (same one-action replay as RadioStart). A journey station instead queues a freshly-built finite arc between its bookends (see above) and does not arm the radio. Gated like /autoq/radio/start — party mode restricts it to the DJ, and 409 AUTOQ_DISABLED when AutoQ is off. Response: {message, name, flow, seedCount, queued}.

from-run captures the live seeded radio run (seeds, flow, and genre-exemption) as a new station in one call — the platform verb behind every surface's “Save current run as station…”. Body {"name": "..."}. 409 NO_ACTIVE_RUN when the radio is off or the run has no seed list to capture (mood runs carry no seeds). Response shape matches POST /autoq/stations.

influences is the station’s reaction memory — tracks upvoted (pick-boosted) or downvoted/banned (hard-excluded) during that station’s runs, persisted in mbxhub-station-influences.json. GET returns {stationId, upvoted:[{url, artist, title}], downvoted:[...]}; DELETE ?url= removes one track from the memory (the un-downvote verb; 404 NOT_FOUND when the track isn’t remembered, 400 INVALID_REQUEST without url). The browse station picker’s Memory button is the UI over these.

Mutation routes (POST / PUT / DELETE) return 403 FORBIDDEN when ApiReadOnlyMode is set — kiosk deployments can’t have stations mutated by remote clients.

A program is a playlist of saved stations — an ordered sequence of entries the radio moves through, one station handing off to the next after its dwell. Entries REFERENCE stations, never own them: order and dwell are the program’s own settings, while flow, candidate filter, seeds and reaction memory all still come from each entry’s station. Backed by mbxhub-programs.json. GET list is summary-shaped (no entries); GET one and create/update return the full record incl. entries (stationId, dwellTracks, dwellMinutes).

Dwell grammar: each entry sets at most one of dwellTracks (advance after N tracks played under that entry) or dwellMinutes (advance after N minutes of music); neither means hold — the radio keeps filling from that station until stopped. (The Workbench’s Programs tab labels dwell “Play for” — same values, friendlier name.) Dwell met on the last resolvable entry is a terminal hold too: the run continues as an ordinary station run rather than looping (whole-program loop is a reserved knob, no v1 behavior).

Hard boundary: the handoff re-binds the run to the next entry’s station — its flow, seeds (for centering), filter, and reaction memory — and takes effect on the next fill only; it never touches the queue, so tracks already queued from the outgoing station play out before the new station’s picks appear (eased boundaries are a reserved knob, no v1 behavior).

Validation: create requires name and at least one entry (400 INVALID_REQUEST otherwise). Every entry’s stationId must resolve to an existing station at save time, and at most one dwell may be set, positive when present — a bad entry returns 400 INVALID_ENTRY naming the failing index (e.g. entry 1: unknown stationId '...'). An entry with no dwell that isn’t last is reachable but strands every entry after it — that’s a warnings array on the 200 response, not an error (the operator may be mid-edit). PUT is a partial update — name and/or entries, at least one required; a non-null entries replaces the list wholesale (re-validated the same way, same warnings shape). Unknown {id} on get/update/delete/play returns 404 NOT_FOUND.

play is the one-action replay: starts the radio on the program’s first resolvable entry exactly like POST /autoq/stations/{id}/play, then arms program mode on top. Gated like /autoq/radio/start — party mode restricts it to the DJ, 409 AUTOQ_DISABLED when AutoQ is off, and 409 PROGRAM_EMPTY when no entry references an existing station. Play also counts as a write — it arms the radio and queues tracks — so it returns 403 FORBIDDEN when ApiReadOnlyMode is set, same as the mutation routes below. Response: {message, name, entryCount, queued}.

A playing program’s position (which entry, tracks/minutes accumulated under it) survives a MusicBee restart via the same run-detail store as the rest of the radio run — the run resumes at the same entry with dwell progress intact. If a station a program references is deleted while that program is on the air, advance skips the dangling entry (logged as a Warn) and moves to the next resolvable one; if the whole program is deleted mid-run, the run holds on its current station instead of erroring.

Mutation routes (POST / PUT / DELETE) return 403 FORBIDDEN when ApiReadOnlyMode is set — kiosk deployments can’t have programs mutated by remote clients.

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

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

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

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

Speech detection — how talk tracks are identified

The speechLikely verdict above is produced by truedat (the analyser that writes mbxmoods.json), not by the hub. It draws on three independent evidence sources; none of them decides anything on its own — they surface as reasons and feed the verdict, and the verdict only gates AutoQ's auto-pick pool (see autoQ.excludeSpeechTracks). Nothing here skips a scan or removes a catalogue entry.

1. Library labels. Read from the iTunes XML, from exactly two markers: Podcast=true, or Genre equal to Podcast (exact match, case-insensitive). The old “Episode Date” heuristic was removed and must not return — MusicBee maps ID3v2.4 TDRL (a release date) into that key, so it rode on ordinary music. Publisher and long duration are not, on their own, speech.

2. Embedded file markers. A bounded header sniff (≤128 KB per file, run only over review candidates during a preview pass — never a full-library sweep), graded into three tiers rather than first-match-wins:

3. Acoustic verdict (speechLikely). Computed at write time from stored Essentia features (danceability, chords strength, silence rate, zero-crossing rate, tempo-peak weight, key-vote strength), so a threshold change is retroactive across the whole catalogue with no rescan. Two gates must both fire for a “yes”: the zero-crossing signal, and danceability under 0.50. That second gate is load-bearing — sparse, live, free-form instrumental music craters on every other signal exactly like talk does, and without it genuine music (live jazz, a live rock outro) was misclassified. Measured: genuine speech sits near 0.00; real-music false positives ran 0.66–1.10.

Scope note: this identifies the genus — speech-dominant. It deliberately does not try to tell podcast from audiobook from lecture: that is provenance, and the audio does not carry it.

// GET /autoq/autocal/candidates?vMin=0.4&vMax=0.6&aMin=0.4&aMax=0.6&source=autoq&limit=25
// Response:
{
  "success": true,
  "data": {
    "source": "autoq",
    "box": { "vMin": 0.4, "vMax": 0.6, "aMin": 0.4, "aMax": 0.6 },
    "count": 2,
    "candidates": [
      { "path": "C:\\Music\\Artist\\Album\\Track.mp3", "artist": "...", "title": "...", "valence": 0.52, "arousal": 0.47 }
    ]
  }
}

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

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

// Response:
{
  "success": true,
  "data": {
    "total": 12480,
    "essentia": 9812,
    "fallback": 2668,
    "warmupInProgress": false,
    "lastWarmup": null
  }
}

// Response:
{
  "success": true,
  "data": { "updated": 342, "elapsedMs": 1302 }
}
// When a gate refuses the run (write toggle off, circuit breaker, field
// mismatch, no mood data), the response says why instead of a silent 0:
{
  "success": true,
  "data": { "updated": 0, "elapsedMs": 0, "blocked": "Mood tag writing is off — pick a mood tag field in Settings → AutoQ (writeMoodTags)" }
}

Tiered reactions for the now playing track. Each emoji has a different score weight.

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

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

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

AutoQ settings in mbxhub.json under the autoQ section:

Send to AutoQ (POST /autoq/send, above): sendMode, sendRefreshWeight, and sendWaypointCap are the three primaries surfaced on the generic settings page; the rest are secondary knobs (workbench + /autoq/settings only) whose defaults reproduce the ruled behavior exactly.

Scoring weights under autoQ.scoringWeights: featureSimilarity (0.5), trackSentiment (0.25), artistSentiment (0.15), recencyPenalty (0.3), diversityPenalty (0.6), explorationBonus (0.1), influenceWeight (0.3).

Reaction scores under autoQ.reactionScores: fire (3), heart (2), like (1), dislike (-1), ban (-100).

Estimation, valence/arousal weights, normalization ranges, confidence thresholds, and genre profiles — full field list with defaults and descriptions is in the config reference. Live values: GET /autoq/settings. Tune interactively at /pages/autoq.html.

Mood Quadrants — Arousal (energy) is the vertical axis, valence (positivity) is the horizontal. Each mood channel targets a point in this space.

GET /vam/annotate/search?q=miles
{"success":true,"data":{"results":[
  {"key":"<sha256>","url":"file://...","title":"So What",
   "artist":"Miles Davis","album":"Kind of Blue","rated":false}
]}}

Rating & state

The rating endpoint is the one that mutates — everything else here is read-only. POST /vam/annotate/rating honors ApiReadOnlyMode (returns 403 API_READ_ONLY) so kiosk deployments can't accumulate stray labels.

Gates — calibration report

Compare the embedded model's predictions against the user's anchor labels. The Gates panel at the top of /pages/autoq.html consumes this surface, and it's the sanity check after every retrain.

Model — disk override and reload

The trained model ships embedded in the DLL but a disk copy at %AppData%\MBXHub\mood-model.json supersedes it. Lets you iterate on retrained models without rebuilding: train → write to AppData → POST /vam/model/reload → loader picks up the new file.

Tuning Console — pairwise A/B

The tuning page (/pages/tune.html) is the "second opinion" loop for V/A scoring. The user picks the higher-on-axis track from a pair (or marks them roughly equal); judgments accumulate as Bradley-Terry signals that the V2 trainer fits alongside the single-track anchor labels. Pair selection biases toward under-compared tracks and close-pair candidates — the model is most uncertain when scores are similar, so each judgment carries more signal than a random pick across 71k tracks where most pairs are trivially separable.

Move: {"x":100,"y":100} (absolute) or {"dx":10,"dy":0} (relative)

Click: {"button":"left"} or {"x":500,"y":300,"button":"right"}

List available presets

Execute a preset by name (e.g., /aria/preset/RIA3)

List allowed programs for the run() command. Returns names only (paths not exposed).

Note: New clients receive ALL events by default. Once you send a subscribe message, you only receive those specific events. Use unsubscribe to stop receiving events without disconnecting.

// Subscribe to specific events (filters to only these events)
{"subscribe": ["TrackChanged", "PlayStateChanged"]}

// Unsubscribe from events (stop receiving them)
{"unsubscribe": ["PositionChanged"]}

// Subscribe to all events (equivalent to no subscriptions)
{"subscribe": ["TrackChanged", "PlayStateChanged", "VolumeChanged",
              "PositionChanged", "QueueChanged", "ShuffleChanged",
              "RepeatChanged", "MetadataChanged", "Reaction",
              "TasteChanged", "ThemeChanged", "SearchMatched",
              "MoodCacheReady", "PartyStateChanged"]}

// TrackChanged
//   cueTrack + cueStartMs are present only when the current track is a
//   CUE-backed virtual track (one physical file, multiple logical tracks).
//   Clients that stream audio locally use cueStartMs to seek <audio>.currentTime.
{
  "event": "TrackChanged",
  "timestamp": "2024-01-03T12:00:00.000Z",
  "data": {
    "fileUrl": "C:\\Music\\song.mp3",
    "title": "Track Title",
    "artist": "Artist Name",
    "album": "Album Name",
    "duration": 245000,
    "artworkUrl": "/nowplaying/artwork",
    "cueTrack": 3,         // optional
    "cueStartMs": 184000   // optional
  }
}

// PlayStateChanged
{
  "event": "PlayStateChanged",
  "timestamp": "2024-01-03T12:00:00.000Z",
  "data": {
    "state": "playing"  // "playing", "paused", "stopped"
  }
}

// VolumeChanged
{
  "event": "VolumeChanged",
  "timestamp": "2024-01-03T12:00:00.000Z",
  "data": {
    "volume": 75,  // 0 to 100
    "muted": false
  }
}

// PositionChanged
{
  "event": "PositionChanged",
  "timestamp": "2024-01-03T12:00:00.000Z",
  "data": {
    "position": 45000,   // Current position in milliseconds
    "duration": 245000   // Total duration in milliseconds
  }
}

// QueueChanged
{
  "event": "QueueChanged",
  "timestamp": "2024-01-03T12:00:00.000Z",
  "data": {
    "action": "add",    // "add", "remove", "clear", "move"
    "index": 5,
    "totalTracks": 42
  }
}

// ShuffleChanged
{
  "event": "ShuffleChanged",
  "timestamp": "2024-01-03T12:00:00.000Z",
  "data": {
    "enabled": true
  }
}

// RepeatChanged
{
  "event": "RepeatChanged",
  "timestamp": "2024-01-03T12:00:00.000Z",
  "data": {
    "mode": "all"  // "none", "all", "one"
  }
}

// MetadataChanged
{
  "event": "MetadataChanged",
  "timestamp": "2024-01-03T12:00:00.000Z",
  "data": {
    "fileUrl": "C:\\Music\\song.mp3",
    "rating": 3,      // -1 (unrated) to 5
    "love": "L"       // "L" (loved), "B" (banned), or "" (neither)
  }
}

// Reaction
{
  "event": "Reaction",
  "timestamp": "2024-01-03T12:00:00.000Z",
  "data": {
    "emoji": "fire",
    "type": "fire",       // fire, heart, like, dislike, ban
    "nickname": "Guest",
    "trackTitle": "Song Name",
    "trackArtist": "Artist"
  }
}

// TasteChanged (debounced, fires after reactions/influences/mood changes)
{
  "event": "TasteChanged",
  "timestamp": "2024-01-03T12:00:05.000Z",
  "data": {
    "topGenres": [{ "name": "Rock", "weight": 1.0 }],
    "topArtists": [{ "name": "Foo Fighters", "weight": 0.85 }],
    "bpmRange": [90, 160],
    "mood": "Energetic",
    "moodConfidence": 0.88,
    "influenceCount": 3,
    "reactionCount": 12
  }
}

// ThemeChanged (fires on PUT /system/theme or dashboard mode toggle)
{
  "event": "ThemeChanged",
  "timestamp": "2024-01-03T12:00:06.000Z",
  "data": {
    "activeMode": 1,
    "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
  }
}

// Connect to WebSocket
const ws = new WebSocket('ws://localhost:8080/ws');

ws.onopen = function() {
  console.log('Connected to MBXHub');

  // Optional: Subscribe to specific events only
  // Without this, you receive ALL events
  ws.send(JSON.stringify({
    subscribe: ['TrackChanged', 'PlayStateChanged', 'PositionChanged']
  }));
};

ws.onmessage = function(event) {
  const msg = JSON.parse(event.data);

  switch (msg.event) {
    case 'TrackChanged':
      console.log('Now playing:', msg.data.title, '-', msg.data.artist);
      break;
    case 'PlayStateChanged':
      console.log('State:', msg.data.state);
      break;
    case 'PositionChanged':
      const pct = (msg.data.position / msg.data.duration * 100).toFixed(1);
      console.log('Position:', pct + '%');
      break;
  }
};

ws.onclose = function() {
  console.log('Disconnected from MBXHub');
};

ws.onerror = function(err) {
  console.error('WebSocket error:', err);
};

// Later: Unsubscribe from position updates (too frequent)
ws.send(JSON.stringify({ unsubscribe: ['PositionChanged'] }));

// Clean disconnect
ws.close();

Logging is controlled by two settings in mbxhub.json:

500 response body gate: when debugMode is true AND logLevel is Debug or Trace, INTERNAL_ERROR responses include the full exception dump in the body (type, message, stack trace, inner-exception chain) — useful when debugging a self-hosted LAN deployment where the operator is also the consumer. Otherwise the body is the generic fallback string and the dump only lands in mbxhub.log. Default is fail-secure (debugMode: false) so production / shared exposure does not leak internals.

Log files are stored in the MBXHub subfolder of MusicBee's persistent storage:

%AppData%\MusicBee\MBXHub\mbxhub.log

• Log files are automatically rotated when they reach 2MB (debug) or 5MB (normal)
• Old logs are archived as mbxhub.1.log, mbxhub.2.log, etc.
• Maximum 5 archive files in debug mode, 3 otherwise

To enable debug logging:

// In mbxhub.json:
{
  "debugMode": true,
  "logLevel": "Trace"  // or "Debug", "Info", "Warning", "Error"
}

HTTP requests are logged at Info level with timing:

2025-01-25 14:32:15 [INFO ] [REST] HTTP GET /player/status -> 200 (12ms)
2025-01-25 14:32:16 [INFO ] [REST] HTTP POST /player/playpause -> 200 (8ms)
2025-01-25 14:32:17 [INFO ] [Plugin] Track changed: Artist Name - Track Title
2025-01-25 14:32:17 [INFO ] [WebSocket] WS client abc12345 connected from 192.168.1.50:54321

PartyMode uses PIN-based authentication with three roles:

PartyMode endpoints authenticate via the X-Party-PIN header:

# Guest request example
curl -X POST http://localhost:8080/partymode/request \
  -H "X-Party-PIN: 1234" \
  -H "Content-Type: application/json" \
  -d '{"url":"C:\\Music\\Track.mp3","nickname":"Haro"}'

# Validate PIN and get role
GET /partymode/validate?pin=1234&nickname=Haro

Invalid or missing PIN returns 401 Unauthorized.

An optional always-on password gate over the whole API surface — a safety net for trusted LANs. Turn it on in the plugin under Settings → Remote Connection Settings (Configure Access…) → Remote Access by ticking Require password (HTTP Basic) and setting a password. It is off by default and has no web/API configuration.

When enabled, remote requests must carry an HTTP Basic credential. The username is ignored; only the password is checked:

# Any username, the configured password
curl http://localhost:8080/library/files \
  -H "Authorization: Basic $(printf 'x:yourpassword' | base64)"

Missing or wrong credentials return 401 Unauthorized with a WWW-Authenticate: Basic realm="MBXHub" header, so browsers show a native login prompt. Exempt from the gate: localhost (the host machine), the /ws event stream, and the live-PartyMode surface (party guests authenticate with their PIN, not this password).

Limits — this is a speed bump, not transport security. Over plain HTTP the password is sent base64-encoded (effectively cleartext) on every request; only HTTPS fixes that. The stored password is an unsalted SHA-256 hash. Fine for a single shared secret on a trusted network, not a hostile one.

The password is stored only as a one-way hash — never in plain text, and it cannot be recovered. If you forget it, set a new one in the same Remote Access settings where you enabled the gate.

MBXHub supports three protection levels for different deployment scenarios:

Configure via kioskMode and apiReadOnlyMode in settings.

PartyMode includes built-in limits and optional per-IP rate limiting:

Built-in limits (always active):

• Join deduplication: Same nickname can only trigger join announcement once per 60 seconds
• Request history: Maximum 100 entries kept in memory per session
• Feed buffer: Maximum 100 items (joins + requests + votes)

Per-IP rate limiting (configurable via Settings → Party Mode...):

• Requests/min: Max song requests per minute per IP (default: 5)
• Votes/min: Max votes per minute per IP (default: 5)

Returns 429 Too Many Requests when limits exceeded.

• Maximum request body size: 1 MB
• Content-Type validation for JSON endpoints
• No stack traces exposed in error responses

MBXHub can restrict write operations via settings with granular per-operation controls:

Restriction Hierarchy:

• Master read-only - Blocks all write operations API-wide
• Category restriction - Blocks all operations within a category
• Operation restriction - Blocks specific operations only

Settings cascade: master OR category OR operation = blocked

Granular Operations:

Default Settings:

The philosophy: player and queue are open, destructive operations are locked. Playlists, tag edits, and file deletion default to read-only.

Settings cascade: master OR category OR operation = blocked. The granular playlist settings default to false but are moot because their parent apiReadOnlyPlaylists is true.

Action Categories (v0.5.2.6+):

Always Permitted (exempt from restrictions):

• All GET requests - Browse, search, view queue, get status, stream audio/artwork
• PartyMode guest actions - Song requests, voting, viewing party queue
• PartyMode DJ role - When party active, DJ bypasses restrictions for player/queue/shuffle

Blocked requests return 403 Forbidden:

{"success":false,"error":{"code":"READ_ONLY","message":"API is in read-only mode"}}
{"success":false,"error":{"code":"PARTY_LOCKED","message":"Media browsing is locked during PartyMode (DJ-only)."}}

All file URLs are Windows paths. URL-encode when passing in path parameters:

// Original: C:\Music\Artist\Track.mp3
// Encoded:  C%3A%5CMusic%5CArtist%5CTrack.mp3

// Example: GET /library/file/C%3A%5CMusic%5CArtist%5CTrack.mp3

Most list endpoints support offset and limit query parameters:

• Default limit: 50
• Maximum limit: 10000
• Example: GET /library/files?offset=100&limit=50

Library endpoints support ?sort= parameter for server-side sorting:

• alpha (default) - Alphabetical by title+artist
• artist - By artist name, then title
• album - By album name, then track number
• title - By title only
• date - By date added (newest first)
• track - By disc number, then track number (natural album order)
• name - By display name
• year-asc - By year ascending (chronological, oldest first)

Example: GET /library/files?artist=Pink+Floyd&sort=album

v0.5.3.4 behavior notes. String comparisons use InvariantCultureIgnoreCase over diacritic-folded keys, so non-Latin album titles (Cyrillic / Greek / CJK / Hebrew / Arabic) sort under their own scripts instead of dropping to the tail of an A→Z list (ASCII libraries unchanged). Custom-* sorts configured as Numeric send rows with unparseable values (Year=1999/2000 on compilations, whitespace-padded fields) to the END of the list alongside other non-Numerics, matching the Auto kind's segregation — previously they landed at the TOP via a long.MinValue sentinel.

Shuffle, banlist, and influence endpoints require TrueShuffle or AutoQ to be enabled. Check availability:

GET /shuffle/status
// Returns 503 SERVICE_UNAVAILABLE if TrueShuffle/AutoQ not enabled

For real-time updates (track changes, state changes), use WebSocket instead of polling:

• Use REST for: Commands (play, pause), queries (get queue, search)
• Use WebSocket for: Real-time UI updates, visualizations, progress bars
• See WebSocket Events section

By default, MBXHub only accepts localhost connections. For network access:

1. Enable allowRemoteConnections in settings
2. Configure Windows Firewall (use Settings → Firewall → Add Rule)
3. Clients connect to your PC's IP address (e.g., http://192.168.1.100:8080)

MBXHub automatically detects CUE-backed audio files and resolves per-track metadata across all surfaces:

• Player status (/player/status) - Overlays title, artist, trackNo, album from CUE sheet
• Position (/nowplaying/position) - Includes cueTrack and cueTitle
• Now playing (/nowplaying) - Includes cueTrack and cueStartMs (browser-mode clients seek the container and report play stats against the right sub-track)
• Tags (/nowplaying/tag) - Returns CUE track data for TrackTitle, Artist, Album, TrackNo
• WebSocket - track events include cueTrack field when CUE active
• Dashboard - Now-playing shows resolved CUE track metadata

Encoding detection: BOM check → UTF-8 validation → Windows-1252 fallback. Built-in regex parser; no external CUE library required.