MBXHub REST API SDK

Version: 0.45 | Base URL: http://localhost:8080

140+ REST endpoints providing full coverage of all 137 MusicBee API methods via both REST and RPC interfaces.

Dashboard NEW in 0.45

The web dashboard provides a full-featured browser-based remote control for MusicBee. Server-side rendered HTML with CSS themes - no JavaScript required for core functionality.

GET /

Redirects to /dashboard

GET /dashboard

Full web dashboard with now playing, player controls, volume, ratings, shuffle toggle, and ARiA presets (if enabled).

Features:

Album artwork display (base64 embedded)
Track info (title, artist, album)
Progress bar with live WebSocket updates
Play/Pause, Stop, Previous, Next buttons
Volume Up/Down, Mute toggle
Love button and 5-star rating
Shuffle/AutoDJ three-state toggle (Off, Shuffle, AutoDJ)
Repeat mode toggle (cycles off → all → one)
Theme switcher (Dark, Light, Midnight) - cookie persisted
ARiA preset buttons (collapsible, when enabled)
Connection indicator (logo turns green when WebSocket connected)

GET /status

Simple HTML status page with link to dashboard.

GET /dashboard/theme?t={theme}

Set theme (dark, light, midnight). Persisted via cookie.

Dashboard Actions (POST with redirect)

All dashboard actions use POST-Redirect-GET pattern. After the action, redirects back to /dashboard with a status message.

Endpoint	Action
`/dashboard/play`	Play/Pause toggle
`/dashboard/stop`	Stop playback
`/dashboard/next`	Next track
`/dashboard/prev`	Previous track
`/dashboard/volup`	Volume +5%
`/dashboard/voldown`	Volume -5%
`/dashboard/mute`	Mute toggle
`/dashboard/shuffle`	Enable shuffle (disables AutoDJ)
`/dashboard/shuffle-off`	Turn off shuffle and AutoDJ
`/dashboard/autodj`	Start AutoDJ
`/dashboard/repeat`	Cycle repeat mode (off → all → one)
`/dashboard/love`	Love toggle
`/dashboard/rate/{1-5}`	Set star rating (click same to clear)
`/dashboard/aria/{preset}`	Execute ARiA preset
`/dashboard/aria-expand`	Expand ARiA presets section
`/dashboard/aria-collapse`	Collapse ARiA presets section

System Endpoints

GET /system/status

Returns system status and enabled modules.

GET /system/ping

Health check endpoint.

GET /system/settings PUT /system/settings

Get or update hub configuration (ports, enabled modules).

Player Control

Playback

POST /player/play POST /player/pause POST /player/playpause POST /player/stop

Navigation

POST /player/next POST /player/previous POST /player/next-album POST /player/previous-album

Volume & Position

GET /player/volume PUT /player/volume GET /player/mute PUT /player/mute GET /player/position PUT /player/position

Shuffle & Repeat

GET /player/shuffle PUT /player/shuffle GET /player/repeat PUT /player/repeat

Audio Processing

GET /player/equalizer PUT /player/equalizer GET /player/dsp PUT /player/dsp GET /player/crossfade PUT /player/crossfade GET /player/replaygain PUT /player/replaygain GET /player/scrobble PUT /player/scrobble

AutoDJ & Advanced

GET /player/autodj POST /player/autodj/start POST /player/autodj/stop GET /player/stopaftercurrent POST /player/stopaftercurrent POST /player/queue-random

Output Devices

GET /player/output-devices PUT /player/output-device

List available audio output devices and switch between them.

Display & State

GET /player/status GET /player/button-enabled GET /player/show-time-remaining GET /player/show-rating-track GET /player/show-rating-love POST /player/show-equaliser

Streaming & Statistics

POST /player/open-stream POST /player/update-play-statistics

Open stream handles and update play/skip counts.

Now Playing

GET /nowplaying

Returns current track info with full metadata.

Track Data

GET /nowplaying/position GET /nowplaying/tag GET /nowplaying/property GET /nowplaying/lyrics GET /nowplaying/downloaded-lyrics

Query params: ?field=TrackTitle or ?type=Bitrate

Artwork

GET /nowplaying/artwork GET /nowplaying/artwork-url GET /nowplaying/downloaded-artwork GET /nowplaying/downloaded-artwork-url

Returns album artwork as binary image or URL.

Artist Pictures

GET /nowplaying/artist-picture GET /nowplaying/artist-thumbnail GET /nowplaying/artist-picture-urls

Soundtrack

GET /nowplaying/is-soundtrack GET /nowplaying/soundtrack-pictures

Audio Analysis

GET /nowplaying/spectrum GET /nowplaying/sound-graph GET /nowplaying/sound-graph-ex

FFT spectrum and waveform data for visualizations.

Queue Management

GET /queue

Returns the now playing list with track metadata. Supports ?offset=0&limit=50

Queue Info

GET /queue/current GET /queue/next-index GET /queue/has-prior GET /queue/has-following

Queue Actions

POST /queue/add POST /queue/playnow POST /queue/clear POST /queue/move POST /queue/play-library-shuffled

Track at Index

GET /queue/{index}/url GET /queue/{index}/tag GET /queue/{index}/property DELETE /queue/{index}

Query params: ?field=Artist or ?type=Duration

Library Browsing

