.TH mp3info 1 "July 16, 2001" "mp3info"

.SH NAME
mp3info \- MP3 technical info viewer and ID3 tag editor

.SH SYNOPSIS
.B mp3info \fP[\fB -h \fP|\fB -G \fP]\fB
.PP
.B mp3info \fP[\fB-x\fP] [\fB-F\fP] [\fB-r a\fP|\fBm\fP|\fBv\fP] [\fB-p\fP \fIFORMAT_STRING\fP] \fIfile...\fR
.PP
.B mp3info \fP[\fB-d\fP]\fB \fIfile...\fP
.PP
.B mp3info \fP[\fB-i\fP] [\fB-t \fItitle\fP] [\fB-a \fIartist\fP] [\fB-l \fIalbum\fP] [\fB-y \fIyear\fP] [\fB-c \fIcomment\fP] [\fB-n \fItrack\fP] [\fB-g \fIgenre\fP] \fIfile...\fP
.br

.SH DESCRIPTION
.B 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. 

.SH OPTIONS
.B
.IP "-a \fIartist\fP"
Specify ID3 artist name
.B
.IP "-c \fIcomment\fP"
Specify ID3 comment
.B
.IP "-g \fIgenre\fP"
Specify ID3 genre (use \fB-G\fP option for a list of valid genres).
You may specify either a genre name or a number.
.B
.IP "-l \fIalbum\fP"
Specify ID3 album name
.B
.IP "-n \fItrack\fP"
Specify ID3 v1.1 track number
.B
.IP "-t \fItitle\fP"
Specify ID3 track title
.B
.IP "-y \fIyear\fP"
Specify ID3 copyright year
.B
.IP -G
Display a list of valid genres and their associated numeric codes. These are the only
values accepted by the \fB-g\fP switch.
.B
.IP -h 
Display a help page
.B
.IP -x
Display technical attributes of the MP3 file
.B
.IP "-r a\fP|\fBm\fP|\fBv"
Report bit rate of Variable Bit Rate (VBR) files as one of the following
(See the section below entitled \fBBit Rates\fP for more information):
.PP
.RS 7
.PD 0
.HP
.B a
\- Average bit rate [float](Note: this option also causes the bit rates of
non-VBR files to be displayed as floating point values).
.LP
.HP
.B m
\- Median bit rate [integer]
.LP
.HP
.B v
\- Simply use the word 'Variable' [string] (this is the default).
.PD
.RE
.B
.IP -i
Edit ID3 tag interactively (uses curses/ncurses functions)
.B
.IP -d
Delete ID3 tag (if one exists)
.B
.IP -f
Force Mode: Treat all files as MP3s even if MP3 frames can't be found
.B
.IP -F
Do a Full scan for technical information (see the section \fBSpeed Considerations\fP below for more information)
.PP
.B
-p "\fIFORMAT_STRING\fP"
.IP 
Print MP3 attributes according to \fIFORMAT_STRING\fP.  \fIFORMAT_STRING\fP is 
similar to a \fBprintf(3)\fP 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 \fBprintf(3)\fP.  See
the \fBEXAMPLES\fP section below for examples of how format strings are used
in mp3info.
.PP
.IP
.B Conversion Specifiers
.PP
.RS 10
.PD 0
.B
.IP %f
Filename without the path [string]
.B
.IP %F
Filename with the path [string]
.B
.IP %k
File size in KB [integer]
.B
.IP %a
Artist [string]
.B
.IP %c
Comment [string]
.B
.IP %g
Musical genre [string]
.B
.IP %G
Musical genre number [integer]
.B
.IP %l
Album name [string]
.B
.IP %n
Track [integer]
.B
.IP %t
Track Title [string]
.B
.IP %y
Year [string]
.B
.IP %C
Copyright flag [string]
.B
.IP %e
Emphasis [string]
.B
.IP %E
CRC Error protection [string]
.B
.IP %L
MPEG Layer [string]
.B
.IP %O
Original material flag [string]
.B
.IP %o
Stereo/mono mode [string]
.B
.IP %p
Padding [string]
.B
.IP %v
MPEG Version [float]
.B
.IP %u
Number of good audio frames [integer]
.B
.IP %b
Number of corrupt audio frames [integer]
.B
.IP %Q
Sampling frequency in Hz [integer]
.B
.IP %q
Sampling frequency in kHz [integer]
.B
.IP %r
Bit Rate in kbps (type and meaning affected by \fB-r\fP option)
.B
.IP %m
Playing time: minutes only [integer]
.B
.IP %s
Playing time: seconds only [integer] (usually used in conjunction with \fB%m\fP)
.B
.IP %S
Total playing time in seconds [integer] 
.B
.IP %%
A single percent sign
.RE
.PD
.PP
.RS 7
.B "Escape Sequences"
.RE
.PP
.PD 0
.RS 10
.B
.IP \en
Newline
.B
.IP \et
Horizontal tab
.B
.IP \ev
Vertical tab
.B
.IP \eb
Backspace
.B
.IP \er
Carriage Return
.B
.IP \ef
Form Feed
.B
.IP \ea
Audible Alert (terminal bell)
.B
.IP \ex\fIhh\fB
Any arbitrary character specified by the hexidecimal number \fIhh\fP
.B
.IP \e\fIooo\fB
Any arbitrary character specified by the octal number \fIooo\fP
.B
.IP \fB\e\e\fP
A single backslash character
.RE
.PP
.PD


