Documentation

Welcome to the MBXRemote documentation. Browse the guides below to learn about all features and capabilities.

Features Overview

Complete guide to all MBXRemote features including library sync, playback control, and advanced options.

Keyboard Shortcuts

Full list of keyboard shortcuts and global hotkeys for quick access to all functions.

Initiator Actions

Remote Initiated Actions to control MusicBee's UI on your jukebox/media center from across the room.

MusicBee Plugin

Plugin installation, configuration, and the extended RIA plugin for full Initiator Actions support.

Download & Install

Get the latest version and learn about installation requirements.

Quick Start Guide

1. Installation

Download MBXRemote from the download page
Extract the ZIP file to any location
Run MBXRemote.exe
If prompted, install .NET 8.0 Runtime

2. First Connection

Ensure MusicBee is running with the Remote plugin enabled
MBXRemote will auto-discover MusicBee instances on your network
Select your MusicBee instance from the list
Click Connect

3. Library Sync

After connecting, MBXRemote will sync your music library to a local SQLite database. This allows offline browsing and fast searches. The initial sync may take a few minutes for large libraries.

4. Basic Controls

Play/Pause: Click the play button or press Space
Next/Previous: Use the transport buttons or Ctrl+Right/Ctrl+Left
Volume: Use the volume slider or Ctrl+Up/Ctrl+Down
Mute: Click the speaker icon or press Ctrl+M

Application Architecture

Technology Stack

Framework: .NET 8.0 LTS with C# 12
UI Framework: Windows Forms with High DPI support
Database: SQLite with Entity Framework Core 8.0
Networking: TCP sockets with MusicBee Remote Protocol v4
Serialization: Newtonsoft.Json for protocol messages
Logging: NLog for structured logging

Configuration

Settings Location

All settings are stored in: %APPDATA%\MBXRemote\settings.json

Database Location

The library cache database is stored in: %APPDATA%\MBXRemote\musicbee.db

Log Files

Application logs are stored in: %APPDATA%\MBXRemote\logs\

Protocol Information

MBXRemote implements the MusicBee Remote Protocol v4, which uses JSON over TCP with CRLF termination.

Message Format

{
  "context": "command_name",
  "data": {
    "field": "value"
  }
}

Key Protocol Commands

playerplay, playerpause, playerplaypause - Playback control
playernext, playerprevious, playerstop - Transport
playervolume, playermute - Volume control
nowplayingtrack, nowplayingcover - Now playing info
browsetracks, browseartists, browsealbums - Library browsing

Troubleshooting

Connection Issues

Ensure MusicBee is running with the Remote plugin enabled
Check that both computers are on the same network
Verify firewall allows UDP port 5900 for discovery
Try manual connection using MusicBee's IP address

Performance Issues

For large libraries (100,000+ tracks), initial sync may take several minutes
Virtual list mode handles large libraries efficiently
Database operations are optimized for speed

Hotkey Conflicts

If global hotkeys don't work, check for conflicts with other applications
Customize hotkeys in Settings > Hotkeys
Disable conflicting hotkeys in other applications