MBXHub

Documentation

Quick Navigation

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

Steps

  1. Get MusicBee if you haven't already
  2. Download the latest release ZIP file
  3. Extract mb_MBXHub.dll and MBXHub.exe
  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
  6. Go to Tools → MBXHub Settings and click Configure Firewall to allow network access
  7. Optionally, configure MusicBee hotkeys for ARiA navigation presets

Verifying Installation

Open the dashboard in your browser:

http://localhost:8080

Configuration

MBXHub can be configured via the REST API or by editing the settings file.

Settings

Setting Default Description
RestEnabled true Enable/disable REST API
RestPort 8080 HTTP port for REST API
RpcEnabled true Enable/disable RPC endpoint
DebugMode false Enable verbose logging

Changing Settings via API

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

{
  "restPort": 8080,
  "debugMode": true
}

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

Page URL Purpose
Join /pages/partymode/ PIN + nickname entry
Guest /pages/partymode/guest.html Browse and request songs
DJ /pages/partymode/dj.html Full queue control, see requests
Display /pages/partymode/display.html TV mode with artwork, lyrics, QR code

Tips

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:

MusicBee Preferences > Hotkeys
MusicBee Preferences showing hotkey configuration for tab navigation

Example configuration using home-row keys:

MusicBee Action Hotkey Global
General: Goto Tab 1Ctrl+Alt+AYes
General: Goto Tab 2Ctrl+Alt+SYes
General: Goto Tab 3Ctrl+Alt+DYes
General: Goto Tab 4Ctrl+Alt+FYes
General: Goto Tab 5Ctrl+Alt+GYes
General: Goto Tab 6Ctrl+Alt+HYes
General: Goto Tab 7Ctrl+Alt+JYes
General: Goto Tab 8Ctrl+Alt+KYes
General: Goto Tab 9Ctrl+Alt+LYes
Player: Toggle VisualiserCtrl+Alt+Shift+VYes
Player: Visualiser FullscreenF11Yes

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.

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

Issue: Cannot connect to localhost:8080

Solution: Check that MusicBee is running and the plugin is loaded. Look in MusicBee's plugin settings to verify MBXHub is enabled. Check Windows Firewall isn't blocking the port.

Issue: CORS errors in browser

Solution: MBXHub restricts CORS to localhost and local network IPs (192.168.x.x, 10.x.x.x, 172.16-31.x.x). Ensure your request originates from an allowed IP range.

Issue: Port already in use

Solution: Change the REST port in settings to an available port (e.g., 8081).

Issue: Can't find the Plugins folder (Windows Store version)

Solution: The Windows Store version of MusicBee uses a sandboxed location that's difficult to access. Use the portable version instead for easier plugin installation.

Issue: Pages not updating after upgrade

How page serving works:

  1. Check if file exists on disk → serve from disk
  2. If not found on disk → serve from embedded resources
  3. If not found in either → 404

Disk files take priority (for customization), embedded resources as fallback (for updates/defaults).

Solution: Delete specific files from %APPDATA%\MusicBee\MBXHub\pages\ and refresh your browser. The embedded version will be served automatically - no restart needed.

Note: Back up any customizations before deleting.

Getting Help

If you need additional help: