Stagger is an ID3v1/ID3v2 tag manipulation package written in pure Python 3.
The ID3v2 tag format is notorious for its useless specification documents and its quirky, mutually incompatible part-implementations. Stagger is to provide a robust tagging package that is able to handle all the various badly formatted tags out there and allow you to convert them to a consensus format.
The package has a stable API and has been used in production for several years.
Features currently implemented:
- Reads and writes ID3 v1.0, 1.1, 2.2, 2.3 and 2.4 tags.
- Supports conversion between tag versions.
- Supports unsynchronized tags (all versions) and compressed frames (2.3 and 2.4 only).
- Full Unicode support, with customizable text encoding preferences.
- Has built-in support for all standard frame types (plus a few nonstandard ones). Easily extensible with additional frame types if needed.
- Supports duplicate frames and multiple text strings in a single frame.
- Supports reading/writing frames of unrecognized types and frames with invalid data. Automatically recognizes unknown text and URL frames.
- The order of frames in a tag is fully customizable.
- Package comes with extensive unit tests for an extra measure of code kwalitee.
- Tested under Mac OS X, Windows and GNU/Linux.
>>> import stagger
>>> from stagger.id3 import * # contains ID3 frame types
>>> tag = stagger.read_tag("track01.mp3")
>>> tag[TIT2] # tag is a MutableMapping
TIT2(utf-8 "Staralfur")
>>> tag[TIT2] = TIT2(text="The Show Must Go On") # Explicit constructor
>>> tag[TIT2] = "The Show Must Go On" # Implicit constructor
>>> tag[TIT2] = ("Foo", "Bar", "Baz") # Multiple strings
>>> tag.title = "The Battle of Evermore" # Alternative, friendlier API
>>> tag.write()