LAME MP3 Encoder Bindings

1.8.2 · active · verified Sat Apr 11

lameenc is a Python library providing bindings for the LAME MP3 encoding library. It simplifies the process of encoding PCM audio data into MP3 format without requiring users to compile the LAME binaries themselves, as it distributes pre-compiled wheels for various operating systems and Python versions. The library is actively maintained, with frequent updates to support new Python versions and add features.

Warnings

breaking Python version support changes frequently. For example, v1.8.2 dropped support for Python 3.8 and 3.9, and v1.6.2 dropped support for Python 3.7. Always check the latest release notes for compatible Python versions.
Fix: Ensure your project's Python environment aligns with the `lameenc` version's supported Python range. Upgrade Python or pin `lameenc` to an older compatible version.
breaking The library's license switched from MIT to LGPLv3 in v1.5.0. This is a significant change with implications for how projects using `lameenc` can be licensed and distributed.
Fix: Review the LGPLv3 license requirements and ensure your project's licensing and distribution comply with its terms if using versions 1.5.0 or newer.
gotcha The `Encoder` expects raw PCM data in 16-bit interleaved format. Incorrect input format (e.g., 8-bit, 32-bit float, non-interleaved, or different channel ordering) will lead to corrupted output or errors.
Fix: Pre-process your audio data to ensure it's in the required 16-bit signed integer, interleaved PCM format. Libraries like `soundfile` or `scipy.io.wavfile` can help read/convert audio files to this format.
gotcha Older versions of `lameenc` (prior to v1.6.0) had optimization issues on macOS and Linux, which meant significantly slower encoding performance compared to later versions or direct LAME command-line usage.
Fix: Upgrade to `lameenc` version 1.6.0 or newer to benefit from improved encoding speeds on macOS and Linux platforms.
gotcha Variable Bit Rate (VBR) encoding support was added in v1.8.0. If you require VBR, ensure you are using this version or newer.
Fix: To use VBR encoding, upgrade to `lameenc` version 1.8.0 or later. Consult the `Encoder` API for the new methods to configure VBR.
gotcha The ability to set the output sample rate was introduced in v1.7.0. Prior versions only allowed setting the input sample rate.
Fix: If you need to explicitly control the output sample rate, upgrade to `lameenc` version 1.7.0 or later and use the `set_out_sample_rate()` method.
gotcha While `lameenc` provides Python bindings, some external tools and libraries have observed it to be 'slow' due to factors like writing temporary files to disk or introducing encoder/decoder delays. This may affect real-time or performance-critical applications.
Fix: For highly performance-sensitive applications, benchmark `lameenc` against other available audio processing libraries or consider directly invoking the LAME command-line tool via `subprocess` if intermediate file I/O is acceptable.

Install

pip install lameenc Install stable version

Imports

Encoder
```
from lameenc import Encoder
```
The primary class for MP3 encoding is `Encoder`.

Quickstart

This quickstart demonstrates how to initialize the `lameenc.Encoder`, configure its parameters like bit rate, sample rate, channels, and quality, and then encode raw 16-bit interleaved PCM audio data into an MP3 byte stream. The example includes generating dummy stereo sine wave PCM data for a runnable demonstration.

import lameenc
import array

# Example: Generate some dummy 16-bit PCM stereo audio (e.g., a sine wave)
# For a real application, this would come from an audio input/file
sample_rate = 44100  # Hz
channels = 2         # Stereo
duration = 3         # seconds
num_samples = sample_rate * duration

# Create a bytearray for 16-bit interleaved PCM data
# Each sample is 2 bytes (16-bit), stereo means 2 samples per frame
pcm_data_raw = array.array('h', [0] * (num_samples * channels))

# Fill with a simple sine wave (for demonstration purposes)
import math
for i in range(num_samples):
    amplitude = int(32767 * math.sin(2 * math.pi * 440 * i / sample_rate))
    pcm_data_raw[i * channels] = amplitude  # Left channel
    pcm_data_raw[i * channels + 1] = amplitude # Right channel

pcm_bytes = pcm_data_raw.tobytes()

# Initialize the encoder
encoder = lameenc.Encoder()
encoder.set_bit_rate(128)  # 128 kbps
encoder.set_in_sample_rate(sample_rate)
encoder.set_channels(channels)
encoder.set_quality(2)     # 2 = highest, 7 = fastest

# Encode the audio
mp3_data = encoder.encode(pcm_bytes)
mp3_data += encoder.flush() # Flush any remaining buffered data

# Save to a file (optional)
with open('output.mp3', 'wb') as f:
    f.write(mp3_data)

print(f"MP3 data generated and saved to output.mp3 (size: {len(mp3_data)} bytes)")

view raw JSON →