From b44ea70209c40a6e1600f6c59d5c73ef6685645b Mon Sep 17 00:00:00 2001 From: wm4 Date: Sun, 13 May 2018 12:19:11 +0200 Subject: ipc: alias set_property_string to set_property The only effective difference is that the former explicitly checks whether the JSON value type is string, and errors out if not. The rest is exactly the same (mpv_set_property_string is mpv_set_property with MPV_FORMAT_STRING). It seems silly to keep this, so just remove it. --- DOCS/man/ipc.rst | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) (limited to 'DOCS/man/ipc.rst') diff --git a/DOCS/man/ipc.rst b/DOCS/man/ipc.rst index 289ef5b799..1a5eadfe49 100644 --- a/DOCS/man/ipc.rst +++ b/DOCS/man/ipc.rst @@ -180,14 +180,7 @@ extra commands can also be used as part of the protocol: { "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" } + Alias for ``set_property``. Both commands accept native values and strings. ``observe_property`` Watch a property for changes. If the given property is changed, then an -- cgit v1.2.3 From fc574ee5634112c21ee4b61d8f9b7517ec3192a2 Mon Sep 17 00:00:00 2001 From: wm4 Date: Sun, 13 May 2018 12:46:50 +0200 Subject: ipc: some user-visible changes to prepare for making all commands async I wanted to put all commands through mpv_command_node_async() instead of mpv_command_node(). Using synchronous commands over a synchronous transport doesn't make sense anyway. This would have used the request_id field in IPC requests as reply ID for the async commands. But the latter need to be [u]int64, while the former can be any type. To avoid that we need an extra lookup table for mapping reply IDs to request_id values, we now require that request_id fields are integers. Since this would be an incompatible change, just deprecate non-integers for now, and plan the change for a later time. --- DOCS/man/ipc.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'DOCS/man/ipc.rst') diff --git a/DOCS/man/ipc.rst b/DOCS/man/ipc.rst index 1a5eadfe49..0c551e8706 100644 --- a/DOCS/man/ipc.rst +++ b/DOCS/man/ipc.rst @@ -108,7 +108,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 +125,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``). -- cgit v1.2.3 From d36b85cfdf4714a0498aec2a1f548ce0467e4fe3 Mon Sep 17 00:00:00 2001 From: wm4 Date: Thu, 17 May 2018 16:28:13 +0200 Subject: json: add some non-standard extensions Also clarify this and previously existing differences to standard JSON in ipc.rst. --- DOCS/man/ipc.rst | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) (limited to 'DOCS/man/ipc.rst') diff --git a/DOCS/man/ipc.rst b/DOCS/man/ipc.rst index 0c551e8706..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: @@ -266,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" } -- cgit v1.2.3