1SoundFile
2=========
3
4|version| |python| |status| |license|
5
6|contributors| |downloads|
7
8`SoundFile <https://github.com/bastibe/SoundFile>`__ is an audio
9library based on libsndfile, CFFI and NumPy. Full documentation is
10available on http://pysoundfile.readthedocs.org/.
11
12SoundFile can read and write sound files. File reading/writing is
13supported through `libsndfile <http://www.mega-nerd.com/libsndfile/>`__,
14which is a free, cross-platform, open-source (LGPL) library for reading
15and writing many different sampled sound file formats that runs on many
16platforms including Windows, OS X, and Unix. It is accessed through
17`CFFI <http://cffi.readthedocs.org/>`__, which is a foreign function
18interface for Python calling C code. CFFI is supported for CPython 2.6+,
193.x and PyPy 2.0+. SoundFile represents audio data as NumPy arrays.
20
21| SoundFile is BSD licensed (BSD 3-Clause License).
22| (c) 2013, Bastian Bechtold
23
24
25|open-issues| |closed-issues| |open-prs| |closed-prs|
26
27.. |contributors| image:: https://img.shields.io/github/contributors/bastibe/soundfile.svg
28.. |version| image:: https://img.shields.io/pypi/v/soundfile.svg
29.. |python| image:: https://img.shields.io/pypi/pyversions/soundfile.svg
30.. |license| image:: https://img.shields.io/github/license/bastibe/soundfile.svg
31.. |downloads| image:: https://img.shields.io/pypi/dm/soundfile.svg
32.. |open-issues| image:: https://img.shields.io/github/issues/bastibe/soundfile.svg
33.. |closed-issues| image:: https://img.shields.io/github/issues-closed/bastibe/soundfile.svg
34.. |open-prs| image:: https://img.shields.io/github/issues-pr/bastibe/soundfile.svg
35.. |closed-prs| image:: https://img.shields.io/github/issues-pr-closed/bastibe/soundfile.svg
36.. |status| image:: https://img.shields.io/pypi/status/soundfile.svg
37
38Breaking Changes
39----------------
40
41SoundFile has evolved rapidly during the last few releases. Most
42notably, we changed the import name from ``import pysoundfile`` to
43``import soundfile`` in 0.7. In 0.6, we cleaned up many small
44inconsistencies, particularly in the the ordering and naming of
45function arguments and the removal of the indexing interface.
46
47In 0.8.0, we changed the default value of ``always_2d`` from ``True``
48to ``False``. Also, the order of arguments of the ``write`` function
49changed from ``write(data, file, ...)`` to ``write(file, data, ...)``.
50
51In 0.9.0, we changed the ``ctype`` arguments of the ``buffer_*``
52methods to ``dtype``, using the Numpy ``dtype`` notation. The old
53``ctype`` arguments still work, but are now officially deprecated.
54
55Installation
56------------
57
58SoundFile depends on the Python packages CFFI and NumPy, and the
59system library libsndfile.
60
61In a modern Python, you can use ``pip install soundfile`` to download
62and install the latest release of SoundFile and its dependencies.
63On Windows and OS X, this will also install the library libsndfile.
64On Linux, you need to install libsndfile using your distribution's
65package manager, for example ``sudo apt-get install libsndfile1``.
66
67If you are running on an unusual platform or if you are using an older
68version of Python, you might need to install NumPy and CFFI separately,
69for example using the Anaconda_ package manager or the `Unofficial Windows
70Binaries for Python Extension Packages <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_.
71
72.. _Anaconda: https://www.continuum.io/downloads
73
74Read/Write Functions
75--------------------
76
77Data can be written to the file using `soundfile.write()`, or read from
78the file using `soundfile.read()`. SoundFile can open all file formats
79that `libsndfile supports
80<http://www.mega-nerd.com/libsndfile/#Features>`__, for example WAV,
81FLAC, OGG and MAT files (see `Known Issues <https://github.com/bastibe/SoundFile#known-issues>`__ below about writing OGG files).
82
83Here is an example for a program that reads a wave file and copies it
84into an FLAC file:
85
86.. code:: python
87
88 import soundfile as sf
89
90 data, samplerate = sf.read('existing_file.wav')
91 sf.write('new_file.flac', data, samplerate)
92
93Block Processing
94----------------
95
96Sound files can also be read in short, optionally overlapping blocks
97with `soundfile.blocks()`.
98For example, this calculates the signal level for each block of a long
99file:
100
101.. code:: python
102
103 import numpy as np
104 import soundfile as sf
105
106 rms = [np.sqrt(np.mean(block**2)) for block in
107 sf.blocks('myfile.wav', blocksize=1024, overlap=512)]
108
109SoundFile Objects
110-----------------
111
112Sound files can also be opened as `soundfile.SoundFile` objects. Every
113SoundFile has a specific sample rate, data format and a set number of
114channels.
115
116If a file is opened, it is kept open for as long as the SoundFile
117object exists. The file closes when the object is garbage collected,
118but you should use the `soundfile.SoundFile.close()` method or the
119context manager to close the file explicitly:
120
121.. code:: python
122
123 import soundfile as sf
124
125 with sf.SoundFile('myfile.wav', 'r+') as f:
126 while f.tell() < f.frames:
127 pos = f.tell()
128 data = f.read(1024)
129 f.seek(pos)
130 f.write(data*2)
131
132All data access uses frames as index. A frame is one discrete time-step
133in the sound file. Every frame contains as many samples as there are
134channels in the file.
135
136RAW Files
137---------
138
139Pysoundfile can usually auto-detect the file type of sound files. This
140is not possible for RAW files, though:
141
142.. code:: python
143
144 import soundfile as sf
145
146 data, samplerate = sf.read('myfile.raw', channels=1, samplerate=44100,
147 subtype='FLOAT')
148
149Note that on x86, this defaults to ``endian='LITTLE'``. If you are
150reading big endian data (mostly old PowerPC/6800-based files), you
151have to set ``endian='BIG'`` accordingly.
152
153You can write RAW files in a similar way, but be advised that in most
154cases, a more expressive format is better and should be used instead.
155
156Virtual IO
157----------
158
159If you have an open file-like object, Pysoundfile can open it just like
160regular files:
161
162.. code:: python
163
164 import soundfile as sf
165 with open('filename.flac', 'rb') as f:
166 data, samplerate = sf.read(f)
167
168Here is an example using an HTTP request:
169
170.. code:: python
171
172 import io
173 import soundfile as sf
174 from urllib.request import urlopen
175
176 url = "http://tinyurl.com/shepard-risset"
177 data, samplerate = sf.read(io.BytesIO(urlopen(url).read()))
178
179Note that the above example only works with Python 3.x.
180For Python 2.x support, replace the third line with:
181
182.. code:: python
183
184 from urllib2 import urlopen
185
186Known Issues
187------------
188
189Writing to OGG files can result in empty files with certain versions of libsndfile. See `#130 <https://github.com/bastibe/SoundFile/issues/130>`__ for news on this issue.
190
191News
192----
193
1942013-08-27 V0.1.0 Bastian Bechtold:
195 Initial prototype. A simple wrapper for libsndfile in Python
196
1972013-08-30 V0.2.0 Bastian Bechtold:
198 Bugfixes and more consistency with PySoundCard
199
2002013-08-30 V0.2.1 Bastian Bechtold:
201 Bugfixes
202
2032013-09-27 V0.3.0 Bastian Bechtold:
204 Added binary installer for Windows, and context manager
205
2062013-11-06 V0.3.1 Bastian Bechtold:
207 Switched from distutils to setuptools for easier installation
208
2092013-11-29 V0.4.0 Bastian Bechtold:
210 Thanks to David Blewett, now with Virtual IO!
211
2122013-12-08 V0.4.1 Bastian Bechtold:
213 Thanks to Xidorn Quan, FLAC files are not float32 any more.
214
2152014-02-26 V0.5.0 Bastian Bechtold:
216 Thanks to Matthias Geier, improved seeking and a flush() method.
217
2182015-01-19 V0.6.0 Bastian Bechtold:
219 A big, big thank you to Matthias Geier, who did most of the work!
220
221 - Switched to ``float64`` as default data type.
222 - Function arguments changed for consistency.
223 - Added unit tests.
224 - Added global ``read()``, ``write()``, ``blocks()`` convenience
225 functions.
226 - Documentation overhaul and hosting on readthedocs.
227 - Added ``'x'`` open mode.
228 - Added ``tell()`` method.
229 - Added ``__repr__()`` method.
230
2312015-04-12 V0.7.0 Bastian Bechtold:
232 Again, thanks to Matthias Geier for all of his hard work, but also
233 Nils Werner and Whistler7 for their many suggestions and help.
234
235 - Renamed ``import pysoundfile`` to ``import soundfile``.
236 - Installation through pip wheels that contain the necessary
237 libraries for OS X and Windows.
238 - Removed ``exclusive_creation`` argument to ``write``.
239 - Added ``truncate()`` method.
240
2412015-10-20 V0.8.0 Bastian Bechtold:
242 Again, Matthias Geier contributed a whole lot of hard work to this
243 release.
244
245 - Changed the default value of ``always_2d`` from ``True`` to
246 ``False``.
247 - Numpy is now optional, and only loaded for ``read`` and
248 ``write``.
249 - Added ``SoundFile.buffer_read`` and
250 ``SoundFile.buffer_read_into`` and ``SoundFile.buffer_write``,
251 which read/write raw data without involving Numpy.
252 - Added ``info`` function that returns metadata of a sound file.
253 - Changed the argument order of the ``write`` function from
254 ``write(data, file, ...)`` to ``write(file, data, ...)``
255
256 And many more minor bug fixes.
257
2582017-02-02 V0.9.0 Bastian Bechtold:
259 Thank you, Matthias Geier, Tomas Garcia, and Todd, for contributions
260 for this release.
261
262 - Adds support for ALAC files.
263 - Adds new member ``__libsndfile_version__``
264 - Adds number of frames to ``info`` class
265 - Adds ``dtype`` argument to ``buffer_*`` methods
266 - Deprecates ``ctype`` argument to ``buffer_*`` methods
267 - Adds official support for Python 3.6
268
269 And some minor bug fixes.
270
2712017-11-12 V0.10.0 Bastian Bechtold:
272 Thank you, Matthias Geier, Toni Barth, Jon Peirce, Till Hoffmann,
273 and Tomas Garcia, for contributions to this release.
274
275 - Should now work with cx_freeze.
276 - Several documentation fixes in the README.
277 - Removes deprecated ``ctype`` argument in favor of ``dtype`` in ``buffer_*()``.
278 - Adds ``SoundFile.frames`` in favor of now-deprecated ``__len__()``.
279 - Improves performance of ``blocks`` and ``SoundFile.blocks()``.
280 - Improves import time by using CFFI's out of line mode.
281 - Adds a build script for building distributions.
282