MBXHub

by HALRAD Research

Download MBXHub

MBXHub - The bridge to everything else.

Reflection

Stable. Recommended for most people.

Download
  • EV4: Preferred Persistent Speaker (PPS) — choose your default Cast speaker in MBXCast and enable Automatic connection. Press Play to connect, or enable Keep awake to connect when MusicBee starts. Pause, stop and an empty queue keep the established connection in place.
  • EV4: Wake device when starting a Cast — optionally wake your preferred speaker when playback starts, if it supports Wake-on-LAN.
  • EV4: Keep awake — wake/connect to your preferred speaker without pressing Play and maintain the connection while MusicBee runs. If connection takes longer than 90 seconds, playback stops on Cast and automatic retries pause until you connect the preferred speaker manually; the next MusicBee session uses your saved settings again.
  • EV4: Pop out Cast Control into a desktop overlay or a separate browser window.
  • EV4: Control Cast volume and mute directly from MusicBee.
  • EV4: HUD (app) and Overlay (Hub web) settings refined.
  • EV4: DICE — plays a random album, on the AutoQ panel in MusicBee and the radio toolbar on Play, Stations and ON-AIR.
  • EV4: Refresh Station targeting by this track or from the queue ahead.
  • EV4: Music map: a ring around any track becomes a station — set its size, press Seed, and it starts.
  • EV4: HUD metadata settings in HUD Settings to control how it is displayed.
  • EV4: Configure which Charms are shown in the HUD.
  • EV4: The HUD bonus transport defaults to Explore on new installs.
  • MBXCast — casting from inside MusicBee. A MusicBee plugin that drives the cast engine from the player, and makes casting just another audio endpoint: pick a Cast speaker like any other output, your queue stays MusicBee’s queue, and you switch speakers on the fly without re-routing your audio. The HUD, Play page, dashboard and Cast charm still drive the same cast.
  • Music Map — your library drawn by mood. Every scanned song is a dot colored by its genre. Filter by artist or album, click a dot to Play now or Play next, and watch the radio’s trail and where it is heading. The Song / Library toggle on the ON-AIR Mood Map, or the new Music Map charm in the overlay or a browser.
  • Stations remember the mood. Every way of saving a station now keeps the same settings — flow, genre-free, Tight/Loose, freshness, duration and mood — and playing it puts them back. So a program of two stations can shift the mood, say Upbeat into Night.
  • AutoQ radio doesn’t repeat a song in a session. An mp3 and a FLAC copy of the same song count as one. Recently played songs also stay pushed back for hours instead of minutes.
  • Library track count fixed — it was coming up short when CUE files were in the library.
  • Casting overhaul (beta). Cast MusicBee’s queue to a Google Cast speaker — the speaker fetches each track itself and plays the queue unattended, MusicBee’s queue stays the one queue, and the cast keeps playing through a MusicBee restart. One Cast button on the HUD, Play and the dashboard.
  • API keys — named, revocable credentials for other programs. Read or Read-write, with an explicit Execute grant for ARiA host automation, on the Remote Access tab.
  • Play a whole list, an album or a genre in one call. POST /queue/play-list takes the urls and a position; POST /library/albums/{album}/play and /library/genres/{genre}/play resolve the tracks on the hub, so an automation can name a record and nothing else.
  • Undo — take back what you just did. Ctrl+K on the web pages, Ctrl+Z in the AutoQ Workbench. One step back across queue, volume, mute, bans, ratings, love and skips.
  • Immersive play — the artwork on the whole screen. A control in the corner of the cover fills the display, in a browser or in the HUD overlay; the details and transport fade over it.

Full changelog

Windows 10 or later · MusicBee 3.x · .NET Framework 4.8 · .NET 10.0 Desktop Runtime for MBXHub.exe

Segue

Newest features, less tested.

