How to Overlay Timecode in FFmpeg Using drawtext

This article explains how to use FFmpeg's drawtext video filter to overlay a dynamic, frame-accurate timecode onto a video. You will learn the essential syntax, how to configure the frame rate, and how to customize the appearance and positioning of the timecode display, complete with copy-and-paste command examples.

The Basic Timecode Command

To overlay a dynamic timecode, you must use the drawtext filter with the timecode parameter. This parameter requires a starting time and a specified frame rate (rate) to calculate the counting frames accurately.

Here is a standard command to burn a white timecode with a semi-transparent black background into the bottom center of a video:

ffmpeg -i input.mp4 -vf "drawtext=fontfile=/path/to/font.ttf:timecode='00\:00\:00\:00':rate=30:x=(w-tw)/2:y=h-th-50:fontsize=24:fontcolor=white:box=1:boxcolor=black@0.5" -c:a copy output.mp4

Parameter Breakdown

  • fontfile: The absolute path to a TrueType (.ttf) or OpenType (.otf) font on your system. This is required for drawtext to render text.
  • timecode: The starting timecode in hh:mm:ss:ff (hours:minutes:seconds:frames) format. Note that the colons must be escaped with backslashes (00\:00\:00\:00).
  • rate (or r): The frame rate of your source video (e.g., 24, 25, 29.97, 30, 60). This must match your video's frame rate to prevent the timecode from drifting out of sync.
  • x and y: The coordinates for the text placement.
    • x=(w-tw)/2 centers the text horizontally.
    • y=h-th-50 places the text 50 pixels from the bottom of the video.
  • fontsize: The size of the rendered text in pixels.
  • fontcolor: The color of the text (e.g., white, yellow, or hex codes like 0xFFFFFF).
  • box and boxcolor: Setting box=1 enables a background bounding box. boxcolor=black@0.5 sets the box color to black with 50% opacity to ensure the timecode is readable against any background.

Customizing the Timecode Start Time

If your video does not start at zero, you can change the starting value of the timecode parameter. For example, to start the timecode at 1 hour, 30 minutes, and 15 seconds:

-vf "drawtext=fontfile=font.ttf:timecode='01\:30\:15\:00':rate=24:..."

Alternative: Using the pts Option for Elapsed Time

If you prefer to display elapsed running time in standard hours, minutes, and seconds (without frame numbers), you can use the pts (Presentation Timestamp) function inside the text parameter instead of the timecode parameter:

ffmpeg -i input.mp4 -vf "drawtext=fontfile=font.ttf:text='%{pts\:hms}':x=50:y=50:fontsize=32:fontcolor=white:box=1:boxcolor=black@0.6" -c:a copy output.mp4

This method automatically scales to the video's internal timing without requiring you to manually define the frame rate.