diff options
Diffstat (limited to 'DOCS/man/input.rst')
| -rw-r--r-- | DOCS/man/input.rst | 1640 |
1 files changed, 1318 insertions, 322 deletions
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index 2b483a4f05..2dc9bebf57 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -41,6 +41,8 @@ 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.) +Also see `Key names`_. + input.conf syntax ----------------- @@ -60,8 +62,8 @@ character), or a symbolic name (as printed by ``--input-keylist``). command. ``<command>`` 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``. +multiple (or none) arguments, all separated by whitespace. String arguments +should be quoted, typically with ``"``. See ``Flat command syntax``. You can bind multiple commands to one key. For example: @@ -78,25 +80,124 @@ 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. +Key names +--------- + +All mouse and keyboard input is to converted to mpv-specific key names. Key +names are either special symbolic identifiers representing a physical key, or a +text key names, which are unicode code points encoded as UTF-8. These are what +keyboard input would normally produce, for example ``a`` for the A key. As a +consequence, mpv uses input translated by the current OS keyboard layout, rather +than physical scan codes. + +Currently there is the hardcoded assumption that every text key can be +represented as a single unicode code point (in NFKC form). + +All key names can be combined with the modifiers ``Shift``, ``Ctrl``, ``Alt``, +``Meta``. They must be prefixed to the actual key name, where each modifier +is followed by a ``+`` (for example ``ctrl+q``). + +The ``Shift`` modifier requires some attention. For instance ``Shift+2`` should +usually be specified as key-name ``@`` at ``input.conf``, and similarly the +combination ``Alt+Shift+2`` is usually ``Alt+@``, etc. Special key names like +``Shift+LEFT`` work as expected. If in doubt - use ``--input-test`` to check +how a key/combination is seen by mpv. + +Symbolic key names and modifier names are case-insensitive. Unicode key names +are case-sensitive because input bindings typically respect the shift key. + +Another type of key names are hexadecimal key names, that serve as fallback +for special keys that are neither unicode, nor have a special mpv defined name. +They will break as soon as mpv adds proper names for them, but can enable you +to use a key at all if that does not happen. + +All symbolic names are listed by ``--input-keylist``. ``--input-test`` is a +special mode that prints all input on the OSD. + +Comments on some symbolic names: + +``KP*`` + Keypad names. Behavior varies by backend (whether they implement this, and + on how they treat numlock), but typically, mpv tries to map keys on the + keypad to separate names, even if they produce the same text as normal keys. + +``MOUSE_BTN*``, ``MBTN*`` + Various mouse buttons. + + Depending on backend, the mouse wheel might also be represented as a button. + In addition, ``MOUSE_BTN3`` to ``MOUSE_BTN6`` are deprecated aliases for + ``WHEEL_UP``, ``WHEEL_DOWN``, ``WHEEL_LEFT``, ``WHEEL_RIGHT``. + + ``MBTN*`` are aliases for ``MOUSE_BTN*``. + +``WHEEL_*`` + Mouse wheels (typically). + +``AXIS_*`` + Deprecated aliases for ``WHEEL_*``. + +``*_DBL`` + Mouse button double clicks. + +``MOUSE_MOVE``, ``MOUSE_ENTER``, ``MOUSE_LEAVE`` + Emitted by mouse move events. Enter/leave happens when the mouse enters or + leave the mpv window (or the current mouse region, using the deprecated + mouse region input section mechanism). + +``CLOSE_WIN`` + Pseudo key emitted when closing the mpv window using the OS window manager + (for example, by clicking the close button in the window title bar). + +``GAMEPAD_*`` + Keys emitted by the SDL gamepad backend. + +``UNMAPPED`` + Pseudo-key that matches any unmapped key. (You should probably avoid this + if possible, because it might change behavior or get removed in the future.) + +``ANY_UNICODE`` + Pseudo-key that matches any key that produces text. (You should probably + avoid this if possible, because it might change behavior or get removed in + the future.) + Flat command syntax ------------------- This is the syntax used in input.conf, and referred to "input.conf syntax" in a number of other places. -``<command> ::= [<prefixes>] <command_name> (<argument>)*`` -``<argument> ::= (<string> | " <quoted_string> " )`` +| +| ``<command> ::= [<prefixes>] <command_name> (<argument>)*`` +| ``<argument> ::= (<unquoted> | " <double_quoted> " | ' <single_quoted> ' | `X <custom_quoted> X`)`` ``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. +Arguments are separated by whitespaces even if the command expects only one +argument. Arguments with whitespaces or other special characters must be quoted, +or the command cannot be parsed correctly. + +Double quotes interpret JSON/C-style escaping, like ``\t`` or ``\"`` or ``\\``. +JSON escapes according to RFC 8259, minus surrogate pair escapes. This is the +only form which allows newlines at the value - as ``\n``. + +Single quotes take the content literally, and cannot include the single-quote +character at the value. -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. +Custom quotes also take the content literally, but are more flexible than single +quotes. They start with ````` (back-quote) followed by any ASCII character, +and end at the first occurance of the same pair in reverse order, e.g. +```-foo-``` or ````bar````. The final pair sequence is not allowed at the +value - in these examples ``-``` and `````` respectively. In the second +example the last character of the value also can't be a back-quote. + +Mixed quoting at the same argument, like ``'foo'"bar"``, is not supported. + +Note that argument parsing and property expansion happen at different stages. +First, arguments are determined as described above, and then, where applicable, +properties are expanded - regardless of argument quoting. However, expansion +can still be prevented with the ``raw`` prefix or ``$>``. See `Input Command +Prefixes`_ and `Property Expansion`_. Commands specified as arrays ---------------------------- @@ -119,6 +220,9 @@ 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. +Property expansion is disabled by default for these APIs. This can be changed +with the ``expand-properties`` prefix. See `Input Command Prefixes`_. + 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. @@ -134,11 +238,10 @@ 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`_. ``--input-cmdlist`` also lists them. +The name of the command is provided with a ``name`` string field. The name of +each command is defined in each command description in the +`List of Input Commands`_. ``--input-cmdlist`` also lists them. See the +``subprocess`` command for an example. Some commands do not support named arguments (e.g. ``run`` command). You need to use APIs that pass arguments as arrays. @@ -146,6 +249,9 @@ 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. +Property expansion is disabled by default for these APIs. This can be changed +with the ``expand-properties`` prefix. See `Input Command Prefixes`_. + List of Input Commands ---------------------- @@ -201,6 +307,12 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). Mark the current time position. The next normal ``revert-seek`` command will seek back to this point, no matter how many seeks happened since last time. + mark-permanent + If set, mark the current position, and do not change the mark position + before the next ``revert-seek`` command that has ``mark`` or + ``mark-permanent`` set (or playback of the current file ends). Until + this happens, ``revert-seek`` will always seek to the marked point. This + flag cannot be combined with ``mark``. Using it without any arguments gives you the default behavior. @@ -232,6 +344,10 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). the minimum, on underflow set it to the maximum. If ``up`` or ``down`` is omitted, assume ``up``. + Whether or not key-repeat is enabled by default depends on the property. + Currently properties with continuous values are repeatable by default (like + ``volume``), while discrete values are not (like ``osd-level``). + ``multiply <name> <value>`` Similar to ``add``, but multiplies the property or option with the numeric value. @@ -301,8 +417,35 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). force Terminate playback if the first file is being played. +``playlist-play-index <integer|current|none>`` + Start (or restart) playback of the given playlist index. In addition to the + 0-based playlist entry index, it supports the following values: + + <current> + The current playlist entry (as in ``playlist-current-pos``) will be + played again (unload and reload). If none is set, playback is stopped. + (In corner cases, ``playlist-current-pos`` can point to a playlist entry + even if playback is currently inactive, + + <none> + Playback is stopped. If idle mode (``--idle``) is enabled, the player + will enter idle mode, otherwise it will exit. + + This comm and is similar to ``loadfile`` in that it only manipulates the + state of what to play next, without waiting until the current file is + unloaded, and the next one is loaded. + + Setting ``playlist-pos`` or similar properties can have a similar effect to + this command. However, it's more explicit, and guarantees that playback is + restarted if for example the new playlist entry is the same as the previous + one. + ``loadfile <url> [<flags> [<options>]]`` - Load the given file or URL and play it. + Load the given file or URL and play it. Technically, this is just a playlist + manipulation command (which either replaces the playlist or appends an entry + to it). Actual file loading happens independently. For example, a + ``loadfile`` command that replaces the current file with a new one returns + before the current file is stopped, and the new file even begins loading. Second argument: @@ -317,8 +460,10 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). The third argument is a list of options and values which should be set while the file is playing. It is of the form ``opt1=value1,opt2=value2,..``. - Not all options can be changed this way. Some options require a restart - of the player. + When using the client API, this can be a ``MPV_FORMAT_NODE_MAP`` (or a Lua + table), however the values themselves must be strings currently. These + options are set during playback, and restored to the previous value at end + of playback (see `Per-File Options`_). ``loadlist <url> [<flags>]`` Load the given playlist file or URL (like ``--playlist``). @@ -329,6 +474,10 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). Stop playback and replace the internal playlist with the new one. <append> Append the new playlist at the end of the current internal playlist. + <append-play> + Append the new playlist, and if nothing is currently playing, start + playback. (Always starts with the new playlist, even if the internal + playlist was not empty before running this command.) ``playlist-clear`` Clear the playlist, except the currently played file. @@ -350,6 +499,12 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). Shuffle the playlist. This is similar to what is done on start if the ``--shuffle`` option is used. +``playlist-unshuffle`` + Attempt to revert the previous ``playlist-shuffle`` command. This works + only once (multiple successive ``playlist-unshuffle`` commands do nothing). + May not work correctly if new recursive playlists have been opened since + a ``playlist-shuffle`` command. + ``run <command> [<arg1> [<arg2> [...]]]`` 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 @@ -378,6 +533,9 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). Similar to ``run``, but gives more control about process execution to the caller, and does does not detach the process. + You can avoid blocking until the process terminates by running this command + asynchronously. (For example ``mp.command_native_async()`` in Lua scripting.) + 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`_. @@ -387,13 +545,13 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). 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. + a filename with no path components, in which case the executable is + searched in the directories in 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 + terminates (optional, default: true). If enabled, stopping playback will automatically kill the process, and you can't start it outside of playback. @@ -409,12 +567,42 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). ``capture_stderr`` (``MPV_FORMAT_FLAG``) Same as ``capture_stdout``, but for stderr. + ``detach`` (``MPV_FORMAT_FLAG``) + Whether to run the process in detached mode (optional, default: no). In + this mode, the process is run in a new process session, and the command + does not wait for the process to terminate. If neither + ``capture_stdout`` nor ``capture_stderr`` have been set to true, + the command returns immediately after the new process has been started, + otherwise the command will read as long as the pipes are open. + + ``env`` (``MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING]``) + Set a list of environment variables for the new process (default: empty). + If an empty list is passed, the environment of the mpv process is used + instead. (Unlike the underlying OS mechanisms, the mpv command cannot + start a process with empty environment. Fortunately, that is completely + useless.) The format of the list is as in the ``execle()`` syscall. Each + string item defines an environment variable as in ``NANME=VALUE``. + + On Lua, you may use ``utils.get_env_list()`` to retrieve the current + environment if you e.g. simply want to add a new variable. + + ``stdin_data`` (``MPV_FORMAT_STRING``) + Feed the given string to the new process' stdin. Since this is a string, + you cannot pass arbitrary binary data. If the process terminates or + closes the pipe before all data is written, the remaining data is + silently discarded. Probably does not work on win32. + + ``passthrough_stdin`` (``MPV_FORMAT_FLAG``) + If enabled, wire the new process' stdin to mpv's stdin (default: no). + Before mpv 0.33.0, this argument did not exist, but the behavior was as + if this was set to true. + 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). + does not 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 @@ -433,11 +621,12 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). 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 mpv as a result of ``playback_only`` being set to true. ``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``. + Whether the process has been killed by mpv, for example as a result of + ``playback_only`` being set to true, aborting the command (e.g. by + ``mp.abort_async_command()``), or if the player is about to exit. Note that the command itself will always return success as long as the parameters are correct. Whether the process could be spawned or whether @@ -446,8 +635,32 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). 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. + In all cases, the subprocess will be terminated on player exit. Also see + `Asynchronous command details`_. Only the ``run`` command can start + processes in a truly detached way. + + .. admonition:: Warning + + Don't forget to set the ``playback_only`` field if you want the command + run while the player is in idle mode, or if you don't want that end of + playback kills the command. + + .. admonition:: Example + + :: + + local r = mp.command_native({ + name = "subprocess", + playback_only = false, + capture_stdout = true, + args = {"cat", "/proc/cpuinfo"}, + }) + if r.status == 0 then + print("result: " .. r.stdout) + end + + This is a fairly useless Lua example, which demonstrates how to run + a process in a blocking manner, and retrieving its stdout output. ``quit [<code>]`` Exit the player. If an argument is given, it's used as process exit code. @@ -494,16 +707,30 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). This works by unloading and re-adding the subtitle track. -``sub-step <skip>`` +``sub-step <skip> <flags>`` Change subtitle timing such, that the subtitle event after the next ``<skip>`` subtitle events is displayed. ``<skip>`` can be negative to step backwards. -``sub-seek <skip>`` + Secondary argument: + + primary (default) + Steps through the primary subtitles. + secondary + Steps through the secondary subtitles. + +``sub-seek <skip> <flags>`` Seek to the next (skip set to 1) or the previous (skip set to -1) subtitle. This is similar to ``sub-step``, except that it seeks video and audio instead of adjusting the subtitle delay. + Secondary argument: + + primary (default) + Seeks through the primary subtitles. + secondary + Seeks through the secondary subtitles. + For embedded subtitles (like with Matroska), this works only with subtitle events that have already been displayed, or are within a short prefetch range. @@ -529,6 +756,18 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). used only through the client API or from a script using ``mp.command_native``. (see `Property Expansion`_). +``expand-path "<string>"`` + Expand a path's double-tilde placeholders into a platform-specific path. + As ``expand-text``, this can only be used through the client API or from + a script using ``mp.command_native``. + + .. admonition:: Example + + ``mp.osd_message(mp.command_native({"expand-path", "~~home/"}))`` + + This line of Lua would show the location of the user's mpv + configuration directory on the OSD. + ``show-progress`` Show the progress bar, the elapsed time and the total duration of the file on the OSD. @@ -537,11 +776,24 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). Write the resume config file that the ``quit-watch-later`` command writes, but continue playback normally. -``stop`` +``delete-watch-later-config [<filename>]`` + Delete any existing resume config file that was written by + ``quit-watch-later`` or ``write-watch-later-config``. If a filename is + specified, then the deleted config is for that file; otherwise, it is the + same one as would be written by ``quit-watch-later`` or + ``write-watch-later-config`` in the current circumstance. + +``stop [<flags>]`` Stop playback and clear playlist. With default settings, this is essentially like ``quit``. Useful for the client API: playback can be stopped without terminating the player. + The first argument is optional, and supports the following flags: + + keep-playlist + Do not clear the playlist. + + ``mouse <x> <y> [<button> [<mode>]]`` Send a mouse event with given coordinate (``<x>``, ``<y>``). @@ -576,6 +828,12 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). empty string, ``KEYUP`` will be set on all keys. Otherwise, ``KEYUP`` will only be set on the key specified by ``name``. +``keybind <name> <command>`` + Binds a key to an input command. ``command`` must be a complete command + containing all the desired arguments and flags. Both ``name`` and + ``command`` use the ``input.conf`` naming scheme. This is primarily + useful for the client API. + ``audio-add <url> [<flags> [<title> [<lang>]]]`` Load the given audio file. See ``sub-add`` command. @@ -585,10 +843,22 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). ``audio-reload [<id>]`` Reload the given audio tracks. See ``sub-reload`` command. +``video-add <url> [<flags> [<title> [<lang> [<albumart>]]]]`` + Load the given video file. See ``sub-add`` command for common options. + + ``albumart`` (``MPV_FORMAT_FLAG``) + If enabled, mpv will load the given video as album art. + +``video-remove [<id>]`` + Remove the given video track. See ``sub-remove`` command. + +``video-reload [<id>]`` + Reload the given video tracks. See ``sub-reload`` command. + ``rescan-external-files [<mode>]`` - Rescan external files according to the current ``--sub-auto`` and - ``--audio-file-auto`` settings. This can be used to auto-load external - files *after* the file was loaded. + Rescan external files according to the current ``--sub-auto``, + ``--audio-file-auto`` and ``--cover-art-auto`` settings. This can be used + to auto-load external files *after* the file was loaded. The ``mode`` argument is one of the following: @@ -610,6 +880,10 @@ Input Commands that are Possibly Subject to Change ``vf <operation> <value>`` Change video filter chain. + The semantics are exactly the same as with option parsing (see + `VIDEO FILTERS`_). As such the text below is a redundant and incomplete + summary. + The first argument decides what happens: <set> @@ -619,8 +893,8 @@ Input Commands that are Possibly Subject to Change Append the new filter chain to the previous one. <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. + Check if the given filter (with the exact parameters) is already in the + video chain. If it is, remove the filter. If it isn't, add the filter. (If several filters are passed to the command, this is done for each filter.) @@ -628,12 +902,15 @@ Input Commands that are Possibly Subject to Change without filter name and parameters as filter entry. This toggles the enable/disable flag. + <remove> + Like ``toggle``, but always remove the given filter from the chain. + <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. + filter. Deprecated, use ``remove``. <clr> Remove all filters. Note that like the other sub-commands, this does @@ -659,7 +936,7 @@ Input Commands that are Possibly Subject to Change .. admonition:: Example for input.conf - - ``a vf set flip`` turn video upside-down on the ``a`` key + - ``a vf set vflip`` turn the video upside-down on the ``a`` key - ``b vf set ""`` remove all video filters on ``b`` - ``c vf toggle gradfun`` toggle debanding on ``c`` @@ -689,6 +966,8 @@ Input Commands that are Possibly Subject to Change list yourself when adding a second key binding for cycling backwards. ``enable-section <name> [<flags>]`` + This command is deprecated, except for mpv-internal uses. + Enable all key bindings in the named input section. The enabled input sections form a stack. Bindings in sections on the top of @@ -711,9 +990,13 @@ Input Commands that are Possibly Subject to Change Same. ``disable-section <name>`` + This command is deprecated, except for mpv-internal uses. + Disable the named input section. Undoes ``enable-section``. ``define-section <name> <contents> [<flags>]`` + This command is deprecated, except for mpv-internal uses. + 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 @@ -812,6 +1095,115 @@ 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. +``osd-overlay`` + Add/update/remove an OSD overlay. + + (Although this sounds similar to ``overlay-add``, ``osd-overlay`` is for + text overlays, while ``overlay-add`` is for bitmaps. Maybe ``overlay-add`` + will be merged into ``osd-overlay`` to remove this oddity.) + + You can use this to add text overlays in ASS format. ASS has advanced + positioning and rendering tags, which can be used to render almost any kind + of vector graphics. + + This command accepts the following parameters: + + ``id`` + Arbitrary integer that identifies the overlay. Multiple overlays can be + added by calling this command with different ``id`` parameters. Calling + this command with the same ``id`` replaces the previously set overlay. + + There is a separate namespace for each libmpv client (i.e. IPC + connection, script), so IDs can be made up and assigned by the API user + without conflicting with other API users. + + If the libmpv client is destroyed, all overlays associated with it are + also deleted. In particular, connecting via ``--input-ipc-server``, + adding an overlay, and disconnecting will remove the overlay immediately + again. + + ``format`` + String that gives the type of the overlay. Accepts the following values + (HTML rendering of this is broken, view the generated manpage instead, + or the raw RST source): + + ``ass-events`` + The ``data`` parameter is a string. The string is split on the + newline character. Every line is turned into the ``Text`` part of + a ``Dialogue`` ASS event. Timing is unused (but behavior of timing + dependent ASS tags may change in future mpv versions). + + Note that it's better to put multiple lines into ``data``, instead + of adding multiple OSD overlays. + + This provides 2 ASS ``Styles``. ``OSD`` contains the text style as + defined by the current ``--osd-...`` options. ``Default`` is + similar, and contains style that ``OSD`` would have if all options + were set to the default. + + In addition, the ``res_x`` and ``res_y`` options specify the value + of the ASS ``PlayResX`` and ``PlayResY`` header fields. If ``res_y`` + is set to 0, ``PlayResY`` is initialized to an arbitrary default + value (but note that the default for this command is 720, not 0). + If ``res_x`` is set to 0, ``PlayResX`` is set based on ``res_y`` + such that a virtual ASS pixel has a square pixel aspect ratio. + + ``none`` + Special value that causes the overlay to be removed. Most parameters + other than ``id`` and ``format`` are mostly ignored. + + ``data`` + String defining the overlay contents according to the ``format`` + parameter. + + ``res_x``, ``res_y`` + Used if ``format`` is set to ``ass-events`` (see description there). + Optional, defaults to 0/720. + + ``z`` + The Z order of the overlay. Optional, defaults to 0. + + Note that Z order between different overlays of different formats is + static, and cannot be changed (currently, this means that bitmap + overlays added by ``overlay-add`` are always on top of the ASS overlays + added by ``osd-overlay``). In addition, the builtin OSD components are + always below any of the custom OSD. (This includes subtitles of any kind + as well as text rendered by ``show-text``.) + + It's possible that future mpv versions will randomly change how Z order + between different OSD formats and builtin OSD is handled. + + ``hidden`` + If set to true, do not display this (default: false). + + ``compute_bounds`` + If set to true, attempt to determine bounds and write them to the + command's result value as ``x0``, ``x1``, ``y0``, ``y1`` rectangle + (default: false). If the rectangle is empty, not known, or somehow + degenerate, it is not set. ``x1``/``y1`` is the coordinate of the + bottom exclusive corner of the rectangle. + + The result value may depend on the VO window size, and is based on the + last known window size at the time of the call. This means the results + may be different from what is actually rendered. + + For ``ass-events``, the result rectangle is recomputed to ``PlayRes`` + coordinates (``res_x``/``res_y``). If window size is not known, a + fallback is chosen. + + You should be aware that this mechanism is very inefficient, as it + renders the full result, and then uses the bounding box of the rendered + bitmap list (even if ``hidden`` is set). It will flush various caches. + Its results also depend on the used libass version. + + This feature is experimental, and may change in some way again. + + .. note:: + + Always use named arguments (``mpv_command_node()``). Lua scripts should + use the ``mp.create_osd_overlay()`` helper instead of invoking this + command directly. + ``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 @@ -824,7 +1216,8 @@ Input Commands that are Possibly Subject to Change ``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()``. + Lua scripts can get their name via ``mp.get_script_name()``. Note that + client names only consist of alphanumeric characters and ``_``. This command has a variable number of arguments, and cannot be used with named arguments. @@ -836,7 +1229,8 @@ Input Commands that are Possibly Subject to Change The argument is the name of the binding. It can optionally be prefixed with the name of the script, using ``/`` as - separator, e.g. ``script-binding scriptname/bindingname``. + separator, e.g. ``script-binding scriptname/bindingname``. Note that script + names only consist of alphanumeric characters and ``_``. For completeness, here is how this command works internally. The details could change any time. On any matching key event, ``script-message-to`` @@ -847,8 +1241,13 @@ Input Commands that are Possibly Subject to Change 2. The name of the binding (as established above). 3. The key state as string (see below). 4. The key name (since mpv 0.15.0). + 5. The text the key would produce, or empty string if not applicable. - The key state consists of 2 letters: + The 5th argument is only set if no modifiers are present (using the shift + key with a letter is normally not emitted as having a modifier, and results + in upper case text instead, but some backends may mess up). + + The key state consists of 2 characters: 1. One of ``d`` (key was pressed down), ``u`` (was released), ``r`` (key is still down, and was repeated; only if key repeat is enabled for this @@ -856,6 +1255,9 @@ Input Commands that are Possibly Subject to Change 2. Whether the event originates from the mouse, either ``m`` (mouse button) or ``-`` (something else). + Future versions can add more arguments and more key state characters to + support more input peculiarities. + ``ab-loop`` Cycle through A-B loop states. The first command will set the ``A`` point (the ``ab-loop-a`` property); the second the ``B`` point, and the third @@ -876,6 +1278,12 @@ 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. + The ``stride`` is the number of bytes from a pixel at ``(x0, y0)`` to the + pixel at ``(x0, y0 + 1)``. This can be larger than ``w * 4`` if the image + was cropped, or if there is padding. This number can be negative as well. + You access a pixel with ``byte_index = y * stride + x * 4`` (assuming the + ``bgr0`` format). + The ``flags`` argument is like the first argument to ``screenshot`` and supports ``subtitles``, ``video``, ``window``. @@ -891,19 +1299,31 @@ Input Commands that are Possibly Subject to Change ``af-command <label> <command> <argument>`` Same as ``vf-command``, but for audio filters. -``apply-profile <name>`` +``apply-profile <name> [<mode>]`` 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. - There is no such thing as "unapplying" a profile - applying a profile - merely sets all option values listed within the profile. + The mode argument: + + ``default`` + Apply the profile. Default if the argument is omitted. + + ``restore`` + Restore options set by a previous ``apply-profile`` command for this + profile. Only works if the profile has ``profile-restore`` set to a + relevant mode. Prints a warning if nothing could be done. See + `Runtime profiles`_ for details. ``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. + On success, returns a ``mpv_node`` with a ``client_id`` field set to the + return value of the ``mpv_client_id()`` API call of the newly created script + handle. + ``change-list <name> <operation> <value>`` This command changes list options as described in `List Options`_. The ``<name>`` parameter is the normal option name, while ``<operation>`` is @@ -920,9 +1340,268 @@ Input Commands that are Possibly Subject to Change equivalent is ``--glsl-shaders-append=file.glsl`` or alternatively ``--glsl-shader=file.glsl``. +``dump-cache <start> <end> <filename>`` + Dump the current cache to the given filename. The ``<filename>`` file is + overwritten if it already exists. ``<start>`` and ``<end>`` give the + time range of what to dump. If no data is cached at the given time range, + nothing may be dumped (creating a file with no packets). + + Dumping a larger part of the cache will freeze the player. No effort was + made to fix this, as this feature was meant mostly for creating small + excerpts. + + See ``--stream-record`` for various caveats that mostly apply to this + command too, as both use the same underlying code for writing the output + file. + + If ``<filename>`` is an empty string, an ongoing ``dump-cache`` is stopped. + + If ``<end>`` is ``no``, then continuous dumping is enabled. Then, after + |