eyeD3 0.5.1

Travis Shirk <travis@pobox.com>
07.20.2003

General Information

eyeD3 is a Python program/module for processing (reading and writing) ID3 tags. Information about mp3 files (i.e bit rate, sample frequency, play time, etc.) is also available. The formats supported are ID3 v1.0/v1.1 and v2.3/v2.4.

The current stable version is 0.5.1. Download it or earlier versions here.

See the NEWS and/or ChangeLog for changes.

Requirements

Python >= 2.2
Optik 1.4 -- Required to run the eyeD3 program; programming with the module does not require it.

Installation

Source tarball

     gzip -dc eyeD3-0.5.1.tar.gz | tar xvf -
     cd eyeD3-0.5.1
     ./configure
     make
     make install (as root)

RPM

     rpm -Uvh ./eyeD3-0.5.1-1.noarch.rpm

How to Use eyeD3

The 'eyeD3' utility program can perform most ID3 tasks, and it is also the best example of how to use the API. It supports the following features:

  Usage
  =====
    eyeD3 [OPTS] file [file...]
  
  options
  =======
    --version             show program's version number and exit
    -h, --help            show this help message and exit
  
  Tag Versions
  ------------
      -1, --v1            Only read/write ID3 v1.x tags. By default, v1.x tags are
                          only read if there is not a v2.x tag.
      -2, --v2            Only read/write ID3 v2.x tags.
      --to-v1.1           Convert the file's tag to ID3 v1.1. (Or 1.0 if there is
                          no track number.)
      --to-v2.3           Convert the file's tag to ID3 v2.3
      --to-v2.4           Convert the file's tag to ID3 v2.4
  
  Tag Data
  --------
      -a STRING, --artist=STRING
                          Set artist
      -A STRING, --album=STRING
                          Set album
      -t STRING, --title=STRING
                          Set title
      -n NUM, --track=NUM
                          Set track number
      -N NUM, --track-total=NUM
                          Set total number of tracks
      -G GENRE, --genre=GENRE
                          Set genre. The argument is a valid genre string or
                          number.  See --list-genres
      -Y STRING, --year=STRING
                          Set a four digit year.
      --comment=[LANGUAGE]:[DESCRIPTION]:COMMENT
                          Set comment
      --remove-v1         Remove ID3 v1.x tag.
      --remove-v2         Remove ID3 v2.x tag.
      --remove-all        Remove both ID3 v1.x and v2.x tags.
  
  Tag Versions
  ------------
      -l, --list-genres   Display the table of ID3 genres and exit
      -i, --write-images  Causes all attached images (APIC frames) to be written
                          to the current directory.
      --no-color          Disable color output
      -v, --verbose       Show all available information
      --debug             Trace program execution.

Some simple programming examples follow here, excluding any error handling, of course :)

Reading the contents of an mp3 file containing either v1 or v2 tag info:

     import eyeD3;
     tag = eyeD3.Tag();
     tag.link("/some/file.mp3");
     print tag.getArtist();
     print tag.getAlbum();
     print tag.getTitle();

Read an mp3 file (track length, bitrate, etc.) and access it's tag:

  if eyeD3.isMp3File(f):
     audioFile = eyeD3.Mp3AudioFile(f, self.opts.tagVersion);
     tag = audioFile.getTag();

Specific tag versions can be selected:

     tag.link("/some/file.mp3", eyeD3.ID3_V2);
     tag.link("/some/file.mp3", eyeD3.ID3_V1);
     tag.link("/some/file.mp3", eyeD3.ID3_ANY);  # The default.

Or you can iterate over the raw frames:

     tag = eyeD3.Tag();
     tag.link("/some/file.mp3");
     for frame in tag.frames:
        print frame;

Once a tag is linked to a file it can be modified and saved:

     tag.setArtist("Cro-Mags");
     tag.setAlbulm("Age of Quarrel");
     tag.update();

If the tag linked in was v2 and you'd like to save it as v1:

     tag.update(eyeD3.ID3_V1_1);

Read in a tag and remove it from the file:

     tag.link("/some/file.mp3");
     tag.remove();

Bugs and Patches

Find bugs! Please submit all comments, bug reports, or feature requests to Travis Shirk <travis@pobox.com>. Those of of the patch variety are especially welcome :)