MBXHub

volup/voldown - Adjust volume by 5%.
volup1/voldown1 - Adjust volume by 1% (fine control).

shuffle=enable, shuffle-off=disable both, autodj=start AutoDJ, repeat=cycle mode

love - Toggle love tag on current track.
rate/0 - Toggle bomb (don't play). Click on → click off.
rate/1-5 - Toggle star rating. Click to set, click same to clear.
ban - Ban track from shuffle, skip to next (undo: skip back within 10s).
setban - Set ban flag without skipping.

mood - Set AutoQ mood channel (form: mood=Energetic).
react/fire|heart|like|dislike|ban - Submit reaction. Fire triggers queue refresh.
refresh-queue - Refresh vibe list and queue tracks.
influence/artist|genre/up|down - Thumbs up/down for artist or genre.

Set pagesPath in mbxhub.json to customize the pages directory:

{
  "pagesPath": "C:\\MyCustomPages"
}

Default location: %APPDATA%\MusicBee\MBXHub\pages\

Set defaultPage to change the root URL redirect:

{
  "defaultPage": "/pages/player.html"
}

Options: /dashboard (default), /pages/player.html, /pages/partymode/, /pages/nowplaying.html, or any custom page.

Kiosk Mode: Lock the display to a single page/app. All navigation redirects to the default page.

{
  "defaultPage": "/pages/partymode/",
  "kioskMode": true
}

Multi-page apps work: sub-paths are allowed (e.g., /pages/partymode/ allows /pages/partymode/guest.html). API calls and resources still work. Only editable in mbxhub.json (not exposed via API).

Serves index.html from the pages directory

Serves any file from the pages directory (HTML, CSS, JS, images, fonts)

• /pages/index.html - Landing page listing available views
• /pages/player.html - Full-featured desktop player with:
  • Now Playing (artwork, title, artist, genre, lyrics)
  • Player controls (play/pause, prev/next, shuffle, repeat, volume, seek)
  • Browse panel (Artists, Albums, Genres, Playlists, Podcasts, Radio, Moods — empty categories auto-hidden)
  • Queue panel (Up Next with Now/Next/Last actions)
  • Vibe score badge, reaction buttons, mood channel selector
  • Influence thumbs, ARiA presets, Love/Ban buttons
  • Live WebSocket updates (including Reaction events)
  • Mobile tab bar (Now Playing / Browse / Queue), tablet 2-column, desktop 3-column with resizable panels
• /pages/nowplaying.html - Focused now-playing view with artwork, lyrics, and queue. Auto-stacks below 800px with accordion sections (Now Playing, Queue, Lyrics) — expanding one collapses the others
• /pages/browse.html - Library browser with 7 responsive tabs (Albums/Artists/Genres/Playlists/Podcasts/Radio/Moods), drilldown navigation, diacritic and punctuation normalized fuzzy search, album art grid, batch queue, and playlist picker
• /pages/config.html - Settings and configuration for dashboard layout and AutoQ parameters
• /pages/autoq.html - AutoQ Tuning Console with mixer-style sliders for scoring weights and normalization ranges
• /pages/phantom.html - Devialet Phantom speaker control: transport, volume, source selection

To customize pages:

1. Navigate to the pages directory (shown in MBXHub settings)
2. Edit player.html or create new HTML files
3. Refresh the browser - changes appear immediately
4. To reset to defaults, delete the pages folder and restart MusicBee

MBXHub serves /llms.txt - an AI-friendly API reference. Use it with Claude or any AI to generate custom pages:

1. Tell Claude: "Read https://mbxhub.com/llms.txt and build me a Party-On-Mode page - big artwork, guest queue requests, vibe controls"
2. Claude fetches the API cheat sheet (public URL works from any AI)
3. Claude generates code using relative URLs (/nowplaying, /player/play) that work on any MBXHub instance
4. Save to %APPDATA%\MusicBee\MBXHub\pages\
5. Open http://localhost:8080/pages/partyon.html

The generated code uses relative URLs, so it works on your local MBXHub without modification.

Use the Settings → Firewall panel or CLI: MBXHub.exe firewall add --name MBXHub --tcp 8080 --udp 1900,3702 --urlacl 8080. mDNS port 5353 is managed by the Windows DNS client service.

Tag fields: TrackTitle, Artist, Album, AlbumArtist, Year, Genre, Rating, RatingLove, Comment, Composer, Conductor, TrackNo, DiscNo, Lyrics, Publisher

Properties: Bitrate, SampleRate, Channels, Duration, Size, DateAdded, DateModified, PlayCount, SkipCount, LastPlayed

Examples:

GET /nowplaying/tag?field=Artist        → {"value": "Breaking Rust"}
GET /nowplaying/tag?field=Album         → {"value": "Love Don't Live Here"}
GET /nowplaying/tag?field=Genre         → {"value": "Rock"}
GET /nowplaying/tag?field=TrackNo       → {"value": "3"}
GET /nowplaying/property?type=Bitrate   → {"value": "320"}
GET /nowplaying/property?type=Duration  → {"value": "234000"} (ms)
GET /nowplaying/property?type=PlayCount → {"value": "42"}

Returns album artwork as binary image or URL

FFT spectrum and waveform data for visualizations

// POST /queue/add - Add tracks to queue (position: "next" or "last")
{"urls": ["file:///C:/Music/song1.mp3", "file:///C:/Music/song2.mp3"], "position": "last"}
// or single track:
{"url": "file:///C:/Music/song.mp3", "position": "next"}
// Response: {"success": true, "data": {"result": true, "added": 2, "position": "last"}}

// POST /queue/playnow - Play track immediately
{"url": "file:///C:/Music/song.mp3"}

// POST /queue/play - Play track at index
{"index": 3}

// POST /queue/move - Move track in queue
{"from": 5, "to": 2}

/library/albums/detailed returns albums with firstTrackUrl, year, and dateAdded for artwork lookups and sorting. Eliminates per-album /library/files?limit=1 round-trips. Params: ?offset=&limit=

/library/album-artists returns distinct album artists. Params: ?offset=&limit=

Note: URL-encode the file path in the URL (e.g., /library/file/file%3A%2F%2F%2FC%3A%2FMusic%2Ftrack.mp3)

// GET /library/file/{url} - Extended track metadata (includes playCount, lastPlayed, etc.)
{
  "success": true,
  "data": {
    "url": "file:///C:/Music/Artist/Album/track.mp3",
    "title": "Love Don't Live Here",
    "artist": "Breaking Rust",
    "album": "Greatest Hits",
    "duration": 234000,
    "albumArtist": "Breaking Rust",
    "genre": "Rock",
    "year": "2024",
    "trackNo": "3",
    "discNo": "1",
    "rating": "4.5",
    "composer": "J. Smith",
    "bitrate": "320",
    "format": "MPEG Audio",
    "sampleRate": "44100",
    "playCount": 42,
    "dateAdded": "2024-01-15",
    "lastPlayed": "2024-01-20"
  }
}

// PUT /library/file/{url} - Update metadata (fields: title, artist, album, albumArtist, genre, year, trackNo, discNo, composer, comment, rating)
{"rating": "5", "comment": "Great track!"}
// Response: {"success": true, "data": {"result": true, "updated": ["rating", "comment"]}}

// POST /library/artwork/batch - Batch artwork fetch (max 50 URLs per request)
// Request: {"urls": ["D:\\Music\\track1.mp3", "D:\\Music\\track2.flac"]}
// Response: {"success": true, "data": {"D:\\Music\\track1.mp3": "data:image/jpeg;base64,/9j/...", "D:\\Music\\track2.flac": null}}

// GET /playlists - List all playlists
{
  "success": true,
  "data": {
    "total": 5,
    "playlists": [
      {"url": "playlist://Favorites", "name": "Favorites", "trackCount": 120},
      {"url": "playlist://Workout", "name": "Workout", "trackCount": 45},
      // ... more playlists
    ]
  }
}

// POST /playlists - Create new playlist
{"name": "New Playlist", "folder": "", "files": ["file:///C:/Music/song1.mp3"]}
// Response: {"success": true, "data": {"url": "playlist://New Playlist", "name": "New Playlist", "trackCount": 1}}

// PUT /playlists/{url} - Replace playlist contents
{"files": ["file:///C:/Music/song1.mp3", "file:///C:/Music/song2.mp3"]}

// GET /playlists/{url}/files - Get playlist tracks (supports pagination: ?offset=0&limit=50)
{
  "success": true,
  "data": {
    "total": 120,
    "offset": 0,
    "limit": 50,
    "tracks": [
      {"index": 0, "url": "file:///...", "title": "Song", "artist": "Artist", "album": "Album", "duration": 234000},
      // ... more tracks
    ]
  }
}

// POST /playlists/{url}/files - Add tracks to playlist
{"urls": ["C:\\Music\\song.mp3"]}

Party Mode settings are configured in MusicBee via Settings → Network → Party Mode...

Protect Metadata: When enabled, blocks PUT /track/{}/love, PUT /track/{}/rating, and PUT /track/{}/tags for everyone during the party. Use this to prevent guests from permanently modifying your library ratings. The setting also blocks the DJ—toggle it off temporarily if you need to make edits.

Built-in pages at /pages/partymode/:

• index.html - PIN + nickname entry (guest join page)
• guest.html - Browse 7 tabs (Albums, Artists, Genres, Playlists, Podcasts, Radio, Moods), fuzzy search, request songs, vote on vibes
• dj.html - Start/stop party, set PINs, manage queue, see requests & vibes
• display.html - TV mode: artwork, lyrics, request feed, QR code, floating reactions
• leaderboard.html - Party stats: guest activity, top tracks, reaction counts

Reset the shuffle cycle. All tracks become unplayed.

Tracks played/remaining in shuffle cycle. Query: ?offset=&limit=

// POST /banlist - Ban a track
{"url": "file:///C:/Music/track.mp3", "reason": "Corrupted audio at 2:30"}

// DELETE /banlist/{url} - Unban a track (URL-encode the file path)

// POST /influences - Add an influence
{"type": "--", "target": "Genre", "value": "Audiobook"}
// type: "++" (more) or "--" (less/exclude)
// target: "Genre" or "Artist"

// DELETE /influences/Genre/Audiobook - Remove specific influence

// POST /influences/clear - Clear all influences (reset preferences)

Tiered reactions for the now playing track. Each emoji has a different score weight.

// Request body (always reacts to currently playing track):
{
  "emoji": "🔥",
  "nickname": "Mike"
}
// emoji: "🔥", "❤️", "👍", "👎", "🚫" or "fire", "heart", "like", "dislike", "ban"

// Response:
{
  "success": true,
  "data": {
    "recorded": true,
    "emoji": "🔥",
    "trackUrl": "C:\\Music\\track.mp3",
    "trackTitle": "Uptown Funk",
    "trackArtist": "Mark Ronson",
    "nickname": "Mike"
  }
}

// Response:
{
  "success": true,
  "data": {
    "count": 25,
    "trackUrl": null,
    "reactions": [
      {
        "emoji": "🔥",
        "type": "fire",
        "trackUrl": "C:\\Music\\track.mp3",
        "trackTitle": "Uptown Funk",
        "trackArtist": "Mark Ronson",
        "nickname": "Haro",
        "timestamp": "2026-02-01T20:45:00Z"
      }
    ]
  }
}

AutoQ settings in mbxhub.json under the autoQ section:

Scoring weights under autoQ.scoringWeights: featureSimilarity (0.5), trackSentiment (0.25), artistSentiment (0.15), recencyPenalty (0.3), diversityPenalty (0.6), explorationBonus (0.1), influenceWeight (0.3).

Reaction scores under autoQ.reactionScores: fire (3), heart (2), like (1), dislike (-1), ban (-100).

Estimation settings under autoQ.estimation: usePercentileNormalization (true) — ranks each feature against the library for automatic 0-1 spread. When false, uses absolute ranges below. useGenreAdjustment (true) — applies genre-specific weight multipliers to V/A computation (e.g., BPM matters less for EDM, chord changes matter more for jazz). moodMatchMinSimilarity (0.5), moodComboMaxResults (3), moodComboMinScore (0.85), bpmMin (80), bpmMax (170), ratingScale (5.0), yearMin (1950), yearMax (2030), playCountLogDivisor (4.0).

Confidence scoring under autoQ.estimation: confidenceEssentiaBase (0.9), confidenceFallbackGenre (0.45), confidenceFallbackNone (0.2) — base confidence by data source. confidenceMinForTag (0.3) — skip writing mood tag when confidence is below this threshold. Confidence = sourceBase × channelProximity (how close V/A lands to nearest mood channel).

Genre profiles under autoQ.genreProfiles: dictionary of genre name → weight multiplier profile. Each profile has 14 multipliers (8 arousal: bpm, loudness, flux, centroid, dance, onsetRate, zcr, rms; 6 valence: mode, valDance, dissonance, pitchSalience, chords, mfcc). Values are multiplied against base weights then renormalized. Built-in profiles cover electronic, metal, jazz, classical, hip-hop, folk, pop/rock, and R&B. Set to null to use built-in defaults.

Valence weights (positivity, 6 active inputs) under autoQ.estimation: valenceWeightMode (0.35), valenceWeightCentroid (0.0 — centroid is an arousal feature), valenceWeightDance (0.05), valenceWeightFlatness (0.0), valenceWeightDissonance (0.25), valenceWeightPitchSalience (0.10), valenceWeightChords (0.15), valenceWeightMfcc (0.10). Mode scoring: modeScoreMajor (0.85), modeScoreMinor (0.4).

Arousal weights (energy/intensity, 8 inputs) under autoQ.estimation: arousalWeightBpm (0.25), arousalWeightLoudness (0.20), arousalWeightFlux (0.15), arousalWeightCentroid (0.05), arousalWeightDance (0.02), arousalWeightOnsetRate (0.15), arousalWeightZcr (0.08), arousalWeightRms (0.10).

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), mfccMin/Max (70/220).

