[FFmpeg-devel] [PATCH] Add drawtext filter from the libavfilter soc repo.

[Justin Ruggles]

Hi,

On 02/22/2011 05:10 PM, Stefano Sabatini wrote:

> + at section drawtext
> +
> +Draw text string or text from specified file on top of video using the
> +libfreetype library.
> +
> +To enable compilation of this filter you need to configure FFmpeg with
> + at code{--enable-libfreetype}.


"This filter requires the FreeType 2 library.  To enable compilation of..."

> +The filter also recognizes strftime() sequences in the provided text
> +and expands them accordingly. Check the documentation of strftime().

Maybe mention that strftime() is a Standard C Library function in time.h
or give a good reference.  The first 2 Google hits for strftime are PHP
and C++ references.  This is user documentation, and we can't expect
that all our users are C programmers and know what strftime() means or
how to easily find out.

> + at item fontfile
> +The font file to be used for drawing text. Path must be included.
> +This parameter is mandatory.

The first user question that comes to mind when reading this is "What
type of font do I have to use?".  I think it would be nice to mention
that the font must be in a format supported by the FreeType 2 library as
configured on the host system.

> + at item text
> +The text string to be drawn. The text must be a sequence of UTF-8
> +encoded characters.
> +This parameter is mandatory if no file is specified.
> +
> + at item textfile
> +A text file containing text to be drawn. The text must be a sequence
> +of UTF-8 encoded characters
> +
> +This parameter is mandatory if no text string is specified.
> +
> +If both text and textfile are specified, an error is thrown.


This sounds awkward and not obvious to a non-coder.  May be better to
say something like "You must specify either text or textfile, but you
may not specify both" or "Either the text or textfile parameter is
mandatory, but both cannot be used together in the same command"

> +
> + at item x, y
> +The offsets where text will be drawn within the video frame.
> +Relative to the top/left border of the output image.

I know neither part is a sentence... but it reads much better with a
comma between them rather than a period.

> +The default value of @var{x} and @var{y} is 0.
> +
> + at item fontsize
> +The font size to be used for drawing text.
> +The default value of @var{size} is 16.

In what units?

> + at item fontcolor
> +The color to be used for drawing fonts.
> +Either a string (e.g. "red") or in 0xRRGGBB[AA] format
> +(e.g. "0xff000033"), possibly followed by an alpha specifier.
> +The default value of @var{fontcolor} is "black".

Might be simpler to add a section regarding the color format string in
the docs somewhere, then link to it from the various parameters in
libavfilter that specify a color rather than having to explain the same
thing for each parameter.

Also, that example uses alpha, so what kind of "alpha specifier" would
follow it?

Thanks,
Justin