How To: Dump and Load metadata with ffmpeg

In a previous article, "Create/Write ID3 tags using ffmpeg" (see Related articles below) I mention a feature of ffmpeg; dumping and loading metadata to and from a file. In this article I will show you how to do that.

Dump metadata to a file

The first thing we need to know is how ffmpeg uses a file for metadata. To do this lets create the file by dumping the metadata from a file that you know has metadata. I will use a m4a (aac) file from iTunes. The following command line will create a text file named "metadata.txt" in the directory you issue the command from.

The command starts like any other ffmpeg command. Call ffmpeg and pass in an input file. However, after the input file name, all we need is to tell ffmpeg we want to dump the metadata to a file by using the ‘format’ option: "-f ffmetadata" and specify an output file name.

The file format is as follows:

1. A file consists of a header and a number of metadata tags divided into sections, each on its own line.
2. The header is a ‘;FFMETADATA’ string, followed by a version number (now 1).
3. Metadata tags are of the form ‘key=value’.
4. Immediately after the header follows global metadata.
5. After global metadata there may be sections with per-stream/per-chapter metadata.
6. A section starts with the section name in uppercase (i.e. STREAM or CHAPTER) in brackets (‘[’, ‘]’) and ends with a new/next section or end of file.
7. Empty lines and lines starting with ‘;’ or ‘#’ are ignored.
8. Metadata keys or values containing special characters (‘=’, ‘;’, ‘#’, ‘\’ and a newline) must be escaped with a backslash ‘\’.
9. Note that whitespace in metadata (e.g. foo = bar) is considered to be a part of the tag (in the example above key is ‘foo ’, value is ‘ bar’ (Notice the space after foo and before bar)).

The ffmetadata file, "metadata.txt" that ffmpeg created from the command line above, looks like this:

;FFMETADATA1
major_brand=M4A 
minor_version=0
compatible_brands=M4A mp42isom
composer=Willie Royal
title=Napali
artist=Willie & Lobo
album=Caliente
genre=Jazz
track=2/11
date=1997
gapless_playback=0
encoder=iTunes v7.2.0.34, QuickTime 7.1.6
album_artist=Willie & Lobo

Some of the "key=value" pairs are unique to the m4a format like, "major_brand=M4A" and "compatible_brands=M4A mp42isom", but that shows you what the file looks like. Run the command line on some of your files to see more examples. Remember, the output file name can be any valid file name you like. I used "metadata.txt" just as an example.

Loading metadata from a file

Now that we have a text file with metadata, we want to use that file to load the metadata into our output file. This will create ID3 tags if we are encoding a mp3 file. In fact lets do that. We will create a mp3 file from the m4a file, that is in iTunes, that we used to dump the metadata from. Before we load the file we want to delete some of the "key=value" pairs from the "metadata.txt" file because we may not want that information in our mp3 file. You could also add new metadata by inserting new "key=value" line(s) to the text file. The previous article "Create/Write ID3 tags using ffmpeg" (see Related articles below) has a table with valid keys to use. Open the "metadata.txt" file in a text editor. (Note: ffmpeg uses UTF-8 encoding so be sure to use a text editor that can encode UTF-8 if you use any special characters unique to that charset.)  In our example, we want to delete the lines that are crossed out:

;FFMETADATA1
major_brand=M4A 
minor_version=0
compatible_brands=M4A mp42isom
composer=Willie Royal
title=Napali
artist=Willie & Lobo
album=Caliente
genre=Jazz
track=2/11
date=1997
gapless_playback=0
encoder=iTunes v7.2.0.34, QuickTime 7.1.6
album_artist=Willie & Lobo

Our saved text file now looks like this:

;FFMETADATA1
composer=Willie Royal
title=Napali
artist=Willie & Lobo
album=Caliente
genre=Jazz
track=2/11
date=1997
album_artist=Willie & Lobo

Here is the command line to load the metadata text file and encode (create) an mp3 file with ID3v2.3 tags:

Lets break down that command line so you can understand all the options being used:

• "ffmpeg32" - call the ffmpeg batch file created in the article "Setup and Use ffmpeg on Windows" (see Related articles below)
• "-i "02 Napali.m4a" - the m4a media input file. ffmpeg inputs are zero-based so this is input zero (0)
• "-i metadata.txt" - our metadata text input file. ffmpeg input number one (1)
• "-map_metadata 1" - tells ffmpeg where to find the metadata. This maps to input one (1), our text file
• "-ar 44100" - set the audio sampling rate (in Hz)
• "-c:a libmp3lame" - set the audio codec to use to encode the audio
• "-b:r 192k" - set the audio bit rate
• "-id3v2_version 3" - set the ID3v2 version to create v2.3 tags (Windows only recognizes version 2.3)
• "-f mp3" - set the output format. This will force a constant bit rate
• "02 Napali.mp3" - the output file

That is all there is to it. Pretty simple and useful. The best way to learn more about it is to use it. Enjoy!