# MBXHub API

> MusicBee REST API - v0.5.3.1
>
> llms.txt specification: https://llmstxt.org/
> Requires MusicBee 3.1+ (API rev 53). Supports up to API rev 58 (MusicBee 3.6+ APIs available when present).

## Endpoints

- Base URL: `http://localhost:8080`
- WebSocket: `ws://localhost:8080/ws`
- API Docs: `http://localhost:8080/docs`

## Player Control

- `POST /player/play` - Start playback
- `POST /player/pause` - Pause playback
- `POST /player/playpause` - Toggle play/pause (alias: `/player/play-pause`)
- `POST /player/stop` - Stop playback
- `POST /player/next` - Next track
- `POST /player/previous` - Previous track
- `GET /player/volume` - Get volume (0-100)
- `PUT /player/volume` - Set volume (body: {"volume":50})
- `GET /player/shuffle` - Get shuffle state
- `PUT /player/shuffle` - Set shuffle (body: {"shuffle":true/false})
- `GET /player/autodj` - AutoDJ state
- `POST /player/autodj/start` - Start AutoDJ
- `POST /player/autodj/stop` - Stop AutoDJ
- `GET /player/repeat` - Get repeat mode
- `PUT /player/repeat` - Set repeat (off/all/one)
- `GET /player/status` - Full player state
- `GET /player/mute` - Mute state
- `PUT /player/mute` - Set mute (body: {"mute":true})
- `GET /player/position` - Playback position in ms
- `PUT /player/position` - Seek (body: {"position":ms})
- `POST /player/next-album` - Skip to next album
- `POST /player/previous-album` - Skip to previous album
- `POST /player/queue-random` - Queue a random track (alias: `/player/queuerandom`)

### Audio Processing
- `GET /player/equaliser` - Get equalizer state (also `/player/equalizer`)
- `PUT /player/equaliser` - Set equalizer
- `GET /player/dsp` - Get DSP enabled state
- `PUT /player/dsp` - Set DSP enabled
- `GET /player/crossfade` - Get crossfade state
- `PUT /player/crossfade` - Set crossfade
- `GET /player/replaygain` - Get replay gain mode
- `PUT /player/replaygain` - Set replay gain mode
- `GET /player/scrobble` - Get scrobble (Last.fm) state
- `PUT /player/scrobble` - Set scrobble

### Display Settings
- `GET /player/stopaftercurrent` - Get stop-after-current state
- `POST /player/stopaftercurrent` - Toggle stop-after-current
- `GET /player/show-time-remaining` - Show time remaining preference
- `GET /player/show-rating-track` - Show rating on track preference
- `GET /player/show-rating-love` - Show love rating preference
- `POST /player/show-equaliser` - Open the equaliser window in MusicBee (also `/player/show-equalizer`)
- `GET /player/button-enabled?button=N` - Check if a UI button is enabled
- `GET /player/output-devices` - List audio output devices
- `PUT|POST /player/output-device` - Switch output device (body: {"device":"name"})

## Device & Mixer Control

### Windows Audio Device
- `GET /devices/audio/outputs` - List all active Windows audio render devices (name, id, isDefault)
- `GET /devices/audio/volume` - Windows audio device volume and mute state
- `PUT /devices/audio/volume` - Set Windows audio device volume (body: {"volume":50})
- `PUT /devices/audio/mute` - Set Windows audio device mute (body: {"mute":true})

### Network Endpoints
- `GET /devices/endpoints` - List configured network endpoints
- `POST /devices/endpoints` - Add a network endpoint (body: {"ip":"192.168.1.50","type":"devialet","name":"Living Room"})
- `POST /devices/endpoints/scan` - mDNS scan for LAN speakers; bodyless (Content-Length: 0); ~4s blocking; returns [{name, ip, port, hostName, serviceType, alreadyConfigured, existingId}]
- `DELETE /devices/endpoint/{id}` - Remove a saved endpoint
- `GET /devices/endpoint/{id}/volume` - Get endpoint volume and mute state
- `PUT /devices/endpoint/{id}/volume` - Set endpoint volume (body: {"volume":50})
- `PUT /devices/endpoint/{id}/mute` - Set endpoint mute (body: {"mute":true})
- `GET /devices/endpoint/{id}/sources` - List endpoint input sources
- `PUT /devices/endpoint/{id}/source` - Select endpoint input source (body: {"sourceId":"upnp"})

### Mixer Settings
- `GET /mixer/settings` - Get mixer settings (default fader)
- `PUT /mixer/settings` - Set mixer settings (body: {"defaultFader":"device"})
- `GET /mixer/volume` - Get volume from default fader (player or device)
- `PUT /mixer/volume` - Set volume on default fader (body: {"volume":50})

### Streaming
- `POST /player/update-play-statistics` - Update play count and statistics

## Now Playing

- `GET /nowplaying` - Current track metadata
- `GET /nowplaying/artwork` - Album art (binary image)
- `GET /nowplaying/lyrics` - Track lyrics. Response: `{ hasLyrics, lyrics, source?, label? }`. `source` is `"lyrics"` (MusicBee field) or `"comment"` (fallback to track Comment tag when no real lyrics exist). When `source: "comment"`, `label` is the chip text shown above the body (default "from comment"). Truncated to `LyricsFallback.MaxDisplayChars` (default 4000). Configurable via `LyricsFallback.{Enabled, MaxDisplayChars, Label}`; hard-killable via `ApiDisableLyricsFallback`.
- `GET /nowplaying/position` - Playback position in ms
- `GET /nowplaying/property?type=X` - File property (Size, Bitrate, DateAdded, etc.)
- `GET /nowplaying/tag?field=X` - File tag (Artist, Album, Genre, Rating, etc.)
- `GET /nowplaying/artwork-url` - Artwork as data URL (base64)
- `GET /nowplaying/downloaded-artwork` - Downloaded artwork (binary)
- `GET /nowplaying/downloaded-artwork-url` - Downloaded artwork as data URL
- `GET /nowplaying/downloaded-lyrics` - Downloaded lyrics from provider
- `GET /nowplaying/artist-picture` - Artist picture (binary, ?fadingPercent=0)
- `GET /nowplaying/artist-thumbnail` - Artist thumbnail (smaller)
- `GET /nowplaying/artist-picture-urls` - Artist picture URLs (?localOnly=false). Response includes a `pictures` array with `src` URLs (serveable via `/nowplaying/artist-pictures/{index}`) in addition to raw file paths.
- `GET /nowplaying/artist-pictures/{index}` - Serve current artist's Nth picture as binary image (0-based). Query: ?localOnly=true
- `GET /nowplaying/is-soundtrack` - Whether current track is a soundtrack
- `GET /nowplaying/soundtrack-pictures` - Soundtrack picture URLs
- `GET /nowplaying/spectrum` - Real-time spectrum data (frequency analysis)
- `GET /nowplaying/sound-graph` - Waveform graph data
- `GET /nowplaying/sound-graph-ex` - Extended waveform graph data
- `GET /nowplaying/peak` - Current stereo peak and RMS levels (0.0-1.0). Returns {peak: [L, R], rms: [L, R]}. Requires MusicBee 3.6+ (API rev 58+)

## Queue

- `GET /queue` - List queue (?offset=0&limit=50)
- `GET /queue/current` - Current track index
- `POST /queue/add` - Add tracks (body: {"url":"path","position":"next|last"} or batch: {"urls":["path1","path2"],"position":"last"})
- `POST /queue/playnow` - Play track immediately (body: {"url":"path","cueTrack":3})
- `POST /queue/clear` - Clear queue
- `POST /queue/move` - Reorder (body: {"from":0,"to":5})
- `DELETE /queue/{index}` - Remove track by index
- `POST /queue/play` - Play track at index (body: {"index":3,"cueTrack":1})
- `GET /queue/next-index?offset=1` - Get index N tracks ahead/behind
- `GET /queue/has-prior` - Whether queue has prior tracks
- `GET /queue/has-following` - Whether queue has following tracks
- `POST /queue/play-library-shuffled` - Clear queue and play library shuffled
- `GET /queue/{index}/url` - Get file URL for track at index
- `GET /queue/{index}/tag?field=X` - Get tag for track at index
- `GET /queue/{index}/property?type=X` - Get property for track at index

### Virtual Tracks (CUE)
Virtual Tracks share the same audio file URL. The queue response includes Virtual Track metadata:
- `cueTrack` - Track number when detected
- `cueStartMs` - Start offset in milliseconds within the physical file
- Track titles from CUE sheet (not embedded audio metadata)
- Include `cueTrack` in add/playnow to preserve track identity

### CUE Track Resolution
MBXHub detects CUE-backed audio files and resolves per-track metadata automatically across all surfaces:
- `GET /player/status` - Returns CUE track title, artist, trackNo, cueTrack field
- `GET /nowplaying/position` - Includes `cueTrack` and `cueTitle` when active
- `GET /nowplaying/tag?field=TrackTitle` - Returns CUE track title (not base file)
- WebSocket `TrackChanged` events include `cueTrack` and `cueStartMs` fields when CUE active
- Dashboard shows resolved CUE track metadata
- Listen Here streaming: seeks to `cueStartMs`, shows track-relative progress, auto-advances at track end

CUE parsing uses a built-in regex parser with encoding detection (BOM, UTF-8 validation, Windows-1252 fallback). No external CUE library is loaded or required.

## Library

- `GET /library/files` - Query files (?query=&artist=&albumArtist=&album=&genre=&offset=&limit=&sort=)
- `GET /library/artists` - List artists (?offset=&limit=&sort=)
- `GET /library/albums` - List albums (?artist=&offset=&limit=&sort=)
- `GET /library/albums/detailed` - Albums with firstTrackUrl, year, dateAdded for artwork lookups and sorting (?offset=&limit=) — eliminates per-album /library/files round-trips
- `GET /library/album-artists` - List album artists (?offset=&limit=)
- `GET /library/albums/by-artist` - Albums for an artist (?albumArtist= or ?artist=, &sort=alpha|year|year-asc). ?artist= queries ArtistPeople (broader), ?albumArtist= queries AlbumArtist (exact credit)
- `GET /library/albums/unheard` - Albums where all tracks have playCount=0 (?offset=&limit=)
- `GET /library/albums/with-pdf` - Albums that contain PDF booklets (?offset=&limit=)
- `GET /library/genres` - List genres (?sort=)
- `GET /library/inbox` - Files in MusicBee Inbox (Source Type 4). Progressive: browse tab hidden if empty
- `GET /library/audiobooks` - Audiobook files (Source Type 32). Progressive: browse tab hidden if empty
- `GET /library/videos` - Video files (Source Type 64). Progressive: browse tab hidden if empty
- `GET /library/search?q=term` - Full-text search over title/artist/album/genre. Two modes: **strict** (default) requires the typed phrase to appear as a contiguous run of whole words in a single field — "st anger" matches the album "St. Anger" (and from v0.5.3.0 also matches mid-typing partials like "st an") but NOT "Stranger" or "Strange Anger"; **substring** is loose — any query word appearing as a substring passes ("anger" matches "Stranger"). Default mode from `Library.DisableStrictSearch` setting (false=strict, shipped default). Override per-call with `?substring=true|false`. Diacritic and punctuation normalized. Response includes `mode: "strict"|"substring"`. Also supports `?sort=`. **v0.5.3.0:** add `?dsl=true` to route the query through `SearchDslParser` (qualifier syntax — `artist:`, `album:`, `genre:`, `year:`, `rating:`, `fmt:`, range / boolean / grouping); cheat sheet at `GET /library/search/syntax`. **v0.5.3.0 backstop:** queries shorter than `search.live.minQueryLength` (default 2) return `400 QUERY_TOO_SHORT` with `{error: "Query must be at least N characters (got M)."}` — single-char walks stall every other MB-API consumer for the duration of the cursor lock, so this protects fleet-wide responsiveness from runaway non-conforming clients (curl, scripts).
- `GET /library/search/syntax` - **v0.5.3.0.** Returns the DSL grammar as JSON (qualifiers, operators, worked examples). Response shape: `{version, qualifiers:[{name, type, allowsRange, allowsOperators, mapping, enumValues}], operators:[{symbol, description}], examples:[{query, description}]}`. Authoritative source — the reference below is derived from the same data. Used by Cmd+K's cheatsheet and any other client surfacing DSL syntax to users.

#### Query DSL Reference

The DSL layers on top of free-text: every plain word still matches normally, qualifiers narrow the result, operators compose. Auto-detected on `/library/search` and `/search` when `library.search.dsl.enabled = true` (default); force per-call with `?dsl=true`.

**Qualifiers** (19 total):

| Qualifier | Type | Range/Ops | Maps to | Notes |
|---|---|---|---|---|
| `artist:` | string | — | ArtistPeople | Includes featured / album artists |
| `album:` | string | — | Album | |
| `albumartist:` | string | — | AlbumArtist | Compilation-aware |
| `genre:` | string | — | Genre | Multi-value tags split client-side |
| `year:` | int | range + ops | Year | `year:1985`, `year:1985..1990`, `year:>=2000` |
| `decade:` | enum | — | derived from Year | Values: `60s`, `70s`, `80s`, `90s`, `00s`, `10s`, `20s` |
| `rating:` | int | range + ops | Rating (0–5) | `rating:>=4`, `rating:3..5` |
| `loved:` | bool | — | Loved tag | `loved:true` / `loved:false` |
| `bpm:` | int | range + ops | Tempo (Truedat/Essentia) | Requires fingerprint or mood-cache data |
| `mood:` | string | — | AutoQ mood channel | Channel name (e.g. `mood:chill`). **Post-filter** |
| `vibe:` | float | range + ops | AutoQ vibe score | 0–1. `vibe:>=0.7` |
| `source:` | enum | — | MB Source Type | Values: `library`, `inbox`, `audiobooks`, `videos`, `podcasts`. Default from `library.search.dsl.defaultSource` |
| `playlist:` | string | — | playlist filter | **Post-process** — intersects with named playlist membership |
| `added:` | date | range + ops | DateAdded | ISO (`2025-01-01`), relative (`now-7d`), or named alias |
| `played:` | date | range + ops | DateLastPlayed | Same date format as `added:` |
| `playcount:` | int | range + ops | PlayCount | `playcount:>10`, `playcount:0` (never played) |
| `duration:` | int (seconds) | range + ops | Duration | `duration:>3600` (over an hour) |
| `path:` | string | — | FilePath substring | Case-insensitive substring match on full path |
| `lyric:` | string | — | lyrics body | **Post-process**, expensive. Gated on `library.search.dsl.allowLyricSearch = true` (default off) |

**Operators**:

