diff options
Diffstat (limited to '')
| -rw-r--r-- | DOCS/man/input.rst | 241 |
1 files changed, 187 insertions, 54 deletions
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index 8dbf58b..6d6b64c 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. @@ -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 @@ -452,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. @@ -469,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: @@ -490,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. @@ -655,7 +694,7 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). wasn't started in detached mode, even if ``playback_only`` is false. - .. admonition:: Warning + .. 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 @@ -827,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 @@ -886,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 -------------------------------------------------- @@ -1033,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. @@ -1091,6 +1135,11 @@ 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 @@ -1213,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 @@ -1329,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 @@ -1422,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 @@ -2157,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. @@ -2318,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: @@ -2407,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 @@ -2579,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 @@ -2661,7 +2737,10 @@ Property list 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. + 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 @@ -2728,6 +2807,19 @@ 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. @@ -2953,6 +3045,13 @@ Property list The codec name used by this track, for example ``h264``. Unavailable in some rare cases. + ``track-list/N/codec-desc`` + The codec descriptive name used by this track. + + ``track-list/N/codec-profile`` + The codec profile used by this track. Available only if the track has + been already decoded. + ``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. @@ -3013,6 +3112,11 @@ Property list ``track-list/N/demux-par`` Pixel aspect ratio. + ``track-list/N/format-name`` + Short name for format from ffmpeg. If the track is audio, this will be + the name of the sample format. If the track is video, this will be the + name of the pixel format. + ``track-list/N/audio-channels`` (deprecated) Deprecated alias for ``track-list/N/demux-channel-count``. @@ -3048,6 +3152,8 @@ Property list "external" MPV_FORMAT_FLAG "external-filename" MPV_FORMAT_STRING "codec" MPV_FORMAT_STRING + "codec-desc" MPV_FORMAT_STRING + "codec-profile" MPV_FORMAT_STRING "ff-index" MPV_FORMAT_INT64 "decoder-desc" MPV_FORMAT_STRING "demux-w" MPV_FORMAT_INT64 @@ -3325,39 +3431,19 @@ Property list ``current-vo`` Current video output driver (name as used with ``--vo``). +``current-gpu-context`` + Current GPU context of video output driver (name as used with ``--gpu-context``). + Valid for ``--vo=gpu`` and ``--vo=gpu-next``. + ``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. @@ -3368,6 +3454,48 @@ Property list and not using raw mode, the underlying content will be given (e.g. strings will be printed directly, rather than quoted and JSON-escaped). +``menu-data`` (RW) + This property stores the raw menu definition. See `Context Menu`_ section for details. + + ``type`` + Menu item type. Can be: ``separator``, ``submenu``, or empty. + + ``title`` + Menu item title. Required if type is not ``separator``. + + ``cmd`` + Command to execute when the menu item is clicked. + + ``shortcut`` + Menu item shortcut key which appears to the right of the menu item. + A shortcut key does not have to be functional; it's just a visual hint. + + ``state`` + Menu item state. Can be: ``checked``, ``disabled``, ``hidden``, or empty. + + ``submenu`` + Submenu items, which is required if type is ``submenu``. + + 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 (menu item) + "type" MPV_FORMAT_STRING + "title" MPV_FORMAT_STRING + "cmd" MPV_FORMAT_STRING + "shortcut" MPV_FORMAT_STRING + "state" MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING] + "submenu" MPV_FORMAT_NODE_ARRAY[menu item] + + Writing to this property with the client API using ``MPV_FORMAT_NODE`` or with + Lua ``mp.set_property_native`` will trigger an immediate update of the menu if + mpv video output is currently active. You may observe the ``current-vo`` + property to check if this is the case. + ``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. @@ -3430,9 +3558,8 @@ Property list ``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. + or a git hash. This property is unavailable if mpv is linked against older + FFmpeg versions. ``libass-version`` The value of ``ass_library_version()``. This is an integer, encoded in a @@ -3681,7 +3808,9 @@ 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. +associated with the properties. Additionally, there is a ``>`` prefix to format +human-readable text, with fixed precision for floating-point values. This is +useful for printing values where a constant width is important. .. admonition:: Examples @@ -3690,6 +3819,10 @@ associated with the properties. - ``${=time-pos}`` expands to ``863.4`` (same time, plus 400 milliseconds - milliseconds are normally not shown in the formatted case) + - ``${avsync}`` expands to ``+0.003`` + - ``${>avsync}`` expands to ``+0.0030`` + - ``${=avsync}`` expands to ``0.003028`` + 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 |