summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJames Ross-Gowan <rossymiles@gmail.com>2016-03-23 23:01:57 +1100
committerJames Ross-Gowan <rossymiles@gmail.com>2016-03-23 23:15:27 +1100
commita07832313d382c2a6fce9477ce1067f125d94a2a (patch)
treecbbf43caad5d8cb32d1838f61993c1b90ecad9e3
parentcd50ebba363315e15276e3b0895c33e85813fc4a (diff)
downloadmpv-a07832313d382c2a6fce9477ce1067f125d94a2a.tar.bz2
mpv-a07832313d382c2a6fce9477ce1067f125d94a2a.tar.xz
man: ipc: update for named pipe IPC on Windows
-rw-r--r--DOCS/man/ipc.rst39
-rw-r--r--DOCS/man/options.rst14
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=<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)