[FFmpeg-devel] [PATCH 1/3] doc/filters/drawtext: clarify meaning of strftime format string

[FFmpeg-devel] [PATCH 1/3] doc/filters/drawtext: clarify meaning of strftime format string

[Stefano Sabatini]

Also clarify what should be used instead of the strftime expansion mode.
---
 doc/filters.texi | 28 +++++++++++++++-------------
 1 file changed, 15 insertions(+), 13 deletions(-)

diff --git a/doc/filters.texi b/doc/filters.texi
index 4449998ba4..b397100ff8 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -12103,13 +12103,12 @@ The default value of @var{bordercolor} is "black".
 
 @item expansion
 Select how the @var{text} is expanded. Can be either @code{none},
-@code{strftime} (deprecated) or
-@code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section
-below for details.
+@code{strftime} (deprecated) or @code{normal} (default). See the
+@ref{drawtext_expansion, Text expansion} section below for details.
 
 @item basetime
 Set a start time for the count. Value is in microseconds. Only applied
-in the deprecated strftime expansion mode. To emulate in normal expansion
+in the deprecated @code{strftime} expansion mode. To emulate in normal expansion
 mode use the @code{pts} function, supplying the start time (in seconds)
 as the second argument.
 
@@ -12340,10 +12339,12 @@ The current packet's size (in bytes).
 @anchor{drawtext_expansion}
 @subsection Text expansion
 
-If @option{expansion} is set to @code{strftime},
-the filter recognizes strftime() sequences in the provided text and
-expands them accordingly. Check the documentation of strftime(). This
-feature is deprecated.
+If @option{expansion} is set to @code{strftime}, the filter recognizes
+sequences accepted by the @code{strftime} C function in the provided
+text and expands them accordingly. Check the documentation of
+@code{strftime}. This feature is deprecated in favor of @code{normal}
+expansion with the @code{gmtime} or @code{localtime} expansion
+functions.
 
 If @option{expansion} is set to @code{none}, the text is printed verbatim.
 
@@ -12390,13 +12391,13 @@ It can be used to add padding with zeros from the left.
 
 @item gmtime
 The time at which the filter is running, expressed in UTC.
-It can accept an argument: a strftime() format string.
+It can accept an argument: a @code{strftime} C function format string.
 The format string is extended to support the variable @var{%[1-6]N}
 which prints fractions of the second with optionally specified number of digits.
 
 @item localtime
 The time at which the filter is running, expressed in the local time zone.
-It can accept an argument: a strftime() format string.
+It can accept an argument: a @code{strftime} C function format string.
 The format string is extended to support the variable @var{%[1-6]N}
 which prints fractions of the second with optionally specified number of digits.
 
@@ -12438,8 +12439,8 @@ If the format is set to @code{hms}, a third argument @code{24HH} may be
 supplied to present the hour part of the formatted timestamp in 24h format
 (00-23).
 
-If the format is set to @code{localtime} or @code{gmtime},
-a third argument may be supplied: a strftime() format string.
+If the format is set to @code{localtime} or @code{gmtime}, a third
+argument may be supplied: a @code{strftime} C function format string.
 By default, @var{YYYY-MM-DD HH:MM:SS} format will be used.
 @end table
 
@@ -12543,7 +12544,8 @@ drawtext="text='Test Text': fontsize=h/30: x=(w-text_w)/2: y=(h-text_h*2)"
 @end example
 
 @item
-Print the date of a real-time encoding (see strftime(3)):
+Print the date of a real-time encoding (see documentation for the
+@code{strftime} C function):
 @example
 drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}'
 @end example
-- 
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".

[FFmpeg-devel] [PATCH 2/3] doc/filters: propose solutions to avoid shell escaping

[Stefano Sabatini]

Reference drawtext textfile option and ffmpeg -filter_complext_script
and -filter_script as solutils to avoid shell escaping.

Address issue:
http://trac.ffmpeg.org/ticket/9008
---
 doc/ffmpeg.texi  |  2 ++
 doc/filters.texi | 22 +++++++++++++++++-----
 2 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi
index 6baf51bf0a..adfc2726ff 100644
--- a/doc/ffmpeg.texi
+++ b/doc/ffmpeg.texi
@@ -769,6 +769,7 @@ syntax.
 See the @ref{filter_complex_option,,-filter_complex option} if you
 want to create filtergraphs with multiple inputs and/or outputs.
 
+@anchor{filter_script option}
 @item -filter_script[:@var{stream_specifier}] @var{filename} (@emph{output,per-stream})
 This option is similar to @option{-filter}, the only difference is that its
 argument is the name of the file from which a filtergraph description is to be
