From e0f0f6fe26b7f8d941a20f2c86564b83e5fb52cb Mon Sep 17 00:00:00 2001 From: Alessandro Ghedini Date: Tue, 14 Oct 2014 22:35:37 +0200 Subject: manpage: add JSON IPC documentation --- DOCS/man/changes.rst | 4 +- DOCS/man/ipc.rst | 140 +++++++++++++++++++++++++++++++++++++++++++++++++++ DOCS/man/mpv.rst | 2 + DOCS/man/options.rst | 3 ++ wscript_build.py | 2 +- 5 files changed, 148 insertions(+), 3 deletions(-) create mode 100644 DOCS/man/ipc.rst 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=`` + Enable the IPC support and create the listening socket at the given path. + ``--input-appleremote=`` (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] -- cgit v1.2.3