eyed3.id3 package

Submodules

eyed3.id3.apple module

Here lies Apple frames, all of which are non-standard. All of these would have been standard user text frames by anyone not being a bastard, on purpose.

class eyed3.id3.apple.PCST(_=None)

Bases: Frame

Indicates a podcast. The 4 bytes of data is undefined, and is typically all 0.

render()

class eyed3.id3.apple.TKWD(_=None, **kwargs)

Bases: TextFrame

Podcast keywords.

class eyed3.id3.apple.TDES(_=None, **kwargs)

Bases: TextFrame

Podcast description. One encoding byte followed by text per encoding.

class eyed3.id3.apple.TGID(_=None, **kwargs)

Bases: TextFrame

Podcast URL of the audio file. This should be a W frame!

class eyed3.id3.apple.WFED(_=None, url='')

Bases: TextFrame

Another podcast URL, the feed URL it is said.

class eyed3.id3.apple.GRP1(_=None, **kwargs)

Bases: TextFrame

Apple grouping, could be a TIT1 conversion.

class eyed3.id3.apple.MVNM(_=None, **kwargs)

Bases: TextFrame

Movement name. An Apple extension for classical music.

class eyed3.id3.apple.MVIN(_=None, **kwargs)

Bases: TextFrame

Movement index (e.g. “3/9”). An Apple extension for classical music.

eyed3.id3.frames module

exception eyed3.id3.frames.FrameException(*args)

Bases: Error

class eyed3.id3.frames.Frame(**kwargs)

Bases: object

property header

parse(**kwargs)

render()

static decompress(data)

static compress(data)

static decrypt(data)

static encrypt(data)

property text_delim

property encoding

property strict_rendering

property unknown

class eyed3.id3.frames.TextFrame(**kwargs)

Bases: Frame

Text frames. Data string format: encoding (one byte) + text

property text

parse(data, frame_header)

render()

static isValidFrameId(fid: bytes) → bool

class eyed3.id3.frames.UserTextFrame(**kwargs)

Bases: TextFrame

property description

parse(data, frame_header)

Data string format: encoding (one byte) + description + b”" + text

render()

class eyed3.id3.frames.DateFrame(id, date='')

Bases: TextFrame

parse(data, frame_header)

property date

class eyed3.id3.frames.UrlFrame(id, url='')

Bases: Frame

property url

parse(data, frame_header)

render()

class eyed3.id3.frames.UserUrlFrame(**kwargs)

Bases: UrlFrame

Data string format: encoding (one byte) + description + b”" + url (iso-8859-1)

property description

parse(data, frame_header)

render()

class eyed3.id3.frames.UnknownFrame(id)

Bases: Frame

Unknown Frame.

class eyed3.id3.frames.ImageFrame(**kwargs)

Bases: Frame

OTHER = 0

ICON = 1

OTHER_ICON = 2

FRONT_COVER = 3

BACK_COVER = 4

LEAFLET = 5

MEDIA = 6

LEAD_ARTIST = 7

ARTIST = 8

CONDUCTOR = 9

BAND = 10

COMPOSER = 11

LYRICIST = 12

RECORDING_LOCATION = 13

DURING_RECORDING = 14

DURING_PERFORMANCE = 15

VIDEO = 16

BRIGHT_COLORED_FISH = 17

ILLUSTRATION = 18

BAND_LOGO = 19

PUBLISHER_LOGO = 20

MIN_TYPE = 0

MAX_TYPE = 20

URL_MIME_TYPE = b'-->'

URL_MIME_TYPE_STR = '-->'

URL_MIME_TYPE_VALUES = (b'-->', '-->')

property description

property mime_type

property picture_type

parse(data, frame_header)

render()

static picTypeToString(t)

static stringToPicType(s)

makeFileName(name=None)

class eyed3.id3.frames.ObjectFrame(**kwargs)

Bases: Frame

property description

property mime_type

property filename

parse(data, frame_header)

Parse the frame from data bytes using details from frame_header.

Data string format: <Header for ‘General encapsulated object’, ID: “GEOB”> Text encoding $xx MIME type <text string> $00 Filename <text string according to encoding> $00 (00) Content description <text string according to encoding> $00 (00) Encapsulated object <binary data>

render()

class eyed3.id3.frames.PrivateFrame(id=b'PRIV', owner_id=b'', owner_data=b'')

Bases: Frame

PRIV

owner_id: bytes

owner_data: bytes

parse(data, frame_header)

render()

class eyed3.id3.frames.MusicCDIdFrame(id=b'MCDI', toc=b'')

