README for ID3.py, version 1.2

Copyright (C) 1999, 2000, 2002 Ben Gertzfield <[email protected]>
--------------------------------------------------------------

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!

ID3.py is hosted by SourceForge.Net, and the latest release will
always be available from:

http://id3-py.sourceforge.net/

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 Früvous"
    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.

NEW DICTIONARY-BASED INTERFACE
------------------------------

As of ID3.py version 1.2, a new dictionary-based interface compatible
with ogg.vorbis is available.  You can now use ID3 objects just like
a dictionary:

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

	id3info['TITLE'] = "Green Eggs and Ham"
	id3info['ARTIST'] = "Moxy Früvous"

	for k, v in id3info.items():
            print k, ":", v
    except InvalidTagError, message:
	print "Invalid ID3 tag:", message

Note that ID3.py (by default) stores just a string in each value in
the dictionary-based interface.  ogg.vorbis uses a *list*, not a
single string, so if you want compatibility with ogg.vorbis, call the
ID3 constructor with as_tuple=1:

    from ID3 import *
    try:
        id3info = ID3("moxy.mp3", as_tuple=1)
        for k, v in id3info.items()
            print k, ":", v[0]
    except InvalidTagError, message:
        print "Invalid ID3 tag:", message

Of course, all the tuples will only have one string value inside them,
as that's all the ID3 version 1.1 standard supports.

ID3 OBJECT FIELDS
-----------------

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.

If any of the fields are not defined in the ID3 tag, the dictionary
based interface will not contain a key for that field!  Test with
ID3.has_key('ARTIST') etc. first.

    ID3.title or ID3['TITLE']
      Title of the song.
    ID3.artist or ID3['ARTIST']
      Artist/creator of the song.
    ID3.album or ID3['ALBUM']
      Title of the album the song is from.
    ID3.year or 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://mp3.musichall.cz/id3master/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['GENRE']
      String value corresponding to the integer in ID3.genre.  If there
      is no genre string available for the ID3.genre number, this will
      be set to "Unknown Genre".
    ID3.comment or ID3['COMMENT']
      Comment about the song.
    ID3.track or ID3['TRACKNUMBER']
      Track number of the song. None if undefined.
      NOTE: ID3['TRACKNUMBER'] will return a *string* containing the
      track number, for compatibility with ogg.vorbis.

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

   legal_genre(genre_number)
     Checks if genre_number is a legal index into ID3.genres.  Returns
     true if so, false otherwise.

   as_dict()
     Returns just the dictionary containing the ID3 tag fields.
     See the notes above for the dictionary interface.

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.