COMMAND INTERFACE ================= The mpv core can be controlled with commands and properties. A number of ways to interact with the player use them: key bindings (``input.conf``), OSD (showing information with properties), JSON IPC, the client API (``libmpv``), and the classic slave mode. input.conf ---------- The input.conf file consists of a list of key bindings, for example:: s screenshot # take a screenshot with the s key LEFT seek 15 # map the left-arrow key to seeking forward by 15 seconds Each line maps a key to an input command. Keys are specified with their literal value (upper case if combined with ``Shift``), or a name for special keys. For example, ``a`` maps to the ``a`` key without shift, and ``A`` maps to ``a`` with shift. The file is located in the mpv configuration directory (normally at ``~/.config/mpv/input.conf`` depending on platform). The default bindings are defined here:: https://github.com/mpv-player/mpv/blob/master/etc/input.conf A list of special keys can be obtained with ``mpv --input-keylist`` In general, keys can be combined with ``Shift``, ``Ctrl`` and ``Alt``:: ctrl+q quit **mpv** can be started in input test mode, which displays key bindings and the commands they're bound to on the OSD, instead of executing the commands:: mpv --input-test --force-window --idle (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 ----------------- ``[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 ``--no-input-right-alt-gr`` changes this behavior. Newlines always start a new binding. ``#`` starts a comment (outside of quoted string arguments). To bind commands to the ``#`` key, ``SHARP`` can be used. ```` is either the literal character the key produces (ASCII or Unicode character), or a symbolic name (as printed by ``--input-keylist``). ``
`` (braced with ``{`` and ``}``) is the input section for this 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: | a show-text "command 1" ; show-text "command 2" It's also possible to bind a command to a sequence of keys: | a-b-c show-text "command run after a, b, c have been pressed" (This is not shown in the general command syntax.) If ``a`` or ``a-b`` or ``b`` are already bound, this will run the first command 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. | | `` ::= [] ()*`` | `` ::= ( | " " | ' ' | `X 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 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 ---------------------------- 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``. ``seek []`` Change the playback position. By default, seeks by a relative amount of seconds. The second argument consists of flags controlling the seek mode: relative (default) Seek relative to current position (a negative value seeks backwards). absolute Seek to a given time (a negative value starts from the end of the file). absolute-percent Seek to a given percent position. relative-percent Seek relative to current position in percent. keyframes Always restart playback at keyframe boundaries (fast). exact Always do exact/hr/precise seeks (slow). Multiple flags can be combined, e.g.: ``absolute+keyframes``. 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 []`` 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 ``revert-seek`` command itself. This only works within a single file. The first argument is optional, and can change the behavior: mark 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. ``frame-step`` Play one frame, then pause. Does nothing with audio-only playback. ``frame-back-step`` Go back by one frame, then pause. Note that this can be very slow (it tries to be precise, not fast), and sometimes fails to behave as expected. How well this works depends on whether precise seeking works correctly (e.g. see the ``--hr-seek-demuxer-offset`` option). Video filters or other video post-processing that modifies timing of frames (e.g. deinterlacing) should usually work, but might make backstepping silently behave incorrectly in corner cases. Using ``--hr-seek-framedrop=no`` should help, although it might make precise seeking slower. This does not work with audio-only playback. ``set `` Set the given property or option to the given value. ``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 []`` 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``. 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 `` Similar to ``add``, but multiplies the property or option with the numeric value. ``screenshot `` Take a screenshot. Multiple flags are available (some can be combined with ``+``): (default) Save the video image, in its original resolution, and with subtitles. Some video outputs may still include the OSD in the output under certain circumstances.