Bases: Frame

property toc

parse(data, frame_header)

class eyed3.id3.frames.PlayCountFrame(id=b'PCNT', count=0)

Bases: Frame

parse(data, frame_header)

render()

class eyed3.id3.frames.PopularityFrame(id=b'POPM', email=b'', rating=0, count=0)

Bases: Frame

Frame type for ‘POPM’ frames; popularity. Frame format: <Header for ‘Popularimeter’, ID: “POPM”> Email to user <text string> $00 Rating $xx Counter $xx xx xx xx (xx …)

property rating

property email

property count

parse(data, frame_header)

render()

class eyed3.id3.frames.UniqueFileIDFrame(id=b'UFID', owner_id=b'', uniq_id=b'')

Bases: Frame

property owner_id

property uniq_id

parse(data, frame_header)

Data format Owner identifier <text string> $00 Identifier up to 64 bytes binary data>

render()

class eyed3.id3.frames.LanguageCodeMixin

Bases: object

property lang

class eyed3.id3.frames.DescriptionLangTextFrame(**kwargs)

Bases: Frame, LanguageCodeMixin

property description

property text

parse(data, frame_header)

render()

class eyed3.id3.frames.CommentFrame(id=b'COMM', description='', lang=b'eng', text='')

Bases: DescriptionLangTextFrame

class eyed3.id3.frames.LyricsFrame(id=b'USLT', description='', lang=b'eng', text='')

Bases: DescriptionLangTextFrame

class eyed3.id3.frames.TermsOfUseFrame(**kwargs)

Bases: Frame, LanguageCodeMixin

property text

parse(data, frame_header)

render()

class eyed3.id3.frames.TocFrame(**kwargs)

Bases: Frame

Table of content frame. There may be more than one, but only one may have the top-level flag set.

Data format: Element ID: <string>TOC flags: %000000ab Entry count: %xx Child elem IDs: <string>(… num entry count) Description: TIT2 frame (optional)

TOP_LEVEL_FLAG_BIT = 6

ORDERED_FLAG_BIT = 7

parse(data, frame_header)

render()

class eyed3.id3.frames.RelVolAdjFrameV24(fid=b'RVA2', identifier=None, channel_type=None, adjustment=None, peak=None)

Bases: Frame

CHANNEL_TYPE_OTHER = 0

CHANNEL_TYPE_MASTER = 1

CHANNEL_TYPE_FRONT_RIGHT = 2

CHANNEL_TYPE_FRONT_LEFT = 3

CHANNEL_TYPE_BACK_RIGHT = 4

CHANNEL_TYPE_BACK_LEFT = 5

CHANNEL_TYPE_FRONT_CENTER = 6

CHANNEL_TYPE_BACK_CENTER = 7

CHANNEL_TYPE_BASS = 8

property identifier

property channel_type

property adjustment

property peak

parse(data, frame_header)

render()

class eyed3.id3.frames.RelVolAdjFrameV23(fid=b'RVAD')

Bases: Frame

FRONT_CHANNEL_RIGHT_BIT = 0

FRONT_CHANNEL_LEFT_BIT = 1

BACK_CHANNEL_RIGHT_BIT = 2

BACK_CHANNEL_LEFT_BIT = 3

FRONT_CENTER_CHANNEL_BIT = 4

BASS_CHANNEL_BIT = 5

CHANNEL_DEFN = [('front_right', 0), ('front_left', 1), ('front_right_peak', None), ('front_left_peak', None), ('back_right', 2), ('back_left', 3), ('back_right_peak', None), ('back_left_peak', None), ('front_center', 4), ('front_center_peak', None), ('bass', 5), ('bass_peak', None)]

class VolumeAdjustments(master: int = 0, master_peak: int = 0, front_right: int = 0, front_left: int = 0, front_right_peak: int = 0, front_left_peak: int = 0, back_right: int = 0, back_left: int = 0, back_right_peak: int = 0, back_left_peak: int = 0, front_center: int = 0, front_center_peak: int = 0, back_center: int = 0, back_center_peak: int = 0, bass: int = 0, bass_peak: int = 0, other: int = 0, other_peak: int = 0)

Bases: object

master: int = 0

master_peak: int = 0

front_right: int = 0

front_left: int = 0

front_right_peak: int = 0

front_left_peak: int = 0

back_right: int = 0

back_left: int = 0

back_right_peak: int = 0

back_left_peak: int = 0

front_center: int = 0

front_center_peak: int = 0

back_center: int = 0

back_center_peak: int = 0

bass: int = 0

