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 | 128 | ||||
| -rw-r--r-- | DOCS/man/encode.rst | 21 | ||||
| -rw-r--r-- | DOCS/man/input.rst | 1576 | ||||
| -rw-r--r-- | DOCS/man/ipc.rst | 96 | ||||
| -rw-r--r-- | DOCS/man/javascript.rst | 64 | ||||
| -rw-r--r-- | DOCS/man/libmpv.rst | 20 | ||||
| -rw-r--r-- | DOCS/man/lua.rst | 279 | ||||
| -rw-r--r-- | DOCS/man/mpv.rst | 625 | ||||
| -rw-r--r-- | DOCS/man/options.rst | 2727 | ||||
| -rw-r--r-- | DOCS/man/osc.rst | 113 | ||||
| -rw-r--r-- | DOCS/man/stats.rst | 163 | ||||
| -rw-r--r-- | DOCS/man/vf.rst | 98 | ||||
| -rw-r--r-- | DOCS/man/vo.rst | 459 |
16 files changed, 4739 insertions, 1861 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 index 3c83d7e877..69cc103c15 100644 --- a/DOCS/man/console.rst +++ b/DOCS/man/console.rst @@ -11,59 +11,105 @@ Keybindings \` Show the console. -ESC +ESC and Ctrl+[ Hide the console. -ENTER +ENTER, Ctrl+j and Ctrl+m Run the typed command. Shift+ENTER Type a literal newline character. -Ctrl+LEFT and Ctrl+RIGHT - Move cursor to previous/next word. +LEFT and Ctrl+b + Move the cursor to the previous character. -UP and DOWN - Navigate command history. +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 command history. + Stop navigating the command history. INSERT Toggle insert mode. -Shift+INSERT - Paste text (uses the primary selection on X11.) +Ctrl+v + Paste text (uses the clipboard on X11 and Wayland). -TAB - Complete the command or property name at the cursor. +Shift+INSERT + Paste text (uses the primary selection on X11 and Wayland). -Ctrl+C - Clear current line. +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. -Ctrl+K. - Delete text from the cursor to the end of the line. +Shift+TAB + Cycle through the completions backwards. -Ctrl+L +Ctrl+l Clear all log messages from the console. -Ctrl+U - Delete text from the cursor to the beginning of the line. +Commands +-------- -Ctrl+V - Paste text (uses the clipboard on X11.) +``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. -Ctrl+W - Delete text from the cursor to the beginning of the current word. + .. admonition:: Examples for input.conf -Commands --------- + ``% script-message-to console type "seek absolute-percent; keypress ESC" 6`` + Enter a percent position to seek to and close the console. -``script-message-to console type <text>`` - Show the console and pre-fill it with the provided text. + ``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 ------------ @@ -77,7 +123,7 @@ 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 `ON SCREEN CONTROLLER`_. +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. @@ -97,11 +143,35 @@ Configurable Options ``font`` Default: unset (picks a hardcoded font depending on detected platform) - Set the font used for the REPL and the console. This probably doesn't - have to be a monospaced font. + 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 6262f5dc5a..26f3d6cbc8 100644 --- a/DOCS/man/encode.rst +++ b/DOCS/man/encode.rst @@ -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. @@ -50,18 +46,10 @@ You can encode files from one format/codec to another using this facility. ``--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. @@ -83,19 +71,14 @@ You can encode files from one format/codec to another using this facility. ``--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. diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index 04cd8883f7..7863090c59 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. @@ -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. + +Custom quotes also take the content literally, but are more flexible than single +quotes. They start with ````` (back-quote) followed by any ASCII character, +and end at the first occurrence of the same pair in reverse order, e.g. +```-foo-``` or ````bar````. The final pair sequence is not allowed at the +value - in these examples ``-``` and `````` respectively. In the second +example the last character of the value also can't be a back-quote. -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. +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. @@ -210,11 +238,10 @@ This applies to certain APIs, such as ``mp.command_native()`` (with tables that have string keys) in Lua scripting, or ``mpv_command_node()`` (with MPV_FORMAT_NODE_MAP) in the C libmpv client API. -Like with array commands, quoting and escaping is inherently not needed in the -normal case. - -The name of each command is defined in each command description in the -`List of Input Commands`_. ``--input-cmdlist`` also lists them. +The name of the command is provided with a ``name`` string field. The name of +each command is defined in each command description in the +`List of Input Commands`_. ``--input-cmdlist`` also lists them. See the +``subprocess`` command for an example. Some commands do not support named arguments (e.g. ``run`` command). You need to use APIs that pass arguments as arrays. @@ -222,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 ---------------------- @@ -234,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 @@ -277,6 +307,12 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). Mark the current time position. The next normal ``revert-seek`` command will seek back to this point, no matter how many seeks happened since last time. + mark-permanent + If set, mark the current position, and do not change the mark position + before the next ``revert-seek`` command that has ``mark`` or + ``mark-permanent`` set (or playback of the current file ends). Until + this happens, ``revert-seek`` will always seek to the marked point. This + flag cannot be combined with ``mark``. Using it without any arguments gives you the default behavior. @@ -298,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``. @@ -308,6 +347,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. @@ -326,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 @@ -344,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 |