From a07832313d382c2a6fce9477ce1067f125d94a2a Mon Sep 17 00:00:00 2001 From: James Ross-Gowan Date: Wed, 23 Mar 2016 23:01:57 +1100 Subject: man: ipc: update for named pipe IPC on Windows --- DOCS/man/ipc.rst | 39 ++++++++++++++++++++++++++++++++------- DOCS/man/options.rst | 14 ++++++++++---- 2 files changed, 42 insertions(+), 11 deletions(-) diff --git a/DOCS/man/ipc.rst b/DOCS/man/ipc.rst index e3ff1bd243..7a0ed69723 100644 --- a/DOCS/man/ipc.rst +++ b/DOCS/man/ipc.rst @@ -1,10 +1,10 @@ JSON IPC ======== -mpv can be controlled by external programs using the JSON-based IPC protocol. It -can be enabled by specifying the path to a unix socket using the option -``--input-unix-socket``. Clients can connect to this socket and send commands to -the player or receive events from it. +mpv can be controlled by external programs using the JSON-based IPC protocol. +It can be enabled by specifying the path to a unix socket or a named pipe using +the option ``--input-ipc-server``. Clients can connect to this socket and send +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 diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index 7280a3e6d3..d8de023a60 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -2440,7 +2440,7 @@ Input ``--input-file=`` 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=`` +``--input-ipc-server=`` 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\``). 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=`` (OS X only) -- cgit v1.2.3