summaryrefslogtreecommitdiffstats
path: root/DOCS
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2017-06-30 16:39:36 +0200
committerwm4 <wm4@nowhere>2017-06-30 16:39:36 +0200
commit91583fccac85880ad2199f50463c095560791d56 (patch)
treec0e18c2755edf4bd3f9255975cbe1d8f1f1e97f7 /DOCS
parentc1f46dbbe9a9b2d1ae6694118244bea8859ab2f0 (diff)
downloadmpv-91583fccac85880ad2199f50463c095560791d56.tar.bz2
mpv-91583fccac85880ad2199f50463c095560791d56.tar.xz
options: change path list options, and document list options
The changes to path list options is basically getting rid of the need to pass multiple paths to a single option. Instead, you can use the option multiple times. The old behavior can be used by using the -set suffix with the option. Change some options to path lists. For example --script is now append by default, and if you use --script-set, you need to use ":"/";" as separator instead of ",". --sub-paths/--audio-file-paths is a deprecated alias now, and will break if the user tries to pass multiple paths to it. I'm assuming that if these are used, most users will pass only 1 path anyway. --opengl-shaders has more compatibility handling, since it's probably rather common that users pass multiple options to it. Also document all that in the manpage. I'll probably regret this later, as it somewhat increases the complexity of the option parser, rather than increasing it.
Diffstat (limited to 'DOCS')
-rw-r--r--DOCS/interface-changes.rst8
-rw-r--r--DOCS/man/mpv.rst29
-rw-r--r--DOCS/man/options.rst34
3 files changed, 63 insertions, 8 deletions
diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst
index 93894f2404..a678e0d528 100644
--- a/DOCS/interface-changes.rst
+++ b/DOCS/interface-changes.rst
@@ -38,6 +38,14 @@ Interface changes
- --field-dominance is deprecated (use --vf=setfield=bff or tff)
- --really-quiet subtle behavior change
- the deprecated handling of setting "no-" options via client API is dropped
+ - the following options change to append-by-default (and possibly separator):
+ --script
+ --audio-file-paths
+ --sub-paths
+ also, the following options are deprecated:
+ --audio-file-paths => --audio-file-path
+ --sub-paths => --sub-file-path
+ --opengl-shaders => --opengl-shader
--- mpv 0.25.0 ---
- remove opengl-cb dxva2 dummy hwdec interop
(see git "vo_opengl: remove dxva2 dummy hwdec backend")
diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst
index 1da99715dc..9befe435da 100644
--- a/DOCS/man/mpv.rst
+++ b/DOCS/man/mpv.rst
@@ -416,6 +416,35 @@ file stops playing. If option ``--c`` is changed during playback of
file-local options. The option ``--a`` is never reset here.
+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``.
+
+Options for filenames do not use ``,`` as separator, but ``:`` (Unix) or ``;``
+(Windows).
+
+============= ===============================================
+Suffix Meaning
+============= ===============================================
+-add Append 1 or more items
+-add-str 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
+============= ===============================================
+
+Although some operations allow specifiying multiple ``,``-separated items, using
+this is strongly discouraged and deprecated, except for ``-set``.
+
+Without suffix, the action taken is normally ``-set``.
+
+Some options (like ``--sub-file``, ``--audio-file``, ``--opengl-shader``) append
+one file per option use. Their default action is ``-add-str``.
+
Playing DVDs
------------
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index 2be7de2195..5b2e838243 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -1367,6 +1367,8 @@ Audio
option will add a new audio track. The details are similar to how
``--sub-file`` works.
+ This is a list option. See `List Options`_ for details.
+
``--audio-format=<format>``
Select the sample format used for output from the audio filter layer to
the sound card. The values that ``<format>`` can adopt are listed below in
@@ -1433,11 +1435,14 @@ Audio
:no: Don't automatically load external audio files.
:exact: Load the media filename with audio file extension (default).
:fuzzy: Load all audio files containing media filename.
- :all: Load all audio files in the current and ``--audio-file-paths``
+ :all: Load all audio files in the current and ``--audio-file-path``
directories.
``--audio-file-paths=<path1:path2:...>``
- Equivalent to ``--sub-paths`` option, but for auto-loaded audio files.
+ Deprecated, use ``--audio-file-path``.
+
+``--audio-file-path=path1>``
+ Equivalent to ``--sub-file-path`` option, but for auto-loaded audio files.
``--audio-client-name=<name>``
The application name the player reports to the audio API. Can be useful
@@ -1512,6 +1517,8 @@ 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.)
+ This is a list option. See `List Options`_ for details.
+
``--secondary-sid=<ID|auto|no>``
Select a secondary subtitle stream. This is similar to ``--sid``. If a
secondary subtitle is selected, it will be rendered as toptitle (i.e. on
@@ -1786,7 +1793,7 @@ Subtitles
:no: Don't automatically load external subtitle files.
:exact: Load the media filename with subtitle file extension (default).
:fuzzy: Load all subs containing media filename.
- :all: Load all subs in the current and ``--sub-paths`` directories.
+ :all: Load all subs in the current and ``--sub-file-path`` directories.
``--sub-codepage=<codepage>``
You can use this option to specify the subtitle codepage. uchardet will be
@@ -1854,6 +1861,9 @@ Subtitles
Never applied to text subtitles.
``--sub-paths=<path1:path2:...>``
+ Deprecated, use ``--sub-file-path``.
+
+``--sub-file-path=path``
Specify extra directories to search for subtitles matching the video.
Multiple directories can be separated by ":" (";" on Windows).
Paths can be relative or absolute. Relative paths are interpreted relative
@@ -1864,15 +1874,16 @@ Subtitles
.. admonition:: Example
Assuming that ``/path/to/video/video.avi`` is played and
- ``--sub-paths=sub:subtitles:/tmp/subs`` is specified, mpv searches for
- subtitle files in these directories:
+ ``--sub-file-path=sub --sub-file-path=subtitles`` is specified, mpv
+ searches for subtitle files in these directories:
- ``/path/to/video/``
- ``/path/to/video/sub/``
- ``/path/to/video/subtitles/``
- - ``/tmp/subs/``
- the ``sub`` configuration subdirectory (usually ``~/.config/mpv/sub/``)
+ This is a 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
them.
@@ -4156,10 +4167,11 @@ The following video options are currently all specific to ``--vo=opengl`` and
results, as can missing or incorrect display FPS information (see
``--display-fps``).
-``--opengl-shaders=<files>``
+``--opengl-shader=<file>``
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.
+ and access all previous intermediate textures. Each use of the option will
+ add another file to the internal list of shaders (see `List Options`_).
.. admonition:: Warning
@@ -4316,6 +4328,10 @@ The following video options are currently all specific to ``--vo=opengl`` and
pass. When overwriting a texture marked ``fixed``, the WIDTH, HEIGHT and
OFFSET must be left at their default values.
+``--opengl-shaders=<files>``
+ Deprecated option for ``--opengl-shader``. Command line parsing behaves
+ slightly diffent. ``--opengl-shader-set`` gives exactly the same behavior.
+
``--deband``
Enable the debanding algorithm. This greatly reduces the amount of visible
banding, blocking and other quantization artifacts, at the expensive of
@@ -4999,6 +5015,8 @@ Miscellaneous
does not cause default stream selection over the "proper" file. This makes
it slightly less intrusive.
+ This is a list option. See `List Options`_ for details.
+
``--autoload-files=<yes|no>``
Automatically load/select external files (default: yes).