Skip to main content

Extended WAVE I/O

Project description

## ewave

Pure python support for reading and writing extended WAVE formats.

The wave module in Python's standard library is old and doesn't support a number
of useful formats and encodings, notably IEEE floats. Ewave is a small, simple
solution written in pure Python that provides a number of enhanced features:

- Floating point formats
- Extensible formats (> 2 channels, larger bit depths)
- Read and write using memory mapping for simple, speedy access to large files
- Read directly to numpy arrays
- Data appended to existing files in read/write modes can be immediately accessed
- Rescaling of data for different encodings and bit depths
- Supports Python context managers for cleaner resource semantics

### Requirements and installation

Ewave requires Python 2.6+ or 3.2+ and numpy 1.0+.

To install, run `python setup.py install` in the source directory, or
`pip install ewave`. Because numpy is a large installation, it's not installed
automatically; run `pip install numpy` if you don't already have it.

### Usage

There are some notable differences between the ewave interface and the standard
library wave module. There's only a single class that manages both reading and
writing, and a number of the properties have changed names and behaviors.
Importantly, the read method by default returns a numpy memmap to the data in
the file. This provides faster access to large files and allows writing data in
place.

For example, to write a second of stereo white noise in floating point format
and then rescale it in place:

```python
import ewave
from numpy import random
data = random.randn(48000,2)
with ewave.open("myfile.wav","w+",sampling_rate=48000,dtype='f',nchannels=2) as fp:
fp.write(data)
# rescale the data by 50%
fp.read(memmap='r+') *= 0.5
```

### Testing

Ewave has been tested on a large number of different WAVE formats and comes with
a fairly extensive unit test suite. To run unit tests on files, place them in
the 'test' subdirectory and run `nosetests`. You can also place unsupported or
invalid files in the 'unsupported' directory to test whether ewave rejects them
correctly. Bug reports are always appreciated.

### Limitations and related projects

'Exotic' encodings like A-law and mu-law are not supported. Formats in which
the container size (the bit depth) does not align with a native data type,
including some 24-bit formats, are not supported. Data cannot be appended to
files that terminate in something other than a data chunk, and multiple data
chunks are not supported.

Users interested in access to more complex WAVE and non-WAVE files and who do not
mind external library dependencies should consider one of these wrappers to
libsndfile:

- <http://code.google.com/p/libsndfile-python/>
- <http://www.ar.media.kyoto-u.ac.jp/members/david/softwares/audiolab/>

### Licence and acknowledgements

Ewave is based heavily on the original wave module in the Python standard
library and is released under the same Python Software Foundation Licence
(<http://opensource.org/licenses/python-2.0>)

Information about the WAVE formats supported by this module was extensively
gleaned from
<http://www-mmsp.ece.mcgill.ca/documents/audioformats/wave/wave.html>.

[![Build Status](https://travis-ci.org/melizalab/py-ewave.png?branch=master)](https://travis-ci.org/melizalab/py-ewave)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ewave-1.0.4.tar.gz (8.8 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page