


mp3info(1)					       mp3info(1)


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

       -d     Delete ID3 tag (if one exists)

       -f     Foce 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  infor-
	      mation)

       -g genre
	      Specify  ID3  genre  (use	 -G  option for a list of
	      valid genres). You may specify either a genre  name
	      or a number.

       -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

       -i     Edit  ID3	 tag  interactively  (uses curses/ncurses
	      functions; not impremented for OS/2 systems)

       -l album
	      Specify ID3 album name




mp3info			 August 13, 2000			1





mp3info(1)					       mp3info(1)


       -n track
	      Specify ID3 v1.1 track number

       -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 modi-
	      fiers accepted by printf(3).  See the EXAMPLES sec-
	      tion  below  for examples of how format strings are
	      used in mp3info.


	      Conversion Specifiers

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

	      Escape Sequences

		 \n	Newline
		 \t	Horizontal tab
		 \v	Vertical tab
		 \b	Backspace



mp3info			 August 13, 2000			2





mp3info(1)					       mp3info(1)


		 \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

       -r a|m|v
	      Report bit rate of Variable Bit Rate (VBR) files as
	      one  of  the following (See the section below enti-
	      tled 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).

       -t title
	      Specify ID3 track title

       -x     Display technical attributes of the MP3 file

       -y year
	      Specify ID3 copyright year



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 abso-
	      lute  certainty,	it would be necessary to read the



mp3info			 August 13, 2000			3





mp3info(1)					       mp3info(1)


	      entire MP3 file.	Mp3info normally tries	to  speed
	      things up by reading a handful of frames from vari-
	      ous points in the file and estimating  the  statis-
	      tics  for	 the rest of the file based on those sam-
	      ples.  Usually, this results in very accurate esti-
	      mates.   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 determin-
	      ing 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_SPECI-
	      FIER  containing	%m,  %s,  %S,  %u or (rarely) %r.
	      Using the -F switch  under  other	 conditions  will
	      only  slow  down	mp3info.   Also	 note that a FOR-
	      MAT_SPECIFIER containing %b or a VBR MP3 file  will
	      automatically  trigger  a	 full scan even if the -F
	      switch is not used.


       Bit Rates
	      MP3 files are made up of many (usally several thou-
	      sand)  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  sin-
	      gle  bit rate, attempting to report the bit rate of
	      the file as a whole  can	be  problematic.   Conse-
	      quently, 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



mp3info			 August 13, 2000			4





mp3info(1)					       mp3info(1)


	      option is to print the mathematical average of  all
	      the  frames.   This has the advantage of being com-
	      pletely 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 alterna-
	      tive  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 direc-
       tory to "The White Album"


	      mp3info -l "The White Album" *.mp3

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

	      mp3info -d song1.mp3 song2.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 com-
       monly 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



mp3info			 August 13, 2000			5





mp3info(1)					       mp3info(1)


       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  separa-
       tors.   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-jus-
       tified, 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 speci-
       fier  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



mp3info			 August 13, 2000			6





mp3info(1)					       mp3info(1)


       (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 com-
       mand  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 com-
       ment 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.  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.


AUTHOR
       Cedric Tefft <cedric@earthling.net>





mp3info			 August 13, 2000			7





mp3info(1)					       mp3info(1)


SEE ALSO
       printf(3)























































mp3info			 August 13, 2000			8
