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