Write Custom Timecode to MP4 with FFmpeg

Writing custom timecode metadata into QuickTime and MP4 files is a standard requirement for professional post-production workflows, archiving, and editing software compatibility. FFmpeg allows you to inject or overwrite custom timecode values into a file's container metadata—including the QuickTime user data (udta) atom and dedicated timecode tracks—quickly and efficiently without re-encoding your original video and audio streams.

Basic Timecode Injection via Stream Copy

To write a starting timecode into an existing MP4 or MOV container without re-encoding, use the -c copy flag along with the -timecode option:

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

This command parses the input, copies the audio and video packets directly, and writes a standard timecode track (tmcd) and the corresponding metadata into the output container.

Non-Drop-Frame vs. Drop-Frame Format

FFmpeg expects the timecode format to reflect the video stream's frame rate:

  • Non-Drop-Frame (NDF): Use colons throughout (e.g., 01:00:00:00).
  • Drop-Frame (DF): Use a semicolon before the frame count (e.g., 01:00:00;00) for standard fractional broadcast rates like 29.97 fps.

Targeting QuickTime/MP4 User Data (udta) Specifically

QuickTime (.mov) and ISO Base Media (.mp4) handle timecode tracks differently. QuickTime natively expects both a dedicated tmcd track and container-level metadata tags. To ensure maximum compatibility with Apple Pro Apps and other digital asset management systems, explicitly enforce timecode track creation:

ffmpeg -i input.mov -c copy -write_tmcd 1 -timecode 10:00:00:00 output.mov

If you only want to set a generic metadata key inside the container rather than generating a full timecode track, you can assign it directly to the video stream or container metadata tag:

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

Verifying the Applied Timecode

To verify that the custom timecode was properly written to the metadata atoms, inspect the file using ffprobe:

ffprobe -v error -show_entries stream_tags=timecode:format_tags=timecode output.mp4

Alternatively, running a standard ffprobe output.mp4 command will display the active timecode tag under the stream or format metadata section.