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

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

Deprecated Features

NavigationSettings.xml (Deprecated)

The playernavigateto command and NavigationSettings.xml file are deprecated. The older approach required:

1. Client sends tab number via playernavigateto
2. Plugin looks up hotkey mapping in NavigationSettings.xml
3. Plugin sends mapped keys

This has been replaced by playerinitiatoraction where the client sends complete action scripts directly.

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"

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