Support for ID3 tags. A cs.binary based parser/transcriber for ID3 tags and a convenience wrapper for Doug Zongker's pyid3lib: http://pyid3lib.sourceforge.net/

Latest release 20260531: Provide value_type for the BinarySingleValue subclasses.

Short summary:

• EnhancedTagFrame: An Enhanced Tag.
• ID3: Wrapper for pyid3lib.tag.
• ID3V1Frame: An ID3V1 or ID3v1.1 data frame as described in wikipedia: https://en.wikipedia.org/wiki/ID3.
• ID3V22TagDataFrame: An ID3 v2.2.0 tag data frame.
• ID3V23TagDataFrame: An ID3 v2.3.0 tag data frame.
• ID3V2Frame: An ID3v2 frame, based on the document at: https://web.archive.org/web/20120527211939/http://www.unixgods.org/~tilo/ID3/docs/id3v2-00.html.
• ID3V2Size: An ID3v2 size field, a big endian 4 byte field of 7-bit values, high bit 0.
• ID3V2Tags: An ID3V2Tags maps ID3V2 tag information as a SimpleNamespace.
• ISO8859_1NULString: A NUL terminated string encoded with ISO8859-1.
• padded_text: Encode text using encoding, crop to a maximum of length bytes, pad with NULs to length if necessary.
• parse_padded_text: Fetch length bytes from bfr, strip trailing NULs, decode using encoding (default 'ascii'), strip trailling whitepsace.
• TextEncodingClass: A trite class to parse the single byte text encoding field.
• TextInformationFrameBody: A text information frame.
• UCS2NULString: A NUL terminated string encoded with UCS-2.

Module contents:

• class EnhancedTagFrame(cs.binary.SimpleBinary): An Enhanced Tag.

EnhancedTagFrame.parse(bfr): Parse an enhanced tag.

EnhancedTagFrame.transcribe(self): Transcribe the enhanced tag.

• class ID3(types.SimpleNamespace): Wrapper for pyid3lib.tag.

  OBSOLETE. Going away when I'm sure the other classes cover all this stuff off.

ID3.__getitem__(self, key): Fetch the text of the specified frame.

ID3.__setitem__(self, key, value): Set a frame text to value.

ID3.clean(self, attr): Strip NULs and leading and trailing whitespace.

ID3.flush(self): Update the ID3 tags in the file if modified, otherwise no-op. Clears the modified flag.

ID3.get_frame(self, frameid): Return the frame with the specified frameid, or None.

ID3.tag: The tag mapping from self.pathname.

• class ID3V1Frame(cs.binary.SimpleBinary): An ID3V1 or ID3v1.1 data frame as described in wikipedia: https://en.wikipedia.org/wiki/ID3

  The following fields are defined:

  • title: up to 30 ASCII characters
  • artist: up to 30 ASCII characters
  • album: up to 30 ASCII characters
  • year: 4 digit ASCII year
  • comment: up to 30 ASCII bytes, NUL or whitespace padded, up to 28 ASCII bytes if track is nonzero
  • track: 0 for no track, a number from 1 through 255 otherwise; if nonzero then the comment field may only be up to 28 bytes long
  • genre_id: a number value from 0 to 255

ID3V1Frame.parse(bfr): Parse a 128 byte ID3V1 or ID3v1.1 record.

ID3V1Frame.tagset(self): Return a TagSet with the ID3 tag information.

ID3V1Frame.transcribe(self): Transcribe the ID3V1 frame.

• class ID3V22TagDataFrame(cs.binary.SimpleBinary): An ID3 v2.2.0 tag data frame.

  Reference doc: https://id3.org/id3v2-00

ID3V22TagDataFrame.tag_id_class(tag_id): Return the AbstractBinary subclass to decode the a tag body from its tag id. Return None for unrecognised ids.

• class ID3V23TagDataFrame(cs.binary.SimpleBinary): An ID3 v2.3.0 tag data frame.

  Reference doc: https://id3.org/id3v2.3.0

ID3V23TagDataFrame.tag_id_class(tag_id): Return the AbstractBinary subclass to decode the a tag body from its tag id. Return None for unrecognised ids.

• class ID3V2Frame(cs.binary.SimpleBinary): An ID3v2 frame, based on the document at: https://web.archive.org/web/20120527211939/http://www.unixgods.org/~tilo/ID3/docs/id3v2-00.html

ID3V2Frame.parse(bfr): Return an ID3v2 frame as described here:

ID3V2Frame.tagset(self): Return a TagSet with the ID3 tag information.

ID3V2Frame.transcribe(self): Transcribe the ID3v2 frame.

• class ID3V2Size(cs.binary.BinarySingleValue): An ID3v2 size field, a big endian 4 byte field of 7-bit values, high bit 0.

ID3V2Size.VALUE_TYPE

ID3V2Size.parse_value(bfr): Read an ID3V2 size field from bfr, return the size.

ID3V2Size.transcribe_value(size): Transcribe a size in ID3v2 format.

• class ID3V2Tags(types.SimpleNamespace): An ID3V2Tags maps ID3V2 tag information as a SimpleNamespace.

ID3V2Tags.__getattr__(self, attr): Catch frame id attrs and their wordier versions.

ID3V2Tags.__setattr__(self, attr, value): Map attributes to frame ids, set the corresponding __dict__ entry.

• class ISO8859_1NULString(cs.binary.BinarySingleValue): A NUL terminated string encoded with ISO8859-1.

ISO8859_1NULString.VALUE_TYPE

ISO8859_1NULString.transcribe_value(s): pylint: disable=arguments-differ

• padded_text(text, length, encoding='ascii'): Encode text using encoding, crop to a maximum of length bytes, pad with NULs to length if necessary.
• parse_padded_text(bfr, length, encoding='ascii'): Fetch length bytes from bfr, strip trailing NULs, decode using encoding (default 'ascii'), strip trailling whitepsace.
• class TextEncodingClass(cs.binary.BinarySingleValue): A trite class to parse the single byte text encoding field.

TextEncodingClass.VALUE_TYPE

• class TextInformationFrameBody(cs.binary.SimpleBinary): A text information frame.

TextInformationFrameBody.parse(bfr): Parse the text from the frame.

TextInformationFrameBody.transcribe(self): Transcribe the frame.

• class UCS2NULString(cs.binary.BinarySingleValue): A NUL terminated string encoded with UCS-2.

  We're cheating and using UTF16 for this.

UCS2NULString.VALUE_TYPE

UCS2NULString.transcribe_value(s): Transcribe text as UTF-16-LE with leading BOM and trailing NUL.

Release Log

Release 20260531: Provide value_type for the BinarySingleValue subclasses.

Release 20211208:

• ID3V1 and ID3V2 support.
• ID3V1Frame,ID3V2Frame: new .tagset() method to return a TagSet.
• ID3V1Frame.parse: trim trailing NULs from the comment field.
• Assorted other small changes.

Release 20160828: Use "install_requires" instead of "requires" in DISTINFO.

Release 20150116.2: pyid3lib not on PyPI, remove from requirements and mention in README

Release 20150116: Initial PyPI release.