Although it’s more convenient to manipulate the high-level audiotools.MetaData base class, one sometimes needs to be able to view and modify the low-level implementation also.
This is an APEv2 tag used by the WavPack, Monkey’s Audio and Musepack formats, among others. During initialization, it takes a list of ApeTagItem objects and optional contains_header, contains_footer booleans. It can then be manipulated like a regular Python dict with keys as strings and values as ApeTagItem objects. Note that this is also a audiotools.MetaData subclass with all of the same methods.
For example:
>>> tag = ApeTag([ApeTagItem(0, False, 'Title', u'Track Title'.encode('utf-8'))])
>>> tag.track_name
u'Track Title'
>>> tag['Title']
ApeTagItem(0, False, 'Title', 'Track Title')
>>> tag['Title'] = ApeTagItem(0, False, 'Title', u'New Title'.encode('utf-8'))
>>> tag.track_name
u'New Title'
>>> tag.track_name = u'Yet Another Title'
>>> tag['Title']
ApeTagItem(0, False, 'Title', 'Yet Another Title')
The fields are mapped between ApeTag and audiotools.MetaData as follows:
| APEv2 | Metadata |
| Title | track_name |
| Track | track_number/track_total |
| Media | album_number/album_total |
| Album | album_name |
| Artist | artist_name |
| Performer | performer_name |
| Composer | composer_name |
| Conductor | conductor_name |
| ISRC | ISRC |
| Catalog | catalog |
| Copyright | copyright |
| Publisher | publisher |
| Year | year |
| Record Date | date |
| Comment | comment |
Note that Track and Media may be “/”-separated integer values where the first is the current number and the second is the total number.
>>> tag = ApeTag([ApeTagItem(0, False, 'Track', u'1'.encode('utf-8'))])
>>> tag.track_number
1
>>> tag.track_total # None
>>> tag = ApeTag([ApeTagItem(0, False, 'Track', u'2/3'.encode('utf-8'))])
>>> tag.track_number
2
>>> tag.track_total
3
Takes an open file object and returns an ApeTag object of that file’s APEv2 data, or None if the tag cannot be found.
Given a audiotools.bitstream.BitstreamWriter object positioned at the end of the file, this writes the ApeTag to that stream.
Returns the minimum size of the entire APEv2 tag, in bytes.
This is the container for ApeTag data. item_type is an integer with one of the following values:
| 1 | UTF-8 data |
| 2 | binary data |
| 3 | external data |
| 4 | reserved |
read_only is a boolean set to True if the tag-item is read-only. key is an ASCII string. data is a regular Python string (not Unicode).
Returns this tag item’s data as a string.
A convenience classmethod which takes strings of key and value data and returns a populated ApeTagItem object of the appropriate type.
A convenience classmethod which takes strings of key and value data and returns a populated ApeTagItem object of the appropriate type.
A convenience classmethod which takes a key string and value Unicode and returns a populated ApeTagItem object of the appropriate type.
This is a FLAC tag which is prepended to FLAC and Ogg FLAC files. It is initialized with a list of FLAC metadata block objects which it stores internally as a list. It also supports all audiotools.MetaData methods.
For example:
>>> tag = FlacMetaData([Flac_VORBISCOMMENT(
... [u'TITLE=Track Title'], u'Vendor String')])
>>> tag.track_name
u'Track Title'
>>> tag.get_block(Flac_VORBISCOMMENT.BLOCK_ID)
Flac_VORBISCOMMENT([u'TITLE=Track Title'], u'Vendor String')
>>> tag.replace_blocks(Flac_VORBISCOMMENT.BLOCK_ID,
... [Flac_VORBISCOMMENT([u'TITLE=New Track Title'], u'Vendor String')])
>>> tag.track_name
u'New Track Title'
Returns True if the given block ID integer is present in this metadata’s list of blocks.
Adds the given block to this metadata’s list of blocks. Blocks are added such that STREAMINFO will always be first.
Returns the first instance of the given block ID. May raise IndexError if the block ID is not present.
Returns all instances of the given block ID as a list, which may be empty if no matching blocks are present.
Replaces all instances of the given block ID with those taken from the list of blocks. If insufficient blocks are found to replace, this uses FlacMetaData.add_block() to populate the remainder. If additional blocks are found, they are removed.
Yields a set of all blocks this metadata contains.
Given a audiotools.bitstream.BitstreamReader positioned past the FLAC file’s "fLaC" file header, returns a parsed FlacMetaData object. May raise IOError or ValueError if some error occurs parsing the metadata.
Returns this metadata as a human-readable Unicode string.
Returns the size of all metadata blocks including the 32-bit block headers but not including the file’s 4-byte "fLaC" ID.
All values are non-negative integers except for md5sum, which is a 16-byte binary string. All are stored in this metadata block as-is.
This metadata’s block ID as a non-negative integer.
Returns a copy of this metadata block.
Returns this metadata block as a human-readable Unicode string.
Given a audiotools.bitstream.BitstreamReader, returns a parsed Flac_STREAMINFO object. This presumes its 32-bit metadata header has already been read.
Writes this metadata block to the given audiotools.bitstream.BitstreamWriter, not including its 32-bit metadata header.
Returns the size of the metadata block, not including its 32-bit metadata header.
Length is the length of the padding, in bytes.
This metadata’s block ID as a non-negative integer.
Returns a copy of this metadata block.
Returns this metadata block as a human-readable Unicode string.
Given a audiotools.bitstream.BitstreamReader, returns a parsed Flac_PADDING object. This presumes its 32-bit metadata header has already been read.
Writes this metadata block to the given audiotools.bitstream.BitstreamWriter, not including its 32-bit metadata header.
Returns the size of the metadata block, not including its 32-bit metadata header.
application_id is a 4-byte binary string. data is a binary string.
This metadata’s block ID as a non-negative integer.
Returns a copy of this metadata block.
Returns this metadata block as a human-readable Unicode string.
Given a audiotools.bitstream.BitstreamReader, returns a parsed Flac_APPLICATION object. This presumes its 32-bit metadata header has already been read.
Writes this metadata block to the given audiotools.bitstream.BitstreamWriter, not including its 32-bit metadata header.
Returns the size of the metadata block, not including its 32-bit metadata header.
seekpoints is a list of (PCM frame offset, byte offset, PCM frame count) tuples for each seek point in the seektable.
This metadata’s block ID as a non-negative integer.
Returns a copy of this metadata block.
Returns this metadata block as a human-readable Unicode string.
Given a audiotools.bitstream.BitstreamReader, returns a parsed Flac_SEEKTABLE object. This presumes its 32-bit metadata header has already been read.
Writes this metadata block to the given audiotools.bitstream.BitstreamWriter, not including its 32-bit metadata header.
Returns the size of the metadata block, not including its 32-bit metadata header.
Returns a fixed FLAC seektable with empty seek points removed and byte offset / PCM frame count values reordered to be incrementing. Any fixes performed are appended to the fixes_performed list as Unicode strings.
comment_strings is a list of Unicode strings and vendor_string is a Unicode string.
See VorbisComment on how to map strings to attributes.
>>> Flac_VORBISCOMMENT([u"TITLE=Foo", u"ARTIST=Bar"], u"Python Audio Tools")
This metadata’s block ID as a non-negative integer.
Returns a copy of this metadata block.
Returns this metadata block as a human-readable Unicode string.
Given a audiotools.bitstream.BitstreamReader, returns a parsed Flac_VORBISCOMMENT object. This presumes its 32-bit metadata header has already been read.
Writes this metadata block to the given audiotools.bitstream.BitstreamWriter, not including its 32-bit metadata header.
Returns the size of the metadata block, not including its 32-bit metadata header.
Given a audiotools.MetaData-compatible object, returns a Flac_VORBISCOMMENT object.
catalog_number is a 128 byte binary string. lead_in_samples is a non-negative integer. is_cdda is 1 if the cuesheet is from an audio CD, 0 if not. tracks is a list of Flac_CUESHEET_track objects.
This metadata’s block ID as a non-negative integer.
Returns a copy of this metadata block.
Returns this metadata block as a human-readable Unicode string.
Given a audiotools.bitstream.BitstreamReader, returns a parsed Flac_CUESHEET object. This presumes its 32-bit metadata header has already been read.
Writes this metadata block to the given audiotools.bitstream.BitstreamWriter, not including its 32-bit metadata header.
Returns the size of the metadata block, not including its 32-bit metadata header.
Given a audiotools.Sheet-compatible object, total length of the file in PCM frames and an optional sample rate, returns a new Flac_CUESHEET object.
Returns a list of all track numbers in the sheet, typically starting from 1.
Given a track number, returns the corresponnding Flac_CUESHEET_track object, or raises KeyError if the track is not found.
Returns the pre-gap of the entire disc as a Fraction number of seconds.
Given a track number, returns the offset to track track from the start of the stream as a Fraction number of seconds.
May raise KeyError if the track is not found.
Given a track number, returns the length of that track as a Fraction number of seconds.
Note
Unlike with regular audiotools.Sheet objects in which the final track’s length may be None, the lengths of all valid FLAC cuesheet tracks will be known.
Always returns True for FLAC cuesheets.
Returns a audiotools.MetaData object for sheet-specific metadata embedded in the cuesheet. For FLAC cuesheets, this will only contain the catalog number as a Unicode string.
offset is the track’s first index point offset from the start of the stream, in PCM frames. number number is the track’s number on the CD, typically starting from 1. ISRC is the track’s ISRC number as a 12 byte binary string. track_type is 0 for audio, 1 for non-audio. pre_emphasis is 0 for tracks with no pre-emphasis, 1 for tracks with pre-emphasis. index_points is a list of Flac_CUESHEET_index objects.
Returns a copy of this cuesheet track.
Returns this cuesheet track as a human-readable Unicode string.
Given a audiotools.bitstream.BitstreamReader, returns a parsed Flac_CUESHEET_track object.
Writes this cuesheet track to the given audiotools.bitstream.BitstreamWriter.
Returns the track’s number, typically starting from 1.
Returns a list of all index points numbers in the track. A point number of 0 indicates a pre-gap index point.
Given an index number, returns a Flac_CUESHEET_index object.
May raise KeyError if the index point is not found.
Returns a audiotools.MetaData object of the track’s metadata. For FLAC cuesheets, this will be limited to the ISRC.
Returns the track’s filename as a string. For FLAC cuesheets, this will always be the FLAC file which contains the cuesheet.
Always returns True.
Returns True if the track has pre-emphasis.
Always returns True.
offset is the index point’s offset. number is the index point’s number in the set.
Returns a copy of this cuesheet index.
Given a audiotools.bitstream.BitstreamReader, returns a parsed Flac_CUESHEET_index object.
Writes this index point to the given audiotools.bitstream.BitstreamWriter.
Returns this index point’s number where 0 indicates a pre-gap index.
Returns this index point’s offset from the start of the stream as a Fraction number of seconds.
picture_type is one of the following:
| 0 | Other |
| 1 | 32x32 pixels ‘file icon’ (PNG only) |
| 2 | Other file icon |
| 3 | Cover (front) |
| 4 | Cover (back) |
| 5 | Leaflet page |
| 6 | Media (e.g. label side of CD) |
| 7 | Lead artist/lead performer/soloist |
| 8 | Artist/performer |
| 9 | Conductor |
| 10 | Band/Orchestra |
| 11 | Composer |
| 12 | Lyricist/text writer |
| 13 | Recording Location |
| 14 | During recording |
| 15 | During performance |
| 16 | Movie/video screen capture |
| 17 | A bright colored fish |
| 18 | Illustration |
| 19 | Band/artist logotype |
| 20 | Publisher/Studio logotype |
mime_type and description are Unicode strings. width and height are integer number of pixels. color_depth is an integer number of bits per pixel. color_count is an integer number of colors for images with indexed colors, or 0 for formats such as JPEG with no indexed colors. data is a binary string of raw image data.
This is a subclass of audiotools.Image which shares all the same methods and attributes.
This metadata’s block ID as a non-negative integer.
Returns a copy of this metadata block.
Returns this metadata block as a human-readable Unicode string.
Given a audiotools.bitstream.BitstreamReader, returns a parsed Flac_IMAGE object. This presumes its 32-bit metadata header has already been read.
Writes this metadata block to the given audiotools.bitstream.BitstreamWriter, not including its 32-bit metadata header.
Returns the size of the metadata block, not including its 32-bit metadata header.
Given an Flac_IMAGE-compatible object, returns a new Flac_IMAGE block.
Returns a new Flac_IMAGE block with metadata fields cleaned up according to the metrics of the contained raw image data. Any fixes are appended to the fixes_performed list as Unicode strings.
All fields are binary strings with a fixed length:
| field | length |
| track_name | 30 |
| artist_name | 30 |
| album_name | 30 |
| year | 4 |
| comment | 28 |
| track_number | 1 |
| genre | 1 |
>>> tag = ID3v1Comment(track_name='Track Title' + chr(0) * 19, # note the NULL byte padding
... track_number=chr(1))
>>> tag.track_name
u'Track Title'
>>> tag.track_name = u'New Track Name'
>>> tag.track_name
u'New Track Name'
Undefined fields are filled with NULL bytes. Attempting to initialize a field with an incorrect size will raise a ValueError.
Returns this metadata as a human-readable Unicode string.
Given a seekable file object of an MP3 file, returns an ID3v1Comment object. Raises ValueError if the comment is invalid.
Given a file object positioned at the end of an MP3 file, appends this ID3v1 comment to that file.
This is an ID3v2.2 tag, one of the three ID3v2 variants used by MP3 files. During initialization, it takes a list of ID3v22_Frame-compatible objects. It can then be manipulated like a regular Python dict with keys as 3 character frame identifiers and values as lists of ID3v22_Frame objects - since each frame identifier may occur multiple times.
For example:
>>> tag = ID3v22Comment([ID3v22_T__Frame('TT2', 0, u'Track Title')])
>>> tag.track_name
u'Track Title'
>>> tag['TT2']
[<audiotools.__id3__.ID3v22_T__Frame instance at 0x1004c17a0>]
>>> tag['TT2'] = [ID3v22_T__Frame('TT2', 0, u'New Track Title')]
>>> tag.track_name
u'New Track Title'
Fields are mapped between ID3v2.2 frame identifiers, audiotools.MetaData and ID3v22Frame objects as follows:
| Identifier | MetaData | Object |
| TT2 | track_name | ID3v22_T__Frame |
| TRK | track_number/track_total | ID3v22_T__Frame |
| TPA | album_number/album_total | ID3v22_T__Frame |
| TAL | album_name | ID3v22_T__Frame |
| TP1 | artist_name | ID3v22_T__Frame |
| TP2 | performer_name | ID3v22_T__Frame |
| TP3 | conductor_name | ID3v22_T__Frame |
| TCM | composer_name | ID3v22_T__Frame |
| TMT | media | ID3v22_T__Frame |
| TRC | ISRC | ID3v22_T__Frame |
| TCR | copyright | ID3v22_T__Frame |
| TPB | publisher | ID3v22_T__Frame |
| TYE | year | ID3v22_T__Frame |
| TRD | date | ID3v22_T__Frame |
| COM | comment | ID3v22_COM_Frame |
| PIC | images() | ID3v22_PIC_Frame |
The optional total_size field is the total size of the tag, not including the 6 byte ID3 header. If the total size is larger than the size of all tags, the remaining space will be padded with NULL bytes.
This is the base class for the various ID3v2.2 frames. frame_id is a 3 character string and data is the frame’s contents as a string.
Returns a new copy of this frame.
Returns this frame as a human-readable Unicode string.
Given a 3 byte frame ID, frame size and audiotools.bitstream.BitstreamReader (positioned past the 6 byte frame header) returns a parsed ID3v22Frame object.
Writes frame to the given audiotools.bitstream.BitstreamWriter, not including its 6 byte frame header.
Returns the frame’s size, not including its 6 byte frame header.
Returns a new ID3v22Frame object that’s been cleaned of any problems. Any fixes performed are appended to fixes_performed as Unicode strings.
This ID3v22_Frame-compatible object is a container for textual data. frame_id is a 3 character string, data is a binary string and encoding is one of the following integers representing a text encoding:
| 0 | Latin-1 |
| 1 | UCS-2 |
Returns the first integer portion of the frame data as an int if the frame is container for numerical data such as TRK or TPA.
Returns the second integer portion of the frame data as an int if the frame is a numerical container and has a “total” field. For example:
>>> f = ID3v22_T__Frame('TRK', 0, '1/2')
>>> f.number()
1
>>> f.total()
2
Given a 3 byte frame ID and Unicode string, returns a new ID3v22_T__Frame object.
This subclass of ID3v22_T__Frame contains an additional description binary string field to hold user-defined textual data.
This ID3v22_Frame-compatible object is a container for web links. frame_id is a 3 character string, url is a binary string.
This subclass of ID3v22_W__Frame contains an additional description binary string field to hold user-defined web link data.
This ID3v22_Frame-compatible object is for holding a potentially large block of comment data. encoding is the same as in text frames:
| 0 | Latin-1 |
| 1 | UCS-2 |
language is a 3 character string, such as "eng" for English. short_description is a C_string object. data is a binary string.
Given a 3 byte "COM" frame ID and Unicode string, returns a new ID3v22_COM_Frame object.
This is a subclass of audiotools.Image, in addition to being a ID3v22_Frame-compatible object. image_format is one of the following:
| "PNG" | PNG |
| "JPG" | JPEG |
| "BMP" | Bitmap |
| "GIF" | GIF |
| "TIF" | TIFF |
picture_type is an integer representing one of the following:
| 0 | Other |
| 1 | 32x32 pixels ‘file icon’ (PNG only) |
| 2 | Other file icon |
| 3 | Cover (front) |
| 4 | Cover (back) |
| 5 | Leaflet page |
| 6 | Media (e.g. label side of CD) |
| 7 | Lead artist / Lead performer / Soloist |
| 8 | Artist / Performer |
| 9 | Conductor |
| 10 | Band / Orchestra |
| 11 | Composer |
| 12 | Lyricist / Text writer |
| 13 | Recording Location |
| 14 | During recording |
| 15 | During performance |
| 16 | Movie / Video screen capture |
| 17 | A bright colored fish |
| 18 | Illustration |
| 19 | Band / Artist logotype |
| 20 | Publisher / Studio logotype |
description is a C_string. data is a string of binary image data.
Returns the picture_type as a plain string.
Given an audiotools.Image object, returns a new ID3v22_PIC_Frame object.
This is an ID3v2.3 tag, one of the three ID3v2 variants used by MP3 files. During initialization, it takes a list of ID3v23_Frame-compatible objects. It can then be manipulated like a regular Python dict with keys as 4 character frame identifiers and values as lists of ID3v23_Frame objects - since each frame identifier may occur multiple times.
For example:
>>> tag = ID3v23Comment([ID3v23_T___Frame('TIT2', 0, u'Track Title')])
>>> tag.track_name
u'Track Title'
>>> tag['TIT2']
[ID3v23_T___Frame('TIT2', 0, u'Track Title')]
>>> tag['TIT2'] = [ID3v23_T___Frame('TIT2', 0, u'New Track Title')]
>>> tag.track_name
u'New Track Title'
Fields are mapped between ID3v2.3 frame identifiers, audiotools.MetaData and ID3v23_Frame objects as follows:
| Identifier | MetaData | Object |
| TIT2 | track_name | ID3v23_T___Frame |
| TRCK | track_number/track_total | ID3v23_T___Frame |
| TPOS | album_number/album_total | ID3v23_T___Frame |
| TALB | album_name | ID3v23_T___Frame |
| TPE1 | artist_name | ID3v23_T___Frame |
| TPE2 | performer_name | ID3v23_T___Frame |
| TPE3 | conductor_name | ID3v23_T___Frame |
| TCOM | composer_name | ID3v23_T___Frame |
| TMED | media | ID3v23_T___Frame |
| TSRC | ISRC | ID3v23_T___Frame |
| TCOP | copyright | ID3v23_T___Frame |
| TPUB | publisher | ID3v23_T___Frame |
| TYER | year | ID3v23_T___Frame |
| TRDA | date | ID3v23_T___Frame |
| COMM | comment | ID3v23_COMM_Frame |
| APIC | images() | ID3v23_APIC_Frame |
The optional total_size field is the total size of the tag, not including the 6 byte ID3 header. If the total size is larger than the size of all tags, the remaining space will be padded with NULL bytes.
This is the base class for the various ID3v2.3 frames. frame_id is a 4 character string and data is the frame’s contents as a string.
Returns a new copy of this frame.
Returns this frame as a human-readable Unicode string.
Given a 4 byte frame ID, frame size and audiotools.bitstream.BitstreamReader (positioned past the 10 byte frame header) returns a parsed ID3v23_Frame object.
Writes frame to the given audiotools.bitstream.BitstreamWriter, not including its 10 byte frame header.
Returns the frame’s size, not including its 10 byte frame header.
Returns a new ID3v23_Frame object that’s been cleaned of any problems. Any fixes performed are appended to fixes_performed as Unicode strings.
This ID3v23_Frame-compatible object is a container for textual data. frame_id is a 3 character string, data is a binary string and encoding is one of the following integers representing a text encoding:
| 0 | Latin-1 |
| 1 | UCS-2 |
Returns the first integer portion of the frame data as an int if the frame is container for numerical data such as TRCK or TPOS.
Returns the second integer portion of the frame data as an int if the frame is a numerical container and has a “total” field. For example:
>>> f = ID3v23_T___Frame('TRCK', 0, '1/2')
>>> f.number()
1
>>> f.total()
2
Given a 4 byte frame ID and Unicode string, returns a new ID3v23_T___Frame object.
This subclass of ID3v23_T___Frame contains an additional description binary string field to hold user-defined textual data.
This ID3v23_Frame-compatible object is a container for web links. frame_id is a 4 character string, url is a binary string.
This subclass of ID3v23_W___Frame contains an additional description binary string field to hold user-defined web link data.
This ID3v23_Frame-compatible object is for holding a potentially large block of comment data. encoding is the same as in text frames:
| 0 | Latin-1 |
| 1 | UCS-2 |
language is a 3 character string, such as "eng" for English. short_description is a C_string object. data is a binary string.
Given a 4 byte "COMM" frame ID and Unicode string, returns a new ID3v23_COMM_Frame object.
This is a subclass of audiotools.Image, in addition to being a ID3v23_Frame-compatible object. mime_type is a C_string. picture_type is an integer representing one of the following:
| 0 | Other |
| 1 | 32x32 pixels ‘file icon’ (PNG only) |
| 2 | Other file icon |
| 3 | Cover (front) |
| 4 | Cover (back) |
| 5 | Leaflet page |
| 6 | Media (e.g. label side of CD) |
| 7 | Lead artist / Lead performer / Soloist |
| 8 | Artist / Performer |
| 9 | Conductor |
| 10 | Band / Orchestra |
| 11 | Composer |
| 12 | Lyricist / Text writer |
| 13 | Recording Location |
| 14 | During recording |
| 15 | During performance |
| 16 | Movie / Video screen capture |
| 17 | A bright colored fish |
| 18 | Illustration |
| 19 | Band / Artist logotype |
| 20 | Publisher / Studio logotype |
description is a C_string. data is a string of binary image data.
Returns the picture_type as a plain string.
Given an audiotools.Image object, returns a new ID3v23_APIC_Frame object.
This is an ID3v2.4 tag, one of the three ID3v2 variants used by MP3 files. During initialization, it takes a list of ID3v24_Frame-compatible objects. It can then be manipulated like a regular Python dict with keys as 4 character frame identifiers and values as lists of ID3v24_Frame objects - since each frame identifier may occur multiple times.
For example:
>>> tag = ID3v24Comment([ID3v24_T___Frame('TIT2', 0, u'Track Title')])
>>> tag.track_name
u'Track Title'
>>> tag['TIT2']
[ID3v24_T___Frame('TIT2', 0, u'Track Title')]
>>> tag['TIT2'] = [ID3v24_T___Frame('TIT2', 0, u'New Track Title')]
>>> tag.track_name
u'New Track Title'
Fields are mapped between ID3v2.4 frame identifiers, audiotools.MetaData and ID3v24_Frame objects as follows:
| Identifier | MetaData | Object |
| TIT2 | track_name | ID3v24_T___Frame |
| TRCK | track_number/track_total | ID3v24_T___Frame |
| TPOS | album_number/album_total | ID3v24_T___Frame |
| TALB | album_name | ID3v24_T___Frame |
| TPE1 | artist_name | ID3v24_T___Frame |
| TPE2 | performer_name | ID3v24_T___Frame |
| TPE3 | conductor_name | ID3v24_T___Frame |
| TCOM | composer_name | ID3v24_T___Frame |
| TMED | media | ID3v24_T___Frame |
| TSRC | ISRC | ID3v24_T___Frame |
| TCOP | copyright | ID3v24_T___Frame |
| TPUB | publisher | ID3v24_T___Frame |
| TYER | year | ID3v24_T___Frame |
| TRDA | date | ID3v24_T___Frame |
| COMM | comment | ID3v24_COMM_Frame |
| APIC | images() | ID3v24_APIC_Frame |
The optional total_size field is the total size of the tag, not including the 6 byte ID3 header. If the total size is larger than the size of all tags, the remaining space will be padded with NULL bytes.
This is the base class for the various ID3v2.4 frames. frame_id is a 4 character string and data is the frame’s contents as a string.
Returns a new copy of this frame.
Returns this frame as a human-readable Unicode string.
Given a 4 byte frame ID, frame size and audiotools.bitstream.BitstreamReader (positioned past the 10 byte frame header) returns a parsed ID3v24_Frame object.
Writes frame to the given audiotools.bitstream.BitstreamWriter, not including its 10 byte frame header.
Returns the frame’s size, not including its 10 byte frame header.
Returns a new ID3v24_Frame object that’s been cleaned of any problems. Any fixes performed are appended to fixes_performed as Unicode strings.
This ID3v24_Frame-compatible object is a container for textual data. frame_id is a 3 character string, data is a binary string and encoding is one of the following integers representing a text encoding:
| 0 | Latin-1 |
| 1 | UTF-16 |
| 2 | UTF-16BE |
| 3 | UTF-8 |
Returns the first integer portion of the frame data as an int if the frame is container for numerical data such as TRCK or TPOS.
Returns the second integer portion of the frame data as an int if the frame is a numerical container and has a “total” field. For example:
>>> f = ID3v24_T___Frame('TRCK', 0, '1/2')
>>> f.number()
1
>>> f.total()
2
Given a 4 byte frame ID and Unicode string, returns a new ID3v24_T___Frame object.
This subclass of ID3v24_T___Frame contains an additional description binary string field to hold user-defined textual data.
This ID3v24_Frame-compatible object is a container for web links. frame_id is a 4 character string, url is a binary string.
This subclass of ID3v24_W___Frame contains an additional description binary string field to hold user-defined web link data.
This ID3v24_Frame-compatible object is for holding a potentially large block of comment data. encoding is the same as in text frames:
| 0 | Latin-1 |
| 1 | UTF-16 |
| 2 | UTF-16BE |
| 3 | UTF-8 |
language is a 3 character string, such as "eng" for English. short_description is a C_string object. data is a binary string.
Given a 4 byte "COMM" frame ID and Unicode string, returns a new ID3v23_COMM_Frame object.
This is a subclass of audiotools.Image, in addition to being a ID3v24_Frame-compatible object. mime_type is a C_string. picture_type is an integer representing one of the following:
| 0 | Other |
| 1 | 32x32 pixels ‘file icon’ (PNG only) |
| 2 | Other file icon |
| 3 | Cover (front) |
| 4 | Cover (back) |
| 5 | Leaflet page |
| 6 | Media (e.g. label side of CD) |
| 7 | Lead artist / Lead performer / Soloist |
| 8 | Artist / Performer |
| 9 | Conductor |
| 10 | Band / Orchestra |
| 11 | Composer |
| 12 | Lyricist / Text writer |
| 13 | Recording Location |
| 14 | During recording |
| 15 | During performance |
| 16 | Movie / Video screen capture |
| 17 | A bright colored fish |
| 18 | Illustration |
| 19 | Band / Artist logotype |
| 20 | Publisher / Studio logotype |
description is a C_string. data is a string of binary image data.
Returns the picture_type as a plain string.
Given an audiotools.Image object, returns a new ID3v24_APIC_Frame object.
Often, MP3 files are tagged with both an ID3v2 comment and an ID3v1 comment for maximum compatibility. This class encapsulates both comments into a single class.
id3v2_comment is an ID3v22Comment, ID3v23Comment or ID3v24Comment. id3v1_comment is an ID3v1Comment. When getting audiotools.MetaData attributes, the ID3v2 comment is used by default. Set attributes are propagated to both. For example:
>>> tag = ID3CommentPair(ID3v23Comment([ID3v23_T___Frame('TIT2', 0, 'Title 1')]),
... ID3v1Comment(u'Title 2',u'',u'',u'',u'',1, 0))
>>> tag.track_name
u'Title 1'
>>> tag.track_name = u'New Track Title'
>>> unicode(tag.id3v2['TIT2'][0])
u'New Track Title'
>>> tag.id3v1.track_name
u'New Track Title'
The embedded ID3v22Comment, ID3v23Comment or ID3v24Comment
The embedded ID3v1Comment
This is the metadata format used by QuickTime-compatible formats such as M4A and Apple Lossless. version and flags are integers (typically 0) and leaf_atoms is a list of atom objects, one of which should be an ilst tree atom. In addition to being a audiotools.MetaData subclass, this is also a M4A_Tree_Atom subclass with several methods specific for metadata. As an example:
>>> tag = M4A_META_Atom(0, 0,
... [M4A_Tree_Atom('ilst',
... [M4A_ILST_Leaf_Atom('\xa9nam',
... [M4A_ILST_Unicode_Data_Atom(0, 1, "Track Name")])])])
>>> tag.track_name
u'Track Name'
>>> tag['ilst']['\xa9nam']
... M4A_ILST_Leaf_Atom('\xa9nam', [M4A_ILST_Unicode_Data_Atom(0, 1, 'Track Name')])
>>> tag['ilst'].replace_child(M4A_ILST_Leaf_Atom('\xa9nam',
... [M4A_ILST_Unicode_Data_Atom(0, 1, 'New Track Name')])
>>> tag.track_name
u'New Track Name'
Fields are mapped between M4AMetaData, audiotools.MetaData and iTunes as follows:
| M4AMetaData | MetaData | iTunes |
| "\xA9nam" | track_name | Name |
| "\xA9ART" | artist_name | Artist |
| "\xA9day" | year | Year |
| "trkn" | track_number/track_total | Track Number |
| "disk" | album_number/album_total | Album Number |
| "\xA9alb" | album_name | Album |
| "\xA9wrt" | composer_name | Composer |
| "\xA9cmt" | comment | Comment |
| "cprt" | copyright |
Note that several of the 4 character keys are prefixed by the non-ASCII byte 0xA9.
Returns True if the atom has an ilst child atom.
Returns the first ilst child atom, or None if no ilst atom is present.
Appends a new, empty ilst atom after the first hdlr atom, if any.
Returns atom data as a human-readable Unicode string.
Given a 4 byte atom name, size of the entire atom in bytes, a audiotools.bitstream.BitstreamReader, and a dict of atom name strings -> atom classes, returns a new M4A_META_Atom object.
When parsing sub atoms, any atom name in the parsers dict is handled recursively via its value’s parse classmethod. If the atom name is not present, the atom is treated as a generic M4A_Leaf_Atom.
Writes the atom’s contents to the given audiotools.bitstream.BitstreamWriter recursively via its sub-atoms’ build methods. This does not include the atom’s 64-bit size / name header.
Returns the size of the atom data in bytes, not including its 64-bit size / name header.
name is a 4 byte atom name string. data is a string of raw atom data.
Returns a duplicate copy of the atom.
Returns atom data as a human-readable Unicode string.
Given a 4 byte atom name, size of the entire atom in bytes, a audiotools.bitstream.BitstreamReader and an unused dict of atom name strings -> atom classes, returns a new M4A_Leaf_Atom object.
Writes the atom’s contents to the given audiotools.bitstream.BitstreamWriter. This does not include the atom’s 64-bit size / name header.
Returns the size of the atom data in bytes, not including its 64-bit size / name header.
name is a 4 byte atom name string. leaf_atoms is a list of atom-compatible objects, typically M4A_Leaf_Atom, M4A_Tree_Atom or subclasses of either.
Returns a duplicate copy of the atom.
Returns atom data as a human-readable Unicode string.
Given a 4 byte atom name, size of the entire atom in bytes, a audiotools.bitstream.BitstreamReader, and a dict of atom name strings -> atom classes, returns a new M4A_META_Atom object.
When parsing sub atoms, any atom name in the parsers dict is handled recursively via its value’s parse classmethod. If the atom name is not present, the atom is treated as a generic M4A_Leaf_Atom.
Writes the atom’s contents to the given audiotools.bitstream.BitstreamWriter recursively via its sub-atoms’ build methods. This does not include the atom’s 64-bit size / name header.
Returns the size of the atom data in bytes, not including its 64-bit size / name header.
Given a 4 byte atom name string, returns the first instance of that child atom. Raises KeyError if the child is not found.
Given a 4 byte atom name string, returns True if that child atom is present.
Appends an atom-compatible object, to this atom’s list of children.
Given a 4 byte atom name string, removes the first instance of that child, if any.
Replaces the first child atom with the same name with the given atom-compatible object.
Given a list of 4 byte atom name strings, recursively searches M4A_Tree_Atom-compatible sub-children and returns the byte offset of the final child atom. Raises KeyError if the child atom cannot be found.
This atom is a subclass of M4A_Tree_Atom specialized for holding M4A metadata fields and mapping them to Python values.
name is a 4 byte atom name string. leaf_atoms is a list of atom-compatible objects,
Returns the Unicode value of this leaf’s first data child atom.
>>> nam = M4A_ILST_Leaf_Atom("\xa9nam",
... [M4A_ILST_Unicode_Data_Atom(0, 1, "Track Name")])
>>> unicode(nam)
u"Track Name"
Returns the integer value of this leaf’s first data child atom.
>>> trkn = M4A_ILST_Leaf_Atom("trkn",
... [M4A_ILST_TRKN_Data_Atom(1, 2)])
>>> int(trkn)
1
Returns the total integer value of this leaf’s first data child atom.
>>> trkn = M4A_ILST_Leaf_Atom("trkn",
... [M4A_ILST_TRKN_Data_Atom(1, 2)])
>>> trkn.total()
2
This atom is a subclass of M4A_Leaf_Atom specialized for holding Unicode data.
type is an integer (typically 0), flags is an integer (typically 1), data is a binary string of UTF-8-encoded data. The atom’s name field is always "data".
Returns the Unicode value of this atom’s data.
>>> nam = M4A_ILST_Unicode_Data_Atom(0, 1, "Track Name")
>>> unicode(nam)
u"Track Name"
This atom is a subclass of M4A_Leaf_Atom specialized for holding track number data.
track_number and track_total are both integers. Its name field is always "data".
Returns this atom’s track_number value.
>>> trkn = M4A_ILST_TRKN_Data_Atom(1, 2)
>>> int(trkn)
1
Returns this atom’s track_total value.
>>> trkn = M4A_ILST_TRKN_Data_Atom(1, 2)
>>> trkn.total()
2
This atom is a subclass of M4A_Leaf_Atom specialized for holding disc number data.
disc_number and disc_total are both integers. Its name field is always "data".
Returns this atom’s disc_number value.
>>> disk = M4A_ILST_DISK_Data_Atom(3, 4)
>>> int(disk)
3
Returns this atom’s disc_total value.
>>> disk = M4A_ILST_DISK_Data_Atom(3, 4)
>>> disk.total()
4
This atom is a subclass of M4A_Leaf_Atom and of audiotools.Image.
version is an integer (typically 0). flags is an integer (typically 0). image_data is a binary string of cover art data. Its name field is always "data".
This atom parses its raw image data to populate its audiotools.Image-specific methods and fields.
This is a VorbisComment tag used by FLAC, Ogg FLAC, Ogg Vorbis, Ogg Speex and other formats in the Ogg family. comment_strings is a list of Unicode strings. vendor_string is a Unicode string. Once initialized, VorbisComment can be manipulated like a regular Python dict in addition to its standard audiotools.MetaData methods.
For example:
>>> tag = VorbisComment([u'TITLE=Track Title'], u'Vendor String')
>>> tag.track_name
u'Track Title'
>>> tag[u'TITLE']
[u'New Title']
>>> tag[u'TITLE'] = [u'New Title']
>>> tag.track_name
u'New Title'
Fields are mapped between VorbisComment and audiotools.MetaData as follows:
| VorbisComment | Metadata |
| TITLE | track_name |
| TRACKNUMBER | track_number |
| TRACKTOTAL | track_total |
| DISCNUMBER | album_number |
| DISCTOTAL | album_total |
| ALBUM | album_name |
| ARTIST | artist_name |
| PERFORMER | performer_name |
| COMPOSER | composer_name |
| CONDUCTOR | conductor_name |
| SOURCE MEDIUM | media |
| ISRC | ISRC |
| CATALOG | catalog |
| COPYRIGHT | copyright |
| PUBLISHER | publisher |
| DATE | year |
| COMMENT | comment |
Note that if the same key is used multiple times, the metadata attribute only indicates the first one:
>>> tag = VorbisComment([u"TITLE=Title1", u"TITLE=Title2"], u"Vendor String")
>>> tag.track_name
u'Title1'
OpusTags is a subclass of VorbisComment which supports the same field/metadata mapping.