Mood Quadrants — Arousal (energy) is the vertical axis, valence (positivity) is the horizontal. Each mood channel targets a point in this space.

Move: {"x":100,"y":100} (absolute) or {"dx":10,"dy":0} (relative)

Click: {"button":"left"} or {"x":500,"y":300,"button":"right"}

List available presets

Execute a preset by name (e.g., /aria/preset/RIA3)

Note: New clients receive ALL events by default. Once you send a subscribe message, you only receive those specific events. Use unsubscribe to stop receiving events without disconnecting.

// Subscribe to specific events (filters to only these events)
{"subscribe": ["TrackChanged", "PlayStateChanged"]}

// Unsubscribe from events (stop receiving them)
{"unsubscribe": ["PositionChanged"]}

// Subscribe to all events (equivalent to no subscriptions)
{"subscribe": ["TrackChanged", "PlayStateChanged", "VolumeChanged",
              "PositionChanged", "QueueChanged", "ShuffleChanged",
              "RepeatChanged", "MetadataChanged", "Reaction",
              "TasteChanged"]}

// TrackChanged
{
  "event": "TrackChanged",
  "timestamp": "2024-01-03T12:00:00.000Z",
  "data": {
    "fileUrl": "C:\\Music\\song.mp3",
    "title": "Track Title",
    "artist": "Artist Name",
    "album": "Album Name",
    "duration": 245000,
    "artworkUrl": "/nowplaying/artwork"
  }
}

