[FFmpeg-devel] [PATCH] doc/filters: extend section about command, warn about undesirable behaviors

[Stefano Sabatini]

Extend documentation about commands, and add a note to warn users in
case of commands which might fail in special cases, based on a report
by Michael Koch.

Fix trac issue:
http://trac.ffmpeg.org/ticket/8987
---
 doc/filters.texi | 45 ++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 40 insertions(+), 5 deletions(-)

diff --git a/doc/filters.texi b/doc/filters.texi
index 4449998ba4..3db7280bb5 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -327,11 +327,41 @@ See @code{ffmpeg -filters} to view which filters have timeline support.
 @anchor{commands}
 @chapter Changing options at runtime with a command
 
-Some options can be changed during the operation of the filter using
-a command. These options are marked 'T' on the output of
- at command{ffmpeg} @option{-h filter=<name of filter>}.
-The name of the command is the name of the option and the argument is
-the new value.
+Some filters accepts interactive commands which can be sent to filters to
+interactively change their behavior .
+
+When a filter supports commands, it is possible to send a command to the filter,
+either programmatically through the @code{avfilter_process_command()} function
+defined in @file{avfilter.h}, or through dedicated filters such as @ref{sendcmd}
+or @ref{zmq}.
+
+A command can be sent to a filtergraph by specifying the following parameters:
+ at table @option
+
+ at item target
+a filter target, is specified as the unique filter name in the filterchain, or
+as the filter class name followed by "@@@var{id}", where @var{id} is the unique
+filter identifier assigned to the filter in the filtergraph specification
+
+ at item command
+the name of the command defined in the filter
+
+ at item arg
+an optional argument specifying the option to set through the command
+ at end table
+
+Commands are shown as options and marked with the @code{T} flag on the output of
+ at command{ffmpeg} @option{-h filter=<name of filter>}. The name of the
+corresponding option is the name of the command and the argument is the value
+set through the command.
+
+Keep in mind that some commands might change some filters configuration causing
+unexpected behavior. For example, it is possible to send the @command{width}
+command to the @ref{scale} filter for changing the size of a video stream. But
+changing the size mid-stream is not supported by many other filters (for example
+ at ref{eq}, @ref{colorkey} and @ref{despill}). In some cases it works (for example
+the output of @ref{scale} can be used as the second input of @ref{overlay}), but
+in most other cases it would fail.
 
 @anchor{framesync}
 @chapter Options for filters with several inputs (framesync)
@@ -9503,6 +9533,7 @@ Allowed range is from 0.0 to 1.0.
 
 This filter supports the all above options as @ref{commands}.
 
+ at anchor{colorkey}
 @section colorkey
 RGB colorspace color keying.
 This filter operates on 8-bit RGB format frames by setting the alpha component of each pixel
@@ -11421,6 +11452,7 @@ specified file.
 
 @end table
 
+ at anchor{despill}
 @section despill
 
 Remove unwanted contamination of foreground colors, caused by reflected color of
@@ -12704,6 +12736,7 @@ Set the scaling dimension: @code{2} for @code{2xEPX}, @code{3} for
 Default is @code{3}.
 @end table
 
+ at anchor{eq}
 @section eq
 Set brightness, contrast, saturation and approximate gamma adjustment.
 
@@ -29016,6 +29049,7 @@ ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=co
 @end example
 @end itemize
 
+ at anchor{sendcmd}
 @section sendcmd, asendcmd
 
 Send commands to filters in the filtergraph.
@@ -30762,6 +30796,7 @@ ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
 @end example
 @end itemize
 
+ at anchor{zmq}
 @section zmq, azmq
 
 Receive commands sent through a libzmq client, and forward them to
-- 
2.25.1