id3-ffmpeg.md

Get/set ID3 meta tags using ffmpeg

A quick guide on how to read/write/modify ID3 metadata tags for audio / media files using ffmpeg.

FFmpeg has a free-form command line option that allows the user to specify key-value-pairs for encoding metadata. Let's take a look.

1. Read ID3 metadata

To list all global metadata tags for a media file, just set an input but no output file.

Code example(s):

ffmpeg -i file.mp3

^{Example 1: List all ID3 metadata tags for input file.}

---

Unfortunately, there's no build-in option to get just a specific tag's value. But here's a bash one-liner to get that done.

# Get the value for the "title" ID3 metadata tag
ffmpeg -i file.mp3 2>&1 |grep -E '^\s*title\s*\:\s.*$' |awk -F ': ' '{print $2}'

^{Example 2: Get the value of a specific ID3 metadata tag for input file.}

2. Write/modify ID3 metadata

To write "metadata" (a.k.a. ID3 metadata tags) to an audio file, or to modify or delete it, ffmpeg offers the -metadata option, which accepts metadata tags as key-value-pairs.

Here are some basic examples:

Code example(s):

The most basic use of the -metadata option is to set a single ID3 tag.

For example, to set the title tag for an mp3 file, use:

ffmpeg -i file.mp3 -metadata title="Track Title" out.mp3

^{Example 3: Set a single ID3 metadata tag.}

---

You can also set multiple tags at once by creating an option list, as follows:

ffmpeg -i file.mp3 -metadata title="Track Title" -metadata artist="Rockstar" -metadata album="Hot Shit" out.mp3

^{Example 4: Set multiple ID3 metadata tags.}

Description:

Adding, creating, deleting, or clearing ID3 tags with ffmpeg is very simple. The hard part is figuring out what items you want and what the correct tag key names are.

Whether the metadata key-value-pairs are actually encoded into the output file is dependent upon the file format being muxed. Many formats only support a handful of metadata keys.

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 tries to document which keys ffmpeg will encode into which formats.

Windows	ID3v1.1	ID3v2.3	iTunes	Low-level identifier	ffmpeg key	ffmpeg example
Title	title	TIT2	Name / Title	\251nam	title	-metadata title="Track Title"
Subtitle	n/a	TIT3	Description	?	TIT3	-metadata TIT3="Live-Edit"
Comments	comment	COMM	Comments	\251cmt	comment	-metadata comment="Extra info text"
?	n/a	?	Description	\desc	description	-metadata description="Description text: Lorem ipsum ..."
Contributing artists	artist	TPE1	Artist	\251ART	artist	-metadata artist="Artist Name"
Album artist	n/a	TPE2	Album Artist	aART	album_artist	-metadata album_artist="Artist Name"
Album	album	TALB	Album	\251alb	album	-metadata album="Album Title"
Year	year	TYER	Year	\251day	date	-metadata date="1985"
#	track	TRCK	Track Number	trkn	track	-metadata track="2/5" (means 2 of 5)
?	n/a	TRACKTOTAL	?	?	TRACKTOTAL	-metadata TRACKTOTAL="12"
Part of set	n/a	TPOS	Disc Number	?	disc	-metadata disc="1/3" (means 1 of 3)
Genre	genreid	TCON	Genre	\251gen	genre	-metadata genre="Rock"
?	n/a	?	Grouping	\251grp	grouping	-metadata grouping="?"
Composer	n/a	?	Composer	\251wrt	composer	-metadata composer="Composer Name"
Producer	n/a	?	Producer	?	producer	-metadata producer="Producer Name"
Publisher	n/a	?	?	?	publisher	-metadata publisher="Publisher Name"
Copyright	n/a	?	?	\251cpy	copyright	-metadata copyright="(c) YYYY Copyright Holder Name"
Author URL	n/a	?	?	?	author_url	-metadata author_url="http://example.com/"
?	n/a	?	?	?	encoder	-metadata encoder="Lavf57.56.100"

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

But for now, lets look at some more (advanced) options you can use to manipulate metadata..

3. Clear/delete ID3 metadata

Deleting a global ID3 metadata tag is easy, too.

Code example(s):

