eyed3.mp3 package


eyed3.mp3.headers module


Determine if header (an integer, 4 bytes compared) is a valid mp3 frame header.

eyed3.mp3.headers.findHeader(fp, start_pos=0)[source]

Locate the first mp3 header in file stream fp starting a offset start_pos (defaults to 0). Returned is a 3-tuple containing the offset where the header was found, the header as an integer, and the header as 4 bytes. If no header is found header_int will equal 0.

eyed3.mp3.headers.timePerFrame(mp3_header, vbr)[source]

Computes the number of seconds per mp3 frame. It can be used to compute overall playtime and bitrate. The mp3 layer and sample rate from mp3_header are used to compute the number of seconds (fractional float point value) per mp3 frame. Be sure to set vbr True when dealing with VBR, otherwise playtimes may be incorrect.


Deprecated since version 0.9a2: This will be removed in 1.0. Use timePerFrame instead

class eyed3.mp3.headers.Mp3Header(header_data=None)[source]

Bases: object

Header container for MP3 frames.

class eyed3.mp3.headers.VbriHeader[source]

Bases: object

class eyed3.mp3.headers.XingHeader[source]

Bases: object

Header class for the Xing header extensions.

class eyed3.mp3.headers.LameHeader(frame)[source]

Bases: dict

Mp3 Info tag (AKA LAME Tag)

Lame (and some other encoders) write a tag containing various bits of info about the options used at encode time. If available, the following are parsed and stored in the LameHeader dict:

encoder_version: short encoder version [str] tag_revision: revision number of the tag [int] vbr_method: VBR method used for encoding [str] lowpass_filter: lowpass filter frequency in Hz [int] replaygain: if available, radio and audiofile gain (see below) [dict] encoding_flags: encoding flags used [list] nogap: location of gaps when –nogap was used [list] ath_type: ATH type [int] bitrate: bitrate and type (Constant, Target, Minimum) [tuple] encoder_delay: samples added at the start of the mp3 [int] encoder_padding: samples added at the end of the mp3 [int] noise_shaping: noise shaping method [int] stereo_mode: stereo mode used [str] unwise_settings: whether unwise settings were used [boolean] sample_freq: source sample frequency [str] mp3_gain: mp3 gain adjustment (rarely used) [float] preset: preset used [str] surround_info: surround information [str] music_length: length in bytes of original mp3 [int] music_crc: CRC-16 of the mp3 music data [int] infotag_crc: CRC-16 of the info tag [int]

Prior to ~3.90, Lame simply stored the encoder version in the first frame. If the infotag_crc is invalid, then we try to read this version string. A simple way to tell if the LAME Tag is complete is to check for the infotag_crc key.

Replay Gain data is only available since Lame version 3.94b. If set, the replaygain dict has the following structure:


peak_amplitude: peak signal amplitude [float] radio:

name: name of the gain adjustment [str] adjustment: gain adjustment [float] originator: originator of the gain adjustment [str]

audiofile: [same as radio]


Note that as of 3.95.1, Lame uses 89dB as a reference level instead of the 83dB that is specified in the Replay Gain spec. This is not automatically compensated for. You can do something like this if you want:


import eyeD3 af = eyeD3.mp3.Mp3AudioFile(‘/path/to/some.mp3’) lamever = af.lameTag[‘encoder_version’] name, ver = lamever[:4], lamever[4:] gain = af.lameTag[‘replaygain’][‘radio’][‘adjustment’] if name == ‘LAME’ and eyeD3.mp3.lamevercmp(ver, ‘3.95’) > 0:

gain -= 6


Radio and Audiofile Replay Gain are often referrered to as Track and Album gain, respectively. See http://replaygain.hydrogenaudio.org/ for futher details on Replay Gain.

See http://gabriel.mp3-tech.org/mp3infotag.html for the gory details of the LAME Tag.

Read the LAME info tag. frame should be the first frame of an mp3.

PRESETS = {0: 'Unknown', 410: 'V9', 420: 'V8', 430: 'V7', 440: 'V6', 450: 'V5', 460: 'V4', 470: 'V3', 480: 'V2', 490: 'V1', 500: 'V0', 1000: 'r3mix', 1001: 'standard', 1002: 'extreme', 1003: 'insane', 1004: 'standard/fast', 1005: 'extreme/fast', 1006: 'medium', 1007: 'medium/fast'}
REPLAYGAIN_NAME = {0: 'Not set', 1: 'Radio', 2: 'Audiofile'}
REPLAYGAIN_ORIGINATOR = {0: 'Not set', 1: 'Set by artist', 2: 'Set by user', 3: 'Set automatically', 100: 'Set by simple RMS average'}
SAMPLE_FREQUENCIES = {0: '<= 32 kHz', 1: '44.1 kHz', 2: '48 kHz', 3: '> 48 kHz'}
STEREO_MODES = {0: 'Mono', 1: 'Stereo', 2: 'Dual', 3: 'Joint', 4: 'Force', 5: 'Auto', 6: 'Intensity', 7: 'Undefined'}
SURROUND_INFO = {0: 'None', 1: 'DPL encoding', 2: 'DPL2 encoding', 3: 'Ambisonic encoding', 8: 'Reserved'}
VBR_METHODS = {0: 'Unknown', 1: 'Constant Bitrate', 2: 'Average Bitrate', 3: 'Variable Bitrate method1 (old/rh)', 4: 'Variable Bitrate method2 (mtrh)', 5: 'Variable Bitrate method3 (mt)', 6: 'Variable Bitrate method4', 8: 'Constant Bitrate (2 pass)', 9: 'Average Bitrate (2 pass)', 15: 'Reserved'}

Decode the LAME info tag.

eyed3.mp3.headers.lamevercmp(x, y)[source]

Compare LAME version strings.

alpha and beta versions are considered older. Versions with sub minor parts or end with ‘r’ are considered newer.

  • x – The first version to compare.

  • y – The second version to compare.


Return negative if x<y, zero if x==y, positive if x>y.

Module contents

exception eyed3.mp3.Mp3Exception(*args)[source]

Bases: eyed3.Error

Used to signal mp3-related errors.

class eyed3.mp3.Mp3AudioInfo(file_obj, start_offset, tag)[source]

Bases: eyed3.core.AudioInfo

property bit_rate_str
class eyed3.mp3.Mp3AudioFile(path, version=(3, None, None))[source]

Bases: eyed3.core.AudioFile

Audio file container for mp3 files.

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

initTag(version=(2, 4, 0))[source]

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

property tag

Returns a concrete implemenation of eyed3.core.Tag