Wavio

0.0.9 · active · verified Wed Apr 15

Wavio is a Python module for reading and writing WAV files using NumPy arrays. It provides two main functions, `wavio.read` and `wavio.write`, for handling 8-, 16-, 24-, and 32-bit integer WAV files. It leverages Python's standard `wave` module and currently does not support compressed WAV files or direct floating-point WAV file output, converting floating-point input to integers. The current version is 0.0.9, with recent updates focusing on NumPy 2.0.0 compatibility.

Warnings

breaking The API for `wavio.write` changed in version 0.0.5, specifically how floating-point data is scaled. Code written for 0.0.4 or earlier may produce different audio or errors.
Fix: Review the `scale` and `sampwidth` parameters in the `wavio.write` documentation for `wavio` versions 0.0.5 and later to adjust your code. Floating-point inputs now require `sampwidth` to be explicitly given.
gotcha Wavio does not directly support floating-point WAV files or compressed WAV files. When writing floating-point data, it is converted to integers, and if `sampwidth` is not provided, default scaling is applied. Data clipping can occur and will generate a warning.
Fix: Always provide the `sampwidth` parameter when writing floating-point data to control the output bit depth. Be aware of the `scale` parameter in `wavio.write` (defaulting to `[-1.0, 1.0]` mapping to the full integer range) and check for clipping warnings.
deprecated The API of wavio functions is not considered stable, and backwards-incompatible changes may occur between releases.
Fix: Refer to the GitHub release notes and PyPI project description for each new version to be aware of any changes.
gotcha The library explicitly states that it requires Python 3.10 or later as of recent updates, which is a change from older versions that supported Python 3.7+ (and even 2.7 in much older releases).
Fix: Ensure your environment uses Python 3.10 or newer for `wavio` version 0.0.9. Older `wavio` versions may support earlier Python versions.

Install

pip install wavio Install wavio

Imports

wavio
```
import wavio
```
read
wrong:
```
from wavio import read
```
correct:
```
wavio.read('file.wav')
```
The primary functions are typically accessed as attributes of the imported `wavio` module, e.g., `wavio.read` and `wavio.write`.
write
wrong:
```
from wavio import write
```
correct:
```
wavio.write('file.wav', data, rate)
```
The primary functions are typically accessed as attributes of the imported `wavio` module, e.g., `wavio.read` and `wavio.write`.

Quickstart

This quickstart demonstrates how to generate a 3-second 440 Hz sine wave using NumPy and save it as a 24-bit WAV file, then read it back. It illustrates the basic usage of `wavio.write` and `wavio.read`.

import numpy as np
import wavio

# Parameters for the sine wave
rate = 22050  # samples per second
T = 3         # sample duration (seconds)
f = 440.0     # sound frequency (Hz)

# Create time array and sine wave data
t = np.linspace(0, T, int(T * rate), endpoint=False)
x = np.sin(2 * np.pi * f * t)

# Write the sine wave to a 24-bit WAV file
wavio.write("sine24.wav", x, rate, sampwidth=3)

# Read the WAV file back
wav_read = wavio.read("sine24.wav")
print(f"Read WAV file: {wav_read.filename}")
print(f"Sample rate: {wav_read.rate} Hz")
print(f"Sample width: {wav_read.sampwidth} bytes")
print(f"Data shape: {wav_read.data.shape}")

view raw JSON →