To clear/delete a certain metadata tag, set the tag key but leave the value blank, like this:

ffmpeg -i file.mp3 -metadata album="" out.mp3

^{Example 5: Clear an ID3 metadata tag.}

---

Now, if you want to clear/delete all global metadata tags in a file, you could use a command like in example 4 above and just include all the tag's key and a blank value for each item. Buuuut.. that could make your command line very long.

Instead you can use -map_metadata -1. Setting -map_metadata to -1 (negative one) tells ffmpeg to use a non-existent input, and thereby clearing/deleting all global metadata tags.

ffmpeg -i file.mp3 -map_metadata -1 out.mp3

^{Example 6: Delete/clear all global metadata tags.}

4. Dump ID3 metadata to file

Another way to get and set ID3 metadata is to use ffmpeg's metadata muxer/demuxer with (ff)metadata files - simple UTF-8 encoded INI-like text files containing all global metadata information.

Code example(s):

To dump all metadata information of a media file to a (ff)metadata text file, use:

ffmpeg -i file.mp3 -f ffmetadata metadata.txt

^{Example 7: Dunp all global metadata of a media file to a (ff)metadata text file.}

Description:

The MPEG audio file format is (roughly) as follows:

• A file consists of a header and various metadata tags divided by linefeed-separated sections.
• The header starts with the string ;FFMETADATA, followed by a version number.
• Metadata tags are represented as key-value-pairs (key=value).
• Immediately after the header follows global metadata.
• After global metadata there may be sections with per-stream/per-chapter metadata.
• 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.
• Empty lines and lines starting with ; or # are ignored.
• Metadata keys or values containing special characters (=, ;, #, \ and a newline) must be escaped with a backslash (\).
• 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)).

Result:

The (ff)metadata text file that ffmpeg created from the command above, 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

5. Load/apply ID3 metadata from file

Finally, we want to load all metadata for an media file from a (ff)metadata text file and then apply it to an output file.

Note: ffmpeg uses UTF-8 encoding. So, whenever you create or modify a (ff)metadata file, make sure your text editor supports (and uses) UTF-8 encoding!

Code example(s):

So, to load metadata from a (ff)metadata text file and create/encode an mp3 output file with ID3 v2.4 tags (default version) from it, type:

ffmpeg -i file.mp3 -i metadata.txt -map_metadata 1 -c:a libmp3lame -ar 44100 -b:a 192k -write_id3v2 1 -f mp3 out.mp3

^{Example 8: Encode an mp3 file, creating ID3 tags from a (ff)metadata text file.}

---

If you are planning on using the media files with metadata on Windows, do not forget to use both the options to specify ID3 v1 and v2 versions as follows:

ffmpeg -i file.mp3 -i metadata.txt -map_metadata 1 -c:a libmp3lame -ar 44100 -b:a 192k -id3v2_version 3 -write_id3v1 1 -f mp3 out.mp3

^{Example 9: Encode an mp3 file, creating Windows-compatible ID3 tags from a (ff)metadata text file.}

Description:

To help you understand all the options, lets break down that last command:

• ffmpeg - call the ffmpeg programm
• -i "file.mp3 - the media input file (input stream zero (0))
• -i metadata.txt - the (ff)metadata text input file (input stream one (1))
• -map_metadata 1 - tell ffmpeg where to find the metadata -
  a.k.a. map metadata to input stream one (1)
• -ar 44100 - the output file audio sampling rate (in Hz)
• -c:a libmp3lame - the output file audio codec to use to encode
• -b:r 192k - the output file audio bit rate
• -id3v2_version 3 - the ID3v2 version, force creating v2.3 tags (default: v2.4)
  (Required because Windows only supports version 3 of ID3v2 tags!)
• -write_id3v1 1 - the ID3v1 version to create legacy v1.1 tags (disabled by default)
• -f mp3 - the output file format (this will force a constant bit rate)
• out.mp3 - the output file

6. Final notes

That is all there is to it. Pretty simple, he?

References, sources, helpful links:

• FFmpeg - official website
• FFmpeg for Windows
• FFmpeg mp3 muxer/demuxer reference
• FFmpeg metadata reference - wiki.multimedia.cx
• Jon Hall 1, Jon Hall 2