Dashboard Features

• Live WebSocket updates (progress bar, track info, play state)
• Playback controls (play/pause, next, previous, stop)
• Volume control with mute toggle (shift-click for fine adjustment, routes to configurable default fader)
• 5-star rating, love/unlove, and ban buttons
• Shuffle mode toggle (Off / Shuffle / AutoDJ)
• Repeat mode toggle (Off / All / One)
• Album artwork display
• Playlist picker with split button (Play Now / Queue Next / Queue Last / Add Track)
• Mood channel selector with real-time reactions (fire, heart, dislike, ban)
• ARiA preset dropdown for quick automation
• Influence controls (thumbs up/down for artist/genre shuffle preferences)
• QR code connection dialog for quick mobile access
• Dark, Light, and Midnight themes
• Keyboard shortcuts (Space, arrows, M for mute)

Customizable Layout

The Dashboard's panel order and visibility are fully configurable from MBXHub Settings.

• 7 panels - Playback Controls, Mood/Reactions, Rating, Playlists, Shuffle/Repeat, ARiA, Volume
• Reorder - Drag panels up/down to arrange the layout to your preference
• Show/Hide - Check or uncheck panels to control which ones appear
• Collapsible sections - Set how many panels are always visible; the rest fold behind an expand toggle
• Server-rendered - Layout is baked into the HTML and works on any browser; core controls work with no JavaScript, live updates use JS when available
• Configuration stored in dashboardLayout in mbxhub.json (order, hidden, collapseAfter)

Dashboard Settings

Click to close

Charms

Charms are action buttons on the charm bar — on the dashboard, and since v0.5.5.0 as the desktop Charm Bar (Ctrl+Alt+B), where each one opens as its own window. A charm opens a webapp, fires HTTP requests to LAN devices, or calls MBXHub endpoints. Drop-in .json manifests in the charms/ folder — build your own or use the built-ins.

The Charm Bar

Click to close

Browse Charm

Click to close

NowPlaying Charm

Click to close

Set List / Tracklist

Click to close

Mixer Charm

Click to close

Devialet Phantom control (via Mixer)

Click to close

Built-in Charms

Charm bar order and visibility are configurable in charmBar in mbxhub.json, or from the Dashboard tab in MBXHub Settings. Custom charms: drop a .json manifest in the charms/ folder.

Mood Classification

AutoQ maps every track onto a 2D emotion space (valence x arousal) based on Russell's circumplex model. Audio features are extracted by Essentia and combined into valence (happy↔sad) and arousal (energetic↔calm) scores.

• 10 default mood channels - Euphoric, Energetic, Intense, Melancholic, Chill, Dreamy, Uplifting, Angry, Peaceful, Neutral
• 14 audio features extracted per track via Essentia (BPM, key, mode, MFCCs, dissonance, onset rate, and more)
• Valence formula (6 active inputs) - Mode, danceability, dissonance, pitch salience, chord changes, MFCCs
• Arousal formula (8 inputs) - BPM, loudness, spectral flux, centroid, danceability, onset rate, zero-crossing rate, RMS energy
• Genre-aware weight adjustment - Per-genre multipliers adapt feature weights to each genre's acoustic norms. 8 built-in profiles (Electronic, Metal, Jazz, Classical, Hip-Hop, Folk, R&B, Pop/Rock). Custom profiles via autoQ.genreProfiles
• Confidence scoring - Every mood estimate carries a confidence score (0–1). Essentia tracks score ~0.9, fallback tracks ~0.2–0.45. Color-coded badges on Dashboard, Player, and Tuning Console
• Mood combo labels - Tracks near channel boundaries get composite labels (e.g. "Upbeat + Energetic")
• All weights configurable - Tune every formula coefficient via autoQ.estimation settings or the Tuning Console
• Custom mood channels - Define your own mood regions via autoQ.moodChannels

Reactions

Guests and listeners react to tracks in real-time. Reactions feed directly into AutoQ's scoring engine to influence what plays next.

• Fire - This track is hot, play more like it
• Heart - Love it, strong positive signal
• Like / Dislike - Standard thumbs up/down
• Ban - Remove from rotation entirely

