How to Burn Local Time Timestamps in FFmpeg

Burning a timestamp that displays a local time zone onto a video using FFmpeg is accomplished with the drawtext video filter combined with the localtime function. By configuring standard strftime time format specifiers—specifically %Z for the time zone abbreviation or %z for the numerical UTC offset—you can overlay precise, dynamic date and time information directly onto your video frames, either using the system's current time zone or a custom one defined by environment variables.

The Basic drawtext Syntax

FFmpeg provides the drawtext filter via libfreetype. To display an advancing timestamp that starts at a specific historical or reference time and increments with the video’s presentation timestamp (PTS), use the pts:localtime expression.

Here is the general structure of the command:

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

Breakdown of Key Parameters

• fontfile: The absolute path to a TrueType (.ttf) or OpenType (.otf) font file (e.g., /usr/share/fonts/truetype/dejavu/DejaVuSans.ttf on Linux or C\\:/Windows/Fonts/arial.ttf on Windows).
• text: The text overlay template.
  • pts\:localtime\:<epoch_time>\:<format>: Takes a starting UNIX epoch timestamp (in seconds) and advances the time based on the video frame's PTS.
  • %Y-%m-%d: Formats the year, month, and day.
  • %H\\\:%M\\\:%S: Formats hours, minutes, and seconds. Note that colons inside the format string must be escaped with triple backslashes (\\\:) so FFmpeg does not confuse them with filter parameter delimiters.
  • %Z: Outputs the local time zone abbreviation (e.g., EST, PST, CEST).
  • %z: Outputs the local time zone offset relative to UTC (e.g., -0500, +0200).
• x and y: Positioning of the timestamp on the screen (in pixels).
• box: Adds a semi-transparent background behind the text to make it readable against bright backgrounds.

Setting a Specific Local Time Zone

By default, FFmpeg queries the operating system's local time configuration. To burn a timestamp using a specific time zone that differs from your machine's default, define the TZ environment variable directly before executing the FFmpeg command.

Linux and macOS

Prepend the command with the desired TZ database name:

TZ="America/New_York" ffmpeg -i input.mp4 -vf "drawtext=fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf:fontsize=24:fontcolor=yellow:x=w-tw-20:y=20:text='%{pts\:localtime\:1704067200\:%Y-%m-%d %H\\\:%M\\\:%S %Z (%z)}'" -c:a copy output.mp4

Windows (Command Prompt)

Set the TZ environment variable in your session prior to running the command:

set TZ=EST5EDT
ffmpeg -i input.mp4 -vf "drawtext=fontfile='C\:/Windows/Fonts/arial.ttf':fontsize=24:fontcolor=white:x=10:y=10:text='%%{pts\:localtime\:1704067200\:%Y-%m-%d %H\\\:%M\\\:%S %Z}'" -c:a copy output.mp4

(Note: In Windows batch files or command prompts, percentage signs used for variable expansion inside strings may need to be doubled as %%).

Burning the Current Machine Time During Live Capture

If you are capturing live footage or re-encoding and want the timestamp to reflect the actual system time during processing instead of incrementing relative to an epoch offset, use localtime without pts:

ffmpeg -i input.mp4 -vf "drawtext=fontfile=/path/to/font.ttf:fontsize=20:fontcolor=white:x=10:y=10:text='%{localtime\:%Y-%m-%d %H\\\:%M\\\:%S %Z}'" -c:a copy output.mp4