mp3info(1)

🎀 mp3info — the manual, but make it make sense 💖

okay bestie, gather round, because this is mp3info, and it lives in section 1 of the General Commands Manual. it's the little tool that reads and edits ID3 tags and also tells you nerdy technical stuff about your MP3s. you're gonna love her. 🫶

---

✨ NAME ✨

mp3info — MP3 technical info viewer and ID3 tag editor 🌸

---

💅 SYNOPSIS 💅

mp3info [ -h | -G ]

mp3info [-x] [-F] [-r a|m|v] [-p FORMAT_STRING] file...

mp3info [-d] file...

mp3info [-i] [-t title] [-a artist] [-l album] [-y year] [-c comment]
[-n track] [-g genre] file...

---

🦋 DESCRIPTION 🦋

mp3info is a utility that reads and modifies the ID3 tags inside MPEG layer 3 (MP3) files. it can also (optionally, like a little bonus) show you various technical attributes of the MP3 file. yes ma'am. 👑

---

🔥 OPTIONS 🔥

• -a artist — set the ID3 artist name
• -c comment — set the ID3 comment
• -g genre — set the ID3 genre (run the -G option if you need the list of valid genres). you can give either a genre name or a genre number. your call, main character ✨
• -l album — set the ID3 album name
• -n track — set the ID3 v1.1 track number
• -t title — set the ID3 track title
• -y year — set the ID3 copyright year
• -G — display a list of valid genres and their associated numeric codes. these are the only values the -g switch will accept, no cap.
• -h — display a help page
• -x — display technical attributes of the MP3 file
• -r a|m|v — report the bit rate of Variable Bit Rate (VBR) files as one of these (peep the Bit Rates section below if you want the full lore):
  • a — Average bit rate [float] (heads up: this option also makes the bit rates of non-VBR files print as floating point values)
  • m — Median bit rate [integer]
  • v — just literally use the word 'Variable' [string] (this is the default)
