Technical Appendix & Errata

This appendix provides detailed technical documentation for developers and power users interested in the inner workings of MBXRemote and the ARiA protocol.

ARiA Protocol Architecture

The ARiA (Arbitrary Remote Initiated Actions) system is a command-agnostic transport protocol. The protocol itself doesn't interpret commands - it simply transports action scripts from client to server for execution.

[MBXRemote Client] ──TCP/JSON──> [MusicBee Plugin] ──Execute──> [Windows/MusicBee]
        |                              |                           |
   Action Script                 Command-Agnostic            SendKeys/Commands
   "sndKeys(CTRL ALT Q)"            Transport                  Execution

Protocol Message Format

{
  "context": "playerinitiatoraction",
  "data": "sndKeys(CTRL ALT Q)"
}\r\n

The data field contains an action script string passed unchanged to the plugin's execution engine. The protocol layer never parses or validates this content.

SendKeys Notation Reference

ARiA uses .NET System.Windows.Forms.SendKeys notation for keyboard automation.

Modifier Keys

Special Keys

Key Repeat Syntax

{TAB 3}      // Tab 3 times
{RIGHT 5}    // Right arrow 5 times
+{RIGHT 5}   // Shift+Right 5 times (select 5 characters)

DuckyScript Notation

As an alternative to SendKeys symbols, ARiA also accepts DuckyScript-style notation for key combinations - a more readable, space-separated format.

DuckyScript vs SendKeys

DuckyScript Modifiers

DuckyScript Examples

sndKeys(CTRL ALT A)           // MusicBee Goto Tab 1
sndKeys(CTRL ALT S)           // MusicBee Goto Tab 2
sndKeys(CTRL ALT L)           // MusicBee Goto Tab 9
sndKeys(CTRL SHIFT DELETE)    // Ctrl+Shift+Delete
sndKeys(ALT F4)               // Close window
sndKeys(GUI R)                // Windows Run dialog
sndKeys(CTRL A);delay(100);sndKeys(CTRL C)  // Select all, copy

Both notations can be used interchangeably. Use whichever is more readable for your use case.

Complete Key Mapping Reference

Focus Control Prefixes

Control whether MusicBee receives focus before sending keys:

Examples

sndKeys(CTRL ALT Q)           // Focus MusicBee, send Ctrl+Alt+Q (RIA1)
sndKeys(!mb!CTRL S)           // Explicitly focus MusicBee, save
sndKeys(!nofocus!ALT TAB)     // Alt+Tab without changing focus
sndKeys(!nofocus!WIN D)       // Show desktop (current window)

Windows Key Limitation

For Windows key combinations, the plugin uses Windows API (P/Invoke) when WIN or # is detected:

• WIN D or #d - Show Desktop
• WIN L or #l - Lock Computer
• WIN R or #r - Run Dialog
• WIN TAB or #{TAB} - Task View

MusicBee API Status

Working APIs

Non-Working APIs

ARiA Security Model

Plugin Version Requirement

ARiA requires plugin version 1.5+. The plugin version determines ARiA support:

ARiA Command Responses (v1.5+)

When ARiA commands are sent to plugin 1.5+, the plugin responds with one of three values:

Enable/Disable Control

ARiA is controlled via a checkbox in the MusicBee Remote plugin settings:

• Location: MusicBee → Edit → Preferences → Plugins → MusicBee Remote → Configure
• Setting: "Enable ARiA (Arbitrary Remote Initiated Actions)"
• Default: Disabled (for security)
• Storage: %APPDATA%\MusicBee\mb_remote\settings.xml

What Works When ARiA is Disabled

• Standard music controls (play, pause, next, previous)
• Volume control
• Library browsing
• Playlist management
• Now playing information
• All non-keyboard-automation features

Security Considerations

Mitigations:

• ARiA disabled by default - explicit opt-in required
• Use firewall to restrict plugin access to local network only
• Never expose plugin port to internet
• Default focus behavior targets MusicBee (safer)
• !nofocus! prefix required for system-wide control

Protocol Version History

Protocol Negotiation

Plugin v1.5+ performs protocol negotiation based on client request:

• Client requests v4 → Server responds v4.0 (legacy mode, no extended metadata)
• Client requests v4.5 → Server responds v4.5 (extended metadata enabled)

