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

// Recommended socket options for clients
socket.NoDelay = true;           // Disable Nagle algorithm for low latency
socket.ReceiveTimeout = 30000;   // 30 second receive timeout
socket.SendTimeout = 5000;       // 5 second send timeout
socket.KeepAlive = true;         // Enable TCP keep-alive

{
  "context": "discovery",
  "address": "192.168.1.50"
}

{
  "context": "notify",
  "address": "192.168.1.10",
  "name": "DESKTOP-MUSICBEE",
  "port": 3000
}

{
  "context": "error",
  "description": "missing address"
}

public async Task<List<DiscoveredServer>> DiscoverServersAsync(int timeoutMs = 3000)
{
    var servers = new List<DiscoveredServer>();
    var multicast = IPAddress.Parse("239.1.5.10");
    var port = 45345;

    using var udp = new UdpClient();
    udp.Client.SetSocketOption(SocketOptionLevel.Socket, SocketOptionName.ReuseAddress, true);
    udp.JoinMulticastGroup(multicast);

    // Get local IP for the request
    var localIp = GetLocalIPAddress();
    var request = JsonConvert.SerializeObject(new {
        context = "discovery",
        address = localIp
    });
    var bytes = Encoding.UTF8.GetBytes(request);

    // Send discovery request
    await udp.SendAsync(bytes, bytes.Length, new IPEndPoint(multicast, port));

    // Collect responses until timeout
    var deadline = DateTime.UtcNow.AddMilliseconds(timeoutMs);
    while (DateTime.UtcNow < deadline)
    {
        udp.Client.ReceiveTimeout = (int)(deadline - DateTime.UtcNow).TotalMilliseconds;
        try
        {
            var endpoint = new IPEndPoint(IPAddress.Any, 0);
            var response = udp.Receive(ref endpoint);
            var json = Encoding.UTF8.GetString(response);
            var server = JsonConvert.DeserializeObject<DiscoveredServer>(json);
            if (server?.Context == "notify")
                servers.Add(server);
        }
        catch (SocketException) { break; } // Timeout
    }

    return servers;
}

public class DiscoveredServer
{
    [JsonProperty("context")] public string Context { get; set; }
    [JsonProperty("address")] public string Address { get; set; }
    [JsonProperty("name")] public string Name { get; set; }
    [JsonProperty("port")] public int Port { get; set; }
}

// Recommended socket configuration
socket.NoDelay = true;           // Disable Nagle algorithm (low latency)
socket.ReceiveTimeout = 30000;   // 30 second receive timeout
socket.SendTimeout = 5000;       // 5 second send timeout
writer.NewLine = "\r\n";         // CRLF line termination

{
  "context": "player",
  "data": "android"
}

{
  "context": "protocol",
  "data": {
    "protocol_version": 4,
    "no_broadcast": false
  }
}

{
  "context": "init",
  "data": null
}

// Server responds with negotiated version based on client request
{
  "context": "protocol",
  "data": 4.0      // Client requested v4 - no extended metadata
}

{
  "context": "protocol",
  "data": 4.5      // Client requested v4.5+ - extended metadata enabled
}

// Request
{"context": "pluginversion", "data": null}

// Response
{"context": "pluginversion", "data": "1.5.26.3"}

// Version mapping:
// Plugin 1.4.x = MusicBee 3.0 SDK (no podcasts, no album nav)
// Plugin 1.5.x = MusicBee 3.1 SDK (podcasts, album nav, playlist notifications)
//
// Protocol version is negotiated - request v4.5 to get extended metadata
// ARiA availability depends on plugin settings (separate from protocol version)

// Client sends ping
{"context": "ping", "data": null}

// Server responds with pong
{"context": "pong", "data": null}

{"context": "verifyconnection", "data": null}

// Request
{"context": "pluginversion", "data": null}

// Response
{"context": "pluginversion", "data": "1.5.26.3"}

// Request
{"context": "plugininstanceid", "data": null}

// Response
{"context": "plugininstanceid", "data": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}

// Set absolute volume (0-100)
{"context": "playervolume", "data": "75"}

// Increase volume by 5
{"context": "playervolume", "data": "+5"}

// Decrease volume by 5
{"context": "playervolume", "data": "-5"}

{"context": "playermute", "data": "toggle"}  // or "on" / "off"