• -i — edit the ID3 tag interactively (uses curses/ncurses functions)
• -d — delete the ID3 tag (if one exists)
• -f — Force Mode: treat all files as MP3s even if MP3 frames can't be found
• -F — do a Full scan for technical information (the Speed Considerations section below explains why you'd do this)
• -p "FORMAT_STRING" — print MP3 attributes according to FORMAT_STRING.

FORMAT_STRING is giving printf(3) energy: it gets printed verbatim, except for the conversions and escape sequences below. any conversion specifier may optionally include the various alignment, precision, and field width modifiers that printf(3) accepts. the EXAMPLES section further down has examples of how format strings get used in mp3info.

🌈 Conversion Specifiers 🌈

• %f — Filename without the path [string]
• %F — Filename with the path [string]
• %k — File size in KB [integer]
• %a — Artist [string]
• %c — Comment [string]
• %g — Musical genre [string]
• %G — Musical genre number [integer]
• %l — Album name [string]
• %n — Track [integer]
• %t — Track Title [string]
• %y — Year [string]
• %C — Copyright flag [string]
• %e — Emphasis [string]
• %E — CRC Error protection [string]
• %L — MPEG Layer [string]
• %O — Original material flag [string]
• %o — Stereo/mono mode [string]
• %p — Padding [string]
• %v — MPEG Version [float]
• %u — Number of good audio frames [integer]
• %b — Number of corrupt audio frames [integer]
• %Q — Sampling frequency in Hz [integer]
• %q — Sampling frequency in kHz [integer]
• %r — Bit Rate in kbps (its type and meaning are affected by the -r option)
• %m — Playing time: minutes only [integer]
• %s — Playing time: seconds only [integer] (usually used in conjunction with %m)
• %S — Total playing time in seconds [integer]
• %% — A single percent sign

🧚 Escape Sequences 🧚

• \n — Newline
• \t — Horizontal tab
• \v — Vertical tab
• \b — Backspace
• \r — Carriage Return
• \f — Form Feed
• \a — Audible Alert (terminal bell)
• \xhh — Any arbitrary character specified by the hexadecimal number hh
• \ooo — Any arbitrary character specified by the octal number ooo
• \\ — A single backslash character

---

💜 USAGE 💜

• Specifying MP3 files without any other options displays the existing ID3 tag (if any).
• Specifying a track number of 0 reverts an ID3 tag to 1.0 format.
• Non-specified ID3 fields, if existent, will remain unchanged. she's respectful like that 🫶
• Genres can be specified as numbers or names: -g 17 same as -g Rock
• Multiple word fields must be enclosed in quotes (eg: -t "A title")

---

⭐ NOTES ⭐

🌸 Speed Considerations 🌸

so, to determine certain technical attributes (playing time, number of frames, number of bad frames, and in a few cases the bit rate) with absolute certainty, you'd have to read the entire MP3 file. mp3info normally tries to speed things up by reading a handful of frames from various points in the file and estimating the statistics for the rest of the file based on those samples. usually this results in very accurate estimates — audio playing times are usually off by no more than a second, and the number of frames is off by less than 0.1%. often the estimates agree exactly with the full scans. still, the user may wish to ensure that she is getting exact information.

you should specify the -F switch if you want mp3info to read the entire MP3 file when determining this information. note that a full scan will only affect mp3info's output if the -x switch is used, or the -p switch is used with a FORMAT_SPECIFIER containing %m, %s, %S, %u or (rarely) %r. using the -F switch under other conditions will only slow mp3info down. also note that a FORMAT_SPECIFIER containing %b, or a VBR MP3 file, will automatically trigger a full scan even if the -F switch is not used. 🔥

several users have noted that the %u specifier used alone:

mp3info -p "%u" song.mp3

sometimes gives a different number of good frames than when it's used with the %b specifier:

mp3info -p "%u %b" song.mp3

this is because when you use %u by itself, mp3info only estimates the number of frames based on the bitrate and the size of the file. when you use the %b specifier, you force mp3info to do a full scan of the file, which guarantees an accurate count of both the good and bad frames. if you want to guarantee an accurate count of the number of good frames when using %u by itself, you should use the -F option. 💀

🎀 Bit Rates 🎀

MP3 files are made up of many (usually several thousand) audio blocks called 'frames'. each of these frames is encoded at a specific 'bit rate' which determines both the quality of the sound and the size of the frame itself. bit rates can range from 8 Kb/s (kilobits per second) to 320 Kb/s. note that the MP3 specification only allows 14 discreet bit rates for an MP3 file, so, for instance, a stereo MP3 could have frames with bit rates of 128 Kb/s and 160 Kb/s, but nowhere in between. ✨

audio frames with high bit rates sound much better than those with lower bit rates, but take up more space. obviously, one would like to use a bit rate that is only high enough to maintain a comfortable level of audio quality. normally, all the frames in an MP3 file are encoded at the same bit rate. a few MP3 files, however, are encoded such that the bit rate may vary from one frame to the next. these MP3 files are called Variable Bit Rate (or VBR) files. since VBR files do not have one single bit rate, attempting to report the bit rate of the file as a whole can be problematic. consequently, mp3info allows you to specify how you want this value reported. 💅

the default is to simply print the word 'Variable' where the bit rate would normally appear. another option is to print the mathematical average of all the frames. this has the advantage of being completely accurate, but the number printed may not correspond to one of the 14 discreet bit rates that would be allowed for that file. the third alternative solves that problem by allowing the bit rate to be reported as the median bit rate, which is what you would get if you lined up all the frames in the file by bit rate from lowest to highest and picked the frame closest to the middle of the line. 👑

for more specific usage information, see the -r switch and the %r conversion specifier under the description of -p's FORMAT_SPECIFIER.

💅 EXAMPLES 💅

Okay bestie, this is the fun part — let's actually do stuff. ✨

---

🌸 Show me what's in there already

Wanna see the existing ID3 tag info (if there even is any) in song.mp3?

mp3info song.mp3

That's it. That's the whole vibe check. 💖

---

🎀 Set title, artist, genre

Set the title, author and genre of song.mp3 — and every other field stays exactly how it was, no touchy:

mp3info -t "Song Title" -a Author -g "Rock & Roll" song.mp3

Look at her go. 👑

---

🦋 Album for the whole directory

Set the album field of all MP3 files in the current directory to "The White Album":

mp3info -l "The White Album" *.mp3

One command, whole discography sorted. Iconic.

---

💀 Yeet the entire tag

Delete the entire ID3 tag from song1.mp3 and song2.mp3:

mp3info -d song1.mp3 song2.mp3

Gone. Ghosted. Not a single byte left behind. 🫶

---

🌈 Just the comment field, thanks

Delete the comment field from the ID3 tags of all MP3 files in the current directory. All other fields stay completely untouched:

mp3info -c "" *.mp3

Empty string = "please remove this bestie". 💅

---

⭐ A little custom output moment

Display the Title, Artist, Album, and Year of all MP3 files in the current directory. We include the labels like File, etc. and insert newlines (\n) to make things more readable for humans:

mp3info -p "File: %f\nTitle: %t\nArtist: %a\nAlbum: %l\nYear: %y\n\n" *.mp3

Labels? Slayed. Newlines? Slayed. Human-readable? Absolutely.

---

🍓 Spreadsheet girlies, this one's for you

Say you want to build a spreadsheet of your MP3 files. Here's a command you might use to help you accomplish that. Most spreadsheet programs will import an ASCII file and treat a given character as a field separator. A commonly used field separator is the tab character. For each MP3 file in the current directory, we want to output the filename, title, artist, and album on a single line and have the fields separated by a tab (\t) character. Note that you must include a newline (\n) at the end of the format string in order to get each file's information on a separate line. Here's the command:

mp3info -p "%f\t%t\t%a\t%l\t%y\n" *.mp3

No cap, this is the one you'll actually use. 🧚

---

🌸 Fixed-width fields, because some software is picky

Some spreadsheets or other software may allow importing data from flat files where each field is a specific width. Here's where the format modifiers come into play. This next command outputs the same information as the command above, but uses fixed-width fields instead of tab separators. The filename field is defined as 50 characters wide, the title field is defined as 31 characters wide, and so on.

mp3info -p "%50f%31t%31a%31l%4y\n" *.mp3

---

😭 The right-justify problem (and the fix)

The problem with the output of this command is that all strings are normally right-justified within their fields. This looks a little odd since most western languages read from left to right. In order to make the fields left-justified, add a minus sign (-) in front of the field-width:

mp3info -p "%-50f%-31t%-31a%-31l%-4y\n" *.mp3

One tiny dash and suddenly everything reads like a normal person wrote it. The way that minus sign just fixes the whole vibe. ✨

---

💜 Running time, minutes and seconds

Now suppose you just want the running time of each MP3 file specified in minutes and seconds. Simple enough:

mp3info -p "%f: %m:%s\n" *.mp3

---

🎀 The leading-zero glow-up

You may notice when you do this, however, that leading zeros are not displayed in the seconds field (%s). So for instance, if you had a track four minutes and two seconds long its running time would be displayed as 4:2 instead of 4:02. In order to tell mp3info to pad an integer field with zeros, you need to use a field width modifier and place a zero in front of it. The following command is the same as the previous one, but it specifies that mp3info is to display the seconds field with a fixed field-width of two characters and to pad the field with leading zeros if necessary:

mp3info -p "%f: %m:%02s\n" *.mp3

4:2 is not the moment. 4:02 is the moment. 🕐

---

🔥 Precision specifier for floats

The last trick we have to show you is the precision specifier for floating point variables. The following command displays the filename and average bit rate for all MP3 files in the current directory.

mp3info -r a -p "%f %r\n" *.mp3

By default, the floating point value of the average bit rate is displayed with six digits past the decimal point (ex: 175.654332). If you are like me, this seems like a bit of overkill. At most you want one or two digits beyond the decimal place displayed. Or you might not want any. The following command displays the average bit rate with first two, then zero digits beyond the decimal point:

mp3info -r a -p "%f %.2r %.0r\n" *.mp3

Six digits of decimals is giving "I copied my output straight out of a debugger". Two is giving taste. 💅

---

🦋 Field width and precision, together

If you wanted to specify a field width for a floating point value, you could do that by placing the field-width before the decimal point in the field modifier. This command does just that — specifying an average bit-rate field six characters wide that will show two digits of precision beyond the decimal point:

mp3info -r a -p "%f %6.2r\n" *.mp3

---

💀 BUGS 💀

Okay bestie, here's the tea. ☕ Read this part, fr fr.

• There's no "save and quit" in interactive mode. You must fill in all the fields (even if it is with blanks) and let the program finish by itself. CTRL+C does leave MP3info, but the data isn't saved.
• Using space to erase tags in interactive mode does not work correctly if you then backspace over the deleted text.
• The title, author, album, and comment fields are limited to 30 characters. This is a limitation of the ID3 1.0 tag format, not MP3Info. If you specify the track number (with the -n switch), the ID3 1.0 tag becomes a 1.1 tag and the comment field is limited to 28 characters. This is because the difference between ID3 1.0 and 1.1 is that the tag number is stored in the last byte of the comment field. This trick "borrows" two bytes from the fixed-length comment field effectively reducing the maximum comment by two characters.
• Genres cannot be specified arbitrarily. They must be specified from a pre-determined list (use mp3info -G to see that list). Again, this is a limitation of the ID3 1.0 tag format.
• Only ID3 versions 1.0 and 1.1 are supported. ID3V2 is a much more powerful standard and is planned for some as-yet-undetermined future version. Unfortunately, a clean implementation is a heck of a lot of work and I'm unbelievably lazy, so don't hold your breath. It is probably worth noting at this juncture, however, that I do accept patches. :-)
• Exit codes are somewhat haphazard and not well documented.

Real talk though: that CTRL+C one will absolutely eat your tags. Save yourself the heartbreak and let it finish. 😭

---

👑 AUTHOR 👑

Cedric Tefft <cedric@phreaker.net>

Living legend behavior. Respect. 🫶

---

🌈 SEE ALSO 🌈

• printf(3)

---

And that's the whole page, bestie!! This beauty is mp3info(1), and the version we just read through is dated November 6, 2006 — an actual vintage icon, still out here tagging your MP3s like it's nobody's business. 💖✨🎀 Go forth, tag responsibly, and don't you dare hit CTRL+C. 🦋