id3reader

Created 4 January 2004, last updated 26 November 2011

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.

The code in id3reader.py is in the public domain. Do with it as you please.

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

AB 5:00 PM on 21 Apr 2008

Hi Ned,

This is exactly what I have been looking for.
Absolutely fantastic!
Many thanks.

Aamod 1:55 AM on 19 Jul 2008

Awesome python script. Will be definately using it in my project. Will comment about it when I get something concrete..

Don 10:03 AM on 31 Aug 2008

Hi,
Any one knows how to read album art of mp3 files in python?

buyaka 9:44 PM on 12 Dec 2008

I was having problems with lists generated from the data returned by id3reader. The problem was that if one of the fields was empty then you'd have a list of unicode type data with one NoneType in the middle which throws errors with some methods like join which expect str or unicode. I changed the return None in def getValue to return u'None' which worked. I don't how elegant this solution is but it worked.

samuel 5:41 PM on 25 Feb 2011

Hi
I understood that I can read almost all information from media section.
But, how can I read "Length" parameter from this section and how can I read the file audio information?
I need to know the "bit rate" parameter
Thank you for your help
Samuel

H.T 9:35 AM on 16 May 2011

Thank you so much

joshua bonnett 2:32 PM on 28 Jun 2011

Hi, I am working on armstrong cms, a open source cms for newsrooms that uses django. I am wondering about using this code in our project. The project is using Apache license v2. The code is up on https://github.com/armstrong
I am wondering what you think licensing wise.

Tensigh 7:14 PM on 31 May 2012

Any hope of getting one that will write to ID3 tags?

Ned Batchelder 7:42 PM on 31 May 2012

@Tensigh: I'm not even maintaining this reader any more, so I'm definitely not writing a writer.

Tensigh 9:30 PM on 31 May 2012

I see. There are other ones out there, this one just seemed to be the easiest on accessing the tags. Kind of useless though, without being able to write them back.

Thanks, though! Cool project otherwise!

G. Scott 3:51 AM on 28 Aug 2013

I had a problem with some tracks that had fields with characters that couldn't be read by str.decode('utf-16'). Couldn't figure out what the characters were, because nothing would print them, just skip them. The fix I had was to use str.decode('utf-16', 'ignore') (line 149 of version '1.53.20070415').

Hugh Wardlaw 2:04 AM on 26 Mar 2017

Your .py file is replete with errors and I have attempted to repair all of them,but is yet to actually do anything. I cannot get over all the "experts" who write code with so many oversights. Items include Calls without Parens, Prints without parens. half assignments ( =1 ==1 ==0 =0) with no assignment on the left. You must not be doing the Python in Debian Linux or Windows. THe code is REJECTED both places. Do your homework.

Ned Batchelder 2:38 AM on 26 Mar 2017

Hi Hugh, sorry you had a tough time with this code.

This code was written 13 years ago, and runs on Python 2. It sounds
like you ran it on Python 3.

Next time, ask a question. The answer is different than, "Ned is an
idiot claiming to be an expert."

Jean-Paul Roberts 4:08 PM on 5 Jun 2017

Thanks, Ned. That works great!

I've converted it to run under Python 3, and the conversion's available on the same terms as your original. It's available at http://www.jpsoftware.co.uk/id3reader.html , in case it's useful for anyone else.