How to Use mpv IPC Server to Control Playback?

The mpv media player includes a powerful Inter-Process Communication (IPC) server feature that allows external applications or scripts to control playback, modify settings, and retrieve status updates in real-time. By enabling a Unix socket or a Windows named pipe, mpv opens a bidirectional communication channel that accepts commands formatted in JSON-IPC. This guide provides a step-by-step walkthrough on how to enable the IPC server, format valid control commands, and send them using common command-line tools like socat or Python scripts.

Step 1: Enabling the IPC Server in mpv

To allow external applications to communicate with mpv, you must start the player with the --input-ipc-server flag specified. This creates a listener at a designated path.

On Linux and macOS (Unix Sockets):

mpv --input-ipc-server=/tmp/mpvsocket video.mp4

On Windows (Named Pipes):

mpv --input-ipc-server=\\.\pipe\mpvsocket video.mp4

Tip: If you want this feature enabled by default without typing the flag every time, add input-ipc-server=/tmp/mpvsocket (or the Windows equivalent) to your mpv.conf configuration file.

Step 2: Understanding the JSON-IPC Format

mpv listens for commands formatted as JSON objects. Every message sent to the server must end with a newline character (\n) so the player knows the command is complete.

The most common structure for a request contains a command key paired with an array of arguments:

{ "command": ["argument1", "argument2", ...] }

Step 3: Sending Commands via the Command Line

Once mpv is running with the IPC server active, you can interact with it using network utilities. The socat utility is the most reliable tool for Unix sockets.

Pausing and Resuming Playback

To toggle the pause state, send the cycle command for the pause property:

echo '{ "command": ["cycle", "pause"] }' | socat - /tmp/mpvsocket

Adjusting Volume

To set the volume to a specific percentage (e.g., 50%):

echo '{ "command": ["set_property", "volume", 50] }' | socat - /tmp/mpvsocket

Seeking Through Media

To skip forward by 10 seconds:

echo '{ "command": ["seek", 10, "relative"] }' | socat - /tmp/mpvsocket

Step 4: Controlling mpv with Python

For integration into larger software projects, programming languages like Python can interact with the socket directly using the built-in socket library.

The following script demonstrates how to connect to an existing mpv IPC instance on a Unix-based system and pause the video:

import socket
import json

socket_path = "/tmp/mpvsocket"

# Create a Unix domain socket connection
client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
client.connect(socket_path)

# Prepare the payload with a trailing newline
payload = { "command": ["set_property", "pause", True] }
message = json.dumps(payload) + "\n"

# Send the command to mpv
client.sendall(message.encode('utf-8'))

# Read the response from the server
response = client.recv(1024)
print("Response:", response.decode('utf-8'))

client.close()

Step 5: Observing Properties and Events

The IPC server is bidirectional. Not only can you send commands, but mpv will also output JSON responses confirming whether a command succeeded or failed. Furthermore, if you keep the connection open, mpv streams event notifications such as file loading changes, playback interruptions, or end-of-file events, allowing your external application to stay perfectly synchronized with the player’s internal state.