MP3 Stream Interface

This module provides a class to read any audio file and provide it as mp3 frames. Transcoding is done by the MP3 Transcoder module.

MP3Stream Class

class musicdb.lib.stream.mp3stream.MP3Stream(path)

This class allows frame wise access to mp3 frames generated from an valid audio file by transcoding it. See MP3 Transcoder for more details about the transcoding process. The frame wise access can be done by the Frames() generator. Beside the mp3 frames the generator returns lots of information extracted from the mp3 Frame Header.

This class expects a valid audio file and provides an MPEG Layer III mp3 stream without any meta data like an ID3 Tag.

As soon as the object gets created, it starts the transcoding process.

Parameters

path (str/Path) – An absolute path to a valid audio file

Example

mp3stream = MP3Stream("/tmp/test.m4a")  # Start transcoding
for frame in mp3stream.Frames():        # Access mp3 frames
    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 = mp3stream.GetChunk(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 mp3 frame each iteration. There will be no ID3 Tag or any other meta data.

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()

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

When the Version code of an MP3 frame is not as expected, a warning will be printed. This warning will only be printed once for each file.

Returns

A generator that returns a dictionary including a mp3 frame

Raises

ValueError – When the MP3 Sync Bits are not correct

Example

mp3stream = MP3Stream("/tmp/test.m4a")
for frame in mp3stream.Frames():
    print(frame["header"])