Documentation

Getting Started

MBXHub is a MusicBee plugin that exposes the MusicBee API over HTTP. Once installed, you can control MusicBee from any device on your local network.

Installation

Requirements

• Windows 10 or later
• MusicBee 3.5 or later
• .NET Framework 4.8 (the plugin — included with Windows 10+)
• .NET 8.0 Desktop Runtime (the MBXHub.exe companion — media keys, first-run network setup, Overlay)

Steps

1. Get MusicBee if you haven't already
2. Download the latest release ZIP file
3. Extract the ZIP — mb_MBXHub.dll (the plugin), MBXHub.exe (the companion) and mbxutil.exe (maintenance tool)
4. Copy all files to: %APPDATA%\MusicBee\Plugins\ (typically C:\Users\YourName\AppData\Roaming\MusicBee\Plugins, or the Plugins folder next to MusicBee.exe for portable installs)
5. Restart MusicBee — the companion starts with it and, on first run, opens the network setup screen: click Enable network access, then scan the QR code from your phone. You can reopen it any time from the tray icon (Network setup) or Tools → MBXHub → Settings → Firewall
6. Optionally, configure MusicBee hotkeys for ARiA navigation presets
7. Optionally, download Truedat for mood scanning (AutoQ) — see Scanning and the Truedat repository

Verifying Installation

Open the dashboard in your browser (the port is shown on the network-setup screen and in the companion's startup toast; 8080 unless taken):

http://localhost:8080

Configuration

Nearly everything is configurable, and you should not need to edit a file to do it. There are three places to change settings, and they all write to the same config — pick whichever is in front of you.

Settings page (browser)

The fullest surface, and the one to reach for by default. Every setting the plugin exposes is here, grouped by category with its description, range and default:

http://localhost:8080/pages/settings.html

It is linked from the dashboard as Settings, and it works from your phone as well as the machine running MusicBee.

Inside MusicBee

Tools → MBXHub → Settings opens the plugin's own dialog. It carries the settings that have to stay reachable when the network is not — ports, firewall and access control — which is exactly why they are not on the web page. The first-run network setup screen lives here too, and on the companion's tray icon.

Full settings reference

MBXHub serves its own configuration reference, so it always describes the build you actually have rather than whatever a website said at release time:

http://localhost:8080/pages/config.html

Config files

You are welcome to edit these directly, but the settings page is easier and validates what you type. Two processes, two files:

The companion's tray menu has Settings → Open Settings Folder…, which opens the folder its config is actually loaded from — worth using rather than typing a path, especially if MusicBee and the companion are on different machines.

Changing settings from a script

For automation. Send only the keys you want to change; anything you omit is left alone. Keys are the dotted, camelCase paths shown on the settings page:

PUT http://localhost:8080/system/settings
Content-Type: application/json

{
  "debugMode": true,
  "autoQ.enabled": true
}

Three things will refuse you, all deliberately: a few settings (the REST port among them) only change from localhost; remote changes are rejected outright while PartyMode is running; and disableRemoteConfig turns the whole endpoint local-only. Each answers 403 saying which applied.

See the API reference for the full endpoint list.

PartyMode Setup

PartyMode lets guests browse your library and request songs at a party. Three roles: Guest (browse/request), DJ (full control), Display (TV mode).

Quick Start

1. Open http://localhost:8080/pages/partymode/ in a browser
2. Enter a PIN (e.g., 1234) and click "Start Party"
3. Open the Display page on a TV: /pages/partymode/display.html
4. Guests scan the QR code on the display, enter the PIN and their name
5. Guests can now browse and request songs

Pages

Tips

• Use separate PINs for guests and DJ for more control
• The Display page auto-refreshes the QR code every 30 seconds
• Guest vibes (thumbs up/down) influence the shuffle when MBXQ is enabled
• The request feed shows both joins and song requests

ARiA Setup

ARiA (Arbitrary Remote Initiated Actions) enables remote keyboard/mouse control and automation.

How It Works

ARiA actions are defined in the plugin configuration file (mbxhub.json). Each action specifies a script command (like sending keystrokes) that can be triggered remotely. Once ARiA is enabled, you can execute these actions from the REST interface or the dashboard.

The default presets are already configured to send tab navigation hotkeys (Ctrl+Alt+A through L). All you need to do is set up the matching hotkeys in MusicBee and enable ARiA.

Step 1: Open MusicBee Preferences > Hotkeys

1. Open MusicBee on your jukebox/media center PC
2. Go to Edit > Preferences
3. Select Hotkeys from the left panel

Step 2: Configure Tab Navigation Hotkeys

Find the "General: Goto Tab X" actions and assign hotkeys. The screenshot below shows the preconfigured keys:

Example configuration using home-row keys:

Tip: Check the "global" checkbox so the hotkeys work even when MusicBee isn't the focused window. This uses the home-row keys (A, S, D, F, G, H, J, K, L) for easy reach.

Step 3: Enable ARiA in Plugin Settings

1. Still in Preferences, go to Plugins
2. Find MBXHub and click "Configure"
3. Check "Enable ARiA (Arbitrary Remote Initiated Actions)"
4. Click Save to apply all changes

Remember: You can configure any MusicBee hotkey and send it remotely via ARiA - not just tab switching. Play/pause, volume, shuffle, visualizers - anything with a hotkey can be triggered remotely.

Beyond hotkeys: automation preset examples

ARiA scripts aren't limited to keystrokes. Presets are defined under ariaPresets in mbxhub.json (in your MBXHub AppData folder), and the run(…) command can launch a whitelisted external program — so a single dashboard button can scan your library or sync files. Add these keys to your existing mbxhub.json (merge them in — don't replace the whole file), then Save. The presets show up as buttons on the dashboard's ARiA charm.

