MBRCPVAL - Protocol Validator & Testing Tool

v1.5.26.3 Server Mode Client Mode Proxy Mode

MBRCPVAL is a comprehensive command-line tool for validating, testing, and debugging implementations of the MusicBee Remote (MBRC) protocol. Whether you're developing a server plugin, building a client application, or debugging protocol issues, MBRCPVAL provides the tooling you need.

1. Overview
2. Quick Start
3. Operating Modes
4. Test Categories
5. Command Reference
6. Report Formats
7. Best Practices
8. Installation

1. Overview #

What is MBRCPVAL?

MBRCPVAL (MusicBee Remote Control Protocol Validator) is a developer tool that provides:

Protocol Conformance Testing - Verify that your implementation correctly follows the MBRC protocol specification
Behavioral Validation - Test that commands produce expected responses and state changes
Developer Tooling - Interactive REPL, mock servers, and proxy debugging for development workflows
CI/CD Integration - Generate machine-readable reports for automated testing pipelines

Key Features

Validation

Over 100 test cases covering message format, handshake, player control, library browsing, and v4.5 protocol features.

Mock Server

Spin up a fully-functional mock MBRC server with configurable library size for client development and testing.

Interactive REPL

Explore the protocol interactively, send commands, and inspect responses in real-time.

Proxy Mode

Intercept and log traffic between a client and server for debugging protocol issues.

2. Quick Start #

Get started with MBRCPVAL in seconds. Here are the most common usage patterns:

# Validate a server plugin
mbrcpval server --host localhost --port 3000 --suite all --report html

# Start mock server for client development
mbrcpval mock --port 3000 --generate 1000

# Interactive protocol explorer
mbrcpval repl --host localhost --port 3000

# Proxy mode for debugging
mbrcpval proxy --listen 3001 --target localhost:3000

Tip: Use mbrcpval --help to see all available commands and options. Each subcommand also supports --help for detailed usage information.

3. Operating Modes #

MBRCPVAL operates in three distinct modes, each designed for different use cases:

Server Mode server

Connects as a client to test an existing MBRC server or plugin. Runs test suites, validates protocol compliance, and generates reports.

Use for: Plugin development, regression testing, CI/CD validation

Client Mode mock

Starts a mock MBRC server that simulates MusicBee. Accepts client connections and responds to protocol commands with realistic data.

Use for: Client app development, UI testing, offline development

Proxy Mode proxy

Acts as a man-in-the-middle between client and server, logging all traffic. Useful for debugging protocol issues in existing implementations.

Use for: Debugging, protocol analysis, reverse engineering

Mode Selection Diagram

                          +------------------+
                          |   Your Scenario  |
                          +--------+---------+
                                   |
          +------------------------+------------------------+
          |                        |                        |
          v                        v                        v
+------------------+    +------------------+    +------------------+
|  Testing a       |    |  Developing a    |    |  Debugging       |
|  Server/Plugin?  |    |  Client App?     |    |  Both Sides?     |
+--------+---------+    +--------+---------+    +--------+---------+
         |                       |                       |
         v                       v                       v
+------------------+    +------------------+    +------------------+
| mbrcpval server  |    | mbrcpval mock    |    | mbrcpval proxy   |
| --host --port    |    | --port --generate|    | --listen --target|
+------------------+    +------------------+    +------------------+

4. Test Categories #

MBRCPVAL organizes tests into categories, each with a unique ID prefix. You can run all tests, specific categories, or individual tests by ID.

Test Criticality Levels

Tests are categorized by criticality to help prioritize validation efforts:

Level	Tag	Description	Priority
MANDATORY	`mandatory`	Must pass for basic protocol compliance. Failure indicates broken implementation.	1-30
RECOMMENDED	`recommended`	Should pass for good user experience. Failure indicates degraded functionality.	31-70
OPTIONAL	`optional`	May pass for full feature parity. Failure indicates missing advanced features.	71-100

Certification Levels

Based on test results, implementations can achieve certification:

Bronze - 100% mandatory tests pass
Silver - 100% mandatory + 90% recommended tests pass
Gold - 100% mandatory + 100% recommended + 80% optional tests pass
Platinum - 100% all tests pass

Test Categories

Category	ID Range	Criticality	Description
MSG	MSG-001 to MSG-010	Mandatory	Message format validation - JSON structure, encoding, line termination
HSK	HSK-001 to HSK-010	Mandatory	Handshake sequence - player identification, protocol negotiation, init exchange
PLY	PLY-001 to PLY-020	Mandatory/Rec	Player control - play, pause, stop, seek, volume, shuffle, repeat modes
NP	NP-001 to NP-015	Recommended	Now playing - track info, cover art, lyrics, position updates
QUE	QUE-001 to QUE-010	Recommended	Queue operations - list, add, remove, move, clear, play from queue
LIB	LIB-001 to LIB-020	Recommended	Library browse - genres, artists, albums, tracks, search, pagination
V45	V45-001 to V45-015	Optional	v4.5 protocol features - enhanced metadata, output devices, radio streams
ARIA	ARIA-001 to ARIA-010	Optional	Initiator actions - execute remote hotkeys and actions via protocol
DSC	DSC-001 to DSC-010	Optional	UDP discovery - multicast discovery, response format, subnet matching
ERR	ERR-001 to ERR-010	Mandatory/Rec	Error handling - malformed messages, invalid commands, error responses
PERF	PERF-001 to PERF-010	Optional	Performance - connection throughput, response latency, stress testing

