Can you run mpv headless without a GUI?

This article explains how to run the popular command-line media player mpv in a headless environment without a graphical user interface (GUI). It covers the specific command-line flags required to disable video output, methods for controlling the media player remotely using the Inter-Process Communication (IPC) socket, and typical use cases such as background audio playback or server-side video processing.

Running mpv Without Video Output

By default, mpv attempts to open a graphical window to render video. However, if you are working via SSH or on a server without an X server or Wayland display, you can suppress the GUI entirely using the --no-video or --vo=null flags.

• For Audio Files: If you only need to play audio, use the --no-video flag. This prevents mpv from looking for a video track or spawning a window. mpv --no-video audiofile.mp3
• For Video Files (Audio Only): If you open a video file with --no-video, mpv will skip video decoding entirely and only play the audio track.
• For Dropping Video Output Completely: If you must process a video file without displaying it (e.g., for testing or network streaming), route the video output to nothingness using the null video output driver. mpv --vo=null inputvideo.mp4

Controlling mpv in a Headless Environment

When running mpv headlessly, you lose standard keyboard shortcuts like spacebar for pausing. To manage playback, you can use mpv’s powerful JSON IPC interface, which allows you to send commands to the player from another terminal window or a script.

1. Start mpv with an IPC Socket

To enable remote control, you must tell mpv to create a socket file when it launches.

mpv --no-video --input-ipc-server=/tmp/mpvsocket audiofile.ogg

2. Send Commands via the Socket

Once the socket is open, you can send JSON-formatted commands using utilities like socat or echo combined with netcat (nc).

• To Pause/Unpause Playback: echo '{ "command": ["cycle", "pause"] }' | socat - /tmp/mpvsocket
• To Adjust Volume: echo '{ "command": ["set_property", "volume", 80] }' | socat - /tmp/mpvsocket
• To Stop Playback and Quit: echo '{ "command": ["quit"] }' | socat - /tmp/mpvsocket

Running mpv as a Background Service

If you need mpv to persist after closing your terminal session, you can run it detached using terminal multiplexers like tmux or screen, or by running it as a background process with nohup.

nohup mpv --no-video --input-ipc-server=/tmp/mpvsocket stream_url &

This setup makes mpv an excellent choice for lightweight home automation audio systems, internet radio streamers on Raspberry Pi devices, or backend media processing tasks.