This ensures backwards compatibility: legacy clients (Android/iOS v4.0) continue to work while modern clients (MBXRemote) get extended features.

Additive Fields (Always Sent)

These fields are always included regardless of protocol version:

• AlbumCount in browseartists response
• ArtistCount in browsegenres response

Extended Metadata (v4.5 Only)

These fields are only included when v4.5 is negotiated:

• year, rating, bitrate, format, playcount, skipcount, lastplayed, dateadded, loved in browsetracks response

Library Metadata Sync

MBXRemote syncs library metadata from MusicBee to a local SQLite cache. This section documents the sync direction for each field.

Field Sync Direction

Sync Direction Legend

Remote Library Editing Settings

Remote library editing is controlled via Settings > Database > Remote Library Editing:

Protocol Testing

MBXRemote includes a hidden Protocol Compatibility Tester for developers and advanced users to verify plugin compatibility.

Tests Performed

• Protocol Negotiation: Verifies v4 clients get v4.0 responses, v4.5 clients get v4.5
• Extended Metadata: Validates v4 excludes and v4.5 includes year/rating/bitrate/format
• ARiA Availability: Tests if ARiA is enabled (sends harmless delay(1) command)
• Browse Endpoints: Tests browseartists, browsegenres, browsealbums, browsetracks
• Additive Fields: Detects new fields like AlbumCount, ArtistCount
• Backwards Compatibility: Generates warnings if legacy clients might break
• Service Discovery: Tests UDP multicast discovery on 239.1.5.10:45345
• JSON Serialization: Validates Newtonsoft.Json format compatibility

XML/DB Comparison

The Protocol Tester also includes an XML/DB Comparison tool to validate cache integrity:

• Compare: MusicBee library XML export vs local SQLite cache
• Supported Formats: MusicBee XML, iTunes XML, generic XML
• Reports: Tracks only in XML, only in DB, and field differences
• Usage: Click "XML/DB Compare" button and select a MusicBee library export file

The tester generates detailed reports that can be saved to text files for analysis.

Troubleshooting Reference

Keys Not Working

• Verify MusicBee hotkeys are configured (Ctrl+Alt+Q through P for RIA1-10)
• Check plugin logs show "Sending keys:" messages
• Ensure no security software blocks SendKeys
• Verify ARiA is enabled in plugin settings

Wrong Window Receives Keys

• Use !mb! prefix to ensure MusicBee focus
• Check which window has focus before sending
• Add delays between focus change and key send

Debug Logging

Plugin logs are stored at:

%APPDATA%\MusicBee\mb_remote\

Key log entries to check:

"Executing action script: [script]"
"Sending keys: [keys]"
"Focused MusicBee window"
"ARiA functionality is disabled"

Local Database Architecture

MBXRemote uses a local SQLite database for caching library data, enabling fast browsing and searching without constant network requests to MusicBee.

Technology Stack

Database Location

%APPDATA%\MBXRemote\musicbee.db

Cached Entities

Synchronization Strategy

Library data is synchronized from MusicBee on-demand:

• Full Sync: Downloads entire library on first connection or manual refresh
• Incremental Sync: Uses collection hash to detect changes
• Pagination: Large libraries synced in batches (default: 500 items per request)
• Progress Tracking: SyncMetadata table tracks last sync time, count, and duration

Virtual List Mode

For large libraries (200,000+ tracks), MBXRemote uses virtual list mode to avoid loading all data into memory:

• ListView only loads visible rows + buffer
• Database queries fetch data on-demand as user scrolls
• Supports libraries with millions of tracks without performance degradation
• Memory usage stays constant regardless of library size

Database Schema (EF Core)

// Entity Framework Core model configuration
public class MusicBeeContext : DbContext
{
    public DbSet<CachedTrack> CachedTracks { get; set; }
    public DbSet<CachedAlbum> CachedAlbums { get; set; }
    public DbSet<CachedArtist> CachedArtists { get; set; }
    public DbSet<CachedGenre> CachedGenres { get; set; }
    public DbSet<CachedPlaylist> CachedPlaylists { get; set; }
    public DbSet<Connection> Connections { get; set; }
    public DbSet<SyncMetadata> SyncMetadata { get; set; }
}

SQLite Connection String

