mpv JSON IPC Commands Failing: How to Fix It

When mpv JSON IPC commands connect but return errors, produce no visible result, or appear to be ignored, the IPC socket itself is not always the problem. The most common causes are malformed JSON command arrays, confusion between command names and property names, missing newline delimiters, incorrect argument types, shell escaping, and file paths that are interpreted differently than expected. The right approach is to prove that a minimal command works, inspect mpv's reply, and then add your real command parameters one at a time.

This guide focuses on IPC command syntax while also covering the surrounding issues that can make a valid command fail on Windows, Linux, or macOS. After each test, you will know what success looks like and whether you should stop changing settings or continue investigating.

1. Confirm the Symptom With a Minimal Clean mpv Command

Start mpv without your normal configuration and create a temporary IPC endpoint. This separates command syntax problems from scripts, profiles, input bindings, shaders, hardware decoding, subtitle settings, and other customizations.

1.1 Start a clean IPC server

On Linux or macOS, open a terminal and run:

mpv --no-config --idle=yes --input-ipc-server=/tmp/mpvsocket

On Windows PowerShell, use a named pipe:

mpv.exe --no-config --idle=yes --input-ipc-server=\\.\pipe\mpv-ipc

The --idle=yes option keeps mpv running without requiring a file. The --no-config option temporarily prevents user configuration files and scripts from affecting the test. It does not delete or modify your configuration.

Success means the mpv process remains open and creates the requested socket or named pipe. If mpv exits immediately, read the terminal output before testing JSON. An unavailable endpoint, invalid path, or second process attempting to use the same endpoint must be corrected first.

1.2 Send the smallest useful JSON command

An mpv IPC request is normally a JSON object containing a command member. That member must be an array. Each request must end with a newline character.

{"command":["get_property","mpv-version"],"request_id":1}

A successful response resembles:

{"data":"...","request_id":1,"error":"success"}

The exact version string is not important. The decisive result is "error":"success", with the same request_id you sent. Once this command works, stop changing the IPC endpoint, permissions, and socket connection. The transport is functioning, so troubleshoot the failing command itself.

On Unix-like systems, a tool such as socat can send a newline-terminated request:

printf '%s\n' '{"command":["get_property","mpv-version"],"request_id":1}' | socat - /tmp/mpvsocket

Do not assume that every netcat variant supports Unix-domain sockets in the same way. If you are writing an application, test through the same socket library and framing method that the application actually uses.

2. Correct JSON IPC Command Syntax

If the minimal property request succeeds but your real command fails, compare its structure with known-good IPC syntax. A connection only proves that bytes can reach mpv. It does not prove that the bytes form a valid JSON request or a valid mpv command.

2.1 Use a JSON command array

The first item in the array is the command name. Remaining items are separate arguments in the order expected by that command.

{"command":["set_property","pause",true],"request_id":2}

Common mistakes include placing the entire command in one string, sending an object where an array is expected, or encoding booleans and numbers as strings.

{"command":"set pause yes"}
{"command":["set_property pause true"]}
{"command":["set_property","pause","true"]}

These forms are not equivalent to the correct request. In particular, JSON true is a Boolean value, while "true" is text. Some properties permit conversion, but relying on implicit conversion makes failures harder to diagnose.

Success means the reply reports "error":"success" and the requested state changes. Confirm it with a second request rather than relying only on the interface:

{"command":["get_property","pause"],"request_id":3}

2.2 Distinguish commands from properties

Commands perform actions. Properties represent readable or writable player state. For example, loadfile is a command, while pause, volume, aid, sid, and path are properties.

{"command":["loadfile","/media/video.mkv","replace"],"request_id":10}
{"command":["set_property","volume",50],"request_id":11}
{"command":["get_property","path"],"request_id":12}

Do not send a property as though it were an action:

{"command":["pause",true]}

