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

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(-)

On 2023-03-27 05:38 am, Stefano Sabatini wrote:
> 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
> -@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 .

Are they really interactive? Just a return code the other way, not 
exactly ChatGPT.

How about:

"Some filters allow modification of some or all of their parameters 
during execution via commands."

> +
> +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}.

Should mention ffmpeg.c keyboard interaction.

> +A command can be sent to a filtergraph by specifying the following parameters:
> +@table @option
> +
> +@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
> +
> +@item command
> +the name of the command defined in the filter
> +
> +@item arg
> +an optional argument specifying the option to set through the command
> +@end table
> +
> +Commands are shown as options and marked with the @code{T} flag on the output of
> +@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
> +@ref{eq}, @ref{colorkey} and @ref{despill}). In some cases it works (for example

This note in the general section won't help a user identify which 
filters are liable to make such changes via commands.
Such notes are best individually placed in the Commands subsection of 
filters which can change AVFrame format midway,
of which there are only a few.



> +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}.
>   
> +@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
>   
> +@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
>   
> +@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
>   
> +@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
>   
> +@anchor{zmq}
>   @section zmq, azmq
>   
>   Receive commands sent through a libzmq client, and forward them to

On date Monday 2023-03-27 10:54:59 +0530, Gyan Doshi wrote:
> 
> 
> On 2023-03-27 05:38 am, Stefano Sabatini wrote:
> > 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
> > -@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 .
> 
> Are they really interactive? Just a return code the other way, not exactly
> ChatGPT.
> 

> How about:
> 
> "Some filters allow modification of some or all of their parameters during
> execution via commands."

Works for me.

> 
> > +
> > +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}.
> 
> Should mention ffmpeg.c keyboard interaction.

I'd drop this as can be done as a second step (and I don't know ATM
how this works).

> > +A command can be sent to a filtergraph by specifying the following parameters:
> > +@table @option
> > +
> > +@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
> > +
> > +@item command
> > +the name of the command defined in the filter
> > +
> > +@item arg
> > +an optional argument specifying the option to set through the command
> > +@end table
> > +
> > +Commands are shown as options and marked with the @code{T} flag on the output of
> > +@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
> > +@ref{eq}, @ref{colorkey} and @ref{despill}). In some cases it works (for example
> 

> This note in the general section won't help a user identify which filters
> are liable to make such changes via commands.
> Such notes are best individually placed in the Commands subsection of
> filters which can change AVFrame format midway,
> of which there are only a few.

I moved this to the scale section, probably we should review what
filters are affected by this, but this is out of scope.

Thanks.