pymp3 Library

Common errors

• ModuleNotFoundError: No module named 'pymp3'

  cause The `pymp3` library is not installed in your current Python environment.
  fix Install the library using pip: `pip install pymp3`

• error: command 'gcc' failed: No such file or directory

  cause pymp3 is a C extension. This error indicates that the C compiler (gcc) is not found on your system, which is required by pip to compile the library from source.
  fix Install the necessary build tools for your operating system. For Debian/Ubuntu: `sudo apt-get install build-essential`. For macOS: `xcode-select --install`. For Windows: Install 'Desktop development with C++' from Visual Studio Installer.

• An error occurred during decoding: Error decoding MP3 data: Invalid MP3 frame header

  cause The `mp3_data` provided to the `MP3Decoder` does not contain valid MP3 frame headers, or the data is corrupted/incomplete.
  fix Ensure the input `mp3_data` is a complete and valid byte stream of an MP3 file. Verify the source of your MP3 data.

• AttributeError: 'MP3Decoder' object has no attribute 'decode_file'

  cause The `MP3Decoder` class expects raw byte data, not a file path or file object, for its `decode` method. There is no `decode_file` method.
  fix Read the MP3 file's content into a bytes object first, then pass the bytes to `decoder.decode()`. Example: `with open('myfile.mp3', 'rb') as f: mp3_data = f.read(); frames = decoder.decode(mp3_data)`

Warnings

• gotcha pymp3 is a C extension library, meaning it requires a C compiler and development tools (e.g., `build-essential` on Debian/Ubuntu, Xcode Command Line Tools on macOS, Visual C++ Build Tools on Windows) to be installed on your system if pip needs to compile it from source. Compilation issues are common if these tools are missing or misconfigured.
  Fix: Ensure you have the necessary C/C++ build tools for your operating system installed before attempting to `pip install pymp3`.
• breaking Version 0.2.0 specifically addressed a build issue on macOS. Users on macOS attempting to install earlier versions (v0.1.9 or older) might encounter compilation errors, preventing installation.
  Fix: Upgrade to pymp3 version 0.2.0 or newer: `pip install --upgrade pymp3`. Ensure your pip is up to date.
• gotcha pymp3 provides low-level access to MP3 decoding and encoding (raw audio frames). It does NOT include functionality for parsing or manipulating high-level metadata such as ID3 tags (artist, title, album, etc.). If you need ID3 tag support, consider libraries like `mutagen` or `id3-tagger`.
  Fix: For ID3 tag manipulation, use dedicated libraries. For example: `pip install mutagen` and refer to its documentation.

Install

• pip install pymp3 Install pymp3

Imports

• MP3Decoder
  wrong:

  import pymp3.MP3Decoder

  correct:

  from pymp3 import MP3Decoder

  While 'import pymp3' then 'pymp3.MP3Decoder' works, direct import is generally preferred for clarity.
• MP3Encoder

  from pymp3 import MP3Encoder

• PCMFrame

  from pymp3 import PCMFrame

  PCMFrame objects are returned by the decoder, but can also be imported if needed for type hinting or explicit construction.

Quickstart

This quickstart demonstrates how to use `pymp3.MP3Decoder` to process MP3 data into PCM frames. It also includes a conceptual example for `MP3Encoder`. For actual use, replace the placeholder `mp3_data` with valid MP3 content from a file or stream. The library provides low-level access to audio frames, not high-level ID3 tag manipulation.

import io
from pymp3 import MP3Decoder

# In a real application, mp3_data would come from a file or network stream
# For demonstration, we'll use a placeholder or minimal real data if available.
# Note: A real MP3 file's header is required for successful decoding.
# This example uses a very small, non-functional byte string as a stand-in
# to illustrate the API without requiring a file. Expect decoding errors with this.
# Replace with actual MP3 data for practical use.

# Example of dummy data (will likely fail to decode, but shows API):
mp3_data = b'\xff\xfb\x90\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'

try:
    decoder = MP3Decoder()
    frames = decoder.decode(mp3_data)

    if not frames:
        print("No frames decoded. Ensure 'mp3_data' contains valid MP3 content.")
    else:
        print(f"Decoded {len(frames)} PCM frames.")
        for i, frame in enumerate(frames):
            if i < 3: # Print details for first few frames
                print(f"Frame {i+1}: Sample Rate={frame.sample_rate}Hz, Channels={frame.channels}, Data Size={frame.data_size} bytes")
            # frame.data contains the raw PCM bytes

except Exception as e:
    print(f"An error occurred during decoding: {e}")
    print("HINT: Ensure the 'mp3_data' variable contains actual, valid MP3 audio data.")


# --- Example of encoding (conceptual, requires PCM data) ---
# from pymp3 import MP3Encoder, PCMFrame
#
# # Assuming you have some PCM data (e.g., from decoding or generation)
# # This is highly conceptual as valid PCM data is required.
# dummy_pcm_data = b'\x00\x00\x00\x00' * 1024 # Placeholder 16-bit stereo silence
# sample_rate = 44100
# channels = 2
# pcm_frame = PCMFrame(sample_rate, channels, dummy_pcm_data)
#
# try:
#     encoder = MP3Encoder(sample_rate=sample_rate, channels=channels, bitrate=128)
#     encoded_mp3_data = encoder.encode([pcm_frame]) # encode expects a list of frames
#     print(f"Encoded {len(encoded_mp3_data)} bytes of MP3 data (conceptual).")
# except Exception as e:
#     print(f"An error occurred during encoding: {e}")
#     print("HINT: Ensure PCMFrame data and encoder parameters are valid.")