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