soundfile 0.12.1

重大变更

soundfile模块在过去发展迅速。最值得注意的是，我们在0.7版本中将导入名称从import pysoundfile更改为import soundfile。在0.6版本中，我们清理了许多小的不一致，尤其是在函数参数的顺序和命名以及索引接口的删除方面。

在0.8.0版本中，我们将always_2d的默认值从True更改为False。此外，write函数的参数顺序已从write(data, file, ...)更改为write(file, data, ...)。

在0.9.0版本中，我们将buffer_*方法的ctype参数更改为dtype，使用Numpy的dtype表示法。旧的ctype参数仍然有效，但现在已被官方弃用。

在0.12.0版本中，我们更改了libsndfile库的加载顺序。现在，在平台特定的wheel中包装的libsndfile将首先尝试，然后再回退到任何系统提供的libsndfile。如果您想使用系统提供的libsndfile，请安装源包或源wheel，而不是平台特定的wheel。

安装

soundfile模块依赖于Python包CFFI和NumPy，以及库libsndfile。

在现代Python中，您可以使用pip install soundfile下载并安装soundfile模块的最新版本及其依赖项。在Windows（64/32位）和OS X（Intel/ARM）以及Linux 64位上，这将还会安装libsndfile库的当前版本。如果您安装源模块，您需要使用您发行版的包管理器安装libsndfile，例如sudo apt install libsndfile1。

如果您在一个不寻常的平台或使用Python的较旧版本上运行，您可能需要单独安装NumPy和CFFI，例如使用Anaconda包管理器或Python扩展包的非官方Windows二进制文件。

构建

Soundfile自身不包含任何编译代码，可以使用常规的python setup.py bdist_wheel打包成wheel。然而，soundfile依赖于libsndfile，并且可选地将自己的libsndfile副本包含在wheel中。

要构建包含libsndfile的二进制wheel，请确保检出并更新_soundfile_data子模块，然后像往常一样运行python setup.py bdist_wheel。如果wheel的结果文件大小约为1MB，则已捆绑了匹配的libsndfile（没有libsndfile，大小约为25KB）。

要为所有支持的平台构建二进制wheel，请运行python build_wheels.py，这将为我们预编译的libsndfile平台运行python setup.py bdist_wheel。

错误报告

在API使用错误的情况下，soundfile模块会引发通常的ValueError或TypeError。

对于其他错误，会引发SoundFileError（之前为RuntimeError）。特别是，会引发一个名为LibsndfileError的异常子类，该异常由libsndfile库报告错误。在这种情况下，异常对象提供了libsndfile内部错误代码，在LibsndfileError.code属性中，以及原始的libsndfile错误消息在LibsndfileError.error_string属性中。

读写函数

可以使用soundfile.write()将数据写入文件，或使用soundfile.read()从文件中读取数据。soundfile模块可以打开libsndfile支持的所有文件格式，例如WAV、FLAC、OGG和MAT文件（有关写入OGG文件的信息，请参阅下面的已知问题）。

以下是一个示例程序，该程序读取WAV文件并将其复制到FLAC文件中

import soundfile as sf

data, samplerate = sf.read('existing_file.wav')
sf.write('new_file.flac', data, samplerate)

块处理

声音文件也可以通过 soundfile.blocks() 以短块、可选重叠的方式读取。例如，这可以计算长文件的每个块的信号电平。

import numpy as np
import soundfile as sf

rms = [np.sqrt(np.mean(block**2)) for block in
       sf.blocks('myfile.wav', blocksize=1024, overlap=512)]

SoundFile 对象

声音文件还可以以 SoundFile 对象的形式打开。每个 SoundFile 都具有特定的采样率、数据格式和固定数量的通道。

如果打开一个文件，它将保持打开状态，直到 SoundFile 对象存在。当对象被垃圾回收时，文件将关闭，但您应该使用 SoundFile.close() 方法或上下文管理器显式关闭文件。

import soundfile as sf

with sf.SoundFile('myfile.wav', 'r+') as f:
    while f.tell() < f.frames:
        pos = f.tell()
        data = f.read(1024)
        f.seek(pos)
        f.write(data*2)

所有数据访问都使用帧作为索引。帧是声音文件中的一个离散时间步长。每个帧包含与文件中通道数量一样多的样本。

RAW 文件

soundfile.read() 通常可以自动检测声音文件的文件类型。然而，对于 RAW 文件则不行。

import soundfile as sf

data, samplerate = sf.read('myfile.raw', channels=1, samplerate=44100,
                           subtype='FLOAT')

请注意，在 x86 上，这默认为 endian='LITTLE'。如果您正在读取大端数据（主要是基于 PowerPC/6800 的旧文件），则需要相应地设置 endian='BIG'。

您可以用类似的方式写入 RAW 文件，但请注意，在大多数情况下，更具有表现力的格式更好，应该使用它。

虚拟 IO

如果您有一个打开的文件-like 对象，soundfile.read() 可以像常规文件一样打开它。

import soundfile as sf
with open('filename.flac', 'rb') as f:
    data, samplerate = sf.read(f)

以下是一个使用 HTTP 请求的示例

import io
import soundfile as sf
from urllib.request import urlopen

url = "http://tinyurl.com/shepard-risset"
data, samplerate = sf.read(io.BytesIO(urlopen(url).read()))

请注意，上述示例仅适用于 Python 3.x。对于 Python 2.x 支持，将第三行替换为

from urllib2 import urlopen

已知问题

