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.2

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.2
File Size Uploaded Provenance Actions
wandas-0.13.2.tar.gz 5.8 MB Without provenance Details for wandas-0.13.2.tar.gz

Built distribution (wheel)

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

Total release size: 6.1 MB

Release files / wandas-0.13.2.tar.gz

Download URL wandas-0.13.2.tar.gz
Size 5.8 MB
Tags Source
SHA-256 checksum
How to use checksums
156228851c4bda935c4b4c8b0ae169ab1e6b5b2a1046b196c2f0f94606073ead
BLAKE2b-256 checksum
How to use checksums
a2a239a7c93b9253a209846a3f8f69025b6f4eb904891bf443089f7d7c961925
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.2-py3-none-any.whl

Download URL wandas-0.13.2-py3-none-any.whl
Size 366.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d6e63c3bc91eb2f9621653c7b8bdbf20263c6bc960b9580cf35f76da07ccc893
BLAKE2b-256 checksum
How to use checksums
8b309bda52fbc98e2db2406d18464b0991387985694495659cfc799768a2467b
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.2

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.2 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