bass_peak: int = 0

other: int = 0

other_peak: int = 0

property has_master_channel: bool

property has_front_channel: bool

property has_back_channel: bool

property has_front_center_channel: bool

property has_back_center_channel: bool

property has_bass_channel: bool

property has_other_channel: bool

boundsCheck()

setChannelAdj(chan_type, value)

setChannelPeak(chan_type, value)

toV24() → list

Return a list of RVA2 frames

parse(data, frame_header)

render()

class eyed3.id3.frames.StartEndTuple(start, end)

Bases: tuple

A 2-tuple, with names ‘start’ and ‘end’.

end

Alias for field number 1

start

Alias for field number 0

class eyed3.id3.frames.ChapterFrame(id=b'CHAP', element_id=None, times=None, offsets=None, sub_frames=None)

Bases: Frame

Frame type for chapter/section of the audio file. <ID3v2.3 or ID3v2.4 frame header, ID: “CHAP”> (10 bytes) Element ID <text string> $00 Start time $xx xx xx xx End time $xx xx xx xx Start offset $xx xx xx xx End offset $xx xx xx xx <Optional embedded sub-frames>

NO_OFFSET = 4294967295

No offset value, aka ‘0xff0xff0xff0xff’

parse(data, frame_header)

render()

property title

property subtitle

property user_url

class eyed3.id3.frames.FrameSet

Bases: dict

parse(f, tag_header, extended_header)

Read frames starting from the current read position of the file object. Returns the amount of padding which occurs after the tag, but before the audio content. A return value of 0 does not mean error.

property unknown_frame_ids

getAllFrames()

Return all the frames in the set as a list. The list is sorted in an arbitrary but consistent order.

setTextFrame(**kwargs)

eyed3.id3.frames.deunsyncData(data)

eyed3.id3.frames.createFrame(tag_header, frame_header, data)

eyed3.id3.frames.decodeUnicode(bites, encoding)

eyed3.id3.frames.splitUnicode(data, encoding)

eyed3.id3.frames.id3EncodingToString(encoding)

eyed3.id3.frames.stringToEncoding(s)

eyed3.id3.frames.map2_2FrameId(orig_id)

eyed3.id3.headers module

class eyed3.id3.headers.TagHeader(version=(2, 4, 0))

Bases: object

SIZE = 10

clear()

property version

property major_version

property minor_version

property rev_version

parse(f)

Parse an ID3 v2 header starting at the current position of f.

If a header is parsed True is returned, otherwise False. If a header is found but malformed an eyed3.id3.tag.TagException is thrown.

render(tag_len=None)

class eyed3.id3.headers.ExtendedTagHeader

Bases: object

RESTRICT_TAG_SZ_LARGE = 0

RESTRICT_TAG_SZ_MED = 1

RESTRICT_TAG_SZ_SMALL = 2

RESTRICT_TAG_SZ_TINY = 3

RESTRICT_TEXT_ENC_NONE = 0

RESTRICT_TEXT_ENC_UTF8 = 1

RESTRICT_TEXT_LEN_NONE = 0

RESTRICT_TEXT_LEN_1024 = 1

RESTRICT_TEXT_LEN_128 = 2

RESTRICT_TEXT_LEN_30 = 3

RESTRICT_IMG_ENC_NONE = 0

RESTRICT_IMG_ENC_PNG_JPG = 1

RESTRICT_IMG_SZ_NONE = 0

RESTRICT_IMG_SZ_256 = 1

RESTRICT_IMG_SZ_64 = 2

RESTRICT_IMG_SZ_64_EXACT = 3

property update_bit

property crc_bit

property crc

property restrictions_bit

property tag_size_restriction

property tag_size_restriction_description

property text_enc_restriction

property text_enc_restriction_description

property text_length_restriction

property text_length_restriction_description

property image_enc_restriction

property image_enc_restriction_description

property image_size_restriction

property image_size_restriction_description

render(version, frame_data, padding=0)

parse(fp, version)

Parse an ID3 v2 extended header starting at the current position of fp and per the format defined by version. This method should only be called when the presence of an extended header is known since it moves the file position. If a header is found but malformed an eyed3.id3.tag.TagException is thrown. The return value is None.

class eyed3.id3.headers.FrameHeader(**kwargs)

Bases: object

A header for each and every ID3 frame in a tag.

TAG_ALTER = None

FILE_ALTER = None

READ_ONLY = None

COMPRESSED = None

ENCRYPTED = None

GROUPED = None

UNSYNC = None

DATA_LEN = None

copyFlags(rhs)

property major_version