使用 libsndfile 的某些版本写入 OGG 文件可能导致空文件。有关此问题的最新信息，请参阅 #130。

如果您使用 Buildroot 风格的系统，Python 将难以找到 libsndfile.so 文件，这会导致 python-soundfile 无法加载。这显然是 python 中的一个错误。目前，在 soundfile.py 中，您可以在 _ffi.dlopen 中移除对 _find_library 的调用，并将 libsndfile.so 的位置硬编码在。有关此问题的讨论，请参阅 #258。

新闻

2013-08-27 V0.1.0 Bastian Bechtold

初始原型。Python 中 libsndfile 的简单包装器

2013-08-30 V0.2.0 Bastian Bechtold

错误修复并与 PySoundCard 具有更多一致性

2013-08-30 V0.2.1 Bastian Bechtold

错误修复

2013-09-27 V0.3.0 Bastian Bechtold

为 Windows 添加了二进制安装程序和上下文管理器

2013-11-06 V0.3.1 Bastian Bechtold

从 distutils 切换到 setuptools 以便于安装

2013-11-29 V0.4.0 Bastian Bechtold

感谢 David Blewett，现在支持虚拟 IO！

2013-12-08 V0.4.1 Bastian Bechtold

感谢 Xidorn Quan，FLAC 文件不再是 float32。

2014-02-26 V0.5.0 Bastian Bechtold

感谢 Matthias Geier，改进了查找和 flush() 方法。

2015-01-19 V0.6.0 Bastian Bechtold

非常感谢 Matthias Geier，他做了大部分工作！

• 默认数据类型切换为 float64。

• 为了一致性，更改了函数参数。

• 添加了单元测试。

• 添加了全局 read()、write()、blocks() 便利函数。

• 文档重写并托管在 readthedocs 上。

• 添加了 'x' 打开模式。

• 添加了 tell() 方法。

• 添加了 __repr__() 方法。

2015-04-12 V0.7.0 Bastian Bechtold

再次感谢 Matthias Geier 的辛勤工作，但也要感谢 Nils Werner 和 Whistler7 提出的许多建议和帮助。

• 将 import pysoundfile 重命名为 import soundfile。

• 通过包含必要库的 pip 轮子进行安装。

• 从write()中移除了exclusive_creation参数。

• 添加了truncate()方法。

2015-10-20 V0.8.0 Bastian Bechtold

同样，Matthias Geier为此版本贡献了大量辛勤工作。

• 将always_2d的默认值从True更改为False。

• Numpy现在是可选的，并且仅在read和write时加载。

• 添加了SoundFile.buffer_read()、SoundFile.buffer_read_into()和SoundFile.buffer_write()，它们在不涉及Numpy的情况下读写原始数据。

• 添加了返回声音文件元数据的info()函数。

• 将write()函数的参数顺序从write(data, file, ...)更改为write(file, data, ...)。

以及许多其他小错误修复。

2017-02-02 V0.9.0 Bastian Bechtold

感谢Matthias Geier、Tomas Garcia和Todd为此版本做出的贡献。

• 添加了对ALAC文件的支持。

• 添加了新成员__libsndfile_version__

• 在info类中添加了帧数。

• 在buffer_*方法中添加了dtype参数。

• 弃用了ctype参数。

• 添加了对Python 3.6的官方支持。

以及一些小错误修复。

2017-11-12 V0.10.0 Bastian Bechtold

感谢Matthias Geier、Toni Barth、Jon Peirce、Till Hoffmann和Tomas Garcia为此版本做出的贡献。

• 现在应该可以与cx_freeze一起工作。

• 在README中修复了几个文档错误。

• 在buffer_*()中移除了已弃用的ctype参数，改为使用dtype。

• 添加了SoundFile.frames以替代已弃用的__len__()。

• 改进了blocks()和SoundFile.blocks()的性能。

• 通过使用CFFI的out of line模式来改进导入时间。

• 添加了用于构建分发的构建脚本。

2022-06-02 V0.11.0 Bastian Bechtold

感谢tennies、Hannes Helmholz、Christoph Boeddeker、Matt Vollrath、Matthias Geier、Jacek Konieczny、Boris Verkhovskiy、Jonas Haag、Eduardo Moguillansky、Panos Laganakos、Jarvy Jarvison、Domingo Ramirez、Tim Chagnon、Kyle Benesch、Fabian-Robert Stöter和Joe Todd为此版本做出的贡献。

• 添加了MP3支持。

• 为macOS M1添加了二进制wheel。

• 提高了与macOS的兼容性，特别是针对M1机器。

• 修复了在Windows和Python 3.5+上为二进制wheel打开文件描述符的问题。

• 更新了libsndfile到v1.1.0。

• 添加了get_strings方法，可以一次性检索所有元数据。

• 改进了文档、错误信息和测试。

• 以样本为单位显示非常短的文件长度。

• 支持文件系统路径协议（pathlib等）。

2023-02-02 V0.12.0 Bastian Bechtold

感谢Barabazs、Andrew Murray和Jon Peirce为此版本做出的贡献。

• 更新了libsndfile到v1.2.0。

• 改进了预编译库位置，尤其是在使用py2app或cx-freeze时。

• 现在提供Linux x86_64的二进制wheel。

• 现在优先使用打包的libsndfile而不是系统安装的libsndfile。

2023-02-15 V0.12.1 Bastian Bechtold

感谢funnypig提供的错误报告。

• 修复了在没有找到打包库和系统库的情况下检测库位置时的错误。