Use set_property to change a property. Conversely, do not assume every command has a corresponding writable property. If mpv replies that a command is not found or a property is unavailable, verify the name and whether it belongs to the command interface or property interface.

2.3 Terminate every request with a newline

The JSON IPC protocol uses newline-delimited JSON. A request can be valid JSON yet remain unprocessed if your client never sends the terminating newline. This frequently explains a connection that stays open while mpv appears to do nothing.

{"command":["get_property","pause"],"request_id":20}\n

In application code, \n must become an actual line-feed byte. Do not accidentally send the two visible characters backslash and n. Also flush buffered output after writing. Success means mpv returns a complete newline-terminated reply without waiting for the connection to close.

2.4 Read error replies instead of discarding them

Every troubleshooting client should log the complete reply, including error, data, and request_id. A write that completes successfully only confirms that the operating system accepted the bytes.

• success means mpv accepted the command, although a later media operation can still fail.
• A command-related error usually points to the command name, argument count, or argument type.
• A property-related error suggests a misspelled, unavailable, or non-writable property.
• A malformed request may indicate invalid JSON or an invalid request structure.

Assign a unique request_id to each request. IPC clients can also receive asynchronous events, so assuming that the next line is always the reply to the last command is unsafe. Match responses by identifier.

3. Fix Paths and loadfile Parameters

The loadfile command is a common source of mpv JSON IPC commands failing because one path passes through multiple parsers. The JSON parser, programming language, shell, and operating system may each have their own escaping rules.

3.1 Escape Windows paths as JSON

A backslash introduces an escape sequence in JSON. A Windows path therefore needs escaped backslashes when written directly in JSON:

{"command":["loadfile","C:\\Videos\\Example File.mkv","replace"],"request_id":30}

Forward slashes are often simpler where accepted:

{"command":["loadfile","C:/Videos/Example File.mkv","replace"],"request_id":31}

If your programming language serializes an object with a real JSON library, provide the ordinary path string to the serializer. Do not manually add extra escaping unless the language literal itself requires it. Double escaping can cause mpv to receive literal backslashes that are not part of the intended path.

3.2 Preserve spaces and special characters

A JSON array keeps the entire path as one string, so spaces do not need shell-style quoting inside the value. They do require proper JSON string quotes. Apostrophes do not have special meaning to JSON, but they may affect an outer shell command. Quotes inside filenames must be escaped according to JSON rules.

When testing through a shell, save the request in a small script or file if quoting becomes unclear. Better still, use a JSON serializer and a socket API. That removes a layer of shell interpretation.

3.3 Use valid loadfile arguments

A basic replacement request is:

{"command":["loadfile","/home/user/Videos/test.mkv","replace"],"request_id":32}

To add an item to the playlist, use an appropriate load mode supported by the installed mpv command interface, such as:

{"command":["loadfile","/home/user/Videos/next.mkv","append-play"],"request_id":33}

Do not combine the path, mode, and options into one array element. Do not copy positional parameters from an unrelated wrapper library without checking the mpv manual. Command interfaces can gain parameters over time, while the basic path-and-mode form remains easier to isolate.

After loadfile returns success, query path or playlist. If the command succeeds but playback later fails, syntax is no longer the primary problem. Inspect file access, network access, demuxing, decoding, or output logs instead.

4. Observe Properties Correctly

Property observation is asynchronous. The observe_property command registers an observer and mpv subsequently emits property-change events on the same connection.

{"command":["observe_property",100,"pause"],"request_id":40}

The number 100 is the observer ID chosen by your client. It is not the request ID. A typical event includes the observer ID, property name, and current data:

{"event":"property-change","id":100,"name":"pause","data":false}

Keep reading from the connection after registration. If your program reads one reply and then stops, observation may appear broken even though mpv registered it successfully. Likewise, your parser must distinguish event objects from command replies.

To stop observing, pass the same observer ID:

{"command":["unobserve_property",100],"request_id":41}

