How To: Create/Write ID3 tags using ffmpeg

Update: New article: How To: Dump and Load metadata with ffmpeg

I have received so many requests from my previous article, “ID3 tags on Windows using ffmpeg”, asking how to add, create or write ID3 tags with ffmpeg that I wrote this article in response.

The Basics

The option to write ‘tags’ to a file, known as metadata, is -metadata key="value". Here is a basic example:

You repeat the option once for each key/value pair you want to add to your file like this:

If you want to clear or delete a certain key/value pair, include the key but leave the value blank like this:

The examples shown above are the very basic. While they will work and will produce a file, there are more options that need to be included to achieve the desired results.

Adding, creating, deleting, or clearing ID3 tags in ffmpeg is very simple. The hard part is figuring out what items you want and what the ‘key’ names are. For example, in Windows you can right-click on the audio file, select ‘Properties’, then click on the ‘Details’ tab. There are several Property/Value pair items listed; "Title", "Subtitle", "Comments", "Contributing artists", "Album artist", "Album", etcetera. Similar information is available in iTunes by right-clicking on a name, choose ‘Get Info’, then click on the ‘Info’ tab. The following table may help you decide:

I suggest you experiment with the different keys to find what works best for you.

A little more advanced

Lets look at some more advanced options you can use to manipulate metadata. For example, if you want to clear or delete all the global metadata in a file. You could use the examples above and include the key and a blank value for each item but that could make your command line very long. Instead you can use -map_metadata -1 instead. Here it is in a command line:

Setting -map_metadata to -1 (negative one) tells ffmpeg to use a non-existent input thereby clearing or deleting all the global metadata.

You can get the metadatainformation for a media file by including a input file with no output file like this:

FFmpeg is also able to dump metadata from media files into a simple UTF-8 encoded INI-like text file and then load it back using the metadata muxer/demuxer. Use a command line like the following to create the text file:

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. At the beginning of a chapter section there may be an optional timebase to be used for start/end values. It must be in the form ‘TIMEBASE=num/den’, where num and den are integers. If the timebase is missing then start/end times are assumed to be in milliseconds. Next a chapter section must contain chapter start and end times in the form ‘START=num’, ‘END=num’, where num is a positive integer.
8. Empty lines and lines starting with ‘;’ or ‘#’ are ignored.
9. Metadata keys or values containing special characters (‘=’, ‘;’, ‘#’, ‘\’ and a newline) must be escaped with a backslash ‘\’.
10. 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’).

A ffmetadata file might look like this:

;FFMETADATA1
title=bike\\shed
;this is a comment
artist=FFmpeg troll team

[CHAPTER]
TIMEBASE=1/1000
START=0
#chapter ends at 0:01:00
END=60000
title=chapter \#1
[STREAM]
title=multi\
line

You can edit the ffmetadata text file to include, change, or remove metadata by loading it into your media file.

To load the file and include the metadata in the output file, use -map_metadata like this:

The inputs -i in ffmpeg are counted zero-based. What that means is the first input from the command line example above -i in.mp3 is input number zero. The next input -i metadata.txt is input number one. So using -map_metadata 1 we are telling ffmpeg to map the metadata from input one, our text file, to the global metadata of the output file.

Remember the Version

If you are planning on using the media files with metadata on Windows, DO NOT forget to use these options in your command line:

-id3v2_version 3
-write_id3v1 1

As shown in Example 7 above.