Skip to content

Latest commit

 

History

History
41 lines (29 loc) · 2 KB

README.rst

File metadata and controls

41 lines (29 loc) · 2 KB

Stagger

https://travis-ci.org/lorentey/stagger.svg?branch=master

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