// PlayStateChanged
{
  "event": "PlayStateChanged",
  "timestamp": "2024-01-03T12:00:00.000Z",
  "data": {
    "state": "playing"  // "playing", "paused", "stopped"
  }
}

// VolumeChanged
{
  "event": "VolumeChanged",
  "timestamp": "2024-01-03T12:00:00.000Z",
  "data": {
    "volume": 75,  // 0 to 100
    "muted": false
  }
}

// PositionChanged
{
  "event": "PositionChanged",
  "timestamp": "2024-01-03T12:00:00.000Z",
  "data": {
    "position": 45000,   // Current position in milliseconds
    "duration": 245000   // Total duration in milliseconds
  }
}

// QueueChanged
{
  "event": "QueueChanged",
  "timestamp": "2024-01-03T12:00:00.000Z",
  "data": {
    "action": "add",    // "add", "remove", "clear", "move"
    "index": 5,
    "totalTracks": 42
  }
}

// ShuffleChanged
{
  "event": "ShuffleChanged",
  "timestamp": "2024-01-03T12:00:00.000Z",
  "data": {
    "enabled": true
  }
}

// RepeatChanged
{
  "event": "RepeatChanged",
  "timestamp": "2024-01-03T12:00:00.000Z",
  "data": {
    "mode": "all"  // "none", "all", "one"
  }
}

