Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
mp3info(1)		    General Commands Manual		    mp3info(1)

       mp3info - MP3 technical info viewer and ID3 tag editor

       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...

       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 at-
       tributes	of the MP3 file.

       -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 in-

	      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  de-

       -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

       -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 se-
	      quences. 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 KB/s (type	and meaning affected by	-r op-
		 %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
		 \\	A single backslash character
       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")

       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.	Never-
	      theless, the user	may wish to ensure that	she is	getting	 exact

	      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 au-
	      tomatically trigger a full scan even if the  -F  switch  is  not

	      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	 esti-
	      mates  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 accu-
	      rate 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 main-
	      tain 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  sin-
	      gle 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 al-
	      lowed 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 FOR-

       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  un-

	      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 cur-
       rent directory. (All other fields unchanged)

	      mp3info -c "" *.mp3

       Display the Title, Artist, Album, and Year of all MP3 files in the cur-
       rent 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  com-
       mand  you might use to help you accomplish that.	 Most spreadsheet pro-
       grams 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  informa-
       tion  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-

	      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  dis-
       played  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  dis-
       played 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 aver-
       age 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

       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  charac-
       ters.  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  be-
       comes  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 re-
       ducing 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 pow-
       erful standard and is planned for some as-yet-undetermined future  ver-
       sion.  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.

       Cedric Tefft <>


mp3info			       November	6, 2006			    mp3info(1)


Want to link to this manual page? Use this URL:

home | help