Data Source=%APPDATA%\MBXRemote\musicbee.db;
Mode=ReadWriteCreate;
Cache=Shared;
Pooling=True

Database Management

MBXRemote provides a Database Manager dialog (Settings tab) for:

• Viewing cache statistics (track/album/artist counts)
• Clearing cached data
• Forcing full re-sync
• Viewing sync history

ETL Use Case: Library Data Export

MBXRemote's caching system functions as an ETL (Extract, Transform, Load) pipeline for MusicBee library data. The SQLite database can be used independently for:

• Data Analysis: Query your music collection with SQL
• Reporting: Generate statistics, play count reports, genre breakdowns
• Integration: Feed data into other applications (BI tools, scripts, web apps)
• Backup: Portable snapshot of library metadata
• Cross-Platform: Access MusicBee data from Linux/macOS via SQLite

ETL Pipeline

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  MusicBee   │────>│  MBXRemote  │────>│   SQLite    │
│  Library    │     │  Protocol   │     │   Database  │
└─────────────┘     └─────────────┘     └─────────────┘
    EXTRACT           TRANSFORM            LOAD

  - browsetracks      - Normalize         - CachedTracks
  - browsealbums      - Index             - CachedAlbums
  - browseartists     - Deduplicate       - CachedArtists
  - browsegenres      - Type casting      - CachedGenres

Example SQL Queries

-- Top 10 artists by track count
SELECT Name, TrackCount, AlbumCount
FROM CachedArtists
ORDER BY TrackCount DESC
LIMIT 10;

-- Genre distribution
SELECT Name,
       (SELECT COUNT(*) FROM CachedTracks WHERE Genre = CachedGenres.Name) as Tracks
FROM CachedGenres
ORDER BY Tracks DESC;

-- Albums from a specific year
SELECT Name, Artist, TrackCount
FROM CachedAlbums
WHERE Year = '2024';

-- Tracks with high bitrate
SELECT Title, Artist, Album, Bitrate
FROM CachedTracks
WHERE Bitrate >= 320
ORDER BY Bitrate DESC;

Access Methods

Diagnostics and Performance Monitoring

MBXRemote includes comprehensive diagnostic logging for troubleshooting and performance analysis.

DiagnosticsService

A singleton service that tracks performance metrics throughout application lifecycle:

Log Markers for Analysis

Use these markers to filter logs for specific analysis:

Memory Snapshot Format

MEMORY [context]: WorkingSet=150.2MB, Private=180.5MB, GCHeap=45.3MB, Handles=512, Threads=24, GC(Gen0/1/2)=15/3/1

Performance Summary (Shutdown)

=== PERFORMANCE SUMMARY ===
Uptime: 01:23:45
Total Commands Sent: 1,234, Received: 1,230
Total Bytes Sent: 45,678, Received: 12,345,678
CMD [browsetracks]: Count=5, Avg=234.5ms, P95=450ms, Min=120ms, Max=890ms, Errors=0
CMD [browsealbums]: Count=3, Avg=156.2ms, P95=200ms, Min=120ms, Max=210ms, Errors=0
=== END PERFORMANCE SUMMARY ===

Library Sync Timing

=== LIBRARY SYNC STARTING (Full) ===
MEMORY [sync-start]: WorkingSet=95.3MB, Private=120.5MB, GCHeap=35.1MB, Handles=412, Threads=18, GC(Gen0/1/2)=8/2/0
SYNC_STAGE: Genres completed in 234ms
SYNC_STAGE: Albums completed in 567ms
SYNC_STAGE: Artists completed in 890ms
SYNC_STAGE: Tracks completed in 12345ms
SYNC_STAGE: Playlists completed in 123ms
=== LIBRARY SYNC COMPLETED in 14159ms ===
MEMORY [sync-complete]: WorkingSet=180.2MB, Private=210.5MB, GCHeap=85.3MB, Handles=425, Threads=20, GC(Gen0/1/2)=15/3/1

Enabling Verbose Diagnostics

Enable detailed logging in Settings > General > Enable Logging for:

• Debug-level log output
• All command timing logs
• Periodic memory snapshots (every 60 seconds)
• Full network traffic logging

Log File Location

%PROGRAMFILES%\MBXRemote\logs\tntctl.log