// Shuffle
{"context": "playershuffle", "data": "toggle"}  // or true/false

// Repeat modes: "none", "all", "one", "toggle"
{"context": "playerrepeat", "data": "all"}

{"context": "playerautodj", "data": true}  // or false

// Request
{"context": "playerstatus", "data": null}

// Response (Complete Player Status)
{
  "context": "playerstatus",
  "data": {
    "playerrepeat": "None",       // "None", "All", "One"
    "playermute": false,         // boolean
    "playershuffle": "off",      // See shuffle states below
    "playerscrobble": true,     // Last.fm scrobbling enabled
    "playerstate": "Playing",    // "Playing", "Paused", "Stopped"
    "playervolume": "75"         // String "0"-"100"
  }
}

// Request
{"context": "nowplayingtrack", "data": null}

// Response
{
  "context": "nowplayingtrack",
  "data": {
    "artist": "Artist Name",
    "album": "Album Name",
    "albumArtist": "Album Artist",
    "title": "Track Title",
    "year": "2024",
    "genre": "Rock",
    "path": "/path/to/file.mp3",
    "duration": 240000,        // milliseconds
    "rating": 4.5,             // 0-5 scale
    "playCount": 5,
    "bitrate": 320,            // kbps
    "format": "MP3",
    "trackNo": 5,
    "discNo": 1
  }
}

// Request
{"context": "nowplayingcover", "data": null}

// Response (Base64 encoded JPEG/PNG)
{
  "context": "nowplayingcover",
  "data": "iVBORw0KGgoAAAANSUhEUgAAAAUA..."
}

// Get current position
{"context": "nowplayingposition", "data": null}

// Response
{"context": "nowplayingposition", "data": {"position": 45000}}

// Seek to position (milliseconds)
{"context": "nowplayingposition", "data": 60000}

// Request current rating (use "-1")
{"context": "nowplayingrating", "data": "-1"}

// Set rating (0-5, as string with decimal)
{"context": "nowplayingrating", "data": "4.5"}

// Request current status (use "-1")
{"context": "nowplayinglfmrating", "data": "-1"}

// Set: "love", "ban", or "normal"
{"context": "nowplayinglfmrating", "data": "love"}

// Request
{"context": "nowplayinglyrics", "data": null}

// Response (lyrics found)
{
  "context": "nowplayinglyrics",
  "data": {
    "status": 200,
    "lyrics": "First line of lyrics\nSecond line of lyrics\n\nVerse two..."
  }
}

// Response (no lyrics)
{
  "context": "nowplayinglyrics",
  "data": {
    "status": 404,
    "lyrics": ""
  }
}

// Request
{"context": "nowplayingdetails", "data": null}

// Response (complete format)
{
  "context": "nowplayingdetails",
  "data": {
    // Core metadata
    "albumArtist": "Pink Floyd",
    "genre": "Progressive Rock",
    "trackNo": "6",
    "trackCount": "13",
    "discNo": "2",
    "discCount": "2",
    "grouping": "",
    "publisher": "Columbia Records",
    "ratingAlbum": "5",
    "composer": "Roger Waters, David Gilmour",
    "comment": "",
    "encoder": "LAME 3.100",

    // File properties
    "kind": "FLAC Audio",
    "format": "FLAC",
    "size": "45.2 MB",
    "channels": "2",
    "sampleRate": "44100",
    "bitrate": "1411",
    "duration": "6:22",

    // Statistics
    "dateModified": "2024-06-15 14:30:00",
    "dateAdded": "2020-01-10 09:15:00",
    "lastPlayed": "2025-01-26 20:45:00",
    "playCount": "42",
    "skipCount": "3"
  }
}

// Edit a tag
{
  "context": "nowplayingtagchange",
  "data": {
    "tag": "Genre",
    "value": "Art Rock"
  }
}

// Response (returns updated details)
{
  "context": "nowplayingdetails",
  "data": { /* updated track details */ }
}

// Request
{
  "context": "nowplayinglist",
  "data": {
    "offset": 0,
    "limit": 500
  }
}

// Response
{
  "context": "nowplayinglist",
  "data": {
    "playingIndex": 5,        // Current track (0-based)
    "total": 150,
    "data": [
      {
        "title": "Track Title",
        "artist": "Artist Name",
        "album": "Album Name",
        "path": "/path/to/file.mp3",
        "position": 1,           // 1-based position
        "duration": 240000
      }
    ]
  }
}

