stagger's Introduction

Stagger

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

Recommend Projects