(tntctl = tntctl remote viewer technologies)

Logs are rotated daily with 7-day retention.

Design Philosophy

The "Sandworm" Protocol

The ARiA protocol acts as a transport tunnel that carries action scripts without understanding or interpreting them. Like the sandworms of Arrakis that transport spice harvesters without knowledge of their cargo, the protocol simply moves action scripts from client to server.

This separation allows:

• Client Freedom: Clients can send any action script syntax
• Plugin Control: Plugin decides how to execute received scripts
• Future Extension: New command types without protocol changes
• Clean Architecture: Clear separation between transport and execution

Why SendKeys Instead of API?

MusicBee's MB_InvokeCommand(Command.NavigateTo) didn't work for tab switching. The Command enum only has one value (NavigateTo = 1) with no documentation on parameters. Testing showed no consistent behavior.

SendKeys provides a universal solution that:

• Works with MusicBee's existing hotkey system
• Allows user customization of both client and MusicBee hotkeys
• Can automate any keyboard-driven task
• Evolved from specific (tab navigation) to general-purpose automation

The "Jellybee" Codename

MBXRemote v1.0.26.3 is codenamed "Jellybee" - a portmanteau combining:

• Jelly - from the jellyfish mascot (tntctl 🪼)
• Bee - from MusicBee 🐝

The jellyfish represents tntctl (tntctl remote viewer technologies) - the underlying engine that powers MBXRemote's library sync, offline browsing, and local caching. The name "tntctl" rhymes with "tentacle," fitting the aquatic theme.

PartyMode REST API

PartyMode exposes a REST API for guest access to the MusicBee library. All endpoints except /api/session/validate require a valid session token.

Authentication

// Request
POST /api/session/validate
Content-Type: application/json

{ "pin": "1234" }

// Response (200 OK)
{ "token": "abc123...", "expires_in": 1800 }

// Response (401 Unauthorized)
{ "error": "Invalid PIN" }

// Response (429 Too Many Requests)
{ "error": "Too many attempts. Try again in X seconds" }

Library Endpoints

Queue Endpoints

// Request
POST /api/queue/add
Authorization: Bearer {token}
Content-Type: application/json

{ "trackId": 123, "requester": "Guest" }

// Response (200 OK)
{ "success": true, "position": 5 }

// Response (429 Rate Limited)
{ "error": "Rate limit exceeded", "retry_after": 30 }

// Response (403 Queue Full)
{ "error": "Max pending requests reached" }

Authorization Header

All authenticated endpoints require the Authorization header:

Authorization: Bearer {token}

Rate Limiting

PartyMode implements per-session rate limiting to prevent abuse:

• Requests per minute: 10 (configurable via PartyModeRateLimitPerMinute)
• Max pending per session: 3 (configurable via PartyModeMaxQueuePerSession)
• Session timeout: 30 minutes (configurable via PartyModeSessionTimeoutMinutes)

PIN Protection & Lockout

PartyMode protects against brute-force PIN guessing with automatic rate limiting and lockout:

How it works:

• Each IP address is tracked separately
• After 5 failed PIN attempts in one minute, further attempts are rejected with "Too many attempts"
• After 10 total failed attempts within 15 minutes, the IP is locked out for 15 minutes
• Lockouts are stored in memory and reset when MBXRemote restarts
• Successful PIN entry does not reset the failed attempt counter

Note: The lockout is per-IP and in-memory only. Restarting MBXRemote clears all lockouts. For persistent bans, use your router's firewall or Windows Firewall rules.

QR Code for PartyMode

MBXRemote can generate a printable QR code that guests scan to join PartyMode instantly - no need to type a URL or PIN.

Using the Built-in QR Code Generator

1. Go to Settings > Firewall > PartyMode
2. Make sure you have generated a PIN (click "New PIN" if needed)
3. Click "Show QR Code"
4. Enter your PIN when prompted
5. A dialog shows the QR code with options to Print or Copy URL

How It Works

• The QR code embeds your PartyMode URL with the PIN included
• Guests scan the code and go directly to the jukebox - no PIN entry needed
• For manual access (no QR), guests use the base URL and enter the PIN

Tips