Download
  • EV4.3.1: Updated Network status in plugin settings.
  • EV4.3.1: Cast to Google speaker groups — groups made in Google Home appear in the cast menu beside the individual speakers.
  • EV4.3.1: Fixed: improved handling for casting between multiple instances by the same user.
  • EV4.3: Artists and Genres lists can split multi-value tags — one row per person or genre (Browse setting).
  • EV4.3: Play / Next / Last on track rows work again in the player page.
  • EV4.2: Cast Control opens at a fixed height instead of filling the screen, and an overlay window that fails to open now logs why instead of failing silently.
  • EV4.1: Revised /status page reporting.
  • EV4: A reload button beside the mood model in Settings.
  • EV4: Music Map fullscreen keeps the map square with the tools beside it on a wide screen, and works inside the HUD.
  • EV4: The Music Map’s Song view shows the playing song and why it is playing.
  • EV3: A better valence read: the mood model’s valence axis was retrained from side-by-side listening comparisons, so tracks spread across the whole range instead of piling up at the ends. Arousal is unchanged. No rescan needed.
  • EV3: Choose the mood model: a new Model setting under AutoQ picks which mood model scores your tracks — Model 296 (the current model), Model 180 (the July 2026 model), or a model file you put in the hub’s data folder. Switching rescores your library on the spot; no rescan and no tag rewrite.
  • EV3: Picking a mood while the radio is on the air now re-aims the run at it; the seeds, station and flow stay as they were.
  • EV3: Fixed: on a portable install the Shell could pick up a neighbouring install’s TrueDat; and a queue request for a file that is not in the library is refused up front instead of failing when the row comes up to play.
  • Smoother transitions: AutoQ matches the end of each track to the start of the next — key and tempo, including half and double time — using TrueDat’s start and end of track analysis. That analysis (edges) is off by default; without it, AutoQ matches on each track’s main key. A new Loudness Smoothing knob evens out volume jumps between tracks (on by default). Requires TrueDat 0.5.5.3 or later.
  • Better track matching: with Prefer key-compatible on, AutoQ now picks tracks whose keys mix with the one before, instead of only reordering what it already chose. Applies to the radio, Fill, stations, Generate and journeys. On by default.
  • Mood data straight from TrueDat: AutoQ can read TrueDat’s database directly, instead of waiting for TrueDat to export its file. Requires TrueDat 0.5.5.3 or later. Off by default; without it, AutoQ uses your mood file as before. The Workbench Mood tab tells you when your mood data is out of date.
  • The AutoQ Workbench’s Features tab is refreshed: the music map now lives on the plot (library dots, the radio trail, the path ahead, hover for a track’s key, right-click to play), and the channel table moved into its own Edit channels… window.
  • DV1: Roll the dice for a single track, not just an album — a new What it rolls choice on the dice page. A track roll never hands you the track already playing, and pairs with Start a station so the music keeps going.
  • When MusicBee won’t start from the Shell or the HUD, it now says why.
  • Fixed: a program plays each station for the time you set, then moves on. Starting a program replaces what was queued.
  • Migration — the TrueDat store. TrueDat can keep its analysis in truedat.db, a SQLite database. Requires MBXHub and TrueDat 0.5.5.3 or later. Reading the store and the start-and-end-of-track analysis are both off by default; turn them on in Settings. Until TrueDat has built the database, MBXHub keeps using your existing mbxmoods.json. Clean install: truedat.exe --store --edges. Upgrade: truedat.exe --store-import, then truedat.exe --edges --refresh for transitions — the refresh re-analyzes every file.

The full changelog is served by the build itself once it is installed.

Windows 10 or later · MusicBee 3.x · .NET Framework 4.8 · .NET 10.0 Desktop Runtime for MBXHub.exe

Previous Versions

Examples

What's Included Description
mb_MBXHub.dll REST API, WebSocket, Dashboard, Discovery, AutoQ, TrueShuffle, Charms, Mixer, Device Proxy, Audio Streaming, Radio
MBXHub.exe Shell - SMTC media controls bridge, Windows app identity, system-tray dashboard / Machines submenu, and firewall configuration (requires .NET 10.0 Desktop Runtime)

Installation

Upgrading? Copy the new files over the old ones and restart MusicBee. Everything else is automatic: If you've customized pages and want to reset them, delete the pages\ folder at %APPDATA%\MusicBee\MBXHub\, or use MBXHub Settings → General → Export Pages to overwrite with the latest versions.

