eyeD3 0.6.1
Travis Shirk <travis@pobox.com>
05.14.2004


General Information
===================

eyeD3 is a Python module and program for processing ID3 tags.
Information about mp3 files (i.e bit rate, sample frequency,
play time, etc.) is also provided.  The formats supported are ID3
v1.0/v1.1 (http://id3lib.sourceforge.net/id3/id3v1.html)
and v2.3/v2.4 (http://id3lib.sourceforge.net/id3/develop.html).

The current stable version is 0.6.1.  It and earlier versions are
available here (http://eyed3.nicfit.net/releases/).

See the NEWS (NEWS) and/or ChangeLog (ChangeLog) for changes.

Requirements
============
 - Python (http://www.python.org/) >= 2.3

Installation
============

Source tarball
--------------

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


RPM
---

     rpm -Uvh ./eyeD3-0.6.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
  --------
      -aSTRING, --artist=STRING
                          Set artist
      -ASTRING, --album=STRING
                          Set album
      -tSTRING, --title=STRING
                          Set title
      -nNUM, --track=NUM  Set track number
      -NNUM, --track-total=NUM
                          Set total number of tracks
      -GGENRE, --genre=GENRE
                          Set genre. The argument is a valid genre string or
                          number.  See --list-genres
      -YSTRING, --year=STRING
                          Set a four digit year.
      --comment=[LANGUAGE]:[DESCRIPTION]:COMMENT
                          Set comment
      --remove-comments   Remove all comment frames.
      --add-image=IMG_PATH:TYPE[:DESCRIPTION]
                          Add an image to the tag.  The description and type
                          optional, but when used, both ':' delimiters must be
                          present.  The type MUST be an string that corresponds to
                          one given with --list-image-types.
      --list-image-types  List all possible image types
      -i, --write-images  Causes all attached images (APIC frames) to be written
                          to the current directory.
      --set-text-frame=FID:TEXT
                          Set the value of a text frame.  To remove the frame,
                          specify an empty value.  e.g., --set-text-frame="TDRC:"
      --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.
  
  Misc. Options
  -------------
      -l, --list-genres   Display the table of ID3 genres and exit
      --strict            Fail for tags that violate the ID3 specification.
      --jep-118           Output the tag per the format described in JEP-0118. See
                          http://www.jabber.org/jeps/jep-0118.html
      --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();


Support
=======
eyeD3 now has a mailing list.  Send a message to
<eyed3-devel-subscribe@nicfit.net> to subscribe.

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

See Also
========
eyeD3 is free software, refer to the COPYING (COPYING) file for details.

See the TODO (TODO) file for possible enhancements.




