MP3info	- Adds, deletes, or changes MP3 ID3 tags.


ABOUT
=====

Q: What's MP3Info?

A: MP3Info is a little utility used to read and modify the ID3 tags in MPEG 
layer 3 (MP3) files.  In case you don't know, MP3 is a very popular digital 
audio format which encodes a recording with a lossy compression algorithm 
resulting in files representing a minute of near-CD quality stereo sound in 
less than a megabyte of data.   An ID3 tag is a little scrap of data added to 
the end of the MP3 file which stores information about the audio recording 
including the title, artist, album, copyright date, and musical genre.  


HISTORY
=======

MP3Info was originally written by Ricardo Cerqueira <rmc@rccn.net>.  As of 
January 2000, MP3Info is being maintained by Cedric Tefft 
<cedric@earthling.net>.  If you have any bug reports or patches, please email 
them to me.  Bugs get fixed a lot faster if you include patches -- especially 
if the problem is platform specific.


PORTABILITY
===========

MP3Info was developed under Linux, but should work on most UN*X variants.
Included with the text-based version is a gui version which requires the GTK
libraries (see http://www.gtk.org).  The console version runs in plain
command-line and interactive curses mode.  The curses or ncurses library is
required.


OBTAINING THE LATEST VERSION OF MP3INFO
=======================================

MP3Info's home is the software archive at MetaLab (formerly SunSite). Both
source and i386 RPM's are available.

HOMEPAGE 

    http://metalab.unc.edu/mp3info/

PRIMARY DOWNLOAD

   ftp://metalab.unc.edu/pub/linux/apps/sound/mp3-utils/mp3info
   http://metalab.unc.edu/pub/linux/apps/sound/mp3-utils/mp3info

MIRRORS

   ftp://ftp.cdrom.com/pub/linux/sunsite/apps/sound/mp3-utils/mp3info/
   ftp://ftp.cc.gatech.edu/pub/linux/apps/sound/mp3-utils/mp3info/

The entire Metalab archive (including MP3Info) is mirrored to many other 
locations around the world.  A full and current list of Metalab mirrors can be 
found at ftp://metalab.unc.edu/pub/Linux/MIRRORS.html


INSTALLATION
============

Pretty basic.  After unpacking the archive run the following two commands:

make
make install 		(this command must be run by the root user)

If you want to compile just the console or GTK version use 'make mp3info' or 
'make gmp3info' (respectively).


USAGE: Console Version
======================

  mp3info HELP-OPTIONS
  mp3info [EDIT-OPTIONS] MP3-file1 [.. MP3-fileN]

   HELP-OPTIONS
-h	--	Display this help page
-G	--	Display genre list

   EDIT-OPTIONS
-i	   --   Edit ID3 tag interactively
-d	   --   Delete ID3 tag
-f	   --   Assume all files are MP3's (don't check for std. MP3 header)
-t title   --   Specify ID3 track title
-a artist  --   Specify ID3 artist name
-l album   --   Specify ID3 album name
-y year    --   Specify ID3 copyright year
-c comment --   Specify ID3 comment
-g genre   --   Specify ID3 genre (use -G option for a list of valid genres)

Specifying MP3 files without any edit options displays the existing tag.
Non-specified fields, if existant, will remain unchanged.
Genres can be specified as numbers or names: '-g 17' same as '-g Rock'
Remember: Multiple word fields must be enclosed in "" (eg: -t "A title")

Usage: GTK Version
==================

gmp3info song.mp3


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 ID3 tag from song1.mp3 and song2.mp3

	mp3info -d song1.mp3 song2.mp3


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

Some perfectly valid MP3 files do not start with the 'standard' MP3 header
and are rejected by MP3Info as being invalid. I have not been able to locate
any information as to what these headers might be or how to decode them.  If
anyone has access to such information, please forward it on to me so I can make
MP3Info more intelligent about determining what is and is not a valid MP3 file.
For the time being, I have inserted the -f switch as a workaround.


KNOWN LIMITATIONS
=================

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

MP3Info only recognizes MP3 files with "standard" headers see 
http://www.wotsit.org/search.asp?s=music for more information on the MP3 file 
format).  Since MP3Info checks the header in an attempt to determine a valid 
MP3 from any other type of file, it will incorrectly claim that these files 
are not valid MP3's.  Until I figure out what these headers are and how to 
parse them, you will need to use the -f switch on these MP3 files to force 
MP3Info to process them.

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.

I don't have the actual algorithm to determine the running time (length)
of an MP3 file, so I made one up.  It seems to agree with reality to within
a second or two, but this is not guaranteed.


MISCELLANEOUS NEWS & INFO
=========================

MP3Info is looking for a new name!  Several people have pointed out that there 
are other, older programs out there called mp3info which arguably have more of 
a "right" (in as much as such a thing exists in the open source world) to the 
name than this program.  Name suggestions, like bug reports, are happily 
accepted.


DISCLAIMER
==========

I do not take responsibility for damaged files, MP3s or not. If you decide to 
run this on something other than an MP3, tough luck. You're on your own.


TO DO
=====

Make MP3Info capable of recognizing MP3's which do not start with the 'standard'
header (see links for MP3 file formats at http://www.wotsit.org/search.asp?s=music).

Add support for ID3v2 3.0 (www.id3.org) if it starts to become more widely used.
Currently only ID3 v1.0 and 1.1 are supported.

Add an "Open file" option to GMP3info.

Add technical info display (-x in the command-line version) to the GTK version.

					- Cedric Tefft <cedric@earthling.net>
					  March 9, 2000
