summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--DOCS/man/changes.rst4
-rw-r--r--DOCS/man/ipc.rst140
-rw-r--r--DOCS/man/mpv.rst2
-rw-r--r--DOCS/man/options.rst3
-rw-r--r--wscript_build.py2
5 files changed, 148 insertions, 3 deletions
diff --git a/DOCS/man/changes.rst b/DOCS/man/changes.rst
index 95027be547..c3d7900d5a 100644
--- a/DOCS/man/changes.rst
+++ b/DOCS/man/changes.rst
@@ -387,8 +387,8 @@ Slave mode
(The option was readded in 0.5.1 and sets exactly these options.)
-* A JSON RPC protocol giving access to the client API is planned, but nothing
- has emerged yet.
+* A JSON RPC protocol giving access to the client API is also supported. See
+ `JSON IPC`_ for more information.
* **mpv** also provides a client API, which can be used to embed the player
by loading it as shared library. (See ``libmpv/client.h`` in the sources.)
diff --git a/DOCS/man/ipc.rst b/DOCS/man/ipc.rst
new file mode 100644
index 0000000000..b488cd738c
--- /dev/null
+++ b/DOCS/man/ipc.rst
@@ -0,0 +1,140 @@
+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.
+
+Protocol
+--------
+
+Clients can execute commands on the player by sending JSON messages of the
+following form:
+
+::
+
+ { "command": ["command_name", "param1", "param2", ...] }
+
+where ``command_name`` is the name of the command to be executed, followed by a
+list of parameters. Parameters must be formatted as native JSON values
+(integers, strings, booleans, ...). Every message **must** be terminated with
+``\n``. Additionally, ``\n`` must not appear anywhere inside the message. In
+practice this means that messages should be minified before being sent to mpv.
+
+mpv will then send back a reply indicating whether the command was run
+correctly, and an additional field holding the command-specific return data (it
+can also be null).
+
+::
+
+ { "error": "success", "data": null }
+
+mpv will also send events to clients with JSON messages of the following form:
+
+::
+
+ { "event": "event_name" }
+
+where ``event_name`` is the name of the event. Additional event-specific fields
+can also be present. See `List of events`_ for a list of all supported events.
+
+Commands
+--------
+
+Additionally to the commands described in `List of Input Commands`_, a few
+extra commands can also be used as part of the protocol:
+
+``client_name``
+ Return the name of the client as string. This is the string ``ipc-N`` with
+ N being an integer number.
+
+``get_time_us``
+ Return the current mpv internal time in microseconds as a number. This is
+ basically the system time, with an arbitrary offset.
+
+``get_property``
+ Return the value of the given property. The value will be sent in the data
+ field of the replay message.
+
+ Example:
+
+ ::
+
+ { "command": ["get_property", "volume"] }
+ { "data": 50.0, "error": "success" }
+
+``get_property_string``
+ Like ``get_property``, but the resulting data will always be a string.
+
+ Example:
+
+ ::
+
+ { "command": ["get_property_string", "volume"] }
+ { "data": "50.000000", "error": "success" }
+
+``set_property``
+ Set the given property to the given value. See `Properties`_ for more
+ information about properties.
+
+ Example:
+
+ ::
+
+ { "command": ["set_property", "pause", true] }
+ { "error": "success" }
+
+``set_property_string``
+ Like ``set_property``, but the argument value must be passed as string.
+
+ Example:
+
+ ::
+
+ { "command": ["set_property_string", "pause", "yes"] }
+ { "error": "success" }
+
+``observe_property``
+ Watch a property for changes. If the given property is changed, then an
+ event of type ``property-change`` will be generated
+
+ Example:
+
+ ::
+
+ { "command": ["observe_property", 1, "volume"] }
+ { "error": "success" }
+ { "event": "property-change", "id": 1, "data": 52.0, "name": "volume" }
+
+``observe_property_string``
+ Like ``observe_property``, but the resulting data will always be a string.
+
+ Example:
+
+ ::
+
+ { "command": ["observe_property", 1, "volume"] }
+ { "error": "success" }
+ { "event": "property-change", "id": 1, "data": "52.000000", "name": "volume" }
+
+``unobserve_property``
+ Undo ``observe_property`` or ``observe_property_string``. This requires the
+ numeric id passed to the observe command as argument.
+
+ Example:
+
+ ::
+
+ { "command": ["unobserve_property", 1] }
+ { "error": "success" }
+
+``suspend``
+ Suspend the mpv main loop. There is a long-winded explanation of this in
+ the C API function ``mpv_suspend()``. In short, this prevents the player
+ from displaying the next video frame, so that you don't get blocked when
+ trying to access the player.
+
+``resume``
+ Undo one ``suspend`` call. ``suspend`` increments an internal counter, and
+ ``resume`` decrements it. When 0 is reached, the player is actually resumed.
diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst
index 5078aac61a..4cc375d452 100644
--- a/DOCS/man/mpv.rst
+++ b/DOCS/man/mpv.rst
@@ -560,6 +560,8 @@ PROTOCOLS
.. include:: lua.rst
+.. include:: ipc.rst
+
.. include:: changes.rst
ENVIRONMENT VARIABLES
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index 44cbbaaf57..35a8a2e9d8 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -2177,6 +2177,9 @@ Input
or intend to read from stdin later on via the loadfile or loadlist slave
commands.
+``--input-unix-socket=<filename>``
+ Enable the IPC support and create the listening socket at the given path.
+
``--input-appleremote=<yes|no>``
(OS X only)
Enable/disable Apple Remote support. Enabled by default (except for libmpv).
diff --git a/wscript_build.py b/wscript_build.py
index 5960ad7b5e..a7d7e0171f 100644
--- a/wscript_build.py
+++ b/wscript_build.py
@@ -3,7 +3,7 @@ import re
def _add_rst_manual_dependencies(ctx):
manpage_sources_basenames = """
options.rst ao.rst vo.rst af.rst vf.rst encode.rst
- input.rst osc.rst lua.rst changes.rst""".split()
+ input.rst osc.rst lua.rst ipc.rst changes.rst""".split()
manpage_sources = ['DOCS/man/'+x for x in manpage_sources_basenames]