Reaction scores are configurable in autoQ.reactionScores. Each reaction type has a tunable weight that feeds into the track scoring formula.

TrueShuffle

MBXHub unifies the former MBXQ shuffle engine directly into the hub. TrueShuffle ensures every track in your library plays before any track repeats, with mood-aware ordering.

• Full-cycle guarantee - Tracks entire shuffle state across sessions
• Mood-weighted selection - Prefers tracks matching the current vibe
• Influence system - Artist/genre thumbs up/down to steer shuffle
• Ban list - Permanently exclude tracks from rotation

Setup: Mood Tagging

Mood data is generated offline with Truedat, which runs Essentia audio analysis and produces mbxmoods.json. MBXHub reads that file at startup and uses it for mood-aware AutoQ scoring. Without it, AutoQ falls back to genre/BPM metadata estimates. See The Audio Features for details on the 14 features that drive mood estimation.

1. Enable iTunes XML export in MusicBee (Edit → Preferences → Library)
2. Run truedat.exe "iTunes Music Library.xml" to generate mbxmoods.json
3. Place mbxmoods.json in your MusicBee Library folder or %APPDATA%\MusicBee\MBXHub\
4. In MusicBee, go to Edit → Preferences → Tags (1) → Custom Tags and set one tag (e.g. Custom1) to "AutoQ Mood"

Custom Tags Setup

Click to close

MBXHub writes the mood channel name (e.g. "Euphoric", "Chill") into the custom tag so you can see it in MusicBee's column browser, use it in auto-playlists, and sort by mood.

Library Browser

Standalone album browser at /pages/browse.html. Designed for phones and tablets - browse your library without the full player UI.

• Album grid - Artwork cards with artist and album name
• 7 tabs - Albums, Artists, Genres, Playlists, Podcasts, Radio, Moods
• Search - Filter across your entire library
• Queue controls - Play Now, Queue Next, or Queue Last from any result
• Playlist picker - Add tracks to existing playlists

Album Grid

Click to close

Track List

Click to close

Built-in Player Page

A full-featured 3-column desktop layout at /pages/player.html:

• Browse panel - Albums, Artists, Genres, Playlists, Podcasts, Radio, Moods with search
• Player panel - Now Playing with artwork, controls, ratings, lyrics
• Queue panel - Up Next with track management
• Queue buttons on every track: Now, Next, +Q
• Listen Here — stream audio directly to the browser via HTML5 audio
• Radio Stations tab — browse and play radio from MusicBee
• Influencer thumbs (when MBXQ enabled)
• ARiA preset buttons
• WebSocket live updates

Customizable

• Default pages extracted to %APPDATA%\MusicBee\MBXHub\pages\
• Edit the HTML/CSS/JS to customize
• Add your own pages - anything in the folder is served
• Pages call REST API via fetch() - works across the network
• Delete the folder to reset to defaults on next restart

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://my-pc:8080/pages/partyon.html

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

Worked example: Playlist CRUD charm

A longer end-to-end prompt that builds a full Playlist viewer / editor charm on top of a released MBXHub — both the charm manifest (so it lands in the dashboard charm bar) and the HTML page (with create / rename / delete / reorder / add-track / remove-track / play-now / queue-next). The AI reads /llms.txt for the charm manifest schema and the /playlists endpoints, then drops two files into %APPDATA%\MusicBee\MBXHub\. No source edits, no rebuild — reload the dashboard, the charm shows up.

Full prompt: downloads/examples/playlist-charm-prompt.md.

Worked example: MCP server for AI agents

A one-prompt build of a seven-tool MCP server that lets AI agents control MusicBee through MBXHub — search the library (full file paths included), transport controls, now playing, and playlist create / add / play. The adapter contains no MusicBee code: the AI reads /llms.txt as the API contract and generates a single-file stdio server (official MCP SDK, one dependency) whose tools are each a single HTTP call to the Hub. Register it with claude mcp add and MCP-only clients like Claude Desktop can drive MusicBee — e.g. build a playlist from your Last.fm top tracks by composing it with a Last.fm MCP server.