Running Specific Tests

# Run all tests
mbrcpval server --host localhost --suite all

# Run by criticality (mandatory only - Bronze level)
mbrcpval server --host localhost --tags mandatory

# Run mandatory + recommended (Silver level)
mbrcpval server --host localhost --tags mandatory,recommended

# Run specific category
mbrcpval server --host localhost --suite PLY

# Run multiple categories
mbrcpval server --host localhost --suite PLY,NP,QUE

# Run specific test by ID
mbrcpval server --host localhost --test PLY-005

# Run v4.5 specific tests only
mbrcpval server --host localhost --suite V45 --protocol 4.5

5. Command Reference #

`mbrcpval server` - Validate Server/Plugin

Connect to an MBRC server and run validation tests.

Option	Required	Default	Description
`--host`	Yes	-	Server hostname or IP address
`--port`	No	3000	Server TCP port
`--suite`	No	all	Test suite(s) to run (comma-separated or "all")
`--test`	No	-	Run specific test by ID
`--list`	No	false	List all available tests without running them
`--protocol`	No	4.5	Protocol version to test (4.0 or 4.5)
`--report`	No	text	Output format: text, json, html, junit
`--output`	No	stdout	Output file path (or stdout)
`--timeout`	No	30	Command timeout in seconds
`--verbose`	No	false	Show detailed test output
`--fail-fast`	No	false	Stop on first failure

# Full validation with HTML report
mbrcpval server --host 192.168.1.10 --port 3000 --suite all --report html --output report.html

# CI/CD pipeline with JUnit output
mbrcpval server --host localhost --suite MSG,HSK,PLY --report junit --output test-results.xml

`mbrcpval mock` - Start Mock Server

Launch a mock MBRC server for client development and testing.

Option	Required	Default	Description
`--port`	No	3000	TCP port to listen on
`--generate`	No	100	Number of tracks to generate in mock library
`--protocol`	No	4.5	Protocol version to support
`--discovery`	No	true	Enable UDP multicast discovery
`--name`	No	MBRCPVAL-MOCK	Server name for discovery
`--latency`	No	0	Artificial response delay (ms) for testing
`--log`	No	-	Log all protocol traffic to file

# Start mock server with 1000 tracks
mbrcpval mock --port 3000 --generate 1000

# Simulate slow server for timeout testing
mbrcpval mock --port 3000 --latency 500

# Mock server with traffic logging
mbrcpval mock --port 3000 --log traffic.log

`mbrcpval repl` - Interactive Mode

Launch an interactive REPL (Read-Eval-Print Loop) for exploring the protocol.

Option	Required	Default	Description
`--host`	Yes	-	Server hostname or IP address
`--port`	No	3000	Server TCP port
`--protocol`	No	4.0	Protocol version to negotiate
`--history`	No	~/.mbrcpval_history	Command history file

# Start interactive session
mbrcpval repl --host localhost --port 3000

# REPL commands example session:
mbrcpval> .connect                    # Establish connection and handshake
mbrcpval> .send player play          # Send play command
mbrcpval> .send nowplayingtrack       # Request now playing info
mbrcpval> .raw {"context":"ping"}     # Send raw JSON message
mbrcpval> .listen 10                  # Listen for events for 10 seconds
mbrcpval> .disconnect                 # Close connection
mbrcpval> .help                       # Show all REPL commands

`mbrcpval proxy` - Proxy Mode

Start a proxy server that intercepts and logs all traffic between client and server.

Option	Required	Default	Description
`--listen`	No	3001	Port to listen for client connections
`--target`	Yes	-	Target server address (host:port)
`--output`	No	stdout	Log output file
`--format`	No	pretty	Log format: pretty, json, raw
`--filter`	No	-	Filter by context (e.g., "nowplaying*")

# Basic proxy setup
mbrcpval proxy --listen 3001 --target localhost:3000

# Log to file with JSON format
mbrcpval proxy --listen 3001 --target 192.168.1.10:3000 --format json --output trace.json

# Filter to only show nowplaying messages
mbrcpval proxy --listen 3001 --target localhost:3000 --filter "nowplaying*"

`mbrcpval validate` - Validate Single Message

Validate a single JSON message against the protocol specification.

