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

[Stefano Sabatini]

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

> 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.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0002-doc-filters-extend-section-about-commands-warn-about.patch
Type: text/x-diff
Size: 4340 bytes
Desc: not available
URL: <https://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20230329/55c5d296/attachment.patch>