Do you even need it? Agents that can make their own tool calls — Claude Code and anything else that can run curl or issue HTTP requests directly — don’t need an MCP server at all: point them at /llms.txt and they drive the REST API as-is. The MCP server is for agents that can’t make direct HTTP calls (Claude Desktop and other MCP-only clients) — it wraps the same endpoints as MCP tools so those clients can play too.

And this isn’t just about coverage — even a complete wrapping of every endpoint wouldn’t close the gap. MCP tools return one result at a time into the agent’s context; a direct-API agent composes around the calls — scripting, piping, looping, diffing responses, replaying whole test suites — and reads the transport itself (status codes, headers, timing) as evidence when something misbehaves. Hundreds of tool schemas would also swamp an agent’s context, where /llms.txt is documentation it greps on demand. If your agent can speak HTTP, let it.

Full example, prompt, and walkthrough: downloads/examples/mcp.md. Built code with the docs: musicbee-mbxhub-mcp.zip.

Worked example: Lyrion (Squeezebox) plugin — AutoQ picks what plays next

A prompt that builds a Lyrion Music Server plugin against a running MBXHub: browse, search, and stream the MusicBee library on every Squeezebox / squeezelite player in the house — and the hero feature, a “Don’t Stop the Music” provider backed by AutoQ. Pick one of your saved AutoQ stations on the player and go: when the queue runs dry, the plugin generates picks from that station’s seeds — mood radio on hardware players, replacing the long-dead MusicIP lineage those menus were built around. Stations are exposed read-only (build and train them in MBXHub); journeys ride along for free as saved playlists. The plugin is a thin Perl REST client: no MusicBee code, no mood math, and it gets smarter as the Hub’s taste model learns.

Full prompt and endpoint map: downloads/examples/lms-dstm-prompt.md. Built code with the docs: musicbee-mbxhub-lms-dstm.zip.

How It Works

• It still counts as listening. Streamed plays update MusicBee’s play counts, Last Played, skip counts and scrobbling — and feed AutoQ’s taste signals and TrueShuffle’s progress — judged by MusicBee’s own play-count thresholds. An hour on your phone shapes what gets picked at your desk. Closing the tab or switching output never fabricates a skip.
• Take the room with you. One switch moves between the speakers and the device you are holding: flipping to the browser picks up the room’s current track at its position and pauses the room, and flipping back hands it over again. Each device remembers which it was on.
• Seeking is instant — audio is served over HTTP with Range support, so dragging the scrubber jumps rather than rebuffers.
• CUE sheets work properly. The player seeks to the right offset, shows track-relative progress and auto-advances at boundaries; play counting judges each sub-track against its own sheet-derived duration.
• A queue on the device with auto-advance, next and previous, and its own volume
• Tap the headphone on any track in search results or browse views to start
• Off with a single switch in Settings, and the play-reporting behaviour has its own controls

What each browser can play

Nothing here is baked into the product. The play page asks each browser live via canPlayType, and only a definite “no” blocks a track — so when a browser gains a codec, Listen Here picks it up with no code change. This table is for humans deciding what listeners will actually hear. Current browser versions as of July 2026: ✅ plays  ·  ⚠ see note  ·  ❌ does not play.

Reading it in one line: MP3, AAC/M4A and WAV play anywhere, and FLAC plays on anything newer than about 2017. What still trips on real devices is WMA everywhere, AIFF and ALAC off Apple, and Vorbis or Opus on Safari before 18.4 — iPhones not updated past iOS 18.3. Turn transcoding on and WMA joins the first list; the rest stay as they are until their whitelist entry is added.

Full detail, including what MIME candidates each extension probes and why .opus is asked twice: Browser Audio Format Support.

Formats your browser can’t play

WMA and the like are converted on the way to Listen Here, so the whole library plays on whatever device you are holding. You never see a “convert” step: the browser reports what it can decode, asks for a conversion only when it can’t, and the only visible difference is that the ⚠ unplayable chip never appears.

• Nothing is converted in advance — a file converts the first time a browser actually asks for it
• The result is cached, so a track converts once and seeking still works
• Your library files are never touched, and CUE tracks keep their start points
• Output is FLAC, so an already-lossy source is never compressed a second time
• Requires ffmpeg, runs hidden at below-normal priority, and is off until you turn it on

