diff options
Diffstat (limited to 'DOCS/man')
| -rw-r--r-- | DOCS/man/af.rst | 65 | ||||
| -rw-r--r-- | DOCS/man/ao.rst | 157 | ||||
| -rw-r--r-- | DOCS/man/changes.rst | 9 | ||||
| -rw-r--r-- | DOCS/man/console.rst | 177 | ||||
| -rw-r--r-- | DOCS/man/encode.rst | 49 | ||||
| -rw-r--r-- | DOCS/man/input.rst | 1855 | ||||
| -rw-r--r-- | DOCS/man/ipc.rst | 96 | ||||
| -rw-r--r-- | DOCS/man/javascript.rst | 108 | ||||
| -rw-r--r-- | DOCS/man/libmpv.rst | 20 | ||||
| -rw-r--r-- | DOCS/man/lua.rst | 423 | ||||
| -rw-r--r-- | DOCS/man/mpv.rst | 854 | ||||
| -rw-r--r-- | DOCS/man/options.rst | 3177 | ||||
| -rw-r--r-- | DOCS/man/osc.rst | 149 | ||||
| -rw-r--r-- | DOCS/man/stats.rst | 166 | ||||
| -rw-r--r-- | DOCS/man/vf.rst | 306 | ||||
| -rw-r--r-- | DOCS/man/vo.rst | 471 |
16 files changed, 6085 insertions, 1997 deletions
diff --git a/DOCS/man/af.rst b/DOCS/man/af.rst index aebf76431a..98f9a9597a 100644 --- a/DOCS/man/af.rst +++ b/DOCS/man/af.rst @@ -19,8 +19,8 @@ syntax is: The ``--vf`` description describes how libavfilter can be used and how to workaround deprecated mpv filters. -See ``--vf`` group of options for info on how ``--af-defaults``, ``--af-add``, -``--af-pre``, ``--af-del``, ``--af-clr``, and possibly others work. +See ``--vf`` group of options for info on how ``--af-add``, ``--af-pre``, +``--af-clr``, and possibly others work. Available filters are: @@ -100,7 +100,7 @@ Available filters are: ``scaletempo[=option1:option2:...]`` Scales audio tempo without altering pitch, optionally synced to playback - speed (default). + speed. This works by playing 'stride' ms of audio at normal speed then consuming 'stride*scale' ms of input audio. It pieces the strides together by @@ -116,8 +116,8 @@ Available filters are: cause noticeable skips at high scale amounts and an echo at low scale amounts. Very low values will alter pitch. Increasing improves performance. (default: 60) - ``overlap=<percent>`` - Percentage of stride to overlap. Decreasing improves performance. + ``overlap=<factor>`` + Factor of stride to overlap. Decreasing improves performance. (default: .20) ``search=<amount>`` Length in milliseconds to search for best overlap position. Decreasing @@ -162,21 +162,59 @@ Available filters are: Changing playback speed would change pitch, leaving audio tempo at 1.2x. +``scaletempo2[=option1:option2:...]`` + Scales audio tempo without altering pitch. + The algorithm is ported from chromium and uses the + Waveform Similarity Overlap-and-add (WSOLA) method. + It seems to achieves higher audio quality than scaletempo, and rubberband R2 + engine, or ``engine=faster``. This filter is inserted automatically if + ``audio-pitch-correction`` option is used (on by default) when the playback + speed is changed. + + By default, the ``search-interval`` and ``window-size`` parameters + have the same values as in chromium. + + ``min-speed=<speed>`` + Mute audio if the playback speed is below ``<speed>``. (default: 0.25) + + ``max-speed=<speed>`` + Mute audio if the playback speed is above ``<speed>`` + and ``<speed> != 0``. (default: 8.0) + + ``search-interval=<amount>`` + Length in milliseconds to search for best overlap position. (default: 40) + + ``window-size=<amount>`` + Length in milliseconds of the overlap-and-add window. (default: 12) + ``rubberband`` High quality pitch correction with librubberband. This can be used in place - of ``scaletempo``, and will be used to adjust audio pitch when playing - at speed different from normal. It can also be used to adjust audio pitch - without changing playback speed. + of ``scaletempo`` and ``scaletempo2``, and will be used to adjust audio pitch + when playing at speed different from normal. It can also be used to adjust + audio pitch without changing playback speed. - ``<pitch-scale>`` + ``pitch-scale=<amount>`` Sets the pitch scaling factor. Frequencies are multiplied by this value. + (default: 1.0) + + ``engine=<faster|finer>`` + Select the core Rubberband engine to be used. There are two available: + + :Faster: This is the Rubberband R2 engine. It uses significantly less + CPU than the Finer (R3) engine. + :Finer: This is the Rubberband R3 engine. This engine is only available + with librubberband version 3 or newer. This produces significantly + higher quality output, at the cost of higher CPU usage. (Default + if available) This filter has a number of additional sub-options. You can list them with ``mpv --af=rubberband=help``. This will also show the default values for each option. The options are not documented here, because they are merely passed to librubberband. Look at the librubberband documentation to learn what each option does: - http://breakfastquay.com/rubberband/code-doc/classRubberBand_1_1RubberBandStretcher.html + https://breakfastquay.com/rubberband/code-doc/classRubberBand_1_1RubberBandStretcher.html + Do note that certain options are only applicable to one of R2 (faster) and + R3 (finer) engines. (The mapping of the mpv rubberband filter sub-option names and values to those of librubberband follows a simple pattern: ``"Option" + Name + Value``.) @@ -220,3 +258,10 @@ Available filters are: broken filters. In practice, these broken filters will either cause slow A/V desync over time (with some files), or break playback completely if you seek or start playback from the middle of a file. + +``drop`` + This filter drops or repeats audio frames to adapt to playback speed. It + always operates on full audio frames, because it was made to handle SPDIF + (compressed audio passthrough). This is used automatically if the + ``--video-sync=display-adrop`` option is used. Do not use this filter (or + the given option); they are extremely low quality. diff --git a/DOCS/man/ao.rst b/DOCS/man/ao.rst index a0c5052b46..78dfed3b51 100644 --- a/DOCS/man/ao.rst +++ b/DOCS/man/ao.rst @@ -12,17 +12,59 @@ in the list. .. note:: - See ``--ao=help`` for a list of compiled-in audio output drivers. The - driver ``--ao=alsa`` is preferred. ``--ao=pulse`` is preferred on systems - where PulseAudio is used. On BSD systems, ``--ao=oss`` or ``--ao=sndio`` - may work (the latter being experimental). + See ``--ao=help`` for a list of compiled-in audio output drivers sorted by + autoprobe order. Available audio output drivers are: -``alsa`` (Linux only) - ALSA audio output driver +``alsa`` + ALSA audio output driver. - See `ALSA audio output options`_ for options specific to this AO. + The following global options are supported by this audio output: + + ``--alsa-resample=yes`` + Enable ALSA resampling plugin. (This is disabled by default, because + some drivers report incorrect audio delay in some cases.) + + ``--alsa-mixer-device=<device>`` + Set the mixer device used with ``ao-volume`` (default: ``default``). + + ``--alsa-mixer-name=<name>`` + Set the name of the mixer element (default: ``Master``). This is for + example ``PCM`` or ``Master``. + + ``--alsa-mixer-index=<number>`` + Set the index of the mixer channel (default: 0). Consider the output of + "``amixer scontrols``", then the index is the number that follows the + name of the element. + + ``--alsa-non-interleaved`` + Allow output of non-interleaved formats (if the audio decoder uses + this format). Currently disabled by default, because some popular + ALSA plugins are utterly broken with non-interleaved formats. + + ``--alsa-ignore-chmap`` + Don't read or set the channel map of the ALSA device - only request the + required number of channels, and then pass the audio as-is to it. This + option most likely should not be used. It can be useful for debugging, + or for static setups with a specially engineered ALSA configuration (in + this case you should always force the same layout with ``--audio-channels``, + or it will work only for files which use the layout implicit to your + ALSA device). + + ``--alsa-buffer-time=<microseconds>`` + Set the requested buffer time in microseconds. A value of 0 skips requesting + anything from the ALSA API. This and the ``--alsa-periods`` option uses the + ALSA ``near`` functions to set the requested parameters. If doing so results + in an empty configuration set, setting these parameters is skipped. + + Both options control the buffer size. A low buffer size can lead to higher + CPU usage and audio dropouts, while a high buffer size can lead to higher + latency in volume changes and other filtering. + + ``--alsa-periods=<number>`` + Number of periods requested from the ALSA API. See ``--alsa-buffer-time`` + for further remarks. .. warning:: @@ -31,7 +73,8 @@ Available audio output drivers are: explicitly reject multichannel output, as there is no way to detect whether a certain channel layout is actually supported. - You can also try `using the upmix plugin <http://git.io/vfuAy>`_. + You can also try `using the upmix plugin + <https://github.com/mpv-player/mpv/wiki/ALSA-Surround-Sound-and-Upmixing>`_. This setup enables multichannel audio on the ``default`` device with automatic upmixing with shared access, so playing stereo and multichannel audio at the same time will work as expected. @@ -39,15 +82,6 @@ Available audio output drivers are: ``oss`` OSS audio output driver - The following global options are supported by this audio output: - - ``--oss-mixer-device`` - Sets the audio mixer device (default: ``/dev/mixer``). - ``--oss-mixer-channel`` - Sets the audio mixer channel (default: ``pcm``). Other valid values - include **vol, pcm, line**. For a complete list of options look for - ``SOUND_DEVICE_NAMES`` in ``/usr/include/linux/soundcard.h``. - ``jack`` JACK (Jack Audio Connection Kit) audio output driver. @@ -78,8 +112,8 @@ Available audio output drivers are: mode is probably not very useful, other than for debugging or when used with fixed setups. -``coreaudio`` (Mac OS X only) - Native Mac OS X audio output driver using AudioUnits and the CoreAudio +``coreaudio`` (macOS only) + Native macOS audio output driver using AudioUnits and the CoreAudio sound server. Automatically redirects to ``coreaudio_exclusive`` when playing compressed @@ -104,13 +138,23 @@ Available audio output drivers are: passthrough (even if the device reports it as supported). Use with extreme care. - -``coreaudio_exclusive`` (Mac OS X only) - Native Mac OS X audio output driver using direct device access and +``coreaudio_exclusive`` (macOS only) + Native macOS audio output driver using direct device access and exclusive mode (bypasses the sound server). +``avfoundation`` (macOS only) + Native macOS audio output driver using ``AVSampleBufferAudioRenderer`` + in AVFoundation, which supports `spatial audio + <https://support.apple.com/en-us/HT211775>`_. + + .. warning:: + + Turning on spatial audio may hang the playback + if mpv is not started out of the bundle, + though playback with spatial audio off always works. + ``openal`` - OpenAL audio output driver + OpenAL audio output driver. ``--openal-num-buffers=<2-128>`` Specify the number of audio buffers to use. Lower values are better for @@ -122,9 +166,7 @@ Available audio output drivers are: ``--openal-direct-channels=<yes|no>`` Enable OpenAL Soft's direct channel extension when available to avoid - tinting the sound with ambisonics or HRTF. - Channels are dropped when when they are not available as downmixing - will be disabled. Default: no. + tinting the sound with ambisonics or HRTF. Default: yes. ``pulse`` PulseAudio audio output driver @@ -139,26 +181,44 @@ Available audio output drivers are: Set the audio buffer size in milliseconds. A higher value buffers more data, and has a lower probability of buffer underruns. A smaller value makes the audio stream react faster, e.g. to playback speed - changes. + changes. "native" lets the sound server determine buffers. ``--pulse-latency-hacks=<yes|no>`` - Enable hacks to workaround PulseAudio timing bugs (default: no). If + Enable hacks to workaround PulseAudio timing bugs (default: yes). If enabled, mpv will do elaborate latency calculations on its own. If disabled, it will use PulseAudio automatically updated timing information. Disabling this might help with e.g. networked audio or some plugins, while enabling it might help in some unknown situations - (it used to be required to get good behavior on old PulseAudio versions). - - If you have stuttering video when using pulse, try to enable this - option. (Or try to update PulseAudio.) + (it is currently enabled due to known bugs with PulseAudio 16.0). ``--pulse-allow-suspended=<yes|no>`` Allow mpv to use PulseAudio even if the sink is suspended (default: no). Can be useful if PulseAudio is running as a bridge to jack and mpv has its sink-input set to the one jack is using. +``pipewire`` + PipeWire audio output driver + + The following global options are supported by this audio output: + + ``--pipewire-buffer=<1-2000|native>`` + Set the audio buffer size in milliseconds. A higher value buffers + more data, and has a lower probability of buffer underruns. A smaller + value makes the audio stream react faster, e.g. to playback speed + changes. "native" lets the sound server determine buffers. + + ``--pipewire-remote=<remote>`` + Specify the PipeWire remote daemon name to connect to via local UNIX + sockets. + An empty <remote> string uses the default remote named ``pipewire-0``. + + ``--pipewire-volume-mode=<channel|global>`` + Specify if the ``ao-volume`` property should apply to the channel + volumes or the global volume. + By default the channel volumes are used. + ``sdl`` - SDL 1.2+ audio output driver. Should work on any platform supported by SDL - 1.2, but may require the ``SDL_AUDIODRIVER`` environment variable to be set + SDL 2.0+ audio output driver. Should work on any platform supported by SDL + 2.0, but may require the ``SDL_AUDIODRIVER`` environment variable to be set appropriately for your system. .. note:: This driver is for compatibility with extremely foreign @@ -173,10 +233,6 @@ Available audio output drivers are: obtained exact buffer size. A value of 0 selects the sound system default. - ``--sdl-bufcnt=<count>`` - Sets the number of extra audio buffers in mpv. Usually needs not be - changed. - ``null`` Produces no audio output but maintains video playback speed. You can use ``--ao=null --ao-null-untimed`` for benchmarking. @@ -233,21 +289,26 @@ Available audio output drivers are: ``no-waveheader`` option - with ``waveheader`` it's broken, because it will write a WAVE header every time the file is opened. -``rsound`` - Audio output to an RSound daemon. Use ``--audio-device=rsound/<hostname>`` - to set the host name (with ``<hostname>`` replaced, without the ``< >``). - - .. note:: Completely useless, unless you intend to run RSound. Not to be - confused with RoarAudio, which is something completely - different. - ``sndio`` Audio output to the OpenBSD sndio sound system - .. note:: Experimental. There are known bugs and issues. - (Note: only supports mono, stereo, 4.0, 5.1 and 7.1 channel layouts.) ``wasapi`` Audio output to the Windows Audio Session API. + + The following global options are supported by this audio output: + + ``--wasapi-exclusive-buffer=<default|min|1-2000000>`` + Set buffer duration in exclusive mode (i.e., with + ``--audio-exclusive=yes``). ``default`` and ``min`` use the default and + minimum device period reported by WASAPI, respectively. You can also + directly specify the buffer duration in microseconds, in which case a + duration shorter than the minimum device period will be rounded up to + the minimum period. + + The default buffer duration should provide robust playback in most + cases, but reportedly on some devices there are glitches following + stream resets under the default setting. In such cases, specifying a + shorter duration might help. diff --git a/DOCS/man/changes.rst b/DOCS/man/changes.rst index d1daa32bd7..3f5e0e12c8 100644 --- a/DOCS/man/changes.rst +++ b/DOCS/man/changes.rst @@ -8,10 +8,11 @@ There is no real changelog, but you can look at the following things: https://github.com/mpv-player/mpv/releases * The git log, which is the "real" changelog -* The files ``client-api-changes.rst`` and ``interface-changes.rst`` in the - ``DOCS`` sub directoryon the git repository, which document API and user - interface changes (the latter usually documents breaking changes only, rather - than additions). +* The file https://github.com/mpv-player/mpv/blob/master/DOCS/interface-changes.rst + documents changes to the command and user interface, such as options and + properties. +* C API changes are listed in + https://github.com/mpv-player/mpv/blob/master/DOCS/client-api-changes.rst * The file ``mplayer-changes.rst`` in the ``DOCS`` sub directory on the git repository, which used to be in place of this section. It documents some changes that happened since mplayer2 forked off MPlayer. (Not updated diff --git a/DOCS/man/console.rst b/DOCS/man/console.rst new file mode 100644 index 0000000000..69cc103c15 --- /dev/null +++ b/DOCS/man/console.rst @@ -0,0 +1,177 @@ +CONSOLE +======= + +The console is a REPL for mpv input commands. It is displayed on the video +window. It also shows log messages. It can be disabled entirely using the +``--load-osd-console=no`` option. + +Keybindings +----------- + +\` + Show the console. + +ESC and Ctrl+[ + Hide the console. + +ENTER, Ctrl+j and Ctrl+m + Run the typed command. + +Shift+ENTER + Type a literal newline character. + +LEFT and Ctrl+b + Move the cursor to the previous character. + +RIGHT and Ctrl+f + Move the cursor to the next character. + +Ctrl+LEFT and Alt+b + Move the cursor to the beginning of the current word, or if between words, + to the beginning of the previous word. + +Ctrl+RIGHT and Alt+f + Move the cursor to the end of the current word, or if between words, to the + end of the next word. + +HOME and Ctrl+a + Move the cursor to the start of the current line. + +END and Ctrl+e + Move the cursor to the end of the current line. + +BACKSPACE and Ctrl+h + Delete the previous character. + +Ctrl+d + Hide the console if the current line is empty, otherwise delete the next + character. + +Ctrl+BACKSPACE and Ctrl+w + Delete text from the cursor to the beginning of the current word, or if + between words, to the beginning of the previous word. + +Ctrl+DEL and Alt+d + Delete text from the cursor to the end of the current word, or if between + words, to the end of the next word. + +Ctrl+u + Delete text from the cursor to the beginning of the current line. + +Ctrl+k + Delete text from the cursor to the end of the current line. + +Ctrl+c + Clear the current line. + +UP and Ctrl+p + Move back in the command history. + +DOWN and Ctrl+n + Move forward in the command history. + +PGUP + Go to the first command in the history. + +PGDN + Stop navigating the command history. + +INSERT + Toggle insert mode. + +Ctrl+v + Paste text (uses the clipboard on X11 and Wayland). + +Shift+INSERT + Paste text (uses the primary selection on X11 and Wayland). + +TAB and Ctrl+i + Complete the text at the cursor. The first press inserts the longest common + prefix of the completions, and subsequent presses cycle through them. + +Shift+TAB + Cycle through the completions backwards. + +Ctrl+l + Clear all log messages from the console. + +Commands +-------- + +``script-message-to console type <text> [<cursor_pos>]`` + Show the console and pre-fill it with the provided text, optionally + specifying the initial cursor position as a positive integer starting from + 1. + + .. admonition:: Examples for input.conf + + ``% script-message-to console type "seek absolute-percent; keypress ESC" 6`` + Enter a percent position to seek to and close the console. + + ``Ctrl+o script-message-to console type "loadfile ''; keypress ESC" 11`` + Enter a file or URL to play. Tab completes paths in the filesystem. + +Known issues +------------ + +- Pasting text is slow on Windows +- Non-ASCII keyboard input has restrictions +- The cursor keys move between Unicode code-points, not grapheme clusters + +Configuration +------------- + +This script can be customized through a config file ``script-opts/console.conf`` +placed in mpv's user directory and through the ``--script-opts`` command-line +option. The configuration syntax is described in `mp.options functions`_. + +Key bindings can be changed in a standard way, see for example stats.lua +documentation. + +Configurable Options +~~~~~~~~~~~~~~~~~~~~ + +``scale`` + Default: 1 + + All drawing is scaled by this value, including the text borders and the + cursor. + + If the VO backend in use has HiDPI scale reporting implemented, the option + value is scaled with the reported HiDPI scale. + +``font`` + Default: unset (picks a hardcoded font depending on detected platform) + + Set the font used for the REPL and the console. + This has to be a monospaced font for the completion suggestions to be + aligned correctly. + +``font_size`` + Default: 16 + + Set the font size used for the REPL and the console. This will be + multiplied by "scale". + +``border_size`` + Default: 1 + + Set the font border size used for the REPL and the console. + +``case_sensitive`` + Default: no on Windows, yes on other platforms. + + Whether Tab completion is case sensitive. Only works with ASCII characters. + +``history_dedup`` + Default: true + + Remove duplicate entries in history as to only keep the latest one. + multiplied by "scale." + +``font_hw_ratio`` + Default: auto + + The ratio of font height to font width. + Adjusts table width of completion suggestions. + Values in the range 1.8..2.5 make sense for common monospace fonts. diff --git a/DOCS/man/encode.rst b/DOCS/man/encode.rst index 4c885ea168..26f3d6cbc8 100644 --- a/DOCS/man/encode.rst +++ b/DOCS/man/encode.rst @@ -15,11 +15,11 @@ You can encode files from one format/codec to another using this facility. Specifies the output format options for libavformat. See ``--ofopts=help`` for a full list of supported options. - Options are managed in lists. There are a few commands to manage the - options list. + This is a key/value list option. See `List Options`_ for details. - ``--ofopts-add=<options1[,options2,...]>`` - Appends the options given as arguments to the options list. + ``--ofopts-add=<option>`` + Appends the option given as an argument to the options list. (Passing + multiple options is currently still possible, but deprecated.) ``--ofopts=""`` Completely empties the options list. @@ -28,10 +28,6 @@ You can encode files from one format/codec to another using this facility. Specifies the output audio codec. See ``--oac=help`` for a full list of supported codecs. -``--oaoffset=<value>`` - Shifts audio data by the given time (in seconds) by adding/removing - samples at the start. Deprecated. - ``--oacopts=<options>`` Specifies the output audio codec options for libavcodec. See ``--oacopts=help`` for a full list of supported options. @@ -41,27 +37,19 @@ You can encode files from one format/codec to another using this facility. "``--oac=libmp3lame --oacopts=b=128000``" selects 128 kbps MP3 encoding. - Options are managed in lists. There are a few commands to manage the - options list. + This is a key/value list option. See `List Options`_ for details. - ``--oacopts-add=<options1[,options2,...]>`` - Appends the options given as arguments to the options list. + ``--oacopts-add=<option>`` + Appends the option given as an argument to the options list. (Passing + multiple options is currently still possible, but deprecated.) ``--oacopts=""`` Completely empties the options list. -``--oafirst`` - Force the audio stream to become the first stream in the output. - By default, the order is unspecified. Deprecated. - ``--ovc=<codec>`` Specifies the output video codec. See ``--ovc=help`` for a full list of supported codecs. -``--ovoffset=<value>`` - Shifts video data by the given time (in seconds) by shifting the pts - values. Deprecated. - ``--ovcopts=<options>`` Specifies the output video codec options for libavcodec. See --ovcopts=help for a full list of supported options. @@ -74,28 +62,23 @@ You can encode files from one format/codec to another using this facility. ``"--ovc=libx264 --ovcopts=crf=23"`` selects VBR quality factor 23 for H.264 encoding. - Options are managed in lists. There are a few commands to manage the - options list. + This is a key/value list option. See `List Options`_ for details. - ``--ovcopts-add=<options1[,options2,...]>`` - Appends the options given as arguments to the options list. + ``--ovcopts-add=<option>`` + Appends the option given as an argument to the options list. (Passing + multiple options is currently still possible, but deprecated.) ``--ovcopts=""`` Completely empties the options list. -``--ovfirst`` - Force the video stream to become the first stream in the output. - By default, the order is unspecified. Deprecated. - ``--orawts`` Copies input pts to the output video (not supported by some output container formats, e.g. AVI). In this mode, discontinuities are not fixed and all pts are passed through as-is. Never seek backwards or use multiple input files in this mode! -``--no-ocopy-metadata`` - Turns off copying of metadata from input files to output files when - encoding (which is enabled by default). +``--ocopy-metadata=<yes|no>`` + Copy metadata from input files to output files when encoding (default: yes). ``--oset-metadata=<metadata-tag[,metadata-tag,...]>`` Specifies metadata to include in the output file. @@ -103,6 +86,8 @@ You can encode files from one format/codec to another using this facility. FLAC allow almost arbitrary keys, while support in MP4 and MP3 is more limited. + This is a key/value list option. See `List Options`_ for details. + .. admonition:: Example "``--oset-metadata=title="Output title",comment="Another tag"``" @@ -112,6 +97,8 @@ You can encode files from one format/codec to another using this facility. Specifies metadata to exclude from the output file when copying from the input file. + This is a string list option. See `List Options`_ for details. + .. admonition:: Example "``--oremove-metadata=comment,genre``" diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index c96876563f..7863090c59 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -41,14 +41,16 @@ commands they're bound to on the OSD, instead of executing the commands:: (Only closing the window will make **mpv** exit, pressing normal keys will merely display the binding, even if mapped to quit.) +Also see `Key names`_. + input.conf syntax ----------------- ``[Shift+][Ctrl+][Alt+][Meta+]<key> [{<section>}] <command> ( ; <command> )*`` Note that by default, the right Alt key can be used to create special -characters, and thus does not register as a modifier. The option -``--no-input-right-alt-gr`` changes this behavior. +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. @@ -60,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: @@ -78,25 +80,124 @@ that matches, and the multi-key command will never be called. Intermediate keys can be remapped to ``ignore`` in order to avoid this issue. The maximum number of (non-modifier) keys for combinations is currently 4. +Key names +--------- + +All mouse and keyboard input is to converted to mpv-specific key names. Key +names are either special symbolic identifiers representing a physical key, or a +text key names, which are unicode code points encoded as UTF-8. These are what +keyboard input would normally produce, for example ``a`` for the A key. As a +consequence, mpv uses input translated by the current OS keyboard layout, rather +than physical scan codes. + +Currently there is the hardcoded assumption that every text key can be +represented as a single unicode code point (in NFKC form). + +All key names can be combined with the modifiers ``Shift``, ``Ctrl``, ``Alt``, +``Meta``. They must be prefixed to the actual key name, where each modifier +is followed by a ``+`` (for example ``ctrl+q``). + +The ``Shift`` modifier requires some attention. For instance ``Shift+2`` should +usually be specified as key-name ``@`` at ``input.conf``, and similarly the +combination ``Alt+Shift+2`` is usually ``Alt+@``, etc. Special key names like +``Shift+LEFT`` work as expected. If in doubt - use ``--input-test`` to check +how a key/combination is seen by mpv. + +Symbolic key names and modifier names are case-insensitive. Unicode key names +are case-sensitive because input bindings typically respect the shift key. + +Another type of key names are hexadecimal key names, that serve as fallback +for special keys that are neither unicode, nor have a special mpv defined name. +They will break as soon as mpv adds proper names for them, but can enable you +to use a key at all if that does not happen. + +All symbolic names are listed by ``--input-keylist``. ``--input-test`` is a +special mode that prints all input on the OSD. + +Comments on some symbolic names: + +``KP*`` + Keypad names. Behavior varies by backend (whether they implement this, and + on how they treat numlock), but typically, mpv tries to map keys on the + keypad to separate names, even if they produce the same text as normal keys. + +``MOUSE_BTN*``, ``MBTN*`` + Various mouse buttons. + + Depending on backend, the mouse wheel might also be represented as a button. + In addition, ``MOUSE_BTN3`` to ``MOUSE_BTN6`` are deprecated aliases for + ``WHEEL_UP``, ``WHEEL_DOWN``, ``WHEEL_LEFT``, ``WHEEL_RIGHT``. + + ``MBTN*`` are aliases for ``MOUSE_BTN*``. + +``WHEEL_*`` + Mouse wheels (typically). + +``AXIS_*`` + Deprecated aliases for ``WHEEL_*``. + +``*_DBL`` + Mouse button double clicks. + +``MOUSE_MOVE``, ``MOUSE_ENTER``, ``MOUSE_LEAVE`` + Emitted by mouse move events. Enter/leave happens when the mouse enters or + leave the mpv window (or the current mouse region, using the deprecated + mouse region input section mechanism). + +``CLOSE_WIN`` + Pseudo key emitted when closing the mpv window using the OS window manager + (for example, by clicking the close button in the window title bar). + +``GAMEPAD_*`` + Keys emitted by the SDL gamepad backend. + +``UNMAPPED`` + Pseudo-key that matches any unmapped key. (You should probably avoid this + if possible, because it might change behavior or get removed in the future.) + +``ANY_UNICODE`` + Pseudo-key that matches any key that produces text. (You should probably + avoid this if possible, because it might change behavior or get removed in + the future.) + Flat command syntax ------------------- This is the syntax used in input.conf, and referred to "input.conf syntax" in a number of other places. -``<command> ::= [<prefixes>] <command_name> (<argument>)*`` -``<argument> ::= (<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``. -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. |