liquidx / works / PyTagger


pytagger is a ID3 tag reader and writer implemented purely in Python. It supports all the current ID3 tag implementations including ID3v1, ID3v1.1, ID3v2.2, ID3v2.3 and ID3v2.4.

(Note: This project has now been renamed from pyid3v2 to pytagger to avoid conflict with existing projects.)


Example Usage

As with most pieces of software, you'd probably want a sample script to show you how this works:

>>> from tagger import *
>>> mp3_tag = ID3v2('amazing.mp3')      
>>> mp3_tag.version

You can easily access the contents of frames:

>>> for frame in mp3_tag.frames:
...     print frame.fid 
>>> for frame in mp3_tag.frames:
...     if frame.fid == 'TT2':
...             print frame.strings
['Amazing', ''] 

You can add and remove frames from the ID3v2 tag:

>>> title_frame = mp3_tag.new_frame('TT2')
>>> title_frame.set_text('More Amazing') 
>>> title_frame.strings
['More Amazing']
>>> old_title_frame = [frame for frame in mp3_tag.frames if frame.fid == 'TT2'][0]
>>> mp3_tag.frames.remove(old_title_frame)
>>> mp3_tag.frames.append(title_frame)

You can commit your changes or discard them:

>>> mp3_tag.commit()
>>> mp3_tag.commit_to_file('newmusic.mp3')

And of course, you can also use it to read ID3v1 tags

>>> mp3_tag1 = ID3v1('amazing.mp3')
>>> print mp3_tag1.artist
'Alex Lloyd'    

More complete documentation of the API can be found here.


I initially wanted to edit ID3 tags of MP3 files in python. The main reason being that there are alot of MP3s around with non-unicode (eg. Big5 or GB2312) tags floating around. Under Linux GNOME applications default to using UTF-8 and under Mac OS X, iTunes require you to use UTF-16 for non ASCII tags.

I attempted to build wrappers for libid3tag and id3lib. Both of them had pecularities that made it difficult to understand or wrap around with Python.

There are also other pure Python implementations for ID3v1 and ID3v2 but they are either read-only or only support particular version. So rather than learning someone else's code, I decided to have a go at writing my own parser.

The code you see now has gone through a number of refactoring cycles and is the easier to work with for text tags. There are other tags such as embedding objects, numbers and URLs. Those have been less aggressively tested.

pytagger is now the basis of a Mac OS X application I wrote called TagEncoder which allows you to drag and drop MP3s in order to convert their tags from one encoding to another.

However, there will definitely still be bugs left. Right now, it is still in beta state, so the API can change at any minute. If you are using this for any application, please let me know so we can discuss what sort of API is the most useful. I'm still inexperienced with designing APIs so I would appreciate any input.