// MetadataChanged
{
  "event": "MetadataChanged",
  "timestamp": "2024-01-03T12:00:00.000Z",
  "data": {
    "fileUrl": "C:\\Music\\song.mp3",
    "rating": 3,      // -1 (unrated) to 5
    "love": "L"       // "L" (loved), "B" (banned), or "" (neither)
  }
}

// Reaction
{
  "event": "Reaction",
  "timestamp": "2024-01-03T12:00:00.000Z",
  "data": {
    "emoji": "fire",
    "type": "fire",       // fire, heart, like, dislike, ban
    "nickname": "Guest",
    "trackTitle": "Song Name",
    "trackArtist": "Artist"
  }
}

// TasteChanged (debounced, fires after reactions/influences/mood changes)
{
  "event": "TasteChanged",
  "timestamp": "2024-01-03T12:00:05.000Z",
  "data": {
    "profile": {
      "topGenres": [{ "name": "Rock", "weight": 1.0 }],
      "topArtists": [{ "name": "Foo Fighters", "weight": 0.85 }],
      "bpmRange": [90, 160],
      "mood": "Energetic",
      "moodConfidence": 0.88,
      "influenceCount": 3,
      "reactionCount": 12
    }
  }
}

// Connect to WebSocket
const ws = new WebSocket('ws://localhost:8080/');