// Get all playlists
{"context": "playlistlist", "data": null}

// Response
{
  "context": "playlistlist",
  "data": [
    {
      "name": "My Playlist",
      "url": "MyPlaylist",
      "trackCount": 25
    }
  ]
}

// Play a playlist
{"context": "playlistplay", "data": "MyPlaylist"}

// Request
{
  "context": "browsegenres",
  "data": {"offset": 0, "limit": 100}
}

// Response item
{
  "genre": "Rock",
  "count": 250,
  "artistCount": 35
}

{
  "context": "browseartists",
  "data": {"offset": 0, "limit": 100}
}

// Response item
{
  "artist": "Artist Name",
  "albumCount": 5,
  "count": 45
}

{
  "context": "browsealbums",
  "data": {"offset": 0, "limit": 100}
}

// Response item
{
  "album": "Album Title",
  "artist": "Artist Name",
  "year": "2024",
  "count": 12
}

{
  "context": "browsetracks",
  "data": {"offset": 0, "limit": 100}
}

// Response item (base fields)
{
  "title": "Track Title",
  "artist": "Artist Name",
  "album": "Album Name",
  "genre": "Rock",
  "trackno": 5,
  "disc": 1,
  "src": "/path/to/file.mp3"
}

// Response item (v4.5+ extended metadata)
{
  "title": "Track Title",
  "artist": "Artist Name",
  "album": "Album Name",
  "genre": "Rock",
  "trackno": 5,
  "disc": 1,
  "src": "/path/to/file.mp3",
  // Extended fields (v4.5+)
  "year": "2024",
  "rating": "4",
  "bitrate": "320",
  "format": "MP3",
  "playcount": 42,
  "skipcount": 3,
  "lastplayed": "2025-12-20 14:30:00",
  "dateadded": "2024-06-15 09:00:00",
  "loved": "L"  // L=Loved, B=Banned, ""=Neither
}

// Artist Search Response
{
  "context": "librarysearchartist",
  "data": [
    {
      "artist": "Pink Floyd",
      "count": 75        // Number of tracks
    },
    {
      "artist": "Pink Martini",
      "count": 42
    }
  ]
}

// Album Search Response
{
  "context": "librarysearchalbum",
  "data": [
    {
      "album": "The Wall",
      "artist": "Pink Floyd",
      "count": 26         // Tracks on album
    },
    {
      "album": "The Dark Side of the Moon",
      "artist": "Pink Floyd",
      "count": 10
    }
  ]
}

// Get Albums for Specific Artist
{
  "context": "libraryartistalbums",
  "data": "Pink Floyd"  // Exact artist name
}

// Response
{
  "context": "libraryartistalbums",
  "data": [
    { "album": "The Wall", "artist": "Pink Floyd", "count": 26 },
    { "album": "Wish You Were Here", "artist": "Pink Floyd", "count": 5 }
  ]
}

// Step 1: Search for tracks by title
{
  "context": "librarysearchtitle",
  "data": {
    "query": "comfortably numb",
    "offset": 0,
    "limit": 50
  }
}

// Response: list of matching tracks with file paths (src field)
{
  "context": "librarysearchtitle",
  "data": {
    "total": 3,
    "data": [
      {
        "title": "Comfortably Numb",
        "artist": "Pink Floyd",
        "album": "The Wall",
        "src": "D:\\Music\\Pink Floyd\\The Wall\\Comfortably Numb.flac"
      }
    ]
  }
}

// Step 2a: Add track to END of Now Playing queue
{
  "context": "nowplayingqueuelast",
  "data": "D:\\Music\\Pink Floyd\\The Wall\\Comfortably Numb.flac"
}

// OR Step 2b: Add track as NEXT in queue (plays after current track)
{
  "context": "nowplayingqueuenext",
  "data": "D:\\Music\\Pink Floyd\\The Wall\\Comfortably Numb.flac"
}

// OR Step 2c: Play NOW (replaces queue and starts playback)
{
  "context": "libraryqueuetrack",
  "data": "D:\\Music\\Pink Floyd\\The Wall\\Comfortably Numb.flac"
}