property minor_version

property version

property tag_alter

property file_alter

property read_only

property compressed

property encrypted

property grouped

property unsync

property data_length_indicator

render(data_size)

static parse(f, version)

eyed3.id3.tag module

exception eyed3.id3.tag.TagException(*args)

Bases: Error

class eyed3.id3.tag.Tag(version=(2, 4, 0), **kwargs)

Bases: Tag

clear(*, version=(2, 4, 0))

Reset all tag data.

parse(fileobj, version=(3, None, None))

property version

isV1()

Test ID3 major version for v1.x

isV2()

Test ID3 major version for v2.x

setTextFrame(**kwargs)

getTextFrame(fid: bytes)

property composer

property comments

property bpm

property play_count

property publisher

property cd_id

property unknown_frame_ids: set

property images

property encoding_date

property best_release_date

This method tries its best to return a date of some sort, amongst all the possible date frames. The order of preference for a release date is 1) date of original release 2) date of this versions release 3) the recording date. Or None is returned.

getBestDate(prefer_recording_date=False)

This method returns a date of some sort, amongst all the possible date frames. The order of preference is:

1. date of original release

2. date of this versions release

3. the recording date.

Unless prefer_recording_date is True in which case the order is 3, 1, 2.

None will be returned if no dates are available.

property release_date

The date the audio was released. This is NOT the original date the work was released, instead it is more like the pressing or version of the release. Original release date is usually what is intended but many programs use this frame and/or don’t distinguish between the two.

NOTE: ID3v2.3 only has original release date, so setting release_date is the same as original_release_value; they both set TORY.

property original_release_date

The date the work was originally released.

NOTE: ID3v2.3 only stores year. If the Date object is more precise it is store in XDOR, and XDOR is preferred when acessing. The year-only date is stored in the standard TORY frame as well.

property recording_date

The date of the recording. Many applications use this for release date regardless of the fact that this value is rarely known, and release dates are more correct.

property tagging_date

property lyrics

property disc_num

property objects

property privates

property popularities

property genre

property non_std_genre

property user_text_frames

property commercial_url

property copyright_url

property audio_file_url

property audio_source_url

property artist_url

property internet_radio_url

property payment_url

property publisher_url

property user_url_frames

property unique_file_ids

property terms_of_use

property copyright

property encoded_by

save(filename=None, version=None, encoding=None, backup=False, preserve_file_time=False, max_padding=None)

Save the tag. If filename is not give the value from the file_info member is used, or a TagException is raised. The version argument can be used to select an ID3 version other than the version read. Select text encoding with ``encoding or use the existing (or default) encoding. If backup is True the original file is preserved; likewise if preserve_file_time is True the file´s modification/access times are not updated.

static remove(filename, version=(3, None, None), preserve_file_time=False)

property chapters

property table_of_contents

property album_type

property artist_origin

Returns None or a ArtistOrigin dataclass: (city, state, country) Any may be None.

frameiter(fids=None)

A iterator for tag frames. If fids is passed it must be a list of frame IDs to filter and return.

property original_artist

class eyed3.id3.tag.FileInfo(file_name, tagsz=0, tpadd=0)

Bases: object

This class is for storing information about a parsed file. It contains info such as the filename, original tag size, and amount of padding; all of which can make rewriting faster.

initStatTimes()

touch(times)

times is a 2-tuple of (atime, mtime).

class eyed3.id3.tag.AccessorBase(fid, fs, match_func=None)

Bases: object

get(*args, **kwargs)

remove(*args, **kwargs)

Returns the removed item or None if not found.

class eyed3.id3.tag.DltAccessor(FrameClass, fid, fs)

Bases: AccessorBase

Access matching tag frames by “description” and/or “lang” values.

set(**kwargs)

remove(**kwargs)

Returns the removed item or None if not found.

get(**kwargs)

class eyed3.id3.tag.CommentsAccessor(fs)

Bases: DltAccessor

class eyed3.id3.tag.LyricsAccessor(fs)

Bases: DltAccessor

class eyed3.id3.tag.ImagesAccessor(fs)

Bases: AccessorBase

set(**kwargs)

remove(**kwargs)

Returns the removed item or None if not found.

get(**kwargs)

class eyed3.id3.tag.ObjectsAccessor(fs)

Bases: AccessorBase

set(**kwargs)

remove(**kwargs)

Returns the removed item or None if not found.

get(**kwargs)

class eyed3.id3.tag.PrivatesAccessor(fs)

Bases: AccessorBase

set(data, owner_id)

remove(owner_id)