ws.onopen = function() {
  console.log('Connected to MBXHub');

  // Optional: Subscribe to specific events only
  // Without this, you receive ALL events
  ws.send(JSON.stringify({
    subscribe: ['TrackChanged', 'PlayStateChanged', 'PositionChanged']
  }));
};

ws.onmessage = function(event) {
  const msg = JSON.parse(event.data);

  switch (msg.event) {
    case 'TrackChanged':
      console.log('Now playing:', msg.data.title, '-', msg.data.artist);
      break;
    case 'PlayStateChanged':
      console.log('State:', msg.data.state);
      break;
    case 'PositionChanged':
      const pct = (msg.data.position / msg.data.duration * 100).toFixed(1);
      console.log('Position:', pct + '%');
      break;
  }
};

ws.onclose = function() {
  console.log('Disconnected from MBXHub');
};

ws.onerror = function(err) {
  console.error('WebSocket error:', err);
};

// Later: Unsubscribe from position updates (too frequent)
ws.send(JSON.stringify({ unsubscribe: ['PositionChanged'] }));

// Clean disconnect
ws.close();

Logging is controlled by two settings in mbxhub.json:

Log files are stored in the MBXHub subfolder of MusicBee's persistent storage:

%AppData%\MusicBee\MBXHub\mbxhub.log

• Log files are automatically rotated when they reach 2MB (debug) or 5MB (normal)
• Old logs are archived as mbxhub.1.log, mbxhub.2.log, etc.
• Maximum 5 archive files in debug mode, 3 otherwise

To enable debug logging:

// In mbxhub.json:
{
  "debugMode": true,
  "logLevel": "Trace"  // or "Debug", "Info", "Warning", "Error"
}

HTTP requests are logged at Info level with timing:

2025-01-25 14:32:15 [INFO ] [REST] HTTP GET /player/status -> 200 (12ms)
2025-01-25 14:32:16 [INFO ] [REST] HTTP POST /player/playpause -> 200 (8ms)
2025-01-25 14:32:17 [INFO ] [Plugin] Track changed: Artist Name - Track Title
2025-01-25 14:32:17 [INFO ] [WebSocket] WS client abc12345 connected from 192.168.1.50:54321