@@ -1978,6 +1979,7 @@ The default is the number of available CPUs.
 Define a complex filtergraph, i.e. one with arbitrary number of inputs and/or
 outputs. Equivalent to @option{-filter_complex}.
 
+@anchor{filter_complex_script option}
 @item -filter_complex_script @var{filename} (@emph{global})
 This option is similar to @option{-filter_complex}, the only difference is that
 its argument is the name of the file from which a complex filtergraph
diff --git a/doc/filters.texi b/doc/filters.texi
index b397100ff8..1c9d523340 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -282,6 +282,18 @@ previous string will finally result in:
 -vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"
 @end example
 
+In order to avoid cumbersome escaping when using a commandline tool accepting a
+filter specification as input, it is advisable to avoid direct inclusion of the
+filter or options specification in the shell.
+
+For example, in case of the @ref{drawtext,,drawtext filter}, you might prefer to
+use the @option{textfile} option in place of @option{text} to specify the text
+to render.
+
+When using the @command{ffmpeg} tool, you might consider to use the
+@ref{filter_script option,,-filter_script option,ffmpeg} or
+@ref{filter_complex_script option,,-filter_complex_script option,ffmpeg}.
+
 @chapter Timeline editing
 
 Some filters support a generic @option{enable} option. For the filters
@@ -12359,11 +12371,11 @@ braces is a function name, possibly followed by arguments separated by ':'.
 If the arguments contain special characters or delimiters (':' or '@}'),
 they should be escaped.
 
-Note that they probably must also be escaped as the value for the
-@option{text} option in the filter argument string and as the filter
-argument in the filtergraph description, and possibly also for the shell,
-that makes up to four levels of escaping; using a text file avoids these
-problems.
+Note that they probably must also be escaped as the value for the @option{text}
+option in the filter argument string and as the filter argument in the
+filtergraph description, and possibly also for the shell, that makes up to four
+levels of escaping; using a text file with the @option{textfile} option avoids
+these problems.
 
 The following functions are available:
 
-- 
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".

[FFmpeg-devel] [PATCH 3/3] doc/filters: mentions that whitespaces are ignored in the filtergraph specification

[Stefano Sabatini]

Also provide example showing how to use this feature to improve filtergraph
readability.

Address issue:
http://trac.ffmpeg.org/ticket/8115
---
 doc/filters.texi | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/doc/filters.texi b/doc/filters.texi
index 1c9d523340..889de8b11a 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -214,6 +214,23 @@ In a complete filterchain all the unlabelled filter input and output
 pads must be connected. A filtergraph is considered valid if all the
 filter input and output pads of all the filterchains are connected.
 
+Leading and trailing whitespaces (space, tabs, or line feeds) separating tokens
+in the filtergraph specification are ignored. This means that the filtergraph
+can be expressed using empty lines and spaces to improve redability.
+
+For example, the filtergraph:
+@example
+testsrc,split[L1],hflip[L2];[L1][L2] hstack
+@end example
+
+can be represented as:
+@example
+testsrc,
+split [L1], hflip [L2];
+
+[L1][L2] hstack
+@end example
+
 Libavfilter will automatically insert @ref{scale} filters where format
 conversion is required. It is possible to specify swscale flags
 for those automatically inserted scalers by prepending
-- 
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 2/3] doc/filters: propose solutions to avoid shell escaping

[Gyan Doshi]

On 2023-03-26 11:04 pm, Stefano Sabatini wrote:
> Reference drawtext textfile option and ffmpeg -filter_complext_script
> and -filter_script as solutils to avoid shell escaping.

Typos:  `-filter_complext_script` and `solutils`.

Rest: LGTM.

Regards,
Gyan