// Set rating for a track
{
  "context": "librarysetrating",
  "data": {
    "path": "D:\\Music\\Pink Floyd\\The Wall\\Comfortably Numb.flac",
    "rating": "4.0"
  }
}

// Response (success)
{
  "context": "librarysetrating",
  "data": {
    "success": true,
    "path": "D:\\Music\\Pink Floyd\\The Wall\\Comfortably Numb.flac",
    "rating": 4.0
  }
}

// Love a track
{
  "context": "librarysetlove",
  "data": {
    "path": "D:\\Music\\Pink Floyd\\The Wall\\Comfortably Numb.flac",
    "status": "love"
  }
}

// Response (success)
{
  "context": "librarysetlove",
  "data": {
    "success": true,
    "path": "D:\\Music\\Pink Floyd\\The Wall\\Comfortably Numb.flac",
    "status": "love"
  }
}

// Request with pagination
{
  "context": "radiostations",
  "data": {
    "offset": 0,
    "limit": 100
  }
}

// Or simple request (returns all)
{"context": "radiostations", "data": null}

{
  "context": "radiostations",
  "data": {
    "offset": 0,
    "limit": 100,
    "total": 5,
    "data": [
      {
        "name": "BBC Radio 1",
        "url": "http://bbcmedia.ic.llnwd.net/stream/bbcmedia_radio1_mf_p"
      },
      {
        "name": "KEXP 90.3 FM",
        "url": "http://live-mp3-128.kexp.org/kexp128.mp3"
      }
    ]
  }
}

// Request album cover
{
  "context": "libraryalbumcover",
  "data": {
    "album": "The Wall",
    "artist": "Pink Floyd"
  }
}

// Response (Base64 JPEG)
{
  "context": "libraryalbumcover",
  "data": "/9j/4AAQSkZJRgABAQEASABIAAD/..."
}

// Request status
{"context": "librarycovercachebuildstatus", "data": null}

// Response (cache build in progress)
{"context": "librarycovercachebuildstatus", "data": true}

// Response (cache build complete or idle)
{"context": "librarycovercachebuildstatus", "data": false}

{
  "context": "playerinitiatoraction",
  "data": "sndKeys(^a);delay(100);sndKeys(^c)"
}

// Supported functions:
// sndKeys(keys)  - Send keyboard input (^ = Ctrl, + = Shift, % = Alt)
// delay(ms)      - Wait for specified milliseconds

// Navigate to Tab 1 (requires MusicBee hotkey configured for Ctrl+Alt+A)
{"context": "playerinitiatoraction", "data": "sndKeys(^%a)"}

// Focus MusicBee before sending keys (default behavior)
{"context": "playerinitiatoraction", "data": "sndKeys(!mb!CTRL ALT Q)"}

// Send keys to currently focused window (no focus change)
{"context": "playerinitiatoraction", "data": "sndKeys(!nofocus!^c)"}

// Request storage paths
{"context": "pluginstoragepath", "data": null}

// Response (ARiA enabled)
{
  "context": "pluginstoragepath",
  "data": {
    "musicBeePath": "C:\\Users\\user\\AppData\\Roaming\\MusicBee",
    "pluginPath": "C:\\Users\\user\\AppData\\Roaming\\MusicBee\\mb_remote",
    "itunesXml": "C:\\Users\\user\\Music\\iTunes Music Library.xml",
    "itunesXmlExists": true
  }
}

// Response (ARiA disabled)
{
  "context": "pluginstoragepath",
  "data": {
    "error": "Not Enabled",
    "message": "ARiA must be enabled to access storage paths"
  }
}

// Check current hotkey status (read-only)
{"context": "configureariahotkeys", "data": {"action": "check"}}

// Configure missing hotkeys (modifies MusicBee3Settings.ini)
{"context": "configureariahotkeys", "data": {"action": "configure"}}

// Response
{
  "context": "configureariahotkeys",
  "data": {
    "success": true,
    "configured": 11,
    "total": 11,
    "added": 2,
    "hotkeys": [
      {"name": "Tab1", "isConfigured": true, "hotkey": "Ctrl+Alt+A"},
      {"name": "Tab2", "isConfigured": true, "hotkey": "Ctrl+Alt+S"},
      // ... Tab3-Tab9 (D,F,G,H,J,K,L)
      {"name": "VisualiserToggle", "isConfigured": true, "hotkey": "Ctrl+Alt+V"},
      {"name": "VisualiserFullscreen", "isConfigured": true, "hotkey": "Ctrl+Alt+Z"}
    ],
    "settingsPath": "C:\\...\\MusicBee3Settings.ini",
    "backupPath": "C:\\...\\MusicBee3Settings.ini.backup_20251227_120000",
    "message": "Added 2 ARiA hotkeys. Restart MusicBee to apply."
  }
}

