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/1-5 - Toggle star rating. 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%, 42%, 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 - 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 CharMap.cs — union of browse / explore / player local 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). Loaded with defer by every shell page.
• /manifest.webmanifest — v0.5.3.0 PWA manifest. Returns application/manifest+json. The name field carries the literal token __HOST_NAME__ in source, replaced at serve time with Environment.MachineName so the installed PWA shows "MBXHub - <hostname>" in browser install dialogs and “Manage apps” UI (the OS-level desktop / drawer label uses short_name, which stays plain "MBXHub" so renames don't orphan shortcuts). 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 — install never picks up the dynamic hostname on app updates).
• /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. Generated from MBXS\MBXHub.Shell\brand\mbxhub-halard.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

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. Three response shapes:

• { hasLyrics: false, lyrics: null } — no lyrics and no fallback.
• { hasLyrics: true, lyrics, source: "lyrics" } — real MusicBee lyrics.
• { 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.

Fallback is 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, and dateAdded for artwork lookups and sorting. 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. Both 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.

/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)

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:

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.

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"]}

// 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.

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

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
• 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.