>
> Address issue:
> http://trac.ffmpeg.org/ticket/9008
> ---
>   doc/ffmpeg.texi  |  2 ++
>   doc/filters.texi | 22 +++++++++++++++++-----
>   2 files changed, 19 insertions(+), 5 deletions(-)
>
> diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi
> index 6baf51bf0a..adfc2726ff 100644
> --- a/doc/ffmpeg.texi
> +++ b/doc/ffmpeg.texi
> @@ -769,6 +769,7 @@ syntax.
>   See the @ref{filter_complex_option,,-filter_complex option} if you
>   want to create filtergraphs with multiple inputs and/or outputs.
>   
> +@anchor{filter_script option}
>   @item -filter_script[:@var{stream_specifier}] @var{filename} (@emph{output,per-stream})
>   This option is similar to @option{-filter}, the only difference is that its
>   argument is the name of the file from which a filtergraph description is to be
> @@ -1978,6 +1979,7 @@ The default is the number of available CPUs.
>   Define a complex filtergraph, i.e. one with arbitrary number of inputs and/or
>   outputs. Equivalent to @option{-filter_complex}.
>   
> +@anchor{filter_complex_script option}
>   @item -filter_complex_script @var{filename} (@emph{global})
>   This option is similar to @option{-filter_complex}, the only difference is that
>   its argument is the name of the file from which a complex filtergraph
> diff --git a/doc/filters.texi b/doc/filters.texi
> index b397100ff8..1c9d523340 100644
> --- a/doc/filters.texi
> +++ b/doc/filters.texi
> @@ -282,6 +282,18 @@ previous string will finally result in:
>   -vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"
>   @end example
>   
> +In order to avoid cumbersome escaping when using a commandline tool accepting a
> +filter specification as input, it is advisable to avoid direct inclusion of the
> +filter or options specification in the shell.
> +
> +For example, in case of the @ref{drawtext,,drawtext filter}, you might prefer to
> +use the @option{textfile} option in place of @option{text} to specify the text
> +to render.
> +
> +When using the @command{ffmpeg} tool, you might consider to use the
> +@ref{filter_script option,,-filter_script option,ffmpeg} or
> +@ref{filter_complex_script option,,-filter_complex_script option,ffmpeg}.
> +
>   @chapter Timeline editing
>   
>   Some filters support a generic @option{enable} option. For the filters
> @@ -12359,11 +12371,11 @@ braces is a function name, possibly followed by arguments separated by ':'.
>   If the arguments contain special characters or delimiters (':' or '@}'),
>   they should be escaped.
>   
> -Note that they probably must also be escaped as the value for the
> -@option{text} option in the filter argument string and as the filter
> -argument in the filtergraph description, and possibly also for the shell,
> -that makes up to four levels of escaping; using a text file avoids these
> -problems.
> +Note that they probably must also be escaped as the value for the @option{text}
> +option in the filter argument string and as the filter argument in the
> +filtergraph description, and possibly also for the shell, that makes up to four
> +levels of escaping; using a text file with the @option{textfile} option avoids
> +these problems.
>   
>   The following functions are available:
>   

_______________________________________________
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 1/3] doc/filters/drawtext: clarify meaning of strftime format string

[Gyan Doshi]

On 2023-03-26 11:03 pm, Stefano Sabatini wrote:
> Also clarify what should be used instead of the strftime expansion mode.

LGTM.

Regards,
Gyan


> ---
>   doc/filters.texi | 28 +++++++++++++++-------------
>   1 file changed, 15 insertions(+), 13 deletions(-)
>
> diff --git a/doc/filters.texi b/doc/filters.texi
> index 4449998ba4..b397100ff8 100644
> --- a/doc/filters.texi
> +++ b/doc/filters.texi
> @@ -12103,13 +12103,12 @@ The default value of @var{bordercolor} is "black".
>   
>   @item expansion
>   Select how the @var{text} is expanded. Can be either @code{none},
> -@code{strftime} (deprecated) or
> -@code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section
> -below for details.
> +@code{strftime} (deprecated) or @code{normal} (default). See the
> +@ref{drawtext_expansion, Text expansion} section below for details.
>   
>   @item basetime
>   Set a start time for the count. Value is in microseconds. Only applied
> -in the deprecated strftime expansion mode. To emulate in normal expansion
> +in the deprecated @code{strftime} expansion mode. To emulate in normal expansion
>   mode use the @code{pts} function, supplying the start time (in seconds)
>   as the second argument.
>   
> @@ -12340,10 +12339,12 @@ The current packet's size (in bytes).
>   @anchor{drawtext_expansion}
>   @subsection Text expansion
>   
> -If @option{expansion} is set to @code{strftime},
> -the filter recognizes strftime() sequences in the provided text and
> -expands them accordingly. Check the documentation of strftime(). This
> -feature is deprecated.
> +If @option{expansion} is set to @code{strftime}, the filter recognizes
> +sequences accepted by the @code{strftime} C function in the provided
> +text and expands them accordingly. Check the documentation of
> +@code{strftime}. This feature is deprecated in favor of @code{normal}
> +expansion with the @code{gmtime} or @code{localtime} expansion
> +functions.
>   
>   If @option{expansion} is set to @code{none}, the text is printed verbatim.
>   
> @@ -12390,13 +12391,13 @@ It can be used to add padding with zeros from the left.
>   
>   @item gmtime
>   The time at which the filter is running, expressed in UTC.
> -It can accept an argument: a strftime() format string.
> +It can accept an argument: a @code{strftime} C function format string.
>   The format string is extended to support the variable @var{%[1-6]N}
>   which prints fractions of the second with optionally specified number of digits.
>   
>   @item localtime
>   The time at which the filter is running, expressed in the local time zone.
> -It can accept an argument: a strftime() format string.
> +It can accept an argument: a @code{strftime} C function format string.
>   The format string is extended to support the variable @var{%[1-6]N}
>   which prints fractions of the second with optionally specified number of digits.
>   
> @@ -12438,8 +12439,8 @@ If the format is set to @code{hms}, a third argument @code{24HH} may be
>   supplied to present the hour part of the formatted timestamp in 24h format
>   (00-23).
>   
> -If the format is set to @code{localtime} or @code{gmtime},
> -a third argument may be supplied: a strftime() format string.
> +If the format is set to @code{localtime} or @code{gmtime}, a third
> +argument may be supplied: a @code{strftime} C function format string.
>   By default, @var{YYYY-MM-DD HH:MM:SS} format will be used.
>   @end table
>   
> @@ -12543,7 +12544,8 @@ drawtext="text='Test Text': fontsize=h/30: x=(w-text_w)/2: y=(h-text_h*2)"
>   @end example
>   
>   @item
> -Print the date of a real-time encoding (see strftime(3)):
> +Print the date of a real-time encoding (see documentation for the
> +@code{strftime} C function):
>   @example
>   drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}'
>   @end example