// Request
{"context": "playervisualizerlist", "data": null}

// Response (success)
{
  "context": "playervisualizerlist",
  "data": {
    "visualizers": ["Spectrum", "Milkdrop 2", "ProjectM"],
    "defaultVisualizer": "Milkdrop 2",
    "defaultState": "Normal",
    "currentState": "Off"
  }
}

// Response (experimental features disabled)
{
  "context": "playervisualizerlist",
  "data": {
    "error": "Not Enabled",
    "message": "Experimental features are disabled in plugin settings"
  }
}

// Show visualizer in normal window
{
  "context": "playervisualizer",
  "data": {
    "name": "Milkdrop 2",
    "state": "normal"
  }
}

// Show visualizer fullscreen
{
  "context": "playervisualizer",
  "data": {
    "name": "Milkdrop 2",
    "state": "fullscreen"
  }
}

// Turn off visualizer
{
  "context": "playervisualizer",
  "data": {
    "name": "",
    "state": "off"
  }
}

// Response (success)
{
  "context": "playervisualizer",
  "data": {
    "success": true,
    "message": "Visualizer 'Milkdrop 2' shown in fullscreen state"
  }
}

// Request
{"context": "podcastsubscriptions", "data": null}

// Response (success)
{
  "context": "podcastsubscriptions",
  "data": {
    "success": true,
    "error": null,
    "total": 3,
    "subscriptions": [
      {
        "id": "podcast_12345",
        "title": "My Favorite Podcast",
        "grouping": "Technology",
        "genre": "Podcast",
        "description": "Weekly tech discussions...",
        "downloadedCount": 5
      }
    ]
  }
}

// Response (error - requires MusicBee 3.1+)
{
  "context": "podcastsubscriptions",
  "data": {
    "success": false,
    "error": "Requires MusicBee 3.1+",
    "subscriptions": [],
    "total": 0
  }
}

// Request
{
  "context": "podcastepisodes",
  "data": {
    "id": "podcast_12345"
  }
}

// Response (success)
{
  "context": "podcastepisodes",
  "data": {
    "success": true,
    "error": null,
    "subscriptionId": "podcast_12345",
    "total": 25,
    "episodes": [
      {
        "id": "episode_001",
        "subscriptionId": "podcast_12345",
        "title": "Episode 101: Latest News",
        "dateTime": "2025-01-15 10:00:00",
        "description": "In this episode we discuss...",
        "duration": "01:15:30",
        "isDownloaded": true,
        "hasBeenPlayed": false,
        "url": "https://example.com/podcast/episode101.mp3"
      }
    ]
  }
}

// Request
{
  "context": "podcastplay",
  "data": {
    "id": "https://example.com/podcast/episode101.mp3"
  }
}

// Response
{
  "context": "podcastplay",
  "data": {
    "success": true,
    "message": "Playing episode",
    "url": "https://example.com/podcast/episode101.mp3"
  }
}

// Request
{"context": "playeroutput", "data": null}

// Response
{
  "context": "playeroutput",
  "data": {
    "devices": [
      {
        "name": "Speakers (Realtek Audio)",
        "active": true
      },
      {
        "name": "Headphones (USB Audio)",
        "active": false
      },
      {
        "name": "Digital Output (SPDIF)",
        "active": false
      }
    ]
  }
}

// Request (switch to device by name)
{
  "context": "playeroutputswitch",
  "data": "Headphones (USB Audio)"
}

// Response
{
  "context": "playeroutputswitch",
  "data": {
    "success": true
  }
}

// Subscribe to library events
{"context": "librarysubscribe", "data": null}

// Example: Rating changed notification (Plugin → Client)
{
  "context": "libraryratingchanged",
  "data": {
    "src": "C:\\Music\\track.mp3",
    "rating": "4"
  }
}