Success means registration returns an error value of success and changing the property produces a matching event. Once events arrive reliably, do not modify playback, GPU, subtitle, or audio settings to fix the observer.

5. Check Settings Directly Related to the Failing Command

A syntactically valid IPC command can depend on current playback state. Test the exact property or action involved rather than changing unrelated mpv options.

5.1 Tracks, subtitles, audio, and video

If setting sid, aid, or vid seems ineffective, first inspect available tracks:

{"command":["get_property","track-list"],"request_id":50}

Use an actual track ID reported by mpv. A file may have no subtitle track, an external subtitle may have failed to load, or the selected track may already be active. An IPC success response means the property assignment was accepted, not that the chosen media necessarily contains visible dialogue at the current timestamp.

For external subtitles, test the subtitle command with an absolute, correctly escaped path. Then inspect track-list again. Stop changing IPC syntax once the new track appears.

5.2 Screenshots and output-dependent actions

A screenshot command can fail or seem ineffective if no video is loaded, the destination is unwritable, or the screenshot directory and filename template produce an unexpected location. Start with a loaded local file and a basic screenshot command:

{"command":["screenshot","video"],"request_id":51}

Read both the IPC response and terminal log. If mpv reports success, locate the resolved screenshot output before changing drivers or hardware decoding. If it reports a write error, check the destination path and permissions.

5.3 Online URLs, yt-dlp, and streams

When loadfile works for a local file but not an online URL, JSON syntax and IPC transport are already proven. The remaining cause may be network access, an expired stream URL, unsupported authentication, or an unavailable external URL resolver such as yt-dlp.

Run the same URL directly from a terminal with the same mpv executable. If it fails there too, troubleshoot URL resolution or network access rather than rewriting the IPC client. Use a trusted installation source for external tools and verify that mpv can find the intended executable through its environment or configured path.

5.4 Hardware decoding, HDR, and output drivers

Commands that load media can return success before video initialization completes. A later black screen, decoder failure, HDR problem, or output-driver error is not necessarily an IPC failure. Test the file with --hwdec=no or a conservative output configuration only when the log points to decoding or rendering.

If audio plays but video does not, inspect the selected video track and video output messages. If video plays but there is no audio, inspect aid, mute, volume, and audio backend messages. Do not change GPU drivers, display-server settings, or audio backends merely because an IPC request returned an error about malformed parameters.

6. Use mpv Diagnostics to Find the Exact Failure

mpv provides enough diagnostic output to distinguish an invalid IPC request from a media, script, or output problem.

6.1 Increase message detail and write a log

Launch a clean test with verbose IPC-related logging and a log file:

mpv --no-config --idle=yes --input-ipc-server=/tmp/mpvsocket --msg-level=ipc=v --log-file=mpv-ipc.log

On Windows, substitute the named-pipe endpoint and a writable log path. Reproduce one failure, close mpv normally, and search the log for the request, command name, property name, file path, and error. Avoid enabling maximum verbosity permanently because logs can become large and noisy.

6.2 Inspect profiles and configuration

If the command works with --no-config but fails during normal use, configuration is relevant. Use --show-profile=PROFILE_NAME to inspect a named profile you suspect. Also check whether scripts react to property changes or file-load events and then overwrite the value set through IPC.

Temporarily disable one relevant script or option at a time. Do not delete the entire configuration folder. A reversible rename of one script, profile, or option line preserves evidence and makes the cause easier to identify.

6.3 Use the stats overlay and track list

The stats overlay can confirm whether playback is active, which codecs are in use, and whether frames are being dropped. The track-list property provides machine-readable information for IPC clients. These tools are useful after a command has successfully loaded media but the expected audio, video, or subtitle result is missing.

Stop changing JSON once mpv acknowledges the command and diagnostic state confirms the requested property. At that point, investigate the media or output subsystem indicated by the log.

7. Check Operating System and Client-Side Boundaries

If even the minimal request cannot be exchanged, examine the boundary between your client and mpv.

