Features

What you get

mpv-web-control is deliberately small. It doesn't stream audio over the network, manage a library database, or try to be Spotify. Here's what it actually does.

File browsing

The browser view shows every folder and audio file under MUSIC_ROOT. You can't escape that root — path traversal attempts get rejected flat-out. Folders sort alphabetically. Files show their name and extension. That's it. No metadata scraping, no cover art fetcher, no tags. If you want that, use a proper music manager.

Tap a file to queue it. Tap a folder to queue everything inside, recursively. A safety cap of 5,000 items prevents you from accidentally queuing a mount point (configurable via MAX_FOLDER_ITEMS).

Playback controls

Play. Pause. Next track. Previous track. Stop. They do exactly what they say. The seek bar shows your position in the current track and lets you scrub. The volume slider talks directly to mpv — no intermediate layer, no latency.

All of this happens over mpv's JSON IPC protocol through a Unix domain socket. The backend translates your clicks into IPC commands and pipes them to mpv. Response time is effectively instant on a local network.

Playlist management

Hit "save" on your current queue and it writes a JSON file to disk under PLAYLISTS_DIR. Load that playlist later to replace your queue, or append it to keep what's already playing. Delete playlists you don't want anymore.

The files are plain JSON arrays of file paths. You can edit them by hand, sync them between machines, or version-control them. No database means no schema migrations, no corrupted SQLite files, no "please run npm run migrate" messages.

Security model

This thing runs on your LAN. It's designed for trusted networks — your apartment, your home lab, maybe a small office. Here's what it protects against:

  • Path traversal — the backend rejects .. sequences and absolute paths. You stay inside MUSIC_ROOT.
  • Socket hijacking — the mpv IPC socket lives at a known path. Only the user running the server can talk to it.

What it doesn't have: authentication, rate limiting, CORS restrictions, or CSRF tokens. Don't put this on the public internet. If you need remote access, put it behind a VPN or an SSH tunnel.

What it doesn't do

Some things are deliberately out of scope:

  • No audio streaming — mpv plays locally through whatever audio output the host machine uses.
  • No metadata or tag reading — files are just files.
  • No user accounts or multi-user anything.
  • No mobile app — the web interface works fine in mobile browsers.
  • No lyrics, no scrobbling, no recommendations. It plays the files you tell it to play.