Configuration

Environment variables

Everything is configured through environment variables. No config files, no settings UI, no YAML. Set them when you start the server and you're done.

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. Change it if you want playlists somewhere specific.
`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

[Unit]
Description=mpv-web-control
After=network.target

[Service]
Type=simple
User=mpv
WorkingDirectory=/opt/mpv-web-control
ExecStart=/usr/bin/pnpm start
Environment=MUSIC_ROOT=/srv/music
Environment=PORT=3000
Restart=on-failure

[Install]
WantedBy=multi-user.target

Drop this in /etc/systemd/system/mpv-web-control.service and run systemctl enable --now mpv-web-control. Now it starts on boot and restarts if it crashes.

The scripts/install.sh script automates all of this — systemd unit, system user, directory layout, the lot. You only need to write the unit file by hand if you're doing something custom. See Getting Started for the packaged deployment flow.