PySoundFile is an audio library based on libsndfile, CFFI and Numpy
PySoundFile can read and write sound files. File reading/writing is supported through libsndfile, which is a free, cross-platform, open-source library for reading and writing many different sampled sound file formats that runs on many platforms including Windows, OS X, and Unix. It is accessed through CFFI, which is a foreight function interface for Python calling C code. CFFI is supported for CPython 2.6+, 3.x and PyPy 2.0+. PySoundFile represents audio data as NumPy arrays.
PySoundFile is BSD licensed.
(c) 2013, Bastian Bechtold
On the Python side, you need to have CFFI and Numpy in order to use
PySoundFile. Additionally, You need the library libsndfile installed on
your computer. On Unix, use your package manager to install libsndfile.
Then just install PySoundFile using pip or python setup.py install
.
If you are running Windows, I recommend using WinPython or some similar distribution. This should set you up with Numpy. However, you also need CFFI and it's dependency, PyCParser. A good place to get these are the Unofficial Windows Binaries for Python. Having installed those, you can download the Windows installers for PySoundFile:
PySoundFile-0.4.1.win-amd64-py2.7
PySoundFile-0.4.1.win-amd64-py3.3
PySoundFile-0.4.1.win32-py2.7
PySoundFile-0.4.1.win32-py3.3
Each SoundFile can either open a sound file on the disk, or a
file-like object (using libsndfile
's virtual file interface).
Every sound file has a specific samplerate, data format and a set
number of channels. Each sound file can be opened in read_mode
,
write_mode
, or read_write_mode
. Note that read_write_mode
is
unsupported for some formats.
You can read and write any file that libsndfile
can open.
This includes Microsoft WAV, OGG, FLAC and Matlab MAT files. Different
variants of these can be built by ORing snd_types
, snd_subtypes
and snd_endians
or using the predefined formats wave_file
,
flac_file
, matlab_file
and ogg_file
. Note that specifying the
format is only necessary when writing.
If a file on disk is opened, it is kept open for as long as the SoundFile object exists and closes automatically when it goes out of scope. Alternatively, the SoundFile object can be used as a context manager, which closes the file when it exits.
All data access uses frames as index. A frame is one discrete time-step in the sound file. Every frame contains as many samples as there are channels in the file.
Data can be written to the file using write()
, or read from the
file using read()
. Every read and write operation starts at a
certain position in the file. Reading N frames will change this
position by N frames as well. Alternatively, seek()
, and
seek_absolute()
, can be used to set the current position to a
frame index offset from the current position, the start of the file,
or the end of the file, respectively.
Here is an example for a program that reads a wave file and copies it into an ogg-vorbis file:
from pysoundfile import SoundFile
wave = SoundFile('existing_file.wav')
ogg = SoundFile('new_file.ogg', sample_rate=wave.samplerate,
channels=wave.channels, format=ogg_file,
mode=write_mode)
data = wave.read(1024)
while len(data) > 0:
ogg.write(data)
data = wave.read(1024)
Alternatively, slices can be used to access data at arbitrary positions in the file. Note that slices currently only work on frame indices, not channels.
Here is an example of reading in a whole wave file into a NumPy array:
from pysoundfile import SoundFile
wave = SoundFile('existing_file.wav')[:]
If you have an open file-like object, you can use something similar to this to decode it:
from io import BytesIO
from pysoundfile import SoundFile
fObj = BytesIO(open('filename.flac', 'rb').read())
flac = SoundFile(fObj, virtual_io=True)
Here is an example using an HTTP request:
from io import BytesIO
from pysoundfile import SoundFile
import requests
fObj = BytesIO()
response = requests.get('http://www.example.com/my.flac', stream=True)
for data in response.iter_content(4096):
if data:
fObj.write(data)
fObj.seek(0)
flac = SoundFile(fObj, virtual_io=True)
In addition to audio data, there are a number of text fields in every sound file. In particular, you can set a title, a copyright notice, a software description, the artist name, a comment, a date, the album name, a license, a tracknumber and a genre. Note however, that not all of these fields are supported for every file format.