It is a compatibility converter, not a transcoding server, and deliberately so. A browser cannot request a format or a bitrate — it can only say it cannot play the original, and the server picks the one target. The scope is a whitelist rather than a guess, so an MP3 is always served untouched. It is not a bandwidth feature either: FLAC output is larger than the WMA it replaces. The goal is that everything plays, nothing more ambitious.

ffmpeg -i original.wma -f md5 -
ffmpeg -i converted.flac -f md5 -

Two honest caveats. The chain is only as exact as ffmpeg’s WMA Lossless decoder. And most WMA files in the wild are WMA Standard, which is lossy — those can never be bit-perfect against an original master, though FLAC captures the decode exactly as it stands.

Radio Features

• Browse all radio stations configured in MusicBee
• Play via MusicBee or stream locally with Listen Here
• Search/filter stations by name
• REST API: GET /radio/stations

Guest Page

Guests scan a QR code, enter a PIN and nickname, then browse your library and request songs.

• Browse by Album, Artist, Genre, or Playlist
• Search your library
• Queue songs with one tap - requests attributed to nickname
• See Up Next queue (5 tracks)
• Vibes voting (thumbs up/down) on now playing and queued tracks

Browse Genres

Click to close

Queue & Vibes

Click to close

DJ Page

Full control for the party host. Manage the queue, see who requested what, control playback.

• Full playback controls (play/pause, prev/next, volume, seek)
• Drag-and-drop queue reordering
• See guest requests with attribution ("Mike requested...")
• Guest Vibes panel showing current influences
• Browse and add tracks directly

Desktop

Click to close

Mobile

Click to close

Display Page

TV-friendly display for the living room. Big artwork, lyrics, and a live feed of what guests are requesting.

• Large artwork with glow effect
• Live scrolling lyrics
• Request feed showing joins and song requests
• QR code overlay for easy guest access
• Current Vibes panel
• Floating emoji reactions - Teams-style animations float up when guests react (respects prefers-reduced-motion)

TV Display Mode

Click to close

Floating Reactions

When guests react to tracks, Teams-style emoji animations float up across the Display page in real-time via WebSocket. Reactions are broadcast instantly to all connected display screens.

• Fire, Heart, Like, Dislike, Ban emojis
• Smooth float-up animation with randomized positions
• Respects prefers-reduced-motion for accessibility
• Also available on the Now Playing page (/pages/nowplaying.html)

How It Works

1. DJ visits /pages/partymode/ and starts a party with a PIN
2. Display page shows QR code with embedded PIN
3. Guests scan QR, enter nickname, browse and request songs
4. Requests appear on DJ page and display feed
5. Guests can vote on vibes (thumbs up/down) to influence shuffle
6. Reactions trigger floating emoji animations on Display and Now Playing pages

Discovery Features

• SSDP broadcast on local network
• Appears in Windows Explorer Network view
• Click to open the Dashboard in your browser
• Unique device name includes machine identifier

Player Control

• Play, pause, stop, next, previous
• Volume and mute control
• Seek to position
• Shuffle and repeat modes
• Album navigation (next/previous album)

Now Playing

• Current track metadata (title, artist, album, duration)
• Album artwork (binary image)
• Lyrics
• Playback position

Queue Management

• View entire queue with pagination
• Add tracks (queue next or last)
• Remove tracks by index
• Move/reorder tracks
• Clear queue
• Play track immediately

Library Browsing

• Query files with MusicBee filter syntax
• Filter by artist, album, genre
• Full-text search
• Get/update file tags
• Browse distinct artists, albums, genres
• Pagination support (offset/limit)

Playlist Management

• List all playlists
• Create/delete playlists
• Get playlist tracks
• Add/remove tracks from playlists
• Play entire playlist

Audio Processing

• Equalizer on/off
• DSP effects on/off
• Crossfade on/off
• ReplayGain modes (off, track, album, smart)
• Scrobbling on/off

Event Types

