mpv-gopro-timecode

An mpv Lua script that displays the actual embedded timecode from GoPro videos as an on-screen overlay.

GoPro cameras record a time-of-day timecode track (tmcd) in every MP4 file. This script reads that timecode and adds the current playback position to show the real wall-clock time on screen — so you always know exactly when something happened.

Why not just use file timestamps?

Other scripts (like mpv-abstime-osd) estimate the recording time by subtracting the video duration from the file's modification date. That approach breaks when files are copied, re-encoded, or merged. This script reads the actual timecode embedded by the camera, which survives all of that.

Installation

Copy (or symlink) gopro-timecode.lua into your mpv scripts directory:

# Linux / macOS
mkdir -p ~/.config/mpv/scripts
cp gopro-timecode.lua ~/.config/mpv/scripts/

# or symlink for development
ln -s "$(pwd)/gopro-timecode.lua" ~/.config/mpv/scripts/

Requirements

• mpv (tested with v0.41+)
• ffprobe (part of FFmpeg, used as a fallback to extract the timecode)

Both are likely already installed if you're using mpv on Linux.

Usage

Just play a GoPro video:

mpv your_gopro_video.MP4

The timecode appears automatically in the bottom-left corner if the file contains an embedded timecode track.

Key	Action
Alt+t	Toggle the timecode overlay on/off

How it works

1. When a file is loaded, the script looks for a timecode tag in the video metadata
2. If not found there, it falls back to running ffprobe to read the tmcd (timecode) data stream
3. The starting timecode (e.g. 12:00:33;01) is parsed into seconds since midnight
4. As the video plays, the current playback position is added to display the running wall-clock time
5. The time is rendered as an ASS overlay: white text, black outline, top-right corner

Supported formats

• GoPro MP4 files (any model that writes a tmcd track — HERO5 and newer)
• Merged/concatenated GoPro files (the timecode from the first segment is preserved)
• Any other video with a standard tmcd timecode track

Drop-frame timecode

GoPro cameras at 29.97 fps use drop-frame timecode (indicated by a ; separator). The script detects this automatically. Since the overlay shows HH:MM:SS (not individual frames), drop-frame vs. non-drop-frame makes no practical difference for the display.

License

This project is licensed under the GNU General Public License v2.0 or later, with portions under the GNU Lesser General Public License v2.1 or later. See LICENSE.GPL and LICENSE.LGPL for details.