Design a trusted local controller for mpv JSON IPC

Keep the control boundary local and trusted

mpv's JSON IPC enables a separate program to control a player through a local socket or named pipe. The developer explicitly documents that the protocol lacks authentication and encryption and exposes powerful commands. Plan it for a trusted local process with appropriate operating-system access controls; do not turn the socket into a public network service.

Define the small set of actions the controller needs, such as pausing an owned demonstration and reading playback position. Record the player version, controller identity and how it obtains the intended endpoint. Do not accept arbitrary command arrays from an untrusted web page or treat this interface as a restricted remote-control API.

Design message handling before buttons

The documented protocol uses JSON messages separated by line breaks. A socket read can contain part of a message or several messages, so the controller needs a buffer and a line parser. Preserve the original input bytes until a full message boundary is available, then decode and handle one complete message at a time.

Give commands distinct integer request identifiers and keep a pending-request record. Route a reply by its identifier instead of assigning the next incoming JSON object to the last button clicked. Unsolicited events also arrive, and asynchronous command completions can change the order in which results appear. A useful log records message kind and identifier without leaking sensitive file paths into public diagnostics.

Make outcomes visible to the user

Separate a user action being queued from the player reporting successful completion. The official documentation explains that an asynchronous command does not provide a separate start acknowledgement. A controller that immediately displays completed can therefore misrepresent a command still running or one that ultimately fails.

Define states such as pending, completed, failed and connection lost in the application design. If the connection disappears, do not blindly repeat every outstanding action: a repeated non-idempotent command can have a different effect from a property read. Decide the recovery policy for each allowed action and show uncertainty where the outcome cannot be established.

Verify protocol cases on an isolated player

Before relying on the controller, exercise fragmented input, several messages in one read, an unrelated event between command replies, a command error and player shutdown. Use a disposable owned-media sample and a private endpoint. These are proposed developer checks; no controller was implemented or tested for this guide.

Keep the acceptance record with the protocol version and endpoint permissions. Revisit it when updating mpv or changing asynchronous behaviour. The completed design should explain which local process can control the player, how each reply is matched and what happens when the connection fails, without promising that IPC itself supplies a network security boundary.

Related reading

Questions answered

Sources & further reading

Official references for the subjects discussed. Service terms and device software can change.

• https://github.com/mpv-player/mpv/blob/master/DOCS/man/ipc.rst