mirror of
https://github.com/mpv-player/mpv.git
synced 2024-09-20 20:03:10 +02:00
df6435be50
Some rationale for the documented/suggested behavior: It's not really clear what to do with invalid UTF-8, since JSON simply can't transport this information. Maybe you could transfer such strings as byte arrays, but that would be very verbose and inconvenient, and would pose the problem that it's hard to distinguish between strings encoded in this way and actual arrays. There are many other ways how this could be handled. For example, you could replace invalid sequences with '?'. Or you could do it like Python, and use certain reserved unicode codepoints to "tunnel" through invalid bytes. Which of these works really depends on the application. And since this can be done entirely on the byte level (invalid UTF-8 sequences can appear only in strings in our case), it's best to leave this to the receiver.
170 lines
5.3 KiB
ReStructuredText
170 lines
5.3 KiB
ReStructuredText
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. You can use the ``socat`` tool to send
|
|
commands (and receive reply) from the shell.
|
|
|
|
.. warning::
|
|
|
|
This is not intended to be a secure network protocol. It is explicitly
|
|
insecure: there is no authentication, no encryption, and the commands
|
|
themselves are insecure too. For example, the ``run`` command is exposed,
|
|
which can run arbitrary system commands. The use-case is controlling the
|
|
player locally. This is not different from the MPlayer slave protocol.
|
|
|
|
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.
|
|
|
|
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
|
|
with ``#`` and empty lines are ignored.
|
|
|
|
Currently, embedded 0 bytes terminate the current line, but you should not
|
|
rely on this.
|
|
|
|
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.
|
|
|
|
UTF-8
|
|
-----
|
|
|
|
Normally, all strings are in UTF-8. Sometimes it can happen that strings are
|
|
in some broken encoding (often happens with file tags and such, and filenames
|
|
on many Unixes are not required to be in UTF-8 either). This means that mpv
|
|
sometimes sends invalid JSON. If that is a problem for the client application's
|
|
parser, it should filter the raw data for invalid UTF-8 sequences and perform
|
|
the desired replacement, before feeding the data to its JSON parser.
|
|
|
|
mpv will not attempt to construct invalid UTF-8 with broken escape sequences.
|