summaryrefslogtreecommitdiffstats
path: root/DOCS/man/ipc.rst
diff options
context:
space:
mode:
Diffstat (limited to 'DOCS/man/ipc.rst')
-rw-r--r--DOCS/man/ipc.rst42
1 files changed, 40 insertions, 2 deletions
diff --git a/DOCS/man/ipc.rst b/DOCS/man/ipc.rst
index 1a5eadfe49..2aa406b190 100644
--- a/DOCS/man/ipc.rst
+++ b/DOCS/man/ipc.rst
@@ -74,6 +74,12 @@ some wrapper like .NET's NamedPipeClientStream.)
Protocol
--------
+The protocol uses UTF-8-only JSON as defined by RFC-8259. Unlike standard JSON,
+"\u" escape sequences are not allowed to construct surrogate pairs. To avoid
+getting conflicts, encode all text characters including and above codepoint
+U+0020 as UTF-8. mpv might output broken UTF-8 in corner cases (see "UTF-8"
+section below).
+
Clients can execute commands on the player by sending JSON messages of the
following form:
@@ -108,7 +114,10 @@ Because events can occur at any time, it may be difficult at times to determine
which response goes with which command. Commands may optionally include a
``request_id`` which, if provided in the command request, will be copied
verbatim into the response. mpv does not intrepret the ``request_id`` in any
-way; it is solely for the use of the requester.
+way; it is solely for the use of the requester. The only requirement is that
+the ``request_id`` field must be an integer (a number without fractional parts
+in the range ``-2^63..2^63-1``). Using other types is deprecated and will
+currently show a warning. In the future, this will raise an error.
For example, this request:
@@ -122,6 +131,11 @@ Would generate this response:
{ "error": "success", "data": 1.468135, "request_id": 100 }
+If you don't specify a ``request_id``, command replies will set it to 0.
+
+Commands may run asynchronously in the future, instead of blocking the socket
+until a reply is sent.
+
All commands, replies, and events are separated from each other with a line
break character (``\n``).
@@ -258,4 +272,28 @@ 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.
+mpv will not attempt to construct invalid UTF-8 with broken "\u" escape
+sequences. This includes surrogate pairs.
+
+JSON extensions
+---------------
+
+The following non-standard extensions are supported:
+
+ - a list or object item can have a trailing ","
+ - object syntax accepts "=" in addition of ":"
+ - object keys can be unquoted, if they start with a character in "A-Za-z\_"
+ and contain only characters in "A-Za-z0-9\_"
+ - byte escapes with "\xAB" are allowed (with AB being a 2 digit hex number)
+
+Example:
+
+::
+
+ { objkey = "value\x0A" }
+
+Is equivalent to:
+
+::
+
+ { "objkey": "value\n" }