• Print it: Use the Print button to create a party-ready handout
• Static IP: Use a static IP or hostname so the QR code doesn't change
• Test first: Scan the QR code yourself to verify it works before the party
• Security: The PIN is cleared from the browser URL after login for security

Manual QR Code Generation

If you prefer to generate QR codes yourself, use any free QR code generator with this URL format:

http://YOUR_IP:8080?pin=YOUR_PIN

Services like qr-code-generator.com or qrcode-monkey.com work well.

Developer Test Mode

MBXRemote includes hidden developer tools for testing, debugging, and documentation. These are accessed via keyboard shortcuts and are intended for developers, testers, and power users.

Protocol Tester (Ctrl+Shift+Alt+T)

A comprehensive protocol compatibility tester that validates plugin functionality and protocol negotiation.

Test Categories

Output

• Results displayed in scrollable log with pass/fail indicators
• Auto-saves to logs/protocol-test-YYYYMMDD-HHMMSS.txt
• XML/DB comparison saves to logs/xmldb-compare-YYYYMMDD-HHMMSS.txt
• Manual export via Save button

UI Gallery (Ctrl+Shift+Alt+U)

A UI testing and screenshot capture tool for documentation and visual regression testing.

Capabilities

Output (Auto-Saved)

Screenshots and results are automatically saved to:

{MBXRemote.exe location}\assets\screenshots\

Files are named systematically for documentation use:

• Tab-NowPlaying.png, Tab-Library.png, etc.
• Settings-General.png, Settings-Hotkeys.png, etc.
• Dialog-QRCode.png, Dialog-Favorites.png, etc.
• ui-gallery-results.txt - Summary report with pass/fail status

Test Results File

Each capture run generates a results file:

===========================================
MBXRemote UI Gallery Capture Results
Captured: 2025-12-26 14:30:00
Version: 1.0.26.3
===========================================

SUMMARY: 13 passed, 0 failed, 13 total

--- RESULTS ---
[PASS] Tab-NowPlaying
[PASS] Tab-Library
[PASS] Tab-Playlists
...

--- FILES CAPTURED ---
  Tab-NowPlaying.png
  Tab-Library.png
  ...

===========================================
End of report

PartyMode Tester (Ctrl+Shift+Alt+P)

A comprehensive HTTP endpoint tester for validating PartyMode web server functionality.

Test Categories

Output (Auto-Saved)

• Color-coded results: green (pass), red (fail), orange (warning)
• HTTP status codes and response times for each endpoint
• Auto-saves to logs/partymode-test-YYYYMMDD-HHMMSS.txt
• Summary with pass/fail counts and total duration
• Toggle auto-save with checkbox in toolbar

Developer Hotkey Summary

MusicBee ARiA Hotkeys

MBXRemote can automatically configure MusicBee with ARiA-style global hotkeys for tab navigation and visualizer control. These hotkeys work system-wide, even when MusicBee is not focused.

ARiA Hotkey Mappings

The ARiA system uses Ctrl+Alt combined with home row keys (QWERTY left hand: A-L) for tab navigation:

Visualizer Hotkeys

Control MusicBee's visualizer remotely using these global hotkeys:

Automatic Configuration

MBXRemote can automatically add these hotkeys to your MusicBee settings file:

1. Go to Settings > Hotkeys
2. Click "MusicBee ARiA Keys"
3. MBXRemote will scan for your MusicBee settings file
4. Review the current status (which hotkeys are already configured)
5. Click Yes to add missing hotkeys
6. Restart MusicBee for changes to take effect

Key Code Calculation

MusicBee key codes are calculated as: Modifiers + VirtualKeyCode

Example: Ctrl+Alt+A = 393216 (Ctrl+Alt) + 65 (A) = 393281

Settings File Location

MusicBee stores hotkey settings in its main configuration file. Common locations:

XML Format

Hotkeys are stored in the <HotKeys> section as <KeyCommandPair> elements:

<HotKeys>
  <KeyCommandPair>
    <Key>393281</Key>
    <Command>GeneralGotoTab1</Command>
    <IsGlobal>true</IsGlobal>
  </KeyCommandPair>
  <KeyCommandPair>
    <Key>393302</Key>
    <Command>ViewToggleVisualiser</Command>
    <IsGlobal>true</IsGlobal>
  </KeyCommandPair>
  ...
</HotKeys>