cs.id3 20211208

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/

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 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.

Class EnhancedTagFrame(cs.binary.SimpleBinary,types.SimpleNamespace,cs.binary.AbstractBinary,cs.binary.BinaryMixin)

An Enhanced Tag.

Method EnhancedTagFrame.parse(bfr)

Parse an enhanced tag.

Method 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.

Method ID3.__getitem__(self, key)

Fetch the text of the specified frame.

Method ID3.__setitem__(self, key, value)

Set a frame text to value.

Method ID3.clean(self, attr)

Strip NULs and leading and trailing whitespace.

Method ID3.flush(self, *a, **kw)

Update the ID3 tags in the file if modified, otherwise no-op. Clears the modified flag.

Method ID3.get_frame(self, frameid)

Return the frame with the specified frameid, or None.

Property ID3.tag

The tag mapping from self.pathname.

Class ID3V1Frame(cs.binary.SimpleBinary,types.SimpleNamespace,cs.binary.AbstractBinary,cs.binary.BinaryMixin)

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

Method ID3V1Frame.parse(bfr)

Parse a 128 byte ID3V1 or ID3v1.1 record.

Method ID3V1Frame.tagset(self)

Return a TagSet with the ID3 tag information.

Method ID3V1Frame.transcribe(self)

Transcribe the ID3V1 frame.

Class ID3V22TagDataFrame(cs.binary.SimpleBinary,types.SimpleNamespace,cs.binary.AbstractBinary,cs.binary.BinaryMixin)

An ID3 v2.2.0 tag data frame.

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

Method 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,types.SimpleNamespace,cs.binary.AbstractBinary,cs.binary.BinaryMixin)

An ID3 v2.3.0 tag data frame.

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

Method 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,types.SimpleNamespace,cs.binary.AbstractBinary,cs.binary.BinaryMixin)

An ID3v2 frame, based on the document at: https://web.archive.org/web/20120527211939/http://www.unixgods.org/~tilo/ID3/docs/id3v2-00.html

Method ID3V2Frame.parse(bfr)

Return an ID3v2 frame as described here:

Method ID3V2Frame.tagset(self)

Return a TagSet with the ID3 tag information.

Method ID3V2Frame.transcribe(self)

Transcribe the ID3v2 frame.

Class ID3V2Size(cs.binary.BinarySingleValue,cs.binary.AbstractBinary,cs.binary.BinaryMixin)

An ID3v2 size field, a big endian 4 byte field of 7-bit values, high bit 0.

Method ID3V2Size.parse_value(bfr)

Read an ID3V2 size field from bfr, return the size.

Method ID3V2Size.transcribe_value(size)

Transcribe a size in ID3v2 format.

Class ID3V2Tags(types.SimpleNamespace)

An ID3V2Tags maps ID3V2 tag information as a SimpleNamespace.

Method ID3V2Tags.__getattr__(self, attr)

Catch frame id attrs and their wordier versions.

Method ID3V2Tags.__setattr__(self, attr, value)

Map attributes to frame ids, set the corresponding __dict__ entry.

Class ISO8859_1NULString(cs.binary.BinarySingleValue,cs.binary.AbstractBinary,cs.binary.BinaryMixin)

A NUL terminated string encoded with ISO8859-1.

Method ISO8859_1NULString.transcribe_value(s)

pylint: disable=arguments-differ

Function padded_text(text, length, encoding='ascii')

Encode text using encoding, crop to a maximum of length bytes, pad with NULs to length if necessary.

Function 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,cs.binary.AbstractBinary,cs.binary.BinaryMixin)

A trite class to parse the single byte text encoding field.

Class TextInformationFrameBody(cs.binary.SimpleBinary,types.SimpleNamespace,cs.binary.AbstractBinary,cs.binary.BinaryMixin)

A text information frame.

Method TextInformationFrameBody.parse(bfr)

Parse the text from the frame.

Method TextInformationFrameBody.transcribe(self)

Transcribe the frame.

Class UCS2NULString(cs.binary.BinarySingleValue,cs.binary.AbstractBinary,cs.binary.BinaryMixin)

A NUL terminated string encoded with UCS-2.

We're cheating and using UTF16 for this.

Method UCS2NULString.transcribe_value(s)

Transcribe text as UTF-16-LE with leading BOM and trailing NUL.

Release Log

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.