# MBXHub API

> MusicBee REST API - v0.5.5.0
>
> llms.txt specification: https://llmstxt.org/
> Requires MusicBee 3.5+ (API rev 57). 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`

## Authentication

- Optional HTTP Basic password gate (off by default). When enabled, remote requests need `Authorization: Basic <base64 of user:password>` (username ignored). Missing or invalid returns `401` with `WWW-Authenticate: Basic realm="MBXHub"`.
- Exempt from the gate: localhost, the `/ws` event stream, and the live-PartyMode surface (guests use the `X-Party-PIN` header instead).
- Configured only in the plugin (Remote Connection Settings -> Configure Access -> Remote Access); not web/API-configurable. A speed bump for trusted LANs, not transport security: without HTTPS the password is sent base64 (effectively cleartext) on every request.

## 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. When the playing file's Comment carries a time-coded setlist (SL-TPS v1.0), skips to the next setlist entry's `startMs` instead of the next queue file; from the last entry falls through to `Player_PlayNextTrack`. Response carries `scope: "setlist"` + `entryIndex` on setlist hits.
- `POST /player/previous` - Previous track. Setlist-aware. Within 2s of an entry's start it seeks to the previous entry's `startMs`; after 2s it restarts the current entry. From the first entry within the 2s grace it falls through to `Player_PlayPreviousTrack`. Setlist lookup is cached for 2s so consecutive presses don't re-parse the Comment.
- `GET /player/volume` - Get volume (0-100)
- `PUT /player/volume` - Set volume (body: {"volume":50} absolute, or {"delta":-5} relative — resolved server-side, clamped 0-100)
- `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. `type` is one of `devialet` (Phantom), `streamsdk` / `fosi` (StreamUnlimited StreamSDK, e.g. Fosi Audio S3) or `linkplay` / `wiim`
- `POST /devices/endpoints` - Add a network endpoint (body: {"ip":"192.168.1.50","type":"devialet","name":"Living Room"}). `type` chooses the wire dialect — devialet | streamsdk | fosi | linkplay | wiim. Reachability is probed with that dialect before the endpoint is stored, and an unknown type is refused 400 UNKNOWN_TYPE rather than saved as an endpoint nothing can reach
- `POST /devices/endpoints/scan` - LAN discovery scan; bodyless (Content-Length: 0); ~4s blocking. `?protocol=mdns|ssdp|all` (default mdns): mdns sweeps speaker service types, ssdp sweeps UPnP MediaRenderer:1 (WiiM/LinkPlay, Sonos, TVs). Returns [{name, ip, port, hostName, serviceType, alreadyConfigured, existingId, protocol}]; ssdp rows add {model, manufacturer, location}. A row whose `manufacturer` is recognised also carries `kind` (devialet | streamsdk | linkplay - the wire dialect that drives it) and `kindSource` (which rule fired, for diagnosis). Derived from the UPnP description the scan already fetched, so identification adds no request and no probe. An unrecognised device OMITS both fields rather than guessing - absent means unknown, and a human still picks the type. Exact manufacturer match only, never fuzzy: a near-miss abstains rather than producing a confident wrong answer
- `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}). A speaker that does not answer is refused `502 ENDPOINT_UNREACHABLE` rather than reported as set - this route acts on the named endpoint directly and does NOT soft-fall-back to the player the way `/mixer/volume` does
- `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. `defaultFader`, `pollIntervalMs`, `defaultEndpointId` (what is stored) and `defaultEndpointResolved` ({id,name,type,ip} or null — the endpoint the endpoint fader would actually act on right now, fallback already applied)
- `PUT /mixer/settings` - Set mixer settings (body: {"defaultFader":"device"}). `defaultEndpointId` names which configured endpoint the `endpoint` fader acts on; empty string = first in the list. An id matching no endpoint is refused 400 UNKNOWN_ENDPOINT
- `GET /mixer/volume` - Get volume from default fader (player, device, or endpoint). Endpoint mode resolves `mixer.defaultEndpointId`, falling back to the first configured entry in `endpoints[]`; soft-falls-back to player if none configured or the speaker is unreachable
- `PUT /mixer/volume` - Set volume on default fader. Absolute (body: {"volume":50}) or relative (body: {"delta":-5}), the delta resolved server-side against the active fader's current level — same contract as `/player/volume`, so a first press works before any read has landed and two quick presses cannot race a stale read. Response surfaces the actual `fader` that was hit (matters when endpoint mode falls back to player)
- `GET /mixer/mute` - Mute state of the default fader, resolved exactly as `/mixer/volume` is, so volume and mute always land on the same device. `fader` is the one actually hit
- `PUT /mixer/mute` - Set mute on the default fader (body: {"mute":true}), or {"toggle":true} to invert whatever the current fader reports without a read-then-write round trip

