FFmpeg Drawtext: How to Display Frame Number

This article explains how to use the FFmpeg drawtext filter to overlay the real-time frame number onto a video. You will learn the exact command syntax required, see practical examples, and understand how to customize the appearance and positioning of the frame counter on your output video.

To display the current frame number on a video, you must use FFmpeg's drawtext video filter and leverage the evaluate-able variable n (which represents the frame number, starting at 0).

The Basic Command

Here is the fundamental command to overlay the frame number in the top-left corner of your video:

ffmpeg -i input.mp4 -vf "drawtext=fontfile=/path/to/font.ttf:text='%{n}':x=10:y=10:fontsize=24:fontcolor=white" -c:a copy output.mp4

Parameter Breakdown

  • -vf "drawtext=...": This calls the video filter graph and applies the drawtext filter.
  • fontfile=/path/to/font.ttf: Path to a TrueType (.ttf) or OpenType (.otf) font on your system. This is required for FFmpeg to render the text. (On Windows, this might be C\:/Windows/Fonts/arial.ttf).
  • text='%{n}': This is the key argument. %{n} tells FFmpeg to dynamically print the current frame number.
  • x=10:y=10: Sets the coordinate position of the text in pixels. 10:10 places the text 10 pixels from the top and left margins.
  • fontsize=24: Sets the size of the font.
  • fontcolor=white: Sets the color of the text.

Adding a Text Label

If you want to display a label like "Frame: 124" instead of just a raw number, you must escape the colon character (:) with a backslash because colons are used to separate filter arguments in FFmpeg.

ffmpeg -i input.mp4 -vf "drawtext=fontfile=/path/to/font.ttf:text='Frame\: %{n}':x=10:y=10:fontsize=24:fontcolor=white" -c:a copy output.mp4

Improving Readability with a Background Box

If the background of your video makes the white text hard to read, you can add a semi-transparent black background box behind the frame counter:

ffmpeg -i input.mp4 -vf "drawtext=fontfile=/path/to/font.ttf:text='%{n}':x=10:y=10:fontsize=24:fontcolor=white:box=1:boxcolor=black@0.5:boxborderw=5" -c:a copy output.mp4
  • box=1: Enables the background box.
  • boxcolor=black@0.5: Sets the box color to black with 50% opacity.
  • boxborderw=5: Adds a 5-pixel padding/border around the text inside the box.