Getting started

From zero to playing music in two minutes

You'll need a machine running Linux (a Raspberry Pi, some Debian box, whatever) with mpv installed and a folder full of audio files. That's the whole prerequisite list.

Install mpv

On Debian or Raspberry Pi OS:

sudo apt update
sudo apt install mpv

On macOS it's brew install mpv. On Arch, pacman -S mpv. You know the drill.

Install from npm

For a homelab box, install the CLI globally and let it create the systemd service:

npm install -g mpv-web-control
sudo mpv-web-control install --user <linux-user> --music-root <path> --port <port>

Use the Linux user that can read your music files, for example didi. If you omit --music-root, the CLI prompts for it. If you omit --port, it prompts and defaults to 3000.

The install command writes /etc/mpv-web-control/env, installs the systemd unit, and enables and starts/restarts the service by default.

sudo systemctl status mpv-web-control
sudo journalctl -u mpv-web-control -f

Build from source

If you're hacking on the project, clone it and install workspace dependencies:

git clone <repo-url> mpv-web-control
cd mpv-web-control
pnpm install

Node 22 or newer, pnpm 9 or newer. If you're on a Pi and don't have pnpm yet: corepack enable && corepack prepare pnpm@latest --activate.

Build

pnpm build

This compiles the shared contract package, the Hono backend, and the React frontend in one pass. Takes maybe 15 seconds on a Pi 4.

Run it

MUSIC_ROOT=/mnt/my-music pnpm start

The server binds to 0.0.0.0:3000 by default, so anything on your local network can reach it. Open http://<your-pi-ip>:3000 on your phone or laptop.

If mpv isn't already running in the background, the server starts it for you and connects over a Unix socket at /tmp/mpv-web-control.sock.

Manage the service

To install the unit and config without enabling or starting the service, add --no-enable:

sudo mpv-web-control install --user <linux-user> --music-root <path> --port <port> --no-enable

Runtime config lives at /etc/mpv-web-control/env. Playlist data is stored under /var/lib/mpv-web-control/playlists.

To uninstall:

sudo mpv-web-control uninstall

Uninstall stops, disables, and removes the service, then asks what to do with config and data directories. It does not delete Linux users.

Development mode

If you're hacking on the code, run the backend and frontend separately:

# terminal 1
MUSIC_ROOT=/mnt/music pnpm dev:server

# terminal 2
pnpm dev:client

The frontend dev server runs on Vite's default port (5173) with hot reload. The backend restarts on file changes via tsx watch.

What's next?