eyed3.utils package


eyed3.utils.art module

eyed3.utils.art.FRONT_COVER = 'FRONT_COVER'

Album front cover.

eyed3.utils.art.BACK_COVER = 'BACK_COVER'

Album back cover.

eyed3.utils.art.MISC_COVER = 'MISC_COVER'

Other part of the album cover; liner notes, gate-fold, etc.

Artist/band logo.

eyed3.utils.art.ARTIST = 'ARTIST'

Artist/band images.

eyed3.utils.art.LIVE = 'LIVE'

Artist/band images.

eyed3.utils.art.FILENAMES = {'ARTIST': ['artist*'], 'BACK_COVER': ['cover-back', 'back', 'cover-back_*'], 'LIVE': ['live*'], 'LOGO': ['logo*'], 'FRONT_COVER': ['cover-front', 'cover-alternate*', 'cover', 'folder', 'front', 'cover-front_*', 'flier'], 'MISC_COVER': ['cover-insert*', 'cover-liner*', 'cover-disc', 'cover-media*']}

A mapping of art types to lists of filename patterns (excluding file extension): type -> [file_pattern, ..].

eyed3.utils.art.TO_ID3_ART_TYPES = {'ARTIST': [7, 8, 10], 'BACK_COVER': [4], 'LIVE': [15, 14], 'LOGO': [19], 'FRONT_COVER': [3, 0, 1, 5], 'MISC_COVER': [6]}

A mapping of art types to ID3 APIC (image) types: type -> [apic_type, ..]

eyed3.utils.art.FROM_ID3_ART_TYPES = {0: 'FRONT_COVER', 1: 'FRONT_COVER', 3: 'FRONT_COVER', 4: 'BACK_COVER', 5: 'FRONT_COVER', 6: 'MISC_COVER', 7: 'ARTIST', 8: 'ARTIST', 10: 'ARTIST', 14: 'LIVE', 15: 'LIVE', 19: 'LOGO'}

A mapping of ID3 art types to eyeD3 art types; the opposite of TO_ID3_ART_TYPES.


Compares filename (case insensitive) with lists of common art file names and returns the type of art that was matched, or None if no types were matched.

eyed3.utils.art.getArtFromTag(tag, type_=None)[source]

Returns a list of eyed3.id3.frames.ImageFrame objects matching type_, all if type_ is None, or empty if tag does not contain art.

eyed3.utils.binfuncs module

eyed3.utils.binfuncs.bytes2bin(bytes, sz=8)[source]

Accepts a string of bytes (chars) and returns an array of bits representing the bytes in big endian byte order. An optional max sz for each byte (default 8 bits/byte) which can be used to mask out higher bits.


Convert x, an array of “bits” (MSB first), to it’s decimal value.

eyed3.utils.binfuncs.bytes2dec(bytes, sz=8)[source]
eyed3.utils.binfuncs.dec2bin(n, p=1)[source]

Convert a decimal value n to an array of bits (MSB first). Optionally, pad the overall size to p bits.

eyed3.utils.binfuncs.dec2bytes(n, p=1)[source]

Convert x, a list of bits (MSB first), to a synch safe list of bits. (section 6.2 of the ID3 2.4 spec).

eyed3.utils.cli module

This module is deprecated. Use eyed3.utils and eyed3.utils.console instead.

eyed3.utils.cli.getColor(color_code, fp=<open file '<stdout>', mode 'w'>)[source]
eyed3.utils.cli.enableColorOutput(fp, state=True)[source]

eyed3.utils.console module

class eyed3.utils.console.AnsiCodes(codes)[source]

Bases: object

static init(enabled)[source]
class eyed3.utils.console.AnsiFore[source]
GREY = 30
RED = 31
GREEN = 32
BLUE = 34
CYAN = 36
WHITE = 37
RESET = 39
class eyed3.utils.console.AnsiBack[source]
GREY = 40
RED = 41
GREEN = 42
BLUE = 44
CYAN = 46
WHITE = 47
RESET = 49
class eyed3.utils.console.AnsiStyle[source]
DIM = 2
class eyed3.utils.console.Spinner(msg, file=None, step=1, chars=None, use_unicode=True, print_done=True)[source]

Bases: object

A class to display a spinner in the terminal.

It is designed to be used with the with statement:

with Spinner("Reticulating splines", "green") as s:
    for item in enumerate(items):
class eyed3.utils.console.ProgressBar(total_or_items, file=None)[source]

Bases: object

A class to display a progress bar in the terminal.

It is designed to be used either with the with statement:

with ProgressBar(len(items)) as bar:
    for item in enumerate(items):

or as a generator:

for item in ProgressBar(items):
total_or_items : int or sequence
If an int, the number of increments in the process being tracked. If a sequence, the items to iterate over.
file : writable file-like object, optional
The file to write the progress bar to. Defaults to sys.stdout. If file is not a tty (as determined by calling its isatty member, if any), the scrollbar will be completely silent.

Update the progress bar to the given value (out of the total given to the constructor).

