Add Timestamp to Videos

Troy Williams

2022-07-01

Timestamps

We are doing some experimental work and a lot of the video footage is recorded with GoPro. They are durable and work well in the field. Unfortunately they don’t support timestamp overlay with the date and time on the video. I decided to use FFmpeg and a shell script to automate the process. The following script will take the video, extract the creation_time tag from the video and use that to generate the timestamp overlay.

The script will also re-encode the video to h.265 making it smaller, in some cases reducing the file size to 10 % of the original size.

#!/usr/bin/env bash

# -----------
# SPDX-License-Identifier: MIT
# Copyright (c) 2022 Troy Williams

# uuid       = 70204dea-f8b9-11ec-a408-cbfc46763958
# author     = Troy Williams
# email      = troy.williams@bluebill.net
# date       = 2022-06-30
# -----------

# this script will add timestamps (like security cameras) to the bottom left
# corner of the video. It will use the creation date as the starting point of
# the timestamp counter. The output video will be re-encoded to h265 format.

# NOTE: Some videos indicate they are in UTC, but in fact are not.They will need
# be correct otherwise the timestamp will be incorrect.

# NOTE: If the creation_time isn't set, the video will be skipped.

# Usage:

# $ ./timestamp.sh 20210613_191928.mp4

# loop through files in a folder:
# $ for FILE in ./2022-06-28/*; do ./timestamp.sh "${FILE}"; done
# $ for FILE in ./2022-06-28/*; do ./timestamp.sh "${FILE}" --over-write; done

# Requirements:

# JSON parser: $ sudo apt install jq

# References

# https://www.cyberciti.biz/faq/unix-linux-bsd-appleosx-bash-assign-variable-command-output/
# https://stackoverflow.com/questions/1955505/parsing-json-with-unix-tools
# https://www.baeldung.com/linux/use-command-line-arguments-in-bash-script
# https://stackoverflow.com/a/965069
# https://www.howtogeek.com/529219/how-to-parse-json-files-on-the-linux-command-line-with-jq/
# https://cameronnokes.com/blog/working-with-json-in-bash-using-jq/
# https://stackoverflow.com/questions/965053/extract-filename-and-extension-in-bash

# https://ourcodeworld.com/articles/read/1484/how-to-get-the-information-and-metadata-of-a-media-file-audio-or-video-in-json-format-with-ffprobe
# ffprobe -loglevel 0 -print_format json -show_format -show_streams GX013438.MP4

# ----------------
# Set the script to halt on errors
set -e

if [[ -z "$1" ]]; then
    echo "USAGE: $ 1./timestamp.sh video.mp4"
    exit 1
fi

# Get the movie name
# MOVIE=${1}

# What is the full path of the movie name?
INPUT=$(readlink -f $1)

# Strip longest match of */ from start
filename="${INPUT##*/}"

# Substring from 0 thru pos of filename
dir="${INPUT:0:${#INPUT} - ${#filename}}"

# Strip shortest match of . plus at least one non-dot char from end
base="${filename%.[^.]*}"

# Substring from len of base thru end
ext="${filename:${#base} + 1}"

# If we have an extension and no base, it's really the base
if [[ -z "$base" && -n "$ext" ]]; then
    base=".$ext"
    ext=""
fi

# Create the new file name
OUTPUT="${dir}"/"${base}".stamped."${ext}"

# need to use raw mode `-r` in jq call to return a raw string otherwise it will be trouble to deal with
STARTDATE=$(ffprobe -loglevel 0 -print_format json -show_format -show_streams "${INPUT}" | jq -r .format.tags.creation_time)

if [[ -z "${STARTDATE}" ]]; then
    echo "ERROR - No creation_time in metadata! ${INPUT}"
    exit 1
fi

# Convert the date to EPOCH. This will be used to set the time for the draw text method.
EPOCH=$(date --date=${STARTDATE} +%s)

echo "Video Create Time: ${STARTDATE} (${EPOCH})"

# we assume that the STARTDATE is in UTC 0000, Zulu time, GMT and that we want to convert it to the local time on the computer.
ffmpeg -i "${INPUT}" -vf drawtext="fontsize=30:fontcolor=yellow:text='%{pts\:localtime\:${EPOCH}}':x=(w-text_w) - 10:y=(h-text_h) - 10" -vcodec libx265 -crf 28 "${OUTPUT}"

if [ ${3:-"invalid"} == "--over-write" ]; then

    echo "Moving ${OUTPUT} -> ${INPUT}"
    mv "${OUTPUT}" "${INPUT}"

else
    echo "To overwrite the existing video, use --over-write"
fi

I did notice that the GoPro we were using didn’t have the correct time embedded in the video. It was the local time with no timezone. The above script would attempt to convert the time to local time and the stamp would be wrong. I wrote the following script to fix that issue. It extracts the creation_time, removes the timezone and assigns the local timezone. It then converts this back to UTC and write it back to the video.

#!/usr/bin/env bash

# -----------
# SPDX-License-Identifier: MIT
# Copyright (c) 2022 Troy Williams

# uuid       = e577e81c-f938-11ec-9c1a-0d95d112ee30
# author     = Troy Williams
# email      = troy.williams@bluebill.net
# date       = 2022-07-01
# -----------

