How to Use FFmpeg drawtext Filter to Overlay Video Text

This article provides a quick, step-by-step guide on how to use the FFmpeg drawtext video filter to overlay custom text onto your videos. You will learn the basic syntax, how to customize text appearance (such as font, size, and color), how to position the text accurately using mathematical expressions, and how to apply practical styling like background boxes.

To overlay text on a video using FFmpeg, you must use the video filter flag (-vf) followed by the drawtext filter and its parameters.

Basic Command Syntax

The simplest way to add text to a video is by using the following command structure:

ffmpeg -i input.mp4 -vf "drawtext=text='Your Text Here':fontcolor=white:fontsize=24" -codec:a copy output.mp4

In this command: * -i input.mp4: Specifies the input video file. * -vf "drawtext=...": Applies the video filter. * text='Your Text Here': Defines the string of text you want to overlay. * fontcolor=white: Sets the text color (accepts color names or hex codes like 0xFFFFFF). * fontsize=24: Sets the size of the text in pixels. * -codec:a copy: Copies the audio stream without re-encoding to save processing time.

Choosing a Font

By default, FFmpeg will attempt to use a system font. However, to ensure your text renders correctly, it is best to specify the path to a TrueType font (.ttf) or OpenType font (.otf) file using the fontfile parameter:

ffmpeg -i input.mp4 -vf "drawtext=fontfile=/path/to/font.ttf:text='Custom Font Text':fontcolor=yellow:fontsize=32" output.mp4

Positioning the Text

FFmpeg uses coordinate variables to position text. The variables w and h represent the width and height of the video frame, while text_w (or tw) and text_h (or th) represent the width and height of the rendered text.

Example command for centered text:

ffmpeg -i input.mp4 -vf "drawtext=text='Centered Text':x=(w-text_w)/2:y=(h-text_h)/2:fontsize=30:fontcolor=white" output.mp4

Adding a Background Box

To make text more readable against complex video backgrounds, you can add a colored background box behind the text using the box, boxcolor, and boxborderw parameters:

ffmpeg -i input.mp4 -vf "drawtext=text='Subtitled Text':x=(w-text_w)/2:y=h-th-20:fontsize=24:fontcolor=white:box=1:boxcolor=black@0.5:boxborderw=10" output.mp4