Write Custom Timecode to MOV with FFmpeg

This article explains how to configure and write custom timecode metadata to a QuickTime MOV container using FFmpeg. You will learn the specific command-line arguments required to embed a precise starting timecode, handle drop-frame and non-drop-frame formats, and write this metadata efficiently without re-encoding your video.

The Basic Timecode Command

To write a custom starting timecode to an MOV container, use the -timecode option in FFmpeg. This option automatically creates a dedicated timecode track (tmcd) within the QuickTime MOV file, which is widely recognized by professional video editing software (NLEs) like Adobe Premiere Pro, DaVinci Resolve, and Final Cut Pro.

The basic syntax is as follows:

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

In this command: * -i input.mp4 specifies your source file. * -timecode 01:30:00:00 sets the starting timecode to 1 hour, 30 minutes, 0 seconds, and 0 frames. * -c:v copy -c:a copy copies the video and audio streams without re-encoding, preserving original quality and processing the file instantly. * output.mov is the destination file.

Drop-Frame vs. Non-Drop-Frame Timecode

Depending on your project’s frame rate, you must format the timecode string correctly to denote drop-frame or non-drop-frame timecode:

Non-Drop-Frame (e.g., 24fps, 25fps, 30fps, 50fps, 60fps): Use colons (:) as separators.
```
-timecode 12:00:00:00
```
Drop-Frame (e.g., 29.97fps, 59.94fps): Use a semicolon (;) or dot (.) before the frame number to specify drop-frame timecode, which prevents time drift.
```
-timecode 12:00:00;00
```

Writing Timecode During Re-encoding

If you are transcoding your video while adding the timecode, replace the stream copy flags with your desired video and audio encoders:

ffmpeg -i input.mkv -c:v libx264 -crf 23 -timecode 09:15:30:00 output.mov

Adding Timecode to Specific Streams

In complex files with multiple video streams, you can target a specific stream by adding the stream specifier to the metadata flag. For example, to apply the metadata to the first video stream:

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

Verifying the Timecode

To verify that the custom timecode was successfully written to the MOV container, run ffprobe on the output file:

ffprobe -v error -show_format -show_streams output.mov

Look for the tags section under the video stream or the dedicated tmcd stream, which will display the starting timecode value:

[STREAM]
...
codec_name=tmcd
TAG:timecode=01:30:00:00
[/STREAM]