• TrackChanged - Track change with full metadata
• PlayStateChanged - Play, pause, stop state changes
• VolumeChanged - Volume and mute changes
• PositionChanged - Playback position updates
• QueueChanged - Queue modifications
• ShuffleChanged - Shuffle mode changes
• RepeatChanged - Repeat mode changes
• MetadataChanged - Rating, love, or tag changes on a track
• Reaction - Real-time emoji reactions (fire, heart, like, dislike, ban) with nickname and track info

Clients subscribe to specific events via { subscribe: ['TrackChanged', 'Reaction'] }. Empty subscription receives all events.

ARiA Features

• Send keyboard input (SendKeys or DuckyScript format)
• Mouse control (move, click at coordinates)
• Wake sleeping/locked PC remotely
• Volume control (up, down, mute)
• Launch programs
• Send HTTP webhooks
• Show Windows notifications (toast)
• Restart MusicBee or system

Presets & Automation

• Pre-configured presets for MusicBee tab navigation (Ctrl+Alt+A through L)
• Custom presets via JSON configuration
• Command chaining with delays
• Macro support with recursion protection

Smart Shuffle Tracking

• View shuffle cycle progress (% complete)
• Reset shuffle cycle
• View played tracks in current cycle
• View remaining unplayed tracks

Influence System

Influence Controls

Click to close

Pandora-style thumbs up/down for smart shuffle preferences.

• Target by Genre or Artist metadata
• Positive influences boost matching tracks in shuffle
• Negative influences (--) hard exclude matching tracks
• Dashboard thumbs up/down buttons
• REST API for programmatic control

Side panel — wide, everything in one row

Click to close

Narrow — two pages, one toggle

Click to close

Ban List Management

• View all banned tracks
• Ban tracks with optional reason
• Unban tracks

Why a Shell?

MusicBee (especially portable installs) has no registered Application User Model ID. Windows doesn't know who owns the SMTC session, so the media flyout shows a generic or wrong app name. The Shell solves this by being a registered Windows application that communicates with MusicBee over REST.

Same architecture used by Discord, Spotify, and other apps that offload SMTC to helper processes.

SMTC Bridge Features

• Registered AUMID - Windows sees "MBXHub" in the media flyout
• Full metadata sync - Title, artist, album, album artist, artwork, track number
• Playback controls - Play, pause, stop, next, previous, seek
• Timeline - Position and duration with real-time updates
• Shuffle and repeat - Bidirectional sync with MusicBee
• Auto-reconnect - Survives MusicBee restarts, reconnects automatically
• Event-driven - WebSocket events, no polling

Setup

• MBXHub.exe --install - Register AUMID and create Start Menu shortcut
• MBXHub.exe - Start SMTC bridge (auto-installs on first run)
• Configure via mbxhub-shell.json (host, port, retry settings)
• Requires .NET 8.0 Desktop Runtime

MusicBee Detection

MBXHub.exe --detect finds MusicBee across all install types:

• Microsoft Store - Package lookup in AppData
• Installed - Registry (HKLM/HKCU Uninstall keys)
• Portable - Common locations (D:\MusicBee, C:\MusicBee, Program Files)

Sync Features (Coming Soon)

• Discover MBXHub instances on network
• Push/pull files between nodes
• Mirror or selective sync modes
• Track sync operation progress

Method Categories

• Player_* - 30+ playback control methods
• NowPlaying_* - 20+ current track methods
• NowPlayingList_* - 15+ queue methods
• Library_* - 25+ library methods
• Playlist_* - 15+ playlist methods
• Setting_* - 10+ settings methods
• MB_* - 15+ application methods
• Podcasts_* - Podcast subscription methods
• Sync_* - Device sync methods

Local Network Only

• CORS restricted to localhost and local network IPs
• Supports 192.168.x.x, 10.x.x.x, 172.16-31.x.x ranges
• No internet exposure by default
• Request body size limits (1MB max)

API Access Control

Restrict write operations via granular read-only settings.

• Master read-only mode - Disable all write operations API-wide
• Granular controls - Restrict Player, Queue, Library, or Playlists independently
• PartyMode exempt - PartyMode endpoints always functional (voting, requests)
• Returns 403 Forbidden with READ_ONLY error code when blocked
• Configurable in MBXHub Settings panel