PartyMode uses PIN-based authentication with three roles:

PartyMode endpoints authenticate via the X-Party-PIN header:

# Guest request example
curl -X POST http://localhost:8080/partymode/request \
  -H "X-Party-PIN: 1234" \
  -H "Content-Type: application/json" \
  -d '{"url":"C:\\Music\\Track.mp3","nickname":"Haro"}'

# Validate PIN and get role
GET /partymode/validate?pin=1234&nickname=Haro

Invalid or missing PIN returns 401 Unauthorized.

MBXHub supports three protection levels for different deployment scenarios:

Configure via kioskMode and apiReadOnlyMode in settings.

PartyMode includes built-in limits and optional per-IP rate limiting:

Built-in limits (always active):

• Join deduplication: Same nickname can only trigger join announcement once per 60 seconds
• Request history: Maximum 100 entries kept in memory per session
• Feed buffer: Maximum 100 items (joins + requests + votes)

Per-IP rate limiting (configurable via Settings → Party Mode...):

• Requests/min: Max song requests per minute per IP (default: 10)
• Votes/min: Max votes per minute per IP (default: 30)

Returns 429 Too Many Requests when limits exceeded.

• Maximum request body size: 1 MB
• Content-Type validation for JSON endpoints
• No stack traces exposed in error responses

MBXHub can restrict write operations via settings with granular per-operation controls:

Restriction Hierarchy:

• Master read-only - Blocks all write operations API-wide
• Category restriction - Blocks all operations within a category
• Operation restriction - Blocks specific operations only

Settings cascade: master OR category OR operation = blocked

Granular Operations:

Default Settings:

The philosophy: player and queue are open, destructive operations are locked. Playlists, tag edits, and file deletion default to read-only.

Settings cascade: master OR category OR operation = blocked. The granular playlist settings default to false but are moot because their parent apiReadOnlyPlaylists is true.

Always Permitted (exempt from restrictions):

• All GET requests - Browse, search, view queue, get status, stream audio/artwork
• PartyMode guest actions - Song requests, voting, viewing party queue
• PartyMode DJ role - When party active, DJ bypasses restrictions for player/queue/shuffle

Blocked requests return 403 Forbidden:

{"success":false,"error":{"code":"READ_ONLY","message":"API is in read-only mode"}}

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

// Example: GET /library/file/C%3A%5CMusic%5CArtist%5CTrack.mp3

Most list endpoints support offset and limit query parameters:

• Default limit: 50
• Maximum limit: 10000
• Example: GET /library/files?offset=100&limit=50

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

Shuffle, banlist, and influence endpoints require TrueShuffle or AutoQ to be enabled. Check availability:

GET /shuffle/status
// Returns 503 SERVICE_UNAVAILABLE if TrueShuffle/AutoQ not enabled

For real-time updates (track changes, state changes), use WebSocket instead of polling:

• Use REST for: Commands (play, pause), queries (get queue, search)
• Use WebSocket for: Real-time UI updates, visualizations, progress bars
• See WebSocket Events section

By default, MBXHub only accepts localhost connections. For network access:

1. Enable allowRemoteConnections in settings
2. Configure Windows Firewall (use Settings → Firewall → Add Rule)
3. Clients connect to your PC's IP address (e.g., http://192.168.1.100:8080)

MBXHub automatically detects CUE-backed audio files and resolves per-track metadata across all surfaces:

• Player status (/player/status) - Overlays title, artist, trackNo, album from CUE sheet
• Position (/nowplaying/position) - Includes cueTrack and cueTitle
• Tags (/nowplaying/tag) - Returns CUE track data for TrackTitle, Artist, Album, TrackNo
• WebSocket - track events include cueTrack field when CUE active
• Dashboard - Now-playing shows resolved CUE track metadata

Encoding detection: BOM check → UTF-8 validation → Windows-1252 fallback. Optional CueSharp.dll in Plugins folder enables enhanced parsing via reflection.