Videre
This commit is contained in:
@@ -0,0 +1,438 @@
|
||||
Metadata-Version: 2.1
|
||||
Name: soundfile
|
||||
Version: 0.13.1
|
||||
Summary: An audio library based on libsndfile, CFFI and NumPy
|
||||
Home-page: https://github.com/bastibe/python-soundfile
|
||||
Author: Bastian Bechtold
|
||||
Author-email: basti@bastibe.de
|
||||
License: BSD 3-Clause License
|
||||
Keywords: audio,libsndfile
|
||||
Platform: any
|
||||
Classifier: Development Status :: 5 - Production/Stable
|
||||
Classifier: Intended Audience :: Developers
|
||||
Classifier: Intended Audience :: Science/Research
|
||||
Classifier: License :: OSI Approved :: BSD License
|
||||
Classifier: Natural Language :: English
|
||||
Classifier: Operating System :: OS Independent
|
||||
Classifier: Programming Language :: Python
|
||||
Classifier: Programming Language :: Python :: 3
|
||||
Classifier: Programming Language :: Python :: 2
|
||||
Classifier: Programming Language :: Python :: Implementation :: PyPy
|
||||
Classifier: Programming Language :: Python :: Implementation :: CPython
|
||||
Classifier: Topic :: Multimedia :: Sound/Audio
|
||||
Description-Content-Type: text/x-rst
|
||||
License-File: LICENSE
|
||||
Requires-Dist: cffi >=1.0
|
||||
Requires-Dist: numpy
|
||||
Provides-Extra: numpy
|
||||
|
||||
python-soundfile
|
||||
================
|
||||
|
||||
|version| |python| |status| |license|
|
||||
|
||||
|contributors| |downloads|
|
||||
|
||||
The `soundfile <https://github.com/bastibe/python-soundfile>`__ module is an audio
|
||||
library based on libsndfile, CFFI and NumPy. Full documentation is
|
||||
available on https://python-soundfile.readthedocs.io/.
|
||||
|
||||
The ``soundfile`` module can read and write sound files. File reading/writing is
|
||||
supported through `libsndfile <http://www.mega-nerd.com/libsndfile/>`__,
|
||||
which is a free, cross-platform, open-source (LGPL) 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 <https://cffi.readthedocs.io/>`__, which is a foreign function
|
||||
interface for Python calling C code. CFFI is supported for CPython 2.6+,
|
||||
3.x and PyPy 2.0+. The ``soundfile`` module represents audio data as NumPy arrays.
|
||||
|
||||
| python-soundfile is BSD licensed (BSD 3-Clause License).
|
||||
| (c) 2013, Bastian Bechtold
|
||||
|
||||
|
||||
|open-issues| |closed-issues| |open-prs| |closed-prs|
|
||||
|
||||
.. |contributors| image:: https://img.shields.io/github/contributors/bastibe/python-soundfile.svg
|
||||
.. |version| image:: https://img.shields.io/pypi/v/soundfile.svg
|
||||
.. |python| image:: https://img.shields.io/pypi/pyversions/soundfile.svg
|
||||
.. |license| image:: https://img.shields.io/github/license/bastibe/python-soundfile.svg
|
||||
.. |downloads| image:: https://img.shields.io/pypi/dm/soundfile.svg
|
||||
.. |open-issues| image:: https://img.shields.io/github/issues/bastibe/python-soundfile.svg
|
||||
.. |closed-issues| image:: https://img.shields.io/github/issues-closed/bastibe/python-soundfile.svg
|
||||
.. |open-prs| image:: https://img.shields.io/github/issues-pr/bastibe/python-soundfile.svg
|
||||
.. |closed-prs| image:: https://img.shields.io/github/issues-pr-closed/bastibe/python-soundfile.svg
|
||||
.. |status| image:: https://img.shields.io/pypi/status/soundfile.svg
|
||||
|
||||
Breaking Changes
|
||||
----------------
|
||||
|
||||
The ``soundfile`` module has evolved rapidly in the past. Most
|
||||
notably, we changed the import name from ``import pysoundfile`` to
|
||||
``import soundfile`` in 0.7. In 0.6, we cleaned up many small
|
||||
inconsistencies, particularly in the the ordering and naming of
|
||||
function arguments and the removal of the indexing interface.
|
||||
|
||||
In 0.8.0, we changed the default value of ``always_2d`` from ``True``
|
||||
to ``False``. Also, the order of arguments of the ``write`` function
|
||||
changed from ``write(data, file, ...)`` to ``write(file, data, ...)``.
|
||||
|
||||
In 0.9.0, we changed the ``ctype`` arguments of the ``buffer_*``
|
||||
methods to ``dtype``, using the Numpy ``dtype`` notation. The old
|
||||
``ctype`` arguments still work, but are now officially deprecated.
|
||||
|
||||
In 0.12.0, we changed the load order of the libsndfile library. Now,
|
||||
the packaged libsndfile in the platform-specific wheels is tried
|
||||
before falling back to any system-provided libsndfile. If you would
|
||||
prefer using the system-provided libsndfile, install the source
|
||||
package or source wheel instead of the platform-specific wheels.
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
The ``soundfile`` module depends on the Python packages CFFI and NumPy, and the
|
||||
library libsndfile.
|
||||
|
||||
In a modern Python, you can use ``pip install soundfile`` to download
|
||||
and install the latest release of the ``soundfile`` module and its
|
||||
dependencies. On Windows (64/32) and OS X (Intel/ARM) and Linux 64,
|
||||
this will also install a current version of the library libsndfile. If
|
||||
you install the source module, you need to install libsndfile using
|
||||
your distribution's package manager, for example ``sudo apt install
|
||||
libsndfile1``.
|
||||
|
||||
If you are running on an unusual platform or if you are using an older
|
||||
version of Python, you might need to install NumPy and CFFI separately,
|
||||
for example using the Anaconda_ package manager.
|
||||
|
||||
.. _Anaconda: https://www.continuum.io/downloads
|
||||
|
||||
Building
|
||||
--------
|
||||
|
||||
``Soundfile`` itself does not contain any compiled code and can be
|
||||
bundled into a wheel with the usual ``python setup.py bdist_wheel``.
|
||||
However, ``soundfile`` relies on libsndfile, and optionally ships its
|
||||
own copy of libsndfile in the wheel.
|
||||
|
||||
To build a binary wheel that contains libsndfile, make sure to
|
||||
checkout and update the ``_soundfile_data`` submodule, then run
|
||||
``python setup.py bdist_wheel`` as usual. If the resulting file size
|
||||
of the wheel is around one megabyte, a matching libsndfile has been
|
||||
bundled (without libsndfile, it's around 25 KB).
|
||||
|
||||
To build binary wheels for all supported platforms, run ``python
|
||||
build_wheels.py``, which will ``python setup.py bdist_wheel`` for each
|
||||
of the platforms we have precompiled libsndfiles for.
|
||||
|
||||
Error Reporting
|
||||
---------------
|
||||
|
||||
In case of API usage errors the ``soundfile`` module raises the usual `ValueError` or `TypeError`.
|
||||
|
||||
For other errors `SoundFileError` is raised (used to be `RuntimeError`).
|
||||
Particularly, a `LibsndfileError` subclass of this exception is raised on
|
||||
errors reported by the libsndfile library. In that case the exception object
|
||||
provides the libsndfile internal error code in the `LibsndfileError.code` attribute and the raw
|
||||
libsndfile error message in the `LibsndfileError.error_string` attribute.
|
||||
|
||||
Read/Write Functions
|
||||
--------------------
|
||||
|
||||
Data can be written to the file using `soundfile.write()`, or read from
|
||||
the file using `soundfile.read()`. The ``soundfile`` module can open all file formats
|
||||
that `libsndfile supports
|
||||
<http://www.mega-nerd.com/libsndfile/#Features>`__, for example WAV,
|
||||
FLAC, OGG and MAT files (see `Known Issues <https://github.com/bastibe/python-soundfile#known-issues>`__ below about writing OGG files).
|
||||
|
||||
Here is an example for a program that reads a wave file and copies it
|
||||
into an FLAC file:
|
||||
|
||||
.. code:: python
|
||||
|
||||
import soundfile as sf
|
||||
|
||||
data, samplerate = sf.read('existing_file.wav')
|
||||
sf.write('new_file.flac', data, samplerate)
|
||||
|
||||
Block Processing
|
||||
----------------
|
||||
|
||||
Sound files can also be read in short, optionally overlapping blocks
|
||||
with `soundfile.blocks()`.
|
||||
For example, this calculates the signal level for each block of a long
|
||||
file:
|
||||
|
||||
.. code:: python
|
||||
|
||||
import numpy as np
|
||||
import soundfile as sf
|
||||
|
||||
rms = [np.sqrt(np.mean(block**2)) for block in
|
||||
sf.blocks('myfile.wav', blocksize=1024, overlap=512)]
|
||||
|
||||
``SoundFile`` Objects
|
||||
---------------------
|
||||
|
||||
Sound files can also be opened as `SoundFile` objects. Every
|
||||
`SoundFile` has a specific sample rate, data format and a set number of
|
||||
channels.
|
||||
|
||||
If a file is opened, it is kept open for as long as the `SoundFile`
|
||||
object exists. The file closes when the object is garbage collected,
|
||||
but you should use the `SoundFile.close()` method or the
|
||||
context manager to close the file explicitly:
|
||||
|
||||
.. code:: python
|
||||
|
||||
import soundfile as sf
|
||||
|
||||
with sf.SoundFile('myfile.wav', 'r+') as f:
|
||||
while f.tell() < f.frames:
|
||||
pos = f.tell()
|
||||
data = f.read(1024)
|
||||
f.seek(pos)
|
||||
f.write(data*2)
|
||||
|
||||
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.
|
||||
|
||||
RAW Files
|
||||
---------
|
||||
|
||||
`soundfile.read()` can usually auto-detect the file type of sound files. This
|
||||
is not possible for RAW files, though:
|
||||
|
||||
.. code:: python
|
||||
|
||||
import soundfile as sf
|
||||
|
||||
data, samplerate = sf.read('myfile.raw', channels=1, samplerate=44100,
|
||||
subtype='FLOAT')
|
||||
|
||||
Note that on x86, this defaults to ``endian='LITTLE'``. If you are
|
||||
reading big endian data (mostly old PowerPC/6800-based files), you
|
||||
have to set ``endian='BIG'`` accordingly.
|
||||
|
||||
You can write RAW files in a similar way, but be advised that in most
|
||||
cases, a more expressive format is better and should be used instead.
|
||||
|
||||
Virtual IO
|
||||
----------
|
||||
|
||||
If you have an open file-like object, `soundfile.read()` can open it just like
|
||||
regular files:
|
||||
|
||||
.. code:: python
|
||||
|
||||
import soundfile as sf
|
||||
with open('filename.flac', 'rb') as f:
|
||||
data, samplerate = sf.read(f)
|
||||
|
||||
Here is an example using an HTTP request:
|
||||
|
||||
.. code:: python
|
||||
|
||||
import io
|
||||
import soundfile as sf
|
||||
from urllib.request import urlopen
|
||||
|
||||
url = "http://tinyurl.com/shepard-risset"
|
||||
data, samplerate = sf.read(io.BytesIO(urlopen(url).read()))
|
||||
|
||||
Note that the above example only works with Python 3.x.
|
||||
For Python 2.x support, replace the third line with:
|
||||
|
||||
.. code:: python
|
||||
|
||||
from urllib2 import urlopen
|
||||
|
||||
In-memory files
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
Chunks of audio, i.e. `bytes`, can also be read and written without touching the filesystem.
|
||||
In the following example OGG is converted to WAV entirely in memory (without writing files to the disk):
|
||||
|
||||
.. code:: python
|
||||
|
||||
import io
|
||||
import soundfile as sf
|
||||
|
||||
def ogg2wav(ogg: bytes):
|
||||
ogg_buf = io.BytesIO(ogg)
|
||||
ogg_buf.name = 'file.ogg'
|
||||
data, samplerate = sf.read(ogg_buf)
|
||||
wav_buf = io.BytesIO()
|
||||
wav_buf.name = 'file.wav'
|
||||
sf.write(wav_buf, data, samplerate)
|
||||
wav_buf.seek(0) # Necessary for `.read()` to return all bytes
|
||||
return wav_buf.read()
|
||||
|
||||
Controlling bitrate mode and compression level
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
For some audio formats, you can control the bitrate and compression level.
|
||||
|
||||
`compression_level` is a float between 0 and 1, with 1 being the highest compression,
|
||||
and `bitrate_mode` is 'VARIABLE', 'CONSTANT', or 'AVERAGE'.
|
||||
|
||||
.. code:: python
|
||||
|
||||
import soundfile as sf
|
||||
|
||||
# for example, this uncompressed 5 minute wav file with 32 kHz sample rate is 18 Mb
|
||||
data, samplerate = sf.read('5min_32kHz.wav')
|
||||
|
||||
# maximum mp3 compression results in 1.1 Mb file, with either CONSTANT or VARIABLE bit rate
|
||||
sf.write('max_compression_vbr.mp3', data, samplerate, bitrate_mode='VARIABLE', compression_level=.99)
|
||||
sf.write('max_compression_cbr.mp3', data, samplerate, bitrate_mode='CONSTANT', compression_level=.99)
|
||||
|
||||
# minimum mp3 compression results in 3.5 Mb file
|
||||
sf.write('min_compression_vbr.mp3', data, samplerate, bitrate_mode='VARIABLE', compression_level=0)
|
||||
|
||||
Known Issues
|
||||
------------
|
||||
|
||||
Writing to OGG files can result in empty files with certain versions of libsndfile. See `#130 <https://github.com/bastibe/python-soundfile/issues/130>`__ for news on this issue.
|
||||
|
||||
If using a Buildroot style system, Python has trouble locating ``libsndfile.so`` file, which causes python-soundfile to not be loaded. This is apparently a bug in `python <https://bugs.python.org/issue13508>`__. For the time being, in ``soundfile.py``, you can remove the call to ``_find_library`` and hardcode the location of the ``libsndfile.so`` in ``_ffi.dlopen``. See `#258 <https://github.com/bastibe/python-soundfile/issues/258>`__ for discussion on this issue.
|
||||
|
||||
News
|
||||
----
|
||||
|
||||
2013-08-27 V0.1.0 Bastian Bechtold:
|
||||
Initial prototype. A simple wrapper for libsndfile in Python
|
||||
|
||||
2013-08-30 V0.2.0 Bastian Bechtold:
|
||||
Bugfixes and more consistency with PySoundCard
|
||||
|
||||
2013-08-30 V0.2.1 Bastian Bechtold:
|
||||
Bugfixes
|
||||
|
||||
2013-09-27 V0.3.0 Bastian Bechtold:
|
||||
Added binary installer for Windows, and context manager
|
||||
|
||||
2013-11-06 V0.3.1 Bastian Bechtold:
|
||||
Switched from distutils to setuptools for easier installation
|
||||
|
||||
2013-11-29 V0.4.0 Bastian Bechtold:
|
||||
Thanks to David Blewett, now with Virtual IO!
|
||||
|
||||
2013-12-08 V0.4.1 Bastian Bechtold:
|
||||
Thanks to Xidorn Quan, FLAC files are not float32 any more.
|
||||
|
||||
2014-02-26 V0.5.0 Bastian Bechtold:
|
||||
Thanks to Matthias Geier, improved seeking and a flush() method.
|
||||
|
||||
2015-01-19 V0.6.0 Bastian Bechtold:
|
||||
A big, big thank you to Matthias Geier, who did most of the work!
|
||||
|
||||
- Switched to ``float64`` as default data type.
|
||||
- Function arguments changed for consistency.
|
||||
- Added unit tests.
|
||||
- Added global `read()`, `write()`, `blocks()` convenience
|
||||
functions.
|
||||
- Documentation overhaul and hosting on readthedocs.
|
||||
- Added ``'x'`` open mode.
|
||||
- Added `tell()` method.
|
||||
- Added ``__repr__()`` method.
|
||||
|
||||
2015-04-12 V0.7.0 Bastian Bechtold:
|
||||
Again, thanks to Matthias Geier for all of his hard work, but also
|
||||
Nils Werner and Whistler7 for their many suggestions and help.
|
||||
|
||||
- Renamed ``import pysoundfile`` to ``import soundfile``.
|
||||
- Installation through pip wheels that contain the necessary
|
||||
libraries for OS X and Windows.
|
||||
- Removed ``exclusive_creation`` argument to `write()`.
|
||||
- Added `truncate()` method.
|
||||
|
||||
2015-10-20 V0.8.0 Bastian Bechtold:
|
||||
Again, Matthias Geier contributed a whole lot of hard work to this
|
||||
release.
|
||||
|
||||
- Changed the default value of ``always_2d`` from ``True`` to
|
||||
``False``.
|
||||
- Numpy is now optional, and only loaded for ``read`` and
|
||||
``write``.
|
||||
- Added `SoundFile.buffer_read()` and
|
||||
`SoundFile.buffer_read_into()` and `SoundFile.buffer_write()`,
|
||||
which read/write raw data without involving Numpy.
|
||||
- Added `info()` function that returns metadata of a sound file.
|
||||
- Changed the argument order of the `write()` function from
|
||||
``write(data, file, ...)`` to ``write(file, data, ...)``
|
||||
|
||||
And many more minor bug fixes.
|
||||
|
||||
2017-02-02 V0.9.0 Bastian Bechtold:
|
||||
Thank you, Matthias Geier, Tomas Garcia, and Todd, for contributions
|
||||
for this release.
|
||||
|
||||
- Adds support for ALAC files.
|
||||
- Adds new member ``__libsndfile_version__``
|
||||
- Adds number of frames to ``info`` class
|
||||
- Adds ``dtype`` argument to ``buffer_*`` methods
|
||||
- Deprecates ``ctype`` argument to ``buffer_*`` methods
|
||||
- Adds official support for Python 3.6
|
||||
|
||||
And some minor bug fixes.
|
||||
|
||||
2017-11-12 V0.10.0 Bastian Bechtold:
|
||||
Thank you, Matthias Geier, Toni Barth, Jon Peirce, Till Hoffmann,
|
||||
and Tomas Garcia, for contributions to this release.
|
||||
|
||||
- Should now work with cx_freeze.
|
||||
- Several documentation fixes in the README.
|
||||
- Removes deprecated ``ctype`` argument in favor of ``dtype`` in ``buffer_*()``.
|
||||
- Adds `SoundFile.frames` in favor of now-deprecated ``__len__()``.
|
||||
- Improves performance of `blocks()` and `SoundFile.blocks()`.
|
||||
- Improves import time by using CFFI's out of line mode.
|
||||
- Adds a build script for building distributions.
|
||||
|
||||
2022-06-02 V0.11.0 Bastian Bechtold:
|
||||
Thank you, tennies, Hannes Helmholz, Christoph Boeddeker, Matt
|
||||
Vollrath, Matthias Geier, Jacek Konieczny, Boris Verkhovskiy,
|
||||
Jonas Haag, Eduardo Moguillansky, Panos Laganakos, Jarvy Jarvison,
|
||||
Domingo Ramirez, Tim Chagnon, Kyle Benesch, Fabian-Robert Stöter,
|
||||
Joe Todd
|
||||
|
||||
- MP3 support
|
||||
- Adds binary wheels for macOS M1
|
||||
- Improves compatibility with macOS, specifically for M1 machines
|
||||
- Fixes file descriptor open for binary wheels on Windows and Python 3.5+
|
||||
- Updates libsndfile to v1.1.0
|
||||
- Adds get_strings method for retrieving all metadata at once
|
||||
- Improves documentation, error messages and tests
|
||||
- Displays length of very short files in samples
|
||||
- Supports the file system path protocol (pathlib et al)
|
||||
|
||||
2023-02-02 V0.12.0 Bastian Bechtold
|
||||
Thank you, Barabazs, Andrew Murray, Jon Peirce, for contributions
|
||||
to this release.
|
||||
|
||||
- Updated libsndfile to v1.2.0
|
||||
- Improves precompiled library location, especially with py2app or cx-freeze.
|
||||
- Now provide binary wheels for Linux x86_64
|
||||
- Now prefers packaged libsndfile over system-installed libsndfile
|
||||
|
||||
2023-02-15 V0.12.1 Bastian Bechtold
|
||||
Thank you, funnypig, for the bug report
|
||||
|
||||
- Fixed typo on library location detection if no packaged lib and
|
||||
no system lib was found
|
||||
|
||||
2025-01-02 V0.13.0 Bastian Bechtold
|
||||
Thank you, Zhong Jianxin, mcclure, jneuendorf-i4h, aoirint, endolith, Guy Illes, ytya, Sam Lapp, Benjamin Moody
|
||||
|
||||
- Updated libsndfile to v1.2.2
|
||||
- Linux arm64 builds added
|
||||
- Numpy is now a dependency
|
||||
- Fixed error in blocks, if file is very short
|
||||
- Compression level and bitrate controls added for compressed files
|
||||
- Various README improvements
|
||||
- Various build system improvements
|
||||
- Various improvements to error messages
|
||||
|
||||
2025-01-25 V0.13.1 Bastian Bechtold
|
||||
Thank you, Brian McFee and Guy Illes
|
||||
|
||||
- Fixed regression in blocks
|
||||
Reference in New Issue
Block a user