| Symbol | Meaning | Where it applies |
|---|---|---|
| `>` | greater than | Qualifiers with `allowsOperators` |
| `>=` | greater than or equal | Same |
| `<` | less than | Same |
| `<=` | less than or equal | Same |
| `..` | inclusive range (low..high) | Qualifiers with `allowsRange` |
| `-` (prefix) | exclude | Free-text term or qualifier (e.g. `-genre:metal`, `-live`) |
| `OR` / `or` | boolean OR | Between sibling expressions. Default between terms is AND |
| `( ... )` | grouping | Forces precedence inside a larger expression |

**Examples**:

| Query | Result |
|---|---|
| `artist:radiohead` | Tracks by Radiohead |
| `year:1985..1990` | Tracks released between 1985 and 1990 inclusive |
| `year:1965 rating:>4` | 1965 tracks rated above 4 — two range/op qualifiers (implicit AND) |
| `mood:chill rating:>=4` | Chill-mood tracks rated 4 or higher — mood is post-filter |
| `rock -genre:metal` | Rock tracks excluding metal — free-text plus exclusion |
| `(rock or metal) -live` | Rock or metal, but not live recordings |
| `source:audiobooks duration:>3600` | Audiobooks longer than one hour |
| `played:<now-30d playcount:>5` | Favorites you haven't played in the last 30 days |
| `decade:80s -genre:disco` | 80s, no disco — decade enum plus genre exclusion |

**Composition rules**:

- Default between terms is AND. Use `OR` (or lowercase `or`) for disjunction; parentheses for grouping.
- Free-text terms work alongside qualifiers — `radiohead year:>=2000` filters Radiohead from 2000 onward.
- Post-filter qualifiers (`mood`, `playlist`, `lyric`) run after candidate selection, capped by `library.search.dsl.maxPostFilterCandidates` (default 5000).
- Unknown qualifiers return `422 INVALID_DSL` with parse position and Levenshtein-based "did you mean" suggestions.
- Date format: ISO (`2025-01-01`), relative (`now-7d`, `now-30d`), or named alias from `library.search.dsl.dateAliases` (defaults: `lastweek`, `lastmonth`, `thisyear`).
- `GET /search?q=&buckets=&limit=&cursor=` - **v0.5.3.0 federated search.** Runs typed buckets (tracks / albums / artists / playlists / saved) in parallel and returns a unified response with cursor pagination on the tracks bucket, facet counts, and a top-hit. Cursors are HMAC-stamped + TTL-checked (stale → 410, malformed → 400, query-mismatch → 400). Backs the Cmd+K palette and (v0.5.3.0+) the dashboard search bar, player.html, browse.html, and explore.html. **DSL routing (v0.5.3.0 post-launch):** auto-detects DSL queries the same way `/library/search` does (qualifier colons, `..` ranges, `>`/`<`, ` OR `, leading `-`). When detected and `Search.Dsl.Enabled=true` (default), routes through DSL pipeline and response carries `mode: "dsl"`. Per-call `?dsl=true` explicit override still works. Plain free-text queries continue to use strict/substring mode. **Tracks bucket relevance-sorted** by match strength (title > album > artist, with prefix-match bonus) regardless of mode. **v0.5.3.0 backstop:** same `search.live.minQueryLength` (default 2) check as `/library/search` — short queries return `400 QUERY_TOO_SHORT`. **v0.5.3.0 cap bump:** per-bucket `?limit=` raised from 200 to 500 so browse.html's client-side aggregation gets the full intended slice.
- `GET /system/search-index` - **v0.5.3.0.** Live engine + index state snapshot. Currently reports `engine:"mb"` (FTS5 substrate dropped during the post-decouple harvest; seam preserved for future engines).
- `GET /library/file/{url}` - Get file metadata
- `PUT /library/file/{url}` - Update tags (body: {"Artist":"name","Title":"name"})
- `GET /library/files/raw` - Raw file path list (no metadata, faster)
- `GET /library/cuetest?query=` - Test CUE track resolution for a query
- `POST /library/add` - Add file to library (body: {"url":"path"})
- `POST /library/artwork/batch` - Batch artwork fetch (body: {"urls":["path1","path2",...]}, max 50). Returns base64 data URIs keyed by URL, null for missing artwork
- `POST /library/find-device-ids` - Find device persistent IDs (body: {"urls":[...]})
- `POST /library/sync-delta` - Get sync delta (body: {"deviceId":"...","since":"ISO date"})
- `POST /library/commit` - Commit pending tag changes to file (body: {"file":"path"}). Use after batching Library_SetFileTag RPC calls
- `GET /library/evaluate?expression=<expr>&fileUrl=<url>` - Evaluate MusicBee expression (template syntax: <Artist>, $If(), virtual tags). fileUrl optional, defaults to now-playing. Requires MusicBee 3.4.1+ (API rev 55+)
- `GET /library/no-artwork` - MusicBee's placeholder image for tracks with no artwork (binary). Cache-Control: 24h. Requires MusicBee 3.5+ (API rev 57+)
- `GET /library/file/{url}/lyrics` - Lyrics for specific file
- `GET /library/file/{url}/artwork` - Artwork for specific file (binary)
- `GET /library/file/{url}/artwork-url` - Artwork as data URL for specific file
- `GET /library/file/{url}/artwork-count` - Returns `0` (no artwork) or `1` (artwork present). Probes up to 20 embedded-artwork LOCATIONS and picks the largest byte-size as the canonical image; `/artwork?index=0` then serves that variant. Cached per fileUrl.
- `GET /library/file/{url}/pdf` - PDF booklet from track's album folder (binary, application/pdf)
- `GET /library/file/{url}/fan-art` - List all images in the track's album folder and one level of subfolders. Returns {folder, images:[], count}. Excludes: canonical primary-cover filenames (folder/cover/front/album × .jpg/.jpeg/.png) — duplicates of the primary artwork served by `/artwork`; ALL Windows Media Player cache files (AlbumArtSmall*, AlbumArt_*); thumbnails (<5KB); Thumbs.db; desktop.ini. Security: track must be in MusicBee library.
- `GET /library/fan-art/{path}` - Serve a single fan art image by absolute path (binary). Security: image must be in a directory containing a MusicBee library file. Cache-Control: 1 hour.
- `GET /library/file/{url}/has-pdf` - Check if PDF booklet exists (returns {hasPdf: bool, url: string})
- `GET /library/file/{url}/device-id` - Device persistent ID
- `PUT /library/file/{url}/device-id` - Set device persistent ID
- `GET /library/artist/{name}/similar` - Similar artists (?limit=10)
- `GET /library/artist/{name}/picture` - Artist picture (binary)
- `GET /library/artist/{name}/thumbnail` - Artist thumbnail (smaller)
- `GET /library/artist/{name}/pictures` - Artist picture URLs (?localOnly=false). Response includes a `pictures` array with `src` URLs (serveable via `/library/artist/{name}/pictures/{index}`) in addition to raw file paths.
- `GET /library/artist/{name}/pictures/{index}` - Serve artist picture by index as binary image (0-based, from /pictures list). Query: ?localOnly=true
- `GET /library/recent` - Recently played tracks sorted by last played descending (?limit=50&offset=0&days=30)
- `GET /library/videos` - Video files from MusicBee's Video library node. Returns `{total, videos: [{url, title, artist, album, kind, duration}]}`. Title falls back to filename when tag is empty. Uses Source Type 64 query

## Saved Search & History (v0.5.3.0)

### Saved searches
Persisted query under a name, evaluated on a schedule. Backed by `mbxhub-search.json` next to `mbxhub.json`. Enabled by default; toggle via `library.search.savedSearch.enabled`. Disabled endpoints return 404 NOT_FOUND. **All write/mutation routes return 403 FORBIDDEN when `ApiReadOnlyMode` is set.**

- `GET /search/saved` - List all saved searches `{searches:[...], total}`
- `POST /search/saved` - Create. Body `{name, query, delivery?, schedule?, mbPlaylist?}`. Server generates id. 422 INVALID_DSL on parse error (with parse position); 409 on duplicate name (case-insensitive, per host); 422 INVALID_NAME if name missing or > 80 chars
- `GET /search/saved/{id}` - Fetch one
- `PUT /search/saved/{id}` - Update name / query / delivery / schedule / mbPlaylist
- `DELETE /search/saved/{id}` - 204 on success, 404 if unknown
- `GET /search/saved/{id}/results` - Evaluate now; returns Track B response shape (matched URLs + count)
- `POST /search/saved/{id}/run` - Force re-evaluation; returns diff vs `LastMatchUrls`. Drives the `SearchMatched` WS broadcast (D2)

### Search history
Server-side recent-search log shared by Cmd+K and any other search bar. Falls through to client localStorage if 404. Mutations gated on `ApiReadOnlyMode`.

- `GET /search/history?limit=N` - Newest-first. `limit` defaults 20, caps at 200
- `POST /search/history` - Body `{query, source}`. Empty body clears (returns `{cleared:true}`)
- `DELETE /search/history` - Wipe all entries

## Radio

- `GET /radio/stations` - List radio stations (returns `{total, stations: [{url, name}]}`)

## Playlists

- `GET /playlists` - List all playlists
- `POST /playlists` - Create playlist (body: {"name":"My Playlist","files":["path1","path2"]})
- `GET /playlists/{url}/files` - Get playlist tracks
- `POST /playlists/{url}/files` - Add tracks (body: {"urls":["path1","path2"]})
- `POST /playlists/{url}/play` - Play playlist
- `GET /playlists/{url}` - Get playlist details
- `PUT /playlists/{url}` - Update playlist name
- `DELETE /playlists/{url}` - Delete playlist

## WebSocket

Connect to `ws://localhost:8080/ws` for real-time events:

```javascript
const ws = new WebSocket('ws://localhost:8080/ws');
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  // msg.event: TrackChanged, PlayStateChanged, VolumeChanged, etc.
  // msg.data: event-specific payload
  // msg.timestamp: ISO 8601 timestamp
};
// Subscribe to specific events:
ws.send(JSON.stringify({ subscribe: ['TrackChanged', 'PlayStateChanged'] }));
```

Event types:
- `TrackChanged` - {"fileUrl":"...","title":"...","artist":"...","album":"...","duration":ms,"artworkUrl":"/nowplaying/artwork","cueTrack":N,"cueStartMs":ms}  (cueTrack + cueStartMs present only when CUE active)
- `PlayStateChanged` - {"state":"playing|paused|stopped"}
- `PositionChanged` - {"position":ms,"duration":ms}
- `VolumeChanged` - {"volume":0-100,"muted":bool}
- `ShuffleChanged` - {"enabled":bool}
- `RepeatChanged` - {"mode":"none|all|one"}
- `QueueChanged` - {"action":"changed","index":-1,"totalTracks":-1}
- `MetadataChanged` - {"fileUrl":"...","rating":-1 to 5,"love":"L|B|"}
- `Reaction` - {"emoji":"fire","type":"fire","nickname":"Guest","trackTitle":"...","trackArtist":"..."}
- `TasteChanged` - {"topGenres":[...],"topArtists":[...],"bpmRange":[lo,hi],"mood":"...","moodConfidence":0.0-1.0,"influenceCount":N,"reactionCount":N}
- `ThemeChanged` - {"activeMode":1|2,"accentHue":0-360,"accentSaturation":0-100,"accentLightness":0-100,"bgHue":0-360,"bgSaturation":0-100,"bgLightness":0-100,"surfaceHue":0-360,"surfaceSaturation":0-100,"surfaceLightness":0-100,"textHue":0-360,"textSaturation":0-100,"textLightness":0-100,"intensity":0-100}
- `SearchMatched` - **v0.5.3.0.** Periodic-evaluator broadcast when a saved search's match set changes. `{"id":"...","name":"...","added":[urls],"removed":[urls],"total":N,"evaluatedAt":"ISO8601"}`. Driven by `SavedSearchScheduler` ticking each saved-search interval; only fires when the diff is non-empty

## Static Pages (/pages/)

MBXHub serves HTML, CSS, and JS from the `/pages/` directory.

### How It Works
- Files location: `%APPDATA%\MusicBee\MBXHub\pages\`
- Access via: `http://{host}/pages/yourfile.html`
- Supports: .html, .css, .js, .json, images
- No build step - just save and refresh

### Included Pages
Read these for working reference code:
- `GET /pages/index.html` - Landing page listing available views
- `GET /pages/player.html` - Full 3-column player (browse iframe, now playing, queue) with drag-drop queue reorder and touch support. Browse panel embeds browse.html via iframe with theme sync via postMessage
- `GET /pages/nowplaying.html` - Focused standalone now-playing view. Drag-drop queue reorder on upcoming tracks. Auto-stacks below 800px into three collapsible blades (Now Playing, Queue, Lyrics).
  - **Now Playing has two states**, never fully collapses to header-only: **Expanded** (~50% viewport, full artwork + reactions) and **Compact** (~52px header bar with mini artwork thumb + title + artist + transport buttons: prev / play-pause / next, all hitting `/player/previous` `/player/playpause` `/player/next`). The play/pause icon mirrors `isPlaying` driven by the `PlayStateChanged` WebSocket event.
  - **Queue and Lyrics use last-touch-wins**: at most one is Expanded at a time. Tapping a collapsed Queue or Lyrics header expands it and auto-collapses the peer to its header bar.
  - Floating 6px progress bar fixed at viewport bottom drives seek via click -> `PUT /player/position`. Position fill driven by the `PositionChanged` WebSocket event with a 30s `/nowplaying/position` poll as a tab-visibility-gated safety net.
  - All blade-collapse / transport markup is gated by the stacked layout (typical at tablet width or fullscreen browser). Charm-tab / iframe-mode rendering is unchanged - gated by `body.iframe-mode` and `html.embedded` rules.
