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

[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
-@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:
+@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
+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
-- 
2.25.1

_______________________________________________
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".

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

[Gyan Doshi]

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

_______________________________________________
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".

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

[Stefano Sabatini]

[-- 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".