# MBXHub

> **Release Candidate** — Pre-release software. Features and APIs may change before final release.

MBXHub turns MusicBee into a network-accessible music server with a REST API, WebSocket events, and an intelligent queue engine.

## What's in the Bundle

| File               | Description                                                                            |
| ------------------ | -------------------------------------------------------------------------------------- |
| **mb_MBXHub.dll**  | MusicBee plugin — REST API, WebSocket, Party Mode, AutoQ smart queue                   |
| **MBXHub.exe**     | Standalone shell — Windows media controls (SMTC), firewall configuration, app identity |
| SBOM-MBXHub.dll.md | Software bill of materials for the plugin                                              |
| SBOM-MBXHub.exe.md | Software bill of materials for the shell                                               |
| LICENSE            | Freeware license                                                                       |

## Features

**REST API** — Full playback control, library search, now playing, queue management, playlists, artwork, and system configuration over HTTP.

**WebSocket** — Real-time events for track changes, play state, volume, position, queue updates, reactions, and metadata changes.

**AutoQ** — Intelligent queue engine that scores tracks based on listening session taste, mood matching (via Essentia audio features), reactions, influences, diversity, and configurable weights.

Mood vectors are produced by [Truedat](https://github.com/halrad-com/Truedat), a standalone tool that uses [Essentia](https://essentia.upf.edu/) to extract per-track audio features and map each song onto a 2D valence/arousal emotion space.

**Party Mode** — Guest-friendly mode with QR code join, reaction buttons, and configurable access controls. Works across all browsers.

**SMTC Bridge** — MBXHub.exe provides Windows System Media Transport Controls integration so MusicBee appears in the Windows media flyout with full metadata, artwork, and playback controls.

**SSDP Discovery** — Automatic network discovery so clients can find MBXHub without manual IP configuration.

**CUE Sheet Support** — Resolves individual tracks within CUE sheet files. Built-in regex parser with encoding detection (BOM, UTF-8, Windows-1252 fallback).

## Requirements

| Component     | Requires                                                                                                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| mb_MBXHub.dll | MusicBee + .NET Framework 4.8 (included with Windows 10+)                                                                                                                                  |
| MBXHub.exe    | .NET 8.0 Desktop Runtime — [download](https://dotnet.microsoft.com/download/dotnet/8.0/runtime) (pick the **Desktop Runtime** column for your Windows architecture, x64 for most machines) |

## Installation

### Plugin (mb_MBXHub.dll)

Copy `mb_MBXHub.dll` to your MusicBee `Plugins` folder and restart MusicBee. The plugin appears in MusicBee's Settings under Plugins.

### Shell (MBXHub.exe)

Place `MBXHub.exe` in the same folder as the plugin and run it. On first launch, use `MBXHub.exe --install` to register the Windows app identity (AUMID) for proper SMTC integration.

```
MBXHub.exe                  Start SMTC bridge (default)
MBXHub.exe --install        Register app identity + Start Menu shortcut
MBXHub.exe --uninstall      Remove registration
MBXHub.exe --detect         Find MusicBee installations
MBXHub.exe --version        Print version
MBXHub.exe --help           Show all options
```

### Firewall (MBXHub.exe firewall)

Configure Windows Firewall rules for MBXHub's HTTP and discovery ports. Self-elevates via UAC when needed.

```
MBXHub.exe firewall add --name MBXHub --tcp 8080 --udp 45345 --urlacl 8080
MBXHub.exe firewall remove --name MBXHub --port 8080
MBXHub.exe firewall check --name MBXHub --port 8080
MBXHub.exe firewall status
MBXHub.exe firewall open
MBXHub.exe firewall --help
```

Or use the Firewall section in MBXHub Settings inside MusicBee — it calls these commands automatically.

## Configuration

Configure MBXHub from any of: the **web Settings page**, the **MusicBee plugin Settings** dialog, the **Shell tray menu**, or the REST API (`GET /system/settings`, `PUT /system/settings`). You rarely need to touch the files directly.

Under the hood, the plugin stores its settings in `mbxhub.json` under `%APPDATA%\MusicBee\MBXHub\`, and the Shell stores its settings in `mbxhub-shell.json` under `%LOCALAPPDATA%\MBXHub\` (alongside the log and other per-user state).

## API Documentation

When the plugin is running, visit `http://localhost:{port}/docs` for full interactive API documentation, or `http://localhost:{port}/llms.txt` for an AI-friendly endpoint index.

## Dependencies

| Library                                               | License      | Used By                      |
| ----------------------------------------------------- | ------------ | ---------------------------- |
| [MusicBee Plugin API](https://getmusicbee.com/forum/) | MusicBee SDK | Plugin (host interface)      |
| [QRCoder](https://github.com/codebude/QRCoder)        | MIT          | Plugin (Party Mode QR codes) |
| [System.Text.Json](https://github.com/dotnet/runtime) | MIT          | Plugin (settings + API JSON) |

See the SBOM files for complete dependency details.

## Related Projects

| Project                                          | Description                                                                   |
| ------------------------------------------------ | ----------------------------------------------------------------------------- |
| [Truedat](https://github.com/halrad-com/Truedat) | Standalone audio feature extraction tool for MusicBee libraries (open source) |
| [Essentia](https://essentia.upf.edu/)            | Audio analysis library by the Music Technology Group at UPF (open source)     |
| [MusicBee](https://getmusicbee.com/)             | Music manager and player for Windows                                          |

## License

Copyright (c) 2026 Halrad LLC. All rights reserved.

MBXHub is freeware. Free to use with attribution. See LICENSE for full terms.

## Contact

**Email:** mbxhub@halrad.com
**Web:** https://mbxhub.com/