Step 1: Download & Extract

Download and extract all files.

Step 2: Copy to Plugins

Copy the DLL and EXE files to your MusicBee Plugins folder:

  • Default: C:\Program Files (x86)\MusicBee\Plugins\
  • Portable: [MusicBee folder]\Plugins\

The SBOM files are informational and don't need to be copied.

Step 3: Start MusicBee

Launch MusicBee. MBXHub loads automatically.

Step 4: Network Access (for other devices)

The dashboard on this PC (http://localhost:8080) needs nothing. To reach MBXHub from your phone or another computer, allow network access — the first-run setup screen does this in one click (with an admin prompt), or set it up by hand from the Tools menu:

  • MBXHub Settings → Firewall → add the rules (needs administrator)
  • Or export a script and run it in an elevated console

Step 5: Open Dashboard

Open a browser:

http://localhost:8080

You should see the Now Playing dashboard. Use the theme toggle in the header to switch between light and dark modes:

http://localhost:8080/docs
- for the docs.
http://localhost:8080/pages
- for the HTML pages.

Dashboard (embedded)

  • Album artwork and track info
  • Artist/Genre influence buttons
  • Progress bar with seek
  • Ban, star rating, and love buttons
  • Playback controls
  • Volume control (routes to configurable default fader)
  • Charm bar — Mixer, Browse, NowPlaying, Player, Phantom, SMTC Link
  • Shuffle (Off/Shuffle/DJ) and repeat toggles
  • ARiA presets
  • Playlist selector
  • Theme toggle (light/dark/midnight)

Player Page (/pages/player.html)

  • 3-column layout (responsive for tablet/mobile)
  • Browse: Albums, Artists, Genres, Playlists, Podcasts, Radio, Moods
  • Search with instant results
  • Queue panel with Up Next
  • Now, Next, +Q buttons on tracks
  • Lyrics display
  • Fully customizable HTML/CSS/JS
  • Edit in %APPDATA%\MusicBee\MBXHub\pages\

Step 6: Set Up Mood Data (Optional)

AutoQ classifies tracks by mood using 14 audio features extracted by Truedat. Without mood data, AutoQ falls back to genre/BPM metadata estimates.

Mood data lives in a single mbxmoods.json file. MBXHub reads it directly — there's no database, no peer sync, no background scanner. Generate the file once with Truedat and drop it in the right place; AutoQ picks it up on the next startup.

  1. Enable iTunes XML export - In MusicBee, go to Edit → Preferences → Library and enable "iTunes Music Library.xml" export
  2. Download Truedat (source) - Extract the folder
  3. Run Truedat - truedat.exe "iTunes Music Library.xml"
    extract it into \Library\truedat \Library is where the XML is exported, then from the library folder run 'truedat\truedat.exe'
    This scans your library and produces mbxmoods.json. Truedat's scan is incremental and resumable — large libraries take hours (or days) but you can stop and restart any time.
  4. Drop mbxmoods.json next to your library — AutoQ reads it on the next startup. That alone gives mood-aware picks.

Show mood in a MusicBee field (optional)

  1. Name a Custom field in MusicBee (Edit → Preferences → Tags (1)), e.g. AutoQ Mood.
  2. MBXHub Settings → AutoQ → Write mood labels to: → pick that field.
  3. MBXHub Settings → API Access → uncheck Disable library mood tag write.
  4. Open the AutoQ Workbench → Mood tab → click Retag to write the mood into your library. New plays are tagged automatically.
MusicBee Custom Tags Configuration

The custom tag can be configured in mbxhub.json via autoQ.moodTagField and autoQ.moodTagFieldName. This lets you see mood data in MusicBee's column browser, use it in auto-playlists, and sort by mood.

System Requirements

Component Requirement
Operating SystemWindows 10 or later
MusicBeeMusicBee 3.x or later
Framework (Plugin).NET Framework 4.8 (included with Windows 10+)
Framework (Shell).NET 10.0 Desktop Runtime (for MBXHub.exe SMTC bridge — choose the Desktop Runtime column for your architecture).

Configuration

Open MusicBee → Edit → Preferences → Plugins → Configure

Settings and logs are stored in:

%AppData%\MusicBee\MBXHub\

Files:

Default Ports

Service Port
REST API + Dashboard8080
WebSocket8080
Shell SMTC8081 (REST port + 1)

Troubleshooting

Issue Solution
Port already in use Open MusicBee → Edit → Preferences → Plugins → MBXHub → Configure to change port
Connection refused Use the Firewall section in MBXHub Settings to add firewall rules, or manually allow inbound TCP on port 8080
The PC can open it, but a phone or other device can’t If http://localhost:8080 works on the PC but another device on the same Wi-Fi can’t connect — and MBXHub shows no incoming connection — the block is usually on your router, not the PC. Many ISP-supplied routers enable client isolation (also called AP isolation or “guest” mode) or a built-in firewall that blocks device-to-device traffic on your own network. Open your router’s admin page, turn off client/AP isolation, and try lowering or disabling its firewall. This is separate from Windows Firewall — and from UPnP: MBXHub does not use router UPnP/port-forwarding, so leaving that disabled is fine.
Plugin not loading Verify DLL is in correct Plugins folder
Pages not updating after upgrade Page serving: (1) disk file if exists, (2) embedded resource fallback, (3) 404. Disk takes priority for customization, embedded for updates. Delete specific files from %APPDATA%\MusicBee\MBXHub\pages\ and refresh - embedded version served automatically, no restart needed.

Build with the API

MBXHub has a full REST API. Build your own pages, automate your library, or let an AI do it for you.

# Grab the API cheat sheet
curl http://localhost:8080/llms.txt

Feed that to Claude or any AI and ask for what you want:

$ claude "Read http://localhost:8080/llms.txt and build me a vinyl-crate album browser with cover art"

Save the output to %APPDATA%\MusicBee\MBXHub\pages\ and open it at http://localhost:8080/pages/yourpage.html. The API uses relative URLs, so pages work on any MBXHub instance without changes.

Worked examples

Playlist Creator Charm A playlist viewer / editor charm for the dashboard — create, rename, reorder, add / remove tracks. playlist-charm-prompt.md
Pixelblaze LED Controller Charm Embed Pixelblaze’s existing controller page in a dashboard Charm. Includes a manifest, wrapper, and AI prompt; browser and hardware checks remain outstanding. Read the prompt • Walkthrough (.md) • Prompt (.md)
MusicBee MCP server for AI agents A seven-tool MCP server so Claude Desktop and other agents can drive MusicBee through MBXHub. mcp.md • musicbee-mbxhub-mcp.zip
MusicBee Lyrion (LMS - Squeezebox) plugin Browse and stream the MusicBee library on Squeezebox players, with AutoQ picking what plays next. lms-dstm-prompt.md • musicbee-mbxhub-lms-dstm.zip
IKANDY charm manifest A charm manifest for a desktop app: one button that starts IKANDY, in the Tools menu and on the charm bar. app.ikandy.md • app.ikandy.json

For more information, see the MBXHub repository on GitHub.

★ halrad-com/mbxhub on GitHub Browse the samples →

Full API documentation: API Reference • llms.txt

Repositories & Other HALRAD Projects

MBXHub ships as a release from this site. Its repository carries the samples and supplemental material that go with it — the worked examples above, the companion projects, and the hardware field notes the device charms were built from.

Project What it is Repository
MBXHub Samples and supplemental material — the worked examples above (dynaport, lms-dstm, mcp, playlist-charm, library-tree) plus device field notes for the WiiM, Devialet Phantom and Fosi hardware. The hub itself is downloaded from this site. halrad-com/mbxhub
Truedat The mood and fingerprint extractor CLI that writes the mbxmoods.json AutoQ reads — Step 6 of the install guide above. halrad-com/Truedat
Firebug The Windows firewall and URL-ACL helper behind MBXHub's one-click network setup. halrad-com/firebug
Clouseau MusicBee inspector / debugger. halrad.com/mbclouseau