Option	Required	Default	Description
`--message`	No	-	JSON message to validate (inline)
`--file`	No	-	File containing JSON message(s)
`--stdin`	No	false	Read message from stdin
`--direction`	No	auto	Message direction: client, server, auto

# Validate inline message
mbrcpval validate --message '{"context":"player","data":"toggle"}'

# Validate from file
mbrcpval validate --file messages.json

# Validate from pipeline
cat message.json | mbrcpval validate --stdin

6. Report Formats #

MBRCPVAL supports multiple output formats for different use cases:

Text Format (default)

Human-readable console output with colors and formatting.

MBRCPVAL Protocol Validation Report
====================================
Target: localhost:3000
Protocol: v4.0
Date: 2025-01-15 14:32:00

Test Results:
-------------
[PASS] MSG-001: Valid JSON structure
[PASS] MSG-002: CRLF line termination
[PASS] MSG-003: UTF-8 encoding without BOM
[FAIL] HSK-003: Protocol version negotiation
       Expected: {"context":"protocol","data":{"protocol_version":4}}
       Received: (no response within 5000ms)
[SKIP] V45-001: Enhanced metadata (requires v4.5)

Summary: 87 passed, 2 failed, 11 skipped
Duration: 12.4 seconds

JSON Format

Machine-readable format for programmatic processing.

{
  "target": "localhost:3000",
  "protocol": "4.0",
  "timestamp": "2025-01-15T14:32:00Z",
  "results": [
    {
      "id": "MSG-001",
      "name": "Valid JSON structure",
      "status": "pass",
      "duration_ms": 12
    },
    {
      "id": "HSK-003",
      "name": "Protocol version negotiation",
      "status": "fail",
      "error": "Timeout waiting for response",
      "duration_ms": 5000
    }
  ],
  "summary": {
    "passed": 87,
    "failed": 2,
    "skipped": 11,
    "duration_ms": 12400
  }
}

HTML Format

Interactive HTML report with expandable details, suitable for sharing.

mbrcpval server --host localhost --report html --output report.html

Generates a self-contained HTML file with:

Summary dashboard with pass/fail statistics
Collapsible test category sections
Request/response payloads for each test
Timing information and performance graphs

JUnit XML Format

Compatible with CI/CD systems (Jenkins, Azure DevOps, GitHub Actions).

<?xml version="1.0" encoding="UTF-8"?>
<testsuites name="MBRCPVAL" tests="100" failures="2" time="12.4">
  <testsuite name="MSG" tests="10" failures="0">
    <testcase name="MSG-001: Valid JSON structure" time="0.012"/>
    <testcase name="MSG-002: CRLF line termination" time="0.008"/>
  </testsuite>
  <testsuite name="HSK" tests="10" failures="1">
    <testcase name="HSK-003: Protocol version negotiation" time="5.0">
      <failure message="Timeout waiting for response"/>
    </testcase>
  </testsuite>
</testsuites>

7. Best Practices #

For Plugin Developers

Run full validation before release: Use --suite all to catch any protocol regressions
Test both protocol versions: Run tests with --protocol 4.0 and --protocol 4.5
Integrate into CI/CD: Use JUnit output for automated testing in your build pipeline
Focus on error handling: The ERR test suite specifically validates edge cases
Validate discovery: Ensure UDP discovery works with --suite DSC

For Client Developers

Use mock server during development: mbrcpval mock --generate 1000 provides realistic data
Test edge cases: Use --latency to simulate slow connections
Explore with REPL: The interactive mode helps understand protocol behavior
Validate your messages: Use mbrcpval validate to check message format before sending
Test reconnection: Kill and restart the mock server to test your reconnection logic

For QA/Testing

Use proxy mode for debugging: Intercept traffic between real client and server
Generate comprehensive reports: HTML reports are ideal for sharing test results
Run performance tests: The PERF suite measures response times and throughput
Test under load: Use multiple mock clients with the mock server
Compare versions: Run tests against multiple plugin versions for regression testing

8. Installation #

System Requirements

Runtime: .NET 8.0 or later
Operating System: Windows 10/11
Memory: 128 MB minimum (more for large mock libraries)
Network: TCP/UDP access to target server

Installation Steps

Option 1: Download Release

# Download the latest release from GitHub
# Extract to a directory in your PATH

# Verify installation
mbrcpval --version

Option 2: Build from Source

# Clone the repository
git clone https://github.com/halrad/mbrcpval.git
cd mbrcpval

# Build the project
dotnet build -c Release

# Run directly
dotnet run -- server --host localhost --port 3000

Option 3: .NET Tool (Global)

# Install as a global .NET tool
dotnet tool install -g mbrcpval

# Run from anywhere
mbrcpval server --host localhost

Download MBRCPVAL

Get the latest version of MBRCPVAL for your platform.

Download for Windows

View on GitHub | Release Notes

Note: MBRCPVAL is part of the 'MBRC' ecosystem. For the complete MBRC protocol specification, see the Protocol SDK documentation.