.SH USAGE

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

.SH NOTES

.IP "\fBSpeed Considerations\fP"
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.  
.IP
One should specify the \fB-F\fP 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 \fB-x\fP switch is used or the \fB-p\fP switch is 
used with a FORMAT_SPECIFIER containing \fB%m\fP, \fB%s\fP, \fB%S\fP, \fB%u\fP 
or (rarely) \fB%r\fP.  Using the \fB-F\fP switch under other conditions will 
only slow down mp3info.  Also note that a FORMAT_SPECIFIER containing \fB%b\fP 
or a VBR MP3 file will automatically trigger a full scan even if the \fB-F\fP 
switch is not used.

.IP "\fBBit Rates\fP"
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.
.IP
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.
.IP
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.
.IP
For more specific usage information, see the \fB-r\fP switch and the \fB%r\fP 
conversion specifier under the description of
\fB-p\fP's FORMAT_SPECIFIER.


.SH EXAMPLES

Display existing ID3 tag information (if any) in song.mp3
.PP
.IP
.B
mp3info song.mp3
.PP
Set the title, author and genre of song.mp3. (All other fields unchanged)
.IP
.B
mp3info -t "Song Title" -a Author -g "Rock & Roll" song.mp3
.PP
Set the album field of all MP3 files in the current directory 
to "The White Album"
.PP
.IP
.B
mp3info -l "The White Album" *.mp3
.PP
Delete the entire ID3 tag from song1.mp3 and song2.mp3
.IP
.B
mp3info -d song1.mp3 song2.mp3
.PP
Delete the comment field from the ID3 tags of all MP3 files
in the current directory. (All other fields unchanged)
.IP
.B
mp3info -c "" *.mp3
.PP
Display the Title, Artist, Album, and Year of all MP3 files in the current directory.
We include the labels 'File', etc. and insert newlines (\fB\en\fP) to make things
more readable for humans:
.IP
.B
mp3info -p "File: %f\enTitle: %t\enArtist: %a\enAlbum: %l\enYear: %y\en\en" *.mp3
.PP
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 (\fB\et\fP) character.  Note
that you must include a newline (\fB\en\fP) at the end of the format string in order
to get each file's information on a separate line.  Here's the command:
.IP
.B
mp3info -p "%f\et%t\et%a\et%l\et%y\en" *.mp3
.PP
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.
.IP
.B
mp3info -p "%50f%31t%31a%31l%4y\en" *.mp3
.PP
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 (\fB-\fP) in front of the field-width:
.IP
.B
mp3info -p "%-50f%-31t%-31a%-31l%-4y\en" *.mp3
.PP
Now suppose you just want the running time of each MP3 file specified in minutes
and seconds.  Simple enough:
.IP
.B
mp3info -p "%f: %m:%s\en" *.mp3
.PP
You may notice when you do this, however, that leading zeros are not displayed
in the seconds field (\fB%s\fP).  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:
.IP
.B
mp3info -p "%f: %m:%02s\en" *.mp3
.PP
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.  
.IP
.B
mp3info -r a -p "%f %r\en" *.mp3
.PP
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:
.IP
.B
mp3info -r a -p "%f %.2r %.0r\en" *.mp3
.PP
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:
.IP
.B
mp3info -r a -p "%f %6.2r\en" *.mp3
.SH 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.
.PP
Using space to erase tags in interactive mode does not work correctly if you 
then backspace over the deleted text.
.PP
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 \fB-n\fP 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.
.PP
Genres cannot be specified arbitrarily.  They must be specified from a 
pre-determined list (use \fBmp3info -G\fP to see that list).  Again, this is a 
limitation of the ID3 1.0 tag format.
.PP
Only ID3 versions 1.0 and 1.1 are supported.  Version 3.0 is a "non-standard" 
standard that is much more flexible than the 1.0 standard, but has not yet 
been widely adopted.  The jury is still out.  See www.id3.org for more info.

.SH AUTHOR
Cedric Tefft <cedric@earthling.net>

.SH "SEE ALSO"
\fBprintf\fP(3)\fB