Skip to main content

Wandas

English | 日本語

PyPI CI codecov MIT License Python Version

Signal analysis that feels like working with a data frame.

Wandas is a Python library that treats audio, vibration and sensor waveforms as one frame (ChannelFrame) that carries the sampling rate, channel names, units and processing history. Reading, preprocessing, frequency analysis and plotting are written as a method chain.

import wandas as wd

x = wd.read("https://raw.githubusercontent.com/kasahart/wandas/main/learning-path/sample_audio.wav", end=15)  # first 15 s
x.describe()                                               # waveform, spectrogram and spectrum at a glance
x.remove_dc().high_pass_filter(cutoff=100).welch().plot()  # preprocess, then a Welch spectrum

Wandas describe() output

Why Wandas

With NumPy and SciPy alone, you keep track of the sampling rate, channel names, units and "what was done" yourself.

# NumPy / SciPy: you carry the array and the sampling rate yourself
import scipy.signal

a, fs = x.data, x.sampling_rate
sos = scipy.signal.butter(4, 100, "highpass", fs=fs, output="sos")
y_np = scipy.signal.sosfiltfilt(sos, a - a.mean(axis=-1, keepdims=True))

# Wandas: the same 4th-order zero-phase Butterworth
y = x.remove_dc().high_pass_filter(cutoff=100)
y.operation_history  # [{'operation': 'wandas.audio.remove_dc', ...}, ...]
  • Methods never change the original frame; each returns a new one, and the processing history stays on the result.
  • A processing chain can be saved and re-applied to another recording (RecipePlan).

What you can do

Area Main features
Input WAV / FLAC / OGG / MP3 / CSV, URLs, NumPy arrays
Preprocessing DC removal, high/low/band-pass, A-weighting, resampling, trimming
Levels Per-channel calibration, RMS, dB SPL
Frequency analysis FFT, Welch, STFT, 1/N-octave bands, coherence, transfer functions
Psychoacoustics Loudness, roughness, sharpness (via MoSQITo)
Many files Build a recording list from folders or CSV and process it in one go
Browser Core processing and WAV in the browser with Pyodide, without a local Python install

Installation

pip install wandas
pip install "wandas[marimo]"          # audio playback in describe() on Jupyter / marimo
pip install "wandas[psychoacoustic]"  # psychoacoustic metrics
pip install "wandas[io]"              # WDF save and load
pip install "wandas[effects]"         # librosa-backed audio effects
pip install "wandas[ml]"              # PyTorch / TensorFlow tensor conversion

Check with a known signal

Add a DC offset to 750 Hz and 1500 Hz tones, then remove the DC and apply a 1 kHz low-pass filter.

import numpy as np
import wandas as wd

sr = 48_000
t = np.arange(sr) / sr
samples = 0.25 + 0.20 * np.sin(2 * np.pi * 750 * t) + 0.05 * np.sin(2 * np.pi * 1500 * t)

signal = wd.from_numpy(samples, sampling_rate=sr, ch_labels=["Original"], ch_units="Pa")
processed = signal.remove_dc().low_pass_filter(cutoff=1_000).rename_channels({0: "After DC removal + 1 kHz low-pass"})

comparison = signal.concat_frame(processed)
comparison.plot(overlay=True, xlim=(0, 0.02))
comparison.fft().plot(overlay=True, xlim=(0, 4_000)).set_ylim(30, 90)  # amplitude level, dB re 20 µPa

Overlaid waveforms of the original and processed signal

Overlaid FFT spectra of the original and processed signal

The 750 Hz tone stays and the 1500 Hz tone is attenuated.

Work with many files

import wandas as wd

# recordings/
# ├── label=ok/  a.wav, b.wav, ...
# └── label=ng/  c.wav, d.wav, ...
dataset = wd.from_folder("recordings/", recursive=True, path_metadata=True)
ok = dataset.select(label="ok")
spectra = ok.trim(0, 5).resample(16_000).stft(n_fft=512)  # first 5 s
spectra[0].data  # NumPy array (channel, frequency, time); mono has no channel axis

from_folder() and select() do not open any audio file, so selection stays fast even for many files. Each recording is read and computed only when you take a result out, such as spectra[0].

Learn more

License

MIT License. Bug reports and ideas are welcome in the issue tracker.

Metadata

Release files for wandas 0.13.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for wandas 0.13.1
File Size Uploaded Provenance Actions
wandas-0.13.1.tar.gz 5.7 MB Without provenance Details for wandas-0.13.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for wandas 0.13.1
File Interpreter ABI Platform Actions
wandas-0.13.1-py3-none-any.whl Python 3 none any Details for wandas-0.13.1-py3-none-any.whl

Total release size: 6.1 MB

Release files / wandas-0.13.1.tar.gz

Download URL wandas-0.13.1.tar.gz
Size 5.7 MB
Tags Source
SHA-256 checksum
How to use checksums
61ce459f31215f9884ab4f251de2f58fdbf3d0bab7799818d9b2dd74926276dc
BLAKE2b-256 checksum
How to use checksums
e305d60602a5c0983d9701efb5f113469bbd496e5b7d94bd40e9e40134d7ddf4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / wandas-0.13.1-py3-none-any.whl

Download URL wandas-0.13.1-py3-none-any.whl
Size 354.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
af24df0342fb0d39fc9c0351549c0673d2bfa8d15e5eb252bc2269a4d915a53f
BLAKE2b-256 checksum
How to use checksums
ae392de3cc40acc6f09ea5e77b6f26e03e7bb08cbf4f49760d4097169794a0bf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for wandas 0.13.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.13.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page