# This script will take the video and correct the creation time issue with it.
# It assumes that the the creation time did not have the proper timezone set.
# This means that other programs will attempt to convert from GMT/Zulu time and
# get the wrong time stamp.

# This script assumes that the video has the correct local time, but was
# inserted without a timezone. It will extract that time, and configure it as a
# local time. It will then convert the local time properly to UTC +00:00 and
# write it back to the video.

# Generally this script would be executed before the `timestamp.sh` script.

# Usage:

# List the creation time and what it would be in local time:
# $ ./correct_times.sh GX013443.MP4

# Write the corrected local time to the video.
# $ ./correct_times.sh GX013443.MP4 --update

# Write the corrected local time to the video.and overwrite the existing file
# $ ./correct_times.sh GX013443.MP4 --update --over-write

# loop through files in a folder:
# $ for FILE in ./2022-06-28/*; do ./correct_times.sh "${FILE}"; done
# $ for FILE in ./2022-06-28/*; do ./correct_times.sh "${FILE}" --update; done
# $ for FILE in ./2022-06-28/*; do ./correct_times.sh "${FILE}" --update --over-write; done


# Requirements:

# JSON parser: $ sudo apt install jq

# References

# https://stackoverflow.com/questions/16548528/command-to-get-time-in-milliseconds
# https://stackoverflow.com/questions/28016578/how-can-i-parse-create-a-date-time-stamp-formatted-with-fractional-seconds-utc
# https://serverfault.com/questions/1020446/linux-get-utc-offset-from-current-or-other-timezones-on-given-date-and-time
# https://man7.org/linux/man-pages/man1/date.1.html

# ----------------
# Set the script to halt on errors
set -e

if [[ -z "$1" ]]; then
    echo "USAGE: $ 1./correct_times video.mp4 --update --over-write"
    exit 1
fi

# Get the movie name
MOVIE=$1

# Extract the creation datetime

# # need to use raw mode `-r` in jq call to return a raw string otherwise it will be trouble to deal with
# CREATED=$(ffprobe -loglevel 0 -print_format json -show_format -show_streams ${MOVIE} | jq -r .format.tags.creation_time)
# echo "Video Create Time (Zulu):  ${CREATED}"

# # Convert the creation time to local time
# LOCALTIME=$(date --date="${CREATED}" "+%FT%T %z (%Z)")
# echo "Video Create Time (local): ${LOCALTIME}"

# # Does the date in the video, match the corrected string?
# D1=$(date +%s --date="${CREATED}")
# D2=$(date +%s --date="${LOCALTIME}")

# echo ${D1}
# echo ${D2}

# if [ ${D1} == ${D2} ]; then
#     echo "Same datetimes!"
# else
#     echo "Different datetimes!"
# fi


# need to use raw mode `-r` in jq call to return a raw string otherwise it will be trouble to deal with
CREATED=$(ffprobe -loglevel 0 -print_format json -show_format -show_streams ${MOVIE} | jq -r .format.tags.creation_time)

if [[ -z "${CREATED}" ]]; then
    echo "ERROR - No creation_time in metadata! ${MOVIE}"
    exit 1
fi

echo
echo "Video Create Time (Zulu):  ${CREATED}"

# Convert the creation time to local time
LOCALTIME=$(date --date="${CREATED}" "+%FT%T %z (%Z)")
echo "Video Create Time (local): ${LOCALTIME}"

echo "--------"
# strip the timezone from the string
STRIPPED=$(TZ=UTC date --date="${CREATED}" "+%FT%T")
echo "Video Create Time (without timezone):${STRIPPED}"

# Express the string in the local timezone
TO_LOCAL=$(date --date="${STRIPPED}" "+%FT%T %z (%Z)")
echo "Video Create Time (to local):${TO_LOCAL}"

echo "--------"
# convert the local time string to UTC
CONVERTED=$(TZ=UTC date --date="${TO_LOCAL}" "+%FT%T.%6NZ") # this is the correct time string
echo "Video Create Time (to UTC):${CONVERTED}"
echo

# Video Create Time (Zulu):  2022-06-28T12:34:27.000000Z
# Video Create Time (local): 2022-06-28T08:34:27 -0400 (EDT)
# --------
# Video Create Time (without timezone):2022-06-28T12:34:27
# Video Create Time (to local):2022-06-28T12:34:27 -0400 (EDT)
# --------
# Video Create Time (to UTC):2022-06-28T16:34:27.000000Z

# -----------

OUTPUT="${MOVIE%%.*}".corrected."${MOVIE##*.}"

if [ ${2:-"invalid"} == "--update" ]; then

    # Write the converted timezone to the video
    echo "Updating metadata ${MOVIE} -> ${OUTPUT}"
    ffmpeg -i "${MOVIE}" -c copy -metadata creation_time="${CONVERTED}" "${OUTPUT}"

    if [ ${3:-"invalid"} == "--over-write" ]; then

        echo "Moving ${OUTPUT} -> ${MOVIE}"
        mv "${OUTPUT}" "${MOVIE}"

    else
        echo "To overwrite the existing video, use --over-write"
    fi

else
    echo "To update the metadata use --update"
fi