README for ID3.py, version 1.1

Copyright (C) 1999, 2000 Ben Gertzfield <che@debian.org>
--------------------------------------------------------

This is a simple Python module for retrieving and setting so-called
ID3 tags on MP3 compressed audio files through an object-oriented
interface. MP3 players generally use this simple information for
display track title, artist name, and album title while playing
the sound file.

ID3.py supports ID3 version 1.1, including the track number field.
I have no current plans to code up the monstrosity that is ID3v2
(http://www.id3.org/id3v2.3.0.html) but if someone wants to add
that functionality, feel free!

To install ID3.py, either simply copy the ID3.py file to your
site-wide Python module installation directory
(/usr/local/lib/python/site-python, for instance) or, if you have
Python v1.6 or later (or have Distutils installed), you can simply
run:

# python setup.py install

from the command-line.

Here's a simple example of using the ID3 module. This example prints
the current ID3 information (nicely formatted) of a given MP3, changes
the title and artist tags, and then (implicitly, when the object is
destroyed) writes out the changes to the file.

from ID3 import *
    try:
	filename = '/some/path/moxy.mp3'
        id3info = ID3(filename)

        # alternatively, can pass in a file or equivalent if opened in r+b mode
	# id3info = ID3(open(filename, 'r+b'), filename)

        print id3info
        id3info.title = "Green Eggs and Ham"
        id3info.artist = "Moxy Frvous"
    except InvalidTagError, message:
        print "Invalid ID3 tag:", message

Notice that simply changing the value of the fields is enough; no
special functions need to be called.

Here's a list of all the fields in an ID3 object that are interesting.
Note that all ID3 fields, unless otherwise specified, are a maximum of
30 characters in length. If a field is set to a string longer than the
maximum, it will be truncated when it's written to disk.

   ID3.title
      Title of the song.
   ID3.artist
     Artist/creator of the song.
   ID3.album
     Title of the album the song is from.
   ID3.year
     Year the song was released. Maximum of 4 characters (Y10K bug!)
   ID3.genre
     Genre of the song. Integer value from 0 to 255. Genre specification
     comes from (sorry) WinAMP. http://id3master.mute.cz/faq.htm
     has a list of current genres; I spell-checked this list against
     WinAMP's by running strings(1) on the file Winamp/Plugins/in_mp3.dll 
     and made a few corrections.
   ID3.comment
     Comment about the song.
   ID3.track
     Track number of the song. None if undefined.

This field shouldn't be changed, but might be of use:

   ID3.genres
     List of all genres. ID3.genre above is used to index into this
     list. ID3.genres is current as of WinAMP 1.92.

Here are the methods of interest that the ID3 module contains:

   write()
     If the class data above have changed, opens the file given
     to the constructor read-write and writes out the new header.
     If the header is flagged for deletion (see delete() below)
     truncates the last 128 bytes of the file to remove the header.

     NOTE: write() is called from ID3's deconstructor, so it's technically
     unnecessary to call it. However, write() can raise an InvalidTagError,
     which can't be caught during deconstruction, so generally it's 
     nicer to call it when writing is desired.
   
   delete()
     Flags the ID3 tag for deletion upon destruction of the object
   
   find_genre(genre_string)
     Searches for the numerical value of the given genre string in the
     ID3.genres table. The search is performed case-insensitively. Returns
     an integer from 0 to len(ID3.genres).

The only exception is ID3.InvalidTagError; this exception will be
raised from the constructor when the given file cannot be opened, when
an IOError is raised while reading the file, and when an IOError occurs
during a write, after the tag has been modified.
