man: ipc: update for named pipe IPC on Windows

DOCS/man/ipc.rst

@@ -1,10 +1,10 @@
 JSON IPC
 ========
 
-mpv can be controlled by external programs using the JSON-based IPC protocol. It
+mpv can be controlled by external programs using the JSON-based IPC protocol.
-can be enabled by specifying the path to a unix socket using the option
+It can be enabled by specifying the path to a unix socket or a named pipe using
-``--input-unix-socket``. Clients can connect to this socket and send commands to
+the option ``--input-ipc-server``. Clients can connect to this socket and send
-the player or receive events from it.
+commands to the player or receive events from it.
 
 .. warning::
 
@@ -17,12 +17,12 @@ the player or receive events from it.
 Socat example
 -------------
 
-You can use the ``socat`` tool to send commands (and receive reply) from the
+You can use the ``socat`` tool to send commands (and receive replies) from the
 shell. Assuming mpv was started with:
 
 ::
 
-    mpv file.mkv --input-unix-socket=/tmp/mpvsocket
+    mpv file.mkv --input-ipc-server=/tmp/mpvsocket
 
 Then you can control it using socat:
 
@@ -46,6 +46,31 @@ It's also possible to send input.conf style text-only commands:
 But you won't get a reply over the socket. (This particular command shows the
 playback time on the player's OSD.)
 
+Command Prompt example
+----------------------
+
+Unfortunately, it's not as easy to test the IPC protocol on Windows, since
+Windows ports of socat (in Cygwin and MSYS2) don't understand named pipes. In
+the absence of a simple tool to send and receive from bidirectional pipes, the
+``echo`` command can be used to send commands, but not receive replies from the
+command prompt.
+
+Assuming mpv was started with:
+
+::
+
+    mpv file.mkv --input-ipc-server=\\.\pipe\mpvsocket
+
+You can send commands from a command prompt:
+
+::
+
+    echo show_text ${playback-time} >\\.\pipe\mpvsocket
+
+To be able to simultaneously read and write from the IPC pipe, like on Linux,
+it's necessary to write an external program that uses overlapped file I/O (or
+some wrapper like .NET's NamedPipeClientStream.)
+
 Protocol
 --------
 
@@ -102,7 +127,7 @@ break character (``\n``).
 
 If the first character (after skipping whitespace) is not ``{``, the command
 will be interpreted as non-JSON text command, as they are used in input.conf
-(or ``mpv_command_string()`` in the client API). Additionally, line starting
+(or ``mpv_command_string()`` in the client API). Additionally, lines starting
 with ``#`` and empty lines are ignored.
 
 Currently, embedded 0 bytes terminate the current line, but you should not

DOCS/man/options.rst

@@ -2440,7 +2440,7 @@ Input
 ``--input-file=<filename>``
     Read commands from the given file. Mostly useful with a FIFO. Since
     mpv 0.7.0 also understands JSON commands (see `JSON IPC`_), but you can't
-    get replies or events. Use ``--input-unix-socket`` for something
+    get replies or events. Use ``--input-ipc-server`` for something
     bi-directional. On MS Windows, JSON commands are not available.
 
     This can also specify a direct file descriptor with ``fd://N`` (UNIX only).
@@ -2460,12 +2460,18 @@ Input
     or intend to read from stdin later on via the loadfile or loadlist slave
     commands.
 
-``--input-unix-socket=<filename>``
+``--input-ipc-server=<filename>``
     Enable the IPC support and create the listening socket at the given path.
 
-    See `JSON IPC`_ for details.
+    On Linux and Unix, the given path is a regular filesystem path. On Windows,
+    named pipes are used, so the path refers to the pipe namespace
+    (``\\.\pipe\<name>``). If the ``\\.\pipe\`` prefix is missing, mpv will add
+    it automatically before creating the pipe, so
+    ``--input-ipc-server=/tmp/mpv-socket`` and
+    ``--input-ipc-server=\\.\pipe\tmp\mpv-socket`` are equivalent for IPC on
+    Windows.
 
-    Not available on MS Windows.
+    See `JSON IPC`_ for details.
 
 ``--input-appleremote=<yes|no>``
     (OS X only)