// Player state change (play/pause/stop, shuffle, repeat, scrobble)
{
  "context": "playerstate",
  "data": {
    "state": "playing",     // "playing", "paused", "stopped"
    "shuffle": false,
    "repeat": "none",       // "none", "all", "one"
    "scrobble": true,
    "mute": false,
    "volume": 75
  }
}

// Volume change (standalone event)
{
  "context": "playervolume",
  "data": 75
}

// Mute change (standalone event)
{
  "context": "playermute",
  "data": true
}

// Repeat mode change
{
  "context": "playerrepeat",
  "data": "all"
}

// Shuffle change
{
  "context": "playershuffle",
  "data": true
}

// Now playing track changed
{
  "context": "nowplayingtrack",
  "data": {
    "artist": "Pink Floyd",
    "album": "The Wall",
    "albumArtist": "Pink Floyd",
    "title": "Comfortably Numb",
    "year": "1979",
    "genre": "Progressive Rock",
    "path": "D:\\Music\\Pink Floyd\\The Wall\\Comfortably Numb.flac"
  }
}

// Cover art changed (Base64 JPEG)
{
  "context": "nowplayingcover",
  "data": "/9j/4AAQSkZJRgABAQEASABIAAD/..."
}

// Lyrics changed
{
  "context": "nowplayinglyrics",
  "data": {
    "status": 200,
    "lyrics": "Hello, is there anybody in there..."
  }
}

// Rating changed
{
  "context": "nowplayingrating",
  "data": "4.5"
}

// Love status changed
{
  "context": "nowplayinglfmrating",
  "data": "love"
}

// Position update
{
  "context": "nowplayingposition",
  "data": {
    "current": 125000,    // Current position in milliseconds
    "total": 382000       // Total duration in milliseconds
  }
}

// Now Playing list changed (tracks added, removed, or reordered)
{
  "context": "nowplayinglistchanged",
  "data": true
}

// Recommended client action: re-fetch the now playing list
{"context": "nowplayinglist", "data": {"offset": 0, "limit": 500}}

// Playlist created
{
  "context": "playlistcreated",
  "data": {
    "name": "New Playlist",
    "url": "NewPlaylist"
  }
}

// Playlist updated
{
  "context": "playlistupdated",
  "data": {
    "name": "Updated Playlist",
    "url": "UpdatedPlaylist"
  }
}

// Playlist deleted
{
  "context": "playlistdeleted",
  "data": {
    "name": "Deleted Playlist",
    "url": "DeletedPlaylist"
  }
}

// Tag/metadata changed
{
  "context": "librarytagchanged",
  "data": {
    "path": "D:\\Music\\track.mp3",
    "eventType": "tagchanged",
    "artist": "Artist Name",
    "title": "Track Title",
    // ... full metadata if includeMetadata=true
  }
}

// File added to library
{
  "context": "libraryfileadded",
  "data": {
    "path": "D:\\Music\\new_track.mp3",
    "eventType": "fileadded"
  }
}

// File removed from library
{
  "context": "libraryfiledeleted",
  "data": {
    "path": "D:\\Music\\removed_track.mp3",
    "eventType": "filedeleted"
  }
}

// Rating changed in library
{
  "context": "libraryratingchanged",
  "data": {
    "path": "D:\\Music\\track.mp3",
    "eventType": "ratingchanged",
    "rating": "4"
  }
}

// Play count changed
{
  "context": "libraryplaycountchanged",
  "data": {
    "path": "D:\\Music\\track.mp3",
    "eventType": "playcountchanged",
    "playCount": 43
  }
}

// C# example
public class SocketMessage
{
    [JsonProperty("context")]
    public string Context { get; set; }

    [JsonProperty("data")]
    public object? Data { get; set; }

    public string ToJson() => JsonConvert.SerializeObject(this);

    public static SocketMessage FromJson(string json)
        => JsonConvert.DeserializeObject<SocketMessage>(json);
}

// The same field may appear as any of these:
albumArtist | album_artist | AlbumArtist
playCount   | play_count   | PlayCount
trackNo     | track_no     | track

// Defensive parsing example:
var artist = item["artist"] ?? item["Artist"];
var trackNo = item["trackNo"] ?? item["track_no"] ?? item["track"];

Connection Quality Thresholds:
  Excellent: RTT < 50ms,  Loss < 1%
  Good:      RTT < 150ms, Loss < 5%
  Fair:      RTT < 300ms, Loss < 10%
  Poor:      RTT > 300ms or Loss > 10%

