diff options
Diffstat (limited to 'DOCS/man/input.rst')
| -rw-r--r-- | DOCS/man/input.rst | 2608 |
1 files changed, 2096 insertions, 512 deletions
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index ef3ceb1fb5..df4766b5be 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -41,14 +41,16 @@ 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 ----------------------------- +Also see `Key names`_. + +input.conf syntax +----------------- -``[Shift+][Ctrl+][Alt+][Meta+]<key> [{<section>}] [<prefixes>] <command> (<argument>)* [; <command>]`` +``[Shift+][Ctrl+][Alt+][Meta+]<key> [{<section>}] <command> ( ; <command> )*`` 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 -``--no-input-right-alt-gr`` changes this behavior. +characters, and thus does not register as a modifier. This can be changed +with ``--input-right-alt-gr`` option. Newlines always start a new binding. ``#`` starts a comment (outside of quoted string arguments). To bind commands to the ``#`` key, ``SHARP`` can be used. @@ -59,9 +61,9 @@ character), or a symbolic name (as printed by ``--input-keylist``). ``<section>`` (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. +``<command>`` is the command itself. It consists of the command name and +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,15 +80,193 @@ 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> ::= (<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 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. + +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 occurrence 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 +---------------------------- + +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. + +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. + +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 +--------------- + +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. + +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. + +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 ---------------------- +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``. + ``--input-default-bindings=no``. -``seek <seconds> [relative|absolute|absolute-percent|relative-percent|exact|keyframes]`` +``seek <target> [<flags>]`` Change the playback position. By default, seeks by a relative amount of seconds. @@ -107,14 +287,15 @@ List of Input Commands Multiple flags can be combined, e.g.: ``absolute+keyframes``. - By default, ``keyframes`` is used for relative seeks, and ``exact`` is used - for absolute seeks. + By default, ``keyframes`` is used for ``relative``, ``relative-percent``, + and ``absolute-percent`` seeks, while ``exact`` is used for ``absolute`` + seeks. Before mpv 0.9, the ``keyframes`` and ``exact`` flags had to be passed as 3rd parameter (essentially using a space instead of ``+``). The 3rd parameter is still parsed, but is considered deprecated. -``revert-seek [mode]`` +``revert-seek [<flags>]`` 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 @@ -126,6 +307,12 @@ List of Input Commands 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. @@ -144,22 +331,31 @@ List of Input Commands This does not work with audio-only playback. -``set <property> "<value>"`` - Set the given property to the given value. +``set <name> <value>`` + Set the given property or option to the given value. -``add <property> [<value>]`` - Add the given value to the property. On overflow or underflow, clamp the - property to the maximum. If ``<value>`` is omitted, assume ``1``. +``del <name>`` + Delete the given property. Most properties cannot be deleted. -``cycle <property> [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``. +``add <name> [<value>]`` + Add the given value to the property or option. On overflow or underflow, + clamp the property to the maximum. If ``<value>`` is omitted, assume ``1``. -``multiply <property> <factor>`` - Multiplies the value of a property with the numeric factor. +``cycle <name> [<value>]`` + 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``. -``screenshot [subtitles|video|window|single|each-frame]`` + 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. + +``screenshot <flags>`` Take a screenshot. Multiple flags are available (some can be combined with ``+``): @@ -173,8 +369,7 @@ List of Input Commands behavior depends on the selected video output. <window> Save the contents of the mpv window. Typically scaled, with OSD and - subtitles. The exact behavior depends on the selected video output, and - if no support is available, this will act like ``video``. + subtitles. The exact behavior depends on the selected video output. <each-frame> Take a screenshot each frame. Issue this command again to stop taking screenshots. Note that you should disable frame-dropping when using @@ -186,45 +381,83 @@ 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 "<filename>" [subtitles|video|window]`` + On success, returns a ``mpv_node`` with a ``filename`` field set to the + saved screenshot location. + +``screenshot-to-file <filename> <flags>`` 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`_. - The ``async`` flag has an effect on this command (see ``screenshot`` - command). - -``playlist-next [weak|force]`` +``playlist-next <flags>`` 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 <flags>`` 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 "<file>" [replace|append|append-play [options]]`` - Load the given file and play it. +``playlist-next-playlist`` + Go to the next entry on the playlist with a different ``playlist-path``. + +``playlist-prev-playlist`` + Go to the first of the previous entries on the playlist with a different + ``playlist-path``. + +``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 command 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> [<index> [<options>]]]`` + Load the given file or URL and play it. Technically, this is just a playlist + manipulation command (which either replaces the playlist or adds 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: @@ -236,19 +469,71 @@ List of Input Commands Append the file, and if nothing is currently playing, start playback. (Always starts with the added file, even if the playlist was not empty before running this command.) - - The third argument is a list of options and values which should be set + <insert-next> + Insert the file into the playlist, directly after the current entry. + <insert-next-play> + Insert the file next, and if nothing is currently playing, start playback. + (Always starts with the added file, even if the playlist was not empty + before running this command.) + <insert-at> + Insert the file into the playlist, at the index given in the third + argument. + <insert-at-play> + Insert the file at the index given in the third argument, and if nothing + is currently playing, start playback. (Always starts with the added + file, even if the playlist was not empty before running this command.) + + The third argument is an insertion index, used only by the ``insert-at`` and + ``insert-at-play`` actions. When used with those actions, the new item will + be inserted at the index position in the playlist, or appended to the end if + index is less than 0 or greater than the size of the playlist. This argument + will be ignored for all other actions. + + The fourth 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> [<index>]]`` + Load the given playlist file or URL (like ``--playlist``). + + Second argument: -``loadlist "<playlist>" [replace|append]`` - Load the given playlist file (like ``--playlist``). + <replace> (default) + 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.) + <insert-next> + Insert the new playlist into the current internal playlist, directly + after the current entry. + <insert-next-play> + Insert 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.) + <insert-at> + Insert the new playlist at the index given in the third argument. + <insert-at-play> + Insert the new playlist at the index given in the third argument, 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.) + + The third argument is an insertion index, used only by the ``insert-at`` and + ``insert-at-play`` actions. When used with those actions, the new playlist + will be inserted at the index position in the internal playlist, or appended + to the end if index is less than 0 or greater than the size of the internal + playlist. This argument will be ignored for all other actions. ``playlist-clear`` Clear the playlist, except the currently played file. -``playlist-remove current|<index>`` +``playlist-remove <index>`` 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 @@ -265,12 +550,20 @@ 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" ...`` +``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 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. @@ -287,23 +580,160 @@ 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. + + 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`_. + + ``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. + + The first array entry is either an absolute path to the executable, or + 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 + of the current playlist entry terminates (optional, default: true). 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. + + ``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 ``NAME=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``) + Typically this is the process exit code (0 or positive) if the process + terminates normally, or negative for other errors (failed to start, + terminated by mpv, and others). The meaning of negative values is + undefined, other than meaning error (and 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 terminates normally, 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 terminated normally. 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 true. + + ``killed_by_us`` (``MPV_FORMAT_FLAG``) + 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 + 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. Also see `Asynchronous + command details`_. Only the ``run`` command can start processes in a truly + detached way. + + .. note:: The subprocess will always be terminated on player exit if it + wasn't started in detached mode, even if ``playback_only`` is + false. + + .. warning:: + + Don't forget to set the ``playback_only`` field to false if you want + the command to run while the player is in idle mode, or if you don't + want the end of playback to kill 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. ``quit-watch-later [<code>]`` Exit player, and store current playback position. Playing that file later will seek to the previous position on start. The (optional) argument is - exactly as in the ``quit`` command. + exactly as in the ``quit`` command. See `RESUMING PLAYBACK`_. -``sub-add "<file>" [<flags> [<title> [<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> @@ -332,32 +762,46 @@ List of Input Commands 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>`` - Seek to the next (skip set to 1) or the previous (skip set to -1) subtitle. + Secondary argument: + + primary (default) + Steps through the primary subtitles. + secondary + Steps through the secondary subtitles. + +``sub-seek <skip> <flags>`` + Change video and audio position such that the subtitle event after + ``<skip>`` subtitle events is displayed. For example, ``sub-seek 1`` skips + to the next subtitle, ``sub-seek -1`` skips to the previous subtitles, and + ``sub-seek 0`` seeks to the beginning of the current 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. - -``osd [<level>]`` - Toggle OSD level. If ``<level>`` is specified, set the OSD mode - (see ``--osd-level`` for valid values). + range. See `Cache`_ for details on how to control the available 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>|-1 [<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. + time, filename, and so on. ``no-osd`` has no effect on this command. <duration> The time in ms to show the message for. By default, it uses the same @@ -366,25 +810,77 @@ List of Input Commands <level> The minimum OSD level to show the text at (see ``--osd-level``). -``expand-text "<string>"`` +``expand-text <text>`` 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`_). +``expand-path "<text>"`` + 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. + +``normalize-path <filename>`` + Return a canonical representation of the path ``filename`` by converting it + to an absolute path, removing consecutive slashes, removing ``.`` + components, resolving ``..`` components, and converting slashes to + backslashes on Windows. Symlinks are not resolved unless the platform is + Unix-like and one of the path components is ``..``. If ``filename`` is a + URL, it is returned unchanged. 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({"normalize-path", "/foo//./bar"}))`` + + This line of Lua prints "/foo/bar" on the OSD. + +``escape-ass <text>`` + Modify ``text`` so that commands and functions that interpret ASS tags, + such as ``osd-overlay`` and ``mp.create_osd_overlay``, will display it + verbatim, and return it. 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({"escape-ass", "foo {bar}"}))`` + + This line of Lua prints "foo \\{bar}" on the OSD. + ``show-progress`` Show the progress bar, the elapsed time and the total duration of the file - on the OSD. + on the OSD. ``no-osd`` has no effect on this command. ``write-watch-later-config`` 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. -``mouse <x> <y> [<button> [single|double]]`` + 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>``). Second argument: @@ -401,24 +897,32 @@ List of Input Commands <double> The mouse event represents double-click. -``keypress <key_name>`` +``keypress <name> [<scale>]`` Send a key event through mpv's input handler, triggering whatever - behavior is configured to that key. ``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. + behavior is configured to that key. ``name`` uses the ``input.conf`` + naming scheme for keys and modifiers. ``scale`` is used to scale numerical + change effected by the bound command (same mechanism as precise scrolling). + 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 |