Install & Compatibility
Where this runs
tested against v0.0.9 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.249s · 89.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.6s · import 0.260s · 86MB
89MB installed
● package 89MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
read
✓ wavio.read('file.wav')
✗ from wavio import read
The primary functions are typically accessed as attributes of the imported `wavio` module, e.g., `wavio.read` and `wavio.write`.
write
✓ wavio.write('file.wav', data, rate)
✗ from wavio import write
The primary functions are typically accessed as attributes of the imported `wavio` module, e.g., `wavio.read` and `wavio.write`.
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}")
Debug
Known issues
breakingThe 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.fixReview 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.
affects: <=0.0.4
gotchaWavio 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.fixAlways 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.
affects: All versions
deprecatedThe API of wavio functions is not considered stable, and backwards-incompatible changes may occur between releases.fixRefer to the GitHub release notes and PyPI project description for each new version to be aware of any changes.
affects: All versions
gotchaThe 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).fixEnsure your environment uses Python 3.10 or newer for `wavio` version 0.0.9. Older `wavio` versions may support earlier Python versions.
affects: <0.0.9 (pre-NumPy 2.0.0 support)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'wavio'
The `wavio` package has not been installed in the current Python environment.
TypeError: Data must be a NumPy array.
The `data` argument provided to `wavio.write` is not a NumPy array (e.g., it's a Python list or tuple).
fixConvert your data to a NumPy array using `numpy.array()` before passing it to `wavio.write`.
ValueError: Data must be 1D or 2D array
The input `data` array provided to `wavio.write` has more than two dimensions (e.g., 3D or higher), but `wavio` only supports 1D (mono) or 2D (stereo/multi-channel) arrays.
fixReshape your `data` array to be 1D (mono) or 2D (multi-channel, with channels as the second dimension) before passing it to `wavio.write`.
wave.Error: unknown format type
The WAV file being read is either compressed, corrupted, or not a standard uncompressed PCM WAV file, which `wavio` (and the underlying `wave` module) does not support.
fixEnsure the WAV file is an uncompressed PCM format. If you need to process compressed formats, use a different library like `pydub` or `soundfile`.
Upgrade
Version history
0.0.9latest on PyPI · released May 24, 2024
Audit
Dependencies
numpyrequiredRequired for array handling; version 1.21.3 or later recommended.