pymp3 - 读写MP3文件

简介

pymp3模块提供了对MP3音频格式的解码/编码接口。此库在内部使用libmp3lame (lame) 和 libmad。提供Windows和*nix系统的二进制发行版包。

安装

使用pip

pip install pymp3

从源代码安装

git clone https://github.com/miarec/pymp3
cd pymp3
pip install .

用法

mp3.Decoder对象（MP3-to-PCM转换器）

mp3.Decoder对象提供了一个对MP3-to-PCM解码功能的接口。它在内部使用知名libmad。

用法示例（将*.mp3文件转换为*.wav）

import mp3
from wave import Wave_write

with open('input.mp3', 'rb') as read_file, open('output.wav', 'wb') as write_file:

    decoder = mp3.Decoder(read_file)

    sample_rate = decoder.get_sample_rate()
    nchannels = decoder.get_channels()

    wav_file = Wave_write(write_file)
    wav_file.setnchannels(nchannels)
    wav_file.setsampwidth(2)
    wav_file.setframerate(sample_rate)

    while True:
        pcm_data = decoder.read(4000)

        if not pcm_data:
            break
        else:
            wav_file.writeframes(pcm_data)

mp3.Encoder对象（PCM-to-MP3转换器）

mp3.Encoder对象提供了一个对PCM-to-MP3编码功能的接口。它在内部使用知名libmp3lame。

用法示例（将*.wav文件转换为*.mp3）

import mp3
from wave import Wave_read

with open('input.wav', 'rb') as read_file, open('output.mp3', 'wb') as write_file:

    wav_file = Wave_read(read_file)

    sample_size = wav_file.getsampwidth()
    sample_rate = wav_file.getframerate()
    nchannels = wav_file.getnchannels()

    if sample_size != 2:
        raise ValueError("Only PCM 16-bit sample size is supported (input audio: %s)" % sample_size)

    encoder = mp3.Encoder(write_file)
    encoder.set_bit_rate(64)
    encoder.set_sample_rate(frame_rate)
    encoder.set_channels(nchannels)
    encoder.set_quality(5)   # 2-highest, 7-fastest
    encoder.set_mod(mp3.MODE_STEREO if nchannels == 2 else mp3.MODE_SINGLE_CHANNEL)

    while True:
        pcm_data = wav_file.readframes(8000)
        if pcm_data:
            encoder.write(pcm_data)
        else:
            encoder.flush()
            break

接口

常量

MPEG层版本，由Decoder.get_layer()返回

• mp3.LAYER_I
• mp3.LAYER_II
• mp3.LAYER_III

MPEG模式，由Decoder.get_mode()返回或提供给Encoder.set_mode()

• mp3.MODE_SINGLE_CHANNEL：单声道（单通道）
• mp3.MODE_DUAL_CHANNEL：双通道模式。注意！LAME编码器不支持双通道模式，请使用立体声或联合立体声。
• mp3.MODE_STEREO：立体声模式（适用于高比特率）
• mp3.MODE_JOINT_STEREO：联合立体声模式（适用于低比特率）

mp3.Encoder（PCM-to-MP3转换器）

构造函数

• mp3.Encoder(fp)：创建一个编码器对象。`fp`是一个具有`write()`方法的文件类对象，用于写入二进制数据。

类方法

• set_channels(nchannels: int): 设置通道数（1为单声道，2为立体声）
• set_quality(quality: int): 设置编码器质量，2为最高，7为最快（默认为5）
• set_bit_rate(bitrate: int): 设置恒定比特率（单位：kbps）
• set_sample_rate(sample_rate: int): 设置输入采样率（单位：Hz）
• set_mode(mode: int): 设置MPEG模式（可以是mp3.MODE_STEREO、mp3.MODE_JOINT_STEREO、mp3.MODE_SINGLE_CHANNEL之一）。注意，LAME不支持双通道模式！
• write(data: bytes): 对一块PCM数据进行编码（有符号16位交错）并将其写入文件。
• flush(): 将最后的MP3数据块刷新到文件中。

重要！

在关闭文件之前，调用flush()方法将最后的MP3数据块写入文件。

mp3.Decoder (MP3转PCM转换器)

构造函数

• mp3.Decoder(fp): 创建一个解码器对象。fp是一个具有read()方法的文件类似对象，用于读取二进制数据。

类方法

• is_valid() -> bool: 如果文件中至少找到一个有效的MPEG帧，则返回TRUE
• read(nbytes = None: int) -> bytes: 读取mp3文件，解码成PCM格式（16位有符号交错）并返回请求的字节数。如果未提供nbytes，则从文件中读取多达256MB
• get_channels() -> int: 获取通道数（1为单声道，2为立体声）
• get_bit_rate() -> int: 获取比特率（单位：kbps）
• get_sample_rate() -> int: 获取采样率（单位：Hz）
• get_mode() -> int: 获取MPEG模式（可以是mp3.MODE_STEREO、mp3.MODE_JOINT_STEREO、mp3.MODE_SINGLE_CHANNEL或mp3.MODE_DUAL_CHANNEL）
• get_layer() -> int: 获取MPEG层（可以是mp3.LAYER_I、mp3.Layer_II、mp3.Layer_III）

构建二进制包

先决条件

• [推荐] 使用python -v venv venv创建python虚拟环境，并使用source venv/bin/activate激活它
• 使用pip install -r requirements-dev.txt安装开发所需的包

要为您的平台构建二进制包（*.whl），运行

pip wheel . --verbose

该命令的结果将在当前目录中生成mp3*.whl文件。

可选的--verbose参数允许您查看构建过程。

要安装构建的WHL文件

pip install pymp3*.whl

要在开发模式下构建和安装包

pip install -e . --verbose

此命令将构建*.so文件（或Windows上的*.dll）而不是*.whl。

可选的--verbose参数允许您查看构建过程。

单元测试

要运行单元测试，使用以下命令（假设pymp3模块已安装到当前python环境中）

pytest tests

解决构建失败的问题（C代码）

该库是用CMake构建的，当setuptools构建包时会自动调用CMake。

您可以直接调用CMake来查看报告的错误信息

cmake -S . -B build
cmake --build build

如果系统上可用的Python解释器有多个，则向cmake命令添加-DPython3_EXECUTABLE=<path-to-python-exe>以提示CMake使用正确的版本。否则，CMake将选择默认的Python解释器。

该命令将在相应的构建目录中构建pymp3.so（或Windows上的pymp3.pyd）文件（在Windows上，它将是./build/Release或./build/Debug，在Linux上，它将是./build）。

默认情况下，Windows上的Visual Studio构建Debug配置。向构建命令添加--config=Release以选择Release配置

cmake --build build --config=Release

默认情况下，此项目将从github下载lame和mad库并在本地编译。如果您想使用系统安装的lame/mad，请将以下参数传递给cmake命令

-DPYMP3_USE_SYSTEM_LIBMAD=ON -DPYMP3_USE_SYSTEM_LAME=ON

TODO

• 允许用户通过环境变量定义PYMP3_USE_SYSTEM_LIBMAD/LAME，在setup.py中读取它们并将其传递给cmake