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

**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. Optionally enhanced with the [CueSharp](https://wyday.com/cuesharp/) library (delay-loaded soft dependency — not required).

## Requirements

| Component | Requires |
|-----------|----------|
| mb_MBXHub.dll | MusicBee + .NET Framework 4.8 (included with Windows 10+) |
| MBXHub.exe | .NET 8.0 Desktop Runtime |

## 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

The plugin creates `mbxhub.json` in MusicBee's AppData directory. Settings are also accessible via the REST API (`GET /system/settings`, `PUT /system/settings`) and the MusicBee Settings UI.

The shell reads `mbxhub-shell.json` from the same directory as the EXE.

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

## Third-Party Dependencies

| Library | License | Used By |
|---------|---------|---------|
| [MusicBee Plugin API](https://getmusicbee.com/forum/index.php?topic=20076.0) | MusicBee SDK | Plugin (host interface) |
| [Newtonsoft.Json](https://github.com/JamesNK/Newtonsoft.Json) | MIT | Plugin, Shell |
| [QRCoder](https://github.com/codebude/QRCoder) | MIT | Plugin (Party Mode QR codes) |
| [Firebug](https://dev.azure.com/halrad/firebug) | MIT | Plugin (in-process checks), Shell (firewall CLI) |
| [SsdpCore](https://dev.azure.com/halrad/firebug) | MIT | Plugin (SSDP/UPnP discovery) |
| [CueSharp](https://wyday.com/cuesharp/) | LGPL | Plugin (optional, delay-loaded) |

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/