Attempt 1:  1 second
Attempt 2:  2 seconds
Attempt 3:  4 seconds
Attempt 4:  8 seconds
Attempt 5:  16 seconds
Attempt 6+: 30 seconds (maximum)

Maximum attempts: 10

{
  "context": "error",
  "data": "Error description message"
}

// Success
{"context": "librarysetrating", "data": {"success": true}}

// Failure
{"context": "librarysetrating", "data": {"success": false, "error": "Track not found"}}

Allowed IPs: ["192.168.1.50", "192.168.1.51", "192.168.1.100"]

Connection from 192.168.1.50 → Allowed
Connection from 192.168.1.99 → Rejected

Base IP: 192.168.1.10
Last Octet Max: 50

Connection from 192.168.1.25 → Allowed (25 is between 10 and 50)
Connection from 192.168.1.5  → Rejected (5 < 10)
Connection from 192.168.1.75 → Rejected (75 > 50)
Connection from 192.168.2.25 → Rejected (different subnet)

// Rejection message (received immediately after connect, before handshake)
{"context": "notallowed", "data": ""}

// Client handling pseudocode
on_message_received(msg):
    if msg.context == "notallowed":
        show_error("Connection rejected - your IP is not allowed")
        disconnect()
        // Do NOT attempt automatic reconnection
        // This requires user/admin action to resolve

using System.Net.Sockets;
using System.Text;
using Newtonsoft.Json;

public class MbrcClient
{
    private TcpClient _client;
    private StreamWriter _writer;
    private StreamReader _reader;

    public async Task ConnectAsync(string host, int port = 5900)
    {
        _client = new TcpClient { NoDelay = true };
        await _client.ConnectAsync(host, port);

        var stream = _client.GetStream();
        var utf8NoBom = new UTF8Encoding(false);
        _writer = new StreamWriter(stream, utf8NoBom) { NewLine = "\r\n", AutoFlush = true };
        _reader = new StreamReader(stream, utf8NoBom);

        // Handshake
        await SendAsync("player", "android");
        await SendAsync("protocol", new { protocol_version = 4, no_broadcast = false });
        await SendAsync("init", null);

        // Start receive loop
        _ = Task.Run(ReceiveLoop);
    }

    public async Task SendAsync(string context, object data)
    {
        var msg = JsonConvert.SerializeObject(new { context, data });
        await _writer.WriteLineAsync(msg);
    }

    private async Task ReceiveLoop()
    {
        while (_client.Connected)
        {
            var line = await _reader.ReadLineAsync();
            if (line != null)
            {
                ProcessMessage(line);
            }
        }
    }

    private void ProcessMessage(string json)
    {
        var msg = JsonConvert.DeserializeObject<dynamic>(json);
        string context = msg.context;

        switch (context)
        {
            case "nowplayingtrack":
                Console.WriteLine($"Now Playing: {msg.data.artist} - {msg.data.title}");
                break;
            case "pong":
                // Heartbeat response
                break;
            // Handle other messages...
        }
    }
}

import socket
import json
import threading

class MbrcClient:
    def __init__(self, host, port=5900):
        self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
        self.sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
        self.sock.connect((host, port))

    def send(self, context, data=None):
        msg = json.dumps({"context": context, "data": data})
        self.sock.sendall((msg + "\r\n").encode('utf-8'))

    def handshake(self):
        self.send("player", "android")
        self.send("protocol", {"protocol_version": 4, "no_broadcast": False})
        self.send("init")

    def receive_loop(self):
        buffer = ""
        while True:
            data = self.sock.recv(4096).decode('utf-8')
            buffer += data
            while "\r\n" in buffer:
                line, buffer = buffer.split("\r\n", 1)
                msg = json.loads(line)
                self.handle_message(msg)

    def handle_message(self, msg):
        context = msg.get("context")
        data = msg.get("data")

        if context == "nowplayingtrack":
            print(f"Now Playing: {data['artist']} - {data['title']}")
        elif context == "pong":
            pass  # Heartbeat

# Usage
client = MbrcClient("192.168.1.100")
client.handshake()
threading.Thread(target=client.receive_loop, daemon=True).start()
client.send("playerplaypause")

