Write Custom Timecode Metadata to MP4 with FFmpeg

This guide explains how to write custom timecode metadata into the QuickTime/MP4 user data (udta) atom using FFmpeg. You will learn the specific command-line arguments required to inject standard timecode tracks and custom metadata tags into your video files for seamless integration with professional editing software.

Method 1: Adding a Standard QuickTime Timecode Track (tmcd)

The most robust way to add a timecode to a QuickTime (MOV) or MP4 file is to write a dedicated timecode track (tmcd). This track is natively recognized by video editing software like Adobe Premiere, DaVinci Resolve, and Final Cut Pro.

Run the following command to apply a starting timecode without re-encoding the video:

ffmpeg -i input.mp4 -c copy -timecode 01:30:00:00 output.mp4

• -c copy: Copies the video and audio streams without re-encoding, preserving quality and processing instantly.
• -timecode 01:30:00:00: Sets the starting timecode (Format: HH:MM:SS:FF for non-drop frame, or HH:MM:SS;FF for drop frame).

Method 2: Writing Custom Timecode to the User Data Atom (udta)

If you need to write the timecode as a text-based metadata key inside the QuickTime user data (udta) atom rather than a dedicated track, you can use FFmpeg’s -metadata flag.

Run this command to write custom timecode metadata:

ffmpeg -i input.mp4 -c copy -metadata "timecode=01:30:00:00" output.mp4

Method 3: Using QuickTime Metadata Tags

To ensure that custom metadata is written properly into the QuickTime-specific container format (using the keys or udta atoms), use the -movflags use_metadata_tags option. This forces FFmpeg to write standard and custom metadata keys in a format compatible with Apple devices and software.

ffmpeg -i input.mp4 -c copy -movflags use_metadata_tags -metadata "com.apple.quicktime.timecode=01:30:00:00" output.mp4

Verifying the Metadata

To verify that the timecode metadata was written successfully to the MP4/MOV container, use FFmpeg’s companion tool, ffprobe:

ffprobe -show_format -show_streams output.mp4

Look for the TAG:timecode or the handler name tmcd in the console output to confirm the presence of your custom timecode.