7.1 Socket and named-pipe permissions

On Linux and macOS, the client must be able to access the Unix socket and its parent directory. Avoid placing the socket in a directory inaccessible to the client user. Remove a stale socket only after confirming no mpv process is using it.

On Windows, use the exact named-pipe path. The server and client should generally run in compatible user and privilege contexts. Running one process elevated and the other normally can introduce access differences. Do not elevate both programs unless there is a demonstrated need.

7.2 Partial reads and writes

Socket APIs may write or return fewer bytes than requested. Robust clients loop until the entire request plus newline is sent, retain incomplete received data, and parse only complete newline-delimited messages. A response may also contain Unicode, so decode it consistently as UTF-8.

If short requests work but long loadfile requests fail intermittently, inspect buffering and partial-write handling before changing mpv. This is especially important for clients that send long paths or command-specific option strings.

7.3 File and network permissions

mpv runs with the permissions and environment of the mpv process, not necessarily those of the IPC client. A path visible inside a container, sandbox, remote session, or network-mounted environment may not be visible to mpv. Confirm access by opening the identical absolute path directly with the same mpv executable and user context.

8. Run a Clean Temporary Test Before Changing Multiple Options

Use a controlled sequence so every result narrows the cause:

1. Start mpv with --no-config --idle=yes and a fresh temporary IPC endpoint.
2. Send get_property for mpv-version with a request ID and newline.
3. Send set_property for pause, then read it back.
4. Load a small, known-good local media file using an absolute path.
5. Query path, playlist, or track-list to verify the result.
6. Reintroduce only the relevant profile, script, option, or real media source.

If a step succeeds, preserve it and move forward. If a step fails, inspect that request and its reply before proceeding. Changing shell quoting, hardware decoding, subtitle settings, output drivers, and scripts simultaneously destroys the evidence needed to identify the actual fault.

9. Quick Fix Checklist

• Put the command and each argument in a JSON array.
• Send one newline-terminated JSON object per request.
• Use JSON booleans and numbers instead of quoted substitutes.
• Distinguish action commands from properties changed through set_property.
• Escape Windows backslashes or use appropriate forward-slash paths.
• Pass the loadfile path and mode as separate array elements.
• Add unique request IDs and match replies by those IDs.
• Log and inspect every error value.
• Continue reading the connection for observed property events.
• Test a local file before diagnosing yt-dlp or network streams.
• Use --no-config temporarily instead of deleting configuration.
• Stop changing IPC settings once a minimal request returns success.

10. Frequently Asked Questions

10.1 Why does mpv connect but do nothing?

The request may be waiting for its newline terminator, buffered but not flushed, malformed, or sent as one command string instead of a JSON array. Read the socket continuously and inspect mpv's reply. A successful connection is not proof that mpv parsed the command.

10.2 What is the correct JSON syntax for an mpv command?

Use an object whose command value is an array, such as {"command":["set_property","pause",true],"request_id":1}. End the serialized object with a real newline character.

10.3 Why does loadfile return success but the video still fails?

The command may have been accepted while the later open, demux, decode, network, or output stage failed. Check terminal output or --log-file. Test a known-good local file to separate IPC syntax from stream, yt-dlp, codec, GPU, HDR, or permission problems.

10.4 Why am I not receiving observed property changes?

Keep the connection open and continue reading after the registration reply. Match property-change events by the observer id. Do not confuse that observer ID with the command's request_id.

10.5 Should I delete my mpv configuration?

No. First run a temporary --no-config test. If that fixes the issue, inspect the directly relevant profile, script, input binding, or option one at a time. This is safer and more informative than deleting the entire configuration folder.

10.6 When should I stop troubleshooting IPC syntax?

Stop when a minimal request receives "error":"success", request IDs match, and a read-back query confirms the requested state. If media still does not play correctly, move to the specific subsystem identified by logs, such as file access, URL resolution, tracks, decoding, video output, audio output, or screenshot permissions.