{
  "context": "librarysubscribe",
  "data": {
    "eventTypes": ["tagchanged", "fileadded", "filedeleted", "ratingchanged", "playcountchanged"],
    "includeMetadata": true
  }
}

{
  "context": "librarysubscribe",
  "data": {
    "success": true,
    "subscribedTo": ["tagchanged", "fileadded", "filedeleted", "ratingchanged", "playcountchanged"],
    "includeMetadata": true
  }
}

{
  "context": "librarytagchanged",  // or libraryfileadded, libraryratingchanged, etc.
  "data": {
    "path": "D:\\Music\\Artist\\Album\\Track.mp3",
    "eventType": "tagchanged",
    "artist": "Artist Name",
    "album": "Album Name",
    "albumArtist": "Album Artist",
    "title": "Track Title",
    "genre": "Rock",
    "year": "2024",
    "rating": "4.0",
    "trackNo": "5",
    "discNo": "1",
    "loved": "L",  // "L" = Loved, "" = Not loved
    "additional": null
  }
}

{
  "context": "librarytagchanged",
  "data": {
    "path": "D:\\Music\\Artist\\Album\\Track.mp3",
    "eventType": "tagchanged",
    "additional": null
  }
}

=== MBRC PROTOCOL COMPATIBILITY TEST REPORT ===
Plugin Version:   1.5.25.1226
Negotiated Protocol: 4.5 (client requested 4.5)

Results: 10/10 passed, 0 failed

ADDITIVE FIELDS (v1.5.x):
  - AlbumCount (browseartists) - always sent
  - ArtistCount (browsegenres) - always sent
  - year, rating, bitrate, format, playcount, skipcount, lastplayed, dateadded, loved (browsetracks) - v4.5 only

Backward Compatibility: OK (protocol negotiation active)

# Connect to MusicBee Remote plugin
$client = New-Object System.Net.Sockets.TcpClient("localhost", 3000)
$stream = $client.GetStream()
$writer = New-Object System.IO.StreamWriter($stream)
$reader = New-Object System.IO.StreamReader($stream)
$writer.AutoFlush = $true

# Handshake
$writer.WriteLine('{"context":"player","data":"android"}')
Start-Sleep -Milliseconds 100
$writer.WriteLine('{"context":"protocol","data":{"protocol_version":4}}')
Start-Sleep -Milliseconds 100

# Read protocol response
$response = $reader.ReadLine()
Write-Host "Protocol response: $response"

# Test browse artists
$writer.WriteLine('{"context":"browseartists","data":{"offset":0,"limit":5}}')
Start-Sleep -Milliseconds 500
$response = $reader.ReadLine()
Write-Host "Artists response: $($response.Substring(0, [Math]::Min(500, $response.Length)))..."

# Cleanup
$client.Close()

# Connect and send handshake
(echo '{"context":"player","data":"android"}'; \
 echo '{"context":"protocol","data":{"protocol_version":4}}'; \
 echo '{"context":"browseartists","data":{"offset":0,"limit":5}}'; \
 sleep 2) | nc localhost 3000

{
  "artist": "Pink Floyd",
  "album": "The Wall",
  "album_artist": "Pink Floyd",
  "title": "Comfortably Numb",
  "path": "D:\\Music\\Pink Floyd\\The Wall\\06 - Comfortably Numb.flac",
  "position": 5
}

{
  "context": "browseartists",
  "data": {
    "data": [/* array of items */],
    "offset": 0,       // Starting position
    "limit": 100,      // Items per page
    "total": 1500      // Total items available
  }
}

{
  "artist": "Pink Floyd",
  "AlbumCount": 15     // v1.5.x additive field
}

{
  "album": "The Wall",
  "artist": "Pink Floyd"
}

{
  "genre": "Progressive Rock",
  "ArtistCount": 42    // v1.5.x additive field
}

{
  "name": "My Favorites",
  "url": "MyFavorites"
}

{
  "name": "BBC Radio 1",
  "url": "http://stream.bbc.co.uk/radio1"
}

// Decoding cover art (C#)
byte[] imageBytes = Convert.FromBase64String(coverData);
using var ms = new MemoryStream(imageBytes);
var image = Image.FromStream(ms);

// Decoding cover art (JavaScript)
const img = new Image();
img.src = 'data:image/jpeg;base64,' + coverData;