- `GET /pages/browse.html` - Library browser: 8 tabs (Albums/Artists/Genres/Playlists/Tracks/Podcasts/Radio/Moods) with responsive tab sizing, drilldown and breadcrumbs, diacritic-normalized fuzzy search with 8-category grouped results, album art grid with lazy loading, batch queue via long-press, playlist picker, search-driven Tracks tab via /library/search, video items with direct play (no drilldown), auto-search fallback (when inline name filtering yields no results, auto-triggers full-text server search), light/dark theme
- `GET /pages/config.html` - Settings and configuration interface for dashboard and AutoQ
- `GET /pages/autoq.html` - AutoQ Tuning Console: mixer-style sliders for all scoring weights, reaction scores, and normalization ranges
- `GET /pages/mixer.html` - Unified fader mixing surface: three independent faders for Player (MusicBee), Device (Windows audio), and Endpoint (network speaker) volume. Configurable default fader, mute controls, endpoint source selection. Charm bar integration via postMessage
- `GET /pages/explore.html` - Album art explorer: browse albums as artwork with source filters (All/1mo/3mo/12mo/Unheard), search, sort, image gallery with embedded artwork probing, PDF booklet viewing, play/queue controls, theme sync. Accepts `?album=&artist=` query params for seeding from search or dashboard. Artist discography grid in expanded view shows all albums by the current artist. Expanded-view hero has paired close (×) and dashboard home (⌂) buttons — close dismisses the overlay and stays on explore; home navigates to `/dashboard`. Home is hidden in iframe-mode
- `GET /pages/play.html` - Use MusicBee from a browser. Laid out like the MusicBee AMOLED skin: artist picker (left) with infinite-scroll + jump-on-letter typeahead, pluggable middle pane (Albums / Library / Now-Playing iframe registry), upcoming-queue + now-playing card (right), full-width transport footer.
  - Transport: play/pause, prev/next, shuffle, repeat, AutoDJ, volume + mute, scrubber, love, 5-star rating, AutoQ mood select + refresh, reaction buttons (fire/heart/like/dislike/ban) gated on AutoQ availability
  - "+ Add To Playlist" dropdown beside love/stars: quick-curate the playing track to any playlist; "+ New Playlist…" creates one with the current track as seed; last-used playlist bubbles to the top
  - ARiA presets dropdown in the overflow flyout (auto-hides if ARiA isn't enabled)
  - Influence thumbs (artist + genre) on the right-column now-playing card, visible only when mbxq reports `/influences/current`
  - Global media-key shortcuts: Space = play/pause, ← = previous, → = next (skipped while typing in inputs)
  - Cmd+K command palette (Ctrl+K) — same component as the dashboard via shared `/pages/components/cmdk-bootstrap.js`; action rows show the global hotkey alongside (Space / ← / → / ↑ / ↓)
  - **Listen Here** (browser-side audio): output toggle (🔊 speakers / 🎧 browser) in the transport flyout. Speakers is the default (MB plays through the host machine, controlled via `/player/*`). Browser plays the same server queue via a hidden `<audio>` streaming each track from `GET /stream/<fileUrl>` — play/pause/prev/next/volume/mute/scrubber/auto-advance all route to localAudio in browser mode. Flipping to browser pauses MB; flipping back resumes. Gated on `/system/features.streaming`. Persisted per-client in `localStorage["mbxhub-play-output"]`. Small 🎧 chip in `tb-meta` indicates browser mode at a glance.
  - Explore icon on the transport: same-mode re-click toggles the expanded hero + track-list overlay in `/explore` via `postMessage({exploreToggleExpanded: true})` to the iframe — same hook the T / Enter keys expose internally.
  - Live WebSocket updates plus a 30s position-poll safety net that skips when the tab is hidden
  - Browser-side errors routed to mbxhub.log via `/system/client-log` (no console-only logging)
  - Responsive: 3-column desktop ≥1024px, slide-over drawer at 700-1023 landscape (sticky — click-outside no longer dismisses), single-column stacked <700px or portrait tablet with bottom sheet for queue/np
  - Tablet/phone overflow flyout (▾) collapses secondary controls; auto-closes after firing an action (sub-popovers like Add To and ARiA keep the flyout alive while open)
- `GET /pages/media` - Media: full-bleed image/video viewer from configured folders with auto-rotation, crossfade, category browsing, keyboard/touch navigation

### Shared Resources
- `GET /pages/queue-dragdrop.js` - Shared drag-and-drop queue reorder module. Mouse drag (event delegation) + touch long-press (300ms) with visual clone and auto-scroll. Used by player.html, nowplaying.html, and partymode/dj.html
- `GET /pages/components/cmdk.html` - Cmd+K command palette dialog. Self-mounting `<style>` + `<dialog>` + `<script>` fragment. XSS-safe (textContent, no untrusted innerHTML). Actions are POSTs (Play/Pause/Skip/Volume, Start AutoQ radio) or navigations (Open Charms / Settings / Mixer / Player / Browse / Explore / ARiA). Each action carries an optional `kbd` string that's displayed in the row (e.g. Space / ← / →) — the palette doesn't bind these itself; host pages own the global shortcuts and the palette is the discoverable index. Federated search via `/search`, recents via `/search/history` (localStorage fallback). Settings: `dashboardLayout.commandPalette.{enabled,openShortcut,showChip,recentLimit,bucketLimit,actions}`.
- `GET /pages/components/cmdk-bootstrap.js` - Drop-in loader for the command palette. Add `<script src="/pages/components/cmdk-bootstrap.js" async></script>` before `</body>` on any host page. Loads `search-shared.js` then injects `cmdk.html` via DOMParser so embedded scripts execute. Self-mounting; gracefully degrades when search-shared.js is unreachable. Currently wired into `dashboard`, `play.html`, `explore.html`, `nowplaying.html`, and `browse.html`.
- `GET /pages/components/dashboard.css` - Dashboard stylesheet (~2,900 lines / ~100 KB). Served as an external linked resource by `/dashboard`. Theme variables are injected separately by `GetThemeCss()` in an inline `<style>` block that precedes this link; this file contains the bulk of dashboard styling (layout, transport bar, charm bar, command palette, theme designer, party banner, search results). Cacheable; the `/dashboard` page links it with a `?v={version}` query for release-driven cache invalidation. Safe to link from custom dashboards that want to match the built-in look.
- `GET /pages/components/dashboard.js` - Dashboard client script (~2,800 lines / ~150 KB). WebSocket lifecycle, transport handlers, theme designer, charm bar, partial-section reload, command palette wiring. Loaded with `defer` by `/dashboard` after an inline `<script>` that defines the per-request `_themeData` JSON. Same `?v={version}` cache-busting pattern as `dashboard.css`.
- `GET /pages/search-shared.js` - Search lifecycle helper. Provides `MBXSearch.attachSearch` for debounced typeahead with abort-on-keystroke. Required by cmdk; usable standalone.
- `GET /pages/components/shared.css` - **v0.5.3.0 shared frontend core.** Cross-page styles consolidated from per-page duplication: CSS reset + box-sizing, `prefers-reduced-motion` rules, focus / focus-visible defaults, dual theme palettes (default + theme-quiet, light + dark), scrollbar styling, `.album-art-placeholder`, `.hl` highlight class, `.empty-state`. `.toast` is intentionally NOT shared (per-page implementations diverge). Linked first in each shell page's `<head>` so per-page styles can override. Cacheable; safe to link from custom dashboards.
- `GET /pages/components/shared.js` - **v0.5.3.0 shared frontend core.** Cross-page helpers under the `MBXShared` global namespace: `setPageName` / `getPageName`, `clientLog` (batched + sendBeacon-on-pagehide) + `flushClientLog`, `esc` (HTML-encode), `DIACRITICS` (char map ported from MusicBee `CharMap.cs` — union of browse / explore / player local maps, 1:1 char invariant preserved), `normalize` (iter-based: `DIACRITICS` lookup → lowercase → strip apostrophes → collapse non-alphanumerics to single spaces → trim; NFD form removed in the Option C foundation), `findHighlightSpans(text, query)` (returns `Array<{start, end}>` half-open ranges in ORIGINAL-text index space — walks normalized text, finds full-phrase + per-word occurrences, leaves HTML rendering to the caller so pages can wrap spans their own way), `fmtDuration` (ms → `m:ss` or `h:mm:ss`), `connectWebSocket` (subscribe + JSON parse + dispatch-by-event + auto-reconnect with capped backoff). Loaded with `defer` by every shell page. Sibling to `partymode/shared.js` (party-mode subtree has its own consumers; consolidation deferred to a follow-up plan).

### PWA resources (root scope)
Root-URL static resources (NOT under `/pages/`), served by `StaticFileHandler.ServeEmbeddedRoot` from the `MBXHub.Resources.*` embedded-resource namespace. They make the shell pages installable to the home screen / desktop as a basic web-app shortcut. MBXHub serves over plain HTTP (see "LAN HTTP" below), so full PWA install + offline behavior is limited to secure-context origins.

- `GET /manifest.webmanifest` - **v0.5.3.0** PWA Web App Manifest. Returns `application/manifest+json; charset=utf-8`. Fields: `name` (literal `"MBXHub - <hostname>"` with `__HOST_NAME__` token replaced by `Environment.MachineName` at serve time — surfaces in browser install dialogs and "Manage apps" UI), `short_name` (plain `"MBXHub"` — the OS uses this for desktop / home-screen / app-drawer labels, so it stays static across renames), `description`, `start_url=/`, `scope=/`, `display=standalone`, `orientation=any`, `background_color`/`theme_color` matching the dashboard surface, and an icons array (192/512 plus maskable variants). Served with `Cache-Control: no-cache` so install-time fetches are predictable across browsers (Chromium's installed-PWA "update on reload" path otherwise heuristically caches the manifest indefinitely).
- `GET /icons/{name}` - **v0.5.3.0** PWA icon set. Resolves the embedded `MBXHub.Resources.icons.{name}` and serves with `image/png`. Standard set: `icon-192.png`, `icon-512.png`, `icon-maskable-192.png`, `icon-maskable-512.png`, `apple-touch-icon-180.png`. Generated from `MBXS\MBXHub.Shell\brand\mbxhub-halard.png`.
- `GET /pages/hubs.html` - Hub-switcher page. Renders the "Hub neighbors" list (other MBXHub instances this browser has reached recently, read from `localStorage['mbxhub-hub-neighbors']`) plus a free-text host:port input. Pure DOM — no innerHTML, no remote calls.

### LAN HTTP and "Not secure" warnings
MBXHub serves over plain HTTP. Browsers flag any non-localhost HTTP origin as "Not secure". The connection IS unencrypted — the warning is accurate. Workarounds (no TLS added):
- On the host machine: open `http://localhost:<restPort>/dashboard` — localhost is treated as a secure context by all major browsers, so no warning.
- On other devices: mark the origin as trusted via browser flags. Chrome/Edge: `chrome://flags#unsafely-treat-insecure-origin-as-secure`, add `http://machine-name:8080`, restart. Firefox: `about:config` set `dom.securecontext.allowlist=machine-name:8080`.
- Or click through the warning once per session ("Continue to site" / "Advanced > Proceed"). Browser remembers for the session.
- Full write-up at `/config#network` ("Connecting from another device").

### Hub-neighbors discovery
- **Source 1, local (synchronous):** every successful shell page load in `shared.js` records `location.host` into `localStorage['mbxhub-hub-neighbors']` (cap 12, dedupe by host, sort lastSeen newest-first).
- **Source 2, server (async):** `shared.js` also fetches `GET /system/hub-neighbors` per page load. The plugin reads `%LOCALAPPDATA%\MBXHub\hub-neighbors.json` (written by the Shell's `TrayHost.PersistHubNeighbors` after each SSDP discovery — pre-warm on tray-show plus each Libraries-submenu open) and returns its contents. Browser merges server entries into the same localStorage list.
- The `/pages/hubs.html` page reads the merged list. With the Shell running, the user sees SSDP-discovered peers they have never visited from this browser. Without it, the local source alone still works.

### Creating New Pages
To build a custom UI:
1. Create an HTML file
2. Save to `%APPDATA%\MusicBee\MBXHub\pages\`
3. Access at `http://{host}/pages/yourfile.html`
4. Use fetch() for REST API, WebSocket for live updates
5. Reference `/pages/player.html` for working patterns

### Minimal Starter
```html
<!DOCTYPE html>
<html>
<head>
  <title>My Player</title>
  <style>
    body { font-family: sans-serif; padding: 20px; }
  </style>
</head>
<body>
  <div id="track">Loading...</div>
  <button onclick="playPause()">Play/Pause</button>

  <script>
    async function playPause() {
      await fetch('/player/playpause', {method:'POST'});
    }

    async function update() {
      const res = await fetch('/nowplaying');
      const json = await res.json();
      if (json.success) {
        document.getElementById('track').textContent =
          json.data.artist + ' - ' + json.data.title;
      }
    }

    const ws = new WebSocket('ws://' + location.host + '/ws');
    ws.onmessage = (e) => {
      const msg = JSON.parse(e.data);
      if (msg.event === 'TrackChanged') update();
    };

    update();
  </script>
</body>
</html>
```
Save as `myplayer.html` in pages folder, access at `/pages/myplayer.html`

### Best Practices
Follow these patterns for robust, performant, accessible custom pages.

#### CSS Foundation
All MBXHub pages use these CSS best practices:
```css
:root {
    color-scheme: dark; /* Or dark light for theme switching */
    /* ... CSS variables ... */
}

/* Respect user motion preferences */
@media (prefers-reduced-motion: reduce) {
    *, *::before, *::after {
        animation-duration: 0.01ms !important;
        animation-iteration-count: 1 !important;
        transition-duration: 0.01ms !important;
    }
}

/* Box-sizing reset */
*, *::before, *::after { box-sizing: border-box; }

/* Focus styles for keyboard navigation */
button:focus-visible,
input:focus-visible,
a:focus-visible {
    outline: 2px solid var(--accent);
    outline-offset: 2px;
}

/* Cross-browser scrollbar styling */
.scrollable {
    scrollbar-width: thin; /* Firefox */
    scrollbar-color: rgba(255,255,255,0.1) transparent;
}
.scrollable::-webkit-scrollbar { width: 6px; } /* WebKit */
.scrollable::-webkit-scrollbar-thumb { background: rgba(255,255,255,0.1); border-radius: 3px; }
```

## ARiA (Automation)

- `GET /aria/status` - Check if ARiA is enabled
- `POST /aria/send-keys` - Send keyboard input (body: {"keys":"^a"}). Prefix keys with `!` to send to current foreground window without refocusing MusicBee
- `GET /aria/wake` - Wake PC from sleep (also POST)
- `GET /aria/presets` - List available presets
- `GET /aria/programs` - List allowed programs for run() command
- `GET /aria/preset/{name}` - Execute preset (also POST)
- `POST /aria/focus` - Focus MusicBee window
- `POST /aria/mouse/move` - Move mouse (body: {"x":100,"y":200})
- `POST /aria/mouse/click` - Click mouse (body: {"button":"left","x":100,"y":200})

### ARiA Script Commands
Presets use semicolon-separated script commands:
- `sndkeys(keys)` / `sendkeys(keys)` - Send keyboard input (SendKeys or DuckyScript format). Prefix `!` to skip MusicBee refocus: `sendkeys(!{ENTER})` sends to current foreground window
- `delay(ms)` / `wait(ms)` - Pause execution (max 30000ms)
- `run(name[,extraArgs])` / `exec(...)` - Launch a pre-configured program from `ariaAllowedPrograms` in settings. Programs must be defined in mbxhub.json to be executable
- `webhook(url,method,body)` / `http(...)` - HTTP request. Prefix `!` on URL for fire-and-forget
- `click(x,y,button)` / `mouseclick(...)` - Mouse click at coordinates
- `volume(action)` / `vol(action)` - Volume: up, down, mute, +N, -N
- `toast(msg)` or `toast(title,msg)` - Windows balloon notification
- `restart(target)` - Restart: mb/musicbee/app, system/host, shutdown

### ARiA Settings
Key settings in `mbxhub.json`:
- `ariaEnabled` (default: false) - Enable ARiA automation endpoints
- `ariaWebhookTimeoutMs` (default: 10000) - Timeout for webhook commands in milliseconds
- `ariaPresets` - Named scripts for quick execution (default: RIA1-9 presets mapped to Ctrl+Alt + home row keys)
- `ariaCommands` - Custom command aliases and macros extending the built-in command set
- `ariaAllowedPrograms` - Allowlist for the run() command. Each entry has: name (lookup key), path (executable), args (default arguments, optional), hidden (no console window, optional). Empty by default — run() does nothing until programs are configured
- `allowRemoteExit` (default: false) - Allow remote shutdown of MusicBee via ARiA

## RemoteApp

- `GET /remoteapp/status` - RemoteApp status (configured, supported, rdpEnabled, edition, enabled, apiEnabled)
- `GET /remoteapp/rdp` - Download .rdp file for MusicBee RemoteApp connection (blocked when remoteAppApiDisabled)
  - Query: `?hostname=192.168.1.100` (optional, defaults to request Host header)
  - Any other query param forwarded as .rdp setting override (e.g. `?audioqualitymode=0&redirectprinters=1`)
  - Client (Pro/Enterprise): uses full exe path from registry. Server: uses `||AppName` alias for RDS lookup.

### RemoteApp Settings
Key settings in `mbxhub.json`:
- `remoteAppEnabled` (default: false) - Enable RemoteApp feature
- `remoteAppApiDisabled` (default: false) - Disable /remoteapp/rdp endpoint (API is on by default when feature is enabled)
- Dashboard footer links configurable via `dashboardFooterLinks` in settings (null = defaults)

### Prerequisites
- Windows Client (Pro/Enterprise): (1) Settings > System > Remote Desktop > ON. (2) Allow through firewall (auto-prompted, or manually via Control Panel > Firewall > Allow an app > Remote Desktop). (3) NLA is on by default; disable if older clients cannot connect.
- Windows Server: Install RDS role (`Install-WindowsFeature RDS-Connection-Broker, RDS-Web-Access, RDS-RD-Server -IncludeManagementTools`)

### RemoteApp CLI
- `MBXHub.exe remoteapp setup --path <MusicBee.exe>` - Configure RemoteApp (requires elevation, Pro/Enterprise/Server)
- `MBXHub.exe remoteapp setup --detect` - Auto-detect MusicBee and configure
- `MBXHub.exe remoteapp remove` - Remove RemoteApp configuration (requires elevation)
- `MBXHub.exe remoteapp status` - Show current status
- `MBXHub.exe remoteapp rdp --hostname <host>` - Generate .rdp file content

## Media

Serves images and videos from configured root directories. Categories are subfolders under each root. No MusicBee library integration — purely file-serving from user-configured folders.

### Settings (mbxhub.json)
- `media.imageRoot` (default: "") - Root folder for images. Subfolders become categories. Empty = disabled.
- `media.videoRoot` (default: "") - Root folder for videos. Subfolders become categories. Empty = disabled.
- `media.intervalSeconds` (default: 30, range: 5–300) - Rotation timer in seconds.
- `media.shuffle` (default: true) - Random order (true) or alphabetical sequential (false).

### Endpoints
- `GET /media/settings` - Returns `{intervalSeconds, shuffle}` for page/charm consumption.
- `GET /media/images/categories` - List subfolder names under imageRoot. Files in root listed as `_root`.
- `GET /media/videos/categories` - List subfolder names under videoRoot.
- `GET /media/images/{category}` - List filenames in category. Returns `{name, files:[], count}`. Filenames only (no paths).
- `GET /media/videos/{category}` - List filenames in category.
- `GET /media/images/{category}/next` - Serve next image (rotation state, sequential or shuffled).
- `GET /media/videos/{category}/next` - Serve next video (rotation state, HTTP Range support).
- `GET /media/images/{category}/file/{name}` - Serve specific image by filename.
- `GET /media/videos/{category}/file/{name}` - Serve specific video by filename (HTTP Range support for seeking).

### Supported Formats
- Images: .jpg, .jpeg, .png, .bmp, .webp, .gif
- Videos: .mp4, .webm, .mkv, .avi, .mov, .asf, .wmv (.mp4/.webm inline, others open externally)
- Minimum file size: 5KB (skips thumbnails)

### Security
- All paths validated under configured root — no directory traversal.
- Category names mapped to actual subfolders only.
- Filenames validated against actual directory contents.
- Unconfigured/empty root returns empty array for categories, 404 for file requests.

### Page
- `GET /pages/media` - Full-bleed media viewer with auto-rotation, crossfade transitions (images), video playback with seek support, chrome overlay with category/mode selectors, keyboard/touch/swipe navigation.

## Audio Streaming

- `GET /stream/{path}` - Stream an audio or video file from the MusicBee library
  - Path: URL-encoded absolute file path (e.g. `/stream/C%3A%5CMusic%5Csong.mp3`)
  - Supports HTTP Range requests for seeking (206 Partial Content)
  - MIME types: mp3=audio/mpeg, flac=audio/flac, m4a/mp4=audio/mp4, ogg/oga=audio/ogg, wav=audio/wav, opus=audio/opus, aac=audio/aac, wma=audio/x-ms-wma, aiff/aif=audio/aiff
  - Security: path traversal blocked, audio/video extensions only, must be in MusicBee library
  - 400=invalid path, 403=not in library, 404=not found or streaming disabled, 416=invalid range
  - CUE tracks: client uses `cueStartMs` from track data to seek to correct offset; progress and boundaries handled client-side
  - Disable: `disableStreaming` setting (returns 404 when true)
  - Feature flag: `streaming` in `GET /system/features` response

## Device Proxy

- `POST /api/proxy` - Forward HTTP request to a LAN device (CORS bypass)
  - Body: `{"method":"GET|POST|PUT", "url":"http://192.168.x.x/...", "body":{} }`
  - Only private IPs allowed (RFC 1918 + loopback). Public internet blocked (403).
  - Response: target device response passed through verbatim (status code + body).
  - 502 if device unreachable. 5-second timeout.
  - Disable: `apiDisableProxy` setting (returns 404 when true).

## Charms

Charms are configurable action buttons on the dashboard charm bar. Each charm is a `.json` manifest in the `charms/` folder (MBXHub data directory). MBXHub seeds built-in charms on first run: `mixer.json` (volume mixer), `browse.json` (Library Browser), and `aria.json` (ARiA automation — uses the new action-menu display mode). Hidden in party mode.

### Manifest fields
- `id` - Unique identifier
- `icon` - Emoji or character for the button
- `label` - Tooltip / display name
- `action` - Action type:
  - `webapp /path` - Open HTML page (standalone tab or inline iframe)
  - `iframe-cmd <command>` - Send postMessage to charm iframe (auto-loads if needed)
  - `http://...` - Fire HTTP request (cross-origin routed via `/api/proxy`)
- `display` - `standalone` (new tab), `inline` (iframe), `both` (click=inline, shift+click=standalone), or `action-menu` (single trigger + popover of `expand[]` items — used by the built-in ARiA charm)
- `msg` - Status message after execution
- `context` - Optional: `library-only` or `stream-only`
- `expand` - Array of sub-actions (icon, label, action, display, msg). Renders as grouped button row with connection status dot.

### Settings (`charmBar` in mbxhub.json)
- `order` (default: []) - Charm IDs in display order. New charms appended automatically.
- `hidden` (default: ["endpoints","explore","projector"]) - Charm IDs to hide from the dashboard.
- `buttonSize` (default: "M") - Bar-level button size preset: S (36px), M (44px), L (52px), XL (64px), XXL (76px). S/M were bumped in v0.5.2.1 (was 32/40); XL/XXL added in v0.5.2.3 for high-density touch displays (11.6" FHD @ 150% DPI needs ~76px to hit 0.6" physical).
- `sizeOverrides` (default: {}) - Per-charm size map (charm ID → S/M/L/XL/XXL). Individual charms can break from the bar-level size via this override.
- `breakBefore` (default: []) - Charm IDs that force a new row in the charm bar. Combined with `sizeOverrides`, one charm (e.g. the mixer) can occupy an XL row while the rest stay compact.
- `displayOverrides` (default: {}) - Per-charm display mode (charm ID → "inline" or "standalone"). Overrides the charm manifest's default.

The charm bar is also a dashboard layout section (`charms`) that can be reordered/hidden via `dashboardLayout`.

## System

- `GET /ping` - Health check (alias: `GET /system/ping`)
- `GET /status` - HTML status page with live dashboard: system info (version, uptime, host, modules), library stats (tracks, albums, artists, genres, playlists, podcasts), AutoQ state (status, vibe list, mood cache, auto scan), and feature flags
- `GET /diag` - **Diagnostic surface (v0.5.2.6+).** Embedded HTML page with live sparklines for process CPU%, network in/out, working/private memory, thread count, handle count, GC gen0/1/2 rates. Polls `/diag/perf` from the browser at 1Hz; keeps a 120-sample (~2 min) ring client-side. Server is stateless — no background timer. Off by default; gated on `diagnostics.diagEndpointEnabled = true` in `mbxhub.json`. Returns 404 with explanatory body when disabled.
- `GET /diag/perf` - JSON snapshot for `/diag` page polling. Response: `{ ts (epochMs), processorMs (cumulative TotalProcessorTime), workingSetMB, privateMB, threadCount, handleCount, gen0/gen1/gen2 (cumulative GC.CollectionCount), bytesIn/bytesOut (cumulative system-wide via NetworkInterface, loopback excluded), logicalProcessors }`. Cumulative counters are diffed client-side to derive per-second rates. Same gate as `/diag` — 404 when disabled.
- `GET /diag/mbxhub` - Per-MBXHub instrumentation snapshot rendered by the `/diag` page as a second tile row alongside the MusicBee-process row from `/diag/perf`. Same `diagEndpointEnabled` gate.
- `POST /diag/snapshot` - **v0.5.2.6+**. Takes the `/diag` page's client-side ring (JSON body with `samples`, `sampleCount`, `logicalProcessors`, `capturedAt`) and appends a formatted text block to `diag-snapshots.log` next to `mbxhub.log`. Each entry has a header (timestamp, source IP, sample count), a min/avg/max/latest table per metric, and the raw samples JSON for forensic re-processing. Triggered by the Snapshot button on the page. Same `diagEndpointEnabled` gate. Response: `{success, path, bytes, at}`. Append-only single file — snapshots are visually delimited by `===` rules so operators can extract one section by grep on the timestamp.
- `GET /diag/search` - **v0.5.3.0**. Rolling p50/p90/p95/p99 over the last 256 search calls (in-memory ring, ~28 KB footprint, server-wide singleton). Response: `{ summary: { count, totalRecorded, capacity, library: {count, totalMs:{p50,p90,p95,p99,max,mean}, candidates:{p50,p95,max}, mbCalls:{p50,p95,max}}, federated: {…same shape…}, combined: {…same shape…} }, recent: [{ts, endpoint, q, qLen, mode, totalMs, results, candidates, limit, stages:{mb,cue,am,pf,sort,pg}, mbCalls:{total,qf,ql,qlr,gt,gts,gp,gb,pl}}, …] }`. `library` and `federated` are segregated because they have very different latency distributions; `combined` retained for unsegregated callers. `endpoint` field on each recent entry is `library-search` or `search-federated`. Optional `?recent=N` (default 50, capped at ring capacity) limits the recent slice; the summary always covers the full ring. Same `diagEndpointEnabled` gate as `/diag`.
- `POST /diag/search/reset` - **v0.5.3.0**. Clears the `/diag/search` ring (operator-triggered diagnostics flush). Empty body. Response: `{success, reset:true}`. Same `diagEndpointEnabled` gate. **Returns 403 FORBIDDEN when `ApiReadOnlyMode` is set** — kiosk deployments can't have their perf history wiped by remote clients. Use `Content-Length: 0` header for curl: `curl -X POST -H "Content-Length: 0" http://host/diag/search/reset`.
- `GET /system/status` - Server status
- `GET /system/version` - Version info (includes `host` field with discovery name or machine name)
- `GET /system/capabilities` - Returns this node's capabilities for cross-channel SSDP discovery. Response: `{ node, version, capabilities[], endpoints{} }`. Used by Shell and other MBXHub nodes to discover what this instance offers.
- `GET /system/features` - Enabled feature flags. Response fields: `banlist`, `ratings`, `loved`, `reactions`, `streaming`, `autoq`
- `GET /system/metrics` - Performance metrics
- `GET /system/uptime` - Server start time and uptime duration
- `GET /system/client-ip` - Returns client's IP as seen by the server. Used by the SMTC Link Charm to discover the client's local Shell on remote dashboards.
- `GET /system/settings` - Get MBXHub settings. Response includes the network fields (`restPort`, `restEnabled`, `wsEnabled`, `defaultPage`), legacy `webSocketPort` (always equals `restPort`), plus **v0.5.2.4+** `logLevel` (trace/debug/info/warn/error, propagates to Shell) and `library.disableStrictSearch` (nested bool — disables phrase-per-field strict library search). **v0.5.3.0** `search.live.minQueryLength` (int, default 2) — server-side hard backstop; queries shorter than this on `/library/search` and `/search` return `400 QUERY_TOO_SHORT`. Set to `0` to disable the backstop (not recommended on libraries above ~50k tracks). MBRC was cut; `mbrcPort` / `mbrcEnabled` no longer exist.
- `PUT /system/settings` - Update settings (also POST). Security: `restPort` and `restEnabled` changes require localhost (403 for remote). All changes blocked during party mode for remote clients. Accepts the same field set as GET: **v0.5.2.4+** also accepts `logLevel` (validated against trace/debug/info/information/warn/warning/error, invalid silently ignored) and `library.disableStrictSearch` (creates the nested object if missing). Neither new field requires localhost — both are UX-level settings.
- `GET /system/settings/schema` - Schema for all configurable settings (type, range, default, current value). Blocked during party mode and when remote config is disabled.
- `PUT /system/config` - Update configurable settings via dotted keys. Only [ConfigSetting]-scoped properties. Blocked by read-only mode, party mode, remote config disabled.
- `POST /system/config` - Alias for `PUT /system/config`
- `GET /system/default-page` - Get default redirect page
- `PUT /system/default-page` - Set default page (body: `{"defaultPage":"/pages/player.html"}`)
- `GET /system/theme` - Returns current theme configuration. Per-mode fields: accentHue (0-360), accentSaturation (0-100), accentLightness (0-100), bgHue (0-360), bgSaturation (0-100), bgLightness (0-100), surfaceHue (0-360), surfaceSaturation (0-100), surfaceLightness (0-100), textHue (0-360), textSaturation (0-100), textLightness (0-100), intensity (0-100, saturation multiplier).
- `PUT /system/theme` - Update theme configuration. Body: `{"activeMode":1|2, "mode1":{"accentHue":int, "accentSaturation":int, "accentLightness":int, "bgHue":int, "bgSaturation":int, "bgLightness":int, "surfaceHue":int, "surfaceSaturation":int, "surfaceLightness":int, "textHue":int, "textSaturation":int, "textLightness":int, "intensity":int}, "mode2":{...}}`. Partial updates supported per-field. Broadcasts ThemeChanged WebSocket event with full active-mode payload.
- `theme.disablePinchZoomLock` (default: false) - When true, native pinch-to-zoom is unlocked on the dashboard (default is locked). Also surfaced as a toggle in the theme drawer.
- `GET /system/qr` - QR code PNG for base URL (optional `?url=` override)
- `POST /system/seed-resources` - Force re-extract all embedded resources (pages, charms)
- `POST /system/events/{name}` - Push a named event to the WebSocket broadcaster from sub-process components (Shell, scripts). Body is forwarded as the event payload. Dashboards subscribed to `{name}` receive it.
- `POST /system/client-log` - Browser-side log relay. Body: `{"level":"warn","msg":"...","page":"dashboard"}` (single event) or `{"events":[{...},{...}]}` (batch). Writes each event to the server `mbxhub.log` — dashboard pages should route operational telemetry here rather than `console.log` so problems in guest browsers are visible server-side. Recognized fields: `msg` (required), `level` (optional, default `info`, free-form string → server log levels, unknown = info), `page` (optional; wraps as `[page] msg`). Any OTHER fields on the event object are silently dropped — concatenate stack traces into `msg`. Both `msg` and `page` are sanitized (CR/LF/NUL stripped, 4096/256 char caps). Silent on empty body (returns `accepted:0`). Invalid JSON → `400 INVALID_REQUEST`. Response: `{success:true, data:{accepted:N}}`. **Access:** `ActionCategory.System` (admin-only). PartyMode guests are rejected so guest-sourced log entries can't mix into operator telemetry.

## Network Discovery

MBXHub advertises on the local network via three protocols, all controlled by the `discoveryEnabled` setting:
- **SSDP/UPnP** (UDP 1900) — UPnP device advertisement
- **WS-Discovery** (UDP 3702) — Windows Network folder integration
- **mDNS/DNS-SD** (UDP 5353) — Bonjour/zero-conf (Win10 1809+, graceful fallback on older)

The `discoveryName` setting controls the friendly name shown across all protocols. Empty = machine name.

- `GET /device.xml` - UPnP device description XML (friendlyName, presentationURL, services)
- `POST /wsd` - WS-Discovery metadata exchange. Windows sends SOAP GetMetadata after UDP Probe discovery; response includes PresentationUrl → `/dashboard`. This makes MBXHub appear in the Windows Explorer Network folder with a "Device webpage" link.

Firewall: two TCP ports + three UDP discovery ports.

- **TCP `restPort`** (default 8080) — plugin REST API + WebSocket. Always required.
- **TCP `smtc.port`** (default `restPort + 1`, i.e. 8081) — Shell `/meta/smtc/*` control routes. Open only when MBXHub.exe (Shell) is running and you want remote SMTC retargeting / dashboard SMTC control. Skip for plugin-only / NAS / headless installs (`smtc.enabled: false`).
- **UDP 1900** — SSDP/UPnP discovery
- **UDP 3702** — WS-Discovery (Windows Network folder)
- **UDP 5353** — mDNS/DNS-SD

The plugin's Settings → Firewall helper opens both TCP ports together (REST port + REST port + 1) plus the three UDP ports. `MBXHub.exe --install` adds a separate `MBXHub-Shell` rule + URL ACL for `smtc.port` automatically; `--uninstall` removes it. Configure ports via `restPort` in `mbxhub.json` and `smtc.port` in `mbxhub-shell.json` (override the +1 convention by setting `smtc.port` explicitly).

## PartyMode

Web-based party music system for group listening. Three roles: Guest (browse/request), DJ (full control), Display (TV mode).

### Pages
- `GET /pages/partymode/` - Entry point with PIN + nickname form
- `GET /pages/partymode/guest.html` - Guest: browse 7 tabs (Albums/Artists/Genres/Playlists/Podcasts/Radio/Moods), fuzzy search, request songs, vote, react
- `GET /pages/partymode/dj.html` - DJ: full playback control, drag-drop queue reorder, AutoQ control
- `GET /pages/partymode/display.html` - TV: large artwork, lyrics, floating reactions, request feed
- `GET /pages/partymode/leaderboard.html` - Party stats: top guests, top tracks, reaction counts

**Kill switch:** `ApiDisablePartyMode=true` in mbxhub.json (Features section) returns 404 on every `/partymode/*` route AND `/pages/partymode/*` static page. `GET /system/features` reports `partymode:false` so client UIs can hide entry points.

### Endpoints
- `GET /partymode/status` - Check if party is active
- `POST /partymode/start` - Start party (body: {"guestPin":"1234","djPin":"5678"}); host-only (request.IsLocal); 403 PARTY_START_FORBIDDEN otherwise; 409 PARTY_ALREADY_ACTIVE if a party is already running
- `POST /partymode/stop` - End party session
- `GET /partymode/validate?pin=1234&nickname=Haro` - Validate PIN, register join, returns role (guest/dj)
- `POST /partymode/verify-dj` - Verify DJ PIN for DJ page access (body: {"pin":"5678"})
- `POST /partymode/vote` - Submit vote with attribution (body: {"type":"++","target":"Artist","value":"Rock","nickname":"Haro"})
- `POST /partymode/request` - Submit song request (body: {"url":"path","nickname":"Haro"})
- `GET /partymode/requests` - Recent requests (for DJ view)
- `GET /partymode/feed` - Activity feed: joins, requests, votes, and reactions (for display)
- `GET /partymode/qr` - Generate QR code image (PNG) with party URL
- `GET /partymode/role` - Current user's role (guest/dj/anonymous) + QR sharing flags

### QR Code Sharing
- `GET /system/qr` returns QR for base URL; `?url=` overrides target
- Guest and DJ pages have QR buttons for viral party sharing
- Dashboard QR auto-switches to party join URL when party is active
- Settings: `disableGuestQr` hides QR on guest page, `disableHostQr` hides QR on DJ/dashboard

### Quick Start
1. DJ visits `/pages/partymode/`, starts party with PIN
2. Display page shows QR code with embedded PIN
3. Guests scan QR, enter nickname, browse and request songs
4. Requests appear on DJ page and display feed

### Integration with Influences
Guests can vote (thumbs up/down) on currently playing and queued tracks. Uses the Influences API to adjust shuffle preferences in real-time.

## AutoQ (v0.4.9+)

Intelligent queue system. AutoQ combines TrueShuffle rules, mood analysis, reactions,
and influences to automatically queue tracks that match the room's energy.

### TrueShuffle (Rules Engine)

TrueShuffle manages the shuffle cycle — play rules, cycle tracking, and queue constraints.
Returns `503 SERVICE_UNAVAILABLE` if TrueShuffle/AutoQ not enabled.

- `GET /shuffle/status` - Shuffle cycle progress
- `POST /shuffle/reset` - Reset shuffle cycle
- `GET /shuffle/played` - Tracks played this cycle
- `GET /shuffle/remaining` - Tracks remaining

### Banlist

Permanently excluded tracks. Banned tracks are never queued by AutoQ.
Returns `503 SERVICE_UNAVAILABLE` if TrueShuffle/AutoQ not enabled.

- `GET /banlist` - List banned tracks
- `POST /banlist` - Ban track (body: {"url":"path","reason":"optional"})
- `DELETE /banlist/{url}` - Unban track

### Influences

Influence rules shape AutoQ scoring — Pandora-style thumbs up/down on artists and genres.
Unlike bans (permanent, track-specific), influences are resettable metadata preferences.
Returns `503` if TrueShuffle/AutoQ not enabled.

- `GET /influences` - List influences
- `POST /influences` - Add influence (body: {"type":"++","target":"Genre|Artist","value":"Rock"})
- `DELETE /influences/{target}/{value}` - Remove influence
- `POST /influences/clear` - Clear all influences
- `GET /influences/current` - Current track's influence data

### Scoring System
- **Reactions** on now playing: Fire (+3, triggers queue refresh), Heart (+2), Like (+1), Dislike (-1), Ban (-100, excludes). Reactions auto-create influences: fire/heart → artist++, like → genre++, dislike → genre--, ban → artist--
- **Influences**: Thumbs up/down on artists and genres (also created automatically from reactions)
- **Recency**: Small boost for recently reacted tracks
- **Mood Matching**: Tracks matching target mood score better

### Mood Channels
Default mood channels with arousal/valence targets (customizable via `autoQ.moodChannels` in mbxhub.json):
- Energetic (0.95, 0.85) | Dance (0.80, 0.70) | Intense (0.90, 0.20) | Upbeat (0.65, 0.85)
- Morning (0.50, 0.80) | Chill (0.30, 0.70) | Mellow (0.20, 0.50) | Night (0.15, 0.30)
- Emotional (0.45, 0.20) | Relax (0.10, 0.60)

Custom channels example in mbxhub.json:
```json
"moodChannels": [
  { "name": "Energetic", "emoji": "🔥", "arousal": 0.90, "valence": 0.80 },
  { "name": "Chill", "emoji": "😌", "arousal": 0.35, "valence": 0.65 }
]
```

### Mood Quadrants
Arousal (energy) is the vertical axis, valence (positivity) is the horizontal. Each mood channel targets a point in this 2D space.
- **High arousal + high valence** = Energetic, upbeat (EDM, pop, funk). Fast tempo, bright timbre, strong beats.
- **High arousal + low valence** = Tense, aggressive (metal, hard rock, industrial). Distortion, high energy, dissonance.
- **Low arousal + low valence** = Sad, subdued (ambient drone, slow blues, lo-fi). Slow tempo, dark timbre, soft dynamics.
- **Low arousal + high valence** = Calm, pleasant (chillhop, acoustic folk, soft jazz). Warm timbre, consonance, smooth textures.

### AutoQ Settings
Key settings in `mbxhub.json` under `autoQ`:
- `pickMode` (default: "Weighted") - Track selection mode: Off (shuffle fill only), Favorites (highest-scored), Weighted (score-proportional random), Random (uniform random, diversity caps still apply)
- `artistQuota` (default: 1) - Max tracks from same artist in batch (0=disabled)
- `genreQuota` (default: 3) - Max consecutive same-genre tracks (0=disabled)
- `moodMatchWeight` (default: 0.4) - Weight for mood matching in scoring (0-1)
- `moodTagField` (default: "Custom1") - MusicBee custom tag field for writing mood labels (null=disabled)
- `moodTagFieldName` (default: "AutoQ Mood") - Expected display name for the custom tag field (must match MusicBee config)
- `minReplayMinutes` (default: 30) - Minimum minutes before a track can be replayed
- `diversityWindowSize` (default: 10) - Recent tracks considered for diversity calculations
- `minSessionEntropy` (default: 0.5) - Entropy threshold before boosting diversity (0-5)

### Estimation Settings
Normalization parameters for mood matching and feature extraction, tunable via `autoQ.estimation` in mbxhub.json:
- `usePercentileNormalization` (true) - Use percentile-based normalization (library-adaptive). When false, uses absolute min/max ranges below. Requires >= 5 Essentia-analyzed tracks.
- `moodMatchMinSimilarity` (0.5) - Minimum similarity to match a mood channel
- `bpmMin` (80), `bpmMax` (170) - BPM normalization range (used when percentile off)
- `ratingScale` (5.0) - Rating scale for valence normalization
- `yearMin` (1950), `yearMax` (2030) - Year normalization range
- `playCountLogDivisor` (4.0) - Play count log scaling divisor
- `moodComboMaxResults` (2) - Max mood-combo channels returned per track (range 1-5)
- `moodComboMinScore` (0.85) - Min similarity to include a mood channel in combo results (0-1)
- **Valence weights** (positivity, sum ~1.0) under `autoQ.estimation`: `valenceWeightMode` (0.35), `valenceWeightDissonance` (0.25), `valenceWeightChords` (0.15), `valenceWeightPitchSalience` (0.10), `valenceWeightMfcc` (0.10), `valenceWeightDance` (0.05), `valenceWeightCentroid` (0.0 — centroid is an arousal feature), `valenceWeightFlatness` (0.0 — always zero from Essentia). Mode scoring: `modeScoreMajor` (0.85), `modeScoreMinor` (0.4).
- **Arousal weights** (energy, sum ~1.0) under `autoQ.estimation`: `arousalWeightBpm` (0.25), `arousalWeightLoudness` (0.20), `arousalWeightFlux` (0.15), `arousalWeightOnsetRate` (0.15), `arousalWeightRms` (0.10), `arousalWeightZcr` (0.08), `arousalWeightCentroid` (0.05), `arousalWeightDynamicRange` (0.05), `arousalWeightDance` (0.02). `DynamicRange` is BS.1770 LRA in LU from Essentia; when null, `MoodComputer` falls back to genre-based defaults at lookup time (metal→6, jazz→13, classical→17, unknown→8).
- **Normalization ranges** (used when percentile off) under `autoQ.estimation`: `centroidMin/Max` (500/2300 Hz), `loudnessMin/Max` (-23/-5 dB), `onsetRateMax` (5.5), `zcrMax` (0.12), `rmsMax` (0.008), `chordsRateMax` (0.2), `fluxMax` (0.12), `danceMax` (1.7), `mfccMin/Max` (70/220).

### Endpoints
- `GET /autoq/status` - AutoQ status and configuration
- `POST /autoq/start` - Start AutoQ (body: `{"mode":"autopilot"|"djassist"}`)
- `POST /autoq/stop` - Stop AutoQ
- `GET /autoq/moods` - Get available mood channels with arousal/valence coordinates
- `GET /autoq/moods/browse?channel=Energetic` - Browse tracks matching a mood channel (?limit=200)
- `GET /autoq/track-mood` - Raw mood data for current track (or ?url=file://...). Returns file, album, Essentia features, percentile ranks, computed valence/arousal, best mood match, confidence score (0-1), genre profile applied
- `GET /autoq/mood-by-hash/{hash}` - Hash-keyed counterpart to `/autoq/track-mood` for cross-system lookup. `{hash}` is hex (`audioStreamSha256` = 64 chars, `fileMd5` = 32 chars). Returns the same mood payload shape.
- `POST /autoq/mood` - Set target mood (body: {"channel":"Energetic"})
- `POST /autoq/moods/reload` - Reload mood cache from disk
- `GET /autoq/moods.json` - Download the active mbxmoods.json (seed another node). Disabled by default; toggle in Settings → Configuration → Services.
- `GET /autoq/mood-cache/status` - Local mood-cache totals. Response: `{total, essentia, fallback, warmupInProgress: false, lastWarmup: null}`. Shape preserved for client compatibility; warm-up no longer fires.
- `GET /autoq/vibe-list` - Current candidate tracks with scores (?count=50)
- `POST /autoq/react` - Submit reaction (body: {"emoji":"fire","nickname":"Haro"})
- `GET /autoq/reactions` - Reaction history (?trackUrl=, ?limit=50)
- `GET /autoq/stats` - Leaderboard data (top guests, top tracks, reaction breakdown)
- `GET /autoq/taste-explorer` - Discover tracks adjacent to current taste profile, grouped by category (?limit=100&groupBy=auto|genre|artist|mood)
- `GET /autoq/similar` - Find tracks similar to a seed track by metadata and feature distance (?url={trackUrl}&limit=20)
- `GET /autoq/settings` - All tunable AutoQ parameters (weights, scores, normalization, genre profiles, confidence thresholds)
- `PUT /autoq/settings` - Partial update AutoQ parameters (body: JSON with changed fields only). Changes apply on next scoring pass. Supports genreProfiles dictionary for genre-aware weight adjustment.
- `POST /autoq/retag-moods` - Bulk write mood tags to MusicBee custom field (Essentia-analyzed tracks only)
- `POST /autoq/vibe-list/refresh` - Force refresh vibe list
- `POST /autoq/refresh-queue` - Refresh the vibe list and immediately enqueue picked tracks (vibe-list/refresh + queue action in one call). Used by the dashboard refresh button.
- `POST /autoq/pick` - Pick next track from vibe list (returns best track without queueing)
- `POST /autoq/unban` - Unban a track (body: {"url":"file://..."})
- `GET /autoq/banned` - Check if current track is banned
- `POST /autoq/reset` - Reset AutoQ session state (clears reactions, taste vector, ban list)

### Reactions
- `fire` - This track is fire! (+3, triggers queue refresh)
- `heart` - Love this song (+2)
- `like` - Good choice (+1)
- `dislike` - Not feeling it (-1)
- `ban` - Skip and exclude (-100)

### Quick Start
1. Enable AutoQ in MBXHub settings or via `POST /autoq/start`
2. Guests react to now playing tracks via guest page or `/autoq/react`
3. AutoQ learns preferences and adds matching tracks when queue runs low
4. View leaderboard at `/pages/partymode/leaderboard.html` or via `/autoq/stats`
5. Tune algorithm live at `/pages/autoq.html` - mixer-style sliders for all weights, scores, and normalization ranges

## Access Control (v0.4.8+)

### Roles
- **DJ** - Full playback control, queue management, see requests. Authenticated via DJ PIN.
- **Guest** - Browse library, request songs, vote on vibes. Authenticated via Guest PIN.
- **Anonymous** - Unauthenticated access. Subject to protection level restrictions.

### Protection Levels
- **Default** - Normal operation. Granular read-only controls available (player, queue, library, playlists).
- **Kiosk** - All navigation redirects to default page. For party displays or public terminals.
- **Read-Only** - Master switch blocks all write operations. PartyMode endpoints exempt.

### PIN Authentication
PartyMode uses PIN-based authentication:
- `GET /partymode/validate?pin=1234&nickname=Haro` - Validate PIN, returns role (dj/guest)
- `POST /partymode/verify-dj` - Verify DJ PIN (body: {"pin":"5678"})
- `X-Party-PIN` header - Include PIN in request header for authenticated API calls

### Media Endpoints in PartyMode
**v0.5.2.6+**: When a party is active, `/media/*` endpoints are DJ-only. Guest and Anonymous callers get `403 PARTY_LOCKED`. The host's Projector charm runs as DJ on localhost, so the big-screen flow keeps working. Outside party mode, every caller is allowed (media is browse-only and not covered by the existing ApiReadOnly* gates).

### Access Control Response
Blocked requests return 403 with error code:
```json
{"success":false,"error":{"code":"READ_ONLY","message":"API is in read-only mode"}}
{"success":false,"error":{"code":"PARTY_LOCKED","message":"Player controls locked during PartyMode"}}
```

## Settings

### `mbxhub.json` — diagnostic + performance tunables (v0.5.2.6+)

Two new advanced-tier sections expose the spike-instrumentation knobs and the hot-path constants. **Defaults preserve current behavior.** Tune per environment without rebuilding.

```jsonc
{
  "diagnostics": {
    "diagEndpointEnabled": false,            // gates /diag and /diag/perf (404 when false)
    "rollupIntervalMs": 60000,               // counter-flush cadence for #1, #4, #12, #2 rollup logs
    "warnThresholdsMs": {
      "wsSlowSend": 200,                     // audit #6 — Warn if SendAsync > Nms
      "wsSlowBroadcast": 250,                // audit #5 — Warn if WhenAll > Nms (general events)
      "wsSlowBroadcastPosition": 100,        // audit #5 — tighter for 1Hz PositionChanged
      "moodCacheLockWait": 25,               // audit #8 — Warn if read-path lock entry > Nms
      "moodCacheBulkInsert": 50,             // audit #8 — Warn if bulk insert held > Nms
      "timerDispose": 100,                   // audit MED #18 — Warn if Timer.Dispose blocked
      "smtcUpdate": 30,                      // audit MED #14 — Warn if STA marshal > Nms (Shell)
      "lookAhead": 100,                      // audit #3 — Warn if look-ahead loop > Nms
      "autoQRefresh": 100                    // audit MED #13 — Warn if scoring pass > Nms
    }
  },
  "performance": {
    "wsSendTimeoutMs": 5000,                 // WebSocketClient send timeout (was const 5000)
    "wsMaxClients": 100,                     // EventBroadcaster cap (was const 100)
    "volumeDebounceMs": 50                   // coalesce drag bursts; 0 disables (broadcast every event)
  }
  // Shell-side throttle (SMTC update marshalling) lives in mbxhub-shell.json as `smtc.throttleMs` —
  // see the "MBXHub Shell" section below.
}
```

**How to use during fault investigation:**
1. Enable `/diag` by setting `diagnostics.diagEndpointEnabled = true`, restart MusicBee, navigate to `http://host:8080/diag` and leave the page open.
2. Lower the relevant threshold (e.g. `wsSlowBroadcastPosition: 50`) to surface contention sooner.
3. Tail `mbxhub.log` while reproducing the glitch; the per-finding Warn lines pin down which layer is slow.
4. After the fix, restore defaults or raise thresholds to silence the per-event logs (the per-minute rollup Debug logs always fire when `RollupIntervalMs > 0` and counters > 0).

Audit + reopen criteria: `docs/superpowers/audits/2026-05-02-network-cpu-spike-instrumentation.md` and `docs/backlog/2026-05-02-spike-fixes-deferred.md`.

### 500 response body gate (`debugMode` + `logLevel`)

`INTERNAL_ERROR` (HTTP 500) response bodies are routed through `HubLogger.IsDebugEnabled` — when **both** `debugMode = true` AND `logLevel` is `Debug` (or `Trace`), the body contains the full exception dump (type, message, stack trace, inner-exception chain). Otherwise the body is the generic fallback string. The dump always lands in `mbxhub.log` via `_log.Warn(ex, ...)` regardless of the gate.

Rationale: self-hosted LAN deployments where the operator is also the consumer want the dump in the response so a crash can be debugged from the client without tailing `mbxhub.log`. Default ships fail-secure (`debugMode: false`) so production / shared-network exposure does not leak internals.

To enable on the live instance:
```json
{
  "debugMode": true,
  "logLevel": "Debug"
}
```
Then restart MusicBee (or the plugin). Setting either flag alone does NOT enable the dump — both must hold.

### MusicBee settings (existing)

- `GET /settings` - All MusicBee settings
- `GET /settings/storage-path` - Library storage path
- `GET /settings/skin` - Current skin name
- `GET /settings/field-name?field=N` - Field display name
- `GET /settings/data-type?field=N` - Field data type
- `GET /settings/skin-element-color?element=N&state=N&is498=false` - Skin element color
- `GET /settings/window-borders-skinned` - Whether window borders are skinned
- `GET /settings/lastfm-user` - Last.fm username
- `GET /settings/web-proxy` - Web proxy settings
- `GET /settings/value?id=N&defaultValue=` - Get setting value by ID
- `GET /settings/convert-command?format=N` - Conversion command line

## Podcasts

- `GET /podcasts` - List subscriptions
- `GET /podcasts/{id}` - Subscription details
- `GET /podcasts/{id}/artwork` - Subscription artwork
- `GET /podcasts/{id}/episodes` - List episodes (also: `GET /podcasts/episodes?id={url}` for feed URL IDs)
- `GET /podcasts/{id}/episodes/{index}` - Episode details

## Pending

- `GET /pending` - Pending file info
- `GET /pending/url` - Pending file URL
- `GET /pending/property?type=X` - Pending file property
- `GET /pending/tag?tag=X` - Pending file tag

## MusicBee App

- `POST /app/exit` - Exit MusicBee (requires allowRemoteExit). Optional body: `{"restart":true,"delay":22}` to schedule restart via Task Scheduler
- `POST /app/restart` - Restart MusicBee (requires allowRemoteExit). Optional body: `{"delay":22}`. Convenience alias for exit with restart=true
- `GET /mb/window-handle` - Window handle
- `POST /mb/refresh-panels` - Refresh UI panels
- `POST /mb/command` - Invoke MusicBee command
- `GET /mb/visualisers` - List visualizers
- `POST /mb/visualiser` - Show visualizer
- `POST /mb/plugin-view` - Show plugin view
- `GET /mb/plugin-views` - List plugin views
- `GET /mb/localisation?id=X` - Get localized string
- `POST /mb/nowplaying-assistant` - Show now-playing assistant panel
- `POST /mb/filter` - Open filter in MusicBee (body: {"filter":"..."})
- `POST /mb/window-size` - Set window size (body: {"width":800,"height":600})
- `POST /mb/download` - Download file (body: {"url":"..."})

## RPC

Direct access to all 137 MusicBee API methods. Subject to the same read-only and granular access controls as REST endpoints (e.g., `Player_PlayPause` requires player playback permission, `Library_SetFileTag` requires library tags permission).
- `POST /rpc/{methodName}` - Call any API method

Example:
```
POST /rpc/Player_PlayPause
POST /rpc/NowPlaying_GetFileTag (body: {"tag":"Artist"})
POST /rpc/Library_QueryFiles (body: {"query":"genre=Rock"})
```

Method categories: Player_*, NowPlaying_*, NowPlayingList_*, Library_*, Playlist_*, Setting_*, MB_*, Podcasts_*, Sync_*

**GOTCHA:** After writing tags via RPC, call `MB_RefreshPanels` or MusicBee UI won't update:
```
POST /rpc/Library_SetFileTag (body: {"file":"...","tag":"Rating","value":"5"})
POST /rpc/Library_CommitTagsToFile (body: {"file":"..."})
POST /rpc/MB_RefreshPanels  ← Don't forget this!
```
Note: REST endpoints (PUT /library/file/...) call refresh automatically.

## Sync (Preview)

Library sync between MBXHub instances (coming in .6 LP):
- `GET /sync/status` - Sync status
- `GET /sync/peers` - Known peers
- `GET /sync/discover` - Discover peers on network
- `GET /sync/delta` - Library delta since last sync
- `GET /sync/operations` - All sync operations
- `GET /sync/operations/{syncId}` - Single sync operation by ID
- `POST /sync/start` - Start sync operation
- `POST /sync/stop` - Stop sync
- `POST /sync/pull` - Pull files from peer
- `POST /sync/push` - Push files to peer

### Sync Settings
Settings in `mbxhub.json`:
- `syncEnabled` (default: false) - Enable library sync
- `syncRole` (default: "island") - Sync role: "island" (standalone), "hub", or "spoke"

## Device Sync (MBSync)

Internal MusicBee device synchronization callbacks. Used by MusicBee's built-in sync feature when syncing with mobile devices:
- `POST /mbsync/file/start` - Notify sync file transfer starting
- `POST /mbsync/file/end` - Notify sync file transfer complete
- `POST /mbsync/file/delete/start` - Notify sync file deletion starting
- `POST /mbsync/file/delete/end` - Notify sync file deletion complete

## Debug

Diagnostic endpoints for testing and validation (used by MBXHVAL test toolkit):
- `GET /test/websocket` - Interactive WebSocket event test page with subscription controls
- `GET /debug/clouseau/status` - Clouseau inspector plugin status
- `GET /debug/clouseau/state` - Get Clouseau state snapshot
- `POST /debug/clouseau/state` - Save Clouseau state
- `GET /debug/clouseau/files` - Get Clouseau file list

## Response Format

Success:
```json
{"success":true,"data":{...}}
```

Error:
```json
{"success":false,"error":{"code":"ERROR_CODE","message":"Description"}}
```

## Usage Rules

### File URLs
All file URLs are Windows paths. URL-encode when passing in path parameters:
- Original: `C:\Music\Artist\Track.mp3`
- Encoded: `C%3A%5CMusic%5CArtist%5CTrack.mp3`

### Pagination
Most list endpoints support `offset` and `limit` query parameters:
- Default limit: 50
- Maximum limit: 10000
- Maximum offset: 1000000
- Example: `GET /library/files?offset=100&limit=50`

### Sorting
Library endpoints support `?sort=` parameter for server-side sorting:
- `alpha` (default) - Alphabetical by title+artist
- `artist` - By artist name, then title
- `album` - By album name, then track number
- `title` - By title only
- `date` - By date added (newest first)
- `track` - By disc number, then track number (natural album order)
- `name` - By display name
- `year-asc` - By year ascending (chronological, oldest first)
- Example: `GET /library/files?artist=Pink+Floyd&sort=album`

### Request Limits
- Maximum request body size: 1 MB
- Content-Type must be `application/json` for POST/PUT with body

### CORS Policy
- `localhost`, `127.0.0.1` - Always allowed
- `192.168.x.x`, `10.x.x.x`, `172.16-31.x.x` - Allowed when remote connections enabled
- External origins - Blocked

### Access Control (Read-Only Mode)
MBXHub can restrict write operations via settings:
- **Master read-only**: Disables all write operations API-wide
- **Granular controls**: Player, Queue, Library, Playlists can be individually restricted
- **PartyMode exempt**: PartyMode endpoints always work (voting, requests, etc.)

Blocked requests return:
```json
{"success":false,"error":{"code":"READ_ONLY","message":"API is in read-only mode"}}
```

Handle in code:
```javascript
const res = await fetch('/player/play', {method:'POST'});
if (res.status === 403) {
  const json = await res.json();
  if (json.error?.code === 'READ_ONLY') {
    showMessage('Controls are locked');
  }
}
```

### Security Settings
Key security settings in `mbxhub.json`:
- `apiReadOnlyMode` (default: false) - Master read-only switch. Blocks all write operations API-wide.
- `disableRemoteConfig` (default: false) - Block remote access to settings schema and config updates. Localhost always allowed.
- `protectMetadata` (default: true) - Block metadata writes (love, rate, tag edits) for all users including DJ
- `rateLimitEnabled` (default: true) - Enable rate limiting for PartyMode endpoints
- `rateLimitRequestsPerMinute` (default: 5) - Max song requests per IP per minute
- `rateLimitVotesPerMinute` (default: 5) - Max votes per IP per minute
- `rateLimitPinAttemptsPerMinute` (default: 5) - Max PIN validation attempts per IP per minute
- `trustForwardedFor` (default: false) - Trust X-Forwarded-For header for client IP detection. Only enable if behind a reverse proxy that sets this header.
- `ariaEnabled` (default: false) - ARiA input simulation. When disabled, all /aria endpoints return 403.
- `ariaAllowedPrograms` - Allowlist for ARiA run() command. Only listed programs can be launched. Do not add shell interpreters (cmd.exe, powershell.exe) as they bypass the allowlist.

### IP Filtering
Control which IP addresses can connect when remote connections are enabled:
- `filteringMode` (default: "All") - All (any IP), Range (subnet range), or Specific (whitelist)
- `filterBaseIp` - Base IP for Range mode (e.g., "192.168.1.")
- `filterLastOctetMax` (default: 254) - Max last octet for Range mode
- `filterAllowedIps` - Array of allowed IPs for Specific mode

Example Range mode (allow 192.168.1.1 to 192.168.1.50):
```json
{"filteringMode": "Range", "filterBaseIp": "192.168.1.", "filterLastOctetMax": 50}
```

Example Specific mode (whitelist):
```json
{"filteringMode": "Specific", "filterAllowedIps": ["192.168.1.10", "192.168.1.20"]}
```

### Dashboard Footer Links
Configure which links appear in the dashboard footer via `dashboardFooterLinks` in mbxhub.json:
- `dashboardFooterLinks` (default: null) - Null = built-in defaults (Player, Pages, QR*, RDP*, API*). Array of `{label, url, enabled}` for custom links.
- Conditional visibility: `/system/qr` requires `restEnabled`, `/remoteapp/rdp` requires `remoteAppEnabled` + `!remoteAppApiDisabled`.
- The footer is a dashboard layout section (`footer`) — hide/show and reorder via `dashboardLayout`.

### Dashboard Layout
Configure which dashboard panels are shown, their order, and which are collapsible via `dashboardLayout` in mbxhub.json:
- `order` (default: ["status","search","nowplaying","rating","controls","volume","charms","mood","playlists","toggles","footer"]) - Render order of sections
- `hidden` (default: []) - Section IDs to hide entirely
- `collapseAfter` (default: 5) - First N visible sections always shown; rest go in collapsible group
- `nowPlayingStyle` (default: "full") - Server-side default NP style (see Now Playing Styles)
- `immersiveFadeDelay` (default: 5000, range 0-10000) - Immersive overlay fade delay in ms (0 = always visible)
- `immersiveTextSize` (default: "M") - Now-playing metadata text size. Despite the name, applies to *all* NP styles — not just immersive. Options: S, M, L, XL.
- `statusBarSize` (default: "S") - Status bar size: S (thin, default), M (medium), L (large)
- `searchBarSize` (default: "S") - Search bar size: S (thin, default), M (medium), L (large)
- `controlsSize` (default: "M") - Transport control button size: S, M, L, XL, XXL
- `progressBarSize` (default: "M") - Progress bar thickness: S (4px), M (6px), L (10px)
- `disableVolumeGesture` (default: true) - Disable vertical swipe-on-artwork gesture for volume control. On by default (true) to avoid conflicts with page scroll; horizontal track-skip gestures are unaffected.
- `disableExploreNewWindow` (default: true) - When true, Explore opens in the same tab instead of a new window.

Section IDs: `status` (status bar), `search` (library search), `nowplaying` (track info/artwork), `rating` (stars/ban/love), `controls` (prev/play/next), `volume` (+/-/mute), `playlists` (playlist selector), `toggles` (shuffle/repeat), `mood` (mood/reactions), `charms` (charm bar), `footer` (footer links)

### Now Playing Styles
- `nowPlayingStyle` (default: "full") - Server-side default. Options: `full`, `horizontal`, `noart`, `split`, `immersive`.
- Client-side override: localStorage key `mbxh_np_style` overrides the server default per-device. Header button cycles through all styles.
- `split` — Two-column grid (art left, metadata right). Column ratio configurable via localStorage `mbxh_split_ratio` (default 55, range 40-70).
- `immersive` — Full-bleed album art with gradient overlay and blurred letterbox fill for non-square artwork. Metadata fades in on hover/touch, fades out after delay. Delay configured via server setting `dashboardLayout.immersiveFadeDelay` (default 5000ms, `0` = always visible, range 0 or 1000-10000).
- All styles have zoom-level overrides (67%, 42%, 27%). Split falls back to stacked below 480px. Immersive reduces art height below 400px.
- **Removed in v0.5.2.3**: the `compact` style. Existing configs referencing `compact` gracefully fall back to `full`.

### Dashboard Display Settings
- `hideFileInfo` (default: false) - Hide file format info (codec, sample rate/bitrate) and hi-res badge from the now-playing section. Hi-res badge appears when sample rate exceeds 44.1kHz.
- `hideInfluenceControls` (default: false) - Hide thumbs up/down influence buttons in the now-playing section.
- `hideStatusMessage` (default: false) - Hide the status bar message after dashboard actions.
- `disableExploreButton` (default: false) - Hide the dashboard transport's extra button entirely (the slot to the right of Now Playing). When false, the button renders the target named by `extraTransportButton`.
- `extraTransportButton` (default: `"explore"`, **v0.5.2.6+**) - What the dashboard transport's extra button targets. Resolution: matches a loaded charm id → renders that charm (icon from `expand[0].icon`, action from `expand[0].action`); contains `/` or starts with `http` → URL fallback (renders ↗ glyph, dispatches as `webapp <url>`); empty/blank → falls back to `"explore"`. Examples: `"explore"` (default — Explore charm), `"/pages/play.html"` (player page), `"/pages/browse.html"` (browse page), or any charm id from the registry. Configured via WinForms Dashboard tab or the web settings page (auto-rendered from schema).
- `hideSearchMoods` (default: false) - Hide mood quick-picks from search empty state. Moods section is also collapsible via click.

### Dashboard Search Behavior
- Client-side fuzzy album/artist matching with server-side track search via `GET /library/search?q=`
- Tabs: All, Artists, Albums, Tracks, Playlists. Tab ordering auto-sorts by best fuzzy-score match so the most relevant tab (e.g. Tracks for a song title) floats to the front.
- Playlists tab uses the `p:` prefix filter against cached playlist names. Play/queue-next/queue-last actions via `POST /dashboard/playlist` (form: `playlistUrl=...`).
- Albums tab also runs server-side search and boosts albums containing matching tracks (e.g. searching "wonderwall" surfaces the album)
- Album results have inline track expansion (☰ Tracks button) showing numbered tracklist with per-track play/queue
- Explore button on results opens explore.html seeded with `?album=&artist=` query params
- Empty state shows collapsible mood pills and search history
- Track result rows show `Title — Artist` when the track artist differs from the album artist (same convention in browse.html and explore.html expanded views)

- `disableGuestQr` (default: false) - Hide QR code from guest/party mode dashboard.
- `disableHostQr` (default: false) - Hide QR code from host dashboard.

### Feature Disable Settings
Disable specific API features. When disabled, related endpoints return 404. Feature state (except proxy) is exposed via `GET /system/features`.
- `apiDisableBanlist` (default: false) - Disable ban list endpoints (`/banlist/*`).
- `apiDisableRatings` (default: false) - Disable rating controls (`/dashboard/rate/*`, `/dashboard/love`).
- `apiDisableLoved` (default: false) - Disable love/heart tag feature.
- `apiDisableReactions` (default: false) - Disable reactions/mood feature.
- `apiDisableProxy` (default: false) - Disable device proxy endpoint (`POST /api/proxy`).
- `disableStreaming` (default: false) - Disable audio/video streaming endpoint (`GET /stream/*`).

### MBXHub Shell (MBXHub.exe)
**Optional.** The plugin (`mb_MBXHub.dll`) is fully functional on its own &mdash; REST, WebSocket, dashboard, AutoQ, charms, and discovery all work without the Shell. The Shell adds Windows-side conveniences: SMTC (System Media Transport Controls) integration, a system-tray UI for switching SMTC targets and opening dashboards across the fleet, Windows app identity (AUMID, Start Menu shortcut), and a firewall helper that adds / removes the Windows Firewall rule and URL ACL on `--install` / `--uninstall`.

The Shell binds the SMTC bridge on `restPort + 1` (default 8081). **Local use** (Shell and plugin on the same box) needs no firewall config &mdash; loopback traffic passes through. **Remote use** (Shell on one machine bridging to MBXHub on another) needs the SMTC port open on the machine hosting the Shell, so the remote dashboard can reach `/meta/smtc/*`. `MBXHub.exe --install` opens it for you.

Plugin setting in `mbxhub.json`:
- `startShellOnStartup` (default: false) - Launch MBXHub.exe when MusicBee starts. Plugin stops it on exit.

Shell config in `mbxhub-shell.json` (next to MBXHub.exe):
- `host` (default: "127.0.0.1") - MBXHub REST API host
- `port` (default: 8080) - MBXHub REST API port
- `wsPort` (default: 8080) - WebSocket port
- `smtc.enabled` (default: true) - Enable SMTC bridge (false for headless/NAS)
- `smtc.positionUpdateIntervalMs` (default: 1000) - Local SMTC timeline-update timer cadence. 0 disables the local timer (timeline still updates on incoming WS push). 1-999 clamps up to 1000; 1000-60000 working range; >60000 clamps down. Raise to 5000+ for bluetooth-coexistence/low-bandwidth setups.
- `smtc.throttleMs` (default: 0, **v0.5.2.6+**) - Audit MED #14 throttle: minimum interval (ms) between SmtcBridge.UpdateTimelineProperties marshals triggered by incoming WS PositionChanged. 0 = no throttle (every WS frame hits SMTC). Set on the Shell side because the throttle decision is made where the STA marshal happens.
- `retryIntervalMs` (default: 3000) - Retry interval on connection loss (ms)
- `connectTimeoutMs` (default: 5000) - Connection timeout (ms)
- `logLevel` (default: "Info") - Log verbosity: Trace, Debug, Info, Warn, Error
- `logFile` (default: "mbxhub-shell.log") - Log file path (empty to disable)
- `logDebugOutput` (default: false) - Write to debug output (DebugView/VS Output)
- `debug` (default: false) - Debug mode: smaller log files, more archives

Features: AUMID (`HALRAD.MBXHub`), auto-reconnect, single-instance enforcement. Uninstalling MBXHub via MusicBee cleans up AUMID, Start Menu shortcut, and Apps & Features entry. Requires .NET 8.0 Desktop Runtime.

#### MBXHub.exe CLI
- `MBXHub.exe` (no args) - Start SMTC bridge mode
- `MBXHub.exe status` - Show system health and tool discovery status
- `MBXHub.exe --no-smtc` - Run without SMTC bridge (headless/NAS mode)
- `MBXHub.exe --install` - Register AUMID, create Start Menu shortcut, enable startup, report tool discovery
- `MBXHub.exe --uninstall` - Remove AUMID registration, shortcut, and startup entry
- `MBXHub.exe startup --enable` - Register auto-start at Windows logon (HKCU Run key, visible in Settings > Apps > Startup)
- `MBXHub.exe startup --disable` - Remove auto-start registration
- `MBXHub.exe shutdown` - Gracefully close all running Shell instances
- `MBXHub.exe --detect` - Detect MusicBee installations
- `MBXHub.exe --version` - Show version information
- `MBXHub.exe --help` - Show help

#### MBXHub.exe firewall
Windows Firewall configuration (replaces standalone firebug.exe). Self-elevates via UAC when needed.
- `MBXHub.exe firewall add --name MBXHub --tcp 8080,8081 --udp 1900,3702,5353 --urlacl 8080,8081` - Add firewall rules and URL ACL for the REST port + Shell SMTC port (8081 = REST + 1) plus discovery (UPnP / WS-Discovery / mDNS). This is what the plugin's Settings → Firewall panel writes.
- `MBXHub.exe firewall add --name MBXHub --port 8080 --urlacl` - Add single-port rule with URL ACL
- `MBXHub.exe firewall remove --name MBXHub --port 8080` - Remove firewall rules and URL ACL
- `MBXHub.exe firewall check --name MBXHub --port 8080` - Check if rules exist
- `MBXHub.exe firewall status` - Show firewall and elevation status
- `MBXHub.exe firewall open` - Open Windows Firewall settings UI

Note: `MBXHub.exe --install` writes a separate `MBXHub-Shell` rule + URL ACL for `smtc.port` (default 8081) automatically; `--uninstall` removes it. The `firewall add` commands above are for managing the plugin's combined rule by hand or for non-default port layouts.

### SMTC Target Switching
Runtime SMTC target management — discover MBXHub endpoints on the network and switch which one the Shell mirrors.

**Served by the Shell (`MBXHub.exe`), not the plugin.** Listens on `smtc.port` from `mbxhub-shell.json`, default `8081` (REST port + 1). Cross-origin requests are allowed (`Access-Control-Allow-Origin: *` + OPTIONS preflight) so browser pages served by the plugin on 8080 can call directly.

- `GET http://<host>:8081/meta/smtc/target` - Current SMTC target (host:port) and connection state
- `PUT http://<host>:8081/meta/smtc/target` - Switch SMTC target. Body: `{"target":"host:port"}`. Tears down existing WS connection, updates config, reconnects to new endpoint.
- `GET http://<host>:8081/meta/smtc/endpoints` - Cached list of discovered MBXHub endpoints on the network. Each entry: address, name, active (boolean), capabilities. Returns 503 if SMTC bridge unavailable.
- `POST http://<host>:8081/meta/smtc/endpoints/refresh` - Clear cache and re-scan network via SSDP for MBXHub endpoints. Returns fresh endpoint list.

### REST vs RPC
- Use REST for client apps, clean URLs, resource-oriented design
- Use RPC (`POST /rpc/{methodName}`) for direct MusicBee API access, automation scripts

### Real-time Updates
- Use REST for commands (play, pause) and queries (get queue, search)
- Use WebSocket for real-time UI updates, progress bars, visualizations

### AutoQ Availability
Shuffle, banlist, and influence endpoints require TrueShuffle or AutoQ to be enabled:
- Returns `503 SERVICE_UNAVAILABLE` if TrueShuffle/AutoQ not enabled
- Check with `GET /shuffle/status`

## Anatomy of a Player

Common UI regions and the endpoints that power them:

### Now Playing Panel
Current track display - artwork, title, artist, album
- `GET /nowplaying` - Track metadata
- `GET /nowplaying/artwork` - Album art
- `GET /nowplaying/lyrics` - Lyrics (if available)
- WebSocket `TrackChanged` event - Live updates on track change

### Transport Controls
Play, pause, stop, next, previous buttons
- `POST /player/play`
- `POST /player/pause`
- `POST /player/playpause` - Toggle
- `POST /player/stop`
- `POST /player/next`
- `POST /player/previous`
- WebSocket `PlayStateChanged` event - Button state updates

### Progress / Seek Bar
Position slider, elapsed time, total duration
- `GET /nowplaying/position` - Current position
- `PUT /player/position` - Seek to position
- WebSocket `PositionChanged` event - Live position updates (see seek bar sample code)

### Volume Control
Volume slider, mute button
- `GET /player/volume` - Current volume (0-100)
- `PUT /player/volume` - Set volume
- `GET /player/mute` - Mute state
- `PUT /player/mute` - Toggle mute
- WebSocket `VolumeChanged` event - Live updates

### Mode Controls
Shuffle toggle, repeat cycle, AutoDJ
- `GET /player/shuffle` - Shuffle state (true/false)
- `PUT /player/shuffle` - Set shuffle (body: {"shuffle":true/false})
- `GET /player/autodj` - AutoDJ state
- `POST /player/autodj/start` - Start AutoDJ
- `POST /player/autodj/stop` - Stop AutoDJ
- `GET /player/repeat` - Repeat mode (off/all/one)
- `PUT /player/repeat` - Set repeat (body: {"repeat":"off|all|one"})
- WebSocket `ShuffleChanged` ({enabled:bool}), `RepeatChanged` events

### Dashboard Pages
- `GET /dashboard` - Main dashboard page (HTML). Redirects to default page if configured.
- `GET /dashboard/theme` - Switch theme mode (query: `?mode=1|2`). Saves to settings and broadcasts ThemeChanged WebSocket event.

### Dashboard Transport (SSR form POSTs)
- `POST /dashboard/play` - Play
- `POST /dashboard/pause` - Pause
- `POST /dashboard/stop` - Stop
- `POST /dashboard/next` - Next track
- `POST /dashboard/previous` - Previous track (alias: `/dashboard/prev`)
- `POST /dashboard/shuffle` - Toggle shuffle
- `POST /dashboard/shuffle-off` - Shuffle off
- `POST /dashboard/autodj` - Toggle AutoDJ
- `POST /dashboard/repeat` - Cycle repeat mode

### Dashboard Volume
- `POST /dashboard/volup` - Volume +5%
- `POST /dashboard/voldown` - Volume -5%
- `POST /dashboard/volup1` - Volume +1% (fine)
- `POST /dashboard/voldown1` - Volume -1% (fine)
- `POST /dashboard/mute` - Toggle mute
- Keyboard: / (search), Arrow Up/Down (1%), Shift+Arrow (5%), M (mute)

### Rating / Love / Ban
Star rating (1-5), bomb (0=don't play), love/heart, ban from shuffle
- `POST /dashboard/rate/0` - Toggle bomb (don't play). Click on, click off
- `POST /dashboard/rate/1-5` - Toggle star rating. Click to set, click same to clear
- `POST /dashboard/love` - Toggle love tag
- `POST /dashboard/setban` - Set ban flag without skipping
- WebSocket `MetadataChanged` event for changes

### AutoQ Mood & Reactions
Mood-based track selection and user reactions
- `POST /dashboard/mood` (form: mood=Energetic) - Set mood channel
- `POST /dashboard/react/fire|heart|like|dislike` - Submit reaction
- `POST /dashboard/ban` - Ban current track (skip + add to banlist)
- `POST /dashboard/refresh-queue` - Refresh vibe list and queue tracks
- `POST /dashboard/influence/artist|genre/up|down` - Thumbs up/down for artist or genre
- Fire reaction triggers immediate queue refresh

### Queue / Up Next
List of upcoming tracks
- `GET /queue` - Full queue with pagination
- `GET /queue/current` - Current track index
- `POST /queue/add` - Add track (next or last)
- `DELETE /queue/{index}` - Remove track
- `POST /queue/move` - Reorder
- WebSocket `QueueChanged` event - Queue changes

### Library Browser
Browse by artist, album, genre
- `GET /library/artists` - Artist list
- `GET /library/albums` - Album list (filter by artist)
- `GET /library/albums/detailed` - Albums with firstTrackUrl (for artwork, avoids N+1)
- `GET /library/albums/unheard` - Unplayed albums
- `GET /library/albums/with-pdf` - Albums with PDF booklets
- `GET /library/genres` - Genre list
- `GET /library/inbox` - Inbox files (shown in browse only if non-empty)
- `GET /library/audiobooks` - Audiobook files (shown in browse only if non-empty)
- `GET /library/videos` - Video files (shown in browse only if non-empty)
- `GET /library/files` - Track list (filter by artist/album/genre)
- `GET /library/search?q=` - Search (strict word-boundary by default; `&substring=true` for loose matching)

### Playlists Panel
List and manage playlists
- `GET /playlists` - All playlists
- `GET /playlists/{url}/files` - Tracks in playlist
- `POST /playlists/{url}/play` - Play playlist
- `POST /playlists` - Create new
- `POST /dashboard/playlist` - Play or queue a playlist from the dashboard (form: playlistUrl=...)

### Status Bar
Connection status, server info
- `GET /ping` - Health check
- `GET /system/version` - Version info
- WebSocket connection state

## Sample Code (player.html patterns)

### Fetch Now Playing
```javascript
async function getNowPlaying() {
  const res = await fetch('/nowplaying');
  const json = await res.json();
  if (json.success) {
    document.getElementById('title').textContent = json.data.title;
    document.getElementById('artist').textContent = json.data.artist;
    document.getElementById('album').textContent = json.data.album;
  }
}
```

### Display Artwork
```javascript
document.getElementById('artwork').src = '/nowplaying/artwork?' + Date.now();
```

### Player Controls
```javascript
async function play() { await fetch('/player/play', {method:'POST'}); }
async function pause() { await fetch('/player/pause', {method:'POST'}); }
async function next() { await fetch('/player/next', {method:'POST'}); }
async function prev() { await fetch('/player/previous', {method:'POST'}); }
async function setVolume(v) {
  await fetch('/player/volume', {
    method:'PUT',
    headers:{'Content-Type':'application/json'},
    body:JSON.stringify({volume:v})
  });
}
```

### WebSocket Live Updates
```javascript
const ws = new WebSocket('ws://' + location.host + '/ws');
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  switch(msg.event) {
    case 'TrackChanged':
      document.getElementById('title').textContent = msg.data.title;
      document.getElementById('artwork').src = '/nowplaying/artwork?' + Date.now();
      break;
    case 'PlayStateChanged':
      updatePlayButton(msg.data.state);
      break;
    case 'PositionChanged':
      updateProgress(msg.data.position, msg.data.duration);
      break;
    case 'VolumeChanged':
      updateVolumeSlider(msg.data.volume);
      break;
  }
};
```

### Browse Library
```javascript
async function getArtists() {
  const res = await fetch('/library/artists?limit=100');
  const json = await res.json();
  return json.data; // array of artist names
}

async function getAlbumsByArtist(artist) {
  const res = await fetch('/library/albums?artist=' + encodeURIComponent(artist));
  const json = await res.json();
  return json.data; // array of album objects
}

async function searchLibrary(query) {
  const res = await fetch('/library/search?q=' + encodeURIComponent(query));
  const json = await res.json();
  return json.data; // array of track objects
}
```

### Queue Management
```javascript
async function addToQueue(url, position='last') {
  await fetch('/queue/add', {
    method:'POST',
    headers:{'Content-Type':'application/json'},
    body:JSON.stringify({url:url, position:position})
  });
}

async function playNow(url) {
  await fetch('/queue/playnow', {
    method:'POST',
    headers:{'Content-Type':'application/json'},
    body:JSON.stringify({url:url})
  });
}
```

### Playlists - File vs URL Paths
```javascript
// GOTCHA: Playlist URLs from API are file paths, must be encoded for use in URLs

// Get all playlists
async function getPlaylists() {
  const res = await fetch('/playlists');
  const json = await res.json();
  return json.data; // [{name:'My Playlist', url:'C:\\Users\\...\\My Playlist.m3u'}, ...]
}

// Get tracks in a playlist - MUST encode the path
async function getPlaylistTracks(playlistUrl) {
  // playlistUrl is a Windows path like 'C:\Users\...\My Playlist.m3u'
  const encoded = encodeURIComponent(playlistUrl);
  const res = await fetch('/playlists/' + encoded + '/files');
  const json = await res.json();
  return json.data; // array of file paths
}

// Play a playlist
async function playPlaylist(playlistUrl) {
  const encoded = encodeURIComponent(playlistUrl);
  await fetch('/playlists/' + encoded + '/play', {method:'POST'});
}

// Add tracks to playlist - tracks are also file paths
async function addToPlaylist(playlistUrl, trackUrls) {
  const encoded = encodeURIComponent(playlistUrl);
  await fetch('/playlists/' + encoded + '/files', {
    method:'POST',
    headers:{'Content-Type':'application/json'},
    body:JSON.stringify({urls:trackUrls}) // trackUrls are file paths, not encoded here
  });
}

// Create a playlist - returns the new playlist's file path
async function createPlaylist(name) {
  const res = await fetch('/playlists', {
    method:'POST',
    headers:{'Content-Type':'application/json'},
    body:JSON.stringify({name:name})
  });
  const json = await res.json();
  return json.data.url; // file path to new playlist
}

// Key insight:
// - In URL path: encode with encodeURIComponent()
// - In JSON body: use raw file paths (no encoding)
```

### Love/Unlove Toggle (RatingLove)
`/dashboard/love` toggles the RatingLove tag on the now-playing track. No request body.
```javascript
let loved = false;

async function toggleLove() {
  await fetch('/dashboard/love', { method: 'POST', headers: { 'Content-Length': '0' } });
  loved = !loved;
  document.getElementById('love-btn').classList.toggle('loved', loved);
}

// Sync from now-playing on connect / track change
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.event === 'TrackChanged') {
    fetch('/nowplaying').then(r => r.json()).then(j => {
      loved = j.success && (j.data.ratingLove === 'L' || j.data.ratingLove === true);
      document.getElementById('love-btn').classList.toggle('loved', loved);
    });
  }
};
```

### 3-Way Shuffle Toggle (off → shuffle → autodj → off)
Shuffle is a boolean. AutoDJ is a separate mode with its own endpoints.
```javascript
let shuffleEnabled = false;
let autoDjEnabled = false;

// Determine current mode from player status
async function loadShuffleState() {
  const res = await fetch('/player/status');
  const json = await res.json();
  shuffleEnabled = json.data.shuffle;
  autoDjEnabled = json.data.autoDj;
  updateShuffleButton();
}

// Cycle: off → shuffle → autodj → off
async function cycleShuffle() {
  if (!shuffleEnabled && !autoDjEnabled) {
    // off → shuffle
    await fetch('/player/shuffle', {
      method:'PUT',
      headers:{'Content-Type':'application/json'},
      body:JSON.stringify({shuffle:true})
    });
  } else if (shuffleEnabled && !autoDjEnabled) {
    // shuffle → autodj
    await fetch('/player/autodj/start', {method:'POST'});
  } else {
    // autodj → off
    await fetch('/player/autodj/stop', {method:'POST'});
    await fetch('/player/shuffle', {
      method:'PUT',
      headers:{'Content-Type':'application/json'},
      body:JSON.stringify({shuffle:false})
    });
  }
  // Don't update local state - wait for WebSocket confirmation
}

function updateShuffleButton() {
  const btn = document.getElementById('shuffle-btn');
  const mode = autoDjEnabled ? 'autodj' : shuffleEnabled ? 'shuffle' : 'off';
  btn.className = 'shuffle-' + mode;
  btn.title = mode === 'off' ? 'Shuffle Off' : mode === 'shuffle' ? 'Shuffle' : 'AutoDJ';
}

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.event === 'ShuffleChanged') {
    shuffleEnabled = msg.data.enabled;
    updateShuffleButton();
  }
};
```

### Seek Bar with Position Updates
```javascript
let duration = 0;
let position = 0;
let isSeeking = false; // Prevent WebSocket updates while user is dragging

const seekBar = document.getElementById('seek-bar');

// User starts dragging
seekBar.addEventListener('mousedown', () => { isSeeking = true; });
seekBar.addEventListener('touchstart', () => { isSeeking = true; });

// User releases - send seek command
seekBar.addEventListener('mouseup', doSeek);
seekBar.addEventListener('touchend', doSeek);

async function doSeek() {
  isSeeking = false;
  const newPos = Math.round((seekBar.value / 100) * duration);
  await fetch('/player/position', {
    method:'PUT',
    headers:{'Content-Type':'application/json'},
    body:JSON.stringify({position:newPos})
  });
}

// WebSocket position updates - ignore while seeking
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.event === 'PositionChanged' && !isSeeking) {
    position = msg.data.position;
    duration = msg.data.duration;
    seekBar.value = duration > 0 ? (position / duration) * 100 : 0;
    document.getElementById('time-current').textContent = formatTime(position);
    document.getElementById('time-total').textContent = formatTime(duration);
  }
  if (msg.event === 'TrackChanged') {
    duration = msg.data.duration || 0;
    position = 0;
    seekBar.value = 0;
  }
};

function formatTime(ms) {
  const s = Math.floor(ms / 1000);
  const m = Math.floor(s / 60);
  return m + ':' + String(s % 60).padStart(2, '0');
}
```

## Further Reading

These docs are fetchable from a running MBXHub instance. Read them for complete details.

### GET /docs - Full API Reference (alias: `/api`)
Complete documentation for all 175+ endpoints with:
- Request/response examples for every endpoint
- Query parameters and body schemas
- Error codes and responses
- Integration notes and best practices
**Read when:** You need exact parameter names, response shapes, or edge cases

### GET /aria - ARiA Automation Guide
Remote input simulation and automation:
- DuckyScript syntax for keyboard macros
- Preset configuration (JSON format)
- Wake-on-LAN for sleeping PCs
- MusicBee hotkey integration
- Security considerations
**Read when:** Building automation, macros, or remote wake features

### GET /changelog - Version History
Release notes for all versions:
- New features and endpoints
- Breaking changes
- Bug fixes
**Read when:** Checking what's new or if an endpoint exists in current version

### GET /pages/player.html - Working Example
Full source code of the included web player with all JS inline:
- 3-column responsive layout (browse, now playing, queue)
- All fetch() calls, WebSocket handling, state management
- Browse iframe with theme sync via postMessage
- Drag-drop queue reorder with touch support
**Read when:** You want to see how something is implemented or need working code to copy/adapt

## Website

- https://mbxhub.com - Latest releases and downloads
- https://mbxhub.com/features.html - Feature overview with screenshots
- https://mbxhub.com/api.html - API docs (same as /docs)