[FFmpeg-devel] [PATCH 3/3] lavfi/drawtext: implement more generic expansion.

[Clément Bœsch]

On Sat, Nov 10, 2012 at 07:49:47PM +0100, Nicolas George wrote:
> The new expansion mechanism uses the ${...} notation.

Let's start a bikeshed war: '$' will be a pain with shells (filtergraphs
are often between "" quotes). I think '#', '&' or '@' are better choices.

> For compatibility reasons, it must be enabled explicitly,
> but a warning is printed if a change is likely to happen.
> 
> Signed-off-by: Nicolas George <nicolas.george at normalesup.org>
> ---
>  doc/filters.texi          |   50 ++++++++++++++-
>  libavfilter/vf_drawtext.c |  151 +++++++++++++++++++++++++++++++++++++++++++--
>  2 files changed, 194 insertions(+), 7 deletions(-)
> 
> diff --git a/doc/filters.texi b/doc/filters.texi
> index eaf0f42..8b1894b 100644
> --- a/doc/filters.texi
> +++ b/doc/filters.texi
> @@ -1844,8 +1844,7 @@ libfreetype library.
>  To enable compilation of this filter you need to configure FFmpeg with
>  @code{--enable-libfreetype}.
>  
> -The filter also recognizes strftime() sequences in the provided text
> -and expands them accordingly. Check the documentation of strftime().
> + at subsection Syntax
>  
>  The filter accepts parameters as a list of @var{key}=@var{value} pairs,
>  separated by ":".
> @@ -1865,6 +1864,10 @@ Either a string (e.g. "yellow") or in 0xRRGGBB[AA] format
>  (e.g. "0xff00ff"), possibly followed by an alpha specifier.
>  The default value of @var{boxcolor} is "white".
>  
> + at item compat_expand (or old)
> +Use old strfime-style expansion for the text. It is enabled by default for

Use /the/ old /strftime/-style...

> +now.
> +
>  @item draw
>  Set an expression which specifies if the text should be drawn. If the
>  expression evaluates to 0, the text is not drawn. This is useful for
> @@ -2039,6 +2042,43 @@ each other, so you can for example specify @code{y=x/dar}.
>  If libavfilter was built with @code{--enable-fontconfig}, then
>  @option{fontfile} can be a fontconfig pattern or omitted.
>  
> + at subsection Text expnsion

expansion

> +
> +If @option{compat_expand} is enabled (which is the default for now),
> +the filter also recognizes strftime() sequences in the provided text
> +and expands them accordingly. Check the documentation of strftime().
> +This feature is deprecated.
> +
> +If @option{compat_expand} is not enabled, a more general expansion mechanism
> +is used.
> +
> +The backslash character '\', followed by any character, always expand to the
> +second character.
> +
> +Sequence of the form @code{$@{...@}} are expanded. The text between the

Note: make sure that documentation renders well in the HTML and manpage
output, these special characters are known for causing troubles in the
output.

> +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 filter graph description, and possibly also for the
> +shell, that makes up to four levels of escaping; using a text file avoids
> +these problems.
> +
> +The following function exist:
> +

functions

> + at table @command
> +
> + at 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.
> +
> + at item pts
> +The timestamp of the current frame, in seconds, with microsecond accuracy.
> +
> + at end table
> +
> + at subsection Examples
> +
>  Some examples follow.
>  
>  @itemize
> @@ -2104,6 +2144,12 @@ Use fontconfig to set the font. Note that the colons need to be escaped.
>  drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg'
>  @end example
>  
> + at item
> +Print the date of a real-time encoding (see strftime(3)):
> + at example
> +drawtext='fontfile=FreeSans.ttf:text=$@{localtime:%a %b %d %Y@}'
> + at end example
> +

Sounds nice. Do you plan to do as well for the SMPTE Timecode and the
filters metadata? :)

[...]
> +static int expand_function(AVFilterContext *ctx, AVBPrint *bp, char **rtext)
> +{
> +    const char *text = *rtext;
> +    char *argv[16] = { NULL };
> +    unsigned argc = 0, i;
> +    int ret;
> +
> +    if (*text != '{') {
> +        av_log(ctx, AV_LOG_ERROR, "Stray $ near '%s'\n", text);
> +        return AVERROR(EINVAL);
> +    }
> +    text++;
> +    while (1) {
> +        if (!(argv[argc++] = av_get_token(&text, ":}"))) {
> +            ret = AVERROR(ENOMEM);
> +            goto fail;
> +        }
> +        if (!*text) {
> +            av_log(ctx, AV_LOG_ERROR, "Unterminated ${} near '%s'\n", *rtext);
> +            ret = AVERROR(EINVAL);
> +            goto fail;
> +        }
> +        if (argc == FF_ARRAY_ELEMS(argv))
> +            av_freep(&argv[--argc]); /* error will be caught later */
> +        if (*text == '}')
> +            break;
> +        text++;
> +    }
> +
> +    if ((ret = eval_function(ctx, bp, argv[0], argv + 1, argc - 1)) < 0)
> +        goto fail;
> +    ret = 0;
> +    *rtext = (char *)text + 1;
> +
> +fail:

I'd rather call this "end" since it's reached in case of success as well.

[...]

-- 
Clément B.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 490 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20121110/4d428d96/attachment.asc>