MP3 File Interface

Note

This module will no longer be used in MusicDB. It may get removed in future.

What this module does is now done by MP3 Stream Interface.

This module provides a class to read mp3 files frame wise. Decoding is not part of it.

MP3File Class

class lib.stream.mp3file.MP3File(path)

This class allows frame wise reading of an mp3 file. This is done by the Frames() generator. Beside the mp3 frames the generator returns lots of information extracted from the mp3 Frame Header.

The class expects a valid mp3 file (MPEG Layer III) with an valid ID3 Tag (ID3v2.3.0 or ID3v2.4.0).

Parameters

path (str) – An absolute path to a valid mp3 file

Example

# ffmpeg -filter_complex aevalsrc=0 -acodec libmp3lame -ab 320k -t 1 silence.mp3

mp3file = MP3File("./silence.mp3")
for frame in mp3file.Frames():
    print("=== %5i / %5i ==="%(frame["count"], frame["total"]))
    print(frame["header"])

AnalyzeHeader(header)

This method analyzes a MP3 Frame Header and returns all information that are implicit included in these 4 bytes. It is build for the internal use inside this class.

Primary source for analyzing the header is mpgedit.org (no HTTPS) Another important source is Wikipedia

Base of the implementation of this method is from a python script from Vivake Gupta (vivake AT lab49.com) A further helpful code example comes from SirNickity from the hydrogenaud.io community

Those codes were improved by me to get information I need. These information (and more) are returned as dictionary. The returned dictionary contains the following keys:

• Relevant information:

  • "framesize" (int): Size of a frame in the MP3 file. This includes the 4 bytes of the MP3 Frame Header.

  • "frametime" (float): The playtime of the audio in milliseconds that is encoded in one frame

  • "layer" (int): MPEG layer. For MP3 it should be 3

  • "mpeg version" (int): MPEG version. For MP3, it should be 1

• Further information (I have no idea what some of the information mean. They are simply not relevant anyway.):

  • "protection" (bool): When True the header has a CRC16 checksum

  • "padding" (bool): When True the frame is padded with an extra slot. (The slot size is given in "slotsize")

  • "private" (bool): free to use

  • "mode" (str): Channel mode: "stereo", "joint stereo", "dual channel" or "mono"

  • "modeextension" (str): For MPEG Layer 1 and 2: "4-31", "8-31", "12-31" or "16-31". For MPEG Layer 3: "" (empty), "IS", "MS" or "IS+MS". "IS" stands for Intensity Stereo Mode, "MS" for MS Stereo Mode

  • "copyright" (bool): Copyrighted data

  • "original" (bool): Original data

  • "emphasis" (str): One of the following strings: "none", "50/15 ms", "reserved" or "CCIT J.17"

  • "samples" (int): Samples per frame

  • "slotsize" (int): The size of one slot

  • "bitspersample" (int): Bit per sample

  • "samplerate" (int): Samplerate

Parameters

header (int/bytes) – The 4 byte MP3 Frame Header in bytes, or as integer (unsigned, big endian!)

Returns

A dictionary with all information encoded in the header

Raises

• TypeError – When header is not of type bytes or int.

• ValueError – When there are invalid information encoded in the header.

Example

# ...
header = mp3.read(4)

if header[:2] != b"\xFF\xFB":
    raise ValueError("Expected Frame Sync Bits missing")
try:
    infos = self.AnalyzeHeader(header)
except ValueError as e:
    print("Invalid header! Problem: %s"%(str(e)))

Frames()

This is a generator that returns a frame from the loaded mp3 file and information about that frame.

The returned dictionary contains the following information:

• "frame" (bytes): A complete MP3 Frame including the Frame Header and the Frame Data

• "header" (dict): The interpretation of the MP3 Frame Header as returned by AnalyzeHeader()

• "total" (int): The total number of frames in the mp3 file

• "count" (int): The number of this frame between 1 and total

Returns

A generator that returns a dictionary including a mp3 frame

Example

mp3file = MP3File("./silence.mp3")
for frame in mp3file.Frames():
    print("=== %5i / %5i ==="%(frame["count"], frame["total"]))
    print(frame["header"])

Load(path)

This method loads a new mp3 file. All information from the previous file will be discard.

The method reads the whole file, analyzes each frame, and stores them in memory. The ID3 Tag gets also read, but not further processed.

The following diagram shows how this method loads and processes the mp3 file:

Parameters

path (str) – An absolute path to a valid mp3 file

Returns

Nothing

Raises

ValueError – When there are unexpected for invalid information in the given file.