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 used to read and modify the ID3 tags in MPEG layer
3 (MP3) files. It can also (optionally) display various technical
attributes of the MP3 file.
OPTIONS
-a artist
Specify ID3 artist name
-c comment
Specify ID3 comment
-g genre
Specify ID3 genre (use -G option for a list of valid genres).
You may specify either a genre name or a number.
-l album
Specify ID3 album name
-n track
Specify ID3 v1.1 track number
-t title
Specify ID3 track title
-y year
Specify ID3 copyright year
-G Display a list of valid genres and their associated numeric
codes. These are the only values accepted by the -g switch.
-h Display a help page
-x Display technical attributes of the MP3 file
-r a|m|v
Report bit rate of Variable Bit Rate (VBR) files as one of the
following (See the section below entitled Bit Rates for more
information):
a - Average bit rate [float](Note: this option also causes the
bit rates of non-VBR files to be displayed as floating
point values).
m - Median bit rate [integer]
v - Simply use the word ’Variable’ [string] (this is the
default).
-i Edit ID3 tag interactively (uses curses/ncurses functions)
-d Delete 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 (see the section Speed
Considerations below for more information)
-p "FORMAT_STRING"
Print MP3 attributes according to FORMAT_STRING. FORMAT_STRING
is similar to a printf(3) format string in that it is printed
verbatim except for the following conversions and escape
sequences. Any conversion specifier may optionally include the
various alignment, precision, and field width modifiers accepted
by printf(3). See the EXAMPLES section below for examples of
how format strings are 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 (type and meaning affected by -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 hexidecimal
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 existant, will remain unchanged.
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
In order 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, it would be necessary 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.
Nevertheless, the user may wish to ensure that she is getting
exact information.
One should specify the -F switch if one wants 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 down mp3info. 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 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 (usally 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
Display existing ID3 tag information (if any) in song.mp3
mp3info song.mp3
Set the title, author and genre of song.mp3. (All other fields
unchanged)
mp3info -t "Song Title" -a Author -g "Rock & Roll" song.mp3
Set the album field of all MP3 files in the current directory to "The
White Album"
mp3info -l "The White Album" *.mp3
Delete the entire ID3 tag from song1.mp3 and song2.mp3
mp3info -d song1.mp3 song2.mp3
Delete the comment field from the ID3 tags of all MP3 files in the
current directory. (All other fields unchanged)
mp3info -c "" *.mp3
Display the Title, Artist, Album, and Year of all MP3 files in the
current directory. We include the labels ’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
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
Some spreadsheets or other software may allow importing data from flat
files where each field is a specific width. Here’s where the format
modifers 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 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
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
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
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
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
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.
AUTHOR
Cedric Tefft <cedric@phreaker.net>
SEE ALSO
printf(3)