{
  "ariaPresets": [
    {
      "name": "scan-library",
      "script": "sendkeys({INSERT}); delay(3000); sendkeys(!{ENTER})"
    }
  ]
}

{
  "ariaAllowedPrograms": [
    {
      "name": "music-pull",
      "path": "C:\\Windows\\System32\\Robocopy.exe",
      "args": "\\\\YOUR-SERVER\\Music D:\\Music /MIR /R:2 /W:5 /LOG:D:\\music-pull.log",
      "hidden": true
    },
    {
      "name": "music-push",
      "path": "C:\\Windows\\System32\\Robocopy.exe",
      "args": "D:\\Music \\\\YOUR-SERVER\\Music /E /R:2 /W:5 /LOG:D:\\music-push.log",
      "hidden": true
    }
  ],
  "ariaPresets": [
    {
      "name": "pull-from-server",
      "script": "run(music-pull)",
      "icon": "↓"
    },
    {
      "name": "push-to-server",
      "script": "run(music-push)",
      "icon": "↑"
    }
  ]
}

ARiA Documentation

For complete ARiA documentation including all commands, DuckyScript syntax, presets, and examples, see the ARiA section in the API docs or access /aria directly on your MBXHub instance.

Usage

Basic Usage

Control playback with simple HTTP requests:

# Play/Pause
curl -X POST http://localhost:8080/player/playpause

# Get current track
curl http://localhost:8080/nowplaying

# Set volume to 50%
curl -X PUT http://localhost:8080/player/volume \
  -H "Content-Type: application/json" \
  -d '{"volume": 0.5}'

Advanced Usage

For complete API access, use the RPC endpoint:

# Call any MusicBee API method
curl -X POST http://localhost:8080/rpc/Library_QueryFilesEx \
  -H "Content-Type: application/json" \
  -d '{"query": "[Artist]=Beatles"}'

See the API documentation for all available endpoints.

Troubleshooting

Common Issues

Getting Help

If you need additional help:

• Check the API documentation for endpoint details
• Check the features page for capabilities
• Visit the GitHub repository for issues and discussions