Configuration

Environment variables

Everything is configured through environment variables. For the systemd install, those variables live in /etc/mpv-web-control/env. For manual runs, set them when you start the server.

Variable	Default	What it does
`HOST`	`0.0.0.0`	Bind address. Default listens on all interfaces so LAN devices can connect. Set to `127.0.0.1` if you only want local access.
`PORT`	`3000`	Server port. Change this if something else is using 3000.
`MUSIC_ROOT`	Current working directory	The root folder for browsing and playback. This is the only required variable you should actually care about. Point it at your music collection.
`PLAYLISTS_DIR`	`.mpv-web-control/playlists` under CWD	Where playlist JSON files are stored. Defaults to a hidden directory in your working dir. The systemd install stores playlists under `/var/lib/mpv-web-control/playlists`.
`MPV_SOCKET_PATH`	`/tmp/mpv-web-control.sock`	Path to the mpv IPC socket. If you're running multiple instances, give each one its own socket.
`MPV_BIN`	`mpv`	Path to the mpv binary. Only change this if mpv is installed in a non-standard location or you want to use a specific version.
`MAX_FOLDER_ITEMS`	`5000`	Safety cap for recursive folder queueing. Prevents accidentally adding tens of thousands of files to your queue because you clicked the wrong folder.

Typical setups

Basic — Pi with a USB drive

MUSIC_ROOT=/media/usb/music pnpm start

The USB drive is mounted at /media/usb. Your music lives in a folder called music. That one variable is all you need.

Advanced — custom paths and port

MUSIC_ROOT=/srv/audio \
PLAYLISTS_DIR=/srv/data/playlists \
MPV_SOCKET_PATH=/run/mpv/control.sock \
PORT=8080 \
pnpm start

Running on a proper server with dedicated paths. The socket goes in /run (tmpfs, cleaned on reboot). Port 8080 because 3000 is taken by something else.

systemd service

npm install -g mpv-web-control
sudo mpv-web-control install --user didi --music-root /srv/music --port 3000

The install command writes /etc/mpv-web-control/env, installs the systemd unit, and enables and starts/restarts the service by default. --user controls the service user, so use an account that can read the music files.

Omit --music-root to be prompted for it. Omit --port to be prompted with a default of 3000. Add --no-enable if you want to install the unit and config without starting it.

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