Add Real-Time Date and Time to Video Using FFmpeg

Burning a real-time timestamp onto a video stream is a common requirement for security surveillance, legal documentation, and live broadcasting. This article demonstrates how to use FFmpeg’s built-in drawtext video filter to overlay the current system date and time onto any active video feed or recorded file. You will learn the exact syntax required for time formatting, text styling, and positioning, as well as how to avoid common escaping errors in FFmpeg commands.

Prerequisites

To use the drawtext filter, your FFmpeg build must be compiled with the --enable-libfreetype flag (standard in most official distributions). You also need access to a TrueType (.ttf) or OpenType (.otf) font file on your system.

The Basic Command

FFmpeg provides the %{localtime} function within the drawtext filter to pull the current system clock during processing.

Here is the standard command to burn the current date and time onto a video stream:

ffmpeg -i input.mp4 -vf "drawtext=fontfile=/path/to/font.ttf:text='%{localtime\:%Y-%m-%d %H\\\\\:%M\\\\\:%S}':x=20:y=20:fontsize=24:fontcolor=white:box=1:boxcolor=black@0.6:boxborderw=5" -c:a copy output.mp4

Parameter Breakdown

  • fontfile: The absolute path to a valid font on your system (for example, /usr/share/fonts/truetype/dejavu/DejaVuSans.ttf on Linux, or C\\:/Windows/Fonts/arial.ttf on Windows).
  • text: Formats the date and time using standard strftime syntax.
    • %Y-%m-%d: Outputs Year-Month-Day (e.g., 2023-10-25).
    • %H\\\\\:%M\\\\\:%S: Outputs Hours:Minutes:Seconds.
    • Note on Escaping: Colons (:) are delimiters in FFmpeg filters. Colons inside the text string must be escaped with a backslash (\:), and colons inside time formats often require multiple backslashes (e.g., \\\\\:) depending on your shell to prevent parsing conflicts. Alternatively, you can use %T for time if your system's strftime supports it: text='%{localtime\:%Y-%m-%d %T}'.
  • x and y: Coordinates for text placement, measured in pixels from the top-left corner.
  • fontsize: Size of the text in pixels.
  • fontcolor: Color of the font (e.g., white, yellow, 0xFFFFFF).
  • box: Enables a background bounding box (1 for enabled) to make the text legible against varying video backgrounds.
  • boxcolor: The color and opacity of the background box. black@0.6 creates a semi-transparent black background with 60% opacity.
  • boxborderw: The padding around the text inside the box in pixels.

Burning Timestamps into a Live Stream

When working with live input devices—such as a webcam, capture card, or RTSP stream—add the live capture input flags.

Example: Linux Webcam (V4L2)

ffmpeg -f v4l2 -framerate 30 -video_size 1280x720 -i /dev/video0 \
-vf "drawtext=fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf:text='%{localtime\:%Y-%m-%d %T}':x=10:y=10:fontsize=20:fontcolor=white:box=1:boxcolor=black@0.5" \
-c:v libx264 -preset veryfast -f mp4 live_output.mp4

Example: Windows DirectShow Device

ffmpeg -f dshow -i video="Integrated Camera" -vf "drawtext=fontfile='C\:/Windows/Fonts/arial.ttf':text='%{localtime\:%Y-%m-%d %T}':x=10:y=10:fontsize=22:fontcolor=white:box=1:boxcolor=black@0.5" -c:v libx264 -f mp4 output.mp4

Positioning Options

You can adjust the x and y parameters using FFmpeg expressions:

  • Top-Left: x=20:y=20
  • Top-Right: x=w-tw-20:y=20 (w is video width, tw is text width)
  • Bottom-Left: x=20:y=h-th-20 (h is video height, th is text height)
  • Bottom-Right: x=w-tw-20:y=h-th-20