diff options
Diffstat (limited to 'DOCS/man/input.rst')
| -rw-r--r-- | DOCS/man/input.rst | 621 |
1 files changed, 457 insertions, 164 deletions
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index 514ec0ad53..3e86004c28 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -49,8 +49,8 @@ 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. +characters, and thus does not register as a modifier. This can be changed +with ``--input-right-alt-gr`` option. Newlines always start a new binding. ``#`` starts a comment (outside of quoted string arguments). To bind commands to the ``#`` key, ``SHARP`` can be used. @@ -186,7 +186,7 @@ character at the value. Custom quotes also take the content literally, but are more flexible than single quotes. They start with ````` (back-quote) followed by any ASCII character, -and end at the first occurance of the same pair in reverse order, e.g. +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. @@ -264,7 +264,7 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). ``ignore`` Use this to "block" keys that should be unbound, and do nothing. Useful for disabling default bindings, without disabling all bindings with - ``--no-input-default-bindings``. + ``--input-default-bindings=no``. ``seek <target> [<flags>]`` Change the playback position. By default, seeks by a relative amount of @@ -334,6 +334,9 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). ``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``. @@ -366,8 +369,7 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). behavior depends on the selected video output. <window> Save the contents of the mpv window. Typically scaled, with OSD and - subtitles. The exact behavior depends on the selected video output, and - if no support is available, this will act like ``video``. + subtitles. The exact behavior depends on the selected video output. <each-frame> Take a screenshot each frame. Issue this command again to stop taking screenshots. Note that you should disable frame-dropping when using @@ -384,6 +386,9 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). 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 @@ -417,6 +422,13 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). 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: @@ -431,7 +443,7 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). Playback is stopped. If idle mode (``--idle``) is enabled, the player will enter idle mode, otherwise it will exit. - This comm and is similar to ``loadfile`` in that it only manipulates the + 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. @@ -440,9 +452,9 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). restarted if for example the new playlist entry is the same as the previous one. -``loadfile <url> [<flags> [<options>]]`` +``loadfile <url> [<flags> [<index> [<options>]]]`` Load the given file or URL and play it. Technically, this is just a playlist - manipulation command (which either replaces the playlist or appends an entry + manipulation command (which either replaces the playlist or adds an entry to it). Actual file loading happens independently. For example, a ``loadfile`` command that replaces the current file with a new one returns before the current file is stopped, and the new file even begins loading. @@ -457,15 +469,34 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). Append the file, and if nothing is currently playing, start playback. (Always starts with the added file, even if the playlist was not empty before running this command.) - - The third argument is a list of options and values which should be set + <insert-next> + Insert the file into the playlist, directly after the current entry. + <insert-next-play> + Insert the file next, and if nothing is currently playing, start playback. + (Always starts with the added file, even if the playlist was not empty + before running this command.) + <insert-at> + Insert the file into the playlist, at the index given in the third + argument. + <insert-at-play> + Insert the file at the index given in the third argument, and if nothing + is currently playing, start playback. (Always starts with the added + file, even if the playlist was not empty before running this command.) + + The third argument is an insertion index, used only by the ``insert-at`` and + ``insert-at-play`` actions. When used with those actions, the new item will + be inserted at the index position in the playlist, or appended to the end if + index is less than 0 or greater than the size of the playlist. This argument + will be ignored for all other actions. + + The fourth argument is a list of options and values which should be set while the file is playing. It is of the form ``opt1=value1,opt2=value2,..``. 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>]`` +``loadlist <url> [<flags> [<index>]]`` Load the given playlist file or URL (like ``--playlist``). Second argument: @@ -478,6 +509,26 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). Append the new playlist, and if nothing is currently playing, start playback. (Always starts with the new playlist, even if the internal playlist was not empty before running this command.) + <insert-next> + Insert the new playlist into the current internal playlist, directly + after the current entry. + <insert-next-play> + Insert the new playlist, and if nothing is currently playing, start + playback. (Always starts with the new playlist, even if the internal + playlist was not empty before running this command.) + <insert-at> + Insert the new playlist at the index given in the third argument. + <insert-at-play> + Insert the new playlist at the index given in the third argument, and if + nothing is currently playing, start playback. (Always starts with the + new playlist, even if the internal playlist was not empty before running + this command.) + + The third argument is an insertion index, used only by the ``insert-at`` and + ``insert-at-play`` actions. When used with those actions, the new playlist + will be inserted at the index position in the internal playlist, or appended + to the end if index is less than 0 or greater than the size of the internal + playlist. This argument will be ignored for all other actions. ``playlist-clear`` Clear the playlist, except the currently played file. @@ -551,9 +602,9 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). ``playback_only`` (``MPV_FORMAT_FLAG``) Boolean indicating whether the process should be killed when playback - terminates (optional, default: true). If enabled, stopping playback - will automatically kill the process, and you can't start it outside of - 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 @@ -581,7 +632,7 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). instead. (Unlike the underlying OS mechanisms, the mpv command cannot start a process with empty environment. Fortunately, that is completely useless.) The format of the list is as in the ``execle()`` syscall. Each - string item defines an environment variable as in ``NANME=VALUE``. + 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. @@ -600,12 +651,14 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). The command returns the following result (as ``MPV_FORMAT_NODE_MAP``): ``status`` (``MPV_FORMAT_INT64``) - The raw exit status of the process. It will be negative on error. The - meaning of negative values is undefined, other than meaning error (and - does not correspond to OS low level exit status values). - - On Windows, it can happen that a negative return value is returned - even if the process exits gracefully, because the win32 ``UINT`` exit + 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. @@ -616,9 +669,9 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). Same as ``stdout``, but for stderr. ``error_string`` (``MPV_FORMAT_STRING``) - Empty string if the process exited gracefully. The string ``killed`` if - the process was terminated in an unusual way. The string ``init`` if the - process could not be started. + 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. @@ -633,17 +686,19 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). 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. + 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. - In all cases, the subprocess will be terminated on player exit. Also see - `Asynchronous command details`_. Only the ``run`` command can start - processes in a truly detached way. + .. 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 + .. warning:: - Don't forget to set the ``playback_only`` field if you want the command - run while the player is in idle mode, or if you don't want that end of - playback kills the command. + 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 @@ -668,7 +723,7 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). ``quit-watch-later [<code>]`` Exit player, and store current playback position. Playing that file later will seek to the previous position on start. The (optional) argument is - exactly as in the ``quit`` command. + exactly as in the ``quit`` command. See `RESUMING PLAYBACK`_. ``sub-add <url> [<flags> [<title> [<lang>]]]`` Load the given subtitle file or stream. By default, it is selected as @@ -742,7 +797,7 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). ``show-text <text> [<duration>|-1 [<level>]]`` Show text on the OSD. The string can contain properties, which are expanded as described in `Property Expansion`_. This can be used to show playback - time, filename, and so on. + time, filename, and so on. ``no-osd`` has no effect on this command. <duration> The time in ms to show the message for. By default, it uses the same @@ -770,7 +825,7 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). ``show-progress`` Show the progress bar, the elapsed time and the total duration of the file - on the OSD. + on the OSD. ``no-osd`` has no effect on this command. ``write-watch-later-config`` Write the resume config file that the ``quit-watch-later`` command writes, @@ -811,11 +866,13 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). <double> The mouse event represents double-click. -``keypress <name>`` +``keypress <name> [<scale>]`` 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. + naming scheme for keys and modifiers. ``scale`` is used to scale numerical + change effected by the bound command (same mechanism as precise scrolling). + Useful for the client API: key events can be sent to libmpv to handle + internally. ``keydown <name>`` Similar to ``keypress``, but sets the ``KEYDOWN`` flag so that if the key is @@ -870,6 +927,9 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). <keep-selection> Do not change current track selections. +``context-menu`` + Show context menu on the video window. See `Context Menu`_ section for details. + Input Commands that are Possibly Subject to Change -------------------------------------------------- @@ -905,13 +965,6 @@ Input Commands that are Possibly Subject to Change <remove> Like ``toggle``, but always remove the given filter from the chain. - <del> - Remove the given filters from the video chain. Unlike in the other - cases, the second parameter is a comma separated list of filter names - or integer indexes. ``0`` would denote the first filter. Negative - indexes start from the last filter, and ``-1`` denotes the last - filter. Deprecated, use ``remove``. - <clr> Remove all filters. Note that like the other sub-commands, this does not control automatically inserted filters. @@ -1024,7 +1077,7 @@ Input Commands that are Possibly Subject to Change 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>`` +``overlay-add <id> <x> <y> <file> <offset> <fmt> <w> <h> <stride> <dw> <dh>`` 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. @@ -1082,12 +1135,17 @@ Input Commands that are Possibly Subject to Change (Technically, the minimum size would be ``stride * (h - 1) + w * 4``, but for simplicity, the player will access all ``stride * h`` bytes.) + ``dw`` and ``dh`` specify the (optional) display size of the overlay. + The overlay visible portion of the overlay (``w`` and ``h``) is scaled to + in display to ``dw`` and ``dh``. If parameters are not present, the + values for ``w`` and ``h`` are used. + .. 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 commend returns. + 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. @@ -1204,6 +1262,18 @@ Input Commands that are Possibly Subject to Change use the ``mp.create_osd_overlay()`` helper instead of invoking this command directly. +``escape-ass <text>`` + Modify ``text`` so that commands and functions that interpret ASS tags, + such as ``osd-overlay`` and ``mp.create_osd_overlay``, will display it + verbatim, and return it. This can only be used through the client API or + from a script using ``mp.command_native``. + + .. admonition:: Example + + ``mp.osd_message(mp.command_native({"escape-ass", "foo {bar}"}))`` + + This line of Lua prints "foo \\{bar}" on the OSD. + ``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 @@ -1287,16 +1357,21 @@ Input Commands that are Possibly Subject to Change The ``flags`` argument is like the first argument to ``screenshot`` and supports ``subtitles``, ``video``, ``window``. -``vf-command <label> <command> <argument>`` - Send a command to the filter with the given ``<label>``. Use ``all`` to send - it to all filters at once. The command and argument string is filter - specific. Currently, this only works with the ``lavfi`` filter - see - the libavfilter documentation for which commands a filter supports. +``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. - Note that the ``<label>`` is a mpv filter label, not a libavfilter filter - name. + ``<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>`` +``af-command <label> <command> <argument> [<target>]`` Same as ``vf-command``, but for audio filters. ``apply-profile <name> [<mode>]`` @@ -1315,6 +1390,16 @@ Input Commands that are Possibly Subject to Change relevant mode. Prints a warning if nothing could be done. See `Runtime profiles`_ for details. +``load-config-file <filename>`` + Load a configuration file, similar to the ``--include`` option. If the file + was already included, its previous options are not reset before it is + reparsed. + +``load-input-conf <filename>`` + Load an input configuration file, similar to the ``--input-conf`` option. If + the file was already included, its previous bindings are not reset before it + is reparsed. + ``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 @@ -1379,7 +1464,7 @@ Input Commands that are Possibly Subject to Change 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 reencode parts of a file + 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 @@ -1408,6 +1493,13 @@ Input Commands that are Possibly Subject to Change 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. +``begin-vo-dragging`` + Begin window dragging if supported by the current VO. This command should + only be called while a mouse button is being pressed, otherwise it will + be ignored. The exact effect of this command depends on the VO implementation + of window dragging. For example, on Windows only the left mouse button can + begin window dragging, while X11 and Wayland allow other mouse buttons. + Undocumented commands: ``ao-reload`` (experimental/internal). List of events @@ -1419,8 +1511,8 @@ 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 hooks -to enforce synchronous execution. +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: @@ -1815,7 +1907,7 @@ Property list .. note:: - Most options can be set as runtime via properties as well. Just remove the + 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 @@ -1916,6 +2008,11 @@ Property list 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. @@ -1930,13 +2027,9 @@ Property list situations, e.g. when video packets are damaged, or the decoder doesn't follow the usual rules. Unavailable if video is disabled. - ``drop-frame-count`` is a deprecated alias. - ``frame-drop-count`` Frames dropped by VO (when using ``--framedrop=vo``). - ``vo-drop-frame-count`` is a deprecated alias. - ``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 @@ -1966,6 +2059,11 @@ Property list ``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 @@ -1975,21 +2073,41 @@ Property list 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. @@ -2117,6 +2235,11 @@ Property list ``af-metadata/<filter-label>`` Equivalent to ``vf-metadata/<filter-label>``, but for audio filters. +``deinterlace-active`` + Returns ``yes``/true if mpv's deinterlacing filter is active. Note that it + will not detect any manually inserted deinterlacing filters done via + ``--vf``. + ``idle-active`` Returns ``yes``/true if no file is loaded, but the player is staying around because of the ``--idle`` option. @@ -2278,12 +2401,6 @@ Property list 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: @@ -2367,12 +2484,6 @@ Property list 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 @@ -2401,12 +2512,28 @@ Property list ``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 corresponds 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.) @@ -2419,7 +2546,7 @@ Property list ``video-params/gamma`` The gamma function in use as string. (Exact values subject to change.) - ``video-params/sig-peak`` + ``video-params/sig-peak`` (deprecated) The video file's tagged signal peak as float. ``video-params/light`` @@ -2440,6 +2567,33 @@ Property list (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: @@ -2466,6 +2620,15 @@ Property list "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 @@ -2487,6 +2650,11 @@ Property list Has the same sub-properties as ``video-params``. +``video-target-params`` + Same as ``video-params``, but with the target properties that VO outputs to. + + 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 @@ -2522,30 +2690,6 @@ Property list 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 @@ -2554,10 +2698,9 @@ Property list 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``. + It is also possible to write to this property. This has the same behavior as + writing ``window-scale``. Note that writing to ``current-window-scale`` will + not affect the value of ``window-scale``. ``focused`` Whether the window has focus. Might not be supported by all VOs. @@ -2568,8 +2711,11 @@ Property list 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 Product Names as used in the System Information with a serial number + in brackets and only one display name is returned since a window can only be + on one screen. On Wayland, these are the wl_output names if protocol + version >= 4 is used (LVDS-1, HDMI-A-1, X11-1, etc.), or the wl_output model + reported by the geometry event if protocol version < 4 is used. ``display-fps`` The refresh rate of the current display. Currently, this is the lowest FPS @@ -2578,11 +2724,6 @@ Property list available on all platforms. Note that any of the listed facts may change any time without a warning. - Writing to this property is deprecated. It has the same effect as writing to - ``override-display-fps``. Since mpv 0.31.0, this property is unavailable - if no display FPS was reported (e.g. if no video is active), while in older - versions, it returned the ``--display-fps`` option value. - ``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 @@ -2602,13 +2743,6 @@ Property list 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``. -``video-aspect`` (RW) - Deprecated. This is tied to ``--video-aspect-override``, but always - reports the current video aspect if video is active. - - The read and write components of this option can be split up into - ``video-params/aspect`` and ``video-aspect-override`` respectively. - ``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 @@ -2648,8 +2782,25 @@ Property list Any of these properties may be unavailable or set to dummy values if the VO window is not created or visible. +``term-size`` + The current terminal size. + + This has two sub-properties. + + ``term-size/w`` + width of the terminal in cells + ``term-size/h`` + height of the terminal in cells + + This property is not observable. Reacting to size changes requires + polling. + +``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. + Read-only - last known mouse position, normalized to OSD dimensions. Has the following sub-properties (which can be read as ``MPV_FORMAT_NODE`` or Lua table with ``mp.get_property_native``): @@ -2662,34 +2813,77 @@ Property list coordinates should be ignored when this value is false, because the video backends update them only when the pointer hovers the window. +``touch-pos`` + Read-only - last known touch point positions, normalized to OSD dimensions. + + This has a number of sub-properties. Replace ``N`` with the 0-based touch + point index. Whenever a new finger touches the screen, a new touch point is + added to the list of touch points with the smallest unused ``N`` available. + + ``touch-pos/count`` + Number of active touch points. + + ``touch-pos/N/x``, ``touch-pos/N/y`` + Position of the Nth touch point. + + ``touch-pos/N/id`` + Unique identifier of the touch point. This can be used to identify + individual touch points when their indexes change. + + 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 touch point) + "x" MPV_FORMAT_INT64 + "y" MPV_FORMAT_INT64 + "id" MPV_FORMAT_INT64 + +``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. - This property is experimental and might be removed in the future. + This has sub-properties for different formats: + + ``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. -``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 |