Add Custom Metadata to MOV Files Using FFmpeg

This article explains how to write custom user metadata keys, such as "Director" or "CreationTime", into QuickTime (.mov) files using the FFmpeg command-line tool. You will learn the exact command-line syntax required to embed these tags and how to verify that the metadata has been successfully written to your output file without re-encoding your video.

The Basic FFmpeg Metadata Command

To add metadata to a QuickTime file, you use the -metadata option in FFmpeg. This option follows a key="value" format. To avoid re-encoding the video and audio streams, combine this with the -c copy flag, which performs a stream copy and preserves the original quality instantly.

Run the following command in your terminal to write custom metadata:

ffmpeg -i input.mp4 -c copy -metadata director="John Doe" -metadata creation_time="2023-10-27T10:30:00Z" output.mov

Understanding the Parameters

  • -i input.mp4: Specifies the input video file.
  • -c copy: Instructs FFmpeg to copy the video and audio streams without re-encoding them, making the process nearly instantaneous.
  • -metadata director="John Doe": Writes a custom metadata tag where the key is director and the value is John Doe.
  • -metadata creation_time="2023-10-27T10:30:00Z": Writes the creation time. Note that for standardized fields like creation time, FFmpeg uses the lowercase snake_case key creation_time and expects ISO 8601 format.
  • output.mov: The resulting QuickTime container file containing your embedded metadata.

Adding Arbitrary Custom Keys

QuickTime containers support arbitrary custom metadata keys via the "keys" atom. You can define entirely custom fields that are not part of the standard QuickTime specification:

ffmpeg -i input.mov -c copy -metadata project_name="Apollo" -metadata camera_model="Red V-Raptor" output_custom.mov

FFmpeg will automatically write these custom key-value pairs into the metadata track of the .mov container.

How to Verify the Metadata

Once the file is generated, you can verify that the custom metadata keys were written correctly using ffprobe, which is included with your FFmpeg installation. Run the following command:

ffprobe -hide_banner -show_format output_custom.mov

Look at the [FORMAT] section of the output. Under TAGS, you will see your custom metadata keys and their assigned values displayed clearly.