Overlay Dynamic Timecode and Frame Count with FFmpeg

This article provides a step-by-step guide on how to overlay a dynamic, real-time timecode and custom frame count onto a video using FFmpeg. You will learn the exact command-line syntax to burn this metadata directly into your video files, customize the starting frame number, and format the visual output for professional video editing and QA workflows.

To overlay both a dynamic timecode and a custom frame count, you will use FFmpeg's drawtext video filter. This filter allows you to render text on top of a video stream using various system variables, such as pts for time and n for frame numbers.

The FFmpeg Command

Below is the complete command to overlay a dynamic timecode in the top-left corner and a custom frame count (starting at a designated number) in the top-right corner:

ffmpeg -i input.mp4 -vf "drawtext=fontfile=/path/to/font.ttf:timecode='00\:00\:00\:00':rate=30:x=10:y=10:fontsize=24:fontcolor=white:box=1:boxcolor=black@0.5, drawtext=fontfile=/path/to/font.ttf:text='Frame\: %{eif\:n+1000\:d}':x=w-tw-10:y=10:fontsize=24:fontcolor=white:box=1:boxcolor=black@0.5" -c:a copy output.mp4

Parameter Breakdown

To customize this command for your specific video file, understand how the key parameters function:

  • fontfile: The absolute path to a TrueType (.ttf) or OpenType (.otf) font file on your system (e.g., /Windows/Fonts/arial.ttf on Windows or /Library/Fonts/Arial.ttf on macOS).
  • timecode: Sets the starting timecode in HH:MM:SS:FF format. Note that the colons must be escaped with backslashes (\:) inside the filter.
  • rate: Sets the frame rate for the timecode calculation. This should match your input video's frame rate (e.g., 24, 29.97, 30, 60).
  • text='Frame\: %{eif\:n+1000\:d}':
    • n represents the current frame number (starting at 0).
    • +1000 is the offset to start your custom frame count at 1000. Change this number to whatever starting frame you require.
    • eif stands for "evaluate integer formula," which processes the math, and \:d formats the result as a decimal.
  • x and y: The horizontal and vertical coordinates of the text.
    • x=10:y=10 places the timecode in the top-left corner.
    • x=w-tw-10:y=10 places the frame count in the top-right corner by subtracting the text width (tw) and a 10-pixel padding from the video width (w).
  • box and boxcolor: box=1 enables a background box behind the text, and boxcolor=black@0.5 sets a black background with 50% opacity to ensure the text remains readable against any video background.
  • -c:a copy: Copies the audio stream without re-encoding, saving processing time.