How to Burn Frame Numbers onto Video with FFmpeg

This article provides a straightforward guide on how to overlay sequential frame numbers onto every frame of a video using the FFmpeg command-line tool. You will learn the exact command syntax, how the drawtext filter works, and how to customize the position, size, and background of the printed numbers.

To print frame numbers onto a video, you must use FFmpeg's drawtext video filter. The key to displaying the frame number is using the %{n} evaluation variable inside the text parameter.

Here is the basic command to overlay frame numbers:

ffmpeg -i input.mp4 -vf "drawtext=text='%{n}':x=10:y=10:fontsize=24:fontcolor=white:box=1:boxcolor=black@0.5" -c:a copy output.mp4

Command Breakdown

  • -i input.mp4: Specifies your input video file.
  • -vf: Flags the start of the video filter graph.
  • drawtext=...: The filter used to render text.
    • text='%{n}': This is the most crucial part. The %{n} variable tells FFmpeg to print the current frame number (starting at 0).
    • x=10:y=10: Sets the coordinates where the text will appear. In this case, 10 pixels from the top-left corner.
    • fontsize=24: Sets the size of the font.
    • fontcolor=white: Sets the text color to white.
    • box=1:boxcolor=black@0.5: Draws a semi-transparent black background box (50% opacity) behind the text to ensure the numbers remain readable on light backgrounds.
  • -c:a copy: Copies the audio stream without re-encoding it, which speeds up the processing time.
  • output.mp4: The path for the newly generated video.

By default, FFmpeg will attempt to use a system font. However, to avoid errors or default-font fallback issues, it is best to define a specific font file using the fontfile parameter:

On Windows:

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

On macOS:

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

On Linux:

ffmpeg -i input.mp4 -vf "drawtext=fontfile='/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf':text='%{n}':x=10:y=10:fontsize=24:fontcolor=white" -c:a copy output.mp4

Advanced Modifications

Start the Frame Count from 1 (Instead of 0)

FFmpeg starts counting frames at 0 by default. To start the visible counter at 1, use an expression:

text='%{expr\:n+1}'

Change the Position of the Text

You can dynamically position the text using variables like w (video width), h (video height), tw (text width), and th (text height).

  • Bottom-Right Corner: x=w-tw-10:y=h-th-10
  • Top-Center: x=(w-tw)/2:y=10