GET /library/files

Query library with ?query=, ?artist=, ?album=, ?genre=, ?offset=, ?limit=

GET /library/search

Full-text search: ?q=search+term

Aggregations

GET /library/artists GET /library/albums GET /library/genres

File Operations

GET /library/file/{url} PUT /library/file/{url} POST /library/add

Get/update file metadata, add files to library.

File Details

GET /library/file/{url}/lyrics GET /library/file/{url}/artwork GET /library/file/{url}/artwork-url GET /library/file/{url}/device-id PUT /library/file/{url}/device-id

Artist Info

GET /library/artist/{name}/similar GET /library/artist/{name}/picture GET /library/artist/{name}/thumbnail GET /library/artist/{name}/pictures

Sync & Device IDs

POST /library/find-device-ids POST /library/sync-delta

Find files by device IDs, get library changes since date.

Playlist Management

List & Create

GET /playlists POST /playlists

Playlist Operations

GET /playlists/{url} PUT /playlists/{url} DELETE /playlists/{url}

Playlist Files

GET /playlists/{url}/files POST /playlists/{url}/files POST /playlists/{url}/play

Pending Files

Files waiting to be processed/added to the library.

GET /pending GET /pending/url GET /pending/tag GET /pending/property

Query params: ?field=TrackTitle or ?type=Size

Podcasts

GET /podcasts

List podcast subscriptions. Query: ?query=

Subscription Details

GET /podcasts/{id} GET /podcasts/{id}/artwork GET /podcasts/{id}/episodes GET /podcasts/{id}/episodes/{index}

MusicBee Settings

GET /settings

Get all MusicBee settings overview.

Individual Settings

GET /settings/storage-path GET /settings/skin GET /settings/skin-element-color GET /settings/window-borders-skinned GET /settings/field-name GET /settings/data-type GET /settings/lastfm-user GET /settings/web-proxy GET /settings/value GET /settings/convert-command

Query params vary: ?field=, ?id=, ?codec=, etc.

MusicBee Application

Window Control

GET /mb/window-handle POST /mb/window-size POST /mb/refresh-panels

Commands & Navigation

POST /mb/command POST /mb/filter POST /mb/nowplaying-assistant

Visualizers & Plugins

GET /mb/visualisers POST /mb/visualiser GET /mb/plugin-views POST /mb/plugin-view

Utilities

GET /mb/localisation POST /mb/download

MusicBee Device Sync

Control MusicBee's internal device synchronization.

POST /mbsync/file/start POST /mbsync/file/end POST /mbsync/file/delete/start POST /mbsync/file/delete/end

Signal file sync start/end for device synchronization.

ARiA - Input Simulation

Simulate keyboard and mouse input to wake or control the host PC. Useful for remote wake scenarios where TMRemote needs to wake a sleeping/locked PC via simple HTTP calls.

Security: ARiA is disabled by default. Enable it in MBXHub settings (ariaEnabled: true). Returns 403 FORBIDDEN when disabled.

GET /aria/status

Check if ARiA input simulation is enabled.

{
  "success": true,
  "data": {
    "enabled": true,
    "message": "ARiA input simulation is enabled"
  }
}

POST /aria/wake

Quick wake: moves mouse slightly and sends a harmless key (Shift) to wake a sleeping/locked PC.

POST /aria/wake
{ }

Response: { "success": true, "data": { "result": true } }

POST /aria/send-keys

Send keyboard input using SendKeys format.

Symbol	Meaning
`^`	Ctrl
`%`	Alt
`+`	Shift
`#`	Win (Windows key)
`{ENTER}`	Enter key
`{ESC}`	Escape key
`{F1}`-`{F12}`	Function keys
`{WIN}`	Windows key (standalone)

POST /aria/send-keys
{ "keys": "^a" }  // Ctrl+A

Response: { "success": true, "data": { "keys": "^a", "result": true } }

POST /aria/mouse/move

Move mouse to absolute coordinates or relative to current position.

// Absolute movement
POST /aria/mouse/move
{ "x": 100, "y": 100 }

// Relative movement
POST /aria/mouse/move
{ "dx": 10, "dy": 0 }

Response: { "success": true, "data": { "x": 100, "y": 100 } }

POST /aria/mouse/click

Click at current position or specified coordinates. Supports left, right, middle buttons.

// Click at current position
POST /aria/mouse/click
{ "button": "left" }

// Move and click
POST /aria/mouse/click
{ "x": 500, "y": 300, "button": "left" }

Response: { "success": true, "data": { "button": "left", "result": true } }

RPC Interface

Direct access to all 137 MusicBee API methods:

POST /rpc/{methodName}

Invoke any MusicBee API method directly by name.

Example:

POST /rpc/Library_GetFileTag
Content-Type: application/json

{
  "fileUrl": "C:\\Music\\song.mp3",
  "field": "TrackTitle"
}

Error Handling

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Error Code	HTTP Status	Description
NOT_FOUND	404	Endpoint or resource not found
INVALID_REQUEST	400	Invalid parameters
ARIA_DISABLED	403	ARiA input simulation is disabled
METHOD_NOT_ALLOWED	405	Wrong HTTP method
INTERNAL_ERROR	500	Server error
SERVICE_UNAVAILABLE	503	Optional module not installed

MBXHub | REST API SDK