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 partial 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. This fork aims to maintain compatibility with recent Python versions.

Features

• 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 quality
• Tested under Mac OS X, Windows and GNU/Linux

>>> from stagger import read_tag
>>> from stagger.id3 import TIT2                  # Support for all ID3 tags
>>> tag = read_tag("track01.mp3")                 # Read and parse a file
>>> tag[TIT2]                                     # Every 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 string support
>>> tag.title = "The Battle of Evermore"          # Easy and friendly API
>>> tag.bitrate                                   # Bitrate info is read too
320
>>> tag.write()                                   # Write changes back to file

Install

You can add it to your setup.py or pyproject.toml file as a dependency using:

stagger @ git+https://git@github.com/Jelmerro/stagger@master

Contribute

You can support my work on ko-fi or Github sponsors. Another way to help is to report issues or suggest new features. Please try to follow recommendations by flake8 and pylint when developing. For an example vimrc that can auto-format based on the included linters, you can check out my personal vimrc. The unit tests can be run with: python -m unittest test/*.py.