Returns the removed item or None if not found.

get(owner_id)

class eyed3.id3.tag.UserTextsAccessor(fs)

Bases: AccessorBase

set(**kwargs)

remove(**kwargs)

Returns the removed item or None if not found.

get(**kwargs)

class eyed3.id3.tag.UniqueFileIdAccessor(fs)

Bases: AccessorBase

set(data, owner_id)

remove(owner_id)

Returns the removed item or None if not found.

get(owner_id)

class eyed3.id3.tag.UserUrlsAccessor(fs)

Bases: AccessorBase

set(**kwargs)

remove(**kwargs)

Returns the removed item or None if not found.

get(**kwargs)

class eyed3.id3.tag.PopularitiesAccessor(fs)

Bases: AccessorBase

set(email, rating, play_count)

remove(email)

Returns the removed item or None if not found.

get(email)

class eyed3.id3.tag.ChaptersAccessor(fs)

Bases: AccessorBase

set(element_id, times, offsets=(None, None), sub_frames=None)

remove(element_id)

Returns the removed item or None if not found.

get(element_id)

class eyed3.id3.tag.TocAccessor(fs)

Bases: AccessorBase

set(**kwargs)

remove(element_id)

Returns the removed item or None if not found.

get(element_id)

class eyed3.id3.tag.TagTemplate(pattern, path_friendly='-', dotted_dates=False)

Bases: Template

pattern = re.compile('\n            \\$(?:\n              (?P<escaped>\\$)  |   # Escape sequence of two delimiters\n              (?P<named>[_a-z][_a-z0-9:]*)       |   # delimiter and a Python identifier\n              , re.IGNORECASE|re.VERBOSE)

idpattern = '[_a-z][_a-z0-9:]*'

substitute(tag, zeropad=True)

safe_substitute(tag, zeropad=True)

Module contents

eyed3.id3.isValidVersion(v, fully_qualified=False)

Check the tuple v against the list of valid ID3 version constants. If fully_qualified is True it is enforced that there are 3 components to the version in v. Returns True when valid and False otherwise.

eyed3.id3.normalizeVersion(v)

If version tuple v is of the non-specific type (v1 or v2, any, etc.) a fully qualified version is returned.

eyed3.id3.versionToString(v)

Conversion version tuple v to a string description.

exception eyed3.id3.GenreException(*args)

Bases: Error

Excpetion type for exceptions related to genres.

class eyed3.id3.Genre(name=None, id: int = None, genre_map=None)

Bases: object

A genre in terms of a name and and id. Only when name is a “standard” genre (as defined by ID3 v1) will id be a value other than None.

Constructor takes an optional name and ID. If id is provided the name, regardless of value, is set to the string the id maps to. Likewise, if name is passed and is a standard genre the id is set to the correct value. Any invalid id values cause a ValueError to be raised. Genre names that are not in the standard list are still accepted but the id value is set to None.

property id

The Genre’s id property. When setting the value is strictly enforced and if the value is not a valid genre code a ValueError is raised. Otherwise the id is set and the name property is updated to the code’s string name.

property name

The Genre’s name property. When setting the value the name is looked up in the standard genre map and if found the id ppropery is set to the numeric valud and the name is normalized to the sting found in the map. Non standard genres are set (with a warning log) and the id is set to None. It is valid to set the value to None.

static parse(g_str, id3_std=True)

Parses genre information from genre_str. The following formats are supported: 01, 2, 23, 125 - ID3 v1.x style. (01), (2), (129)Hardcore, (9)Metal, Indie - ID3v2 style with and without refinement. Raises GenreException when an invalid string is passed.

class eyed3.id3.GenreMap(*args)

Bases: dict

Classic genres defined around ID3 v1 but suitable anywhere. This class is used primarily as a way to map numeric genre values to a string name. Genre strings on the other hand are not required to exist in this list.

The optional *args are passed directly to the dict constructor.

GENRE_MIN = 0

GENRE_MAX = 191

ID3_GENRE_MIN = 0

ID3_GENRE_MAX = 79

WINAMP_GENRE_MIN = 80

WINAMP_GENRE_MAX = 191

GENRE_ID3V1_MAX = 255

get(key)

Return the value for key if key is in the dictionary, else default.

property ids

iter()

class eyed3.id3.TagFile(path, version=(3, None, None))

Bases: AudioFile

A shim class for dealing with files that contain only ID3 data, no audio.

Construct with a path and invoke _read. All other members are set to None.

initTag(version=(2, 4, 0))

Add a id3.Tag to the file (removing any existing tag if one exists).