Created 4 January 2004, last updated 26 March 2006

Id3reader.py is a Python module that reads ID3 metadata tags in MP3 files. It can read ID3v1, ID3v2.2, ID3v2.3, or ID3v2.4 tags. It does not write tags at all.

As of March 2006, I am no longer maintaining this module. If you would like to own it, feel free to take it. I can help you take it over if you would like.

Installation

To install id3reader, just copy id3reader.py to your Python path.

Download: id3reader.py

Usage

Using id3reader couldn't be simpler:

import id3reader # Construct a reader from a file or filename. id3r = id3reader.Reader('my_favorite.mp3') # Ask the reader for ID3 values: print id3r.getValue('TT2')

In addition to whatever literal ID3 tag ids are found in the file (TP1, TIT2, etc), id3reader defines five pseudo ids for convenience:

id3r.getValue('album') id3r.getValue('performer') id3r.getValue('title') id3r.getValue('track') id3r.getValue('year')

These ids find the appropriate ID3 id for the ID3 version read from the file, so you can get at this basic data without having to consider the different versions of the ID3 spec.

If you run id3reader from the console, it will dump the ID3 information for the MP3 file named as its argument.

Coverage

The ID3 spec is quite extensive, and specifies functionality that I have never encountered in actual MP3 files. Id3reader implements as much of the spec as I have seen used. If you have files that id3reader does not properly interpret, please mail them to me. I'll extend id3reader to read them.

Changes

5 January 2004: It wasn't reading ID3v1 tags properly, and had problems with empty string values.

9 January 2004: Now it reads ID3v2.3 properly, and reads unsyncronized tags.

13 January 2004: Fix unsynchronized reading, reads compressed frames, improved detection of end of frames, extended headers are read (but not interpreted), multi-string frames are interpreted, and the file is closed if we opened it.

3 August 2004: Add support for genres (although they're stupid), and the command-line mode will print strings regardless of their encoding.

13 September 2004: Better protection against non-character data when showing the data on the command line.

Comments

oziko 9:37 AM on 6 Jan 2004

Sooo easy to use. it's really nice!

tobias 12:51 PM on 13 Jan 2004

hi

this is a very cool piece of software. i use before eyed3 and my files where not read at all. with this peace of software it's so much easier to write my programs. thank you for your work and please go on :-)

tobias

Andy 5:27 PM on 17 Feb 2004

Perfect! Just what I've been looking for. Much better at reading v2 tags than anything else I've found for python. Keep up the good work :o)

ianare 4:05 PM on 7 Sep 2005

sweet! just what i needed... now i can incorporate renaming files by id tag in my file reanming program. Thank you very much!

Henry 4:27 AM on 4 Dec 2005

Need a way to read ID3v1/1.1 and ID3v2.x seperately so an application can compare, copy tag, delete one or the other, etc.

rpyron 3:52 PM on 20 Jan 2006

In class Reader, change the initialization of self.header to:
self.header = _Header()
It is apparently legal (though not likely) to have an MP3 file with no ID3 tags at all.

I am writing a special-purpose splitter that first copies only the data to another file, then goes back later and adds ID3 tags. I am using id3writer for this, which in turn relies on your id3reader.

id3 writer is available from http://www.comfortableshoe.co.uk/cgi-bin/blosxom.cgi/Home/Python/id3Writer.comments

Garito 11:01 PM on 16 Feb 2006

Hi!

I like your lib, thanks

But I need some help: how can I read comments?

If I try dump I could see them but I don't know how to read them

Thanks!

Tim Almond 2:51 AM on 31 Mar 2006

Hi Ned,

I'm trying to write something to set ID3 tags in Python using ID3-PY (http://id3-py.sourceforge.net/).

Does that replace id3reader?

Bats 12:58 PM on 7 Apr 2006

Hey - fabulous script, just the thing I was looking for. Great stuff, thanks a lot!

Christina 7:39 AM on 18 Apr 2006

Hey,

maybe somebody could help me in this case.
Beside the other informations i am reading out of mp3 files, i want to read the time of the mp3s, for example(03:45). Do you know if this is possible with id3Reader and how?
If it is not possible with the id3reader, how else can i get the time?

thank you
Christina

ianare 3:00 PM on 25 May 2006

was having some problems with encodings in unicode build of wxpython. here is my solution:

def getValue(self, id, encoding):
""" Return the value for an ID3 tag id, or for a
convenience label ('title', 'performer', ...),
or return None if there is no such value.
"""
if self.frames.has_key(id):
if hasattr(self.frames[id], 'value'):
if isinstance(self.frames[id].value, unicode):
returnValue = self.frames[id].value
else:
returnValue = unicode(self.frames[id].value, encoding)
return returnValue

if _simpleDataMapping.has_key(id):
for id2 in _simpleDataMapping[id]:
v = self.getValue(id2, encoding)
if v:
if isinstance(v, unicode):
returnV = v
else:
returnV = unicode(v, encoding)
return returnV
return None

so now I can specify the encoding returned by id3reader, usage is as follows:
id3r = id3reader.Reader(file)
value = id3r.getValue(id, encoding)

ianare 3:01 PM on 25 May 2006

hum the tabs didn't stick... well you should know what to do ;)

Chris Mahan 2:15 PM on 4 Sep 2006

very nice.

Thanks

Chris Mahan 2:17 PM on 4 Sep 2006

I can't even write my own url.

Sergey 4:14 PM on 20 Mar 2008

Very, good! Thanks!
One problem, I can't get tags from string in zip file:

z = zipfile.ZipFile("zip.zip")
flist = z.namelist()
for j in flist:
next_mp3 = z.read(j)
id3 = id3reader.Reader(next_mp3) # Not work :((