Configure Drop-Frame Timecode in FFmpeg Drawtext

This guide explains how to properly configure the FFmpeg drawtext video filter to render drop-frame timecodes for NTSC-standard frame rates such as 29.97 fps and 59.94 fps. You will learn the correct delimiter syntax required by FFmpeg to enable drop-frame counting, how to set the precise framerate fraction, and how to escape special characters inside your terminal to prevent filter parsing errors.

The Drop-Frame Syntax in drawtext

FFmpeg determines whether a timecode is non-drop-frame (NDF) or drop-frame (DF) based on the delimiter used between seconds and frames in the timecode parameter:

  • Colon (:): Specifies non-drop-frame (e.g., 01:00:00:00).
  • Semicolon (;) or Period (.): Specifies drop-frame (e.g., 01:00:00;00).

When configured with a semicolon or period and paired with an NTSC fractional framerate, FFmpeg drops frame numbers 00 and 01 at the start of every minute, except for every tenth minute, keeping the counter aligned with real-world clock time.

Required Filter Parameters

To generate a valid drop-frame timecode, you must supply at least two core parameters to the drawtext filter:

  1. timecode: The starting timecode string using ; or . before the frame number.
  2. rate (or r): The exact framerate expressed as a fraction. Always use 30000/1001 for 29.97 fps or 60000/1001 for 59.94 fps rather than decimal values to avoid rounding and drift errors.

Escaping the Semicolon

The semicolon is a reserved separator in both terminal shells (like Bash and Zsh) and within FFmpeg's filtergraph parser. To prevent FFmpeg or your shell from misinterpreting the timecode, you must escape the semicolon with a backslash (\;) or properly quote the entire filtergraph argument.

Complete Command Example

The following command overlays a drop-frame timecode starting at 01:00:00;00 onto a 29.97 fps video:

ffmpeg -i input.mp4 -vf "drawtext=fontfile=/path/to/font.ttf:timecode='01\:00\:00\;00':rate=30000/1001:x=(w-text_w)/2:y=h-text_h-20:fontsize=36:fontcolor=white:box=1:boxcolor=black@0.6:boxborderw=5" -c:a copy output.mp4

Key Parameter Breakdown

  • timecode='01\:00\:00\;00': Sets the starting point to hour 1 in drop-frame format. The colons and semicolons are backslash-escaped to avoid filter string parsing conflicts.
  • rate=30000/1001: Sets the exact NTSC 29.97 fps timebase required for standard drop-frame math.
  • box=1:boxcolor=black@0.6:boxborderw=5: Generates a semi-transparent black background behind the text to ensure the timecode remains legible against any footage.
  • x=(w-text_w)/2:y=h-text_h-20: Centers the timecode horizontally and places it 20 pixels above the bottom edge of the frame.