_______________________________________________
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 3/3] doc/filters: mentions that whitespaces are ignored in the filtergraph specification

[Gyan Doshi]

On 2023-03-26 11:04 pm, Stefano Sabatini wrote:
> Also provide example showing how to use this feature to improve filtergraph
> readability.

LGTM.

Regards,
Gyan

>
> Address issue:
> http://trac.ffmpeg.org/ticket/8115
> ---
>   doc/filters.texi | 17 +++++++++++++++++
>   1 file changed, 17 insertions(+)
>
> diff --git a/doc/filters.texi b/doc/filters.texi
> index 1c9d523340..889de8b11a 100644
> --- a/doc/filters.texi
> +++ b/doc/filters.texi
> @@ -214,6 +214,23 @@ In a complete filterchain all the unlabelled filter input and output
>   pads must be connected. A filtergraph is considered valid if all the
>   filter input and output pads of all the filterchains are connected.
>   
> +Leading and trailing whitespaces (space, tabs, or line feeds) separating tokens
> +in the filtergraph specification are ignored. This means that the filtergraph
> +can be expressed using empty lines and spaces to improve redability.
> +
> +For example, the filtergraph:
> +@example
> +testsrc,split[L1],hflip[L2];[L1][L2] hstack
> +@end example
> +
> +can be represented as:
> +@example
> +testsrc,
> +split [L1], hflip [L2];
> +
> +[L1][L2] hstack
> +@end example
> +
>   Libavfilter will automatically insert @ref{scale} filters where format
>   conversion is required. It is possible to specify swscale flags
>   for those automatically inserted scalers by prepending

_______________________________________________
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 2/3] doc/filters: propose solutions to avoid shell escaping

[Stefano Sabatini]

On date Monday 2023-03-27 10:05:56 +0530, Gyan Doshi wrote:
> 
> 
> On 2023-03-26 11:04 pm, Stefano Sabatini wrote:
> > Reference drawtext textfile option and ffmpeg -filter_complext_script
> > and -filter_script as solutils to avoid shell escaping.
> 
> Typos:  `-filter_complext_script` and `solutils`.
> 
> Rest: LGTM.

Fixed and applied, thanks.
_______________________________________________
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 1/3] doc/filters/drawtext: clarify meaning of strftime format string

[Stefano Sabatini]

On date Monday 2023-03-27 10:06:07 +0530, Gyan Doshi wrote:
> 
> 
> On 2023-03-26 11:03 pm, Stefano Sabatini wrote:
> > Also clarify what should be used instead of the strftime expansion mode.
> 
> LGTM.

Applied, thanks.
_______________________________________________
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 3/3] doc/filters: mentions that whitespaces are ignored in the filtergraph specification

[Stefano Sabatini]

On date Monday 2023-03-27 10:06:19 +0530, Gyan Doshi wrote:
> 
> 
> On 2023-03-26 11:04 pm, Stefano Sabatini wrote:
> > Also provide example showing how to use this feature to improve filtergraph
> > readability.
> 
> LGTM.

Applied, thanks.
_______________________________________________
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".