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

[Stefano Sabatini <stefasab@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 3573 bytes --]

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.

[-- Attachment #2: 0002-doc-filters-extend-section-about-commands-warn-about.patch --]
[-- Type: text/x-diff, Size: 4339 bytes --]

From 6e7a92a01409ce0b283f61ece24cb35c3b3012d4 Mon Sep 17 00:00:00 2001
From: Stefano Sabatini <stefasab@gmail.com>
Date: Mon, 27 Mar 2023 02:05:24 +0200
Subject: [PATCH 2/3] doc/filters: extend section about commands, warn about
 undesirable behaviors of scale options

Extend documentation about commands, and add a note to width/height
scale commands to warn users that it might fail when the chained
filter do not support mid-stream size changes.

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

diff --git a/doc/filters.texi b/doc/filters.texi
index 120fe6664a..c17faf7a41 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -356,11 +356,33 @@ 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 allow modification of some or all of their parameters during
+execution via commands.
+
+Commands to the filter can be sent to a target 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:
+@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.
 
 @anchor{framesync}
 @chapter Options for filters with several inputs (framesync)
@@ -9532,6 +9554,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
@@ -11450,6 +11473,7 @@ specified file.
 
 @end table
 
+@anchor{despill}
 @section despill
 
 Remove unwanted contamination of foreground colors, caused by reflected color of
@@ -12735,6 +12759,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.
 
@@ -20074,7 +20099,6 @@ Evaluate expressions for each incoming frame.
 
 Default value is @samp{init}.
 
-
 @item interl
 Set the interlacing mode. It accepts the following values:
 
@@ -20385,6 +20409,14 @@ The command accepts the same syntax of the corresponding option.
 
 If the specified expression is not valid, it is kept at its current
 value.
+
+Keep in mind that this command, by changing the output video size, might change
+some chained filters configuration causing unexpected behavior. 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 the
+output of @ref{scale} can be used as the second input of @ref{overlay}), but in
+most other cases it would fail.
+
 @end table
 
 @section scale_cuda
@@ -29084,6 +29116,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.
@@ -30830,6 +30863,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
-- 
2.25.1


[-- Attachment #3: Type: text/plain, Size: 251 bytes --]

_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".