classmethod map(function, items, multiprocess=False, file=None)[source]

Does a map operation while displaying a progress bar with percentage complete.

def work(i):

ProgressBar.map(work, range(50))
function : function
Function to call for each step
items : sequence
Sequence where each element is a tuple of arguments to pass to function.
multiprocess : bool, optional
If True, use the multiprocessing module to distribute each task to a different processor core.
file : writeable file-like object, optional
The file to write the progress bar to. Defaults to sys.stdout. If file is not a tty (as determined by calling its isatty member, if any), the scrollbar will be completely silent.
eyed3.utils.console.boldText(s, fp=<open file '<stdout>', mode 'w'>, c=None)[source]

eyed3.utils.log module

class eyed3.utils.log.Logger(name)[source]

Bases: logging.Logger

Base class for all loggers

verbose(msg, *args, **kwargs)[source]

Log  msg at ‘verbose’ level, debug < verbose < info


initialize the default logger with console output

eyed3.utils.prompt module

eyed3.utils.prompt.DISABLE_PROMPT = None

Whenever a prompt occurs and this value is not None it can be exit to call sys.exit (see EXIT_STATUS) or raise to throw a RunttimeError, which can be caught if desired.

exception eyed3.utils.prompt.PromptExit[source]

Bases: exceptions.RuntimeError

Raised when DISABLE_PROMPT is ‘raise’ and prompt is called.

eyed3.utils.prompt.prompt(msg, default=None, required=True, type_=<type 'unicode'>, validate=None, choices=None)[source]

Prompt user for imput, the prequest is in msg. If default is not None it will be displayed as the default and returned if not input is entered. The value None is only returned if required is False. The response is passed to type_ for conversion (default is unicode) before being returned. An optional list of valid responses can be provided in ``choices`.

Module contents

eyed3.utils.guessMimetype(filename, with_encoding=False)[source]

Return the mime-type for filename. If with_encoding is True the encoding is included and a 2-tuple is returned, (mine, enc).

eyed3.utils.walk(handler, path, excludes=None, fs_encoding='UTF-8')[source]

A wrapper around os.walk which handles exclusion patterns and unicode conversion.

class eyed3.utils.FileHandler[source]

Bases: object

A handler interface for eyed3.utils.walk() callbacks.


Called for each file walked. The file f is the full path and the return value is ignored. If the walk should abort the method should raise a StopIteration exception.

handleDirectory(d, files)[source]

Called for each directory d after handleFile has been called for each file in files. StopIteration may be raised to halt iteration.


Called when there are no more files to handle.


Function decorator to enforce unicode argument types. None is a valid argument value, in all cases, regardless of not being unicode. *args Positional arguments may be numeric argument index values (requireUnicode(1, 3) - requires argument 1 and 3 are unicode) or keyword argument names (requireUnicode(“title”)) or a combination thereof.

eyed3.utils.formatTime(seconds, total=None, short=False)[source]

Format seconds (number of seconds) as a string representation. When short is False (the default) the format is:


Otherwise, the format is exacly 6 characters long and of the form:

1w 3d 2d 4h 1h 5m 1m 4s 15s

If total is not None it will also be formatted and appended to the result seperated by ‘ / ‘.

eyed3.utils.KB_BYTES = 1024

Number of bytes per KB (2^10)

eyed3.utils.MB_BYTES = 1048576

Number of bytes per MB (2^20)

eyed3.utils.GB_BYTES = 1073741824

Number of bytes per GB (2^30)

eyed3.utils.KB_UNIT = 'KB'

Kilobytes abbreviation

eyed3.utils.MB_UNIT = 'MB'

Megabytes abbreviation

eyed3.utils.GB_UNIT = 'GB'

Gigabytes abbreviation

eyed3.utils.formatSize(size, short=False)[source]

Format size (nuber of bytes) into string format doing KB, MB, or GB conversion where necessary.

When short is False (the default) the format is smallest unit of bytes and largest gigabytes; ‘234 GB’. The short version is 2-4 characters long and of the form

256b 64k 1.1G

Format a timedelta object td into a string.

eyed3.utils.chunkCopy(src_fp, dest_fp, chunk_sz=524288)[source]

Copy src_fp to dest_fp in chunk_sz byte increments.

class eyed3.utils.ArgumentParser(*args, **kwargs)[source]

Bases: argparse.ArgumentParser

Subclass of argparse.ArgumentParser that adds version and log level options.

class eyed3.utils.LoggingAction(*args, **kwargs)[source]

Bases: argparse._AppendAction

eyed3.utils.datePicker(thing, prefer_recording_date=False)[source]

This function returns a date of some sort, amongst all the possible dates (members called release_date, original_release_date, and recording_date of type eyed3.core.Date).

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.

eyed3.utils.makeUniqueFileName(file_path, uniq=u'')[source]

The file_path is the desired file name, and it is returned if the file does not exist. In the case that it already exists the path is adjusted to be unique. First, the uniq string is added, and then a couter is used to find a unique name.