command: add better runtime filter toggling method

Basically, see the example in input.rst.

This is better than the "old" vf-toggle method, because it doesn't
require the user to duplicate the filter string in mpv.conf and
input.conf.

Some aspects of this changes are untested, so enjoy your alpha testing.

3 files changed, 48 insertions, 24 deletions

diff --git a/DOCS/man/af.rst b/DOCS/man/af.rst
index 040b44cd64..9dff18ebbe 100644
--- a/DOCS/man/af.rst
+++ b/DOCS/man/af.rst
@@ -4,8 +4,8 @@ AUDIO FILTERS
 Audio filters allow you to modify the audio stream and its properties. The
 syntax is:
 
-``--af=<filter1[=parameter1:parameter2:...],filter2,...>``
-    Setup a chain of audio filters.
+``--af=...``
+    Setup a chain of audio filters. See ``--vf`` for the syntax.
 
 .. note::
 
@@ -15,27 +15,8 @@ syntax is:
     wrapper, which gives you access to most of libavfilter's filters. This
     includes all filters that have been ported from MPlayer to libavfilter.
 
-You can also set defaults for each filter. The defaults are applied before the
-normal filter parameters.
-
-``--af-defaults=<filter1[=parameter1:parameter2:...],filter2,...>``
-    Set defaults for each filter.
-
-Audio filters are managed in lists. There are a few commands to manage the
-filter list:
-
-``--af-add=<filter1[,filter2,...]>``
-    Appends the filters given as arguments to the filter list.
-
-``--af-pre=<filter1[,filter2,...]>``
-    Prepends the filters given as arguments to the filter list.
-
-``--af-del=<index1[,index2,...]>``
-    Deletes the filters at the given indexes. Index numbers start at 0,
-    negative numbers address the end of the list (-1 is the last).
-
-``--af-clr``
-    Completely empties the filter list.
+See ``--vf`` group of options for info on how ``--af-defaults``, ``--af-add``,
+``--af-pre``, ``--af-del``, ``--af-clr``, and possibly others work.
 
 Available filters are:
 
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index 9e578867cf..d252bb93a1 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -452,6 +452,9 @@ Input Commands that are Possibly Subject to Change
         (If several filters are passed to the command, this is done for
         each filter.)
 
+        A special variant is combining this with labels, and using ``@name:!``
+        as filter entry. This toggles the enable/disable flag.
+
     del
         Remove the given filters from the video chain. Unlike in the other
         cases, the second parameter is a comma separated list of filter names
@@ -487,6 +490,16 @@ Input Commands that are Possibly Subject to Change
         - ``b vf set ""`` remove all video filters on ``b``
         - ``c vf toggle lavfi=gradfun`` toggle debanding on ``c``
 
+    .. admonition:: Example how to toggle disabled filters at runtime
+
+        - Add something ``vf-add=@deband:!lavfi=[gradfun]`` to ``mpv.conf``. The
+          ``@deband:`` is the label, and ``deband`` is an arbitrary, user-given
+          name for this filter entry. The ``!`` before the filter name disables
+          the filter by default. Everything after this is the normal filter name
+          and the filter parameters.
+        - Add ``a vf toggle @deband:!`` to ``input.conf``. This toggles the
+          "disabled" flag for the filter identified with ``deband``.
+
 ``cycle-values ["!reverse"] <property> "<value1>" "<value2>" ...``
     Cycle through a list of values. Each invocation of the command will set the
     given property to the next value in the list. The command maintains an
diff --git a/DOCS/man/vf.rst b/DOCS/man/vf.rst
index 9da20942f6..a3f7ee6dab 100644
--- a/DOCS/man/vf.rst
+++ b/DOCS/man/vf.rst
@@ -5,7 +5,37 @@ Video filters allow you to modify the video stream and its properties. The
 syntax is:
 
 ``--vf=<filter1[=parameter1:parameter2:...],filter2,...>``
-    Setup a chain of video filters.
+    Setup a chain of video filters. This consists on the filter name, and an
+    option list of parameters after ``=``. The parameters are separated by
+    ``:`` (not ``,``, as that starts a new filter entry).
+
+    Before the filter name, a label can be specified with ``@name:``, where
+    name is an arbitrary user-given name, which identifies the filter. This
+    is only needed if you want to toggle the filter at runtime.
+
+    A ``!`` before the filter name means the filter is enabled by default. It
+    will be skipped on filter creation. This is also useful for runtime filter
+    toggling.
+
+    See the ``vf`` command (and ``toggle`` sub-command) for further explanations
+    and examples.
+
+    The general filter entry syntax is:
+
+        ``["@"<label-name>":"] ["!"] <filter-name> [ "=" <filter-parameter-list> ]``
+
+    and the ``filter-parameter-list``:
+
+        ``<filter-parameter> | <filter-parameter> "," <filter-parameter-list>``
+
+    and ``filter-parameter``:
+
+        ``( <param-name> "=" <param-value> ) | <param-value>``
+
+    ``param-value`` can further be quoted in ``[`` / ``]`` in case the value
+    contains characters like ``,`` or ``=``. This is used in particular with
+    the ``lavfi`` filter, which uses a very similar syntax as mpv (MPlayer
+    historically) to specify filters and their parameters.
 
 You can also set defaults for each filter. The defaults are applied before the
 normal filter parameters.