{"id":8502,"library":"pymp3","title":"pymp3 Library","description":"pymp3 is a lightweight Python library for reading and writing MP3 files, primarily providing low-level access to MP3 frames and PCM data. It is currently at version 0.2.0 and has an infrequent release cadence, focusing on stability and essential bug fixes.","status":"active","version":"0.2.0","language":"en","source_language":"en","source_url":"https://github.com/miarec/pymp3","tags":["audio","mp3","encoding","decoding","low-level"],"install":[{"cmd":"pip install pymp3","lang":"bash","label":"Install pymp3"}],"dependencies":[],"imports":[{"note":"While 'import pymp3' then 'pymp3.MP3Decoder' works, direct import is generally preferred for clarity.","wrong":"import pymp3.MP3Decoder","symbol":"MP3Decoder","correct":"from pymp3 import MP3Decoder"},{"symbol":"MP3Encoder","correct":"from pymp3 import MP3Encoder"},{"note":"PCMFrame objects are returned by the decoder, but can also be imported if needed for type hinting or explicit construction.","symbol":"PCMFrame","correct":"from pymp3 import PCMFrame"}],"quickstart":{"code":"import io\nfrom pymp3 import MP3Decoder\n\n# In a real application, mp3_data would come from a file or network stream\n# For demonstration, we'll use a placeholder or minimal real data if available.\n# Note: A real MP3 file's header is required for successful decoding.\n# This example uses a very small, non-functional byte string as a stand-in\n# to illustrate the API without requiring a file. Expect decoding errors with this.\n# Replace with actual MP3 data for practical use.\n\n# Example of dummy data (will likely fail to decode, but shows API):\nmp3_data = b'\\xff\\xfb\\x90\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00'\n\ntry:\n    decoder = MP3Decoder()\n    frames = decoder.decode(mp3_data)\n\n    if not frames:\n        print(\"No frames decoded. Ensure 'mp3_data' contains valid MP3 content.\")\n    else:\n        print(f\"Decoded {len(frames)} PCM frames.\")\n        for i, frame in enumerate(frames):\n            if i < 3: # Print details for first few frames\n                print(f\"Frame {i+1}: Sample Rate={frame.sample_rate}Hz, Channels={frame.channels}, Data Size={frame.data_size} bytes\")\n            # frame.data contains the raw PCM bytes\n\nexcept Exception as e:\n    print(f\"An error occurred during decoding: {e}\")\n    print(\"HINT: Ensure the 'mp3_data' variable contains actual, valid MP3 audio data.\")\n\n\n# --- Example of encoding (conceptual, requires PCM data) ---\n# from pymp3 import MP3Encoder, PCMFrame\n#\n# # Assuming you have some PCM data (e.g., from decoding or generation)\n# # This is highly conceptual as valid PCM data is required.\n# dummy_pcm_data = b'\\x00\\x00\\x00\\x00' * 1024 # Placeholder 16-bit stereo silence\n# sample_rate = 44100\n# channels = 2\n# pcm_frame = PCMFrame(sample_rate, channels, dummy_pcm_data)\n#\n# try:\n#     encoder = MP3Encoder(sample_rate=sample_rate, channels=channels, bitrate=128)\n#     encoded_mp3_data = encoder.encode([pcm_frame]) # encode expects a list of frames\n#     print(f\"Encoded {len(encoded_mp3_data)} bytes of MP3 data (conceptual).\")\n# except Exception as e:\n#     print(f\"An error occurred during encoding: {e}\")\n#     print(\"HINT: Ensure PCMFrame data and encoder parameters are valid.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure you have the necessary C/C++ build tools for your operating system installed before attempting to `pip install pymp3`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to pymp3 version 0.2.0 or newer: `pip install --upgrade pymp3`. Ensure your pip is up to date.","message":"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.","severity":"breaking","affected_versions":"<0.2.0 on macOS"},{"fix":"For ID3 tag manipulation, use dedicated libraries. For example: `pip install mutagen` and refer to its documentation.","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the library using pip: `pip install pymp3`","cause":"The `pymp3` library is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'pymp3'"},{"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.","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.","error":"error: command 'gcc' failed: No such file or directory"},{"fix":"Ensure the input `mp3_data` is a complete and valid byte stream of an MP3 file. Verify the source of your MP3 data.","cause":"The `mp3_data` provided to the `MP3Decoder` does not contain valid MP3 frame headers, or the data is corrupted/incomplete.","error":"An error occurred during decoding: Error decoding MP3 data: Invalid MP3 frame header"},{"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)`","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.","error":"AttributeError: 'MP3Decoder' object has no attribute 'decode_file'"}]}