Syntax

The description of the accepted parameters follows.

box

Used to draw a box around text using background color. Value should be either 1 (enable) or 0 (disable). The default value of box is 0.

boxcolor

The color to be used for drawing box around text. Either a string (e.g. "yellow") or in 0xRRGGBB[AA] format (e.g. "0xff00ff"), possibly followed by an alpha specifier. The default value of boxcolor is "white".

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 specifying that the text should be drawn only when specific conditions are met.

Default value is "1".

See below for the list of accepted constants and functions.

expansion

Select how the text is expanded. Can be either none, strftime (deprecated) or normal (default). See the Text expansion section below for details.

fix_bounds

If true, check and fix text coords to avoid clipping.

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 fontcolor is "black".

fontfile

The font file to be used for drawing text. Path must be included. This parameter is mandatory.

fontsize

The font size to be used for drawing text. The default value of fontsize is 16.

ft_load_flags

Flags to be used for loading the fonts.

The flags map the corresponding flags supported by libfreetype, and are a combination of the following values:

• default
• no_scale
• no_hinting
• render
• no_bitmap
• vertical_layout
• force_autohint
• crop_bitmap
• pedantic
• ignore_global_advance_width
• no_recurse
• ignore_transform
• monochrome
• linear_design
• no_autohint

Default value is "render".

For more information consult the documentation for the FT_LOAD_* libfreetype flags.

shadowcolor

The color to be used for drawing a shadow behind the drawn text. It can be a color name (e.g. "yellow") or a string in the 0xRRGGBB[AA] form (e.g. "0xff00ff"), possibly followed by an alpha specifier. The default value of shadowcolor is "black".

shadowx, shadowy

The x and y offsets for the text shadow position with respect to the position of the text. They can be either positive or negative values. Default value for both is "0".

start_number

The starting frame number for the n/frame_num variable. The default value is "0".

tabsize

The size in number of spaces to use for rendering the tab. Default value is 4.

timecode

Set the initial timecode representation in "hh:mm:ss[:;.]ff" format. It can be used with or without text parameter. timecode_rate option must be specified.

timecode_rate, rate, r

Set the timecode frame rate (timecode only).

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 with the parameter textfile.

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 with the parameter text.

If both text and textfile are specified, an error is thrown.

reload

If set to 1, the textfile will be reloaded before each frame. Be sure to update it atomically, or it may be read partially, or even fail.

x, y

The expressions which specify the offsets where text will be drawn within the video frame. They are relative to the top/left border of the output image.

The default value of x and y is "0".

See below for the list of accepted constants and functions.

The parameters for x and y are expressions containing the following constants and functions:

dar

input display aspect ratio, it is the same as (w / h) * sar

hsub, vsub

horizontal and vertical chroma subsample values. For example for the pixel format "yuv422p" hsub is 2 and vsub is 1.

line_h, lh

the height of each text line

main_h, h, H

the input height

main_w, w, W

the input width

max_glyph_a, ascent

the maximum distance from the baseline to the highest/upper grid coordinate used to place a glyph outline point, for all the rendered glyphs. It is a positive value, due to the grid’s orientation with the Y axis upwards.

max_glyph_d, descent

the maximum distance from the baseline to the lowest grid coordinate used to place a glyph outline point, for all the rendered glyphs. This is a negative value, due to the grid’s orientation, with the Y axis upwards.

max_glyph_h

maximum glyph height, that is the maximum height for all the glyphs contained in the rendered text, it is equivalent to ascent - descent.

max_glyph_w

maximum glyph width, that is the maximum width for all the glyphs contained in the rendered text

n

the number of input frame, starting from 0

rand(min, max)

return a random number included between min and max

sar

input sample aspect ratio

t

timestamp expressed in seconds, NAN if the input timestamp is unknown

text_h, th

the height of the rendered text

text_w, tw

the width of the rendered text

x, y

the x and y offset coordinates where the text is drawn.

These parameters allow the x and y expressions to refer each other, so you can for example specify y=x/dar.

If libavfilter was built with --enable-fontconfig, then fontfile can be a fontconfig pattern or omitted.

Text expansion

If expansion is set to strftime, the filter recognizes strftime() sequences in the provided text and expands them accordingly. Check the documentation of strftime(). This feature is deprecated.

If expansion is set to none, the text is printed verbatim.

If expansion is set to normal (which is the default), the following expansion mechanism is used.

The backslash character ’\’, followed by any character, always expands to the second character.

Sequence of the form %{...} are expanded. The text between the 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 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.

The following functions are available:

expr, e

The expression evaluation result.

It must take one argument specifying the expression to be evaluated, which accepts the same constants and functions as the x and y values. Note that not all constants should be used, for example the text size is not known when evaluating the expression, so the constants text_w and text_h will have an undefined value.

gmtime

The time at which the filter is running, expressed in UTC. It can accept an argument: a strftime() format string.

localtime

The time at which the filter is running, expressed in the local time zone. It can accept an argument: a strftime() format string.

metadata

Frame metadata. It must take one argument specifying metadata key.

n, frame_num

The frame number, starting from 0.

pict_type

A 1 character description of the current picture type.

pts

The timestamp of the current frame, in seconds, with microsecond accuracy.