summaryrefslogtreecommitdiffstats
path: root/DOCS/man
diff options
context:
space:
mode:
Diffstat (limited to 'DOCS/man')
-rw-r--r--DOCS/man/af.rst50
-rw-r--r--DOCS/man/ao.rst114
-rw-r--r--DOCS/man/changes.rst3
-rw-r--r--DOCS/man/console.rst85
-rw-r--r--DOCS/man/encode.rst23
-rw-r--r--DOCS/man/input.rst633
-rw-r--r--DOCS/man/ipc.rst4
-rw-r--r--DOCS/man/javascript.rst29
-rw-r--r--DOCS/man/libmpv.rst14
-rw-r--r--DOCS/man/lua.rst168
-rw-r--r--DOCS/man/mpv.rst406
-rw-r--r--DOCS/man/options.rst1883
-rw-r--r--DOCS/man/osc.rst140
-rw-r--r--DOCS/man/stats.rst77
-rw-r--r--DOCS/man/vf.rst76
-rw-r--r--DOCS/man/vo.rst246
16 files changed, 2682 insertions, 1269 deletions
diff --git a/DOCS/man/af.rst b/DOCS/man/af.rst
index 5ff7426382..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
@@ -161,14 +161,17 @@ Available filters are:
Would play media at 1.2x normal speed, with audio at normal pitch.
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
+ The algorithm is ported from chromium and uses the
Waveform Similarity Overlap-and-add (WSOLA) method.
- It seems to achieve a higher audio quality than scaletempo and rubberband.
+ 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
+ By default, the ``search-interval`` and ``window-size`` parameters
have the same values as in chromium.
``min-speed=<speed>``
@@ -176,22 +179,33 @@ Available filters are:
``max-speed=<speed>``
Mute audio if the playback speed is above ``<speed>``
- and ``<speed> != 0``. (default: 4.0)
+ and ``<speed> != 0``. (default: 8.0)
``search-interval=<amount>``
- Length in milliseconds to search for best overlap position. (default: 30)
-
+ Length in milliseconds to search for best overlap position. (default: 40)
+
``window-size=<amount>``
- Length in milliseconds of the overlap-and-add window. (default: 20)
+ 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
@@ -199,6 +213,8 @@ Available filters are:
merely passed to librubberband. Look at the librubberband documentation
to learn what each option does:
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``.)
diff --git a/DOCS/man/ao.rst b/DOCS/man/ao.rst
index 69ee4da498..f03f64242e 100644
--- a/DOCS/man/ao.rst
+++ b/DOCS/man/ao.rst
@@ -12,16 +12,63 @@ 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`` is preferred.
+ See ``--ao=help`` for a list of compiled-in audio output drivers sorted by
+ autoprobe order.
+
+ Note that the default audio output driver is subject to change, and must
+ not be relied upon. If a certain AO needs to be used, it must be
+ explicitly specified.
Available audio output drivers are:
-``alsa`` (Linux only)
- ALSA audio output driver
+``alsa``
+ ALSA audio output driver.
+
+ The following global options are supported by this audio output:
- See `ALSA audio output options`_ for options specific to this AO.
+ ``--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::
@@ -30,7 +77,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.
@@ -94,11 +142,21 @@ Available audio output drivers are:
passthrough (even if the device reports it as supported). Use with
extreme care.
-
``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.
@@ -127,18 +185,15 @@ 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).
@@ -153,11 +208,21 @@ 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.
+
+ ``--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
@@ -236,3 +301,18 @@ Available audio output drivers are:
``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 63de41c8d2..3f5e0e12c8 100644
--- a/DOCS/man/changes.rst
+++ b/DOCS/man/changes.rst
@@ -10,8 +10,7 @@ There is no real changelog, but you can look at the following things:
* The git log, which is the "real" changelog
* 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. (It usually documents breaking changes only, additions and
- enhancements are often not listed.)
+ 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
diff --git a/DOCS/man/console.rst b/DOCS/man/console.rst
index f883a14c2b..7028e6c76d 100644
--- a/DOCS/man/console.rst
+++ b/DOCS/man/console.rst
@@ -11,63 +11,63 @@ Keybindings
\`
Show the console.
-ESC
+ESC and Ctrl+[
Hide the console.
-ENTER, Ctrl+J and Ctrl+M
+ENTER, Ctrl+j and Ctrl+m
Run the typed command.
Shift+ENTER
Type a literal newline character.
-LEFT and Ctrl+B
+LEFT and Ctrl+b
Move the cursor to the previous character.
-RIGHT and Ctrl+F
+RIGHT and Ctrl+f
Move the cursor to the next character.
-Ctrl+LEFT and Alt+B
+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
+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
+HOME and Ctrl+a
Move the cursor to the start of the current line.
-END and Ctrl+E
+END and Ctrl+e
Move the cursor to the end of the current line.
-BACKSPACE and Ctrl+H
+BACKSPACE and Ctrl+h
Delete the previous character.
-Ctrl+D
+Ctrl+d
Hide the console if the current line is empty, otherwise delete the next
character.
-Ctrl+BACKSPACE and Ctrl+W
+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
+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
+Ctrl+u
Delete text from the cursor to the beginning of the current line.
-Ctrl+K
+Ctrl+k
Delete text from the cursor to the end of the current line.
-Ctrl+C
+Ctrl+c
Clear the current line.
-UP and Ctrl+P
+UP and Ctrl+p
Move back in the command history.
-DOWN and Ctrl+N
+DOWN and Ctrl+n
Move forward in the command history.
PGUP
@@ -79,16 +79,20 @@ PGDN
INSERT
Toggle insert mode.
-Ctrl+V
+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 command or property name at the cursor.
+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+L
+Shift+TAB
+ Cycle through the completions backwards.
+
+Ctrl+l
Clear all log messages from the console.
Commands
@@ -99,9 +103,13 @@ Commands
specifying the initial cursor position as a positive integer starting from
1.
- .. admonition:: Example for input.conf
+ .. 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.
- ``% script-message-to console type "seek absolute-percent" 6``
+ ``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
------------
@@ -115,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.
@@ -135,11 +143,34 @@ 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."
+ 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.
+
+``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..c650d0f6c4 100644
--- a/DOCS/man/encode.rst
+++ b/DOCS/man/encode.rst
@@ -8,7 +8,7 @@ You can encode files from one format/codec to another using this facility.
``--of=<format>``
Specifies the output format (overrides autodetection by the file name
- extension of the file specified by ``-o``). See ``--of=help`` for a full
+ extension of the file specified by ``--o``). See ``--of=help`` for a full
list of supported formats.
``--ofopts=<options>``
@@ -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 54b5ad11d1..6f189cf87a 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:
@@ -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,42 @@ 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. This argument is added in mpv 0.38.0.
+
+ 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>]``
+ .. warning::
+
+ Since mpv 0.38.0, an insertion index argument is added as the third argument.
+ This breaks all existing uses of this command which make use of the argument
+ to include the list of options to be set while the file is playing. To address
+ this problem, the third argument now needs to be set to -1 if the fourth
+ argument needs to be used.
+
+``loadlist <url> [<flags> [<index>]]``
Load the given playlist file or URL (like ``--playlist``).
Second argument:
@@ -478,6 +517,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.
@@ -581,7 +640,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.
@@ -643,7 +702,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
@@ -672,7 +731,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
@@ -724,7 +783,11 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
Steps through the secondary subtitles.
``sub-seek <skip> <flags>``
- Seek to the next (skip set to 1) or the previous (skip set to -1) subtitle.
+ Change video and audio position such that the subtitle event after
+ ``<skip>`` subtitle events is displayed. For example, ``sub-seek 1`` skips
+ to the next subtitle, ``sub-seek -1`` skips to the previous subtitles, and
+ ``sub-seek 0`` seeks to the beginning of the current subtitle.
+
This is similar to ``sub-step``, except that it seeks video and audio
instead of adjusting the subtitle delay.
@@ -737,7 +800,7 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
For embedded subtitles (like with Matroska), this works only with subtitle
events that have already been displayed, or are within a short prefetch
- range.
+ range. See `Cache`_ for details on how to control the available prefetch range.
``print-text <text>``
Print text to stdout. The string can contain properties (see
@@ -746,7 +809,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
@@ -755,12 +818,12 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
<level>
The minimum OSD level to show the text at (see ``--osd-level``).
-``expand-text <string>``
+``expand-text <text>``
Property-expand the argument and return the expanded string. This can be
used only through the client API or from a script using
``mp.command_native``. (see `Property Expansion`_).
-``expand-path "<string>"``
+``expand-path "<text>"``
Expand a path's double-tilde placeholders into a platform-specific path.
As ``expand-text``, this can only be used through the client API or from
a script using ``mp.command_native``.
@@ -772,9 +835,36 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
This line of Lua would show the location of the user's mpv
configuration directory on the OSD.
+``normalize-path <filename>``
+ Return a canonical representation of the path ``filename`` by converting it
+ to an absolute path, removing consecutive slashes, removing ``.``
+ components, resolving ``..`` components, and converting slashes to
+ backslashes on Windows. Symlinks are not resolved unless the platform is
+ Unix-like and one of the path components is ``..``. If ``filename`` is a
+