summaryrefslogtreecommitdiffstats
path: root/DOCS
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2019-12-18 05:11:57 +0100
committerwm4 <wm4@nowhere>2019-12-18 05:32:02 +0100
commitd3e3bd43074ddd8f4c8829a7454b9f855454f462 (patch)
tree9a0b70af29c39231ee2711023e93d5f2ef1e2b4d /DOCS
parentbd96b97170c3332d84381c88e92bbe2a169fae35 (diff)
downloadmpv-d3e3bd43074ddd8f4c8829a7454b9f855454f462.tar.bz2
mpv-d3e3bd43074ddd8f4c8829a7454b9f855454f462.tar.xz
options: increase consistency between list options and document them
Whenever I deal with this, I have to look at the code to make sense of this. And beyond that, there are some strange inconsistencies. (I think this code is cursed. It always was, and maybe always will be.) Although the manpage claimed that using multiple items for -add etc. is deprecated, string list options didn't warn against it. So add the warning, and add something in the changelog (even though nobody will ever read this). The manpage mentioned --vf-append, but this didn't even exist. So add it, I guess. We encourage using -append for the other option types, so for consistency, it should work on filter options. (And I already tricked me into believing it existed when I mentioned it in the manpage.) Make the "operations" table separate for all option types, and mention the option type on every single of the top-level list options.
Diffstat (limited to 'DOCS')
-rw-r--r--DOCS/interface-changes.rst4
-rw-r--r--DOCS/man/encode.rst13
-rw-r--r--DOCS/man/mpv.rst89
-rw-r--r--DOCS/man/options.rst50
-rw-r--r--DOCS/man/vf.rst3
5 files changed, 129 insertions, 30 deletions
diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst
index f12e6ed54a..8926d63f08 100644
--- a/DOCS/interface-changes.rst
+++ b/DOCS/interface-changes.rst
@@ -71,6 +71,10 @@ Interface changes
instead of the actual size of the window. The new "current-window-scale"
property needs to be queried to read the value as indicated by the current
window size. This is a breaking change.
+ - explicitly deprecate passing more than 1 item to "-add" suffix in key/value
+ options (for example --script-opts-add). This was actually always
+ deprecated, like with other list options, but the option parser did not
+ print a warning in this particular case.
--- mpv 0.30.0 ---
- add `--d3d11-output-format` to enable explicit selection of a D3D11
swap chain format.
diff --git a/DOCS/man/encode.rst b/DOCS/man/encode.rst
index 4c885ea168..e897a342cf 100644
--- a/DOCS/man/encode.rst
+++ b/DOCS/man/encode.rst
@@ -15,8 +15,7 @@ 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.
@@ -41,8 +40,7 @@ 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.
@@ -74,8 +72,7 @@ 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.
@@ -103,6 +100,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 +111,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/mpv.rst b/DOCS/man/mpv.rst
index e41e992072..eaced80082 100644
--- a/DOCS/man/mpv.rst
+++ b/DOCS/man/mpv.rst
@@ -472,37 +472,92 @@ List Options
------------
Some options which store lists of option values can have action suffixes. For
-example, you can set a ``,``-separated list of filters with ``--vf``, but the
-option also allows you to append filters with ``--vf-append``.
+example, the ``--display-tags`` option takes a ``,``-separated list of tags, but
+the option also allows you to append a single tag with ``--display-tags-append``,
+and the tag name can for example contain a literal ``,`` without the need for
+escaping.
-Options for filenames do not use ``,`` as separator, but ``:`` (Unix) or ``;``
-(Windows).
+String list and path list options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+String lists are separated by ``,``. The strings are not parsed or interpreted
+by the option system itself. However, most
+
+Path or file list options use ``:`` (Unix) or ``;`` (Windows) as separator,
+instead of ``,``.
+
+They support the following operations:
============= ===============================================
Suffix Meaning
============= ===============================================
--add Append 1 or more items (may become alias for -append)
--append Append single item (avoids need for escaping)
--clr Clear the option
--del Delete an existing item by integer index
--pre Prepend 1 or more items
--set Set a list of items
--toggle Append an item, or remove if if it already exists
+-set Set a list of items (using the list separator, interprets escapes)
+-append Append single item (does not interpret escapes)
+-add Append 1 or more items (same syntax as -set)
+-pre Prepend 1 or more items (same syntax as -set)
+-clr Clear the option (remove all items)
+-del Delete 1 or more items by integer index
+-toggle Append an item, or remove if if it already exists (no escapes)
============= ===============================================
-Although some operations allow specifying multiple ``,``-separated items, using
-this is strongly discouraged and deprecated, except for ``-set``.
+``-append`` is meant as a simple way to append a single item without having
+to escape the argument (you may still need to escape on the shell level).
+
+Key/value list options
+~~~~~~~~~~~~~~~~~~~~~~
+
+A key/value list is a list of key/value string pairs. In programming languages,
+this type of data structure is often called a map or a dictionary. The order
+normally does not matter, although in some cases the order might matter.
+
+They support the following operations:
+
+============= ===============================================
+Suffix Meaning
+============= ===============================================
+-set Set a list of items (using ``,`` as separator)
+-append Append a single item (escapes for the key, no escapes for the value)
+-add Append 1 or more items (same syntax as -set)
+============= ===============================================
-Without suffix, the action taken is normally ``-set``.
+Filter options
+~~~~~~~~~~~~~~
+
+This is a very complex option type for the ``--af`` and ``--vf`` options only.
+They often require complicated escaping. See `VIDEO FILTERS`_ for details. They
+support the following operations:
+
+============= ===============================================
+Suffix Meaning
+============= ===============================================
+-set Set a list of filters (using ``,`` as separator)
+-append Append single filter
+-add Append 1 or more filters (same syntax as -set)
+-pre Prepend 1 or more filters (same syntax as -set)
+-clr Clear the option (remove all filters)
+-del Delete 1 or more filters by integer index or filter label
+-toggle Append a filter, or remove if if it already exists
+-help Pseudo operation that prints a help text to the terminal
+============= ===============================================
+
+General
+~~~~~~~
+
+Without suffix, the operation used is normally ``-set``.
+
+Although some operations allow specifying multiple items, using this is strongly
+discouraged and deprecated, except for ``-set``. There is a chance that
+operations like ``-add`` and ``-pre`` will work like ``-append`` and accept a
+single, unescaped item only (so the ``,`` separator will not be interpreted and
+is passed on as part of the value).
Some options (like ``--sub-file``, ``--audio-file``, ``--glsl-shader``) are
aliases for the proper option with ``-append`` action. For example,
``--sub-file`` is an alias for ``--sub-files-append``.
-Some options only support a subset of the above.
-
Options of this type can be changed at runtime using the ``change-list``
-command, which takes the suffix as separate operation parameter.
+command, which takes the suffix (without the ``-``) as separate operation
+parameter.
CONFIGURATION FILES
===================
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index be9177b09a..1af4b81bc8 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -10,6 +10,8 @@ Track Selection
language codes, Matroska, MPEG-TS and NUT use ISO 639-2 three-letter
language codes, while OGM uses a free-form identifier. See also ``--aid``.
+ This is a string list option. See `List Options`_ for details.
+
.. admonition:: Examples
- ``mpv dvd://1 --alang=hu,en`` chooses the Hungarian language track
@@ -23,6 +25,8 @@ Track Selection
language codes, Matroska uses ISO 639-2 three letter language codes while
OGM uses a free-form identifier. See also ``--sid``.
+ This is a string list option. See `List Options`_ for details.
+
.. admonition:: Examples
- ``mpv dvd://1 --slang=hu,en`` chooses the Hungarian subtitle track on
@@ -33,6 +37,8 @@ Track Selection
``--vlang=<...>``
Equivalent to ``--alang`` and ``--slang``, for video tracks.
+ This is a string list option. See `List Options`_ for details.
+
``--aid=<ID|auto|no>``
Select audio track. ``auto`` selects the default, ``no`` disables audio.
See also ``--alang``. mpv normally prints available audio tracks on the
@@ -700,11 +706,15 @@ Program Behavior
Load a Lua script. The second option allows you to load multiple scripts by
separating them with the path separator (``:`` on Unix, ``;`` on Windows).
+ ``--scripts`` is a path list option. See `List Options`_ for details.
+
``--script-opts=key1=value1,key2=value2,...``
Set options for scripts. A script can query an option by key. If an
option is used and what semantics the option value has depends entirely on
the loaded scripts. Values not claimed by any scripts are ignored.
+ This is a key/value list option. See `List Options`_ for details.
+
``--merge-files``
Pretend that all files passed to mpv are concatenated into a single, big
file. This uses timeline/EDL support internally.
@@ -744,6 +754,8 @@ Program Behavior
The special name ``all`` resets as many options as possible.
+ This is a string list option. See `List Options`_ for details.
+
.. admonition:: Examples
- ``--reset-on-next-file=pause``
@@ -835,6 +847,8 @@ Program Behavior
information to mpv. Take note that SOCKS proxies aren't supported and
https URLs also bypass the proxy. This is a limitation in FFmpeg.
+ This is a key/value list option. See `List Options`_ for details.
+
.. admonition:: Example
- ``--ytdl-raw-options=username=user,password=pass``
@@ -1453,6 +1467,8 @@ Video
mechanism, like ``bug``, ``gray``, ``idct``, ``ec``, ``vismv``,
``skip_top`` (was ``st``), ``skip_bottom`` (was ``sb``), ``debug``.
+ This is a key/value list option. See `List Options`_ for details.
+
.. admonition:: Example
``--vd-lavc-o=debug=pict``
@@ -1712,6 +1728,8 @@ Audio
unneeded and pass all unknown options through the AVOption system is
welcome. A full list of AVOptions can be found in the FFmpeg manual.
+ This is a key/value list option. See `List Options`_ for details.
+
``--ad-spdif-dtshd=<yes|no>``, ``--dtshd``, ``--no-dtshd``
If DTS is passed through, use DTS-HD.
@@ -1799,7 +1817,7 @@ Audio
``--audio-files=<files>``
Play audio from an external file while viewing a video.
- This is a list option. See `List Options`_ for details.
+ This is a path list option. See `List Options`_ for details.
``--audio-file=<file>``
CLI/config file only alias for ``--audio-files-append``. Each use of this
@@ -1880,6 +1898,8 @@ Audio
``--audio-file-paths=<path1:path2:...>``
Equivalent to ``--sub-file-paths`` option, but for auto-loaded audio files.
+ This is a path list option. See `List Options`_ for details.
+
``--audio-client-name=<name>``
The application name the player reports to the audio API. Can be useful
if you want to force a different audio profile (e.g. with PulseAudio),
@@ -1953,7 +1973,7 @@ Subtitles
and ``--secondary-sid`` to select the second index. (The index is printed
on the terminal output after the ``--sid=`` in the list of streams.)
- ``--sub-files`` is a list option (see `List Options`_ for details), and
+ ``--sub-files`` is a path list option (see `List Options`_ for details), and
can take multiple file names separated by ``:`` (Unix) or ``;`` (Windows),
while ``--sub-file`` takes a single filename, but can be used multiple
times to add multiple files. Technically, ``--sub-file`` is a CLI/config
@@ -2045,6 +2065,8 @@ Subtitles
``--sub-ass-force-style=<[Style.]Param=Value[,...]>``
Override some style or script info parameters.
+ This is a string list option. See `List Options`_ for details.
+
.. admonition:: Examples
- ``--sub-ass-force-style=FontName=Arial,Default.Bold=1``
@@ -2325,7 +2347,7 @@ Subtitles
- ``/path/to/video/subtitles/``
- the ``sub`` configuration subdirectory (usually ``~/.config/mpv/sub/``)
- This is a list option. See `List Options`_ for details.
+ This is a path list option. See `List Options`_ for details.
``--sub-visibility``, ``--no-sub-visibility``
Can be used to disable display of subtitles, but still select and decode
@@ -3128,6 +3150,8 @@ Demuxer
be found in the FFmpeg manual. Note that some options may conflict
with mpv options.
+ This is a key/value list option. See `List Options`_ for details.
+
.. admonition:: Example
``--demuxer-lavf-o=fflags=+ignidx``
@@ -4016,6 +4040,8 @@ It also sets the defaults for the ``lavrresample`` audio filter.
Set AVOptions on the SwrContext or AVAudioResampleContext. These should
be documented by FFmpeg or Libav.
+ This is a key/value list option. See `List Options`_ for details.
+
Terminal
--------
@@ -4279,6 +4305,8 @@ Network
``--http-header-fields=<field1,field2>``
Set custom HTTP fields when accessing HTTP stream.
+ This is a string list option. See `List Options`_ for details.
+
.. admonition:: Example
::
@@ -4943,11 +4971,15 @@ The following video options are currently all specific to ``--vo=gpu`` and
This option is deprecated, since there is only one reasonable value.
It may be removed in the future.
-``--glsl-shaders=<file-list>``
+``--glsl-shader=<file>``, ``--glsl-shaders=<file-list>``
Custom GLSL hooks. These are a flexible way to add custom fragment shaders,
which can be injected at almost arbitrary points in the rendering pipeline,
- and access all previous intermediate textures. Each use of the option will
- add another file to the internal list of shaders (see `List Options`_).
+ and access all previous intermediate textures.
+
+ Each use of the ``--glsl-shader`` option will add another file to the
+ internal list of shaders, while ``--glsl-shaders`` takes a list of files,
+ and overwrites the internal list with it. The latter is a path list option
+ (see `List Options`_ for details).
.. admonition:: Warning
@@ -5933,6 +5965,8 @@ Miscellaneous
The default includes a common list of tags, call mpv with ``--list-options``
to see it.
+ This is a string list option. See `List Options`_ for details.
+
``--mc=<seconds/frame>``
Maximum A-V sync correction per frame (in seconds)
@@ -6089,6 +6123,8 @@ Miscellaneous
other options such as e.g. user agent are not available with all protocols,
and printing errors for unknown options would end up being too noisy.)
+ This is a key/value list option. See `List Options`_ for details.
+
``--vo-mmcss-profile=<name>``
(Windows only.)
Set the MMCSS profile for the video renderer thread (default: ``Playback``).
@@ -6119,7 +6155,7 @@ Miscellaneous
it slightly less intrusive. (In mpv 0.28.0 and before, this was not quite
strictly enforced.)
- This is a list option. See `List Options`_ for details.
+ This is a path list option. See `List Options`_ for details.
``--external-file=<file>``
CLI/config file only alias for ``--external-files-append``. Each use of this
diff --git a/DOCS/man/vf.rst b/DOCS/man/vf.rst
index 40994dd652..a9288d7a93 100644
--- a/DOCS/man/vf.rst
+++ b/DOCS/man/vf.rst
@@ -85,6 +85,9 @@ libavfilter bridge.
Video filters are managed in lists. There are a few commands to manage the
filter list.
+``--vf-append=filter``
+ Appends the filter given as arguments to the filter list.
+
``--vf-add=filter``
Appends the filter given as arguments to the filter list. (Passing multiple
filters is currently still possible, but deprecated.)