cthelight/mpd-wui repository overview

⁠MPD Web UI (mpd-wui)

A single-binary, self-contained web UI for Music Player Daemon (MPD)⁠. One Rust process serves the embedded frontend, a JSON API, and a live WebSocket status stream on a single port — and bridges to an existing MPD server over TCP. No build step, no external services, no runtime CDN or font lookups: all media, metadata, and album art come straight from your MPD server.

⁠Highlights

• Now Playing — art, transport controls, seek, volume, and playback modes, plus a persistent mini-player
• Queue — play (replaces the queue with the played song), remove, clear, shuffle, and drag-to-reorder
• Library — debounced fuzzy search (filterable by songs, artists, and albums), folder browsing, and collections by artist, album artist, album, genre, and year
• Live updates — status and change events over WebSocket with locally interpolated progress
• Shareable & browser-native — every view (tab, files level, collection drill, search) is a history entry that reloads or shares as a URL
• Minimal & private — dark, dependency-free UI with no external content and no telemetry
• Tiny image — multi-stage build of a statically linked (musl) binary on scratch: the image is the single ~5 MB binary and nothing else, running as a non-root user

⁠Quick start

Point it at an MPD server on the Docker host:

docker run -d \
  --name mpd-wui \
  -p 8080:8080 \
  -e MPD_HOST=host.docker.internal \
  -e MPD_PORT=6600 \
  -e MPD_PASSWORD=secret \
  --add-host host.docker.internal:host-gateway \
  cthelight/mpd-wui

Then open http://localhost:8080⁠.

Or with Docker Compose:

services:
  mpd-wui:
    image: <yourname>/mpd-wui
    ports:
      - "8080:8080"
    environment:
      MPD_HOST: host.docker.internal
      MPD_PORT: 6600
      MPD_PASSWORD: secret
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: unless-stopped

⁠Configuration

CACHE_TTL controls how often the in-process library snapshot used for search is rebuilt; a stale snapshot is served immediately and refreshed in the background. Album art is cached separately for one hour.

⁠Security notes

The web server performs no authentication of its own and binds 0.0.0.0 by default. Anyone who can reach the port can control playback and the queue, so restrict access with a firewall (or set BIND_ADDR=127.0.0.1 for local-only use) and rely on MPD_PASSWORD for the MPD bridge itself.

⁠How it works

The container runs one statically linked release binary (musl — no base libraries or filesystem required) that embeds the entire frontend (vanilla HTML/CSS/JS). It connects out to your MPD server over TCP, so MPD and your music library never need to be exposed — only this container's single web port does.