From b440f6dfb3d29651d8dcb7abfeb8ed18e3f2b995 Mon Sep 17 00:00:00 2001 From: wm4 Date: Sun, 6 May 2018 18:27:18 +0200 Subject: command: add infrastructure for async commands This enables two types of command behavior: 1. Plain async behavior, like "loadfile" not completing until the file is fully loaded. 2. Running parts of the command on worker threads, e.g. for I/O, such as "sub-add" doing network accesses on a thread while the core continues. Both have no implementation yet, and most new code is actually inactive. The plan is to implement a number of useful cases in the following commits. The most tricky part is handling internal keybindings (input.conf) and the multi-command feature (concatenating commands with ";"). It requires a bunch of roundabout code to make it do the expected thing in combination with async commands. There is the question how commands should be handled that come in at a higher rate than what can be handled by the core. Currently, it will simply queue up input.conf commands as long as memory lasts. The client API is limited by the size of the reply queue per client. For commands which require a worker thread, the thread pool is limited to 30 threads, and then will queue up work in memory. The number is completely arbitrary. --- DOCS/man/input.rst | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) (limited to 'DOCS/man') diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index 58e2b9c27d..6706fc3198 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -870,11 +870,45 @@ prefixes can be specified. They are separated by whitespace. are asynchronous by default (or rather, their effects might manifest after completion of the command). The semantics of this flag might change in the future. Set it only if you don't rely on the effects of this command - being fully realized when it returns. + being fully realized when it returns. See `Synchronous vs. Asynchronous`_. +``sync`` + Allow synchronous execution (if possible). Normally, all commands are + synchronous by default, but some are asynchronous by default for + compatibility with older behavior. All of the osd prefixes are still overridden by the global ``--osd-level`` settings. +Synchronous vs. Asynchronous +---------------------------- + +The ``async`` and ``sync`` prefix matter only for how the issuer of the command +waits on the completion of the command. Normally it does not affect how the +command behaves by itself. There are the following cases: + +- Normal input.conf commands are always run asynchronously. Slow running + commands are queued up or run in parallel. +- "Multi" input.conf commands (1 key binding, concatenated with ``;``) will be + executed in order, except for commands that are async (either prefixed with + ``async``, or async by default for some commands). The async commands are + run in a detached manner, possibly in parallel to the remaining sync commands + in the list. +- Normal Lua and libmpv commands (e.g. ``mpv_command()``) are run in a blocking + manner, unless the ``async`` prefix is used, or the command is async by + default. This means in the sync case the caller will block, even if the core + continues playback. Async mode runs the command in a detached manner. +- Async libmpv command API (e.g. ``mpv_command_async()``) never blocks the + caller, and always notify their completion with a message. The ``sync`` and + ``async`` prefixes make no difference. +- In all cases, async mode can still run commands in a synchronous manner, even + in detached mode. This can for example happen in cases when a command does not + have an asynchronous implementation. The async libmpv API still never blocks + the caller in these cases. + +The only exception is the current legacy behavior with screenshot commands, +which will be fixed later. Using the ``async`` prefix makes them run the file +saving code in a detached manner. + Input Sections -------------- -- cgit v1.2.3 From c349e2f337693c53687b0bd5e4d8669363e2d79d Mon Sep 17 00:00:00 2001 From: wm4 Date: Sun, 6 May 2018 21:23:28 +0200 Subject: command: make sub-add and audio-add commands async Pretty trivial, since commands can be async now, and the common code even provides convenience like running commands on a worker thread. The only ugly thing is that mp_add_external_file() needs an extra flag for locking. This is because there's still some code which calls this synchronously from the main thread, and unlocking the core makes no sense there. --- DOCS/man/input.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'DOCS/man') diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index 6706fc3198..205c732781 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -909,6 +909,9 @@ The only exception is the current legacy behavior with screenshot commands, which will be fixed later. Using the ``async`` prefix makes them run the file saving code in a detached manner. +Currently the following commands have different waiting characteristics with +sync vs. async: sub-add, audio-add + Input Sections -------------- -- cgit v1.2.3 From 1b611e38ef9291c309e97379ef432fd301605033 Mon Sep 17 00:00:00 2001 From: wm4 Date: Mon, 7 May 2018 20:36:17 +0200 Subject: player: make all external file loading actions async Still missing: not freezing when removing a track (i.e. closing demuxer) with the sub-remove/audio-remove/rescan-external-files commands. --- DOCS/man/input.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'DOCS/man') diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index 205c732781..94e1ea0b1f 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -910,7 +910,8 @@ which will be fixed later. Using the ``async`` prefix makes them run the file saving code in a detached manner. Currently the following commands have different waiting characteristics with -sync vs. async: sub-add, audio-add +sync vs. async: sub-add, audio-add, sub-reload, audio-reload, +rescan-external-files. Input Sections -------------- -- cgit v1.2.3 From fb62ffdb943c7b50c3667aeaf452301f84b3b67f Mon Sep 17 00:00:00 2001 From: wm4 Date: Tue, 8 May 2018 18:44:08 +0200 Subject: manpage: mention that --no-correct-pts can break seeking too --- DOCS/man/options.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'DOCS/man') diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index ea8c6df26f..e1f1944408 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -1020,8 +1020,8 @@ Video determined using a fixed framerate value (either using the ``--fps`` option, or using file information). Sometimes, files with very broken timestamps can be played somewhat well in this mode. Note that video - filters, subtitle rendering and audio synchronization can be completely - broken in this mode. + filters, subtitle rendering, seeking (including hr-seeks and backstepping), + and audio synchronization can be completely broken in this mode. ``--fps=`` Override video framerate. Useful if the original value is wrong or missing. -- cgit v1.2.3 From a4321cf6877f47a381ff40bea73ca2934635ea58 Mon Sep 17 00:00:00 2001 From: wm4 Date: Wed, 9 May 2018 22:38:21 +0200 Subject: screenshot: change async behavior to be in line with new semantics Basically reimplement the async behavior on top of the async command code. With this, all screenshot commands are async, and the "async" prefix basically does nothing. The prefix now behaves exactly like with other commands that use spawn_thread. This also means using the prefix in the preset input.conf is pointless (without effect) and misleading, so remove that. The each_frame mode was actually particularly painful in making this change, since the player wants to block for it when writing a screenshot, and generally doesn't fit into the new infrastructure. It was still relatively easy to reimplement by copying the original command and then repeating it on each frame. The waiting is reentrant now, so move the call in video.c to a "safer" spot. One way to observe how the new semantics interact with everything is using the mpv repl script and sending a screenshot command through it. Without async flag, the script will freeze while writing the screenshot (while playback continues), while with async flag it continues. --- DOCS/man/input.rst | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) (limited to 'DOCS/man') diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index 94e1ea0b1f..6aa566294f 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -186,11 +186,10 @@ List of Input Commands second argument (and did not have flags). This syntax is still understood, but deprecated and might be removed in the future. - Setting the ``async`` flag will make encoding and writing the actual image - file asynchronous in most cases. (``each-frame`` mode ignores this flag - currently.) Requesting async screenshots too early or too often could lead - to the same filenames being chosen, and overwriting each others in undefined - order. + If you combine this command with another one using ``;``, you can use the + ``async`` flag to make encoding/writing the image file asynchronous. For + normal standalone commands, this is always asynchronous, and the flag has + no effect. (This behavior changed with mpv 0.29.0.) ``screenshot-to-file "" [subtitles|video|window]`` Take a screenshot and save it to a given file. The format of the file will @@ -204,9 +203,6 @@ List of Input Commands Like all input command parameters, the filename is subject to property expansion as described in `Property Expansion`_. - The ``async`` flag has an effect on this command (see ``screenshot`` - command). - ``playlist-next [weak|force]`` Go to the next entry on the playlist. @@ -905,13 +901,13 @@ command behaves by itself. There are the following cases: have an asynchronous implementation. The async libmpv API still never blocks the caller in these cases. -The only exception is the current legacy behavior with screenshot commands, -which will be fixed later. Using the ``async`` prefix makes them run the file -saving code in a detached manner. +Before mpv 0.29.0, the ``async`` prefix was only used by screenshot commands, +and made them run the file saving code in a detached manner. This is the +default now, and ``async`` changes behavior only in the ways mentioned above. Currently the following commands have different waiting characteristics with sync vs. async: sub-add, audio-add, sub-reload, audio-reload, -rescan-external-files. +rescan-external-files, screenshot, screenshot-to-file. Input Sections -------------- -- cgit v1.2.3 From 159379980ec8c79608b1adada4b66b1d8c016e4a Mon Sep 17 00:00:00 2001 From: wm4 Date: Thu, 10 May 2018 15:26:27 +0200 Subject: lua: expose async commands Might be useful for some. --- DOCS/man/lua.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'DOCS/man') diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index c0c4f9b00a..0dbd7d3c0a 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -115,6 +115,15 @@ The ``mp`` module is preloaded, although it can be loaded manually with error. ``def`` is the second parameter provided to the function, and is nil if it's missing. +``mp.command_native_async(table [,fn])`` + Like ``mp.command_native()``, but the command is ran asynchronously (as far + as possible), and upon completion, fn is called. fn has two arguments: + ``fn(success, result, error)``. ``success`` is always a Boolean and is true + if the command was successful, otherwise false. The second parameter is + the result value (can be nil) in case of success, nil otherwise (as returned + by ``mp.command_native()``). The third parameter is the error string in case + of an error, nil otherwise. + ``mp.get_property(name [,def])`` Return the value of the given property as string. These are the same properties as used in input.conf. See `Properties`_ for a list of -- cgit v1.2.3 From 1aae88b4879f40c68cebbdcd47895787ecdcdf68 Mon Sep 17 00:00:00 2001 From: wm4 Date: Sat, 12 May 2018 14:50:07 +0200 Subject: input: add glue code for named arguments Named arguments should make it easier to have long time compatibility, even if command arguments get added or removed. They're also much nicer for commands with a large number of arguments, especially if many arguments are optional. As of this commit, this can not be used, because there is no command yet which supports them. See the following commit. --- DOCS/man/input.rst | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ DOCS/man/lua.rst | 12 ++++++++- 2 files changed, 86 insertions(+), 1 deletion(-) (limited to 'DOCS/man') diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index 6aa566294f..567d2e0de8 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -78,6 +78,16 @@ that matches, and the multi-key command will never be called. Intermediate keys can be remapped to ``ignore`` in order to avoid this issue. The maximum number of (non-modifier) keys for combinations is currently 4. +Named arguments +--------------- + +Some commands support named arguments (most currently don't). Named arguments +cannot be used with the "flat" input.conf syntax shown above, but require using +e.g. ``mp.command_native()`` in Lua scripting, or e.g. ``mpv_command_node()`` +with the libmpv API. Some commands ask you to only use named arguments (because +the command order is not guaranteed), which means you can't use them as +key bindings in input.conf at all. + List of Input Commands ---------------------- @@ -283,6 +293,71 @@ List of Input Commands execute arbitrary shell commands. It is recommended to write a small shell script, and call that with ``run``. +``subprocess`` + Similar to ``run``, but gives more control about process execution to the + caller, and does does not detach the process. + + This has the following named arguments. The order of them is not guaranteed, + so you should always call them with named arguments, see `Named arguments`_. + + ``args`` (``MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING]``) + Array of strings with the command as first argument, and subsequent + command line arguments following. This is just like the ``run`` command + argument list. + + ``playback_only`` (``MPV_FORMAT_FLAG``) + Boolean indicating whether the process should be killed when playback + terminates (optional, default: yes). If enabled, stopping playback + will automatically kill the process, and you can't start it outside of + playback. + + ``capture_size`` (``MPV_FORMAT_INT64``) + Integer setting the maximum number of stdout plus stderr bytes that can + be captured (optional, default: 64MB). If the number of bytes exceeds + this, capturing is stopped. The limit is per captured stream. + + ``capture_stdout`` (``MPV_FORMAT_FLAG``) + Capture all data the process outputs to stdout and return it once the + process ends (optional, default: no). + + ``capture_stderr`` (``MPV_FORMAT_FLAG``) + Same as ``capture_stdout``, but for stderr. + + The command returns the following result (as ``MPV_FORMAT_NODE_MAP``): + + ``status`` (``MPV_FORMAT_INT64``) + The raw exit status of the process. It will be negative on error. The + meaning of negative values is undefined, other than meaning error (and + does not necessarily correspond to OS low level exit status values). + + On Windows, it can happen that a negative return value is returned + even if the process exits gracefully, because the win32 ``UINT`` exit + code is assigned to an ``int`` variable before being set as ``int64_t`` + field in the result map. This might be fixed later. + + ``stdout`` (``MPV_FORMAT_BYTE_ARRAY``) + Captured stdout stream, limited to ``capture_size``. + + ``stderr`` (``MPV_FORMAT_BYTE_ARRAY``) + Same as ``stdout``, but for stderr. + + ``error_string`` (``MPV_FORMAT_STRING``) + Empty string if the process exited gracefully. The string ``killed`` if + the process was terminated in an unusual way. The string ``init`` if the + process could not be started. + + On Windows, ``killed`` is only returned when the process has been + killed by mpv as a result of ``playback_only`` being set to ``yes``. + + ``killed_by_us`` (``MPV_FORMAT_FLAG``) + Set to ``yes`` if the process has been killed by mpv as a result + of ``playback_only`` being set to ``yes``. + + Note that the command itself will always return success as long as the + parameters are correct. Whether the process could be spawned or whether + it was somehow killed or returned an error status has to be queried from + the result value. + ``quit []`` Exit the player. If an argument is given, it's used as process exit code. diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index 0dbd7d3c0a..dab185a284 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -109,7 +109,17 @@ The ``mp`` module is preloaded, although it can be loaded manually with ``mp.command_native(table [,def])`` Similar to ``mp.commandv``, but pass the argument list as table. This has the advantage that in at least some cases, arguments can be passed as - native types. + native types. It also allows you to use named argument. + + If the table is an array, each array item is like an argument in + ``mp.commandv()`` (but can be a native type instead of a string). + + If the table contains string keys, it's interpreted as command with named + arguments. This requires at least an entry with the key ``name`` to be + present, which must be a string, and contains the command name. The special + entry ``_flags`` is optional, and if present, must be an array of + `Input Command Prefixes`_ to apply. All other entries are interpreted as + arguments. Returns a result table on success (usually empty), or ``def, error`` on error. ``def`` is the second parameter provided to the function, and is -- cgit v1.2.3 From d9bc97bda6e4750af2fbbfcb51ddb6b2c04c277b Mon Sep 17 00:00:00 2001 From: wm4 Date: Sat, 12 May 2018 15:14:07 +0200 Subject: command: add a subprocess command This supports named arguments. It benefits from the infrastructure of async commands. The plan is to reimplement Lua's utils.subprocess() on top of it. --- DOCS/man/input.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'DOCS/man') diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index 567d2e0de8..6d05c5fc5d 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -305,6 +305,11 @@ List of Input Commands command line arguments following. This is just like the ``run`` command argument list. + The first array entry is either an absolute path to the executable, or + a filename with no path components, in which case the ``PATH`` + environment variable. On Unix, this is equivalent to ``posix_spawnp`` + and ``execvp`` behavior. + ``playback_only`` (``MPV_FORMAT_FLAG``) Boolean indicating whether the process should be killed when playback terminates (optional, default: yes). If enabled, stopping playback -- cgit v1.2.3 From 548ef07864f3e1a40f731b2643f037435ceae46d Mon Sep 17 00:00:00 2001 From: wm4 Date: Sat, 12 May 2018 15:36:43 +0200 Subject: lua: reimplement mp.subprocess() by invoking the new subprocess command We keep mp.subprocess() with roughly the same semantics for compatibility with scripts (including the internal ytdl script). Seems to work with rhe ytdl wrapper. Not tested further. --- DOCS/man/lua.rst | 56 +++++++++++++++++--------------------------------------- 1 file changed, 17 insertions(+), 39 deletions(-) (limited to 'DOCS/man') diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index dab185a284..ba09164d3b 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -653,45 +653,23 @@ strictly part of the guaranteed API. ``utils.subprocess(t)`` Runs an external process and waits until it exits. Returns process status - and the captured output. - - The parameter ``t`` is a table. The function reads the following entries: - - ``args`` - Array of strings. The first array entry is the executable. This - can be either an absolute path, or a filename with no path - components, in which case the ``PATH`` environment variable is - used to resolve the executable. The other array elements are - passed as command line arguments. - - ``cancellable`` - Optional. If set to ``true`` (default), then if the user stops - playback or goes to the next file while the process is running, - the process will be killed. - - ``max_size`` - Optional. The maximum size in bytes of the data that can be captured - from stdout. (Default: 16 MB.) - - The function returns a table as result with the following entries: - - ``status`` - The raw exit status of the process. It will be negative on error. - - ``stdout`` - Captured output stream as string, limited to ``max_size``. - - ``error`` - ``nil`` on success. The string ``killed`` if the process was - terminated in an unusual way. The string ``init`` if the process - could not be started. - - On Windows, ``killed`` is only returned when the process has been - killed by mpv as a result of ``cancellable`` being set to ``true``. - - ``killed_by_us`` - Set to ``true`` if the process has been killed by mpv as a result - of ``cancellable`` being set to ``true``. + and the captured output. This is a legacy wrapper around calling the + ``subprocess`` command with ``mp.command_native``. It does the following + things: + + - copy the table ``t`` + - rename ``cancellable`` field to ``playback_only`` + - rename ``max_size`` to ``capture_size`` + - set ``capture_stdout`` field to ``true`` if unset + - set ``name`` field to ``subprocess`` + - call ``mp.command_native(copied_t)`` + - if the command failed, create a dummy result table + - copy ``error_string`` to ``error`` field if the string is non-empty + - return the result table + + It is recommended to use ``mp.command_native`` or ``mp.command_native_async`` + directly, instead of calling this legacy wrapper. It is for compatibility + only. ``utils.subprocess_detached(t)`` Runs an external process and detaches it from mpv's control. -- cgit v1.2.3 From 7f91e2684e8600c45512e36f03aadff0b825a1b0 Mon Sep 17 00:00:00 2001 From: wm4 Date: Sat, 12 May 2018 16:03:04 +0200 Subject: lua: reimplement mp.subprocess_detached() by invoking the "run" command The "run" command is old. I'm not sure why the separate Lua implementation was added. But maybe it as because the "run" command used to be limited to a small number of arguments. This limit has been removed a while ago. In any case, the old implementation is not needed anymore. --- DOCS/man/lua.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'DOCS/man') diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index ba09164d3b..b2e244b6b5 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -682,6 +682,9 @@ strictly part of the guaranteed API. The function returns ``nil``. + This is a legacy wrapper around calling the ``run`` command with + ``mp.commandv`` and other functions. + ``utils.getpid()`` Returns the process ID of the running mpv process. This can be used to identify the calling mpv when launching (detached) subprocesses. -- cgit v1.2.3 From 9c530c7ee9ac0641e58ac1203bd46675e8700cc5 Mon Sep 17 00:00:00 2001 From: wm4 Date: Sat, 12 May 2018 18:47:43 +0200 Subject: command: make "subprocess" explicitly abortable Now mpv_abort_async_command() can be used to stop the process. --- DOCS/man/input.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'DOCS/man') diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index 6d05c5fc5d..cadf515567 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -363,6 +363,8 @@ List of Input Commands it was somehow killed or returned an error status has to be queried from the result value. + This command can be asynchronously aborted via API. + ``quit []`` Exit the player. If an argument is given, it's used as process exit code. -- cgit v1.2.3 From dbe831bd025d34930b97c493d9ef61278408cf46 Mon Sep 17 00:00:00 2001 From: wm4 Date: Sat, 12 May 2018 18:48:35 +0200 Subject: lua: expose mpv_abort_async_command() Also somewhat cleans up mp.command_native_async() error handling. --- DOCS/man/lua.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'DOCS/man') diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index b2e244b6b5..10da40016c 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -134,6 +134,18 @@ The ``mp`` module is preloaded, although it can be loaded manually with by ``mp.command_native()``). The third parameter is the error string in case of an error, nil otherwise. + Returns a table with undefined contents, which can be used as argument for + ``mp.abort_async_command``. + + If starting the command failed for some reason, ``nil, error`` is returned, + and ``fn`` is called indicating failure, using the same error value. + +``mp.abort_async_command(t)`` + Abort a ``mp.command_native_async`` call. The argument is the return value + of that command (which starts asynchronous execution of the command). + Whether this works and how long it takes depends on the command and the + situation. The abort call itself is asynchronous. Does not return anything. + ``mp.get_property(name [,def])`` Return the value of the given property as string. These are the same properties as used in input.conf. See `Properties`_ for a list of -- cgit v1.2.3 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') 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') 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 7428cc51496ca8e56600fdc4034b8f55720f09f9 Mon Sep 17 00:00:00 2001 From: wm4 Date: Sun, 13 May 2018 13:48:47 +0200 Subject: client API: kill async commands on termination This affects async commands started by client API, commands with async capability run in a sync way by client API (think mpv_command_node() with "subprocess"), and detached async work. Since scripts might want to do some cleanup work (that might involve launching processes, don't ask), we don't unconditionally kill everything on exit, but apply an arbitrary timeout of 2 seconds until async commands are aborted. --- DOCS/man/input.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'DOCS/man') diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index cadf515567..4b5ebffd0f 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -365,6 +365,9 @@ List of Input Commands This command can be asynchronously aborted via API. + In all cases, the subprocess will be terminated on player exit. Only the + ``run`` command can start processes in a truly detached way. + ``quit []`` Exit the player. If an argument is given, it's used as process exit code. -- cgit v1.2.3 From 5f61892c42b78d271bcc3f027fb8097a83b32231 Mon Sep 17 00:00:00 2001 From: wm4 Date: Wed, 16 May 2018 18:22:58 +0200 Subject: manpage: remove a reference to a removed option --- DOCS/man/options.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'DOCS/man') diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index e1f1944408..ef86da4635 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -2546,8 +2546,7 @@ Window always re-enabled when the player is paused. This is not supported on all video outputs or platforms. Sometimes it is - implemented, but does not work (known to happen with GNOME). You might be - able to work around this using ``--heartbeat-cmd`` instead. + implemented, but does not work (especially with Linux "desktops"). ``--wid=`` This tells mpv to attach to an existing window. If a VO is selected that -- cgit v1.2.3 From 972989db7e63c199edb605884bb2594eaecc9569 Mon Sep 17 00:00:00 2001 From: wm4 Date: Thu, 17 May 2018 12:46:37 +0200 Subject: manpage: mention that fd:// file descriptors may be modified For example, we call setmode() to switch a FD from text to binary mode on garbage OSes. --- DOCS/man/mpv.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'DOCS/man') diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst index 920aa2e370..c99a30e11f 100644 --- a/DOCS/man/mpv.rst +++ b/DOCS/man/mpv.rst @@ -899,6 +899,8 @@ PROTOCOLS Read data from the given file descriptor (for example 123). This is similar to piping data to stdin via ``-``, but can use an arbitrary file descriptor. + mpv may modify some file descriptor properties when the stream layer "opens" + it. ``fdclose://123`` -- 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') 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 From 332907e1d7225ae39565d462aac5c45c3a5cad97 Mon Sep 17 00:00:00 2001 From: wm4 Date: Thu, 17 May 2018 20:10:39 +0200 Subject: command: give named arguments to almost all commands Before this change, only 1 command or so had named arguments. There is no reason why other commands can't have them, except that it's a bit of work to add them. Commands with variable number of arguments are inherently incompatible to named arguments, such as the "run" command. They still have dummy names, but obviously you can't assign multiple values to a single named argument (unless the argument has an array type, which would be something different). For now, disallow using named argument APIs with these commands. This might change later. 2 commands are adjusted to not need a separate default value by changing flag constants. (The numeric values are C only and can't be set by users.) Make the command syntax in the manpage more consistent. Now none of the allowed choice/flag names are in the command header, and all arguments are shown with their proper name and quoted with <...>. Some places in the manpage and the client.h doxygen are updated to reflect that most commands support named arguments. In addition, try to improve the documentation of the syntax and need for escaping etc. as well. (Or actually most uses of the word "argument" should be "parameter".) --- DOCS/man/input.rst | 249 ++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 172 insertions(+), 77 deletions(-) (limited to 'DOCS/man') diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index 4b5ebffd0f..d2c92d7476 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -41,10 +41,10 @@ commands they're bound to on the OSD, instead of executing the commands:: (Only closing the window will make **mpv** exit, pressing normal keys will merely display the binding, even if mapped to quit.) -General Input Command Syntax ----------------------------- +input.conf syntax +----------------- -``[Shift+][Ctrl+][Alt+][Meta+] [{
}] [] ()* [; ]`` +``[Shift+][Ctrl+][Alt+][Meta+] [{
}] ( ; )*`` Note that by default, the right Alt key can be used to create special characters, and thus does not register as a modifier. The option @@ -59,9 +59,9 @@ character), or a symbolic name (as printed by ``--input-keylist``). ``
`` (braced with ``{`` and ``}``) is the input section for this command. -Arguments are separated by whitespace. This applies even to string arguments. -For this reason, string arguments should be quoted with ``"``. Inside quotes, -C-style escaping can be used. +```` is the command itself. It consists of the command name and +multiple (or none) commands, all separated by whitespace. String arguments +need to be quoted with ``"``. Details see ``Flat command syntax``. You can bind multiple commands to one key. For example: @@ -78,25 +78,89 @@ that matches, and the multi-key command will never be called. Intermediate keys can be remapped to ``ignore`` in order to avoid this issue. The maximum number of (non-modifier) keys for combinations is currently 4. +Flat command syntax +------------------- + +This is the syntax used in input.conf, and referred to "input.conf syntax" in +a number of other places. + +`` ::= [] ()*`` +`` ::= ( | " " )`` + +``command_name`` is an unquoted string with the command name itself. See +`List of Input Commands`_ for a list. + +Arguments are separated by whitespace. This applies even to string arguments. +For this reason, string arguments should be quoted with ``"``. If a string +argument contains spaces or certain special characters, quoting and possibly +escaping is mandatory, or the command cannot be parsed correctly. + +Inside quotes, C-style escaping can be used. JSON escapes according to RFC 8259, +minus surrogate pair escapes, should be a safe subset that can be used. + +Commands specified as arrays +---------------------------- + +This applies to certain APIs, such as ``mp.commandv()`` or +``mp.command_native()`` (with array parameters) in Lua scripting, or +``mpv_command()`` or ``mpv_command_node()`` (with MPV_FORMAT_NODE_ARRAY) in the +C libmpv client API. + +The command as well as all arguments are passed as a single array. Similar to +the `Flat command syntax`_, you can first pass prefixes as strings (each as +separate array item), then the command name as string, and then each argument +as string or a native value. + +Since these APIs pass arguments as separate strings or native values, they do +not expect quotes, and do support escaping. Technically, there is the input.conf +parser, which first splits the command string into arguments, and then invokes +argument parsers for each argument. The input.conf parser normally handles +quotes and escaping. The array command APIs mentioned above pass strings +directly to the argument parsers, or can sidestep them by the ability to pass +non-string values. + +Sometimes commands have string arguments, that in turn are actually parsed by +other components (e.g. filter strings with ``vf add``) - in these cases, you +you would have to double-escape in input.conf, but not with the array APIs. + +For complex commands, consider using `Named arguments`_ instead, which should +give slightly more compatibility. Some commands do not support named arguments +and inherently take an array, though. + Named arguments --------------- -Some commands support named arguments (most currently don't). Named arguments -cannot be used with the "flat" input.conf syntax shown above, but require using -e.g. ``mp.command_native()`` in Lua scripting, or e.g. ``mpv_command_node()`` -with the libmpv API. Some commands ask you to only use named arguments (because -the command order is not guaranteed), which means you can't use them as -key bindings in input.conf at all. +This applies to certain APIs, such as ``mp.command_native()`` (with tables that +have string keys) in Lua scripting, or ``mpv_command_node()`` (with +MPV_FORMAT_NODE_MAP) in the C libmpv client API. + +Like with array commands, quoting and escaping is inherently not needed in the +normal case. + +The name of each command is defined in each command description in the +`List of Input Commands`_. + +Some commands do not support named arguments (e.g. ``run`` command). You need +to use APIs that pass arguments as arrays. + +Named arguments are not supported in the "flat" input.conf syntax, which means +you cannot use them for key bindings in input.conf at all. List of Input Commands ---------------------- +Commands with parameters have the parameter name enclosed in ``<`` / ``>``. +Don't add those to the actual command. Optional arguments are enclosed in +``[`` / ``]``. If you don't pass them, they will be set to a default value. + +Remember to quote string arguments in input.conf (see `Flat command syntax`_). + ``ignore`` Use this to "block" keys that should be unbound, and do nothing. Useful for disabling default bindings, without disabling all bindings with ``--no-input-default-bindings``. -``seek [relative|absolute|absolute-percent|relative-percent|exact|keyframes]`` +``seek []`` Change the playback position. By default, seeks by a relative amount of seconds. @@ -124,7 +188,7 @@ List of Input Commands 3rd parameter (essentially using a space instead of ``+``). The 3rd parameter is still parsed, but is considered deprecated. -``revert-seek [mode]`` +``revert-seek []`` Undoes the ``seek`` command, and some other commands that seek (but not necessarily all of them). Calling this command once will jump to the playback position before the seek. Calling it a second time undoes the @@ -154,22 +218,24 @@ List of Input Commands This does not work with audio-only playback. -``set ""`` - Set the given property to the given value. +``set `` + Set the given property or option to the given value. -``add []`` - Add the given value to the property. On overflow or underflow, clamp the - property to the maximum. If ```` is omitted, assume ``1``. +``add []`` + Add the given value to the property or option. On overflow or underflow, + clamp the property to the maximum. If ```` is omitted, assume ``1``. -``cycle [up|down]`` - Cycle the given property. ``up`` and ``down`` set the cycle direction. On - overflow, set the property back to the minimum, on underflow set it to the - maximum. If ``up`` or ``down`` is omitted, assume ``up``. +``cycle []`` + Cycle the given property or option. The second argument can be ``up`` or + ``down`` to set the cycle direction. On overflow, set the property back to + the minimum, on underflow set it to the maximum. If ``up`` or ``down`` is + omitted, assume ``up``. -``multiply `` - Multiplies the value of a property with the numeric factor. +``multiply `` + Similar to ``add``, but multiplies the property or option with the numeric + value. -``screenshot [subtitles|video|window|single|each-frame]`` +``screenshot `` Take a screenshot. Multiple flags are available (some can be combined with ``+``): @@ -201,36 +267,41 @@ List of Input Commands normal standalone commands, this is always asynchronous, and the flag has no effect. (This behavior changed with mpv 0.29.0.) -``screenshot-to-file "" [subtitles|video|window]`` +``screenshot-to-file `` Take a screenshot and save it to a given file. The format of the file will be guessed by the extension (and ``--screenshot-format`` is ignored - the behavior when the extension is missing or unknown is arbitrary). - The second argument is like the first argument to ``screenshot``. + The second argument is like the first argument to ``screenshot`` and + supports ``subtitles``, ``video``, ``window``. If the file already exists, it's overwritten. Like all input command parameters, the filename is subject to property expansion as described in `Property Expansion`_. -``playlist-next [weak|force]`` +``playlist-next `` Go to the next entry on the playlist. + First argument: + weak (default) If the last file on the playlist is currently played, do nothing. force Terminate playback if there are no more files on the playlist. -``playlist-prev [weak|force]`` +``playlist-prev `` Go to the previous entry on the playlist. + First argument: + weak (default) If the first file on the playlist is currently played, do nothing. force Terminate playback if the first file is being played. -``loadfile "" [replace|append|append-play [options]]`` - Load the given file and play it. +``loadfile [ []]`` + Load the given file or URL and play it. Second argument: @@ -248,13 +319,20 @@ List of Input Commands Not all options can be changed this way. Some options require a restart of the player. -``loadlist "" [replace|append]`` - Load the given playlist file (like ``--playlist``). +``loadlist []`` + Load the given playlist file or URL (like ``--playlist``). + + Second argument: + + (default) + Stop playback and replace the internal playlist with the new one. + + Append the new playlist at the end of the current internal playlist. ``playlist-clear`` Clear the playlist, except the currently played file. -``playlist-remove current|`` +``playlist-remove `` Remove the playlist entry at the given index. Index values start counting with 0. The special value ``current`` removes the current entry. Note that removing the current entry also stops playback and starts playing the next @@ -271,12 +349,14 @@ List of Input Commands Shuffle the playlist. This is similar to what is done on start if the ``--shuffle`` option is used. -``run "command" "arg1" "arg2" ...`` +``run [ [ [...]]]`` Run the given command. Unlike in MPlayer/mplayer2 and earlier versions of mpv (0.2.x and older), this doesn't call the shell. Instead, the command is run directly, with each argument passed separately. Each argument is - expanded like in `Property Expansion`_. Note that there is a static limit - of (as of this writing) 9 arguments (this limit could be raised on demand). + expanded like in `Property Expansion`_. + + This command has a variable number of arguments, and cannot be used with + named arguments. The program is run in a detached way. mpv doesn't wait until the command is completed, but continues playback right after spawning it. @@ -376,15 +456,15 @@ List of Input Commands will seek to the previous position on start. The (optional) argument is exactly as in the ``quit`` command. -``sub-add "" [ [ [<lang>]]]`` - Load the given subtitle file. It is selected as current subtitle after - loading. +``sub-add <url> [<flags> [<title> [<lang>]]]`` + Load the given subtitle file or stream. By default, it is selected as + current subtitle after loading. - The ``flags`` args is one of the following values: + The ``flags`` argument is one of the following values: <select> - Select the subtitle immediately. + Select the subtitle immediately (default). <auto> @@ -427,11 +507,11 @@ List of Input Commands events that have already been displayed, or are within a short prefetch range. -``print-text "<string>"`` +``print-text <text>`` Print text to stdout. The string can contain properties (see - `Property Expansion`_). + `Property Expansion`_). Take care to put the argument in quotes. -``show-text "<string>" [<duration>|- [<level>]]`` +``show-text <text> [<duration> [<level>]]`` Show text on the OSD. The string can contain properties, which are expanded as described in `Property Expansion`_. This can be used to show playback time, filename, and so on. @@ -443,7 +523,7 @@ List of Input Commands <level> The minimum OSD level to show the text at (see ``--osd-level``). -``expand-text "<string>"`` +``expand-text <string>`` Property-expand the argument and return the expanded string. This can be used only through the client API or from a script using ``mp.command_native``. (see `Property Expansion`_). @@ -461,7 +541,7 @@ List of Input Commands essentially like ``quit``. Useful for the client API: playback can be stopped without terminating the player. -``mouse <x> <y> [<button> [single|double]]`` +``mouse <x> <y> [<button> [<mode>]]`` Send a mouse event with given coordinate (``<x>``, ``<y>``). Second argument: @@ -478,24 +558,24 @@ List of Input Commands <double> The mouse event represents double-click. -``keypress <key_name>`` +``keypress <name>`` Send a key event through mpv's input handler, triggering whatever - behavior is configured to that key. ``key_name`` uses the ``input.conf`` + behavior is configured to that key. ``name`` uses the ``input.conf`` naming scheme for keys and modifiers. Useful for the client API: key events can be sent to libmpv to handle internally. -``keydown <key_name>`` +``keydown <name>`` Similar to ``keypress``, but sets the ``KEYDOWN`` flag so that if the key is bound to a repeatable command, it will be run repeatedly with mpv's key repeat timing until the ``keyup`` command is called. -``keyup [<key_name>]`` +``keyup [<name>]`` Set the ``KEYUP`` flag, stopping any repeated behavior that had been - triggered. ``key_name`` is optional. If ``key_name`` is not given or is an + triggered. ``name`` is optional. If ``name`` is not given or is an empty string, ``KEYUP`` will be set on all keys. Otherwise, ``KEYUP`` will - only be set on the key specified by ``key_name``. + only be set on the key specified by ``name``. -``audio-add "<file>" [<flags> [<title> [<lang>]]]`` +``audio-add <url> [<flags> [<title> [<lang>]]]`` Load the given audio file. See ``sub-add`` command. ``audio-remove [<id>]`` @@ -523,21 +603,21 @@ List of Input Commands Input Commands that are Possibly Subject to Change -------------------------------------------------- -``af set|add|toggle|del|clr "filter1=params,filter2,..."`` +``af <operation> <value>`` Change audio filter chain. See ``vf`` command. -``vf set|add|toggle|del|clr "filter1=params,filter2,..."`` +``vf <operation> <value>`` Change video filter chain. The first argument decides what happens: - set + <set> Overwrite the previous filter chain with the new one. - add + <add> Append the new filter chain to the previous one. - toggle + <toggle> Check if the given filter (with the exact parameters) is already in the video chain. If yes, remove the filter. If no, add the filter. (If several filters are passed to the command, this is done for @@ -547,14 +627,14 @@ Input Commands that are Possibly Subject to Change without filter name and parameters as filter entry. This toggles the enable/disable flag. - del + <del> Remove the given filters from the video chain. Unlike in the other cases, the second parameter is a comma separated list of filter names or integer indexes. ``0`` would denote the first filter. Negative indexes start from the last filter, and ``-1`` denotes the last filter. - clr + <clr> Remove all filters. Note that like the other sub-commands, this does not control automatically inserted filters. @@ -593,18 +673,21 @@ Input Commands that are Possibly Subject to Change "disabled" flag for the filter with the label ``deband`` when the ``a`` key is hit. -``cycle-values ["!reverse"] <property> "<value1>" "<value2>" ...`` +``cycle-values [<"!reverse">] <property> <value1> [<value2> [...]]`` Cycle through a list of values. Each invocation of the command will set the given property to the next value in the list. The command will use the current value of the property/option, and use it to determine the current position in the list of values. Once it has found it, it will set the next value in the list (wrapping around to the first item if needed). + This command has a variable number of arguments, and cannot be used with + named arguments. + The special argument ``!reverse`` can be used to cycle the value list in reverse. The only advantage is that you don't need to reverse the value list yourself when adding a second key binding for cycling backwards. -``enable-section "<section>" [flags]`` +``enable-section <name> [<flags>]`` Enable all key bindings in the named input section. The enabled input sections form a stack. Bindings in sections on the top of @@ -626,10 +709,10 @@ Input Commands that are Possibly Subject to Change <allow-vo-dragging> Same. -``disable-section "<section>"`` +``disable-section <name>`` Disable the named input section. Undoes ``enable-section``. -``define-section "<section>" "<contents>" [default|force]`` +``define-section <name> <contents> [<flags>]`` Create a named input section, or replace the contents of an already existing input section. The ``contents`` parameter uses the same syntax as the ``input.conf`` file (except that using the section syntax in it is not @@ -657,7 +740,7 @@ Input Commands that are Possibly Subject to Change information about the key state. The special key name ``unmapped`` can be used to match any unmapped key. -``overlay-add <id> <x> <y> "<file>" <offset> "<fmt>" <w> <h> <stride>`` +``overlay-add <id> <x> <y> <file> <offset> <fmt> <w> <h> <stride>`` Add an OSD overlay sourced from raw data. This might be useful for scripts and applications controlling mpv, and which want to display things on top of the video window. @@ -668,6 +751,9 @@ Input Commands that are Possibly Subject to Change anamorphic video (such as DVD), ``osd-par`` should be read as well, and the overlay should be aspect-compensated. + This has the following named arguments. The order of them is not guaranteed, + so you should always call them with named arguments, see `Named arguments`_. + ``id`` is an integer between 0 and 63 identifying the overlay element. The ID can be used to add multiple overlay parts, update a part by using this command with an already existing ID, or to remove a part with @@ -725,18 +811,24 @@ Input Commands that are Possibly Subject to Change Remove an overlay added with ``overlay-add`` and the same ID. Does nothing if no overlay with this ID exists. -``script-message "<arg1>" "<arg2>" ...`` +``script-message [<arg1> [<arg2> [...]]]`` Send a message to all clients, and pass it the following list of arguments. What this message means, how many arguments it takes, and what the arguments mean is fully up to the receiver and the sender. Every client receives the message, so be careful about name clashes (or use ``script-message-to``). -``script-message-to "<target>" "<arg1>" "<arg2>" ...`` + This command has a variable number of arguments, and cannot be used with + named arguments. + +``script-message-to <target> [<arg1> [<arg2> [...]]]`` Same as ``script-message``, but send it only to the client named ``<target>``. Each client (scripts etc.) has a unique name. For example, Lua scripts can get their name via ``mp.get_script_name()``. -``script-binding "<name>"`` + This command has a variable number of arguments, and cannot be used with + named arguments. + +``script-binding <name>`` Invoke a script-provided key binding. This can be used to remap key bindings provided by external Lua scripts. @@ -773,7 +865,7 @@ Input Commands that are Possibly Subject to Change unseekable streams that are going out of sync. This command might be changed or removed in the future. -``screenshot-raw [subtitles|video|window]`` +``screenshot-raw [<flags>]`` Return a screenshot in memory. This can be used only through the client API. The MPV_FORMAT_NODE_MAP returned by this command has the ``w``, ``h``, ``stride`` fields set to obvious contents. The ``format`` field is set to @@ -783,7 +875,10 @@ Input Commands that are Possibly Subject to Change is freed as soon as the result mpv_node is freed. As usual with client API semantics, you are not allowed to write to the image data. -``vf-command "<label>" "<cmd>" "<args>"`` + The ``flags`` argument is like the first argument to ``screenshot`` and + supports ``subtitles``, ``video``, ``window``. + +``vf-command <label> <command> <argument>`` Send a command to the filter with the given ``<label>``. Use ``all`` to send it to all filters at once. The command and argument string is filter specific. Currently, this only works with the ``lavfi`` filter - see @@ -792,10 +887,10 @@ Input Commands that are Possibly Subject to Change Note that the ``<label>`` is a mpv filter label, not a libavfilter filter name. -``af-command "<label>" "<cmd>" "<args>"`` +``af-command <label> <command> <argument>`` Same as ``vf-command``, but for audio filters. -``apply-profile "<name>"`` +``apply-profile <name>`` Apply the contents of a named profile. This is like using ``profile=name`` in a config file, except you can map it to a key binding to change it at runtime. @@ -803,14 +898,14 @@ Input Commands that are Possibly Subject to Change There is no such thing as "unapplying" a profile - applying a profile merely sets all option values listed within the profile. -``load-script "<path>"`` +``load-script <filename>`` Load a script, similar to the ``--script`` option. Whether this waits for the script to finish initialization or not changed multiple times, and the future behavior is left undefined. -``change-list "<option>" "<operation>" "<value>"`` +``change-list <name> <operation> <value>`` This command changes list options as described in `List Options`_. The - ``<option>`` parameter is the normal option name, while ``<operation>`` is + ``<name>`` parameter is the normal option name, while ``<operation>`` is the suffix or action used on the option. Some operations take no value, but the command still requires the value -- cgit v1.2.3 From 0a7a4779a3772b26c6675910146b0d5a825d8b08 Mon Sep 17 00:00:00 2001 From: wm4 <wm4@nowhere> Date: Thu, 17 May 2018 20:34:31 +0200 Subject: input: slightly improve --input-cmdlist output Output argument names, whether varargs are used, and indicate optional arguments correctly (instead of only half of them). --- DOCS/man/input.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'DOCS/man') diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index d2c92d7476..b577b688d0 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -138,7 +138,7 @@ Like with array commands, quoting and escaping is inherently not needed in the normal case. The name of each command is defined in each command description in the -`List of Input Commands`_. +`List of Input Commands`_. ``--input-cmdlist`` also lists them. Some commands do not support named arguments (e.g. ``run`` command). You need to use APIs that pass arguments as arrays. -- cgit v1.2.3 From dee84be2225481a9eccbbb08f8423afc40c9d07c Mon Sep 17 00:00:00 2001 From: wm4 <wm4@nowhere> Date: Sat, 19 May 2018 17:26:55 +0200 Subject: manpage: update --demuxer-thread option Be a bit more detailed, and discourage disabling it. --- DOCS/man/options.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'DOCS/man') diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index ef86da4635..4c4954a99d 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -2944,9 +2944,12 @@ Demuxer ``--demuxer-thread=<yes|no>`` Run the demuxer in a separate thread, and let it prefetch a certain amount - of packets (default: yes). Having this enabled may lead to smoother - playback, but on the other hand can add delays to seeking or track - switching. + of packets (default: yes). Having this enabled leads to smoother playback, + enables features like prefetching, and prevents that stuck network freezes + the player. On the other hand, it can add overhead, or the background + prefetching can hog CPU resources. + + Disabling this option is not recommended. Use it for debugging only. ``--demuxer-readahead-secs=<seconds>`` If ``--demuxer-thread`` is enabled, this controls how much the demuxer -- cgit v1.2.3 From dbcd654e612ca32673cf2703758b05700cb87d03 Mon Sep 17 00:00:00 2001 From: wm4 <wm4@nowhere> Date: Sat, 19 May 2018 18:41:13 +0200 Subject: player: make playback termination asynchronous Until now, stopping playback aborted the demuxer and I/O layer violently by signaling mp_cancel (bound to libavformat's AVIOInterruptCB mechanism). Change it to try closing them gracefully. The main purpose is to silence those libavformat errors that happen when you request termination. Most of libavformat barely cares about the termination mechanism (AVIOInterruptCB), and essentially it's like the network connection is abruptly severed, or file I/O suddenly returns I/O errors. There were issues with dumb TLS warnings, parsers complaining about incomplete data, and some special protocols that require server communication to gracefully disconnect. We still want to abort it forcefully if it refuses to terminate on its own, so a timeout is required. Users can set the timeout to 0, which should give them the old behavior. This also removes the old mechanism that treats certain commands (like "quit") specially, and tries to terminate the demuxers even if the core is currently frozen. This is for situations where the core synchronized to the demuxer or stream layer while network is unresponsive. This in turn can only happen due to the "program" or "cache-size" properties in the current code (see one of the previous commits). Also, the old mechanism doesn't fit particularly well with the new one. We wouldn't want to abort playback immediately on a "quit" command - the new code is all about giving it a chance to end it gracefully. We'd need some sort of watchdog thread or something equally complicated to handle this. So just remove it. The change in osd.c is to prevent that it clears the status line while waiting for termination. The normal status line code doesn't output anything useful at this point, and the code path taken clears it, both of which is an annoying behavior change, so just let it show the old one. --- DOCS/man/options.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'DOCS/man') diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index 4c4954a99d..d56b52b87b 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -2951,6 +2951,19 @@ Demuxer Disabling this option is not recommended. Use it for debugging only. +``--demuxer-termination-timeout=<seconds>`` + Number of seconds the player should wait to shutdown the demuxer (default: + 0.1). The player will wait up to this much time before it closes the + stream layer forcefully. Forceful closing usually means the network I/O is + given no chance to close its connections gracefully (of course the OS can + still close TCP connections properly), and might result in annoying messages + being logged, and in some cases