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