### Streaming
- `POST /player/update-play-statistics` - Apply a caller-chosen count type to a track (body: {"url","countType"?,"disableScrobble"?}; countType: IncreasePlayCount / IncreaseSkipCount / NoChange). Prefer `/player/report-play`, which judges played vs skipped server-side. 403 FEATURE_DISABLED when `apiDisablePlayCountUpdates` is on; gated by player access during party mode; shares the per-IP play-stat rate limit with `/player/report-play`
- `POST /player/report-play` - Report a Listen Here (browser streaming) playback exit (body: {"url","positionMs","durationMs","cueStartMs"?,"cue"?,"abandoned"?,"disableScrobble"?}). `cue: true` marks a CUE-backed source - required for a sheet's FIRST sub-track, whose cueStartMs is 0. Server applies MusicBee's own play-count trigger settings (percent/seconds, read live) and increments play or skip count via the MusicBee API; position 0 records nothing. `abandoned: true` marks a non-deliberate exit (tab close, output toggle, external track change): past threshold it still counts a play, below it nothing is recorded — never a fabricated skip. Counted plays also feed the AutoQ session signal and (when TrueShuffle is enabled) the shuffle played-set + AutoReset completion check — neither feature is required for counting. Duplicate reports from the same client for the same track (keyed url+cueStartMs, so CUE sub-tracks of one file never collide) inside an adaptive window are ignored (`deduped: true`). When `durationMs` is omitted or 0 the server derives it from the CUE sheet for sub-tracks (next track start − this start; the sheet's last track has no derivable end, so only the seconds rule can count it as a play and no skip is ever fabricated) or the library duration for whole files. Play-stat endpoints share a per-IP rate limit (`rateLimitPlayStatsPerMinute`, 429 when exceeded; loopback exempt). 404 if file not in library or `apiDisablePlayReporting`/`apiDisablePlayCountUpdates` is on

## Now Playing

- `GET /nowplaying` - Current track metadata
- `GET /nowplaying/artwork` - Album art (binary image)
- `GET /nowplaying/lyrics` - Track lyrics. Response: `{ hasLyrics, lyrics, source?, label?, comment? }`. `source` is `"lyrics"` (MusicBee field) or `"comment"` (fallback to the track Comment tag when no real lyrics exist). When `source: "lyrics"` and the track also has a non-empty Comment tag, an additional `comment` field is included so clients can offer a Lyrics/Comment toggle. When `source: "comment"`, `label` is the chip text shown above the body (default "from comment"). Both the sibling `comment` field and the fallback path are truncated to `LyricsFallback.MaxDisplayChars` (default 4000). Configurable via `LyricsFallback.{Enabled, MaxDisplayChars, Label}`; hard-killable via `ApiDisableLyricsFallback` (also suppresses the `comment` field).
- `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). Each track has an optional `provenance:{driver,reason,whenUtc}` (driver: AutoQ|TrueShuffle|Journey|Station|Manual) stamping who filled it and why; omitted when unknown (older fills / manual MB adds)
- `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
- `GET /nowplaying` also returns `cueTrack` + `cueStartMs` for the current track; browser-mode clients seek the container to `cueStartMs` and pass it through to `/player/report-play`

### 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=&people=&offset=&limit=&sort=). `?people=X` on an album-scoped query (`&album=Y`) now post-filters across MB's full role-union — `Artists` (144 — Artist + Performer + Guest + Remixer), `Composer` (43), and `Conductor` (45). This catches feat./guest credits that MB's `ArtistPeople` XmlFilter omits from the Guest role bucket (e.g. David Guetta - "The Whisperer (feat. Sia)" where Sia is tagged GuestArtist). Whole-library `?people=` without `?album=` still uses `ArtistPeople` for speed and continues to miss pure-guest credits. Additional params: `?include=<TagName>` attaches per-track value of a tag for display (e.g. the active sort field when expanding an album under a custom-* sort) — accepts any tag from the 48-tag customSorts allowlist (`Custom1`..`Custom16`, `Virtual1`..`Virtual25`, `Year`, `OriginalYear`, `Sort*`); unknown values silently ignored. Each returned row gets `extraField` + `extraValue` when set. `?roles=true` adds every per-track role-credit field MB tracks separately — `artistsRole`, `performers`, `guests`, `remixers`, `composers`, `conductors`, `artistsUnion` — populated raw from `Library_GetFileTag`. Default off; only paid for when requested. `?setlist=hint` emits a `hasSetlist:bool` per row — true when that track's Comment tag matches the time-coded setlist heuristic (≥3 monotonically increasing entries; see `/library/file/{urlHash}/setlist` for the full accepted-formats grammar, SL-TPS v1.0). Drives the SET LIST badge on the dashboard and the Tracklist tab on `nowplaying.html`. Opt-in to pay the per-row Comment + regex cost; default off. `?sort=year` (and the year/date track sorts on album expansion) extract the 4-digit year from malformed Year tags before sorting — full dates like `20180727`, `2024-01-01`, `5/27/2014`, `1999/2000` sort by their year component instead of as integers ten million high. Sort key only; stored tags and displayed values untouched. Toggle off with the **Disable malformed-Year sort normalization** Advanced setting.
- `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. Each album row includes `virtualKind` (`"cue"` | `"setlist"` | `null`) indicating whether the album is a CUE-split or setlist virtual tracklist.
- `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). Each album row includes `virtualKind` (`"cue"` | `"setlist"` | `null`).
- `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/albums/with-video` - Albums whose folder contains a video file (derived from the Video library, Source Type 64, matched by folder) (?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" (including 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=`. 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`. 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` - Returns the DSL grammar as JSON (qualifiers, operators, worked examples). Response shape: `{version, qualifiers:[{name, type, allowsRange, allowsOperators, filterable, mapping, enumValues}], operators:[{symbol, description}], examples:[{query, description}]}`. `filterable` (bool) marks the qualifiers the AutoQ candidate filter can evaluate — a filter-scoped client derives its allow-list from this flag rather than hardcoding one. 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** (22 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` |
| `arousal:` | float | range + ops | AutoQ arousal (energy axis) | 0–1. `arousal:>0.7`, `arousal:0.7..1.0`. SMFM contributes the same axis as a 2nd source. **Post-filter** |
| `valence:` | float | range + ops | AutoQ valence (bright/dark axis) | 0–1. `valence:<0.4`. **Post-filter** |
| `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 |
| `type:` | string | — | file extension | **Post-process** — exact, case-insensitive match on the file extension (`type:flac`, `type:mp3`). Dot optional. Combine formats with `OR` |
| `key:` | string | — | Camelot mix key | **Post-process** — exact, case-insensitive match on the track's Camelot code from the mood cache (`key:9A`, `key:11B`). Scanned tracks only — no key data never matches. Combine wheel-compatible codes with `OR` |
| `lyric:` | string | — | lyrics body | **Post-process**, expensive. Gated on `library.search.dsl.allowLyricSearch = true` (default off) |

**Any-field / custom slots**: beyond the 21 named qualifiers above, the field registry covers every MusicBee custom slot — `custom1:`…`custom20:` translate to a `Field="CustomN"` condition (e.g. `custom7:live`; Custom17-20 arrived with MusicBee 3.5). Combine with existing qualifiers as usual (`albumartist:"various" custom7:live`). These dynamic slots are NOT listed by `GET /library/search/syntax` (which returns only the 21 static qualifiers). Mood-position search uses the first-class `arousal:`/`valence:` range qualifiers (above), which filter on the AutoQ V/A; SMFM contributes the same axes as a second source.

**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.
- **Where a grouped query runs.** A query that is ONLY a group (`genre:rock OR genre:metal`) is handed to MusicBee's engine whole and runs there. A group placed BESIDE another condition (`artist:davis (genre:rock OR genre:jazz)`) is evaluated in the post-filter instead: MusicBee silently drops the sibling condition when a group sits next to it — measured 2026-08-18 on a ~7.5k library, where `artist:davis` alone matched 0 tracks yet `(genre:rock OR genre:jazz) artist:davis` returned 3385. Same results either way; the difference is that the post-filter path is capped, so a query producing more candidates than `library.search.dsl.maxPostFilterCandidates` answers `413 POST_FILTER_CAP_EXCEEDED` instead of quietly returning the wrong set. Add a selective condition, or write the group on its own.
- 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=` - 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, the dashboard search bar, player.html, browse.html, and explore.html. **DSL routing:** 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. Backstop: same `search.live.minQueryLength` (default 2) check as `/library/search` — short queries return `400 QUERY_TOO_SHORT`. Per-bucket `?limit=` caps at 500 so browse.html's client-side aggregation gets the full intended slice.
- `GET /system/search-index` - Live engine + index state snapshot. Currently reports `engine:"mb"` (the seam is preserved for future search 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.
- `GET /library/no-artwork` - MusicBee's placeholder image for tracks with no artwork (binary). Cache-Control: 24h.
- `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}/videos` - List video files in the track's album folder (+ one subdir level). Filters by extension: `.mp4`, `.mkv`, `.webm`, `.mov`, `.m4v`, `.avi`. Returns `{folder, videos: [{path, name, sizeBytes}], count}`. Drives the Video tab on `nowplaying.html` Extras and the Videos section on `explore.html` expanded album view. Security: track must be in MusicBee library.
- `GET /library/video/{path}` - Serve a single video file by absolute path (binary, Content-Type by extension: video/mp4, video/x-matroska, video/webm, video/quicktime, video/x-msvideo). Same library-scope check as `/library/fan-art/{path}` — the path's directory (or its parent) must contain at least one 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/file/{urlHash}/setlist` - Returns the parsed time-coded set list embedded in a track's Comment tag. Response: `{ fileUrl, fileDurationMs, entries:[{index, startMs, title, rawTime, cueTime}], trailingNotes, parsedAt, extractedCueExists, extractedCuePath }`. Each entry carries `rawTime` (the matched timecode verbatim, e.g. `"0:40"`) and `cueTime` (CUE MM:SS:FF form, e.g. `"00:40:00"`, 75 fps) so consumers don't re-derive them. `fileDurationMs` is the parent file's length so the Tracklist UI can compute per-entry durations including the trailing entry — 0 when a paired CUE exists (signals trailing-duration math is unreliable). Returns `404 NO_SETLIST` if the Comment doesn't match the heuristic. **Accepted line formats** (SL-TPS v1.0): each candidate line is tested independently (multiline `^…$`), with optional leading bullet (`-` / `•` / `*`) and optional decorative index prefix (digits, optional `.` or `)`, optional `-` / `–` / `—`). Then one of two core shapes: **time-first** `[HH:]MM:SS [optional separator] TITLE` or **time-last** `TITLE [optional separator] [HH:]MM:SS`. The optional separator accepts `-`, `–`, `—`, or `:` followed by whitespace (the colon variant is common on YouTube-comment paste-throughs, e.g. `02:46 : Last Train`). The timestamp may also be wrapped in parens, e.g. `(0:11) Live In The Moment` (common on YouTube/Reddit comments); title-internal parens are preserved verbatim. Hours optional; minutes 1-2 digits; seconds exactly 2 digits. Worked examples that all match: `0:40 - Catch These Fists`, `0:00:00 Sweet Lies`, `01 - The SoundMaker - 00:00`, `1. Amyl And The Sniffers - Foo 00:00`, `Man Made Of Meat 01:09`, `02:46 : Last Train`, `(0:11) Live In The Moment`. Index prefixes in the text are decorative; the parser assigns sequential `1, 2, 3, …` from match order. Lines that don't match are silently skipped. Detection rules: ≥3 matched lines (configurable `MinEntries`), timestamps strictly monotonic increasing, optional duration sanity (last timestamp must be before file duration when known). `{urlHash}` is computed from the track's `url` (the `url` field from `/library/files` or `/nowplaying`): `base64url(sha1(utf8(url))[0:16])` with `=` stripped → 22 chars. Browser clients use `MBXShared.urlHashOf(url)` (shared.js), byte-equivalent on secure and non-secure LAN-HTTP contexts.
- `POST /library/file/{urlHash}/extract-setlist-cue` - Body: `{ overwrite: bool }` (default false). Parses the Comment via the same heuristic, builds a real CUE sidecar at `<audio-basename>.cue` (UTF-8 with BOM so `CueParser.DetectEncoding` round-trips), atomic write via tmp (per-call guid suffix) → `File.Replace` → `.bak`. Invalidates `AlbumIndex` so the next browse / search / NP read returns the virtual tracks. Returns `200 OK { cuePath, entriesWritten }`. Errors: `409 CUE_EXISTS` (pre-existing CUE, `overwrite=false`), `400 NO_SETLIST`, `500 WRITE_FAILED`. Gated by `AccessControl.LibraryTags` so PartyMode guests cannot write. Duration sanity: detector rejects setlists whose last timestamp lands past the file's duration.

Deep-link query params on the standalone pages (no new endpoints):
- `/pages/nowplaying.html?tab=tracklist` - Opens the page with the segmented `[Lyrics | Comment | Tracklist]` control switched to the Tracklist tab on the first successful setlist load. Used by the dashboard SET LIST badge.
- `/pages/play.html?np-tab=tracklist` - Same intent for the full-player chrome variant: appends `&tab=tracklist` to the middle-pane nowplaying iframe src so the embedded NP page lands on the Tracklist tab. Used when `DashboardLayout.liveSetBadgeTarget` is set to `"play"`.
- `/pages/browse.html?album=&artist=&trackUrl=<hash>` - After the album drilldown renders, the watcher polls for the row whose `data-url` hashes to `<hash>` (via `MBXShared.urlHashOf`) and scrolls it into view with a brief accent pulse. Generated by the Now Playing right-click "Copy deep link" item.
- `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

### 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"}
- `TempoChanged` - {"file":"..."} - MB 3.5+ playback-tempo notification relay (no tempo value in the MB API; observation event)
- `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` - 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
- `MoodCacheReady` - One-shot broadcast when the cold mood cache finishes loading. `{"entries":N}` (count of moods now in cache). Dashboard's WS handler calls `softUpdate` on receipt to fill the mood pill without a polling fetch. Fires once per plugin start, immediately after MoodCache phase 3 (valence/arousal) completes
- `PartyStateChanged` - Party mode started or ended. `{"isActive":bool}`. Fired from StartParty/StopParty (REST endpoint or WinForms dialog). Already-open pages (player.html) redirect to `/pages/partymode/` the instant a party starts, instead of polling `/partymode/status`; fresh loads are handled server-side by a 302 redirect

## 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` - LEGACY (kept serving for bookmarks/default-page users; receives no new features - superseded by the device-adaptive play.html). Full 3-column player (browse iframe, now playing, queue) with drag-drop queue reorder and touch support
- `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/hud.html` - MBXHub HUD: a compact now-playing / queue / browse / reactions page. Works standalone in any browser, and is the page the MBXHub Shell's Overlay hosts (on by default; summon with Ctrl+Shift+M; toggle from the Shell tray Settings > Enable Overlay or `overlay.enabled` in `mbxhub-shell.json`, where `overlay.hotkey` / `overlay.startPage` also live). `theme.overlayThemeMode` picks which theme slot the Shell-hosted surfaces use — the HUD and the Charm Bar, always the SAME slot (0 = follow the active mode); the HUD re-reads the theme on every summon, so a theme change lands without a restart. `hud.dashboardPage` (default `/dashboard`) sets where the HUD's `Open full dashboard` menu entry goes - root-relative only, anything else falls back to the default. In a narrow overlay the Ctrl+K palette temporarily widens the window while open. `/pages/overlay.html` is an alias. The HUD can also be a DRAWER (tray: `HUD as a drawer`, off by default and remembered PER VIEW; turning it OFF clears every view so off means off, and the tray tick reads the current view each time the menu opens). ON: the HUD rests off the screen edge with a small THUMB showing at the middle of that edge — a pill with a gripper, a chevron and a pin, in the page's theme colours — comes out when the pointer rests on the thumb, and slides back a couple of seconds after the pointer leaves; the pin keeps it out, and a pinned drawer also ignores Esc, because Esc is the fastest way to lose a window you are working in. OFF: an ordinary window, and the thumb (pin included) is not shown at all. Only the thumb wakes it, not the whole edge, so a tall HUD does not open every time the pointer goes past. The edge is chosen for the monitor: one with empty desktop beyond it, so on a screen with another monitor to its right the drawer docks LEFT. What gets remembered is where it sits when it is OUT, never where it rests, or it would reopen off-screen. Focus buys time before it retreats, not immunity — a drawer you can only shut by closing it is not a drawer. See the Overlay section below for what a page must do to behave well when hosted. When hosted by the Shell the HUD has three SIZES, cycled by a chevron in its chrome: `full` (the whole HUD), `player` (a wide short bar - artwork, track, transport, volume, progress hairline) and `transport` (transport and mute only). The size is CHOSEN, not inferred from width - the page's separate narrow-width pass is a different thing. `overlay.mode` remembers the last size and `overlay.bounds` / `overlay.bounds.player` / `overlay.bounds.transport` each remember that size's own window rectangle, so summoning returns the HUD exactly as it was left. There is no second hotkey: every standard Windows shortcut nearby means minimize, and this is minimal rather than minimized. Ctrl+K from a compact size returns to `full` first, because the palette needs vertical room for results. In an ordinary browser the chevron does not appear - a page in a tab cannot resize its window. The HUD can also be dragged by its own content (the `MBXHub` name, the artwork, the compact bar) rather than only by the host's invisible edge band. LISTEN HERE in the HUD: one switch at the right end of the Services row in the browse view (full mode only; nothing is added to the compact bar), speakers (room) <-> browser (this device), shown when `/system/features` says streaming is on. It is the SAME output layer play.html runs (`components/listen-here.js`): flipping to browser takes the room's current track over onto the HUD's own audio at the room's position and pauses the room; flipping back pauses here and resumes the room; while on browser, the 🎧 in the HUD's browse pane and its queue verbs drive a local queue and MusicBee stays silent. The choice is remembered per HUD (`localStorage["mbxhub-hud-output"]`), separately from play.html's.
  - **Fixed Browse / Playing / Queue selector** (pill-behind-glyph) - the three views are always one tap apart, and the target bar above them names the target with volume and an inline pause off the Playing view.
  - **Track-details (i) view** off the target bar - shows only what the track actually has: lyrics, comment, set list, fan art, video, similar. Registry-driven, one chip per source that has content, and the button itself is absent when there is nothing to show.
  - **Playing view** - prev / play-pause / next transport and the reactions (fire / heart / downvote inline, upvote / ban in overflow) sit beside the art, with Mode (mood / flow / ON-AIR) one tap away via the shared radio strip.
  - **Browse view** - a play-first Services grid above the embedded browse page: start a station or a program, reach devices.
  - **Mini-strip** appears whenever you leave the Playing view, so transport stays reachable from Browse and Queue. Queue shows count + total time, tap-to-play-from-here and a two-tap clear.
- `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/autoqworkbench/{faders|live|builder|stations|programs}.html` - AutoQ Workbench: five single-purpose pages that make up one workbench. Each is reachable on its own and is one entry on the `autoqworkbench` charm (not device-specific, so it ships visible - it is NOT in the `charmBar.hidden` defaults). No page adds a REST endpoint - all five ride existing surfaces.
  - `faders.html` - The tunings mixing console. Vertical faders for `scoringWeights` (7), `reactionScores` (5), `influenceScores` (4) and the `estimation` normalization ranges (14), grouped exactly as `GET /autoq/settings` groups them. 400ms-debounced `PUT /autoq/settings` of the whole mutated object (`moodChannels` / `estimation` / `genreProfiles` round-trip untouched); the save indicator is judged from the PUT response only (`saving…` → `saved ✓` / `save failed`); Reset-to-server cancels a pending save and refetches. The normalization rack dims and disables while `estimation.usePercentileNormalization` is on, the same inert treatment autoq.html gives those fields.
  - `live.html` - ON-AIR. Track header with artwork and a metadata sentence, a Valence/Arousal plot (12 mood channels, target ring, current-track dot), a Camelot ring lighting the harmonic neighbours (relative + ±1 hour), reactions (fire / heart / downvote inline, upvote / ban in overflow → `POST /autoq/react {emoji, nickname:"Host"}`; ban chains a bodyless `POST /player/next` with `Content-Length: 0`), and Mode via `MBXShared.attachRadioStrip`. 5s poll of `/nowplaying` + `/autoq/radio` + `/autoq/track-mood` with 1s interpolation; ms → seconds converted once at the fetch boundary. The queue-order why-trail is NOT available over REST (`AutoQDialog.HarmonicTrailFor` is plugin-internal), so the page renders only what `/autoq/radio` + `/autoq/track-mood` provide and says where the trail lives.
  - `builder.html` - Stage-then-Apply queue building. `GET /library/search?q=` (flat `data.tracks`; minimum query length 2, mirroring the server's own `QUERY_TOO_SHORT` gate) feeds a results list with a `+ Stage` verb per row; staging is local, and Apply posts the whole stage as ONE `POST /queue/add {position:"last", urls:[...]}`. Apply is the only queue-write verb. Clear empties the stage only (two-tap armed), Reload is user-driven, there is no auto-refresh anywhere, and the queue below is read-only with a current-row pill.
  - `stations.html` - Saved stations. Flow + seed count per row, Play (`POST /autoq/stations/{id}/play`), inline rename (Enter commits `PUT {name}`; Escape and blur revert), two-tap-armed `DELETE`, and "Save current run" (`POST /autoq/stations/from-run {name}`). There is no name-only create button: `POST /autoq/stations` requires `seedUrls` or a journey.
  - `programs.html` - Saved programs, i.e. sequences of stations. Entry count per row, Play (`POST /autoq/programs/{id}/play`), inline rename (`PUT {name}`), two-tap-armed `DELETE`. Management only - `POST /autoq/programs` requires at least one entry whose `stationId` resolves, so programs are created elsewhere and managed here.
- `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/matrix.html` - OREI BK-808 HDMI matrix charm (matrix.json). Audio-extraction-first: external-audio-out input select (Off/1-8) + SPDIF mode (bind-to-input follows video / bind-to-output / independent audio matrix), then per-output video routing (8 rows), route-to-all, scene recall/save (save is two-tap arm-confirm), power, status poll. Input/output names editable, stored browser-local. Device IP in localStorage; all control via POST /api/proxy {method:POST, url: http://ip/cgi-bin/instr, body:{comhead...}} — private-LAN only, tolerates the firmware's EF-prefix-before-JSON quirk. Shown by default; hide it under Settings → Dashboard → Hidden charms if there is no BK-808 on the LAN. The page itself is always reachable at its URL
- `GET /pages/rail.html` - The Charm Bar (the desktop one — the dashboard's charm strip is a different thing that shares the name): charm icons, read from `/charms/pages`, in a window the MBXHub Shell docks flush to ONE edge of ONE monitor (an edge belongs to that display, never the virtual desktop). Which edge is `overlay.railSide` (tray: Settings > Charm Bar): `left` or `right` gives a vertical column, `top` or `bottom` a horizontal ROW — the same page, laid out along the other axis, with the arrows pointing sideways and Left/Right walking the icons; the work area excludes the taskbar, so a bottom bar sits above it. Clicking an icon opens that charm as its own desktop window growing out of the icon; clicking it again closes it. It is a wrapping grid: at its natural width that is one column (or one row), and dragging it wider (taller) reflows the icons into more — a rectangle or a square if you like. Its length is its ICONS, not the screen — the page measures the icons' extent along the live axis and asks the host via `overlay.contentSize` (`overlay.contentHeight` still goes out for a vertical bar, so an older Shell keeps working); once you have resized it yourself the ask is advisory and your shape stands. Which charms it shows is `charmBar.rail` (empty = all; the `R` box in the web settings charm editor). The FIRST icon is MusicBee — open or focus the player itself, right from the bar — wearing MusicBee's REAL icon when the Shell can extract it from the resolved MusicBee.exe (a drawn bee otherwise; the host posts it as `overlay.appIcon`) — a LOCAL DESKTOP verb, not a hub charm: the host runs the same open-or-focus as the tray's bold Open MusicBee, on the machine the Shell is on, whatever hub the bar targets (a hub call would raise MusicBee on the target's machine; deliberately one hardcoded verb, not an app-launcher registry — that generalization is a named slope and stays parked). SECOND is the HUD — pinned by the page when a Shell hosts it, id `hud`, summoning/dismissing the real HUD window (not a second copy of the page) and lit while the HUD is up; it sits outside the one-at-a-time rule. THIRD is the overlay-sets icon (`sets`, an overlay frame carrying list lines): it summons the real View Switcher — the list of saved sets — never a compositor copy of switcher.html. App icons carry no window, so the windowState echo never marks them. The bar and every charm window it opens FOLLOW HUD TARGETING (`overlay.target`, tray: Settings > HUD Target), LIVE: changing the target re-points the bar and every open charm window in place — geometry, marks and warm state kept — and the bar re-reads `/charms/pages` from the new hub, so the charm list, membership, order and icons are all the TARGET's (HUD=CHARM for targeting). The transient View Switcher is simply rebuilt on its next summon. The legacy `player` charm sits LAST by default (the dashboard's `charmBar.order` has it mid-row; the bar is its own surface) — a named `charmBar.rail` list is the only override. An outlined icon means that charm's window is ON SCREEN (the host tells the bar; closing a window by its own ✕ clears the mark too). One charm window at a time: a plain click closes the others and shows this one; Shift+click shows it alongside; clicking the lit icon closes it. Mouse clicks never activate the bar (the first click lands on the icon, and opening a charm over a game leaves the game's keyboard where it was) — but a deliberate SUMMON focuses it, first icon focused: `Ctrl+Alt+B`, arrows walk, Enter opens, Esc puts it away — a launcher you can drive without touching the mouse. If there are more charms than fit, arrows at each end scroll them (present only while there is somewhere to go). Shell only in practice: in an ordinary browser tab there is no window to dock or open, so the icons render and nothing happens. It skins from `theme.overlayThemeMode` — the SAME slot as the HUD, so the two windows sitting next to each other never disagree; the bar has no theme JS of its own, so it takes a theme change on its next load rather than live. When the hub is NOT running (MusicBee closed), every overlay window draws the host's own offline page instead of the browser's error — MusicBee's icon, the address it is waiting for, and (when the window points at the Shell's own hub) a Start MusicBee button; it reconnects by itself the moment the hub answers. Summon it from the Shell tray (Settings > Charm Bar > Show Charm Bar) or with `overlay.railHotkey` (default `Ctrl+Alt+B`, set in the Hotkeys dialog).

- `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, the shared radio strip (`MBXShared.attachRadioStrip`, same component as the dashboard charm and the MusicBee panel: mood popup menu, ON-AIR toggle with fresh/continue, seeded start, saved-stations list-and-play, refresh, honest status line), reaction buttons (fire/heart/like/dislike/ban) gated on AutoQ availability. At narrow widths the station controls and reaction buttons page via `MBXShared.attachGroupSlide` (dot pager + touch swipe) instead of cramming onto one row.
  - "+ 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 TAKES OVER: MB pauses and the same track resumes in the browser at MB's position (CUE tracks add their file offset). Flipping back is the reverse take-over: the local stream stops and MB resumes in the room at the phone's position (CUE-aware; position handoff skipped when a diverged LocalQueue was playing). A browser-side stream error never advances MB's queue (it surfaces on the output chip and stops). Formats the browser cannot decode are POLICY-unplayable in Listen Here — WMA unconditionally (no browser decodes it), every other format probed live via `canPlayType` (empty answer = blocked; 'maybe' is attempted, with any real failure surfacing on the output chip): unplayable tracks never enter the local queue (chip notes the skip, naming the format), and in mirror mode the doomed load is skipped with MB advanced past it - capped at 3 consecutive so an unplayable run stops with the chip showing why. Browser playback also drives the OS media panel via the MediaSession API (Android notification shade / lock screen): artwork, title, play/pause/prev/next/seek. 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
- `GET /pages/history.html` - Recently-played viewer. Day-range chips (24h / 7d / 30d / etc.) sourced from `GET /library/recent?days=N`. Track list shows title / artist / album / albumArtist plus playCount + skipCount columns; artist and album cells are clickable links into `/pages/browse.html`. Per-row P (Play Now) / L (add to MusicBee queue) buttons. Page-2 prefetch as the user scrolls. Backed by the `/library/recent` cache in `LibraryHandlers` (10-min TTL, invalidated on TrackChanged). Footer link disabled by default.
- `GET /pages/arc.html` - Arc, the waypoint run builder. Pick a start, an optional middle and an end; the run fills in between (`POST /autoq/radio/connect`, 2-3 waypoints in route order). Each stop has a RING - a percentile radius (`GET /autoq/similar?radius=`) that sets how wide its "like tracks" neighbourhood is, so dragging the ring visibly grows or shrinks the candidate list. Candidates rank on the same continuity blend AutoQ picks with, and each row shows why it is close (chroma N%, same/compatible key, close mood, similar timbre, similar dynamics) plus the raw blend distance - or a "tags" chip when either side is unanalysed and the score is tag affinity only. The mood plot positions placed stops by valence/arousal and draws the arc through them; it is a PROJECTION - the ranking is N-D and the list order is authoritative, which the page says on its face. Find a stop by search, by Now Playing, or by picking from another stop's neighbourhood
- `GET /pages/tree.html` - Library Tree. Three-level tree: Album Artist -> "Year - Album" -> Track. A-Z scrubber rail jumps to the first artist under a letter (letters with no artists are dimmed). Albums and tracks are lazy-loaded - a level is fetched the first time its parent is expanded, so the initial paint is artists only. Live filter box narrows the tree as you type. Per-row action cluster on albums and tracks (revealed on hover/focus): Play, Queue Next, Queue Last, Send to AutoQ (`POST /autoq/send`). Works standalone or embedded as a dashboard charm.
- `GET /pages/wiim.html` - WiiM streamer control charm: transport (prev / play-pause / next, seek bar), volume + mute, source selection, shuffle/repeat, and a now-playing readout, plus collapsible cards for the equalizer (on/off, 24 named presets, and a full 10-band custom curve via the undocumented `EQGetBand`/`EQSetBand` commands), the device's saved presets grid (`getPresetInfo` / `MCUKeyShortClick:N`), and device status (output mode, casting flag, remote battery, writable channel balance). Every device call goes out as `POST /api/proxy` - the page NEVER fetches the WiiM directly, because the device speaks HTTPS only and a browser on a plain-HTTP page cannot reach it. Device commands are LinkPlay `httpapi.asp?command=...` calls relayed by the proxy; a device "OK" is never treated as success - every write is confirmed by reading the state back (LinkPlay answers OK to commands it merely parsed). Device memory is a browser-local list (localStorage): every device this browser has confirmed is kept as a tap-to-switch row with a per-row forget, and the most recently used one auto-connects on load. A Scan button discovers WiiM/LinkPlay units via `POST /devices/endpoints/scan?protocol=ssdp`, then identifies them by probing `getStatusEx` through the proxy - no typing IPs. The charm is shown by default; hide it via Dashboard settings, Hidden charms if there is no WiiM on the LAN.
- `GET /pages/streamsdk.html` - StreamSDK device charm, for streamers built on the StreamUnlimited StreamSDK platform - the first is the Fosi Audio S3. A Scan button discovers candidates via `POST /devices/endpoints/scan?protocol=ssdp` and identifies them by probing the StreamSDK API through the proxy, so no IPs are typed; confirmed devices are kept as a browser-local tap-to-switch list (localStorage) with a per-row forget, and the most recently used one reconnects on load. Devices keep their SSDP-advertised name ("Fosi S3", not a bare IP) with the model as a subline; a row remembered before a scan learned the name upgrades in place. While connected, a "Device web client" link opens the unit's own web UI at `/webclient/` on port 80 (an S3-class feature; LinkPlay/WiiM units have no equivalent). Action rows in the settings tree carry a play glyph (▶) that triggers the node via `role:"activate"`. The hero shows now-playing plus transport verbs read from the device's own per-source `controls` map, volume and mute, and buttons for the four physical inputs (Bluetooth, Line In, HDMI, Optical) - network sources are receivers selected by the sender, so they appear as status only. Below the hero the device settings tree is rendered generically from `getRows`: toggles, sliders, enum pickers, text/password fields, action buttons, forms with a submit, container nav rows, headers and read-only values, plus nine one-tap equalizer presets over the ten bands (applied as ten sequential per-band writes) and an allow-listed Extras section. A capability filter hides platform controls the unit does not have and fails OPEN - an unmapped path still renders, because hiding a real control is worse than showing a dead one. Four paths - firmware update, factory reset, the network wizard and the password change - are refused inside `nsdk.js` at the client boundary, before any HTTP is sent. Every device call is relayed as `POST /api/proxy` (the browser never talks to the device directly); state is polled every 3s rather than long-polled, because the proxy caps at 4 concurrent calls; and a write is confirmed by reading the value back, never by the response code - a well-formed write to the wrong node succeeds silently. Transport failures flip the page to UNREACHABLE; device-side errors do not. The charm is shown by default; hide it via Dashboard settings, Hidden charms.
- `GET /pages/settings.html` - Settings editor rendered from `GET /system/settings/schema`: category + tier filters, search across every field, per-field save. Blocked when `disableRemoteConfig` is true or while a party is running (the schema endpoint returns 403).

### 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`, `browse.html`, and `hud.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` - 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` - 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` - PWA Web App Manifest. Returns `application/manifest+json; charset=utf-8`. Both `name` and `short_name` are templated with the host's **advertised name** — the `discoveryName` field in `mbxhub.json`, set via Plugin Settings → "Advertise on local network → Name". The advertised name is independent from the machine's hostname: a host whose Windows computer name is `living-room-pc` but whose advertised name is "prod" serves `name: "MBXHub - prod"` (browser install dialogs / "Manage apps" UI) and `short_name: "MBXHub - prod"` (OS desktop / home-screen / app-drawer labels) — "living-room-pc" never appears in the install UI. If `discoveryName` is empty, the manifest falls back to `Environment.MachineName` (the Windows computer name), and ultimately to the literal `"host"` if even that is unavailable. Trade-off: changing the advertised name updates both fields on the next manifest fetch — already-installed devices pick up the new label after one reinstall or manifest refresh. Other fields: `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). Note: PWA *install* itself is gated by browser policy to HTTPS or localhost; over plain LAN HTTP the manifest still drives iOS "Add to Home Screen" and Android home-screen pins (no SW required for those), but the rich Chrome/Edge "Install as app" surface is unavailable — see "LAN HTTP and 'Not secure' warnings" below.
- `GET /icons/{name}` - 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/switcher.html` - The View Switcher: Alt-Tab for overlay sets, summoned with `overlay.switcherHotkey` (default `Ctrl+Shift+S`; size `overlay.switcherSize`, default 420x360; both in the Hotkeys dialog / mbxhub-shell.json). A transient, centred, always-on-top list of your saved sets — ↑↓ pick, Enter applies, Esc cancels without applying; Save current… and Snap back home below the sets. Save current captures EVERY open overlay window — including the Charm Bar if it is up (the bar is CONTENT, not chrome — operator ruling 2026-08-21: "the bar as content is fine; if you don't want it captured, turn it off") — and applying a set closes every open window that is not a member, so a set without the bar closes the bar. The HUD is the one exception: it lives outside the set system entirely and survives every apply. Each set can carry its OWN summon chord, bound in the tray's Hotkeys dialog (one row per saved set, empty = none) and stored on the set record in overlay-sets.json, so a set and its chord travel together; pressing it applies the set from anywhere, and the switcher shows the chord beside the set. Shell only in practice: in a browser tab there is no host to answer `overlay.listSets`, so the list keeps its placeholder.
- `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; }
```

## Overlay — writing a page that works well inside it

The MBXHub Shell can host any hub page in a borderless always-on-top window over
whatever the user is doing, including a full-screen game. `hud.html` is the page it
hosts by default. This section is what a page needs to know to behave there; a page
that ignores it still WORKS, it just behaves like a browser tab in a window with no
chrome, which is the wrong thing in every specific way.

**The window has no browser furniture.** No address bar, no title bar, no tab, no
scrollbars worth relying on. In the compact views there is no host drag band either
— the PAGE draws its own close control and marks its own drag surfaces. Anything you
would normally expect the browser to provide, you provide.

**Three views, CHOSEN by the user, not inferred from width.** `full` (the whole
page), `player` (a wide short bar) and `transport` (buttons only). A page is told
which one it is in and should render for it. This is a different axis from a
narrow-width media query: a narrow `full` window is still `full`. Height is locked
by the frame in both compact views, and width is capped so a bar can never fill the
screen — do not fight either; design the row to shed instead.

**Shed, do not overflow, and do not refuse.** The user can drag the window as narrow
as they like. A good page drops the least important control one at a time until the
row fits, and keeps every escape hatch — whatever changes the view, whatever closes
the window, and the primary action. Measure a child's RIGHT EDGE to detect overflow;
`scrollWidth` does NOT grow for flex children spilling out of an `overflow: visible`
container, so it will happily report that nothing is wrong.

**Everything is relative, and that is the whole targeting model.** The window's URL
is composed from a host and a port the user picks (`overlay.target`, or the Shell's
own hub when empty), and every fetch you write as a relative path therefore goes to
whichever hub served the page — same origin, no proxy, no CORS. Never hard-code a
host. A page can be looking at a hub on another machine and cannot tell by itself,
so if WHICH hub matters to what you are showing, say so on screen.

**Do not poll while hidden.** The window is warm-hidden on dismiss so recall is
instant, which means your timers keep running and a hidden page keeps costing. The
host sends `overlay.visibility` — stop on hidden, and poll ONCE immediately on show
rather than waiting out the interval.

**When the hub stops answering, go quiet rather than complain.** The convention
`hud.html` follows: dim after two consecutive misses (the last frame is still
roughly true), go dark after four with a single dot as the only live control, and
recover automatically on the first good answer. No dialog, no toast, no red — the
usual cause is the user closing MusicBee on purpose, and several windows each
raising an error for one event reads as several problems.

**Host to page** (`window.chrome.webview` message):

- `{type:"overlay.modeChanged", mode:"full"|"player"|"transport"}` — authoritative;
  render this rather than what you asked for.
- `{type:"overlay.visibility", shown:true|false}` — see above.
- `{type:"overlay.drawer", active, edge:"left"|"right", out, pinned}` — the drawer's
  state, and authoritative in the same way. Render the echo: draw the chevron from
  `out` and the pin from `pinned`, never from your own click, or the control ends up
  claiming a state the window is not in.

**Page to host** (`window.chrome.webview.postMessage`):

- `{type:"overlay.mode", mode:"..."}` — ask to change view. The host answers with
  `overlay.modeChanged`; treat your own request as pending until it does.
- `{type:"overlay.expand", width:N}` / `{type:"overlay.restore"}` — widen
  temporarily (the command palette does this) and put it back. Restore always.
- `{type:"overlay.dragStart"}` — begin a window drag from a page surface.
- `{type:"overlay.openMusicBee"}` — open-or-focus the LOCAL machine's MusicBee (the
  Shell's own tray verb). Host action; honoured only where the host wired it (the
  Charm Bar). Deliberately not a generic launch-anything verb.
- `{type:"overlay.close"}` — dismiss.
- `{type:"overlay.contentHeight", height:N}` — ask the host to make the window as tall
  as your content, in CSS pixels. Height only: a page that could set both dimensions
  could size itself to the whole display.
- `{type:"overlay.contentSize", width:W, height:H}` — the two-axis form, for a page the
  host docks as a bar. The host honours ONE of them — the bar's long axis (height for a
  vertical bar, width for a horizontal one) — and ignores the other, so the same
  "cannot size yourself to the whole display" rule holds. Send the axis you do not mean
  as 0. The host tells a docked bar its side with an `overlay.barSide` echo
  (`{side:"top", horizontal:true}`), re-sent on every navigation and show like the
  other echoes; until it arrives, lay out as a column. Measure your CHILDREN, not a container that
  is already `height:100%` — asking that element how tall its content is answers
  "however tall you already are", which is a rail that can only ever agree with itself.
- `{type:"overlay.openWindow", windowId, page, anchor:{x,y,w,h}, additive?}` — ask the
  host to show another hub page as its own window, growing out of `anchor`. The anchor
  is in YOUR coordinates (CSS pixels inside your viewport); the host converts, because
  only it knows where its window sits and what the monitor scale is. A page that could
  name absolute screen pixels could anchor a window anywhere on the desktop. It is a
  TOGGLE on visibility: a window that is on screen closes; one that is not (never
  opened, or dismissed by its own close button) is shown. ONE AT A TIME by default: a
  plain ask closes every other visible window first (the asking bar excepted);
  `additive:true` (the bar sends it for Shift+click) shows it alongside.
- ECHO `{type:"overlay.windowState", open:[windowId,...]}` — the ids that are VISIBLE
  right now, sent on every open/close/dismiss/reveal and again on every navigation and
  show. The Charm Bar paints its marks from this and from nothing else — never from its
  own clicks, which is how it used to drift after a window was closed by its own ✕.
- `{type:"overlay.drawerPin", pinned:true|false}` — pin the drawer open, or let it
  slide away again. Ask for the opposite of what the host last TOLD you, not of what
  your button looks like; the button is an echo and may be mid-update.
- `{type:"overlay.drawerToggle"}` — slide the drawer out, or back to its edge.

The host only honours messages from the origin the window was opened for.

**`window.chrome.webview` is NOT proof of our host.** It exists in any WebView2
container — a Game Bar widget, for instance. Presence tells you a bridge exists, not
that anyone is listening. Gate host-only affordances (the view chevron, the close
button) on having been TOLD something by the host, and degrade to a plain page
otherwise. `hud.html` hides its chevron until then.

**Theme lands before your first paint.** The Shell substitutes `__THEME_CSS__` and
`__DATA_THEME__` into the served HTML, so the page is correctly themed on the first
frame. Do not wait for `/system/theme` to style the page — fetch it only to react to
changes, and remember the window is recreated on some transitions, so first-byte
correctness is what the user actually sees.

**Config keys** (`mbxhub-shell.json`, Shell-side): `overlay.enabled`,
`overlay.hotkey` (summon/dismiss), `overlay.cycleHotkey` (next view),
`overlay.railHotkey` (the Charm Bar, default `Ctrl+Alt+B`), `overlay.railSide`
(`left` / `right` / `top` / `bottom`; right is the default and where an unreadable
value lands), `overlay.switcherHotkey` (the View Switcher, default `Ctrl+Shift+S`),
`overlay.switcherSize`, `overlay.startPage`, `overlay.target` (`host:port`, empty = the Shell's own hub),
`overlay.mode`, `overlay.bounds` / `.player` / `.transport`, `overlay.windows`,
`overlay.combinedSplits`, `overlay.combinedDrawerCollapsed`, `overlay.engine.sets`, `overlay.engine.charmWindows`.

**The combined panel** (one frame hosting a whole set) is a single row: the first member takes the left column as a **drawer** - a rail on the left edge with a chevron that tucks it away and hands its width to the rest - and every member after it sits beside the next as a column. Nothing stacks top-to-bottom: these pages are lists and consoles, so they want height and tolerate narrowness. Every boundary is a draggable splitter with a 120px floor (nothing drags to zero - collapsing is the drawer's job, and a pane squeezed shut by a drag would have no way back), and distances persist per splitter in `overlay.combinedSplits`. Every pane, drawer included, undocks into its own floating window and docks back to its DECLARED slot rather than the end of the row; the rail carries its own undock button so the drawer can be torn off while collapsed. Tearing off the drawer does not promote its neighbour - the panel is simply columns with no rail until it is reabsorbed.
Layout can be put back from the tray (Settings > Reset overlay layout) without
touching hotkeys, the target, or the feature switches. Reset puts the HUD at HOME:
Full view, centred on the PRIMARY monitor — deliberately not the first-run factory
placement (a strip in the right third). First-run is where a window you have never seen
should politely appear; home is where a window you have LOST should unmistakably come
back, and the centre of the primary screen is the one place on any desk that cannot be
off-screen, behind another monitor, or under the taskbar. Reset also clears the drawer
(`overlay.drawers`) — a resting position is layout, not a decision.

## 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/scan` - Trigger a MusicBee library scan (also POST). Built-in: sends Insert (scan-folders dialog) then a focus-skipped Enter to confirm
- `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
- `truedat.enabled` (default: false) - Enable the Truedat Scan button on the AutoQ Workbench Tuning tab
- `truedat.path` - Full path to truedat.exe. Blank = auto-discover (Plugins\truedat under the MusicBee install and AppData folders, then PATH, then a bounded folder search); a successful discovery writes the found path back
- `truedat.args` - Command-line arguments for scans. Blank = no-arg default scan (truedat locates the library XML itself)
- `truedat.hidden` (default: false) - Launch the scan with no console window; hidden runs are output-captured through the Hub's tool runner into the log
- `truedat.pauseOnExit` (default: false) - Keep the scan's console window open (Press any key...) after truedat exits so the output can be read. Visible runs only - ignored when `hidden` is on. The tool counts as running - and the one-scan-at-a-time slot stays held - until the window is dismissed. Generic ToolRunner option (ToolLaunchSpec.PauseOnExit); the tool's real exit code is preserved through the cmd wrapper
- **Scanning (how tracks earn their intelligence):** truedat (companion analyser) reads the audio and writes mbxmoods.json (V/A mood, key/Camelot, tempo, timbre, speechLikely/hiresGenuine/lossyTranscodeLikely verdicts); the hub consumes it live, no tags written to files. Harmonic-texture wave (2026-08-09, truedat .7 close): `hpcp12` (12-bin key-sensitive chroma, drives continuityHarmonicTextureWeight), `thpcp12` (key-invariant chroma, captured not yet consumed), `dynamicComplexity`, `beatsInterval{Mean,Stdev,Min,Max}` (inter-beat-interval summary = beat regularity; NOT beat positions, so no phrase/downbeat alignment), and six variability fields (`spectralCentroidStdev`, `spectralEnergyStdev`, `dissonanceStdev`, `pitchSalienceStdev`, `hpcpEntropyStdev`, `zeroCrossingRateStdev`, plus `mfccStdev[13]`). All nullable/omit-when-null and NOT backfillable (truedat deletes the raw extractor JSON at parse) - they populate on fresh analysis or one `--refresh-features` pass; absent reads as null, never 0. Launched through the hub's generic Tool Runner: discovery, single-instance guard (second start refused "already running"), exit code + duration, output capture on hidden runs, never kills a process. Quick start: drop truedat in Plugins\truedat (or PATH) + truedat.enabled=true (blank path auto-discovers) -> AutoQ Workbench Tuning tab Scan -> results land live, no restart; re-runs skip already-analysed tracks. ARiA run(truedat) rides the same path when truedat.ariaWhitelist is on. NOT the same as POST /aria/scan (MusicBee's own scan-folders - finds files, analyses nothing); scan-cost exclusions (review surface) save analysis time and do not affect AutoQ picking (that's POST /banlist)
- `truedat.ariaWhitelist` (default: false) - Mirror the truedat settings into ariaAllowedPrograms so run(truedat) works; turning it off removes the entry
- `allowRemoteExit` (default: false) - Allow remote shutdown of MusicBee via ARiA; localhost callers of /app/exit + /app/restart are exempt (request.IsLocal) when they send the `X-MBXHub-Local` header (any non-empty value; a caller-id requirement rather than a secret - it marks deliberate local callers and enables future per-caller allow/deny lists); a headerless local call follows the remote rules, so it needs allowRemoteExit=true; the Disable Features "App Restart" toggle outranks all of this and blocks both endpoints entirely, even from localhost
- `allowRemoteStart` (default: false) - Allow another machine to START MusicBee on this one, via the Shell's `POST /meta/app/start`. The sibling of `allowRemoteExit`, and deliberately a separate permission: closing something that is running and starting something that is not are different acts, and wanting the second without the first is reasonable. Local callers are exempt (the Shell's own offline page, or a script on that box - either could launch MusicBee directly anyway). Read by the SHELL off this file, per request, while MusicBee is down; missing or unparseable reads as false, because a gate that fails open is not a gate. Both settings live in the plugin Settings -> API Access tab so one screen answers "what may other machines do to this one"

## 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: "") - Folders holding images, semicolon-separated. Subfolders become categories; files directly in a root appear under the `_root` pseudo-category. Empty = disabled. Each entry is a path or one of three shorthand tokens - `Pictures`, `Videos`, `Music` (case-insensitive) - for the Windows profile's corresponding known folders (real location looked up, redirected folders honored; an unresolvable token is kept as typed, not dropped). Every token works in either setting.
- `media.videoRoot` (default: "") - Folders holding videos, semicolon-separated, same rules as `media.imageRoot` - e.g. `Pictures;Videos;D:\Concerts` to pick up videos from more than one place. Both settings feed every request: the file extension decides image vs video, not which setting named the folder.
- `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. Files in root listed as `_root`.
- `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. `?compat=1` = a capability statement ("this caller cannot play the original" — the server picks the target, never a format negotiation): with `transcode.enabled` and ffmpeg resolvable, a format THIS caller cannot decode (`.wma` — no browser plays it; `.aiff`/`.aif` — not Chromium/Firefox; `.ogg`/`.oga`/`.opus` — not Safari before 18.4) is converted in transit (flac, cached — a track converts once, seeking + CUE offsets keep working, the source file is never touched) and served `200 audio/flac` with Content-Length + Range; conversion unavailable = the request refuses (503 TRANSCODE_FAILED) and the caller falls back to its unplayable chip; playable formats and requests without the parameter are byte-identical to before. See docs/ffmpeg-and-transcoding.md
- `DELETE /system/transcode-cache` - Drop every cached conversion; returns `{cleared:<count>}`. The cache is derived data that rebuilds on demand, so this is a rebuild trigger, not destruction — nothing of the user's is touched and the sources are never involved. Two uses: evict a suspect conversion (previously only reachable by finding the directory by hand), and force a COLD conversion so a replay actually exercises ffmpeg — a conversion test passes on a warm cache even with ffmpeg uninstalled. 200 even when `transcode.enabled` is off, since the cache can still hold files from when it was on; 503 `TRANSCODE_UNAVAILABLE` only when transcoding was never armed this run. Best-effort per file: a conversion currently being streamed stays, and is reported as not-removed rather than failing the sweep
  - 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)
  - Party gate: while a party is active, /stream returns 404 unless `partyAllowStreaming` is true (default false)
  - Feature flag: `streaming` in `GET /system/features` response

## Device Proxy

- `POST /api/proxy` - Forward an HTTP or HTTPS request to a LAN device (CORS bypass); during an active party this is a Player-class action (guests without player permission are denied)
  - Body: `{"method":"GET|POST|PUT", "url":"http(s)://192.168.x.x/...", "body":{} }`
  - Only private IPs allowed (RFC 1918 + loopback). Public internet blocked (403). Schemes other than `http`/`https` blocked (403).
  - HTTPS targets supported for self-signed LAN gear (e.g. WiiM `https://192.168.x.x/httpapi.asp`). **Certificates are NOT validated** for proxied requests - no chain, hostname or expiry check; the connection is encrypted but unauthenticated. Same address rules as `http` (allowing the scheme reaches no additional hosts). The relaxation is per-request; all other outbound TLS from MusicBee/MBXHub still validates normally.
  - 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.

### Endpoints
- `GET /charms/pages` - The window-able charms: the list the MBXHub Shell's overlay compositor reads to offer a charm as a desktop window. A charm is window-able when one of its actions is `webapp <path>` — that path is a hub page, so it can be a window; charms whose actions are pure HTTP or exec have no page to host and are omitted, as is any page that resolves off this hub. Returns the standard envelope: `{success:true, data:{members:[{windowId:"charm.<id>", page, label, icon, source:"charm"}]}}`. `icon` comes from the charm's own value, or from the `expand` entry that supplied the page when the charm has none of its own — twelve of the fourteen shipped charms keep their icon only on the expand entry, so reading the top level alone answers null for almost all of them. The shipped charms carry inline SVG markup, not an emoji — render it, do not look up a glyph. Top-level `pages/*.html` files are listed too, as `{windowId:"page.<slug>", source:"page"}` with NO icon and a label derived from the filename, so dropping an HTML file in makes it window-able; a page a charm already offers is skipped rather than listed twice. A missing icon is normal, never an error. Ordered by `charmBar.order` — the same list the dashboard bar uses; charms not named in it keep their load order after the named ones. Loose `pages/*.html` are OPT-IN: name the slug (filename without extension) in `charmBar.windowPages` and it appears as `page.<slug>`; empty (the default) means charms only. `charmBar.hidden` wins over an opt-in and accepts either the bare slug or the `page.` id. Visibility is otherwise the charm bar's, not this endpoint's: the same three filters the dashboard applies are applied here — nothing at all during an active party, ids in `charmBar.hidden` dropped, `aria` dropped when ARiA is disabled — so a charm the host hid is never published here. Settings are read per request. Disable: `apiDisableCharmPages` (returns 404 when true).

### 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"]) - 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). XL/XXL suit 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.
- `rail` (default: []) - Which charms appear on the desktop Charm Bar (`/pages/rail.html`), served by `GET /charms/pages?for=rail`. EMPTY MEANS EVERYTHING: a fresh install shows every charm. Untick one in the web settings charm editor (the `R` box beside `NR`) and the list is written out as everyone-but-that-one, in dashboard order; tick them all back and it collapses to `[]` again. Only the bar asks with `?for=rail`, so this never changes what the dashboard or the overlay compositor sees. It cannot resurrect a charm that `hidden` removed, and a listed charm that is no longer installed is skipped rather than blanking the bar.
- `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.** 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.
- `GET /diag/autoq/picks` - The last 20 AutoQ decision records, newest first. One record per pick: which entry point ran (fill, pick, generate, journey, preview, connect, station-play, send), what each eligibility gate removed, where the pick aimed and how far it reached, the top scorers with the components that produced them, what a quota cut, the ordering, and what reached the queue. Requires BOTH `diagEndpointEnabled` and `pickJournalEnabled`. With `pickJournalEnabled` on, the same records are also appended one JSON object per line to `autoq-picks.log` beside `mbxhub.log` (5 MB, 2 archives), so a bug report carries them. Each record is serialized by the same formatter the log file uses, so the wire and the file are byte-identical. Note two shapes a reader must handle: a normally-numeric field is the STRING "NaN"/"Infinity"/"-Infinity" when non-finite, and on a send record `sentUrls`/`sentQueued` are the listener's own tracks while `queued` is AutoQ's fill - they are never one number. A send record also carries `sendMode` (shown as `mode=` on the summary line): the steer variant that applied (refresh/reuse/restart), the same value the send's response reports as `mode`, so the journal and the toast cannot tell two different stories. `sentUrls` is capped at 50 entries so one huge multi-select cannot write an unbounded line; `sentTotal` carries the uncapped count of what was sent. A record with `poolRecorded` false never drew a pool at all, which is distinct from a draw that came back empty.
- `POST /diag/snapshot` - 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` - 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` - 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/truedat/paths` - Where truedat resolves each of its artifacts, asked of truedat itself (`--paths --json`) and never derived hub-side. Response: `{resolvedFrom, paths:[{key,label,path,present,note}], capturedUtc, stale, staleReason}`. `resolvedFrom` names which step chose the catalog (`--moods argument` = the hub pinned it via the `moodsFilePath` setting; otherwise truedat discovered it) — the distinction a wrong-catalog report turns on. Entries with `present:false` are returned, not omitted: "nowhere yet" is an answer. Keys come from truedat and are rendered as supplied, so a newer truedat reporting a new artifact shows up without a hub change. The tool holds one slot, so during a scan this serves the last good answer with `stale:true` and its `capturedUtc`. 503 when truedat is not resolvable and nothing is cached; 502 when its output cannot be read. Rendered at the bottom of `/status`.
- `GET /system/version` - Version info (includes `host` field with discovery name or machine name, and `branch` - the git line this build came from: master, release, a feature branch, or unknown). The branch is NOT in `displayVersion` for master/release: a bare version number is the release, and a suffix marks something as not one. It is reported here because the version string is identity and this endpoint is diagnostics - otherwise answering "which line is this build on" needs the repo and `git branch --contains`
- `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`, `playReporting` (false when `apiDisablePlayReporting` or `apiDisablePlayCountUpdates` is on), `partymode`, `autoq`, `transcode` (true only when `transcode.enabled` AND ffmpeg actually resolves — the capability statement clients key the `?compat=1` ask on), `diag` (mirrors `diagnostics.diagEndpointEnabled`), `libraryTagsWritable` (whether a library-tag WRITE — `POST /dashboard/love`, `POST /dashboard/rate/{n}` — can actually succeed right now; a DIFFERENT question from `ratings`/`loved`, which only say the feature exists. False when any of `apiReadOnlyMode` / `apiReadOnlyLibrary` / `apiReadOnlyLibraryTags` is on — `apiReadOnlyLibraryTags` defaults TRUE, so a stock hub refuses these writes — and false while a party is active, since tag writes are refused for every role including the DJ. Keep rendering the stars and heart either way: reading a rating always works, this flag only says whether to offer to CHANGE it. A snapshot read at page load, so the verb's own 403 is the authority in the moment), `tagEditNotice` (whether a client may EXPLAIN that refusal — false when `disableTagEditNotice` is on, for a hub deliberately run read-only where the block is intended and the explanation is noise. Independent of `libraryTagsWritable`: that says the write is refused, this says whether to say so. When false, still retire the control and keep the reason on hover — suppress only the transient notice. An older hub omits the field; treat absent as TRUE, since a needless toast beats a silently dead control), and `shellBridge` — `{port, binding, seenUtc}` when the MBXHub Shell has announced its overlay bridge this hub run, else null. Use that port instead of assuming `restPort + 1`; null means fall back to the convention. `binding` is `loopback` or `wildcard`, so a client can tell the stronger binding was unavailable. NOT a liveness claim — it is where the Shell SAID it was listening, so probe before drawing an affordance
- `POST /system/shell-bridge` - The Shell announcing its overlay bridge: `{"port":8081,"binding":"loopback"}`; an empty body clears it (clean shutdown). LOCAL CALLERS ONLY (403 otherwise) — a page believing a remote announcement would send pop-out requests at a port somebody else chose. In memory, never persisted; the Shell re-announces on every start
- `GET /system/custom-tag-names` - Returns MB's friendly display-name for each of the 48 tags exposed by `browse.customSorts` (Custom1..Custom16, Virtual1..Virtual25, Year/OriginalYear, Sort*). Response: `{names: {Custom1: "AutoQ Moods", ...}}`. Only entries whose user-configured name in MB Preferences → Tags(1) → Custom Tag Names differs from the raw enum are returned. Used by settings.html's customSorts tag picker to render "AutoQ Moods (Custom1)" instead of just "Custom1".
- `GET /system/sort-registry` - The canonical list of registered sorts (built-ins + customs), so callers do not have to guess sort ids. Response: `{sorts:[{id, label, kind:"builtin"|"custom", directionApplies, valueKind}]}`. **Direction is request-side only** — it is never a property of an entry; `directionApplies` says whether asc/desc is meaningful for that sort at all. Returns `{sorts:[]}` rather than an error when the registry is not wired.
- `GET /system/diag/sort-probe?sort=<sortId>&dir=<asc|desc>` - Diagnostic probe over `SortIndex.GetForRequest`: returns the first 20 album names in the requested order. Exists to smoke-test sort wiring independently of any `/library/*` endpoint. `sort` is required — 400 `MISSING_SORT` without it, 400 `UNKNOWN_SORT` if the id does not resolve against the registry, 503 `SORT_INDEX_UNAVAILABLE` when the index is not wired. `dir` defaults to `asc`.
- `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 `logLevel` (trace/debug/info/warn/error, propagates to Shell) and `library.disableStrictSearch` (nested bool — disables phrase-per-field strict library search). MBRC was cut; `mbrcPort` / `mbrcEnabled` no longer exist. GET additionally returns a read-only `dashboardLayout` block (`disableVirtualTracklistBadge`, and `commandPalette.{enabled,openShortcut,recentLimit,bucketLimit,actions}`) — this response is the config channel for static pages, which have no other route to those values: browse.html reads the badge flag, and the injected command palette reads its own five. Only fields a client actually reads are carried; `commandPalette.showChip` is absent because the chip is rendered server-side. Write them via `PUT /system/config`, not here. Added v0.5.5.0 — before it the block did not exist, so every palette knob silently fell back to a hardcoded client default. This endpoint carries a hand-picked subset, not all of `mbxhub.json`: everything else — including `search.live.minQueryLength`, which despite earlier wording here has never been readable or writable through this endpoint — is written via `PUT /system/config` and listed by `GET /system/settings/schema`.
- `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 a SUBSET of what GET returns — the read-only `dashboardLayout` block is not writable here (use `PUT /system/config`). Beyond the network fields it 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/open-settings` - Open the plugin Settings dialog on MusicBee's UI thread (the first-run setup screen's Settings link). Local-only (403 for remote); 404 when `disableOpenSettings` is set, 503 when the plugin UI is unavailable.
- `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

### Finding the hub - discovery order

**Port 8080 is a default, not a guarantee.** First run selects the first free EVEN pair from 8080-8098 (`PortLadder`); port 80 is never an auto-candidate (privileged http.sys port, needs a URL-ACL reservation to bind). Once chosen the port persists - a later conflict notifies rather than silently hopping. A client that hardcodes 8080 works on most machines and fails on the interesting ones. Four mechanisms, each covering what the one above it cannot:

1. **SSDP / mDNS / WS-Discovery - the advertised answer, and the only one that works off-box.** The UPnP device description carries `presentationUrl` (`http://{host}:{port}/`), `modelName: MBXHub`, the `friendlyName` (`discoveryName`, else machine name) and a stable UUID. It ENUMERATES every instance, so a machine running several MusicBee instances returns several named hubs - the one case the other three answer ambiguously or not at all. The UUID is stable across restarts, so a client can persist WHICH hub it was using rather than a host+port pair that goes stale. No OS-specific APIs; any language with a UDP socket. Unavailable when `discoveryEnabled` is false.
2. **The http.sys registration table - same machine, authoritative, works with discovery off.** Every `HttpListener` binds through the kernel-mode HTTP driver, so `netstat` / `GetExtendedTcpTable` report the owner as `System (PID 4)` and CANNOT name the application. http.sys can: it lists each request queue, the processes attached to it, and their registered URL prefixes. `Firebug.PortOwner.ForPort(port)` returns `{Url, Port, Pid, Image}` rows; to see the same thing by hand, run `netsh http show servicestate view=requestq` and look for the `Registered URLs` block under a `Processes:` entry. The owning image's full path also yields the MusicBee install tree - the input tier 3 needs for a portable install - and the binding shape tells you the posture (`+:port` = bound wildcard, so the URL ACL is present; a `localhost` registration = loopback-only fallback). LIVE state: nothing is registered when the hub is down.
3. **The config file - the only tier that answers while the hub is stopped.** `mbxhub.json`, top-level `restPort`. Normal install `%APPDATA%\MusicBee\MBXHub\mbxhub.json`; portable `<MusicBee install tree>\AppData\MBXHub\mbxhub.json`; prefer the normal path, fall back to the portable one. Also carries `restEnabled`, `requireBasicAuth` and `allowRemoteConnections` - enough to turn "not reachable" into a specific diagnosis.
4. **Ladder probe - last resort, no file or API access.** Try even ports 8080, 8082 ... 8098 with `GET /ping` and require `service: "MBXHub"` in the response body. A port being open proves nothing: another process may hold it, and a URL-ACL reservation outlives the hub - only the identity in the body is evidence.

**Diagnosing a failure** costs two local reads: no registration and no MusicBee process = MusicBee is not running; no registration but MusicBee IS running = REST is not listening (`restEnabled: false`, or the bind failed); registration found but no answer = check `requireBasicAuth`. Loopback clients need no firewall or URL-ACL step - loopback never traverses the firewall and the localhost prefix needs no reservation.

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.

`bannedPeers` (default: `[]`) is an admin-only array of IP addresses (strings). Inbound SSDP M-SEARCHes from these peers are dropped silently before the MX delay — used to suppress a misbehaving flooder on the LAN. Edit via Settings → Network → Configure Access in the WinForms dialog, or directly in `mbxhub.json`. Takes effect on restart.

- `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; first run steps to the next free port if 8080 is taken, and the Shell SMTC port follows at restPort+1) — 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.

**Streaming during a party:** the raw-byte serving endpoints — `GET /stream/*` (audio), `GET /library/video/*`, and `GET /library/file/{url}/pdf` (booklets) — return 404 while a party is active unless `partyAllowStreaming` is enabled (default false). `/system/features` reports the effective audio state as `streaming`.

**Remote surface during a party:** while a party is active, remote clients can reach ONLY the party pages and the endpoints those pages use — library/playlists/podcasts/radio browsing (the guest request tabs), queue/player (DJ verbs, role-gated), nowplaying, influences, reactions, and the ws feed. Everything else — the dashboard, the other web pages, and the admin/config API surface (`/autoq/radio`, `/autoq/stations`, `/autoq/config`, `/system/*` beyond client-log, `/docs`, ...) — answers 302 → `/pages/partymode/`. The host is exempt: localhost never sees the party redirect and keeps the full surface.

### 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.

### AutoQ Workbench — Mirror / Builder (native)

The AutoQ Workbench Queue tab (native WinForms, inside MusicBee) has two modes, switched by a
toggle at the top; the header names the active mode:
- **Mirror ("Next Up Queue")** — the default. Mirrors MusicBee's upcoming queue with the
  now-playing track on top, and AutoQ auto-fills it on every track change. Nothing to learn — it
  just plays.
- **Builder ("Queue Builder")** — a manual scratchpad with auto-fill held off. Search the whole
  library (drives the same in-process search engine as `/library/search` — no new endpoint), drop
  picks into the list, and seed a run from the playing track. The scratchpad's outputs: push it to
  the live queue (Q Next), connect it into a journey, or save it as a station.

Native surface with no REST endpoints of its own — it drives the shipped search / generate /
station engines in-process.

### 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). Twelve bands, arranged so each quadrant of the V/A plane has at least two anchors:
- Relentless 💀 (0.95, 0.10) | Intense ⚡ (0.90, 0.20) | Energetic 🔥 (0.85, 0.75) | Drive 🏌️ (0.78, 0.68)
- Edge 🤘 (0.72, 0.35) | Upbeat 🎉 (0.65, 0.85) | Morning ☀️ (0.50, 0.80) | Emotional 😢 (0.45, 0.20)
- Chill 😌 (0.30, 0.70) | Mellow 💭 (0.20, 0.50) | Night 🌙 (0.15, 0.30) | Relax 🧘 (0.10, 0.60)

Migration: existing user `moodChannels` arrays get missing defaults appended on first load (case-insensitive name match). User positions, renames, and custom bands are preserved.

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

### 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`:
- `autoHeart.enabled` (default: false) - Auto-Heart: a Fire/Heart reaction on the now-playing track loves it in your MusicBee library (solo mode only). Off by default; opt-in. Respects the Loved feature toggle (`apiDisableLoved`) and the read-only tag flags; independent of `protectMetadata`.
- `pickMode` (default: "Weighted") - Track selection mode: Off (AutoQ stops picking and NOTHING fills the queue - playback runs out; TrueShuffle keeps its own skip rules but never queues), Favorites (highest-scored), Weighted (score-proportional random), Random (uniform random, diversity caps still apply), Fresh (play-recency: least-recently-played first, never-played is freshest). The EFFECTIVE queue driver is derived from this + the AutoQ/TrueShuffle enable flags: AutoQ (enabled & pickMode != Off) -> else TrueShuffle (if enabled) -> else Off. The MusicBee Settings dialog and AutoQ Workbench both surface that effective driver so the active mode is never ambiguous
- `freshStrict` (default: false) - Applies to Fresh pick mode: true = strict freshest-first (never-played, then oldest-heard); false = freshness-weighted random that still favors fresh tracks. Never-played composes with the `playcount:0` filter, not a separate control
- `freshness` (default: "Free") - Global default freshness for AutoQ picks: Free (no recency constraint), Fresh (least-recently-played first), NeverHeard (only 0-play tracks). A saved station's own `freshness` overrides this (unset = inherit global). NeverHeard composes with the `playcount:0` gate; Fresh reuses the Fresh pick-mode recency. Surfaced as the Freshness control (Never heard / Fresh / Free) in the AutoQ Workbench Builder's Filters section, baked into a station by Save-as-station
- `artistQuota` (default: 1) - Max tracks from same artist in batch (0=disabled)
- `maxTrackLengthSeconds` (default: 0) - Longest track AutoQ will pick, in seconds (0 = no limit). Applied at the candidate choke point, so fills, funnel, generate, and journeys all respect it; explicitly queued tracks are unaffected. Unknown-duration tracks are excluded while `strictDurationLimit` is on (the default), kept when off.
- `excludeSpeechTracks` (default: true) - Keep talk/podcast tracks out of AutoQ's auto-pick pool: a candidate whose Truedat verdict is `speechLikely="yes"` is dropped at the same candidate choke point as `maxTrackLengthSeconds` (fills, generate, and journeys all inherit it; explicitly queued tracks, journey waypoints, and station seeds are unaffected). Only "yes" excludes - missing verdict, "unknown", "n/a", and "no" all stay playable, so coverage fills in gradually as the library is scanned. On by default; turn off if the untuned speech classifier shows early false positives.
- `filter` (default: "") - Candidate filter in search-DSL syntax. Works as include AND exclude: a plain qualifier keeps only matches, a `-` prefix drops matches; terms AND together, `OR` and parentheses compose. Examples: include `genre:rock`, `year:1980..1989`, `rating:>=4`, `genre:rock rating:>=3`; exclude `-genre:metal`, `-year:1990..1999`, `-genre:"Test Disc" -year:1990..1999 duration:<1200`; compound `(genre:rock OR genre:punk) -artist:"Nickelback" duration:<600`. Empty = off. Saved strictly: `PUT /system/config {"autoQ.filter": ...}` returns 400 INVALID_FILTER with the parse error on a bad expression. Filterable keys: genre, year, duration, bpm, rating, playcount, artist, album (string keys = case-insensitive substring; numeric keys support `<` `<=` `>` `>=` and `lo..hi` ranges). Missing data never matches a predicate - an include drops it, an exclude keeps it; unknown duration is excluded while `strictDurationLimit` is on (the default), kept when off. Bypass list: explicitly queued tracks, journey waypoints, and station seeds are never filtered. Scope: a filter gates new fills only - it does not sweep tracks already in the upcoming queue; clear the queue to apply it immediately.
- `strictDurationLimit` (default: true) - Treat duration limits as hard gates. A track whose duration is unknown/unscanned (0) can't be proven within a bound; on (the default) it is EXCLUDED by both a `duration:` filter bound and `maxTrackLengthSeconds`, so a limit means a limit; off it is KEPT (lenient, the Task 2 precedent). Only bites when a duration limit is set. Explicitly queued tracks, journey waypoints, and station seeds bypass either way.
- `genreQuota` (default: 3) - Max consecutive same-genre tracks (0=disabled). Suspended per-run when the run is genre-quota exempt: saved stations and plain seeded starts default exempt, mood channels default not-exempt
- `glideTightness` (default: 0.6) - PFS glide / Continuity: weight of flow-from-previous (acoustic timbre + Camelot key + half/double tempo + chord density) vs the flow target in each pick (0-1). Workbench Tuning tab + AutoQ console Continuity slider. Off-air this value IS the glide; on-air the strip Tight<->Loose dial governs (glide derived from the dial, this field untouched) until you edit the slider, which overrides the dial for the running run from the next fill on - moving the dial hands control back. The harmonic (Camelot) part of that term is scaled by key-profile agreement, read as n-of-m over the profiles a scan actually carried - full when two or more agree on the mixed key, half on a strict majority or a lone profile, dropped when the mixed key is outvoted (weights renormalise, same as a missing key); pre-wave entries carry no votes and are treated as trusted
- `continuityKeyWeight` (default: 0.25) - Key weight: how much of the continuity blend is Camelot key compatibility, relative to the fixed mood 0.30 / timbre 0.20 / tempo 0.25 weights (the sum renormalises). Raise for fewer key clashes in the ordered chain at the cost of mood/tempo smoothness; 0 removes the key term entirely. Workbench Tuning tab + AutoQ console "Key weight" slider; applies to radio fills, generate, and journeys alike
- `continuityHarmonicTextureWeight` (default: 0) - Harmonic texture weight: continuous-chroma (HPCP 12-bin) cosine similarity beside the Camelot `continuityKeyWeight` term - Camelot owns key relation, this adds graded texture within and across it. Null on either side (unscanned, or a track scanned before the field shipped) skips the term and the remaining weights renormalise like a missing key. Ships dark (0); the operator lights it once the library carries hpcp12. Workbench Tuning tab + AutoQ console "Harmonic texture weight" slider; applies to radio fills, generate, and journeys alike
- `continuityDynamicsWeight` (default: 0) - Dynamics weight: a small loudness/energy-side continuity term over Essentia dynamic_complexity (how close two neighbours sit in loudness dynamics). Same null-skip / renormalise behaviour as the other continuity weights. Ships dark (0). Workbench Tuning tab + AutoQ console "Dynamics weight" slider; applies to radio fills, generate, and journeys alike
- `funnelReach01` (default: 0.246) - Reach: how wide the candidate funnel opens (0=tight/near the run center, 1=wide-roaming). Workbench Tuning tab + AutoQ console Reach slider. Same override rule as `glideTightness`: the strip Tight<->Loose dial governs a run by default (reach derived from the dial, this field untouched); editing the slider overrides the dial for the running run from the next fill on, and moving the dial clears the override. Applies to radio fills, generate, and journeys alike
- `slideEvery` (default: 10) - PFS slide: every Kth pick steps outside the neighborhood (0=off)
- `slideReach` (default: 0.35) - PFS slide: minimum distance from the previous track for a slide pick (0-1)
- `moodMatchWeight` (default: 0.4) - Weight for mood matching in scoring (0-1)
- `moodTagField` (default: "Custom1") - MusicBee tag field for writing mood labels: the native `Mood` field or any `Custom1`-`16` (null=disabled)
- `moodTagFieldName` (default: "AutoQ Mood") - Expected display name for the custom tag field (must match MusicBee config)
- `sendMode` (default: "refresh") - Default Send to Q Behavior: reuse (join seeds cumulatively), refresh (newest send leads, weighted), restart (replace seeds outright). Practically: reuse = "and also this", refresh = "more like this now", restart = "forget that, this instead"
- `sendRefreshWeight` (default: 0.7) - Refresh weighting 0-1: how strongly the newest send dominates the recomputed run center (0 behaves like reuse, 1 like restart)
- `sendWaypointCap` (default: 3) - Max waypoints one send adds to an in-flight journey (1-4; engine hard cap is 4 plus the destination = 5 pinned)
- `sendQueueCap` (default: 0) - How many sent tracks queue immediately (0 = all). Steering always uses the full batch. Secondary knob (workbench + /autoq/settings only)
- `sendBoostStrength` (default: 1.0) - Station-memory write per send: 0 disables, above 0 records an upvote (binary store, parity with a thumbs-up). Secondary knob
- `sendIdleStart` (default: "station") - Idle send behavior: station (start one from the sent tracks) or tray (collect only, surface-side). Secondary knob
- `sendMaxSeeds` (default: 12) - Seed-set bound for cumulative modes; oldest send generation evicts first, newest always survives. Secondary knob
- `sendMagnetPolicy` (default: "keep") - keep = active mood magnet survives a send; clear = a send drops it. Secondary knob
- `sendWaypointOverflow` (default: "queue") - Sent tracks beyond the waypoint cap: queue (play, don't bend the arc) or drop. Secondary knob
- `sendQueuePlacement` (default: "next") - Where sent tracks land in the queue: next or end. Secondary knob
- `sendRefill` (default: "keep") - keep = already-queued fills stay; replace = unplayed fills behind the sends are re-picked against the new center. Secondary knob
- `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)
- `vamAnchorPlaylist` (default: "Auto-Cal") - MusicBee playlist name used as the VAM calibration anchor pool. `GET /vam/gates/report` enumerates this playlist live and joins each track with its VAM anchor annotation (from the annotate flow) to score model drift. Playlist is resolved by name on every request; rename in MusicBee and the endpoint reflects it without a restart.
- `useTrainedModel` (default: true) - Use the embedded trained Ridge/PCA model for valence and arousal predictions. When false, MoodComputer falls back to the legacy weighted-sum formula — making every weight slider, intercept, genre-bias, and the Calibrate/Suggest buttons in the AutoQ Tuning Console live. Toggle off if the embedded model fits your library poorly and you want to tune the formula by hand. `/pages/autoq.html` shows the active path (model vs formula vs missing) at the top of the Estimation Mixer and auto-hides the formula sliders when the model is active.
- `genreMoodDefaults` (default: 30-entry curated table) - Map of genre name → `{ valence, arousal }` used by the fallback estimator when a track has no Essentia features (i.e. day-1 install before any library scan). Case-insensitive lookup; subgenres token-walk so "Heavy Metal" → "Metal", "Hard Rock" → "Rock". Defaults populate on first load. An empty `{}` stays empty (every unscanned track gets neutral 0.5/0.5). Add / remove / retune entries to taste — this is the only place day-1 users can shift fallback predictions without scanning.

#### Trained model — disk override and reload

The trained model ships as an EmbeddedResource (`Resources/mood-model.json`) inside `mb_MBXHub.dll`. At plugin startup `MoodModelLoader.OverridePath` is set to `%AppData%\MBXHub\mood-model.json` — if that file exists on disk it supersedes the embedded default. Lets you iterate on retrained models without rebuilding the DLL: train → write to AppData → restart (or POST /vam/model/reload) → loader picks up the new file and logs `Loaded mood model v3 (disk:…)`. The embedded model is the **24-feature / 146-anchor** fusion model: `modeMajor` (major/minor) is a direct valence input, and a model-carried mean-impute block keeps train/serve parity (valence LOO r=0.865, arousal 0.931). Earlier model generations are archived under `tools/` for comparison.

`tools/calibrate-valence-arousal.py` mean-imputes missing `smfmValence`/`smfmArousal`/`modeMajor` values instead of zero-filling, and stores the per-feature means in a model-carried `impute` block; `MoodModelLoader` substitutes the SAME means at serve time (train/serve parity). `modeMajor` (major=1.0/minor=0.0/null unknown) is one of the 24 features. Older model JSONs without an `impute` block fall back to 0.0-fill.

- `GET /vam/model/info` — model status: `{loaded, source ("disk"|"embedded"|"none"), overridePath, useTrainedModel, active, activePath ("model"|"formula"), model:{version, trainedAt, anchorsUsed, featureCount, valenceLoocvR, arousalLoocvR, essentiaOnlyHead, essentiaOnlyValenceR, essentiaOnlyArousalR}}`. Used by the AutoQ Tuning Console to badge / hide the formula sliders.
- `POST /vam/model/reload` — drop the cached model, re-read from disk/embedded, then recompute every cached per-track V/A in place (promoted model takes effect immediately — no restart). Returns the `/vam/model/info` shape plus `recomputed` (entries swept; -1 = mood cache not loaded yet). No auth gate today; admin-trusted LAN only.
- `essentiaOnlyHead` (bool) in `/vam/model/info` — when true, the model carries a fallback head (`essentiaOnlyValenceR`/`essentiaOnlyArousalR` give its LOO-CV r) that scores tracks with no SMFM instead of collapsing them toward center.
- `GET /vam/model/residuals` — the v3 live-tuning corrections layered on top of the loaded model. Rating a track on the annotation page stores a base-relative correction (`rated − model`) in `mood-residuals.json` keyed by `audioStreamSha256`, so the served V/A reflects it immediately. Returns `{count, file, entries:[{key, corrV, corrA, ratedAt}]}`. Read-only.
- `POST /vam/model/residuals/clear` — reset level 1: drop all live-tuning corrections, back to pure model output. Non-destructive — leaves labels (`mbxvam-labels.json`) and the model file untouched. Returns `{ok, cleared}`. Honors `ApiReadOnlyMode`.
- `GET /vam/diag` — read-only VAM observability: active model (`{loaded, source, overridePath, useTrainedModel, active, detail:{version, trainedAt, anchorsUsed, featureCount, valence/arousal:{transform, loocvR, loocvRmse}}}`), training inputs (`moods`/`labels`/`pairs` file presence + counts + mood-cache stats), the active-vs-`suggest-weights` distinction, `bakeEnv` (`{pythonOnPath, pythonPath}` — interpreter presence for a future retrain/bake; cheap PATH scan, no process spawn), and `knownGaps` flagging documented model-recording gaps (tune-pair usage not recorded in the model file; trainer joins labels by path, not `audioStreamSha256`). Surfaces "what is the model actually consuming?" — mutates nothing.

### 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.92) - Secondary band must score this fraction of the primary's score (0-1). Higher = secondary must be genuinely close, not just kinda close.
- **Valence weights** (positivity, sum ~1.0) under `autoQ.estimation` — rev 4 rebalance: `valenceWeightMode` (0.30, major→pos / minor→neg), `valenceWeightDissonance` (0.30, consonant→pos, strongest negative-valence predictor at audit r=-0.55), `valenceWeightCentroid` (0.20, bright→neg, audit r=-0.53), `valenceWeightSpectralSkewness` (0.20, right-skewed→pos, audit r=+0.46, counterbalances centroid for bright-but-warm material like acoustic/jazz). Zeroed dead-weight features: `valenceWeightDance` (0.0, audit r=+0.02), `valenceWeightPitchSalience` (0.0, r=+0.02), `valenceWeightChords` (0.0, r=+0.16), `valenceWeightMfcc` (0.0), `valenceWeightFlatness` (0.0, Essentia returns 0). Mode scoring: `modeScoreMajor` (0.85), `modeScoreMinor` (0.4).
- **Arousal weights** (energy, sum ~1.0) under `autoQ.estimation` — rev 4: `arousalWeightFlux` (0.20, primary energy signal), `arousalWeightBpm` (0.15), `arousalWeightLoudness` (0.15, *modulated by DR multiplier inside ComputeArousal*), `arousalWeightCentroid` (0.15, brightness/distortion), `arousalWeightOnsetRate` (0.10), `arousalWeightZcr` (0.10), `arousalWeightRms` (0.10, *also modulated by DR multiplier*), `arousalWeightDance` (0.05), `arousalWeightDynamicRange` (0.0 — DR is now a multiplier on loud+rms, not an additive term).
- **Arousal correctives** baked into ComputeArousal (rev 4): (1) DR-multiplier — `loud_norm` and `rms_norm` are scaled by `0.5 + 0.5×clamp(DR×18/8, 0, 1)`, so brick-walled crushed masters (DR<4 LU) get half-credit on loudness signals while genuinely dynamic tracks (DR>8) get full credit (`ArousalWeightDynamicRange` is intentionally 0.0 — DR acts as this multiplier, not an additive term). (2) BPM-doubling sanity check — when `bpm_norm > 0.9` AND `onset_norm < 0.5`, halve the effective BPM percentile (Essentia mis-doubles tempo on sub-pulses; a real top-decile BPM song has matching onset rate).
- **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/radio` - AutoQ-Radio run-state {running, pickMode, source, mood, seedCount, flow, tightness, startedUtc, genreQuotaExempt, flows}. `tightness` is the run's live Tight<->Loose dial (0=Tight..1=Loose). `genreQuotaExempt` is the run's resolved flag - a saved station's own flag on a station replay, true by default on a plain seeded start, the target mood channel's own flag on a mood run
- `POST /autoq/radio/start` - start continuous queue top-up; body {"mode":"fresh"|"continue", "source":"mood"|"seed", "flow":"smooth"|"wave"|"build"|"winddown"} (fresh clears queue first; source and flow optional); 409 AUTOQ_DISABLED if AutoQ is disabled
- `POST /autoq/radio/stop` - stop the radio (queue untouched; also deletes the persisted run detail)
- `POST /autoq/radio/flow` - set the run's flow live (body {"flow":"wave"} - any built-in or drop-in name; unknown degrades to smooth). Applies to the NEXT fill's ordering - an already-spliced journey arc is static and does not re-order; persists with the run detail when on-air. GET /autoq/radio now returns `flows` (built-ins + drop-ins) for pickers. Chrome-sets-flow ruling 2026-07-13: the MusicBee panel and the web strip both carry a flow picker (current selection checked, drop-ins listed live); the knob is turnable today and gains a read-only state when a composed program (sections) owns flow
- `POST /autoq/radio/tightness` - set the run's Tightness dial live (body {"tightness":0.0..1.0}, 0=Tight..1=Loose). 400 INVALID_REQUEST on missing/non-numeric/NaN/out-of-range; applies to the NEXT fill, persists with the run detail when on-air; GET /autoq/radio echoes `tightness`
- Tightness dial (0=Tight..1=Loose): one control over funnel reach + harmonic/tempo/timbre continuity across the dispatched batch. Tight = coherent, DJ-style harmonically-mixed flow (key via Camelot, half/double-aware tempo, acoustic timbre flow track-to-track); Loose = wide-roaming variety. Computed on the library's own analysis - no tagging required. Surfaces: a Tight<->Loose slider on the radio strip (play/dashboard), the single Tight<->Loose dial in the AutoQ Workbench Builder's Filters section (alongside Freshness + Genre-free), and granular Reach + Continuity sliders in the Workbench Tuning tab; persists into a saved Station
- Run-detail persistence: the run's shape (source, mood, flow, seeds/generations, center, station bind + its filter, journey stamp) survives a MusicBee restart via `autoq-radio-run.json` beside mbxhub.json - restored by the first fill when PickMode says the radio is still running. A fresh start or explicit stop supersedes; a corrupt/missing file restores nothing
- Read-only posture: `security.apiReadOnlyMode` (master "blocks ALL writes") now covers the whole AutoQ family — every mutating AutoQ verb (radio start/stop, connect/queue, generate, react, refresh, retag/clear, settings, stations CRUD/play) returns 403 FORBIDDEN while it is on; read/compute endpoints (status, moods, track-mood, vibe list) stay open
- Flows: `smooth` holds the run's mood center; `wave` cycles arousal up and back on a period; `build` ramps each batch from below the center to above it (openers low, closers high); `winddown` is the inverse ramp. Build/winddown ramp per fill batch — each batch is its own arc
- Drop-in flows: define your own in `autoq-flows.json` beside mbxhub.json — `{"flows":[{"name":"gentle","kind":"wave","waveDepth":0.1,"wavePeriod":16},{"name":"sunrise","curve":[0.2,0.5,0.9]}]}`. A definition = base kind + knob overrides (glideTightness/wavePeriod/waveDepth/slideEvery/slideReach), or a `curve` of absolute arousal targets (0..1, lerped across each batch — the curve IS the arc). Names work everywhere a flow name is accepted (start/generate/connect, saved stations, the Workbench picker); built-in names can't be shadowed; hand-edits are live on the next use (mtime reload, no restart); a deleted custom flow degrades to smooth, never breaks a saved station
- `POST /autoq/radio/generate` - reviewable seeded list; body {"seedUrls":[...], "flow":"smooth"|"wave"|"build"|"winddown", "count":25}; never queues (400 without seedUrls, 409 AUTOQ_DISABLED)
- `POST /autoq/radio/connect` - journey generate: finite arc between 2-3 waypoint tracks through V/A space ({"waypoints":[...], "flow", "count"} or {"targetMinutes": 5-600} to size by time instead - fills until that much music, overshoot <= 1 track; count and targetMinutes are mutually exclusive, 400 INVALID_REQUEST when both); response shaped like /autoq/radio/generate
- `POST /autoq/radio/connect/queue` - connect-from-queue: the 2-3 tracks queued ahead ARE the waypoints; the generated arc replaces that queue window (user's tracks still open/close it). Accepts "count" or "targetMinutes" like /autoq/radio/connect. 400 QUEUE_SHAPE with a teach message on any other queue shape. Never arms the radio.
- Journey-building surfaces (ruling 2026-07-15, separation of concerns): building happens in the AutoQ Workbench (MusicBee tab - its list is a builder: edits are local, Connect uses the list's 2-3 rows as waypoints, only Apply writes to the queue; the Queue tab's setup rows - station/flow/filter - collapse behind a chevron, remembered across restarts, and the list columns share the width proportionally) and in the browse page's seed tray on the web (Generate/Connect from tray seeds, Save as playlist - journeys are transient; persisting one is a playlist). The radio strips (MusicBee side panel + the shared web strip on dashboard/play) deliberately carry NO build verbs - a strip starts, selects, and stops a station. The connect endpoints above stay API-available for scripts and a future web builder UX.
- `POST /autoq/send` - Send to AutoQ: one verb, meaning from run state. Body {"files":["url",...], "as":"auto"|"start"|"seed"|"waypoint"|"destination"} (as optional, default auto). Response: {action:"started"|"steered"|"waypoint"|"collect", mode, queued, filled, seeds, waypoints}. `mode` is the steer variant that applied (refresh|reuse|restart, from `sendMode`) on steer and waypoint sends, null otherwise - the same value the pick journal logs for that send. Two counts, never one: `queued` is YOUR OWN tracks that reached the queue, `filled` is what AutoQ chose and added around them. Send one track into a stopped transport and you get queued:1, filled:5 - one track sent, five topped up behind it. `queued` is lower than `files` when a cap dropped sends (`sendQueueCap` on steer; `sendWaypointCap` overflow still counts, being queued at the end) and 0 for `collect` (tray mode queues nothing). `filled` covers the opening batch on a start, the top-up when a send finds the transport stopped, a `sendRefill:"replace"` re-pick, and the corridor tracks a journey arc adds around your pinned waypoints. `filled` counts tracks AutoQ ADDED, which is not the same as how much the queue grew: under `sendRefill:"replace"` some of those replace fills AutoQ first removed, so `filled` can exceed the queue's net growth and occasionally the queue does not grow at all. 400 INVALID_REQUEST/WAYPOINT_NOT_SCANNED/JOURNEY_EMPTY, 409 NO_JOURNEY/AUTOQ_DISABLED, 403 read-only or party non-DJ.
- Send surfaces: browse row verb (envelope icon) + multi-select batch bar, cmd+k (Alt+Enter on track rows), the Workbench Send section (behavior tuning), MusicBee's own right-click context menu ("Send to AutoQ" - routes the selection through the same dispatch; outcome on MB's status bar), and POST /autoq/send for scripts
- Send dispatch: idle → starts a station seeded from the sent tracks (`sendIdleStart=tray` answers `collect` instead and leaves the tray to the surface); radio on air → sent tracks queue next and become the run's new seed generation per the `sendMode` setting (reuse = join cumulatively, refresh = newest send leads/weighted, restart = replace outright — default refresh); a journey in flight (spliced via `/autoq/radio/connect/queue` only — arcs from plain `/autoq/radio/connect` are not tracked) → sent tracks become waypoints on a re-routed remaining arc to the same destination (cap `sendWaypointCap`). A stale stamped destination (no longer ahead in play order) answers `409 NO_JOURNEY` for both auto and explicit `as=waypoint` — never lazily cleared, only the run lifecycle clears it. `as=destination` starts a fresh tracked journey from any state, even a single sent track.
- `GET /autoq/stations` - List saved stations, summary-shaped (no seedUrls) `{count, stations:[...]}`. Each station carries `genreQuotaExempt` (default true)
- `POST /autoq/stations` - Create. Body {name, flow?, seedUrls, genreQuotaExempt?, filter?, targetMinutes?}. Server generates id; `genreQuotaExempt` optional, defaults true; `filter` is an optional per-station candidate filter in search-DSL syntax that COMPOSES with the global autoQ.filter (global = house rules, station = flavor; fills on that station must pass both) - validated strictly, 400 INVALID_FILTER with the parse error. 400 INVALID_REQUEST without name or seedUrls. Alternatively a `journey` object REPLACES seedUrls: {waypoints:[2-5 track urls], fresh?(default true), targetMinutes?} - first waypoint = start, last = end (both pinned), any middles pinned too; every waypoint must have analyzed V/A or 400 WAYPOINT_NOT_SCANNED. A journey station replays a fresh arc, not frozen seeds (see /play)
- `POST /autoq/stations/from-run` - capture the live seeded radio run as a station. Body {name}. 409 NO_ACTIVE_RUN when the radio is off or the run has no seeds
- `GET /autoq/stations/{id}` - Fetch one, full record incl. seedUrls + genreQuotaExempt, plus a `journey` field ({waypoints, fresh, targetMinutes}, null on a seed station). 404 if unknown
- `PUT /autoq/stations/{id}` - Partial update: name, genreQuotaExempt, filter and/or targetMinutes (at least one required). Body {name?, genreQuotaExempt?, filter?, targetMinutes?} - filter present (even "") = validate + apply (400 INVALID_FILTER on a bad expression; "" clears), absent = unchanged; targetMinutes 1-1440 sets, 0 clears back to unlimited, absent = unchanged (400 INVALID_TARGET_MINUTES out of range). 404 if unknown
- `targetMinutes` (optional, 1-1440) on a station stops the run after that many minutes of play; omit for unlimited. Sibling of `filter`, NOT part of `journey`. The queue is left alone, so already-queued tracks play out, and the clock persists across a MusicBee restart rather than resetting. Do NOT confuse it with `journey.targetMinutes`, which SIZES a generated arc - this one STOPS a running station. A journey needs no duration: it ends when it reaches its destination
- The RUN owns the one duration clock (spec 2026-08-31): any run - mood, seed, Send to AutoQ, station - can carry a budget. Armed from a station's targetMinutes at play, or MusicBee-side via the ON-AIR menu's "Stop after..." (panel + Workbench); the station menu's "Duration..." edits a saved station; save-as-station bakes the live run's budget into the recipe. GET /autoq/radio reports read-only `runBudgetMinutes` (null = unlimited) + `runMinutes` (music played against it)
- `DELETE /autoq/stations/{id}` - 404 if unknown
- `POST /autoq/stations/{id}/play` - One-action replay: queues the station's seeds next, applies its flow, starts the radio seeded (inherits the station's genreQuotaExempt automatically). A journey station instead regenerates a FRESH arc between the same pinned start/end each play (new random middle, sized to targetMinutes - works for hours), queues that finite arc, and does NOT arm the radio (the end waypoint is the last track). Gated like /autoq/radio/start (party DJ-only, 409 AUTOQ_DISABLED); 404 if unknown. Response: {message, name, flow, seedCount, queued}
- Station memory: reactions recorded while a station is on the air persist per-station (`mbxhub-station-influences.json`, same folder as the station store). On replay, that station's downvoted/banned tracks are hard-excluded from its fills — active from the very first batch — and favorites get a pick boost; global taste still learns from every reaction as usual. Deleting a station removes its memory.
- `GET /autoq/stations/{id}/influences` - View a station's reaction memory: `{stationId, upvoted:[{url, artist, title}], downvoted:[...]}`. 404 if station unknown. The browse station picker's Memory button is the UI over this.
- `DELETE /autoq/stations/{id}/influences?url=...` - Remove one track from the station's memory (un-downvote / un-boost). 404 NOT_FOUND when the track isn't remembered; 400 INVALID_REQUEST without url. ApiReadOnlyMode-gated like the other station mutations.

### AutoQ Programs
- `GET /autoq/programs` - List saved programs, summary-shaped (no entries) `{count, programs:[...]}`
- `POST /autoq/programs` - Create. Body {name, entries:[{stationId, dwellTracks?, dwellMinutes?}, ...]}. Server generates id. 400 INVALID_REQUEST without name or at least one entry; 400 INVALID_ENTRY naming the failing index when a stationId doesn't resolve or an entry sets both dwellTracks and dwellMinutes or a non-positive dwell
- `GET /autoq/programs/{id}` - Fetch one, full record incl. entries. 404 if unknown
- `PUT /autoq/programs/{id}` - Partial update: name and/or entries (at least one required). Non-null entries replaces the list wholesale, re-validated the same way. 404 if unknown
- `DELETE /autoq/programs/{id}` - 404 if unknown
- `POST /autoq/programs/{id}/play` - One-action replay: starts the radio on the program's first resolvable entry (same as a station play), then arms program mode. Gated like /autoq/radio/start (party DJ-only, 409 AUTOQ_DISABLED); 409 PROGRAM_EMPTY when no entry references an existing station. Response: {message, name, entryCount, queued}
- A program is a playlist of stations: an ordered sequence of entries the radio moves through, one station handing off to the next after its dwell. Entries only add order + dwell - flow, filter, seeds, and reaction memory all still come from each entry's station.
- Dwell grammar: at most one of dwellTracks (advance after N tracks played under that entry) or dwellMinutes (advance after N minutes); neither = hold, the radio keeps filling from that station until stopped. The Workbench's Programs tab labels dwell "Play for" - same values, friendlier name. Dwell met past the last resolvable entry is a terminal hold too - the run continues as an ordinary station run rather than looping. An entry with no dwell that isn't last strands everything after it - a `warnings` array on the 200 response, not an error.
- Hard boundary: the handoff re-binds flow/seeds/filter/memory to the next entry's station on the NEXT fill only - already-queued tracks from the outgoing station play out untouched.
- Restart-resumable: a playing program's entry index and dwell progress persist with the run detail, same as the rest of the radio run. A station deleted mid-program is skipped at the next advance (logged); a program deleted mid-run holds on its current station.
- `GET /autoq/moods` - Get available mood channels with arousal/valence coordinates + `genreQuotaExempt` per channel (default false; suspends genre-diversity quota for radio runs on that channel)
- `GET /autoq/moods/browse?channel=Energetic` - Browse tracks matching a mood channel (?limit=200). Drops federated mood-cache entries that the local MusicBee library can't resolve (peer-only URLs would otherwise render as "Unknown"). `total` reflects the filtered count, not the raw cache hits. Local-library-only display policy &mdash; federation is analytical-only.
- `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. When the track has SMFM scores, also returns `smfmArousal`/`smfmValence` (the 2nd-source V/A). Always returns `effectiveArousal`/`effectiveValence` — the per-axis SMFM↔AutoQ blend (`eff = w·smfm + (1−w)·autoq`) using the weight learned from `/autoq/tune/source-pair` duels; equals the pure AutoQ value until that axis has real votes AND the track has an SMFM prediction (never worse than AutoQ alone until the blend is taught). Also carries `schema` ({have, total, measurable} — the field count computed server-side, next to the payload it counts) and `bootSource` ("catalog", "sidecar", or "sidecar+catalog" once the track's wide block has been hydrated on demand). On a sidecar boot the wide feature block is served per track via a span index over mbxmoods.json — one seek — so the catalog is not held in memory; `measurable:false` means the count reflects the fast cache, not the scan, and is why the AutoQ page shows "Loaded from the fast cache" instead of telling you to rescan
- `GET /autoq/track-mood` key + harmonic fields: `raw.key` (key root) and `raw.camelot` (Camelot code, e.g. 8A) are what AutoQ mixes on. `keyVotes` carries Essentia's three key profiles (krumhansl/temperley/edma, each {key,scale,strength}); the object appears when ANY vote exists and each profile is omitted individually - read what is present, never assume three. Top-level key comes from edma. Do NOT compare the three strengths (different profiles, no shared scale) - use `keyAgreement` = how many of the PRESENT profiles name the key actually mixed on (the flat key/mode, from edma) - NOT the biggest agreeing group, which can name a key nothing mixes in when edma is the outlier. Read as n-of-m: a track may carry 1, 2 or 3 profiles. AutoQ weights the harmonic term by that fraction: unanimous = full, strict majority = half, mixed key outvoted = dropped, single profile measured = half. No votes at all (pre-wave scan) = trusted, so existing libraries mix unchanged
- `GET /autoq/track-mood` tonal+rhythm wave (all nullable, absent = not measured, none backfillable): `averageLoudness` (0-1, NOT dB, NOT the `loudness` field), `bpmFirstPeak`/`bpmFirstPeakWeight`/`bpmSecondPeak`/`bpmSecondPeakWeight`/`bpmSecondPeakSpread` (second peak near 2x/0.5x the first = half/double-time evidence; spread exactly 0 = unmeasured), `chordsKey`/`chordsScale` (most frequent CHORD, not the track key), `chordsNumberRate`, `tuningFrequency` (Hz), `tuningEqualTemperedDeviation`, `tuningDiatonicStrength`, `tuningNontemperedEnergyRatio`. `hasTonalWave` = has this track been analysed since the wave
- `GET /autoq/track-mood` chord distribution: the raw 24-bin `chordsHistogram` is NOT returned - values are percentages summing to ~100 (not 0-1) and bin 0 is not C, so no bin can be honestly labelled. Returns `chordsConcentration` (biggest-bin share) and `chordsEntropy` (0-1 evenness) instead - order-independent reads of the same histogram (focused vs roaming)
- `GET /autoq/track-mood` verdicts: `verdicts` = truedat's write-time judgements when present (`speechLikely`, `hiresGenuine`, `lossyTranscodeLikely`). They re-derive on truedat's next save with no rescan. AutoQ keeps speechLikely=yes out of the auto-pick pool only (`autoQ.excludeSpeechTracks`); explicit queues, journey waypoints and station seeds are unaffected. truedat's --migrate PRUNES CATALOGUE ENTRIES for that verdict - it never touches audio files
- **How truedat identifies speech** (produces the `speechLikely` verdict; three independent evidence sources, none decides alone, none skips a scan or deletes an entry): (1) **library labels** - iTunes XML `Podcast=true` OR `Genre`==`Podcast` (exact, case-insensitive) ONLY; the old Episode-Date heuristic was removed (MusicBee maps ID3v2.4 TDRL, a release date, into that key, so it rode on music); publisher + long duration are not speech. (2) **embedded file markers** - a bounded header sniff (≤128KB/file, preview candidates only, never a full sweep), graded three tiers not first-match: `strong` = ID3 PCST / MP4 pcst (an app asserting podcast); `provenance` = WFED/TGID/purl (came from a feed - says nothing about content, music ships by RSS too); `genre-text` = TCON exactly `Podcast` (exact, not substring - "Comedy Podcast"/"Podcast Rock" no longer trip it). (3) **acoustic verdict** = `speechLikely`, computed at write time from stored Essentia features (danceability, chordsStrength, silenceRate, ZCR, tempo-peak weight, key-vote strength) so a threshold change is retroactive with no rescan; a "yes" needs BOTH the ZCR signal AND danceability<0.50 (the danceability gate is load-bearing - sparse/live/free-form instrumental music craters like talk on every other signal; genuine speech ~0.00, real-music false positives ran 0.66-1.10). Identifies the genus (speech-dominant) only - not podcast vs audiobook vs lecture (that's provenance, audio doesn't carry it)
- `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.
- **Mood/SMFM lookup resolution order:** every track → mood/SMFM-channel resolution tries, in order: (1) exact absolute path; (2) `audioStreamSha256` when a caller supplies a hash; (3) **path tail** — the last 3 path segments `artist\album\file.ext`, lowercased (this is exactly the scanner's stored `fingerprint.v1.pathTail`). The tail step makes `mbxmoods.json` portable across machines and library roots: a json keyed `D:\Music\CDArchive\Artist\Album\f.flac` resolves a local file at `C:\Users\you\Music\Artist\Album\f.flac`. Tail matching fires **only on a path miss**, so exact-path hits are never altered. This is why a moods json scanned on one box works on another without re-pathing.
- `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, catalog-load timings and field coverage. Response: `{total, essentia, fallback, byHashIndexed, warmupInProgress: false, lastWarmup: null, load: {ready, source, jsonMs, jsonCount, sidecarMs, sidecarCount, speedup, savedMs, oversizeBytes, sidecarVersion, sidecarStatus, headline, advice}, coverage: {hpcp12, dynamicComplexity, averageLoudness}, model: {version, source, trainedAt, anchors, valenceR, arousalR}, files: {catalog: {path, exists, bytes, modifiedUtc}, sidecar: {...}}}`. warmupInProgress/lastWarmup are preserved for client compatibility; warm-up no longer fires. `load` reports what populating the cache cost - the canonical mbxmoods.json parse vs truedat's .mbxs binary sidecar. Unmeasured figures are `null`, never 0 (0ms would read as "instant" for something that never ran); a boot takes one path, so both timings appear together only after the process has seen both, and speedup/savedMs appear only when both exist and cover a similar row count (within 10%). `source` is the path that ACTUALLY built the cache — sidecar|json|multipart|oversize-skipped|none — null while `ready` is false (mid-load or just invalidated); `oversizeBytes` carries the byte size of a >2 GB catalog file the JSON loader refused (source reads oversize-skipped), null otherwise. `sidecarVersion`/`sidecarStatus` say why the fast path did or did not run - active (v3 + fresh, it built the cache) | declined-version (v1/v2 carries no model scalars, entries would be hollow) | declined-stale (older than the catalog, or row-count mismatch) | unreadable (present but corrupt/foreign) | absent. Unlike `source` these are NOT gated on `ready`: they describe the resolution attempt recorded at the START of a load, so they explain a slow catalog parse while it is still running. `headline` and `advice` are the server-composed one-line summary and remedy, so every surface states the same thing. `coverage` is the fraction of rows carrying each auto-tuned continuity field (hpcp12 for harmonic texture, dynamicComplexity for dynamics, averageLoudness for the v3-only scalars - near 0 on catalogs scanned by an older truedat) - what the auto-weights ramp on, since those fields only arrive on a truedat --refresh. `model` names the trained model producing valence/arousal (version, source, trainedAt, anchors, leave-one-out valenceR/arousalR), null on the formula path. `files` carries stat-only path/exists/bytes/modifiedUtc for the catalog and its sidecar - the evidence behind a freshness verdict, without opening either file.
- `GET /autoq/vibe-list` - Current candidate tracks with scores (?count=50)
- `POST /autoq/react` - Submit reaction (body: {"emoji":"fire","nickname":"Haro"}). During an active radio run, a reaction to a scanned track also nudges the run's center - positive (fire/heart/like) pulls the center 20% toward that track's V/A, negative (dislike/ban) pushes 10% away; clamped, per-event, persisted with the run detail. Mood runs and centerless fills are untouched (no live center to nudge)
- `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 (?url={trackUrl}&limit=20&radius=5). When BOTH tracks carry analysis, neighbours rank on the SAME continuity blend AutoQ picks with (mood position, continuous chroma, key, tempo, timbre, dynamics at the configured continuity weights, resolved through WithConfiguredPulls so the neighbourhood cannot drift from what the queue would do); tag affinity (same artist/genre/era) refines it, and is the whole score when either side is unanalysed, so a mid-scan library degrades rather than misleads. `radius` is optional and is a PERCENTILE not a distance - `radius=5` = "the closest 5% of the analysed library" - because the blend distance is a normalised composite whose spread shifts as coverage grows, so a fixed distance would change meaning week to week; omit for historic top-`limit` behaviour, and when both are given the ring selects while `limit` caps. Each track carries `similarity` (0-1), `distance` (raw blend distance, null when scored on tags alone) and `reasons` naming the dimensions that actually pulled it close (chroma N%, same/compatible key, close mood, similar timbre, similar dynamics), each omitted when either side lacks that data
- `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. Tightness pair + slide pulls are flat settable fields here: `funnelReach01` (Reach, 0-1), `glideTightness` (Continuity, 0-1), `slideEvery` (0-50, 0 = off), `slideReach` (0-1) - the stored defaults behind the strip's Tight<->Loose dial (which sets the pair live per run via POST /autoq/radio/tightness). Out-of-range values are ignored, not clamped: the field is absent from the response `updated` list. `excludeSpeechTracks` (bool) and `maxTrackLengthSeconds` (int, 0 = off) are settable here too. Editing funnelReach01/glideTightness while the radio is ON applies to the running run immediately (the run normally derives both from the Tight<->Loose dial); moving the dial afterwards takes back control
- `POST /autoq/retag-moods` - Bulk write mood tags to MusicBee custom field (Essentia-analyzed tracks only). When a gate refuses the run, the response carries `data.blocked` with the user-facing reason (write toggle off, circuit breaker, field mismatch, no mood data) — never a silent `updated: 0`. The tag is a display export for MusicBee panels (MBXHub writes it, never consumes it). No automatic BULK rewrite when classifications change — run Retag (Mood Tools, AutoQ page) to bring the whole library current; individual tracks self-heal (tag refreshes on track change and on each AutoQ queue pick).
- `POST /autoq/clear-mood-tags` - Clear the configured mood tag field (Mood or Custom1-16) on all cached tracks that have a value. Explicit cleanup; gated on library-tags read-only only (independent of the write circuit breaker). Targets the currently-configured field, so clear before switching fields. Response: `{cleared, elapsedMs}`
- `GET /autoq/mood-tag-progress` - Live progress of an in-flight retag/clear. Response: `{running, op:"retag"|"clear", processed, total, affected}`. Poll while a bulk write/clear runs. Both ops are resumable — re-running skips already-done tracks (retag skips unchanged tags, clear skips already-empty), so a terminated run is resumed by just re-triggering.
- `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). Works with the radio off too: a one-shot manual fill using the last-used pick strategy, without arming the radio. Used by the dashboard refresh button and the radio strip's mood/refresh controls.
- `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

## Experiments (Labs) — NOT stable API, may change or be removed

> Everything under this heading is experimental, default-OFF, and gated behind the **Labs** category in Settings. These endpoints, settings, and pages are not part of the stable MBXHub API and may change or be removed without notice. Do not build against them yet.

### Field Factory

Generic seam for computing and writing MusicBee `Custom*` fields from registered providers. **Experimental. Default-OFF.** Master flag: `customFields.enabled` (bool, default false). When off, all `/fields/*` endpoints return `403 FIELDS_DISABLED`. Enable from the **Labs** category in Settings (`customFields.enabled` + `customFields.smfm.enabled`); the Labs page (`/pages/labs.html`) is linked from the Configuration page. The existing mood path (AutoQ, `/autoq/retag-moods`) is untouched.

### First provider — SMFM (`smfm`)

Reads the 10 raw SMFM/STMO scores from the SMFM block (written to files by other software) captured during the Truedat scan (stored in `mbxmoods.json`), projects them to an **(arousal, valence)** point on the same mood plane AutoQ uses, and writes those two scalars (0–1) to `Custom*` fields. Provider display name: `"SMFM"`. SMFM is a *second source* on the AutoQ V/A plot — the same kind of signal as AutoQ's Essentia valence/arousal, from a different origin. The raw 10 scores + BPM are kept as-is. Tracks resolve to their SMFM data by absolute path, falling back to **path tail** (`artist\album\file.ext`) on a path miss — so a `mbxmoods.json` scanned under a different root still matches (see "Mood/SMFM lookup resolution order" above).

### Settings (`mbxhub.json`)

- `customFields.enabled` (bool, default `false`) — master enable flag; must be true for any `/fields/*` to function
- `customFields.smfm.enabled` (bool, default `false`) — enable the SMFM provider specifically
- `customFields.smfm.retagOnReload` (bool, default `false`) — automatically retag on plugin startup/reload
- `customFields.smfm.fields` (array) — the two target `Custom*` fields, default `[{"field":"Custom2","name":"SMFM Arousal"},{"field":"Custom3","name":"SMFM Valence"}]`

### Endpoints

- `GET /fields/providers` - List all registered providers. Response: `{providers:[{id, displayName, enabled, targets:[{field,name}], coverage:{total,withData}}]}`. `total` = local library size; `withData` = tracks with source data (the raw 10 SMFM/STMO scores for `smfm`). Returns `403 FIELDS_DISABLED` when facility off.
- `GET /fields/{provider}/coverage` - Coverage detail for one provider. Response: `{provider, total, withData, arousal:{mean}, valence:{mean}}`. `total` = local library size; `withData` = tracks with an SMFM (arousal, valence); `arousal.mean`/`valence.mean` summarize where the library sits on the V/A plane. `404 NO_PROVIDER` for unknown ids. `403 FIELDS_DISABLED` when facility off.
- `GET /fields/{provider}/track?url=` - SMFM mood + raw scores for one track (`?url=` = file path, UTF-8). Response: `{url, found, arousal, valence, scores}` — `arousal`/`valence` are the projected (0–1) mood position, `scores` the raw 10-element SMFM/STMO array. `found:false` with null `arousal`/`valence` and an empty `scores` array when no SMFM data. `400 MISSING_URL` if `?url=` omitted.
- `PUT /fields/{provider}/config` - Update provider settings and queue a background retag. Body: `{fields?:[{field,name},...]}` — the two target `Custom*` fields (Arousal, Valence). Persists to `mbxhub.json` and queues a background retag. Response: `{result:true, provider, retagQueued:true}`. Errors: `400 INVALID_REQUEST` (missing body or empty field/name), `400 INVALID_FIELD` (field not Custom*), `400 UNSUPPORTED` (provider != smfm), `403 READ_ONLY`, `404 NO_PROVIDER`, `500 SAVE_FAILED`.
- `POST /fields/{provider}/retag` - Bulk-write configured fields for all tracks with source data. Blocking. Response: `{updated, elapsedMs}`. If already running, returns `{updated:0, elapsedMs:0, skipped:"in-progress"}` immediately. Errors: `403 READ_ONLY`, `404 NO_PROVIDER`, `500 RETAG_FAILED`.
- `POST /fields/{provider}/clear` - The undo for retag: wipe the provider's configured target fields on every candidate track in one pass (both SMFM slots at once). Blocking. Response: `{cleared, elapsedMs}`; `skipped:"in-progress"` shape when a retag/clear is running. Errors: `403 READ_ONLY`, `404 NO_PROVIDER`, `500 CLEAR_FAILED`. Labs page's Clear button is the UI. Targets the currently-configured fields — clear before switching fields.

### Retag triggers

Two ways a retag fires: (1) **manual** — POST to `/fields/{provider}/retag`; (2) **automatic** — PUT to `/fields/{provider}/config` queues a background retag on any accepted config change.

### Stale-field gotcha

A retag writes **only the currently-configured fields**. If you repoint Arousal or Valence from one `Custom*` field to another, the old field keeps its stale value — there is no auto-clear. Clear old fields manually (e.g. bulk-clear in MusicBee or via `PUT /library/file/{url}`) before reconfiguring.

## VAM Calibration — the Auto-Cal loop

VAM (Valence / Arousal / Mood) is the lens AutoQ uses to score tracks. The
calibration loop centers on **Auto-Cal**, a MusicBee playlist the user maintains
by hand. It holds *anchor* tracks — songs picked as corner / archetype examples
for the V/A axes ("this is maximum energy," "this is deepest sad"). Everything
in this section either feeds Auto-Cal, reads from it, or measures how well the
current model agrees with it.

End-to-end:

1. **Pick** tracks that mean something to you on each axis and drop them in the
   Auto-Cal playlist in MusicBee. The playlist name is configurable via the
   `vamAnchorPlaylist` setting (default `"Auto-Cal"`).
2. **Rate** them on `/pages/annotate.html`. Auto-Cal tracks are served first
   and automatically flagged as anchors when you commit a rating.
3. **Measure** with `GET /vam/gates/report`. The Gates panel at the top of
   `/pages/autoq.html` joins the playlist with your annotations and shows
   per-track and overall fit between the current model and your taste (residual,
   strict-pass count, fail count, mean residual).
4. **Retrain** when drift accumulates. Today this is a pair of Python scripts in
   `tools/` (`calibrate-valence-arousal.py` + `extract-sony-sensme.py`) plus a
   `requirements.txt` for reproducibility — developer-use only. A user-facing
   port of the retrainer ships in the **Truedat** repo (`vam-tools/`), next to
   the analyser that produces `mbxmoods.json`.
5. **Reload** with `POST /vam/model/reload`. The loader prefers
   `%AppData%\MBXHub\mood-model.json` over the embedded copy in the DLL, so a
   fresh retrain swaps in without a rebuild — and the reload sweeps the mood
   cache in place, so it also takes effect without a restart.

The pairwise tuning page (`/pages/tune.html`) feeds the same calibrator from
the other side — A/B comparisons accumulate as Bradley-Terry signals that fit
alongside the anchor labels.

## VAM Annotation

The VAM valence/arousal self-annotation page (`/pages/annotate.html`) lets you
hand-label tracks for a personal V/A model. Tracks reach the rating card two
ways: the random quadrant-balanced queue (`/vam/annotate/next`), or a deliberate
search-and-pick of a specific known corner song.

The AutoCal variant (`/pages/autocal.html`) is the pre-fill-free anchor-curation
page: same rating flow with NO model-prediction placement — both machine reads
ARE drawn on the plot as reference markers (AutoQ read = dot, SMFM read = star,
thin connector showing their disagreement), but nothing pre-places the rating;
the operator's click is the only thing written as the label. Plus an N×N
coverage overlay over the plot and region-candidate discovery for empty cells.
- `GET /autoq/autocal/candidates?vMin&vMax&aMin&aMax&source=autoq|smfm&limit=N` -
  read-only region filter over the mood cache: library tracks whose
  chosen-source V/A read falls inside the (inclusive) box. `source=autoq`
  (default) filters on the computed AutoQ read; `source=smfm` filters on the
  SMFM projection and skips tracks without SMFM data. Returns `{source, box,
  count, candidates:[{path, artist, title, valence, arousal}]}`. Computes and
  mutates nothing.

### Queue endpoint
- `GET /vam/annotate/next[?mode=disagreement]` - Pick the next track for the
  rating card: a honeypot re-serve of an already-rated track ~10% of the time
  (once at least 5 are rated), else the next unrated Auto-Cal anchor if one
  remains, else a fresh quadrant-balanced pick from the library.
  `mode=disagreement` switches the fresh-pick step to target the unrated
  essentia+SMFM track where AutoQ and SMFM diverge most (valence weighted 4:1
  over arousal, rarest-quadrant tiebreak within a 0.05 score band); silently
  falls back to the standard pick when no SMFM-bearing unrated candidates
  remain. Honeypot and Auto-Cal anchor priority are unchanged by the mode.
  Card shape: `{key, url, title, artist, album, isRetest, isAutoCal, rated,
  modelV, modelA, smfmV, smfmA}` - `modelV`/`modelA` are the current model's
  prediction (opt-in pre-fill ghost), `smfmV`/`smfmA` are SMFM's projected
  second opinion (nullable, 4dp, null when the track has no SMFM).
  `503 NO_LIBRARY` if the library is empty; `503 NO_ESSENTIA_DATA` /
  `503 NO_TRACK` if no unrated essentia-scanned candidate exists.

### Anchor-pick endpoints
- `GET /vam/annotate/search?q=<text>` - Case-insensitive substring search on
  title + artist over the library, filtered to essentia-scanned tracks with an
  `audioStreamSha256` key. Returns up to 20 results: `{results:[{key, url,
  title, artist, album, rated}]}` where `rated` is true if the track is already
  labelled. A query shorter than 2 characters returns an empty list.
- `GET /vam/annotate/pick?url=<url>` - Load a specific chosen track as a rating
  card. Validates the url is in the library pool and essentia-scanned; returns
  the same card shape as `/vam/annotate/next`. `404 NOT_PICKABLE` if the url is
  unknown or not essentia-scanned. Picked tracks default the anchor flag on —
  picking is the deliberate-anchor path.

### Rating + state endpoints
- `POST /vam/annotate/rating` - Persist a V/A rating. Body
  `{key, valence, arousal, confidence ("sure"|"unsure"), isAnchor, path}`.
  Tracks already in the configured `vamAnchorPlaylist` get `isAnchor=true`
  forced server-side so the user can't accidentally unset the anchor flag on a
  curated calibration track. Honors `ApiReadOnlyMode` — returns
  `403 API_READ_ONLY` when the kiosk read-only switch is set. Response:
  `{ok, total, file}`.
- `POST /vam/annotate/upsert` - Anchor editor: create or OVERWRITE a label's
  primary V/A by clicking the plot. Body `{key, valence, arousal, confidence?,
  isAnchor?, path?}` (isAnchor defaults true — a placement is a deliberate
  anchor). Unlike `/rating` it overwrites the primary and does NOT append a
  retest. Training input only — never overrides the deterministic model output.
  Honors `ApiReadOnlyMode`. Response: `{ok, updated, total, file}`.
- `POST /vam/annotate/remove` - Anchor editor: delete a label. Body `{key}`.
  Honors `ApiReadOnlyMode`. Response: `{ok, removed, total, file}`.
- `GET /vam/annotate/progress` - Counter snapshot for the annotation HUD:
  `{rated, librarySize, remaining, anchors, unsure,
  quadrants:{q1angry, q2happy, q3sad, q4calm}, selfConsistency:{retested,
  meanValenceDelta, meanArousalDelta, score}}`. `selfConsistency.score` is
  `1 - mean(|ΔV|, |ΔA|)` over honeypot retests; `null` until at least one
  retest has happened.
- `GET /vam/annotate/anchors` - Reference markers for the V/A scatter plot:
  the 12 fixed AutoQ mood channels (`{name, emoji, valence, arousal}`) plus
  the user's own anchor tracks (`{key, valence, arousal, path}`). Read-only.
- `GET /vam/annotate/export` - Full labels store as the Phase V2 trainer
  consumes it: `{count, file, labels:[{key, valence, arousal, confidence,
  isAnchor, path, ratedAt, sessionId, retest:[...]}]}`. The trainer reads
  this file via `--labels`; the endpoint is the canonical shape.
- `GET /vam/annotate/sanity?predictions=<path>&deadZone=0.15` - Coarse
  gross-error gate (spec §4). Compares each anchor's user-rated quadrant
  against a producer's V/A prediction with a centre dead-zone so a
  near-neutral track doesn't fail for crossing a line by a hair. Default
  producer is `mbxhub-formula` (in-process). `?predictions=<path>` points at
  an external V2 producer file. `503 NO_ANCHORS` if no anchors are
  designated yet.

### Gates endpoints
The "gates" surface compares the embedded model's predictions against the user's
anchor labels — feedback for whether the model still fits the listener's taste.
- `GET /vam/gates/report` - Enumerate the `vamAnchorPlaylist` (default "Auto-Cal")
  and join each track with its VAM anchor annotation. Returns per-track rows
  (label V/A, model V/A, residual, pass/fail vs the configured tolerance) plus
  summary stats (strict pass count, fail count, mean residual). Used by the
  Gates panel at the top of `/pages/autoq.html` and as a sanity check after
  every retrain.
- `GET /vam/gates/suggest-weights` - Coordinate-descent fit of the legacy
  formula weights against the rated anchors. Returns suggested values for every
  `valenceWeight*` / `arousalWeight*` / intercept. Note: only takes effect when
  `useTrainedModel=false` (otherwise the formula path is bypassed at scoring time
  — the AutoQ Tuning Console badges this state explicitly).
- `GET /vam/gates/calibrate` - Same fitting machinery as suggest-weights, returns
  the full calibration response shape (initial / final RMSE, per-weight delta).
  Same caveat re `useTrainedModel`. Refused `409 CALIBRATION_REFUSED` while the
  session is running on the fast sidecar cache: its feature ranks are incomplete
  (mfcc is not carried), and a fit against a degenerate column would persist a
  wrong weight that outlives the session. Wait for the background catalog read to
  finish and run again.

### Model endpoints
Trained model status + reload trigger for the no-rebuild iteration loop.
- `GET /vam/model/info` - `{loaded, source ("disk"|"embedded"|"none"),
  overridePath, useTrainedModel, active, activePath ("model"|"formula"),
  model:{version, trainedAt, anchorsUsed, featureCount, valenceLoocvR,
  arousalLoocvR}}`. Drives the AutoQ Tuning Console pill + formula-hidden state.
- `POST /vam/model/reload` - Drop the cached model and re-read from disk
  (OverridePath wins if file exists) or the embedded resource. Returns the same
  shape as `/vam/model/info`. Used after writing a freshly-trained model to
  `%AppData%\MBXHub\mood-model.json` to pick it up without restarting the plugin.
  No auth gate today; admin-trusted LAN only.
- `GET /vam/train/moods` - Training-data export consumed by
  `rebuild-mood-model.cmd` / `tools/calibrate-valence-arousal.py`: a sha-keyed
  derived view of the in-memory mood cache carrying every trainer feature plus
  the C#-only `modeMajor` encoding (`1.0` major / `0.0` minor / `null` unknown)
  and the projected `smfmValence`/`smfmArousal` second opinion. Raw JSON, not
  the success envelope - streamed directly; tens of MB on a large library.
  Shape: `{generatedAt, projectorVersion, projectorHash,
  tracks:{<audioStreamSha256>:{path, audioStreamSha256, ...essentia
  features..., modeMajor, smfmValence, smfmArousal}}, count, skippedNoSha}`.
  Entries without an `audioStreamSha256` are skipped and counted in
  `skippedNoSha` (labels join by sha). `mbxmoods.json` itself is never
  modified - this is a read-only derived view.

## AutoQ Tuning Console — pairwise A/B

The pairwise tuning page (`/pages/tune.html`) is the "second opinion" loop for
V/A scoring. The user is shown two essentia-scanned tracks at a time and picks
which one is higher on the chosen axis (or marks them roughly equal). Judgments
accumulate as Bradley-Terry signals that the V2 trainer fits alongside the
single-track anchor labels from `/vam/annotate/*`. Off to the side of
AutoQEngine — reads its public surface only, never mutates queue / picker
state.

Pair selection biases toward **under-compared** tracks and **close-pair**
candidates (the model is most uncertain when scores are similar, so each
judgment carries more signal than a random pick in a large library where most
pairs are trivially separable).

- `GET /autoq/tune/pair?axis=arousal|valence` - Build a fresh A/B pair on
  the requested axis. Picks A as the least-compared candidate (with random
  tie-break), then picks B as the candidate whose model score is closest to
  A. Response: `{axis, a:{url, title, artist, score, comparisons},
  b:{url, title, artist, score, comparisons}}`. `503 NO_LIBRARY` if the
  library has fewer than 2 essentia-scanned tracks.
- `POST /autoq/tune/judgment` - Persist a pairwise judgment. Body
  `{a, b, axis ("arousal"|"valence"), verdict ("a"|"b"|"tie")}`. Append-only
  to `mbxtune-pairs.json` in the AppData folder. Honors `ApiReadOnlyMode` —
  returns `403 API_READ_ONLY` when set. Response: `{ok, total, axis, file}`.
- `GET /autoq/tune/scores?axis=arousal|valence` - Per-track Bradley-Terry
  scores fitted from the accumulated judgment store. Response:
  `{axis, pairCount, trackCount, tracks:[{url, score, comparisons}]}`. Used
  by the tune page to show the score distribution + outliers.
- `POST /autoq/tune/flag` - File a misclassification flag against a single
  track. Body `{url, observedChannel?, observedArousal?, observedValence?,
  expectedChannel?, notes?}`. Separate store from judgments
  (`mbxtune-flags.json`); the trainer uses these as bias-correction signals.
  Honors `ApiReadOnlyMode`. `503 FLAG_STORE_DISABLED` if the optional flag
  store isn't wired. Response: `{ok, total, file}`.
- `GET /autoq/tune/flags[?summary=true]` - All flags, or per-track
  aggregates with `?summary=true`. Summary mode returns
  `{trackCount, totalFlags, tracks:[{url, flagCount, ...}]}`. Read-only.
- `GET /autoq/tune/source-pair` - **SMFM-vs-AutoQ source duel.** Samples ONE
  high-divergence track that has BOTH an SMFM and an AutoQ V/A prediction (the
  largest gap between the two sources is where a human vote is most informative).
  Response: `{url, title, artist, album, smfm:{arousal,valence},
  autoq:{arousal,valence}, gap:{arousal,valence}, duelsSoFar, sampledCandidates}`.
  `503 NO_SOURCE_PAIR` when no track has both sources (needs a truedat SMFM scan
  + essentia mood data).
- `POST /autoq/tune/source-judgment` - Persist a source-duel vote: which source's
  V/A is closer for that track, per axis. Body `{url, axis ("arousal"|"valence"),
  winner ("smfm"|"autoq"|"same"|"skip")}`. Append-only to
  `mbxtune-source-duels.json` (separate from the track Bradley-Terry store). Honors
  `ApiReadOnlyMode`. Response: `{ok, total, axis, file}`.
- `GET /autoq/tune/blend` - The per-axis SMFM blend weight learned from the duels.
  Response: `{arousal:{wSmfm, n}, valence:{wSmfm, n}, totalDuels}`. `wSmfm` in (0,1)
  is how much the effective V/A leans on SMFM vs AutoQ for that axis (0.5 = neutral,
  no votes yet, Laplace-smoothed). This is what the effective V/A consumes.

## 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

### HTTP Basic Password Gate (optional, off by default)
An optional always-on password gate over the WHOLE API surface — a safety net for trusted LANs. Configured ONLY in the plugin (Settings → Remote Connection Settings → Configure Access → Remote Access → "Require password (HTTP Basic)"); no web/API config. Settings keys: `RequireBasicAuth` (bool, default false) + `BasicAuthPasswordHash` (SHA-256 hex; set via the dialog — never hand-edit). Effective only when enabled AND a hash is set (fail-open guard).
- When on, remote requests must send `Authorization: Basic <base64(user:password)>` — username ignored, only the password is checked.
- Missing/wrong creds → `401 Unauthorized` + `WWW-Authenticate: Basic realm="MBXHub"` (browsers show a native prompt).
- Exempt: localhost (host machine), `/ws` (event stream), and the live-PartyMode surface (guests use their PIN, not this password).
- LIMITS — a speed bump, not transport security: over plain HTTP the password is base64 (≈cleartext) on every request (only HTTPS fixes that); the stored hash is unsalted SHA-256. Fine for one shared secret on a trusted LAN, not a hostile network.

### Media Endpoints in PartyMode
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

Two 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 the per-minute rollup logs
    "warnThresholdsMs": {
      "wsSlowSend": 200,                     // Warn if SendAsync > Nms
      "wsSlowBroadcast": 250,                // Warn if WhenAll > Nms (general events)
      "wsSlowBroadcastPosition": 100,        // tighter for 1Hz PositionChanged
      "moodCacheLockWait": 25,               // Warn if read-path lock entry > Nms
      "timerDispose": 100,                   // Warn if Timer.Dispose blocked
      "smtcUpdate": 30,                      // Warn if STA marshal > Nms (Shell)
      "autoQRefresh": 100                    // Warn if scoring pass > Nms
    }
  },
  "performance": {
    "wsSendTimeoutMs": 5000,                 // WebSocketClient send timeout
    "wsMaxClients": 100,                     // EventBroadcaster cap
    "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).

### 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 for remote callers; localhost is exempt via request.IsLocal WHEN the request carries the `X-MBXHub-Local` header, any non-empty value - the local handshake a cross-origin web page can't send without a CORS preflight the hub doesn't grant; a headerless local call follows the remote rules; the Disable Features "App Restart" toggle blocks it entirely, even from localhost). Optional body: `{"restart":true,"delay":22}` to schedule restart via Task Scheduler
- `POST /app/restart` - Restart MusicBee (requires allowRemoteExit for remote callers; localhost is exempt via request.IsLocal WHEN the request carries the `X-MBXHub-Local` header, any non-empty value, e.g. `curl -X POST -H "X-MBXHub-Local: 1" http://localhost:8080/app/restart`; a headerless local call follows the remote rules; the Disable Features "App Restart" toggle blocks it entirely, even from localhost). 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.

## Review Surface (manifest-driven decide layer)

Human winner-rulings over offline-produced manifests (fleet diffs, dedupe groups,
coherence checks). Manifests are JSON files dropped into `<AppData>\MBXHub\review\`
by offline tools (`tools/fleet/` in the repo); the hub serves them and stores
verdicts beside them. The hub never computes diffs and never applies verdicts.
- `GET /review/manifests` - list dropped manifests `{id, kind, title, generated, classCount, hasVerdicts, savedUtc}`. The `id` IS the file's name stem — drop each manifest as `<id>.json` (that is what `/review/manifest/{id}` and the verdicts routes resolve); an internal `id` property, if present, is display-only and ignored for routing
- `GET /review/manifest/{id}` - full manifest JSON (classes carry their own columns/options)
- `GET /review/verdicts/{id}` - saved verdicts, or 404 `REVIEW_NO_VERDICTS`
- `POST /review/verdicts/{id}` - save verdicts `{id, rulings:{class:{ruling, overrides, excludes}}}`;
  hub stamps `savedUtc` (authoritative); 403 `API_READ_ONLY` in read-only mode; prior
  verdicts kept as a single `.bak`
- `GET /review/asset/{id}` - serve the manifest's `source.reviewHtml` companion (e.g. truedat's co-emitted `dupes.html`) same-origin as text/html (a `file://` link from the http page is browser-blocked); constrained to a bare `.html` filename inside the review folder (no traversal); 404 `REVIEW_NO_ASSET` if none declared. review.html links to it when present
- `POST /review/decisions/{id}` - apply a decisions delta by delegating to `truedat --apply-exclusions`. The hub writes the delta to a temp file UNPARSED (truedat owns the merge) and never writes the exclusion file itself. On success (200) the response body IS `apply-result.json` raw (`{kind, ok, added, removed, alreadyPresent, notFound, changed, backupPath, error}`) — read `ok`/`added`/`removed` at the top level (passthrough shim, not the hub envelope); errors use `{error:{code,message}}`. Rule kinds are the closed set `folder`/`genre`/`file`. Gates: 403 read-only, 400 bad id or missing `source.exclusionsPath`, 404 no such manifest, 409 `REVIEW_TOOL_BUSY` (truedat already running — single slot), 413 body too large. Scan-cost only: it stops truedat spending analysis time on the track and does NOT remove it from AutoQ picking — use `POST /banlist` to keep a track out of AutoQ (reference §9a)
- Review page: `/pages/review.html` renders any manifest generically
- Manifest kinds: `kind:"dupes"` gets a group-keeper view — member rows grouped by duplicate set, the recommended keeper marked (`rec` badge), a radio per group; display-only (Save hidden, no verdicts). The dupes manifest is emitted directly by `truedat --duplicates --manifest <path>` (dropped as `<AppData>/MBXHub/review/dupes.json`); `diff` and other kinds come from `tools/fleet/` producers

## 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`

**Sort behavior notes:**
- String comparisons use `InvariantCultureIgnoreCase` over diacritic-folded keys, so non-Latin album titles (Cyrillic / Greek / CJK / Hebrew / Arabic) sort under their own scripts instead of being dumped at the tail of an A→Z list (ASCII libraries unchanged).
- Custom-* sorts configured as `Numeric` send rows with unparseable values (Year=`1999/2000`, whitespace-padded fields) to the END of the list alongside other non-Numerics, matching the `Auto` kind's segregation.

### 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) - Guards the RPC `ActionCategory.Metadata` path (the `Pending_*` tag-editor methods) and the Auto-Heart write. Does NOT gate the manual love / rate / tag-edit endpoints — those are `ActionCategory.LibraryTags`, governed by the read-only flags (`apiReadOnlyLibraryTags` et al.).
- `rateLimitEnabled` (default: true) - Master switch for per-IP rate limiting (party endpoints plus the reaction and client-log buckets). The play-statistic bucket is deliberately independent — disable it via `rateLimitPlayStatsPerMinute: 0`
- `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
- `rateLimitReactionsPerMinute` (default: 20) - Max emoji reactions (`POST /autoq/react`) per IP per minute
- `rateLimitClientLogsPerMinute` (default: 120) - Max `POST /system/client-log` entries per IP per minute (dedicated bucket — client pages log WS lifecycle and audio errors at volume)
- `rateLimitPlayStatsPerMinute` (default: 60, 0 = unlimited) - Max play-statistic updates per IP per minute across `/player/report-play`, `/player/update-play-statistics`, and RPC `Player_UpdatePlayStatistics` (shared budget; blocks playcount-inflation loops). Independent of `rateLimitEnabled` (whose scope is party endpoints); loopback clients are exempt so host-side bulk sync tools can burst
- `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)
- `immersiveAlwaysShowProgress` (default: false) - Keep the Immersive seek bar always visible at full height (6px). When false (default) the bar collapses to 3px as part of the chrome fade. Position-update events still fire either way; this just controls visibility.
- `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). Set `dashboardLayout.immersiveAlwaysShowProgress: true` to keep the seek bar pinned at full height regardless of the chrome fade.
- All styles have zoom-level overrides (67%, 50%, 27%). Split falls back to stacked below 480px. Immersive reduces art height below 400px.
- The `compact` style no longer exists; configs referencing it 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"`) - 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`).
- `apiDisableCharmPages` (default: false) - Disable charm window-able page list (`GET /charms/pages`, returns 404 when true).
- `disableStreaming` (default: false) - Disable audio/video streaming endpoint (`GET /stream/*`).
- `partyAllowStreaming` (default: false) - Allow browser streaming (`GET /stream/*`, Listen Here) while a party is active. Off = streams 404 for everyone during the party.
- `apiDisablePlayReporting` (default: false) - Disable Listen Here play reporting (`POST /player/report-play`). When on, browser-streamed plays no longer update MusicBee play counts, skip counts, Last Played, or shuffle progress.
- `apiDisablePlayCountUpdates` (default: false) - Block ALL external play-count updates: `/player/report-play`, `/player/update-play-statistics`, and RPC `Player_UpdatePlayStatistics` all refuse. MusicBee's own native counting is unaffected. Implies `apiDisablePlayReporting`.

### 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` (in `%LOCALAPPDATA%\MBXHub\`, alongside the Shell log and
`hub-neighbors.json`; older installs kept it next to MBXHub.exe and are migrated forward on first
load). The Shell is machine-wide: one config per user per machine, however many MusicBee installs
exist. Tray → Settings → Open Settings Folder… opens it on the machine running the Shell:
- `host` (default: "127.0.0.1") - MBXHub REST API host
- `port` (default: 8080; first run picks the next free port if 8080 is taken) - 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) - 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 ACLs for the REST port + Shell SMTC port plus discovery (UPnP / WS-Discovery / mDNS). Also reserves the overlay bridge's explicit loopback prefix (`http://127.0.0.1:<smtc>/overlay/`) on the LAST listed port — http.sys treats an explicit prefix as a separate binding the port wildcard does not cover. Grants are by SID (S-1-1-0 = Everyone), so they work on localized Windows. This is the install path (plugin Settings → Firewall panel).
- `MBXHub.exe firewall repair [--rest 8080] --smtc 8081` - The NARROW repair every in-product Fix runs (Settings → Network Status, both startup prompts, the Shell tray). Walks the reservation inventory and fixes ONLY what is missing or wrongly-held (a reservation granted to the wrong principal is deleted and re-added); an existing firewall rule is never recreated, so user-applied restrictions survive; RDP is never touched. Omit `--rest` for a standalone Shell. Exit 0 only when every entry verifies back healthy.
- `MBXHub.exe firewall add --name MBXHub --port 8080 --urlacl` - Add single-port rule with URL ACL
- `MBXHub.exe firewall remove --name MBXHub --urlacl 8080,8081` - Remove the firewall rule, both URL ACLs, AND the `/overlay/` bridge reservations for the listed ports (remove undoes add). Pass the same comma list you added; `--port 8080` removes a single port's rule + URL ACL. This is what the plugin's Settings → Firewall **Remove** button writes.
- `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.

**Remote start.** The Shell can wake MusicBee on the machine it runs on, which is the one thing the plugin cannot do for itself - when MusicBee is closed, the thing that would answer the request is the thing you are trying to start. Off by default; see `allowRemoteStart`.

- `GET http://<host>:8081/meta/app/start` - Can this Shell start MusicBee? Returns `{"ok":true,"canStart":true|false,"reason":"<short>"}`. No side effects, so a caller can decide whether to offer the verb without firing it. `canStart` is the AND of `allowRemoteStart` (or a local caller) and MusicBee actually being installed on that box - either one false means the POST would fail. The in-flight window below is deliberately not consulted: it is a rate limit, not a capability. `reason` is for diagnosis, not display.
- `POST http://<host>:8081/meta/app/start` - Start MusicBee on that machine. No body, no parameters, ever: the verb starts MusicBee and cannot be pointed at any other program. `200 {"ok":true,"result":"launched"}` when started, `200 {"ok":true,"result":"alreadyRunning"}` when it was already up (a success - the caller's window is dark because the hub has not answered yet, and that race is normal). `403 REMOTE_START_DISABLED` when the setting is off, `403 ORIGIN_NOT_ALLOWED` for an off-LAN browser origin, `404 NO_LOCAL_MUSICBEE` when no installation is found, `429 START_IN_FLIGHT` when a start is already in progress (30s window, cleared early once MusicBee is up), `500 START_FAILED` if the launch throws.

**Write gate (v0.5.5.0).** `PUT /meta/smtc/target`, `POST /meta/notify` and `POST /meta/app/start` are the Shell's state-changing routes, and each requires that a browser-supplied `Origin` be LAN-scoped (loopback, a private-range address, or a single-label / `.local` hostname). An off-LAN origin - a public website that has learned the Shell's port - is refused `403 ORIGIN_NOT_ALLOWED`. A request carrying no `Origin` at all is still served: native callers (the plugin, a script, `curl`) do not send one, and the listener binds wide on purpose so remote SMTC control keeps working. Read routes are unchanged - including `GET /meta/app/start`, which changes nothing, and where a stricter gate than the write buys nothing.

### Overlay Bridge
How a hub page opens a real desktop window. **Served by the Shell, loopback only**: the listener binds `http://127.0.0.1:<smtc.port>/overlay/`, so nothing off the machine can reach it, and it additionally refuses any `Origin` that is not the hub this Shell is paired with. A page discovers the bridge from `GET /system/features` -> `shellBridge` ({port, binding, seenUtc}) rather than guessing the port; `binding` reads `loopback` normally, or `wildcard` when the explicit reservation is missing and the Shell fell back.

- `GET http://127.0.0.1:8081/overlay/health` - Bridge liveness plus the three gates: `{ok, overlayEnabled, setsEnabled, charmWindows}`
- `POST http://127.0.0.1:8081/overlay/window` - Open a hub page as an overlay window. Body: `{"windowId":"charm.mixer","page":"/pages/mixer.html","label":"Mixer","anchor":{...}}`. `windowId` and `page` are required; `page` must be a hub-relative path starting with `/` and carrying no authority (an absolute URL, a protocol-relative `//host` or a backslash is refused `400`), which is what stops a page pointing an overlay window at somewhere off-box. Re-posting a live `windowId` focuses it rather than opening a second
- `DELETE http://127.0.0.1:8081/overlay/window/{id}` - Close that overlay window
- Requires an `Origin` on `POST`/`DELETE`; a request from a disallowed origin is refused outright rather than answered without CORS headers

### 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 (0-5 in 0.5 steps), 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/{0.5-5, .5 steps}` - Set star rating, half-star steps. Click to set, click same value to clear. Server clamps to [0,5] on the 0.5 grid.
- `POST /dashboard/love` - Toggle love tag
- `POST /dashboard/setban` - Set ban flag without skipping
- WebSocket `MetadataChanged` event for changes

**`rate` and `love` are content-negotiated.** They serve both the no-JS dashboard form and
scripted clients from one route. A browser posting the form (its `Accept` carries `text/html`)
gets the `303 -> /dashboard?msg=...` it always has. A `fetch`/XHR caller (`Accept: */*`) gets
JSON instead: `200 {result, message}` on success, or an error envelope on refusal:
- `403 LIBRARY_TAGS_READ_ONLY` - the hub is configured not to write tags. The message names
  WHICH of `apiReadOnlyMode` / `apiReadOnlyLibrary` / `apiReadOnlyLibraryTags` did it, and where
  the switch lives (MusicBee > MBXHub settings > API Access - these are `Security`-category
  settings and are deliberately NOT on the web settings page). This one does not pass on its own.
- `403 PARTY_LOCKED` - refused for the duration of the party; passes when it ends.
- `409 NO_TRACK` - nothing playing. `404 NOT_FOUND` - the feature itself is switched off.
The same reason-carrying 403 answers EVERY library-tag write, not just these two verbs:
`PUT /library/file/*` tag edits (the route player.html rates through), `/fields/*` writes and
setlist edits all share one composer, so a refusal reads the same wherever a client meets it.
Gate the affordance ahead of the click on `libraryTagsWritable` from `GET /system/features`;
treat the codes above as the authority at the moment of the click. Do NOT paint a new star or
heart optimistically when you already know writes are blocked - painting and then reverting a
moment later is indistinguishable from a bug in your client.

### 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
- The dashboard mood section renders the shared radio strip (`MBXShared.attachRadioStrip`, same component as `/pages/play.html` and the MusicBee panel): mood popup menu, ON-AIR toggle (fresh/continue), seeded start, saved-stations list-and-play, refresh, and a status line (`● ON-AIR - <source> - <flow>`). Radio/station actions call the existing `/autoq/radio/*` and `/autoq/stations` endpoints above, not new `/dashboard/*` routes. At narrow widths the station group and the reaction buttons page via `MBXShared.attachGroupSlide` (dot pager + touch swipe) instead of both cramming onto one row.

### 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/albums/with-video` - Albums whose folder contains a video file
- `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;
let canWriteTags = true;   // from GET /system/features.libraryTagsWritable

// Paint the ANSWER, not the ask. A stock hub refuses tag writes
// (apiReadOnlyLibraryTags defaults true), and a heart that fills in and then
// empties again a second later reads as a bug in your page, not as a refusal.
async function toggleLove() {
  const want = !loved;
  if (canWriteTags) paintLove(want);        // known-blocked? then do not paint at all
  const r = await fetch('/dashboard/love', { method: 'POST', headers: { 'Content-Length': '0' } });
  if (r.ok) { paintLove(want); return; }
  paintLove(!want);                         // it did not happen - put the glyph back
  canWriteTags = false;
  const j = await r.json().catch(() => null);
  // Show this ONCE, on the attempt - not on every click, and not as a standing notice.
  showToastOnce(j && j.error ? j.error.message : 'That could not be saved');
}

function paintLove(v) {
  loved = v;
  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)