Registry / serialization / pymp3
library0.2.0pypypiunverified

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.

pip install pymp3
INSTALL
IMPORT
SIG · PYMP3
P
pymp3
serializationpythonv0.2.0
Install
1.7s avg
Import
Disk
17MB
Pass rate
8/ 10
Env Coverage8 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✓ —
✓ 1.65s
py 3.11
✓ —
✓ 1.65s
py 3.12
✓ —
✓ 1.6s
py 3.13
✕ build_error
✕ build_error
py 3.9
✓ —
✓ 1.8s
17MB installed
● package 17MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

MP3Decoder
from pymp3 import MP3Decoder
import pymp3.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.

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.")
Debug
Known issues
gotchapymp3 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`.
affects: All versions
breakingVersion 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.
affects: <0.2.0 on macOS
gotchapymp3 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.
affects: All versions
Upgrade
Version history
0.2.0latest on PyPI · released Mar 6, 2024
Audit
Dependencies

No dependency data recorded yet.

Agent activity
29 hits · last 30 days
node
26
Resources
pymp3 — pip install pymp3 · libregistry