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

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.0
File Size Uploaded Provenance Actions
wandas-0.13.0.tar.gz 5.7 MB Without provenance Details for wandas-0.13.0.tar.gz

Built distribution (wheel)

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

Total release size: 6.1 MB

Release files / wandas-0.13.0.tar.gz

Download URL wandas-0.13.0.tar.gz
Size 5.7 MB
Tags Source
SHA-256 checksum
How to use checksums
fbef64a63dada7c84b1bfbdf41eff5cefbf24f47d52cd93fef387dde81afea1b
BLAKE2b-256 checksum
How to use checksums
204554ad1b08a9805061e61e910a88381184331db4b98322d9bf97b73f40fe86
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.0-py3-none-any.whl

Download URL wandas-0.13.0-py3-none-any.whl
Size 354.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a808ab91777ce446091fb1e5c7f181948f669c8f725b0d4b22de4e767cf7c02c
BLAKE2b-256 checksum
How to use checksums
a8225a73f7c79fce1bccab2733fd8072fcfaa91c4eed91f17bd240af365cd478
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.0

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