diff options
Diffstat (limited to '')
| -rw-r--r-- | DOCS/man/input.rst | 3697 |
1 files changed, 3697 insertions, 0 deletions
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst new file mode 100644 index 0000000..8dbf58b --- /dev/null +++ b/DOCS/man/input.rst @@ -0,0 +1,3697 @@ +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+]<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. + +Newlines always start a new binding. ``#`` starts a comment (outside of quoted +string arguments). To bind commands to the ``#`` key, ``SHARP`` can be used. + +``<key>`` is either the literal character the key produces (ASCII or Unicode +character), or a symbolic name (as printed by ``--input-keylist``). + +``<section>`` (braced with ``{`` and ``}``) is the input section for this +command. + +``<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. + +| +| ``<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``. + +``seek <target> [<flags>]`` + 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 [<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 + ``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 <name> <value>`` + Set the given property or option to the given value. + +``del <name>`` + Delete the given property. Most properties cannot be deleted. + +``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``. + +``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``. + + 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 ``+``): + + <subtitles> (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. + <video> + Like ``subtitles``, but typically without OSD or subtitles. The exact + 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. + <each-frame> + Take a screenshot each frame. Issue this command again to stop taking + screenshots. Note that you should disable frame-dropping when using + this mode - or you might receive duplicate images in cases when a + frame was dropped. This flag can be combined with the other flags, + e.g. ``video+each-frame``. + + Older mpv versions required passing ``single`` and ``each-frame`` as + second argument (and did not have flags). This syntax is still understood, + but deprecated and might be removed in the future. + + 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.) + + 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`` 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 <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 <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. + +``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> [<options>]]`` + 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: + + <replace> (default) + Stop playback of the current file, and play the new file immediately. + <append> + Append the file to the playlist. + <append-play> + 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 + while the file is playing. It is of the form ``opt1=value1,opt2=value2,..``. + 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``). + + Second argument: + + <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.) + +``playlist-clear`` + Clear the playlist, except the currently played file. + +``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 + entry. + +``playlist-move <index1> <index2>`` + Move the playlist entry at index1, so that it takes the place of the + entry index2. (Paradoxically, the moved playlist entry will not have + the index value index2 after moving if index1 was lower than index2, + because index2 refers to the target entry, not the index the entry + will have after moving.) + +``playlist-shuffle`` + 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 + is run directly, with each argument passed separately. Each argument is + 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. + + To get the old behavior, use ``/bin/sh`` and ``-c`` as the first two + arguments. + + .. admonition:: Example + + ``run "/bin/sh" "-c" "echo ${title} > /tmp/playing"`` + + This is not a particularly good example, because it doesn't handle + escaping, and a specially prepared file might allow an attacker to + 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. + + .. admonition:: 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. See `RESUMING PLAYBACK`_. + +``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`` argument is one of the following values: + + <select> + + Select the subtitle immediately (default). + + <auto> + + Don't select the subtitle. (Or in some special situations, let the + default stream selection mechanism decide.) + + <cached> + + Select the subtitle. If a subtitle with the same filename was already + added, that one is selected, instead of loading a duplicate entry. + (In this case, title/language are ignored, and if the was changed since + it was loaded, these changes won't be reflected.) + + The ``title`` argument sets the track title in the UI. + + The ``lang`` argument sets the track language, and can also influence + stream selection with ``flags`` set to ``auto``. + +``sub-remove [<id>]`` + Remove the given subtitle track. If the ``id`` argument is missing, remove + the current track. (Works on external subtitle files only.) + +``sub-reload [<id>]`` + Reload the given subtitle tracks. If the ``id`` argument is missing, reload + the current track. (Works on external subtitle files only.) + + This works by unloading and re-adding the subtitle track. + +``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. + + 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. + +``print-text <text>`` + Print text to stdout. The string can contain properties (see + `Property Expansion`_). Take care to put the argument in quotes. + +``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. ``no-osd`` has no effect on this command. + + <duration> + The time in ms to show the message for. By default, it uses the same + value as ``--osd-duration``. + + <level> + The minimum OSD level to show the text at (see ``--osd-level``). + +``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`_). + +``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. ``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. + +``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>``). + + Second argument: + + <button> + The button number of clicked mouse button. This should be one of 0-19. + If ``<button>`` is omitted, only the position will be updated. + + Third argument: + + <single> (default) + The mouse event represents regular single click. + + <double> + The mouse event represents double-click. + +``keypress <name>`` + Send a key event through mpv's input handler, triggering whatever + 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 <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 [<name>]`` + Set the ``KEYUP`` flag, stopping any repeated behavior that had been + 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 ``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. + +``audio-remove [<id>]`` + Remove the given audio track. See ``sub-remove`` command. + +``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``, + ``--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: + + <reselect> (default) + Select the default audio and subtitle streams, which typically selects + external files with the highest preference. (The implementation is not + perfect, and could be improved on request.) + + <keep-selection> + Do not change current track selections. + + +Input Commands that are Possibly Subject to Change +-------------------------------------------------- + +``af <operation> <value>`` + Change audio filter chain. See ``vf`` command. + +``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> + Overwrite the previous filter chain with the new one. + + <add> + 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 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.) + + A special variant is combining this with labels, and using ``@name`` + 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. + + <clr> + Remove all filters. Note that like the other sub-commands, this does + not control automatically inserted filters. + + The argument is always needed. E.g. in case of ``clr`` use ``vf clr ""``. + + You can assign labels to filter by prefixing them with ``@name:`` (where + ``name`` is a user-chosen arbitrary identifier). Labels can be used to + refer to filters by name in all of the filter chain modification commands. + For ``add``, using an already used label will replace the existing filter. + + The ``vf`` command shows the list of requested filters on the OSD after + changing the filter chain. This is roughly equivalent to + ``show-text ${vf}``. Note that auto-inserted filters for format conversion + are not shown on the list, only what was requested by the user. + + Normally, the commands will check whether the video chain is recreated + successfully, and will undo the operation on failure. If the command is run + before video is configured (can happen if the command is run immediately + after opening a file and before a video frame is decoded), this check can't + be run. Then it can happen that creating the video chain fails. + + .. admonition:: Example for input.conf + + - ``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`` + + .. admonition:: Example how to toggle disabled filters at runtime + + - Add something like ``vf-add=@deband:!gradfun`` to ``mpv.conf``. + The ``@deband:`` is the label, an arbitrary, user-given name for this + filter entry. The ``!`` before the filter name disables the filter by + default. Everything after this is the normal filter name and possibly + filter parameters, like in the normal ``--vf`` syntax. + - Add ``a vf toggle @deband`` to ``input.conf``. This toggles the + "disabled" flag for the filter with the label ``deband`` when the + ``a`` key is hit. + +``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 <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 + the stack are preferred to lower sections. This command puts the section + on top of the stack. If the section was already on the stack, it is + implicitly removed beforehand. (A section cannot be on the stack more than + once.) + + The ``flags`` parameter can be a combination (separated by ``+``) of the + following flags: + + <exclusive> + All sections enabled before the newly enabled section are disabled. + They will be re-enabled as soon as all exclusive sections above them + are removed. In other words, the new section shadows all previous + sections. + <allow-hide-cursor> + This feature can't be used through the public API. + <allow-vo-dragging> + 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 + allowed), including the need to separate bindings with a newline character. + + If the ``contents`` parameter is an empty string, the section is removed. + + The section with the name ``default`` is the normal input section. + + In general, input sections have to be enabled with the ``enable-section`` + command, or they are ignored. + + The last parameter has the following meaning: + + <default> (also used if parameter omitted) + Use a key binding defined by this section only if the user hasn't + already bound this key to a command. + <force> + Always bind a key. (The input section that was made active most recently + wins if there are ambiguities.) + + This command can be used to dispatch arbitrary keys to a script or a client + API user. If the input section defines ``script-binding`` commands, it is + also possible to get separate events on key up/down, and relatively detailed + 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>`` + 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. + + Overlays are usually displayed in screen resolution, but with some VOs, + the resolution is reduced to that of the video's. You can read the + ``osd-width`` and ``osd-height`` properties. At least with ``--vo-xv`` and + 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 + ``overlay-remove``. Using a previously unused ID will add a new overlay, + while reusing an ID will update it. + + ``x`` and ``y`` specify the position where the OSD should be displayed. + + ``file`` specifies the file the raw image data is read from. It can be + either a numeric UNIX file descriptor prefixed with ``@`` (e.g. ``@4``), + or a filename. The file will be mapped into memory with ``mmap()``, + copied, and unmapped before the command returns (changed in mpv 0.18.1). + + It is also possible to pass a raw memory address for use as bitmap memory + by passing a memory address as integer prefixed with an ``&`` character. + Passing the wrong thing here will crash the player. This mode might be + useful for use with libmpv. The ``offset`` parameter is simply added to the + memory address (since mpv 0.8.0, ignored before). + + ``offset`` is the byte offset of the first pixel in the source file. + (The current implementation always mmap's the whole file from position 0 to + the end of the image, so large offsets should be avoided. Before mpv 0.8.0, + the offset was actually passed directly to ``mmap``, but it was changed to + make using it easier.) + + ``fmt`` is a string identifying the image format. Currently, only ``bgra`` + is defined. This format has 4 bytes per pixels, with 8 bits per component. + The least significant 8 bits are blue, and the most significant 8 bits + are alpha (in little endian, the components are B-G-R-A, with B as first + byte). This uses premultiplied alpha: every color component is already + multiplied with the alpha component. This means the numeric value of each + component is equal to or smaller than the alpha component. (Violating this + rule will lead to different results with different VOs: numeric overflows + resulting from blending broken alpha values is considered something that + shouldn't happen, and consequently implementations don't ensure that you + get predictable behavior in this case.) + + ``w``, ``h``, and ``stride`` specify the size of the overlay. ``w`` is the + visible width of the overlay, while ``stride`` gives the width in bytes in + memory. In the simple case, and with the ``bgra`` format, ``stride==4*w``. + In general, the total amount of memory accessed is ``stride * h``. + (Technically, the minimum size would be ``stride * (h - 1) + w * 4``, but + for simplicity, the player will access all ``stride * h`` bytes.) + + .. note:: + + Before mpv 0.18.1, you had to do manual "double buffering" when updating + an overlay by replacing it with a different memory buffer. Since mpv + 0.18.1, the memory is simply copied and doesn't reference any of the + memory indicated by the command's arguments after the command returns. + If you want to use this command before mpv 0.18.1, reads the old docs + to see how to handle this correctly. + +``overlay-remove <id>`` + 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 + 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``). + + 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()``. 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. + +``script-binding <name>`` + Invoke a script-provided key binding. This can be used to remap key + bindings provided by external Lua scripts. + + 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``. 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`` + or ``script-message`` is called (depending on whether the script name is + included), with the following arguments: + + 1. The string ``key-binding``. + 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 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 + binding), ``p`` (key was pressed; happens if up/down can't be tracked). + 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 + will clear both points. + +``drop-buffers`` + Drop audio/video/demuxer buffers, and restart from fresh. Might help with + unseekable streams that are going out of sync. + This command might be changed or removed in the future. + +``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 + ``bgr0`` by default. This format is organized as ``B8G8R8X8`` (where ``B`` + is the LSB). The contents of the padding ``X`` are undefined. The ``data`` + field is of type MPV_FORMAT_BYTE_ARRAY with the actual image data. The image + 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``. + +``vf-command <label> <command> <argument> [<target>]`` + Send a command to the filter. Note that currently, this only works with + the ``lavfi`` filter. Refer to the libavfilter documentation for the list + of supported commands for each filter. + + ``<label>`` is a mpv filter label, use ``all`` to send it to all filters + at once. + + ``<command>`` and ``<argument>`` are filter-specific strings. + + ``<target>`` is a filter or filter instance name and defaults to ``all``. + Note that the target is an additional specifier for filters that + support them, such as complex ``lavfi`` filter chains. + +``af-command <label> <command> <argument> [<target>]`` + Same as ``vf-command``, but for audio filters. + +``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. + + 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 + the suffix or action used on the option. + + Some operations take no value, but the command still requires the value + parameter. In these cases, the value must be an empty string. + + .. admonition:: Example + + ``change-list glsl-shaders append file.glsl`` + + Add a filename to the ``glsl-shaders`` list. The command line + 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 + dumping the existing parts of the cache, anything read from network is + appended to the cache as well. This behaves similar to ``--stream-record`` + (although it does not conflict with that option, and they can be both active + at the same time). + + If the ``<end>`` time is after the cache, the command will _not_ wait and + write newly received data to it. + + The end of the resulting file may be slightly damaged or incomplete at the + end. (Not enough effort was made to ensure that the end lines up properly.) + + Note that this command will finish only once dumping ends. That means it + works similar to the ``screenshot`` command, just that it can block much + longer. If continuous dumping is used, the command will not finish until + playback is stopped, an error happens, another ``dump-cache`` command is + run, or an API like ``mp.abort_async_command`` was called to explicitly stop + the command. See `Synchronous vs. Asynchronous`_. + + .. note:: + + This was mostly created for network streams. For local files, there may + be much better methods to create excerpts and such. There are tons of + much more user-friendly Lua scripts, that will re-encode parts of a file + by spawning a separate instance of ``ffmpeg``. With network streams, + this is not that easily possible, as the stream would have to be + downloaded again. Even if ``--stream-record`` is used to record the + stream to the local filesystem, there may be problems, because the + recorded file is still written to. + + This command is experimental, and all details about it may change in the + future. + +``ab-loop-dump-cache <filename>`` + Essentially calls ``dump-cache`` with the current AB-loop points as + arguments. Like ``dump-cache``, this will overwrite the file at + ``<filename>``. Likewise, if the B point is set to ``no``, it will enter + continuous dumping after the existing cache was dumped. + + The author reserves the right to remove this command if enough motivation + is found to move this functionality to a trivial Lua script. + +``ab-loop-align-cache`` + Re-adjust the A/B loop points to the start and end within the cache the + ``ab-loop-dump-cache`` command will (probably) dump. Basically, it aligns + the times on keyframes. The guess might be off especially at the end (due to + granularity issues due to remuxing). If the cache shrinks in the meantime, + the points set by the command will not be the effective parameters either. + + This command has an even more uncertain future than ``ab-loop-dump-cache`` + and might disappear without replacement if the author decides it's useless. + +Undocumented commands: ``ao-reload`` (experimental/internal). + +List of events +~~~~~~~~~~~~~~ + +This is a partial list of events. This section describes what +``mpv_event_to_node()`` returns, and which is what scripting APIs and the JSON +IPC sees. Note that the C API has separate C-level declarations with +``mpv_event``, which may be slightly different. + +Note that events are asynchronous: the player core continues running while +events are delivered to scripts and other clients. In some cases, you can use +hooks to enforce synchronous execution. + +All events can have the following fields: + +``event`` + Name as the event (as returned by ``mpv_event_name()``). + +``id`` + The ``reply_userdata`` field (opaque user value). If ``reply_userdata`` is 0, + the field is not added. + +``error`` + Set to an error string (as returned by ``mpv_error_string()``). This field + is missing if no error happened, or the event type does not report error. + Most events leave this unset. + +This list uses the event name field value, and the C API symbol in brackets: + +``start-file`` (``MPV_EVENT_START_FILE``) + Happens right before a new file is loaded. When you receive this, the + player is loading the file (or possibly already done with it). + + This has the following fields: + + ``playlist_entry_id`` + Playlist entry ID of the file being loaded now. + +``end-file`` (``MPV_EVENT_END_FILE``) + Happens after a file was unloaded. Typically, the player will load the + next file right away, or quit if this was the last file. + + The event has the following fields: + + ``reason`` + Has one of these values: + + ``eof`` + The file has ended. This can (but doesn't have to) include + incomplete files or broken network connections under + circumstances. + + ``stop`` + Playback was ended by a command. + + ``quit`` + Playback was ended by sending the quit command. + + ``error`` + An error happened. In this case, an ``error`` field is present with + the error string. + + ``redirect`` + Happens with playlists and similar. Details see + ``MPV_END_FILE_REASON_REDIRECT`` in the C API. + + ``unknown`` + Unknown. Normally doesn't happen, unless the Lua API is out of sync + with the C API. (Likewise, it could happen that your script gets + reason strings that did not exist yet at the time your script was + written.) + + ``playlist_entry_id`` + Playlist entry ID of the file that was being played or attempted to be + played. This has the same value as the ``playlist_entry_id`` field in the + corresponding ``start-file`` event. + + ``file_error`` + Set to mpv error string describing the approximate reason why playback + failed. Unset if no error known. (In Lua scripting, this value was set + on the ``error`` field directly. This is deprecated since mpv 0.33.0. + In the future, this ``error`` field will be unset for this specific + event.) + + ``playlist_insert_id`` + If loading ended, because the playlist entry to be played was for example + a playlist, and the current playlist entry is replaced with a number of + other entries. This may happen at least with MPV_END_FILE_REASON_REDIRECT + (other event types may use this for similar but different purposes in the + future). In this case, playlist_insert_id will be set to the playlist + entry ID of the first inserted entry, and playlist_insert_num_entries to + the total number of inserted playlist entries. Note this in this specific + case, the ID of the last inserted entry is playlist_insert_id+num-1. + Beware that depending on circumstances, you may observe the new playlist + entries before seeing the event (e.g. reading the "playlist" property or + getting a property change notification before receiving the event). + If this is 0 in the C API, this field isn't added. + + ``playlist_insert_num_entries`` + See playlist_insert_id. Only present if playlist_insert_id is present. + +``file-loaded`` (``MPV_EVENT_FILE_LOADED``) + Happens after a file was loaded and begins playback. + +``seek`` (``MPV_EVENT_SEEK``) + Happens on seeking. (This might include cases when the player seeks + internally, even without user interaction. This includes e.g. segment + changes when playing ordered chapters Matroska files.) + +``playback-restart`` (``MPV_EVENT_PLAYBACK_RESTART``) + Start of playback after seek or after file was loaded. + +``shutdown`` (``MPV_EVENT_SHUTDOWN``) + Sent when the player quits, and the script should terminate. Normally + handled automatically. See `Details on the script initialization and lifecycle`_. + +``log-message`` (``MPV_EVENT_LOG_MESSAGE``) + Receives messages enabled with ``mpv_request_log_messages()`` (Lua: + ``mp.enable_messages``). + + This contains, in addition to the default event fields, the following + fields: + + ``prefix`` + The module prefix, identifies the sender of the message. This is what + the terminal player puts in front of the message text when using the + ``--v`` option, and is also what is used for ``--msg-level``. + + ``level`` + The log level as string. See ``msg.log`` for possible log level names. + Note that later versions of mpv might add new levels or remove + (undocumented) existing ones. + + ``text`` + The log message. The text will end with a newline character. Sometimes + it can contain multiple lines. + + Keep in mind that these messages are meant to be hints for humans. You + should not parse them, and prefix/level/text of messages might change + any time. + +``hook`` + The event has the following fields: + + ``hook_id`` + ID to pass to ``mpv_hook_continue()``. The Lua scripting wrapper + provides a better API around this with ``mp.add_hook()``. + +``get-property-reply`` (``MPV_EVENT_GET_PROPERTY_REPLY``) + See C API. + +``set-property-reply`` (``MPV_EVENT_SET_PROPERTY_REPLY``) + See C API. + +``command-reply`` (``MPV_EVENT_COMMAND_REPLY``) + This is one of the commands for which the ```error`` field is meaningful. + + JSON IPC and Lua and possibly other backends treat this specially and may + not pass the actual event to the user. See C API. + + The event has the following fields: + + ``result`` + The result (on success) of any ``mpv_node`` type, if any. + +``client-message`` (``MPV_EVENT_CLIENT_MESSAGE``) + Lua and possibly other backends treat this specially and may not pass the + actual event to the user. + + The event has the following fields: + + ``args`` + Array of strings with the message data. + +``video-reconfig`` (``MPV_EVENT_VIDEO_RECONFIG``) + Happens on video output or filter reconfig. + +``audio-reconfig`` (``MPV_EVENT_AUDIO_RECONFIG``) + Happens on audio output or filter reconfig. + +``property-change`` (``MPV_EVENT_PROPERTY_CHANGE``) + Happens when a property that is being observed changes value. + + The event has the following fields: + + ``name`` + The name of the property. + + ``data`` + The new value of the property. + +The following events also happen, but are deprecated: ``idle``, ``tick`` +Use ``mpv_observe_property()`` (Lua: ``mp.observe_property()``) instead. + +Hooks +~~~~~ + +Hooks are synchronous events between player core and a script or similar. This +applies to client API (including the Lua scripting interface). Normally, +events are supposed to be asynchronous, and the hook API provides an awkward +and obscure way to handle events that require stricter coordination. There are +no API stability guarantees made. Not following the protocol exactly can make +the player freeze randomly. Basically, nobody should use this API. + +The C API is described in the header files. The Lua API is described in the +Lua section. + +Before a hook is actually invoked on an API clients, it will attempt to return +new values for all observed properties that were changed before the hook. This +may make it easier for an application to set defined "barriers" between property +change notifications by registering hooks. (That means these hooks will have an +effect, even if you do nothing and make them continue immediately.) + +The following hooks are currently defined: + +``on_load`` + Called when a file is to be opened, before anything is actually done. + For example, you could read and write the ``stream-open-filename`` + property to redirect an URL to something else (consider support for + streaming sites which rarely give the user a direct media URL), or + you could set per-file options with by setting the property + ``file-local-options/<option name>``. The player will wait until all + hooks are run. + + Ordered after ``start-file`` and before ``playback-restart``. + +``on_load_fail`` + Called after after a file has been opened, but failed to. This can be + used to provide a fallback in case native demuxers failed to recognize + the file, instead of always running before the native demuxers like + ``on_load``. Demux will only be retried if ``stream-open-filename`` + was changed. If it fails again, this hook is _not_ called again, and + loading definitely fails. + + Ordered after ``on_load``, and before ``playback-restart`` and ``end-file``. + +``on_preloaded`` + Called after a file has been opened, and before tracks are selected and + decoders are created. This has some usefulness if an API users wants + to select tracks manually, based on the set of available tracks. It's + also useful to initialize ``--lavfi-complex`` in a specific way by API, + without having to "probe" the available streams at first. + + Note that this does not yet apply default track selection. Which operations + exactly can be done and not be done, and what information is available and + what is not yet available yet, is all subject to change. + + Ordered after ``on_load_fail`` etc. and before ``playback-restart``. + +``on_unload`` + Run before closing a file, and before actually uninitializing + everything. It's not possible to resume playback in this state. + + Ordered before ``end-file``. Will also happen in the error case (then after + ``on_load_fail``). + +``on_before_start_file`` + Run before a ``start-file`` event is sent. (If any client changes the + current playlist entry, or sends a quit command to the player, the + corresponding event will not actually happen after the hook returns.) + Useful to drain property changes before a new file is loaded. + +``on_after_end_file`` + Run after an ``end-file`` event. Useful to drain property changes after a + file has finished. + +Input Command Prefixes +---------------------- + +These prefixes are placed between key name and the actual command. Multiple +prefixes can be specified. They are separated by whitespace. + +``osd-auto`` + Use the default behavior for this command. This is the default for + ``input.conf`` commands. Some libmpv/scripting/IPC APIs do not use this as + default, but use ``no-osd`` instead. +``no-osd`` + Do not use any OSD for this command. +``osd-bar`` + If possible, show a bar with this command. Seek commands will show the + progress bar, property changing commands may show the newly set value. +``osd-msg`` + If possible, show an OSD message with this command. Seek command show + the current playback time, property changing commands show the newly set + value as text. +``osd-msg-bar`` + Combine osd-bar and osd-msg. +``raw`` + Do not expand properties in string arguments. (Like ``"${property-name}"``.) + This is the default for some libmpv/scripting/IPC APIs. +``expand-properties`` + All string arguments are expanded as described in `Property Expansion`_. + This is the default for ``input.conf`` commands. +``repeatable`` + For some commands, keeping a key pressed doesn't run the command repeatedly. + This prefix forces enabling key repeat in any case. For a list of commands: + the first command determines the repeatability of the whole list (up to and + including version 0.33 - a list was always repeatable). +``async`` + Allow asynchronous execution (if possible). Note that only a few commands + will support this (usually this is explicitly documented). Some commands + 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. 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. +- Lua also provides APIs for running async commands, which behave similar to the + C counterparts. +- 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. + +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, screenshot, screenshot-to-file, dump-cache, +ab-loop-dump-cache. + +Asynchronous command details +---------------------------- + +On the API level, every asynchronous command is bound to the context which +started it. For example, an asynchronous command started by ``mpv_command_async`` +is bound to the ``mpv_handle`` passed to the function. Only this ``mpv_handle`` +receives the completion notification (``MPV_EVENT_COMMAND_REPLY``), and only +this handle can abort a still running command directly. If the ``mpv_handle`` is +destroyed, any still running async. commands started by it are terminated. + +The scripting APIs and JSON IPC give each script/connection its own implicit +``mpv_handle``. + +If the player is closed, the core may abort all pending async. commands on its +own (like a forced ``mpv_abort_async_command()`` call for each pending command +on behalf of the API user). This happens at the same time ``MPV_EVENT_SHUTDOWN`` +is sent, and there is no way to prevent this. + +Input Sections +-------------- + +Input sections group a set of bindings, and enable or disable them at once. +In ``input.conf``, each key binding is assigned to an input section, rather +than actually having explicit text sections. + +See also: ``enable-section`` and ``disable-section`` commands. + +Predefined bindings: + +``default`` + Bindings without input section are implicitly assigned to this section. It + is enabled by default during normal playback. +``encode`` + Section which is active in encoding mode. It is enabled exclusively, so + that bindings in the ``default`` sections are ignored. + +Properties +---------- + +Properties are used to set mpv options during runtime, or to query arbitrary +information. They can be manipulated with the ``set``/``add``/``cycle`` +commands, and retrieved with ``show-text``, or anything else that uses property +expansion. (See `Property Expansion`_.) + +The property name is annotated with RW to indicate whether the property is +generally writable. + +If an option is referenced, the property will normally take/return exactly the +same values as the option. In these cases, properties are merely a way to change +an option at runtime. + +Property list +------------- + +.. note:: + + Most options can be set at runtime via properties as well. Just remove the + leading ``--`` from the option name. These are not documented below, see + `OPTIONS`_ instead. Only properties which do not exist as option with the + same name, or which have very different behavior from the options are + documented below. + + Properties marked as (RW) are writeable, while those that aren't are + read-only. + +``audio-speed-correction``, ``video-speed-correction`` + Factor multiplied with ``speed`` at which the player attempts to play the + file. Usually it's exactly 1. (Display sync mode will make this useful.) + + OSD formatting will display it in the form of ``+1.23456%``, with the number + being ``(raw - 1) * 100`` for the given raw property value. + +``display-sync-active`` + Whether ``--video-sync=display`` is actually active. + +``filename`` + Currently played file, with path stripped. If this is an URL, try to undo + percent encoding as well. (The result is not necessarily correct, but + looks better for display purposes. Use the ``path`` property to get an + unmodified filename.) + + This has a sub-property: + + ``filename/no-ext`` + Like the ``filename`` property, but if the text contains a ``.``, strip + all text after the last ``.``. Usually this removes the file extension. + +``file-size`` + Length in bytes of the source file/stream. (This is the same as + ``${stream-end}``. For segmented/multi-part files, this will return the + size of the main or manifest file, whatever it is.) + +``estimated-frame-count`` + Total number of frames in current file. + + .. note:: This is only an estimate. (It's computed from two unreliable + quantities: fps and stream length.) + +``estimated-frame-number`` + Number of current frame in current stream. + + .. note:: This is only an estimate. (It's computed from two unreliable + quantities: fps and possibly rounded timestamps.) + +``pid`` + Process-id of mpv. + +``path`` + Full path of the currently played file. Usually this is exactly the same + string you pass on the mpv command line or the ``loadfile`` command, even + if it's a relative path. If you expect an absolute path, you will have to + determine it yourself, for example by using the ``working-directory`` + property. + +``stream-open-filename`` + The full path to the currently played media. This is different from + ``path`` only in special cases. In particular, if ``--ytdl=yes`` is used, + and the URL is detected by ``youtube-dl``, then the script will set this + property to the actual media URL. This property should be set only during + the ``on_load`` or ``on_load_fail`` hooks, otherwise it will have no effect + (or may do something implementation defined in the future). The property is + reset if playback of the current media ends. + +``media-title`` + If the currently played file has a ``title`` tag, use that. + + Otherwise, return the ``filename`` property. + +``file-format`` + Symbolic name of the file format. In some cases, this is a comma-separated + list of format names, e.g. mp4 is ``mov,mp4,m4a,3gp,3g2,mj2`` (the list + may grow in the future for any format). + +``current-demuxer`` + Name of the current demuxer. (This is useless.) + + (Renamed from ``demuxer``.) + +``stream-path`` + Filename (full path) of the stream layer filename. (This is probably + useless and is almost never different from ``path``.) + +``stream-pos`` + Raw byte position in source stream. Technically, this returns the position + of the most recent packet passed to a decoder. + +``stream-end`` + Raw end position in bytes in source stream. + +``duration`` + Duration of the current file in seconds. If the duration is unknown, the + property is unavailable. Note that the file duration is not always exactly + known, so this is an estimate. + + This replaces the ``length`` property, which was deprecated after the + mpv 0.9 release. (The semantics are the same.) + + This has a sub-property: + + ``duration/full`` + ``duration`` with milliseconds. + +``avsync`` + Last A/V synchronization difference. Unavailable if audio or video is + disabled. + +``total-avsync-change`` + Total A-V sync correction done. Unavailable if audio or video is + disabled. + +``decoder-frame-drop-count`` + Video frames dropped by decoder, because video is too far behind audio (when + using ``--framedrop=decoder``). Sometimes, this may be incremented in other + situations, e.g. when video packets are damaged, or the decoder doesn't + follow the usual rules. Unavailable if video is disabled. + +``frame-drop-count`` + Frames dropped by VO (when using ``--framedrop=vo``). + +``mistimed-frame-count`` + Number of video frames that were not timed correctly in display-sync mode + for the sake of keeping A/V sync. This does not include external + circumstances, such as video rendering being too slow or the graphics + driver somehow skipping a vsync. It does not include rounding errors either + (which can happen especially with bad source timestamps). For example, + using the ``display-desync`` mode should never change this value from 0. + +``vsync-ratio`` + For how many vsyncs a frame is displayed on average. This is available if + display-sync is active only. For 30 FPS video on a 60 Hz screen, this will + be 2. This is the moving average of what actually has been scheduled, so + 24 FPS on 60 Hz will never remain exactly on 2.5, but jitter depending on + the last frame displayed. + +``vo-delayed-frame-count`` + Estimated number of frames delayed due to external circumstances in + display-sync mode. Note that in general, mpv has to guess that this is + happening, and the guess can be inaccurate. + +``percent-pos`` (RW) + Position in current file (0-100). The advantage over using this instead of + calculating it out of other properties is that it properly falls back to + estimating the playback position from the byte position, if the file + duration is not known. + +``time-pos`` (RW) + Position in current file in seconds. + + This has a sub-property: + + ``time-pos/full`` + ``time-pos`` with milliseconds. + +``time-start`` + Deprecated. Always returns 0. Before mpv 0.14, this used to return the start + time of the file (could affect e.g. transport streams). See + ``--rebase-start-time`` option. + +``time-remaining`` + Remaining length of the file in seconds. Note that the file duration is not + always exactly known, so this is an estimate. + + This has a sub-property: + + ``time-remaining/full`` + ``time-remaining`` with milliseconds. + +``audio-pts`` + Current audio playback position in current file in seconds. Unlike time-pos, + this updates more often than once per frame. For audio-only files, it is + mostly equivalent to time-pos, while for video-only files this property is + not available. + + This has a sub-property: + + ``audio-pts/full`` + ``audio-pts`` with milliseconds. + +``playtime-remaining`` + ``time-remaining`` scaled by the current ``speed``. + + This has a sub-property: + + ``playtime-remaining/full`` + ``playtime-remaining`` with milliseconds. + +``playback-time`` (RW) + Position in current file in seconds. Unlike ``time-pos``, the time is + clamped to the range of the file. (Inaccurate file durations etc. could + make it go out of range. Useful on attempts to seek outside of the file, + as the seek target time is considered the current position during seeking.) + + This has a sub-property: + + ``playback-time/full`` + ``playback-time`` with milliseconds. + +``chapter`` (RW) + Current chapter number. The number of the first chapter is 0. + +``edition`` (RW) + Current MKV edition number. Setting this property to a different value will + restart playback. The number of the first edition is 0. + + Before mpv 0.31.0, this showed the actual edition selected at runtime, if + you didn't set the option or property manually. With mpv 0.31.0 and later, + this strictly returns the user-set option or property value, and the + ``current-edition`` property was added to return the runtime selected + edition (this matters with ``--edition=auto``, the default). + +``current-edition`` + Currently selected edition. This property is unavailable if no file is + loaded, or the file has no editions. (Matroska files make a difference + between having no editions and a single edition, which will be reflected by + the property, although in practice it does not matter.) + +``chapters`` + Number of chapters. + +``editions`` + Number of MKV editions. + +``edition-list`` + List of editions, current entry marked. Currently, the raw property value + is useless. + + This has a number of sub-properties. Replace ``N`` with the 0-based edition + index. + + ``edition-list/count`` + Number of editions. If there are no editions, this can be 0 or 1 (1 + if there's a useless dummy edition). + + ``edition-list/N/id`` (RW) + Edition ID as integer. Use this to set the ``edition`` property. + Currently, this is the same as the edition index. + + ``edition-list/N/default`` + Whether this is the default edition. + + ``edition-list/N/title`` + Edition title as stored in the file. Not always available. + + When querying the property with the client API using ``MPV_FORMAT_NODE``, + or with Lua ``mp.get_property_native``, this will return a mpv_node with + the following contents: + + :: + + MPV_FORMAT_NODE_ARRAY + MPV_FORMAT_NODE_MAP (for each edition) + "id" MPV_FORMAT_INT64 + "title" MPV_FORMAT_STRING + "default" MPV_FORMAT_FLAG + +``metadata`` + Metadata key/value pairs. + + If the property is accessed with Lua's ``mp.get_property_native``, this + returns a table with metadata keys mapping to metadata values. If it is + accessed with the client API, this returns a ``MPV_FORMAT_NODE_MAP``, + with tag keys mapping to tag values. + + For OSD, it returns a formatted list. Trying to retrieve this property as + a raw string doesn't work. + + This has a number of sub-properties: + + ``metadata/by-key/<key>`` + Value of metadata entry ``<key>``. + + ``metadata/list/count`` + Number of metadata entries. + + ``metadata/list/N/key`` + Key name of the Nth metadata entry. (The first entry is ``0``). + + ``metadata/list/N/value`` + Value of the Nth metadata entry. + + ``metadata/<key>`` + Old version of ``metadata/by-key/<key>``. Use is discouraged, because + the metadata key string could conflict with other sub-properties. + + The layout of this property might be subject to change. Suggestions are + welcome how exactly this property should work. + + When querying the property with the client API using ``MPV_FORMAT_NODE``, + or with Lua ``mp.get_property_native``, this will return a mpv_node with + the following contents: + + :: + + MPV_FORMAT_NODE_MAP + (key and string value for each metadata entry) + +``filtered-metadata`` + Like ``metadata``, but includes only fields listed in the ``--display-tags`` + option. This is the same set of tags that is printed to the terminal. + +``chapter-metadata`` + Metadata of current chapter. Works similar to ``metadata`` property. It + also allows the same access methods (using sub-properties). + + Per-chapter metadata is very rare. Usually, only the chapter name + (``title``) is set. + + For accessing other information, like chapter start, see the + ``chapter-list`` property. + +``vf-metadata/<filter-label>`` + Metadata added by video filters. Accessed by the filter label, + which, if not explicitly specified using the ``@filter-label:`` syntax, + will be ``<filter-name>NN``. + + Works similar to ``metadata`` property. It allows the same access + methods (using sub-properties). + + An example of this kind of metadata are the cropping parameters + added by ``--vf=lavfi=cropdetect``. + +``af-metadata/<filter-label>`` + Equivalent to ``vf-metadata/<filter-label>``, but for audio filters. + +``idle-active`` + Returns ``yes``/true if no file is loaded, but the player is staying around + because of the ``--idle`` option. + + (Renamed from ``idle``.) + +``core-idle`` + Whether the playback core is paused. This can differ from ``pause`` in + special situations, such as when the player pauses itself due to low + network cache. + + This also returns ``yes``/true if playback is restarting or if nothing is + playing at all. In other words, it's only ``no``/false if there's actually + video playing. (Behavior since mpv 0.7.0.) + +``cache-speed`` + Current I/O read speed between the cache and the lower layer (like network). + This gives the number bytes per seconds over a 1 second window (using + the type ``MPV_FORMAT_INT64`` for the client API). + + This is the same as ``demuxer-cache-state/raw-input-rate``. + +``demuxer-cache-duration`` + Approximate duration of video buffered in the demuxer, in seconds. The + guess is very unreliable, and often the property will not be available + at all, even if data is buffered. + +``demuxer-cache-time`` + Approximate time of video buffered in the demuxer, in seconds. Same as + ``demuxer-cache-duration`` but returns the last timestamp of buffered + data in demuxer. + +``demuxer-cache-idle`` + Whether the demuxer is idle, which means that the demuxer cache is filled + to the requested amount, and is currently not reading more data. + +``demuxer-cache-state`` + Each entry in ``seekable-ranges`` represents a region in the demuxer cache + that can be seeked to, with a ``start`` and ``end`` fields containing the + respective timestamps. If there are multiple demuxers active, this only + returns information about the "main" demuxer, but might be changed in + future to return unified information about all demuxers. The ranges are in + arbitrary order. Often, ranges will overlap for a bit, before being joined. + In broken corner cases, ranges may overlap all over the place. + + The end of a seek range is usually smaller than the value returned by the + ``demuxer-cache-time`` property, because that property returns the guessed + buffering amount, while the seek ranges represent the buffered data that + can actually be used for cached seeking. + + ``bof-cached`` indicates whether the seek range with the lowest timestamp + points to the beginning of the stream (BOF). This implies you cannot seek + before this position at all. ``eof-cached`` indicates whether the seek range + with the highest timestamp points to the end of the stream (EOF). If both + ``bof-cached`` and ``eof-cached`` are true, and there's only 1 cache range, + the entire stream is cached. + + ``fw-bytes`` is the number of bytes of packets buffered in the range + starting from the current decoding position. This is a rough estimate + (may not account correctly for various overhead), and stops at the + demuxer position (it ignores seek ranges after it). + + ``file-cache-bytes`` is the number of bytes stored in the file cache. This + includes all overhead, and possibly unused data (like pruned data). This + member is missing if the file cache wasn't enabled with + ``--cache-on-disk=yes``. + + ``cache-end`` is ``demuxer-cache-time``. Missing if unavailable. + + ``reader-pts`` is the approximate timestamp of the start of the buffered + range. Missing if unavailable. + + ``cache-duration`` is ``demuxer-cache-duration``. Missing if unavailable. + + ``raw-input-rate`` is the estimated input rate of the network layer (or any + other byte-oriented input layer) in bytes per second. May be inaccurate or + missing. + + When querying the property with the client API using ``MPV_FORMAT_NODE``, + or with Lua ``mp.get_property_native``, this will return a mpv_node with + the following contents: + + :: + + MPV_FORMAT_NODE_MAP + "seekable-ranges" MPV_FORMAT_NODE_ARRAY + MPV_FORMAT_NODE_MAP + "start" MPV_FORMAT_DOUBLE + "end" MPV_FORMAT_DOUBLE + "bof-cached" MPV_FORMAT_FLAG + "eof-cached" MPV_FORMAT_FLAG + "fw-bytes" MPV_FORMAT_INT64 + "file-cache-bytes" MPV_FORMAT_INT64 + "cache-end" MPV_FORMAT_DOUBLE + "reader-pts" MPV_FORMAT_DOUBLE + "cache-duration" MPV_FORMAT_DOUBLE + "raw-input-rate" MPV_FORMAT_INT64 + + Other fields (might be changed or removed in the future): + + ``eof`` + Whether the reader thread has hit the end of the file. + + ``underrun`` + Whether the reader thread could not satisfy a decoder's request for a + new packet. + + ``idle`` + Whether the thread is currently not reading. + + ``total-bytes`` + Sum of packet bytes (plus some overhead estimation) of the entire packet + queue, including cached seekable ranges. + +``demuxer-via-network`` + Whether the stream demuxed via the main demuxer is most likely played via + network. What constitutes "network" is not always clear, might be used for + other types of untrusted streams, could be wrong in certain cases, and its + definition might be changing. Also, external files (like separate audio + files or streams) do not influence the value of this property (currently). + +``demuxer-start-time`` + The start time reported by the demuxer in fractional seconds. + +``paused-for-cache`` + Whether playback is paused because of waiting for the cache. + +``cache-buffering-state`` + The percentage (0-100) of the cache fill status until the player will + unpause (related to ``paused-for-cache``). + +``eof-reached`` + Whether the end of playback was reached. Note that this is usually + interesting only if ``--keep-open`` is enabled, since otherwise the player + will immediately play the next file (or exit or enter idle mode), and in + these cases the ``eof-reached`` property will logically be cleared + immediately after it's set. + +``seeking`` + Whether the player is currently seeking, or otherwise trying to restart + playback. (It's possible that it returns ``yes``/true while a file is + loaded. This is because the same underlying code is used for seeking and + resyncing.) + +``mixer-active`` + Whether the audio mixer is active. + + This option is relatively useless. Before mpv 0.18.1, it could be used to + infer behavior of the ``volume`` property. + +``ao-volume`` (RW) + System volume. This property is available only if mpv audio output is + currently active, and only if the underlying implementation supports volume + control. What this option does depends on the API. For example, on ALSA + this usually changes system-wide audio, while with PulseAudio this controls + per-application volume. + +``ao-mute`` (RW) + Similar to ``ao-volume``, but controls the mute state. May be unimplemented + even if ``ao-volume`` works. + +``audio-codec`` + Audio codec selected for decoding. + +``audio-codec-name`` + Audio codec. + +``audio-params`` + Audio format as output by the audio decoder. + This has a number of sub-properties: + + ``audio-params/format`` + The sample format as string. This uses the same names as used in other + places of mpv. + + ``audio-params/samplerate`` + Samplerate. + + ``audio-params/channels`` + The channel layout as a string. This is similar to what the + ``--audio-channels`` accepts. + + ``audio-params/hr-channels`` + As ``channels``, but instead of the possibly cryptic actual layout + sent to the audio device, return a hopefully more human readable form. + (Usually only ``audio-out-params/hr-channels`` makes sense.) + + ``audio-params/channel-count`` + Number of audio channels. This is redundant to the ``channels`` field + described above. + + When querying the property with the client API using ``MPV_FORMAT_NODE``, + or with Lua ``mp.get_property_native``, this will return a mpv_node with + the following contents: + + :: + + MPV_FORMAT_NODE_MAP + "format" MPV_FORMAT_STRING + "samplerate" MPV_FORMAT_INT64 + "channels" MPV_FORMAT_STRING + "channel-count" MPV_FORMAT_INT64 + "hr-channels" MPV_FORMAT_STRING + +``audio-out-params`` + Same as ``audio-params``, but the format of the data written to the audio + API. + +``colormatrix`` + Redirects to ``video-params/colormatrix``. This parameter (as well as + similar ones) can be overridden with the ``format`` video filter. + +``colormatrix-input-range`` + See ``colormatrix``. + +``colormatrix-primaries`` + See ``colormatrix``. + +``hwdec`` (RW) + Reflects the ``--hwdec`` option. + + Writing to it may change the currently used hardware decoder, if possible. + (Internally, the player may reinitialize the decoder, and will perform a + seek to refresh the video properly.) You can watch the other hwdec + properties to see whether this was successful. + + Unlike in mpv 0.9.x and before, this does not return the currently active + hardware decoder. Since mpv 0.18.0, ``hwdec-current`` is available for + this purpose. + +``hwdec-current`` + The current hardware decoding in use. If decoding is active, return one of + the values used by the ``hwdec`` option/property. ``no``/false indicates + software decoding. If no decoder is loaded, the property is unavailable. + +``hwdec-interop`` + This returns the currently loaded hardware decoding/output interop driver. + This is known only once the VO has opened (and possibly later). With some + VOs (like ``gpu``), this might be never known in advance, but only when + the decoder attempted to create the hw decoder successfully. (Using + ``--gpu-hwdec-interop`` can load it eagerly.) If there are multiple + drivers loaded, they will be separated by ``,``. + + If no VO is active or no interop driver is known, this property is + unavailable. + + This does not necessarily use the same values as ``hwdec``. There can be + multiple interop drivers for the same hardware decoder, depending on + platform and VO. + +``video-format`` + Video format as string. + +``video-codec`` + Video codec selected for decoding. + +``width``, ``height`` + Video size. This uses the size of the video as decoded, or if no video + frame has been decoded yet, the (possibly incorrect) container indicated + size. + +``video-params`` + Video parameters, as output by the decoder (with overrides like aspect + etc. applied). This has a number of sub-properties: + + ``video-params/pixelformat`` + The pixel format as string. This uses the same names as used in other + places of mpv. + + ``video-params/hw-pixelformat`` + The underlying pixel format as string. This is relevant for some cases + of hardware decoding and unavailable otherwise. + + ``video-params/average-bpp`` + Average bits-per-pixel as integer. Subsampled planar formats use a + different resolution, which is the reason this value can sometimes be + odd or confusing. Can be unavailable with some formats. + + ``video-params/w``, ``video-params/h`` + Video size as integers, with no aspect correction applied. + + ``video-params/dw``, ``video-params/dh`` + Video size as integers, scaled for correct aspect ratio. + + ``video-params/crop-x``, ``video-params/crop-y`` + Crop offset of the source video frame. + + ``video-params/crop-w``, ``video-params/crop-h`` + Video size after cropping. + + ``video-params/aspect`` + Display aspect ratio as float. + + ``video-params/aspect-name`` + Display aspect ratio name as string. The name coresponds to motion + picture film format that introduced given aspect ratio in film. + + ``video-params/par`` + Pixel aspect ratio. + + ``video-params/sar`` + Storage aspect ratio. + + ``video-params/sar-name`` + Storage aspect ratio name as string. + + ``video-params/colormatrix`` + The colormatrix in use as string. (Exact values subject to change.) + + ``video-params/colorlevels`` + The colorlevels as string. (Exact values subject to change.) + + ``video-params/primaries`` + The primaries in use as string. (Exact values subject to change.) + + ``video-params/gamma`` + The gamma function in use as string. (Exact values subject to change.) + + ``video-params/sig-peak`` (deprecated) + The video file's tagged signal peak as float. + + ``video-params/light`` + The light type in use as a string. (Exact values subject to change.) + + ``video-params/chroma-location`` + Chroma location as string. (Exact values subject to change.) + + ``video-params/rotate`` + Intended display rotation in degrees (clockwise). + + ``video-params/stereo-in`` + Source file stereo 3D mode. (See the ``format`` video filter's + ``stereo-in`` option.) + + ``video-params/alpha`` + Alpha type. If the format has no alpha channel, this will be unavailable + (but in future releases, it could change to ``no``). If alpha is + present, this is set to ``straight`` or ``premul``. + + ``video-params/min-luma`` + Minimum luminance, as reported by HDR10 metadata (in cd/m²) + + ``video-params/max-luma`` + Maximum luminance, as reported by HDR10 metadata (in cd/m²) + + ``video-params/max-cll`` + Maximum content light level, as reported by HDR10 metadata (in cd/m²) + + ``video-params/max-fall`` + Maximum frame average light level, as reported by HDR10 metadata (in cd/m²) + + ``video-params/scene-max-r`` + MaxRGB of a scene for R component, as reported by HDR10+ metadata (in cd/m²) + + ``video-params/scene-max-g`` + MaxRGB of a scene for G component, as reported by HDR10+ metadata (in cd/m²) + + ``video-params/scene-max-b`` + MaxRGB of a scene for B component, as reported by HDR10+ metadata (in cd/m²) + + ``video-params/max-pq-y`` + Maximum PQ luminance of a frame, as reported by peak detection (in PQ, 0-1) + + ``video-params/avg-pq-y`` + Average PQ luminance of a frame, as reported by peak detection (in PQ, 0-1) + + When querying the property with the client API using ``MPV_FORMAT_NODE``, + or with Lua ``mp.get_property_native``, this will return a mpv_node with + the following contents: + + :: + + MPV_FORMAT_NODE_MAP + "pixelformat" MPV_FORMAT_STRING + "hw-pixelformat" MPV_FORMAT_STRING + "w" MPV_FORMAT_INT64 + "h" MPV_FORMAT_INT64 + "dw" MPV_FORMAT_INT64 + "dh" MPV_FORMAT_INT64 + "aspect" MPV_FORMAT_DOUBLE + "par" MPV_FORMAT_DOUBLE + "colormatrix" MPV_FORMAT_STRING + "colorlevels" MPV_FORMAT_STRING + "primaries" MPV_FORMAT_STRING + "gamma" MPV_FORMAT_STRING + "sig-peak" MPV_FORMAT_DOUBLE + "light" MPV_FORMAT_STRING + "chroma-location" MPV_FORMAT_STRING + "rotate" MPV_FORMAT_INT64 + "stereo-in" MPV_FORMAT_STRING + "average-bpp" MPV_FORMAT_INT64 + "alpha" MPV_FORMAT_STRING + "min-luma" MPV_FORMAT_DOUBLE + "max-luma" MPV_FORMAT_DOUBLE + "max-cll" MPV_FORMAT_DOUBLE + "max-fall" MPV_FORMAT_DOUBLE + "scene-max-r" MPV_FORMAT_DOUBLE + "scene-max-g" MPV_FORMAT_DOUBLE + "scene-max-b" MPV_FORMAT_DOUBLE + "max-pq-y" MPV_FORMAT_DOUBLE + "avg-pq-y" MPV_FORMAT_DOUBLE + +``dwidth``, ``dheight`` + Video display size. This is the video size after filters and aspect scaling + have been applied. The actual video window size can still be different + from this, e.g. if the user resized the video window manually. + + These have the same values as ``video-out-params/dw`` and + ``video-out-params/dh``. + +``video-dec-params`` + Exactly like ``video-params``, but no overrides applied. + +``video-out-params`` + Same as ``video-params``, but after video filters have been applied. If + there are no video filters in use, this will contain the same values as + ``video-params``. Note that this is still not necessarily what the video + window uses, since the user can change the window size, and all real VOs + do their own scaling independently from the filter chain. + + Has the same sub-properties as ``video-params``. + +``video-frame-info`` + Approximate information of the current frame. Note that if any of these + are used on OSD, the information might be off by a few frames due to OSD + redrawing and frame display being somewhat disconnected, and you might + have to pause and force a redraw. + + This has a number of sub-properties: + + ``video-frame-info/picture-type`` + The type of the picture. It can be "I" (intra), "P" (predicted), "B" + (bi-dir predicted) or unavailable. + + ``video-frame-info/interlaced`` + Whether the content of the frame is interlaced. + + ``video-frame-info/tff`` + If the content is interlaced, whether the top field is displayed first. + + ``video-frame-info/repeat`` + Whether the frame must be delayed when decoding. + +``container-fps`` + Container FPS. This can easily contain bogus values. For videos that use + modern container formats or video codecs, this will often be incorrect. + + (Renamed from ``fps``.) + +``estimated-vf-fps`` + Estimated/measured FPS of the video filter chain output. (If no filters + are used, this corresponds to decoder output.) This uses the average of + the 10 past frame durations to calculate the FPS. It will be inaccurate + if frame-dropping is involved (such as when framedrop is explicitly + enabled, or after precise seeking). Files with imprecise timestamps (such + as Matroska) might lead to unstable results. + +``window-scale`` (RW) + Window size multiplier. Setting this will resize the video window to the + values contained in ``dwidth`` and ``dheight`` multiplied with the value + set with this property. Setting ``1`` will resize to original video size + (or to be exact, the size the video filters output). ``2`` will set the + double size, ``0.5`` halves the size. + + Note that setting a value identical to its previous value will not resize + the window. That's because this property mirrors the ``window-scale`` + option, and setting an option to its previous value is ignored. If this + value is set while the window is in a fullscreen, the multiplier is not + applied until the window is taken out of that state. Writing this property + to a maximized window can unmaximize the window depending on the OS and + window manager. If the window does not unmaximize, the multiplier will be + applied if the user unmaximizes the window later. + + See ``current-window-scale`` for the value derived from the actual window + size. + + Since mpv 0.31.0, this always returns the previously set value (or the + default value), instead of the value implied by the actual window size. + Before mpv 0.31.0, this returned what ``current-window-scale`` returns now, + after the window was created. + +``current-window-scale`` (RW) + The ``window-scale`` value calculated from the current window size. This + has the same value as ``window-scale`` if the window size was not changed + since setting the option, and the window size was not restricted in other + ways. If the window is fullscreened, this will return the scale value + calculated from the last non-fullscreen size of the window. The property + is unavailable if no video is active. + + When setting this property in the fullscreen or maximized state, the behavior + is the same as window-scale. In all other cases, setting the value of this + property will always resize the window. This does not affect the value of + ``window-scale``. + +``focused`` + Whether the window has focus. Might not be supported by all VOs. + +``display-names`` + Names of the displays that the mpv window covers. On X11, these + are the xrandr names (LVDS1, HDMI1, DP1, VGA1, etc.). On Windows, these + are the GDI names (\\.\DISPLAY1, \\.\DISPLAY2, etc.) and the first display + in the list will be the one that Windows considers associated with the + window (as determined by the MonitorFromWindow API.) On macOS these are the + Display Product Names as used in the System Information and only one display + name is returned since a window can only be on one screen. + +``display-fps`` + The refresh rate of the current display. Currently, this is the lowest FPS + of any display covered by the video, as retrieved by the underlying system + APIs (e.g. xrandr on X11). It is not the measured FPS. It's not necessarily + available on all platforms. Note that any of the listed facts may change + any time without a warning. + +``estimated-display-fps`` + The actual rate at which display refreshes seem to occur, measured by + system time. Only available if display-sync mode (as selected by + ``--video-sync``) is active. + +``vsync-jitter`` + Estimated deviation factor of the vsync duration. + +``display-width``, ``display-height`` + The current display's horizontal and vertical resolution in pixels. Whether + or not these values update as the mpv window changes displays depends on + the windowing backend. It may not be available on all platforms. + +``display-hidpi-scale`` + The HiDPI scale factor as reported by the windowing backend. If no VO is + active, or if the VO does not report a value, this property is unavailable. + It may be saner to report an absolute DPI, however, this is the way HiDPI + support is implemented on most OS APIs. See also ``--hidpi-window-scale``. + +``osd-width``, ``osd-height`` + Last known OSD width (can be 0). This is needed if you want to use the + ``overlay-add`` command. It gives you the actual OSD/window size (not + including decorations drawn by the OS window manager). + + Alias to ``osd-dimensions/w`` and ``osd-dimensions/h``. + +``osd-par`` + Last known OSD display pixel aspect (can be 0). + + Alias to ``osd-dimensions/osd-par``. + +``osd-dimensions`` + Last known OSD dimensions. + + Has the following sub-properties (which can be read as ``MPV_FORMAT_NODE`` + or Lua table with ``mp.get_property_native``): + + ``osd-dimensions/w`` + Size of the VO window in OSD render units (usually pixels, but may be + scaled pixels with VOs like ``xv``). + + ``osd-dimensions/h`` + Size of the VO window in OSD render units, + + ``osd-dimensions/par`` + Pixel aspect ratio of the OSD (usually 1). + + ``osd-dimensions/aspect`` + Display aspect ratio of the VO window. (Computing from the properties + above.) + + ``osd-dimensions/mt``, ``osd-dimensions/mb``, ``osd-dimensions/ml``, ``osd-dimensions/mr`` + OSD to video margins (top, bottom, left, right). This describes the + area into which the video is rendered. + + Any of these properties may be unavailable or set to dummy values if the + VO window is not created or visible. + +``window-id`` + Read-only - mpv's window id. May not always be available, i.e due to window + not being opened yet or not being supported by the VO. + +``mouse-pos`` + Read-only - last known mouse position, normalizd to OSD dimensions. + + Has the following sub-properties (which can be read as ``MPV_FORMAT_NODE`` + or Lua table with ``mp.get_property_native``): + + ``mouse-pos/x``, ``mouse-pos/y`` + Last known coordinates of the mouse pointer. + + ``mouse-pos/hover`` + Boolean - whether the mouse pointer hovers the video window. The + coordinates should be ignored when this value is false, because the + video backends update them only when the pointer hovers the window. + +``sub-ass-extradata`` + The current ASS subtitle track's extradata. There is no formatting done. + The extradata is returned as a string as-is. This property is not + available for non-ASS subtitle tracks. + +``sub-text`` + The current subtitle text regardless of sub visibility. Formatting is + stripped. If the subtitle is not text-based (i.e. DVD/BD subtitles), an + empty string is returned. + +``sub-text-ass`` + Like ``sub-text``, but return the text in ASS format. Text subtitles in + other formats are converted. For native ASS subtitles, events that do + not contain any text (but vector drawings etc.) are not filtered out. If + multiple events match with the current playback time, they are concatenated + with line breaks. Contains only the "Text" part of the events. + + This property is not enough to render ASS subtitles correctly, because ASS + header and per-event metadata are not returned. You likely need to do + further filtering on the returned string to make it useful. + +``secondary-sub-text`` + Same as ``sub-text``, but for the secondary subtitles. + +``sub-start`` + The current subtitle start time (in seconds). If there's multiple current + subtitles, returns the first start time. If no current subtitle is present + null is returned instead. + +``secondary-sub-start`` + Same as ``sub-start``, but for the secondary subtitles. + +``sub-end`` + The current subtitle end time (in seconds). If there's multiple current + subtitles, return the last end time. If no current subtitle is present, or + if it's present but has unknown or incorrect duration, null is returned + instead. + +``secondary-sub-end`` + Same as ``sub-end``, but for the secondary subtitles. + +``playlist-pos`` (RW) + Current position on playlist. The first entry is on position 0. Writing to + this property may start playback at the new position. + + In some cases, this is not necessarily the currently playing file. See + explanation of ``current`` and ``playing`` flags in ``playlist``. + + If there the playlist is empty, or if it's non-empty, but no entry is + "current", this property returns -1. Likewise, writing -1 will put the + player into idle mode (or exit playback if idle mode is not enabled). If an + out of range index is written to the property, this behaves as if writing -1. + (Before mpv 0.33.0, instead of returning -1, this property was unavailable + if no playlist entry was current.) + + Writing the current value back to the property will have no effect. + Use ``playlist-play-index`` to restart the playback of the current entry if + desired. + +``playlist-pos-1`` (RW) + Same as ``playlist-pos``, but 1-based. + +``playlist-current-pos`` (RW) + Index of the "current" item on playlist. This usually, but not necessarily, + the currently playing item (see ``playlist-playing-pos``). Depending on the + exact internal state of the player, it may refer to the playlist item to + play next, or the playlist item used to determine what to play next. + + For reading, this is exactly the same as ``playlist-pos``. + + For writing, this *only* sets the position of the "current" item, without + stopping playback of the current file (or starting playback, if this is done + in idle mode). Use -1 to remove the current flag. + + This property is only vaguely useful. If set during playback, it will + typically cause the playlist entry *after* it to be played next. Another + possibly odd observable state is that if ``playlist-next`` is run during + playback, this property is set to the playlist entry to play next (unlike + the previous case). There is an internal flag that decides whether the + current playlist entry or the next one should be played, and this flag is + currently inaccessible for API users. (Whether this behavior will kept is + possibly subject to change.) + +``playlist-playing-pos`` + Index of the "playing" item on playlist. A playlist item is "playing" if + it's being loaded, actually playing, or being unloaded. This property is set + during the ``MPV_EVENT_START_FILE`` (``start-file``) and the + ``MPV_EVENT_START_END`` (``end-file``) events. Outside of that, it returns + -1. If the playlist entry was somehow removed during playback, but playback + hasn't stopped yet, or is in progress of being stopped, it also returns -1. + (This can happen at least during state transitions.) + + In the "playing" state, this is usually the same as ``playlist-pos``, except + during state changes, or if ``playlist-current-pos`` was written explicitly. + +``playlist-count`` + Number of total playlist entries. + +``playlist-path`` + The original path of the playlist for the current entry before mpv expanded + the entries. Unavailable if the file was not originally associated with a + playlist in some way. + +``playlist`` + Playlist, current entry marked. Currently, the raw property value is + useless. + + This has a number of sub-properties. Replace ``N`` with the 0-based playlist + entry index. + + ``playlist/count`` + Number of playlist entries (same as ``playlist-count``). + + ``playlist/N/filename`` + Filename of the Nth entry. + + ``playlist/N/playing`` + ``yes``/true if the ``playlist-playing-pos`` property points to this + entry, ``no``/false or unavailable otherwise. + + ``playlist/N/current`` + ``yes``/true if the ``playlist-current-pos`` property points to this + entry, ``no``/false or unavailable otherwise. + + ``playlist/N/title`` + Name of the Nth entry. Available if the playlist file contains + such fields and mpv's parser supports it for the given + playlist format, or if the playlist entry has been opened before and a + media-title other then then filename has been acquired. + + ``playlist/N/id`` + Unique ID for this entry. This is an automatically assigned integer ID + that is unique for the entire life time of the current mpv core + instance. Other commands, events, etc. use this as ``playlist_entry_id`` + fields. + + ``playlist/N/playlist-path`` + The original path of the playlist for this entry before mpv expanded + it. Unavailable if the file was not originally associated with a playlist + in some way. + + When querying the property with the client API using ``MPV_FORMAT_NODE``, + or with Lua ``mp.get_property_native``, this will return a mpv_node with + the following contents: + + :: + + MPV_FORMAT_NODE_ARRAY + MPV_FORMAT_NODE_MAP (for each playlist entry) + "filename" MPV_FORMAT_STRING + "current" MPV_FORMAT_FLAG (might be missing; since mpv 0.7.0) + "playing" MPV_FORMAT_FLAG (same) + "title" MPV_FORMAT_STRING (optional) + "id" MPV_FORMAT_INT64 + +``track-list`` + List of audio/video/sub tracks, current entry marked. Currently, the raw + property value is useless. + + This has a number of sub-properties. Replace ``N`` with the 0-based track + index. + + ``track-list/count`` + Total number of tracks. + + ``track-list/N/id`` + The ID as it's used for ``-sid``/``--aid``/``--vid``. This is unique + within tracks of the same type (sub/audio/video), but otherwise not. + + ``track-list/N/type`` + String describing the media type. One of ``audio``, ``video``, ``sub``. + + ``track-list/N/src-id`` + Track ID as used in the source file. Not always available. (It is + missing if the format has no native ID, if the track is a pseudo-track + that does not exist in this way in the actual file, or if the format + is handled by libavformat, and the format was not whitelisted as having + track IDs.) + + ``track-list/N/title`` + Track title as it is stored in the file. Not always available. + + ``track-list/N/lang`` + Track language as identified by the file. Not always available. + + ``track-list/N/image`` + ``yes``/true if this is a video track that consists of a single + picture, ``no``/false or unavailable otherwise. The heuristic used to + determine if a stream is an image doesn't attempt to detect images in + codecs normally used for videos. Otherwise, it is reliable. + + ``track-list/N/albumart`` + ``yes``/true if this is an image embedded in an audio file or external + cover art, ``no``/false or unavailable otherwise. + + ``track-list/N/default`` + ``yes``/true if the track has the default flag set in the file, + ``no``/false or unavailable otherwise. + + ``track-list/N/forced`` + ``yes``/true if the track has the forced flag set in the file, + ``no``/false or unavailable otherwise. + + ``track-list/N/codec`` + The codec name used by this track, for example ``h264``. Unavailable + in some rare cases. + + ``track-list/N/external`` + ``yes``/true if the track is an external file, ``no``/false or + unavailable otherwise. This is set for separate subtitle files. + + ``track-list/N/external-filename`` + The filename if the track is from an external file, unavailable + otherwise. + + ``track-list/N/selected`` + ``yes``/true if the track is currently decoded, ``no``/false or + unavailable otherwise. + + ``track-list/N/main-selection`` + It indicates the selection order of tracks for the same type. + If a track is not selected, or is selected by the ``--lavfi-complex``, + it is not available. For subtitle tracks, ``0`` represents the ``sid``, + and ``1`` represents the ``secondary-sid``. + + ``track-list/N/ff-index`` + The stream index as usually used by the FFmpeg utilities. Note that + this can be potentially wrong if a demuxer other than libavformat + (``--demuxer=lavf``) is used. For mkv files, the index will usually + match even if the default (builtin) demuxer is used, but there is + no hard guarantee. + + ``track-list/N/decoder-desc`` + If this track is being decoded, the human-readable decoder name, + + ``track-list/N/demux-w``, ``track-list/N/demux-h`` + Video size hint as indicated by the container. (Not always accurate.) + + ``track-list/N/demux-crop-x``, ``track-list/N/demux-crop-y`` + Crop offset of the source video frame. + + ``track-list/N/demux-crop-w``, ``track-list/N/demux-crop-h`` + Video size after cropping. + + ``track-list/N/demux-channel-count`` + Number of audio channels as indicated by the container. (Not always + accurate - in particular, the track could be decoded as a different + number of channels.) + + ``track-list/N/demux-channels`` + Channel layout as indicated by the container. (Not always accurate.) + + ``track-list/N/demux-samplerate`` + Audio sample rate as indicated by the container. (Not always accurate.) + + ``track-list/N/demux-fps`` + Video FPS as indicated by the container. (Not always accurate.) + + ``track-list/N/demux-bitrate`` + Audio average bitrate, in bits per second. (Not always accurate.) + + ``track-list/N/demux-rotation`` + Video clockwise rotation metadata, in degrees. + + ``track-list/N/demux-par`` + Pixel aspect ratio. + + ``track-list/N/audio-channels`` (deprecated) + Deprecated alias for ``track-list/N/demux-channel-count``. + + ``track-list/N/replaygain-track-peak``, ``track-list/N/replaygain-track-gain`` + Per-track replaygain values. Only available for audio tracks with + corresponding information stored in the source file. + + ``track-list/N/replaygain-album-peak``, ``track-list/N/replaygain-album-gain`` + Per-album replaygain values. If the file has per-track but no per-album + information, the per-album values will be copied from the per-track + values currently. It's possible that future mpv versions will make + these properties unavailable instead in this case. + + When querying the property with the client API using ``MPV_FORMAT_NODE``, + or with Lua ``mp.get_property_native``, this will return a mpv_node with + the following contents: + + :: + + MPV_FORMAT_NODE_ARRAY + MPV_FORMAT_NODE_MAP (for each track) + "id" MPV_FORMAT_INT64 + "type" MPV_FORMAT_STRING + "src-id" MPV_FORMAT_INT64 + "title" MPV_FORMAT_STRING + "lang" MPV_FORMAT_STRING + "image" MPV_FORMAT_FLAG + "albumart" MPV_FORMAT_FLAG + "default" MPV_FORMAT_FLAG + "forced" MPV_FORMAT_FLAG + "selected" MPV_FORMAT_FLAG + "main-selection" MPV_FORMAT_INT64 + "external" MPV_FORMAT_FLAG + "external-filename" MPV_FORMAT_STRING + "codec" MPV_FORMAT_STRING + "ff-index" MPV_FORMAT_INT64 + "decoder-desc" MPV_FORMAT_STRING + "demux-w" MPV_FORMAT_INT64 + "demux-h" MPV_FORMAT_INT64 + "demux-crop-x" MPV_FORMAT_INT64 + "demux-crop-y" MPV_FORMAT_INT64 + "demux-crop-w" MPV_FORMAT_INT64 + "demux-crop-h" MPV_FORMAT_INT64 + "demux-channel-count" MPV_FORMAT_INT64 + "demux-channels" MPV_FORMAT_STRING + "demux-samplerate" MPV_FORMAT_INT64 + "demux-fps" MPV_FORMAT_DOUBLE + "demux-bitrate" MPV_FORMAT_INT64 + "demux-rotation" MPV_FORMAT_INT64 + "demux-par" MPV_FORMAT_DOUBLE + "audio-channels" MPV_FORMAT_INT64 + "replaygain-track-peak" MPV_FORMAT_DOUBLE + "replaygain-track-gain" MPV_FORMAT_DOUBLE + "replaygain-album-peak" MPV_FORMAT_DOUBLE + "replaygain-album-gain" MPV_FORMAT_DOUBLE + +``current-tracks/...`` + This gives access to currently selected tracks. It redirects to the correct + entry in ``track-list``. + + The following sub-entries are defined: ``video``, ``audio``, ``sub``, + ``sub2`` + + For example, ``current-tracks/audio/lang`` returns the current audio track's + language field (the same value as ``track-list/N/lang``). + + If tracks of the requested type are selected via ``--lavfi-complex``, the + first one is returned. + +``chapter-list`` (RW) + List of chapters, current entry marked. Currently, the raw property value + is useless. + + This has a number of sub-properties. Replace ``N`` with the 0-based chapter + index. + + ``chapter-list/count`` + Number of chapters. + + ``chapter-list/N/title`` + Chapter title as stored in the file. Not always available. + + ``chapter-list/N/time`` + Chapter start time in seconds as float. + + When querying the property with the client API using ``MPV_FORMAT_NODE``, + or with Lua ``mp.get_property_native``, this will return a mpv_node with + the following contents: + + :: + + MPV_FORMAT_NODE_ARRAY + MPV_FORMAT_NODE_MAP (for each chapter) + "title" MPV_FORMAT_STRING + "time" MPV_FORMAT_DOUBLE + +``af``, ``vf`` (RW) + See ``--vf``/``--af`` and the ``vf``/``af`` command. + + When querying the property with the client API using ``MPV_FORMAT_NODE``, + or with Lua ``mp.get_property_native``, this will return a mpv_node with + the following contents: + + :: + + MPV_FORMAT_NODE_ARRAY + MPV_FORMAT_NODE_MAP (for each filter entry) + "name" MPV_FORMAT_STRING + "label" MPV_FORMAT_STRING [optional] + "enabled" MPV_FORMAT_FLAG [optional] + "params" MPV_FORMAT_NODE_MAP [optional] + "key" MPV_FORMAT_STRING + "value" MPV_FORMAT_STRING + + It's also possible to write the property using this format. + +``seekable`` + Whether it's generally possible to seek in the current file. + +``partially-seekable`` + Whether the current file is considered seekable, but only because the cache + is active. This means small relative seeks may be fine, but larger seeks + may fail anyway. Whether a seek will succeed or not is generally not known + in advance. + + If this property returns ``yes``/true, so will ``seekable``. + +``playback-abort`` + Whether playback is stopped or is to be stopped. (Useful in obscure + situations like during ``on_load`` hook processing, when the user can stop + playback, but the script has to explicitly end processing.) + +``cursor-autohide`` (RW) + See ``--cursor-autohide``. Setting this to a new value will always update + the cursor, and reset the internal timer. + +``osd-sym-cc`` + Inserts the current OSD symbol as opaque OSD control code (cc). This makes + sense only with the ``show-text`` command or options which set OSD messages. + The control code is implementation specific and is useless for anything else. + +``osd-ass-cc`` + ``${osd-ass-cc/0}`` disables escaping ASS sequences of text in OSD, + ``${osd-ass-cc/1}`` enables it again. By default, ASS sequences are + escaped to avoid accidental formatting, and this property can disable + this behavior. Note that the properties return an opaque OSD control + code, which only makes sense for the ``show-text`` command or options + which set OSD messages. + + .. admonition:: Example + + - ``--osd-msg3='This is ${osd-ass-cc/0}{\\b1}bold text'`` + - ``show-text "This is ${osd-ass-cc/0}{\\b1}bold text"`` + + Any ASS override tags as understood by libass can be used. + + Note that you need to escape the ``\`` character, because the string is + processed for C escape sequences before passing it to the OSD code. See + `Flat command syntax`_ for details. + + A list of tags can be found here: + https://aegisub.org/docs/latest/ass_tags/ + +``vo-configured`` + Whether the VO is configured right now. Usually this corresponds to whether + the video window is visible. If the ``--force-window`` option is used, this + usually always returns ``yes``/true. + +``vo-passes`` + Contains introspection about the VO's active render passes and their + execution times. Not implemented by all VOs. + + This is further subdivided into two frame types, ``vo-passes/fresh`` for + fresh frames (which have to be uploaded, scaled, etc.) and + ``vo-passes/redraw`` for redrawn frames (which only have to be re-painted). + The number of passes for any given subtype can change from frame to frame, + and should not be relied upon. + + Each frame type has a number of further sub-properties. Replace ``TYPE`` + with the frame type, ``N`` with the 0-based pass index, and ``M`` with the + 0-based sample index. + + ``vo-passes/TYPE/count`` + Number of passes. + + ``vo-passes/TYPE/N/desc`` + Human-friendy description of the pass. + + ``vo-passes/TYPE/N/last`` + Last measured execution time, in nanoseconds. + + ``vo-passes/TYPE/N/avg`` + Average execution time of this pass, in nanoseconds. The exact + timeframe varies, but it should generally be a handful of seconds. + + ``vo-passes/TYPE/N/peak`` + The peak execution time (highest value) within this averaging range, in + nanoseconds. + + ``vo-passes/TYPE/N/count`` + The number of samples for this pass. + + ``vo-passes/TYPE/N/samples/M`` + The raw execution time of a specific sample for this pass, in + nanoseconds. + + When querying the property with the client API using ``MPV_FORMAT_NODE``, + or with Lua ``mp.get_property_native``, this will return a mpv_node with + the following contents: + + :: + + MPV_FORMAT_NODE_MAP + "TYPE" MPV_FORMAT_NODE_ARRAY + MPV_FORMAT_NODE_MAP + "desc" MPV_FORMAT_STRING + "last" MPV_FORMAT_INT64 + "avg" MPV_FORMAT_INT64 + "peak" MPV_FORMAT_INT64 + "count" MPV_FORMAT_INT64 + "samples" MPV_FORMAT_NODE_ARRAY + MP_FORMAT_INT64 + + Note that directly accessing this structure via subkeys is not supported, + the only access is through aforementioned ``MPV_FORMAT_NODE``. + +``perf-info`` + Further performance data. Querying this property triggers internal + collection of some data, and may slow down the player. Each query will reset + some internal state. Property change notification doesn't and won't work. + All of this may change in the future, so don't use this. The builtin + ``stats`` script is supposed to be the only user; since it's bundled and + built with the source code, it can use knowledge of mpv internal to render + the information properly. See ``stats`` script description for some details. + +``video-bitrate``, ``audio-bitrate``, ``sub-bitrate`` + Bitrate values calculated on the packet level. This works by dividing the + bit size of all packets between two keyframes by their presentation + timestamp distance. (This uses the timestamps are stored in the file, so + e.g. playback speed does not influence the returned values.) In particular, + the video bitrate will update only per keyframe, and show the "past" + bitrate. To make the property more UI friendly, updates to these properties + are throttled in a certain way. + + The unit is bits per second. OSD formatting turns these values in kilobits + (or megabits, if appropriate), which can be prevented by using the + raw property value, e.g. with ``${=video-bitrate}``. + + Note that the accuracy of these properties is influenced by a few factors. + If the underlying demuxer rewrites the packets on demuxing (done for some + file formats), the bitrate might be slightly off. If timestamps are bad + or jittery (like in Matroska), even constant bitrate streams might show + fluctuating bitrate. + + How exactly these values are calculated might change in the future. + + In earlier versions of mpv, these properties returned a static (but bad) + guess using a completely different method. + +``packet-video-bitrate``, ``packet-audio-bitrate``, ``packet-sub-bitrate`` + Old and deprecated properties for ``video-bitrate``, ``audio-bitrate``, + ``sub-bitrate``. They behave exactly the same, but return a value in + kilobits. Also, they don't have any OSD formatting, though the same can be + achieved with e.g. ``${=video-bitrate}``. + + These properties shouldn't be used anymore. + +``audio-device-list`` + The list of discovered audio devices. This is mostly for use with the + client API, and reflects what ``--audio-device=help`` with the command line + player returns. + + When querying the property with the client API using ``MPV_FORMAT_NODE``, + or with Lua ``mp.get_property_native``, this will return a mpv_node with + the following contents: + + :: + + MPV_FORMAT_NODE_ARRAY + MPV_FORMAT_NODE_MAP (for each device entry) + "name" MPV_FORMAT_STRING + "description" MPV_FORMAT_STRING + + The ``name`` is what is to be passed to the ``--audio-device`` option (and + often a rather cryptic audio API-specific ID), while ``description`` is + human readable free form text. The description is set to the device name + (minus mpv-specific ``<driver>/`` prefix) if no description is available + or the description would have been an empty string. + + The special entry with the name set to ``auto`` selects the default audio + output driver and the default device. + + The property can be watched with the property observation mechanism in + the client API and in Lua scripts. (Technically, change notification is + enabled the first time this property is read.) + +``audio-device`` (RW) + Set the audio device. This directly reads/writes the ``--audio-device`` + option, but on write accesses, the audio output will be scheduled for + reloading. + + Writing this property while no audio output is active will not automatically + enable audio. (This is also true in the case when audio was disabled due to + reinitialization failure after a previous write access to ``audio-device``.) + + This property also doesn't tell you which audio device is actually in use. + + How these details are handled may change in the future. + +``current-vo`` + Current video output driver (name as used with ``--vo``). + +``current-ao`` + Current audio output driver (name as used with ``--ao``). + +``shared-script-properties`` (RW) + This is a key/value map of arbitrary strings shared between scripts for + general use. The player itself does not use any data in it (although some + builtin scripts may). The property is not preserved across player restarts. + + This is very primitive, inefficient, and annoying to use. It's a makeshift + solution which could go away any time (for example, when a better solution + becomes available). This is also why this property has an annoying name. You + should avoid using it, unless you absolutely have to. + + Lua scripting has helpers starting with ``utils.shared_script_property_``. + They are undocumented because you should not use this property. If you still + think you must, you should use the helpers instead of the property directly. + + You are supposed to use the ``change-list`` command to modify the contents. + Reading, modifying, and writing the property manually could data loss if two + scripts update different keys at the same time due to lack of + synchronization. The Lua helpers take care of this. + + (There is no way to ensure synchronization if two scripts try to update the + same key at the same time.) + +``user-data`` (RW) + This is a recursive key/value map of arbitrary nodes shared between clients for + general use (i.e. scripts, IPC clients, host applications, etc). + The player itself does not use any data in it (although some builtin scripts may). + The property is not preserved across player restarts. + + This is a more powerful replacement for ``shared-script-properties``. + + Sub-paths can be accessed directly; e.g. ``user-data/my-script/state/a`` can be + read, written, or observed. + + The top-level object itself cannot be written directly; write to sub-paths instead. + + Converting this property or its sub-properties to strings will give a JSON + representation. If converting a leaf-level object (i.e. not a map or array) + and not using raw mode, the underlying content will be given (e.g. strings will be + printed directly, rather than quoted and JSON-escaped). + +``working-directory`` + The working directory of the mpv process. Can be useful for JSON IPC users, + because the command line player usually works with relative paths. + +``protocol-list`` + List of protocol prefixes potentially recognized by the player. They are + returned without trailing ``://`` suffix (which is still always required). + In some cases, the protocol will not actually be supported (consider + ``https`` if ffmpeg is not compiled with TLS support). + +``decoder-list`` + List of decoders supported. This lists decoders which can be passed to + ``--vd`` and ``--ad``. + + ``codec`` + Canonical codec name, which identifies the format the decoder can + handle. + + ``driver`` + The name of the decoder itself. Often, this is the same as ``codec``. + Sometimes it can be different. It is used to distinguish multiple + decoders for the same codec. + + ``description`` + Human readable description of the decoder and codec. + + When querying the property with the client API using ``MPV_FORMAT_NODE``, + or with Lua ``mp.get_property_native``, this will return a mpv_node with + the following contents: + + :: + + MPV_FORMAT_NODE_ARRAY + MPV_FORMAT_NODE_MAP (for each decoder entry) + "codec" MPV_FORMAT_STRING + "driver" MPV_FORMAT_STRING + "description" MPV_FORMAT_STRING + +``encoder-list`` + List of libavcodec encoders. This has the same format as ``decoder-list``. + The encoder names (``driver`` entries) can be passed to ``--ovc`` and + ``--oac`` (without the ``lavc:`` prefix required by ``--vd`` and ``--ad``). + +``demuxer-lavf-list`` + List of available libavformat demuxers' names. This can be used to check + for support for a specific format or use with ``--demuxer-lavf-format``. + +``input-key-list`` + List of `Key names`_, same as output by ``--input-keylist``. + +``mpv-version`` + The mpv version/copyright string. Depending on how the binary was built, it + might contain either a release version, or just a git hash. + +``mpv-configuration`` + The configuration arguments that were passed to the build system. If the + meson version used to compile mpv is older than 1.1.0, then a hardcoded + string of a few, arbitrary options is displayed instead. + +``ffmpeg-version`` + The contents of the ``av_version_info()`` API call. This is a string which + identifies the build in some way, either through a release version number, + or a git hash. This applies to Libav as well (the property is still named + the same.) This property is unavailable if mpv is linked against older + FFmpeg and Libav versions. + +``libass-version`` + The value of ``ass_library_version()``. This is an integer, encoded in a + somewhat weird form (apparently "hex BCD"), indicating the release version + of the libass library linked to mpv. + +``platform`` + Returns a string describing what target platform mpv was built for. The value + of this is dependent on what the underlying build system detects. Some of the + most common values are: ``windows``, ``darwin`` (macos or ios), ``linux``, + ``android``, and ``freebsd``. Note that this is not a complete listing. + +``options/<name>`` (RW) + The value of option ``--<name>``. Most options can be changed at runtime by + writing to this property. Note that many options require reloading the file + for changes to take effect. If there is an equivalent property, prefer + setting the property instead. + + There shouldn't be any reason to access ``options/<name>`` instead of + ``<name>``, except in situations in which the properties have different + behavior or conflicting semantics. + +``file-local-options/<name>`` (RW) + Similar to ``options/<name>``, but when setting an option through this + property, the option is reset to its old value once the current file has + stopped playing. Trying to write an option while no file is playing (or + is being loaded) results in an error. + + (Note that if an option is marked as file-local, even ``options/`` will + access the local value, and the ``old`` value, which will be restored on + end of playback, cannot be read or written until end of playback.) + +``option-info/<name>`` + Additional per-option information. + + This has a number of sub-properties. Replace ``<name>`` with the name of + a top-level option. No guarantee of stability is given to any of these + sub-properties - they may change radically in the feature. + + ``option-info/<name>/name`` + The name of the option. + + ``option-info/<name>/type`` + The name of the option type, like ``String`` or ``Integer``. For many + complex types, this isn't very accurate. + + ``option-info/<name>/set-from-commandline`` + Whether the option was set from the mpv command line. What this is set + to if the option is e.g. changed at runtime is left undefined (meaning + it could change in the future). + + ``option-info/<name>/set-locally`` + Whether the option was set per-file. This is the case with + automatically loaded profiles, file-dir configs, and other cases. It + means the option value will be restored to the value before playback + start when playback ends. + + ``option-info/<name>/default-value`` + The default value of the option. May not always be available. + + ``option-info/<name>/min``, ``option-info/<name>/max`` + Integer minimum and maximum values allowed for the option. Only + available if the options are numeric, and the minimum/maximum has been + set internally. It's also possible that only one of these is set. + + ``option-info/<name>/choices`` + If the option is a choice option, the possible choices. Choices that + are integers may or may not be included (they can be implied by ``min`` + and ``max``). Note that options which behave like choice options, but + are not actual choice options internally, may not have this info + available. + +``property-list`` + The list of top-level properties. + +``profile-list`` + The list of profiles and their contents. This is highly + implementation-specific, and may change any time. Currently, it returns an + array of options for each profile. Each option has a name and a value, with + the value currently always being a string. Note that the options array is + not a map, as order matters and duplicate entries are possible. Recursive + profiles are not expanded, and show up as special ``profile`` options. + + The ``profile-restore`` field is currently missing if it holds the default + value (either because it was not set, or set explicitly to ``default``), + but in the future it might hold the value ``default``. + +``command-list`` + The list of input commands. This returns an array of maps, where each map + node represents a command. This map currently only has a single entry: + ``name`` for the name of the command. (This property is supposed to be a + replacement for ``--input-cmdlist``. The option dumps some more + information, but it's a valid feature request to extend this property if + needed.) + +``input-bindings`` + The list of current input key bindings. This returns an array of maps, + where each map node represents a binding for a single key/command. This map + has the following entries: + + ``key`` + The key name. This is normalized and may look slightly different from + how it was specified in the source (e.g. in input.conf). + + ``cmd`` + The command mapped to the key. (Currently, this is exactly the same + string as specified in the source, other than stripping whitespace and + comments. It's possible that it will be normalized in the future.) + + ``is_weak`` + If set to true, any existing and active user bindings will take priority. + + ``owner`` + If this entry exists, the name of the script (or similar) which added + this binding. + + ``section`` + Name of the section this binding is part of. This is a rarely used + mechanism. This entry may be removed or change meaning in the future. + + ``priority`` + A number. Bindings with a higher value are preferred over bindings + with a lower value. If the value is negative, this binding is inactive + and will not be triggered by input. Note that mpv does not use this + value internally, and matching of bindings may work slightly differently + in some cases. In addition, this value is dynamic and can change around + at runtime. + + ``comment`` + If available, the comment following the command on the same line. (For + example, the input.conf entry ``f cycle bla # toggle bla`` would + result in an entry with ``comment = "toggle bla", cmd = "cycle bla"``.) + + This property is read-only, and change notification is not supported. + Currently, there is no mechanism to change key bindings at runtime, other + than scripts adding or removing their own bindings. + +Inconsistencies between options and properties +---------------------------------------------- + +You can access (almost) all options as properties, though there are some +caveats with some properties (due to historical reasons): + +``vid``, ``aid``, ``sid`` + While playback is active, these return the actually active tracks. For + example, if you set ``aid=5``, and the currently played file contains no + audio track with ID 5, the ``aid`` property will return ``no``. + + Before mpv 0.31.0, you could set existing tracks at runtime only. + +``display-fps`` + This inconsistent behavior is deprecated. Post-deprecation, the reported + value and the option value are cleanly separated (``override-display-fps`` + for the option value). + +``vf``, ``af`` + If you set the properties during playback, and the filter chain fails to + reinitialize, the option will be set, but the runtime filter chain does not + change. On the other hand, the next video to be played will fail, because + the initial filter chain cannot be created. + + This behavior changed in mpv 0.31.0. Before this, the new value was rejected + *iff* a video (for ``vf``) or an audio (for ``af``) track was active. If + playback was not active, the behavior was the same as the current one. + +``playlist`` + The property is read-only and returns the current internal playlist. The + option is for loading playlist during command line parsing. For client API + uses, you should use the ``loadlist`` command instead. + +``profile``, ``include`` + These are write-only, and will perform actions as they are written to, + exactly as if they were used on the mpv CLI commandline. Their only use is + when using libmpv before ``mpv_initialize()``, which in turn is probably + only useful in encoding mode. Normal libmpv users should use other + mechanisms, such as the ``apply-profile`` command, and the + ``mpv_load_config_file`` API function. Avoid these properties. + +Property Expansion +------------------ + +All string arguments to input commands as well as certain options (like +``--term-playing-msg``) are subject to property expansion. Note that property +expansion does not work in places where e.g. numeric parameters are expected. +(For example, the ``add`` command does not do property expansion. The ``set`` +command is an exception and not a general rule.) + +.. admonition:: Example for input.conf + + ``i show-text "Filename: ${filename}"`` + shows the filename of the current file when pressing the ``i`` key + +Whether property expansion is enabled by default depends on which API is used +(see `Flat command syntax`_, `Commands specified as arrays`_ and `Named +arguments`_), but it can always be enabled with the ``expand-properties`` +prefix or disabled with the ``raw`` prefix, as described in `Input Command +Prefixes`_. + +The following expansions are supported: + +``${NAME}`` + Expands to the value of the property ``NAME``. If retrieving the property + fails, expand to an error string. (Use ``${NAME:}`` with a trailing + ``:`` to expand to an empty string instead.) + If ``NAME`` is prefixed with ``=``, expand to the raw value of the property + (see section below). +``${NAME:STR}`` + Expands to the value of the property ``NAME``, or ``STR`` if the + property cannot be retrieved. ``STR`` is expanded recursively. +``${?NAME:STR}`` + Expands to ``STR`` (recursively) if the property ``NAME`` is available. +``${!NAME:STR}`` + Expands to ``STR`` (recursively) if the property ``NAME`` cannot be + retrieved. +``${?NAME==VALUE:STR}`` + Expands to ``STR`` (recursively) if the property ``NAME`` expands to a + string equal to ``VALUE``. You can prefix ``NAME`` with ``=`` in order to + compare the raw value of a property (see section below). If the property + is unavailable, or other errors happen when retrieving it, the value is + never considered equal. + Note that ``VALUE`` can't contain any of the characters ``:`` or ``}``. + Also, it is possible that escaping with ``"`` or ``%`` might be added in + the future, should the need arise. +``${!NAME==VALUE:STR}`` + Same as with the ``?`` variant, but ``STR`` is expanded if the value is + not equal. (Using the same semantics as with ``?``.) +``$$`` + Expands to ``$``. +``$}`` + Expands to ``}``. (To produce this character inside recursive + expansion.) +``$>`` + Disable property expansion and special handling of ``$`` for the rest + of the string. + +In places where property expansion is allowed, C-style escapes are often +accepted as well. Example: + + - ``\n`` becomes a newline character + - ``\\`` expands to ``\`` + +Raw and Formatted Properties +---------------------------- + +Normally, properties are formatted as human-readable text, meant to be +displayed on OSD or on the terminal. It is possible to retrieve an unformatted +(raw) value from a property by prefixing its name with ``=``. These raw values +can be parsed by other programs and follow the same conventions as the options +associated with the properties. + +.. admonition:: Examples + + - ``${time-pos}`` expands to ``00:14:23`` (if playback position is at 14 + minutes 23 seconds) + - ``${=time-pos}`` expands to ``863.4`` (same time, plus 400 milliseconds - + milliseconds are normally not shown in the formatted case) + +Sometimes, the difference in amount of information carried by raw and formatted +property values can be rather big. In some cases, raw values have more +information, like higher precision than seconds with ``time-pos``. Sometimes +it is the other way around, e.g. ``aid`` shows track title and language in the +formatted case, but only the track number if it is raw. |