Drawtext

Video Single output Transform

Draw text on top of video frames using libfreetype library.

FFmpeg filter: drawtext — the official reference.

Add it to a graph. The explicit form works for every filter — bind it to its input and read the result from outputs():

$node   = $video->addFilter(new Drawtext(…));
$result = $node->outputs()[0];

Shorthand. Single-output filters can skip the node — apply() returns the result stream directly:

$result = $video->apply(new Drawtext(…));

When to use it

TODO — when this filter shines: what it’s the right tool for, what to reach for instead when it isn’t, and how it composes with neighbouring filters.

How to use it

TODO — prose: how the filter actually works and what its key parameters mean (the explanation FFmpeg’s terse option help omits).

Examples

TODO — runnable PHP, with the equivalent ffmpeg CLI alongside.

Gotchas

TODO

See also

TODO

Parameters

Parameter	Type	Default	Range / values	Description
fontfile	string	—	—	set font file
text	string	—	—	set text
textfile	string	—	—	set text file
fontcolor	string	black	—	set foreground color
fontcolor_expr	string	—	—	set foreground color expression
boxcolor	string	white	—	set box color
bordercolor	string	black	—	set border color
shadowcolor	string	black	—	set shadow color
box	bool	false	—	set box
boxborderw	string	0	—	set box borders width
line_spacing	int	0	—	set line spacing in pixels
fontsize	int|float|string	—	expression	set font size
text_align	int|string	0	—	set text alignment
x	int|float|string	0	expression	set x expression
y	int|float|string	0	expression	set y expression
boxw	int	0	≥ 0	set box width
boxh	int	0	≥ 0	set box height
shadowx	int	0	—	set shadow x offset
shadowy	int	0	—	set shadow y offset
borderw	int	0	—	set border width
tabsize	int	4	≥ 0	set tab size
basetime	int	—	—	set base time
font	string	Sans	—	Font name
expansion	DrawtextExpansion	normal	none, normal, strftime	set the expansion mode
y_align	DrawtextYAlign	text	text, baseline, font	set the y alignment
timecode	string	—	—	set initial timecode
tc24hmax	bool	false	—	set 24 hours max (timecode only)
timecode_rate	string	—	—	set rate (timecode only)
reload	int	0	≥ 0	reload text file at specified frame interval
alpha	string	1	—	apply alpha while rendering
fix_bounds	bool	false	—	check and fix text coords to avoid clipping
start_number	int	0	≥ 0	start frame number for n/frame_num variable
text_source	string	—	—	the source of text
text_shaping	bool	true	—	attempt to shape text before drawing
ft_load_flags	int|string	0	—	set font loading flags for libfreetype

FFmpeg also names these options (use the parameter shown above): r → timecode_rate, rate → timecode_rate.

---

Maps to FFmpeg’s drawtext filter. Verified against ffmpeg n7.1.1.