diff options
Diffstat (limited to 'DOCS/man/input.rst')
| -rw-r--r-- | DOCS/man/input.rst | 554 |
1 files changed, 353 insertions, 201 deletions
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index bce4da018e..2dc9bebf57 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -62,8 +62,8 @@ character), or a symbolic name (as printed by ``--input-keylist``). command. ``<command>`` is the command itself. It consists of the command name and -multiple (or none) commands, all separated by whitespace. String arguments -need to be quoted with ``"``. Details see ``Flat command syntax``. +multiple (or none) arguments, all separated by whitespace. String arguments +should be quoted, typically with ``"``. See ``Flat command syntax``. You can bind multiple commands to one key. For example: @@ -97,6 +97,12 @@ 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. @@ -160,19 +166,38 @@ Flat command syntax This is the syntax used in input.conf, and referred to "input.conf syntax" in a number of other places. -``<command> ::= [<prefixes>] <command_name> (<argument>)*`` -``<argument> ::= (<string> | " <quoted_string> " )`` +| +| ``<command> ::= [<prefixes>] <command_name> (<argument>)*`` +| ``<argument> ::= (<unquoted> | " <double_quoted> " | ' <single_quoted> ' | `X <custom_quoted> X`)`` ``command_name`` is an unquoted string with the command name itself. See `List of Input Commands`_ for a list. -Arguments are separated by whitespace. This applies even to string arguments. -For this reason, string arguments should be quoted with ``"``. If a string -argument contains spaces or certain special characters, quoting and possibly -escaping is mandatory, or the command cannot be parsed correctly. +Arguments are separated by whitespaces even if the command expects only one +argument. Arguments with whitespaces or other special characters must be quoted, +or the command cannot be parsed correctly. + +Double quotes interpret JSON/C-style escaping, like ``\t`` or ``\"`` or ``\\``. +JSON escapes according to RFC 8259, minus surrogate pair escapes. This is the +only form which allows newlines at the value - as ``\n``. + +Single quotes take the content literally, and cannot include the single-quote +character at the value. -Inside quotes, C-style escaping can be used. JSON escapes according to RFC 8259, -minus surrogate pair escapes, should be a safe subset that can be used. +Custom quotes also take the content literally, but are more flexible than single +quotes. They start with ````` (back-quote) followed by any ASCII character, +and end at the first occurance of the same pair in reverse order, e.g. +```-foo-``` or ````bar````. The final pair sequence is not allowed at the +value - in these examples ``-``` and `````` respectively. In the second +example the last character of the value also can't be a back-quote. + +Mixed quoting at the same argument, like ``'foo'"bar"``, is not supported. + +Note that argument parsing and property expansion happen at different stages. +First, arguments are determined as described above, and then, where applicable, +properties are expanded - regardless of argument quoting. However, expansion +can still be prevented with the ``raw`` prefix or ``$>``. See `Input Command +Prefixes`_ and `Property Expansion`_. Commands specified as arrays ---------------------------- @@ -195,6 +220,9 @@ quotes and escaping. The array command APIs mentioned above pass strings directly to the argument parsers, or can sidestep them by the ability to pass non-string values. +Property expansion is disabled by default for these APIs. This can be changed +with the ``expand-properties`` prefix. See `Input Command Prefixes`_. + Sometimes commands have string arguments, that in turn are actually parsed by other components (e.g. filter strings with ``vf add``) - in these cases, you you would have to double-escape in input.conf, but not with the array APIs. @@ -221,6 +249,9 @@ to use APIs that pass arguments as arrays. Named arguments are not supported in the "flat" input.conf syntax, which means you cannot use them for key bindings in input.conf at all. +Property expansion is disabled by default for these APIs. This can be changed +with the ``expand-properties`` prefix. See `Input Command Prefixes`_. + List of Input Commands ---------------------- @@ -313,6 +344,10 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). the minimum, on underflow set it to the maximum. If ``up`` or ``down`` is omitted, assume ``up``. + Whether or not key-repeat is enabled by default depends on the property. + Currently properties with continuous values are repeatable by default (like + ``volume``), while discrete values are not (like ``osd-level``). + ``multiply <name> <value>`` Similar to ``add``, but multiplies the property or option with the numeric value. @@ -439,6 +474,10 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). Stop playback and replace the internal playlist with the new one. <append> Append the new playlist at the end of the current internal playlist. + <append-play> + Append the new playlist, and if nothing is currently playing, start + playback. (Always starts with the new playlist, even if the internal + playlist was not empty before running this command.) ``playlist-clear`` Clear the playlist, except the currently played file. @@ -506,13 +545,13 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). argument list. The first array entry is either an absolute path to the executable, or - a filename with no path components, in which case the ``PATH`` - environment variable. On Unix, this is equivalent to ``posix_spawnp`` - and ``execvp`` behavior. + a filename with no path components, in which case the executable is + searched in the directories in the ``PATH`` environment variable. On + Unix, this is equivalent to ``posix_spawnp`` and ``execvp`` behavior. ``playback_only`` (``MPV_FORMAT_FLAG``) Boolean indicating whether the process should be killed when playback - terminates (optional, default: yes). If enabled, stopping playback + terminates (optional, default: true). If enabled, stopping playback will automatically kill the process, and you can't start it outside of playback. @@ -532,7 +571,7 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). 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 ``yes``, + ``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. @@ -555,8 +594,8 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). ``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 default was if - it was set to ``yes``. + 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``): @@ -582,13 +621,12 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). process could not be started. On Windows, ``killed`` is only returned when the process has been - killed by mpv as a result of ``playback_only`` being set to ``yes``. + killed by mpv as a result of ``playback_only`` being set to true. ``killed_by_us`` (``MPV_FORMAT_FLAG``) - Set to ``yes`` if the process has been killed by mpv, for example as a - result of ``playback_only`` being set to ``yes``, aborting the command - (e.g. by ``mp.abort_async_command()``), or if the player is about to - exit. + 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 @@ -669,16 +707,30 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). This works by unloading and re-adding the subtitle track. -``sub-step <skip>`` +``sub-step <skip> <flags>`` Change subtitle timing such, that the subtitle event after the next ``<skip>`` subtitle events is displayed. ``<skip>`` can be negative to step backwards. -``sub-seek <skip>`` + Secondary argument: + + primary (default) + Steps through the primary subtitles. + secondary + Steps through the secondary subtitles. + +``sub-seek <skip> <flags>`` Seek to the next (skip set to 1) or the previous (skip set to -1) subtitle. This is similar to ``sub-step``, except that it seeks video and audio instead of adjusting the subtitle delay. + Secondary argument: + + primary (default) + Seeks through the primary subtitles. + secondary + Seeks through the secondary subtitles. + For embedded subtitles (like with Matroska), this works only with subtitle events that have already been displayed, or are within a short prefetch range. @@ -724,6 +776,13 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). Write the resume config file that the ``quit-watch-later`` command writes, but continue playback normally. +``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 @@ -784,8 +843,11 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). ``audio-reload [<id>]`` Reload the given audio tracks. See ``sub-reload`` command. -``video-add <url> [<flags> [<title> [<lang>]]]`` - Load the given video file. See ``sub-add`` 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. @@ -794,9 +856,9 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). Reload the given video tracks. See ``sub-reload`` command. ``rescan-external-files [<mode>]`` - Rescan external files according to the current ``--sub-auto`` and - ``--audio-file-auto`` settings. This can be used to auto-load external - files *after* the file was loaded. + Rescan external files according to the current ``--sub-auto``, + ``--audio-file-auto`` and ``--cover-art-auto`` settings. This can be used + to auto-load external files *after* the file was loaded. The ``mode`` argument is one of the following: @@ -831,8 +893,8 @@ Input Commands that are Possibly Subject to Change Append the new filter chain to the previous one. <toggle> - Check if the given filter (with the exact parameters) is already - in the video chain. If yes, remove the filter. If no, add the filter. + Check if the given filter (with the exact parameters) is already in the + video chain. If it is, remove the filter. If it isn't, add the filter. (If several filters are passed to the command, this is done for each filter.) @@ -874,7 +936,7 @@ Input Commands that are Possibly Subject to Change .. admonition:: Example for input.conf - - ``a vf set flip`` turn video upside-down on the ``a`` key + - ``a vf set vflip`` turn the video upside-down on the ``a`` key - ``b vf set ""`` remove all video filters on ``b`` - ``c vf toggle gradfun`` toggle debanding on ``c`` @@ -1112,14 +1174,14 @@ Input Commands that are Possibly Subject to Change between different OSD formats and builtin OSD is handled. ``hidden`` - If set to ``yes``/true, do not display this (default: no). + If set to true, do not display this (default: false). ``compute_bounds`` - If set to ``yes``/true, attempt to determine bounds and write them to - the command's result value as ``x0``, ``x1``, ``y0``, ``y1`` rectangle - (default: no). 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. + 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 @@ -1154,7 +1216,8 @@ Input Commands that are Possibly Subject to Change ``script-message-to <target> [<arg1> [<arg2> [...]]]`` Same as ``script-message``, but send it only to the client named ``<target>``. Each client (scripts etc.) has a unique name. For example, - Lua scripts can get their name via ``mp.get_script_name()``. + Lua scripts can get their name via ``mp.get_script_name()``. Note that + client names only consist of alphanumeric characters and ``_``. This command has a variable number of arguments, and cannot be used with named arguments. @@ -1166,7 +1229,8 @@ Input Commands that are Possibly Subject to Change The argument is the name of the binding. It can optionally be prefixed with the name of the script, using ``/`` as - separator, e.g. ``script-binding scriptname/bindingname``. + separator, e.g. ``script-binding scriptname/bindingname``. Note that script + names only consist of alphanumeric characters and ``_``. For completeness, here is how this command works internally. The details could change any time. On any matching key event, ``script-message-to`` @@ -1525,10 +1589,19 @@ This list uses the event name field value, and the C API symbol in brackets: ``audio-reconfig`` (``MPV_EVENT_AUDIO_RECONFIG``) Happens on audio output or filter reconfig. -The following events also happen, but are deprecated: ``tracks-changed``, -``track-switched``, ``pause``, ``unpause``, ``metadata-update``, ``idle``, -``tick``, ``chapter-change``. Use ``mpv_observe_property()`` -(Lua: ``mp.observe_property()``) instead. +``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 ~~~~~ @@ -1631,7 +1704,9 @@ prefixes can be specified. They are separated by whitespace. 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. + 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 @@ -1746,6 +1821,9 @@ Property list 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.) @@ -1754,7 +1832,7 @@ Property list being ``(raw - 1) * 100`` for the given raw property value. ``display-sync-active`` - Return whether ``--video-sync=display`` is actually active. + Whether ``--video-sync=display`` is actually active. ``filename`` Currently played file, with path stripped. If this is an URL, try to undo @@ -1785,6 +1863,9 @@ Property list .. 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 @@ -1894,7 +1975,7 @@ Property list Remaining length of the file in seconds. Note that the file duration is not always exactly known, so this is an estimate. -``audio-pts`` (R) +``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 @@ -1945,12 +2026,12 @@ Property list 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`` + ``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`` - ``yes`` if this is the default edition, ``no`` otherwise. + Whether this is the default edition. ``edition-list/N/title`` Edition title as stored in the file. Not always available. @@ -2037,21 +2118,21 @@ Property list Equivalent to ``vf-metadata/<filter-label>``, but for audio filters. ``idle-active`` - Return ``yes`` if no file is loaded, but the player is staying around + Returns ``yes``/true if no file is loaded, but the player is staying around because of the ``--idle`` option. (Renamed from ``idle``.) ``core-idle`` - Return ``yes`` if the playback core is paused, otherwise ``no``. This can - be different ``pause`` in special situations, such as when the player - pauses itself due to low network cache. + 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`` if playback is restarting or if nothing is - playing at all. In other words, it's only ``no`` if there's actually + 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`` (R) +``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). @@ -2069,14 +2150,13 @@ Property list data in demuxer. ``demuxer-cache-idle`` - Returns ``yes`` if the demuxer is idle, which means the demuxer cache is - filled to the requested amount, and is currently not reading more data. + 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`` - Various undocumented or half-documented things. - Each entry in ``seekable-ranges`` represents a region in the demuxer cache - that can be seeked to. If there are multiple demuxers active, this only + 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. @@ -2091,8 +2171,8 @@ Property list 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 set to ``yes``, and there's only 1 - cache range, the entire stream is cached. + ``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 @@ -2101,7 +2181,13 @@ Property list ``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 is not active. + 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. @@ -2124,58 +2210,59 @@ Property list "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`` - True if the reader thread has hit the end of the file. + Whether the reader thread has hit the end of the file. ``underrun`` - True if the reader thread could not satisfy a decoder's request for a + Whether the reader thread could not satisfy a decoder's request for a new packet. ``idle`` - True if the thread is currently not reading. + 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`` - Returns ``yes`` if 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). + 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`` (R) - Returns the start time reported by the demuxer in fractional seconds. +``demuxer-start-time`` + The start time reported by the demuxer in fractional seconds. ``paused-for-cache`` - Returns ``yes`` when playback is paused because of waiting for the cache. + Whether playback is paused because of waiting for the cache. ``cache-buffering-state`` - Return the percentage (0-100) of the cache fill status until the player - will unpause (related to ``paused-for-cache``). + The percentage (0-100) of the cache fill status until the player will + unpause (related to ``paused-for-cache``). ``eof-reached`` - Returns ``yes`` if end of playback was reached, ``no`` otherwise. 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. + 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`` - Returns ``yes`` if the player is currently seeking, or otherwise trying - to restart playback. (It's possible that it returns ``yes`` while a file - is loaded. This is because the same underlying code is used for seeking and + 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`` - Return ``yes`` if the audio mixer is active, ``no`` otherwise. + 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. @@ -2238,14 +2325,14 @@ Property list Same as ``audio-params``, but the format of the data written to the audio API. -``colormatrix`` (R) +``colormatrix`` Redirects to ``video-params/colormatrix``. This parameter (as well as similar ones) can be overridden with the ``format`` video filter. -``colormatrix-input-range`` (R) +``colormatrix-input-range`` See ``colormatrix``. -``colormatrix-primaries`` (R) +``colormatrix-primaries`` See ``colormatrix``. ``hwdec`` (RW) @@ -2261,8 +2348,8 @@ Property list this purpose. ``hwdec-current`` - Return the current hardware decoding in use. If decoding is active, return - one of the values used by the ``hwdec`` option/property. ``no`` indicates + 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`` @@ -2299,6 +2386,10 @@ Property list 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 @@ -2357,6 +2448,7 @@ Property list 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 @@ -2401,12 +2493,20 @@ Property list redrawing and frame display being somewhat disconnected, and you might have to pause and force a redraw. - Sub-properties:: + 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/picture-type - video-frame-info/interlaced - video-frame-info/tff - video-frame-info/repeat + ``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 @@ -2429,6 +2529,15 @@ Property list (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. @@ -2437,14 +2546,21 @@ Property list Before mpv 0.31.0, this returned what ``current-window-scale`` returns now, after the window was created. -``current-window-scale`` +``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. The property is unavailable if no video is active. + 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 ther 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. Currently works only on X11 and Wayland. + 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 @@ -2468,13 +2584,18 @@ Property list versions, it returned the ``--display-fps`` option value. ``estimated-display-fps`` - Only available if display-sync mode (as selected by ``--video-sync``) is - active. Returns the actual rate at which display refreshes seem to occur, - measured by system time. + 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. @@ -2490,8 +2611,8 @@ Property list ``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 size, which can be - different from the window size in some cases. + ``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``. @@ -2506,31 +2627,45 @@ Property list Has the following sub-properties (which can be read as ``MPV_FORMAT_NODE`` or Lua table with ``mp.get_property_native``): - ``w`` + ``osd-dimensions/w`` Size of the VO window in OSD render units (usually pixels, but may be scaled pixels with VOs like ``xv``). - ``h`` + ``osd-dimensions/h`` Size of the VO window in OSD render units, - ``par`` + ``osd-dimensions/par`` Pixel aspect ratio of the OSD (usually 1). - ``aspect`` + ``osd-dimensions/aspect`` Display aspect ratio of the VO window. (Computing from the properties above.) - ``mt``, ``mb``, ``ml``, ``mr`` + ``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. +``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-text`` - Return 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. + 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. This property is experimental and might be removed in the future. @@ -2547,16 +2682,25 @@ Property list This property is experimental and might be removed in the future. +``secondary-sub-text`` + Same as ``sub-text``, but for the secondary subtitles. + ``sub-start`` - Return 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. + 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`` - Return 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. + 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 @@ -2630,12 +2774,12 @@ Property list Filename of the Nth entry. ``playlist/N/playing`` - ``yes`` if the ``playlist-playing-pos`` property points to this entry, - unavailable or ``no`` otherwise. + ``yes``/true if the ``playlist-playing-pos`` property points to this + entry, ``no``/false or unavailable otherwise. ``playlist/N/current`` - ``yes`` if the ``playlist-current-pos`` property points to this entry, - unavailable or ``no`` otherwise. + ``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. Only available if the playlist file contains @@ -2692,33 +2836,39 @@ Property list ``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`` if this is a video track that consists of a single picture, - ``no`` or unavailable otherwise. This is used for video tracks that are - really attached pictures in audio files. + ``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`` if the track has the default flag set in the file, ``no`` - otherwise. + ``yes``/true if the track has the default flag set in the file, + ``no``/false or unavailable otherwise. ``track-list/N/forced`` - ``yes`` if the track has the forced flag set in the file, ``no`` - otherwise. + ``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`` if the track is an external file, ``no`` otherwise. This is - set for separate subtitle files. + ``yes``/true if the track is an external file, ``no``/false or + |