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 --enable-libfreetype.

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

The filter accepts parameters as a list of key=value pairs, separated by ":".

The description of the accepted parameters follows.

fontfile

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

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.

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.

fontsize

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

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

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

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.

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

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

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
• end table

Default value is "render".

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

tabsize

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

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

W, H

the input width and height

tw, text_w

the width of the rendered text

th, text_h

the height of the rendered text

lh, line_h

the height of each text line

sar

input sample aspect ratio

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.

max_glyph_w

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

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_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.

n

the number of input frame, starting from 0

t

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

timecode

initial timecode representation in "hh:mm:ss[:;.]ff" format. It can be used with or without text parameter. rate option must be specified. Note that timecode options are not effective if FFmpeg is build with --disable-avcodec.

r, rate

frame rate (timecode only)

Some examples follow.

• Draw "Test Text" with font FreeSerif, using the default values for the optional parameters.

  drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"

• Draw ’Test Text’ with font FreeSerif of size 24 at position x=100 and y=50 (counting from the top-left corner of the screen), text is yellow with a red box around it. Both the text and the box have an opacity of 20%.

  drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
            x=100: y=50: fontsize=24: fontcolor=yellow@0.2: box=1: boxcolor=red@0.2"

  Note that the double quotes are not necessary if spaces are not used within the parameter list.

• Show the text at the center of the video frame:

  drawtext=fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h-line_h)/2"

• Show a text line sliding from right to left in the last row of the video frame. The file LONG_LINE is assumed to contain a single line with no newlines.

  drawtext=fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t

• Show the content of file CREDITS off the bottom of the frame and scroll up.

  drawtext=fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"

• Draw a single green letter "g", at the center of the input video. The glyph baseline is placed at half screen height.

  drawtext=fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent

For more information about libfreetype, check: http://www.freetype.org/.