Signals and stimuli for auditory research, built for Jupyter.

sonore is a small Python library for making, manipulating, and analyzing sounds the way hearing scientists think about them. Its analysis and synthesis tools cover tones, harmonic complexes, shaped and correlated noises, ERB-spaced subbands, invertible spectrograms, a phase vocoder, interaural cues, HRIR spatialization of moving sources, synthetic room reverberation, and sound texture synthesis. Levels are written as levels (snd + 6*dB), times as seconds (snd[0.1:0.5]), and any sound at the end of a notebook cell plays.

It brings the sounds and representations of hearing research together in one coherent system, held to the following standard: every frame inverts exactly, the mathematics in its design documents is checked by standalone scripts and the code by its tests, and every example in the gallery can be heard beside the code that made it. It is built to learn from and to build on.

The name comes from Pierre Schaeffer's objet sonore, the "sound object": a sound taken as a thing in its own right and studied for how it is heard rather than for what produced it. The Sound object at the center of this library is meant in the same spirit. The logo is drawn from the spectrogram of sonore saying its own name with a formant synthesizer.

▶ Listen to the gallery: every sound in this README and more, each playable next to its plots, with a playhead that follows the sound.

▶ Try it in your browser: one editable cell that runs sonore on the page, through Pyodide, with nothing to install.

▶ Draw sounds with sonore-sketch: draw speech, paint a spectrogram or draw a modulation spectrum with a mouse, or erase parts of a recording's spectrogram or modulation spectrum, and hear what sonore makes of it, in your browser.

A short tutorial you can run in the browser, with nothing to install: sounds, classic and complex stimuli, sound textures, voices, and spatial hearing with reverberation and movement.

sonore is a library under active development and verification. Until version 1.0, its API may change between releases without warning, and it has not yet been fully validated for research use. Please check anything you rely on against an independent implementation.

What it's for

• Psychophysical stimuli. Pure tones, harmonic complexes with any phase scheme (cosine, sine, alternating, random, Schroeder±), band-limited square, sawtooth and pulse trains, all on a fixed F0 or following any F0 contour (an F0Track, or window times and values) without aliasing, chirps, band-limited and spectrally tilted noise, iterated rippled noise. Everything is reproducible from a seed.
• Binaural and spatial hearing. Exact fractional ITDs, ILDs, interaurally correlated noise, Oscor and Phasewarp, windowed ITD/ILD/coherence analysis (broadband or per band), and rendering of static or moving sources through measured HRIRs (PKU-IOA, downloaded on first use, or any SOFA file), with each ear's delay sliding continuously so a source can change distance (level, travel time, Doppler) in a room.
• Synthetic speech. A Klatt-style cascade/parallel formant synthesizer (Klatt, 1980) driven by named parameter tracks (F0, formant frequencies and bandwidths, voicing, aspiration and frication levels), for vowels, consonant continua and breathy voice with every acoustic cue set exactly.
• Speech in noise. Speech-shaped noise from a long-term average spectrum, mixing at a target SNR, ideal binary and ratio masks with exact resynthesis.
• Cochlear-implant and envelope/TFS studies. A perfect-reconstruction ERB filterbank, Hilbert envelopes and fine structure, and a channel vocoder.
• Spectrotemporal modulation. Moving ripples, sums of ripples, and dynamic moving ripples, specified as patterns in time and log-frequency and rendered on tone, harmonic, noise, or low-noise carriers (or any sound's fine structure), plus a modulation spectrum in cycles/octave to verify them.
• Time and pitch manipulation. A phase vocoder (Gordon & Strawn, 1985) with phase locking: time-stretch without changing pitch, pitch-shift without changing duration, and oscillator-bank resynthesis with arbitrary frequency remapping (e.g. shifting a harmonic complex to make it inharmonic).
• Rooms. Synthetic impulse responses with frequency-dependent decay from the statistics of real rooms (Traer & McDermott, 2016), with a controllable DRR and decorrelated binaural tails, plus the paper's "unnatural" variants (time-reversed and linear decays; inverted, exaggerated and reduced frequency dependence) and a per-band RT60 measurement.
• Sound textures. The texture model of McDermott & Simoncelli (2011): measure a recording's envelope, modulation and correlation statistics, and synthesize new samples that share them. A clean-room implementation with analytic gradients; every deviation from the MATLAB toolbox is documented (so.texture.DIFFERENCES_FROM_TOOLBOX).
• Teaching and demos. One-call overview plots (waveform, spectrum, spectrogram, modulation spectrum) next to an audio player.

sonore is not an experiment runner, does not calibrate to dB SPL, and has no models of the ear or of perception; see "Related projects" below for those.

Install

pip install "sonore[notebook]"   # extras: sofa (HRIR files), play (sounddevice), dev (tests)

or, for the development version:

git clone https://github.com/choyun1/sonore
cd sonore
pip install -e ".[notebook]"

Requires Python ≥ 3.11, numpy, scipy ≥ 1.12, matplotlib, and soundfile.

A first cell in a notebook:

import sonore as so
from sonore import dB

fs = 44100
tone = so.pure_tone(0.5, fs, 1000).ramp(10e-3) - 20 * dB
noise = so.gaussian_noise(0.5, fs, rng=0).ramp(10e-3) - 20 * dB
tone_in_noise = tone + (noise + 5 * dB)  # the tone at -5 dB SNR
so.overview(tone_in_noise)
tone_in_noise  # a Sound at the end of a cell plays

Gallery

The listening gallery has every sound beside plots of the same audio, with a playhead that follows it, and the code for each example. Three of the kinds of plot sonore draws:

Spectrograms. One sentence, read by a male and a female talker, through a wideband (5 ms) and a narrowband (33 ms) Gabor frame: the first resolves the glottal pulses, the second the harmonics. ▶ listen

Cepstrum. The cepstrogram of the same sentence for each talker, with so.Cepstrum's F0 beside WORLD's Harvest. ▶ listen

Modulation spectra. Three ripple patterns as specified (top), the synthesized sounds' subband envelopes (middle), and their measured so.ModulationSpectrum (bottom), which peaks at each specified rate and density. ▶ single ▶ sum of two ▶ dynamic

More in the gallery:

Stimuli

• Synthetic sounds: speech-shaped noise, beats, tone sequences, aliasing. ▶ speech-shaped noise
• Iterated rippled noise: a pitch made from noise and a delay. ▶ sixteen iterations
• Spectrotemporal ripples: moving ripples on different carriers. ▶ dynamic ripple
• Sound textures: syntheses from statistics (McDermott & Simoncelli, 2011). ▶ stream
• Sound quilts: recordings cut into segments and reordered (Overath et al., 2015). ▶ fire

Analysis and resynthesis

• Analysis and resynthesis: perfect reconstruction and the ideal binary mask. ▶ binary mask
• Phase vocoder: duration, pitch and partials changed independently. ▶ up a fifth

Voices

• Two talkers: the male and female talker every speech page uses. ▶ both
• Seeing speech: time-frequency analysis on one sentence. ▶ reassignment
• Formant synthesis: Klatt's synthesizer taken apart, and a sentence copied from its formants. ▶ copy
• Pitch tracking: three trackers, where each fails, and how the errors sound. ▶ buzz on the track
• Spectral envelope: timbre without pitch, and MFCCs. ▶ envelope only
• Source and aperiodicity: how much of a voice is noise. ▶ whispered
• Rebuilding and changing a voice: pitch and formants moved separately. ▶ one talker toward another

Envelopes and modulation

• Hearing through a vocoder: cochlear-implant simulation. ▶ sixteen bands
• Modulation spectrogram: how each band's envelope moves, moment by moment. ▶ speech, babble, noise
• Hearing a modulation spectrum: sounds made from a measured, edited or drawn modulation spectrum. ▶ rain with a sentence's timing

Spatial hearing (🎧 headphones)

• Binaural cues: timing and correlation between the ears, and height. ▶ over the head
• Rooms: distance, and rooms built from the statistics of real ones. ▶ time-reversed decay
• Moving talkers: talkers rendered through measured HRIRs. ▶ pass-by

Music

• Timbre: attack, brightness and spectral flux, measured.
• Tuning and temperament: just and tempered intervals, and Twinkle, Twinkle in four tunings. ▶ just intonation
• The pipe organ: stops as additive synthesis (a template).

Conventions

• Sounds. Sound = immutable (n_samples, n_channels) float array + fs. Operations return new Sounds.
• Arithmetic. a + b mixes, a * b multiplies sample-wise, 2 * a scales, mono broadcasts to stereo.
• Bands and envelopes. A filterbank's output (Subbands) is a collection of Sounds, and so is its fine structure (.tfs()). Envelopes are not sounds: Envelope and Envelopes are their own types, non-negative, often at a low sampling rate, and applied to sounds by multiplication. Envelopes (one envelope per band) is what the field calls a cochleagram. The Hilbert decomposition is literal: sb == sb.envelopes() * sb.tfs().
• Levels. a + 6*dB, a - 3*dB. Adding a bare number is an error, so it can't be mistaken for a DC offset. dB is always 20*log10(amplitude).
• Time. snd[0.1:0.5] slices by seconds; snd.data for samples.
• Randomness. Every stochastic function takes rng= (a seed or np.random.Generator).
• Binaural. Positive ITD = right ear leads; positive ILD = right ear louder.
• Space. Meters, head-centered, x = right, y = front, z = up. hcc = (distance cm, elevation °, azimuth ° clockwise from front).
• Threads. The large FFTs (filterbanks, Hilbert envelopes, resampling) use every available core. Results don't depend on it; when running several jobs in parallel, so.set_fft_workers(1) (also as a with block) keeps them from competing.
• Plots. Every plotting function takes an optional ax and returns it; global matplotlib settings are never touched.

What's in it

The folders follow meaning. core holds Sound and the processing that needs no analysis; sources makes sounds from parameters; frames are analyses with an exact inverse, and views are one-way analyses together with the routes back to sound they have (the channel vocoder, WORLD's synthesis, the phase vocoder); spatial and texture are topics built on those. Imports between modules never form a cycle, and core imports nothing above it at module level. plotting is called from every object's .plot(). docs/design/layout.md has the diagram. Most names are also at the top level as so.name; the texture ones are under so.texture and sonore.texture.synth.

Related projects

Where to go for what sonore leaves out:

• slab: calibrated levels in dB SPL, playback, trial sequences and adaptive staircases. Its sound making overlaps with sonore's, and the two share the same sample layout (samples × channels), so a sound passes between them in one line:

  s = slab.Sound(snd.data, samplerate=snd.fs)  # sonore to slab; then set s.level in dB SPL
  snd = so.Sound(s.data, s.samplerate)  # slab to sonore
  

  slab reads samples as pascals, so a sonore sound at RMS 1 shows as 94 dB SPL until you set its level.

• PsychoPy: running experiments.

• Auditory Modeling Toolbox (MATLAB/Octave) and torch_amt (PyTorch): models of the auditory system that predict what a listener hears.

• brian2hears: auditory periphery and spiking models.

• MoSQITo: loudness, sharpness, roughness and other sound quality metrics.

• Parselmouth (Praat in Python) and pyworld (WORLD): speech analysis and synthesis.

• librosa: music and audio analysis.

• pyroomacoustics: geometric room simulation.

• pyfar / sofar: acoustics and SOFA files.

• sonore-sketch (source): five tabs, each one of sonore's routes back to sound with a surface to draw on. Draw speech (formant tracks for the Klatt synthesizer), Paint spectrogram, Erase spectrogram (of a recording), Draw modulation (blobs on a modulation spectrum) and Erase modulation (of a recording). It runs sonore in the browser, with nothing to install.

Roadmap

Only work still to do is listed here. Finished items are in docs/roadmap-done.md, and changes by release in CHANGELOG.md.

Next

• Code audit. A line-by-line human read of src/sonore, one module per sitting, each closing the gaps in its tests; progress in issue #48.

Texture synthesis

• All channels at once. Impose the channels jointly; the per-channel objective is overhead-bound (about 2 s per iteration for 5 s of sound).
• Sparse pops. Fire-like recordings have pops whose sizes follow a power law (tail exponent about 1 to 1.6, measured on envelope peaks), so their envelope kurtosis has no stable value: in a 20 s fire recording it grows from about 220 over 1 s to about 1900 over 20 s. Neither sonore nor the MATLAB toolbox reproduces such recordings well. Open questions: a tail exponent as a texture statistic, and whether one event_train with power-law levels can give both the hiss and the pops.

Other

• The rest of KLSYN88's voice-quality controls (Klatt & Klatt, 1990) for the formant synthesizer: open quotient, spectral tilt, flutter, double pulsing, and its KLGLOTT88 source.
• A decimated, invertible constant-Q transform (nonstationary Gabor frames in frequency).
• Peak-based sinusoidal modeling (McAulay & Quatieri, 1986) alongside the channel oscillator bank.
• Routes back to sound from a sharpened time-frequency picture: a synchrosqueezed STFT (the coefficients moved in frequency only, so it stays exactly invertible) and partials tracked on the reassigned spectrogram, played by an oscillator bank (as in Fitz & Haken's Loris).
• On-demand download of other public HRIR databases.
• A block-by-block (streaming) modulation spectrogram, as the reference for a live version on a phone: the modulation spectrum of everyday sounds as they happen.

References

The works sonore implements, follows or cites are listed in docs/references.md, each with a link to the work, tags linking to the code that implements it, and the gallery pages that use it. The same page lists the reference implementations sonore was checked against or consulted.

Development

pip install -e ".[dev]"
pytest                             # ~40 s; one test file per module
ruff check . && ruff format .
python docs/gallery/build.py       # regenerate the listening gallery (a few minutes)

How sonore was developed

sonore began as sigtools, the code I (Adrian Cho) wrote in graduate school to make psychoacoustic stimuli (migrating from sigtools). The 0.2 redesign and everything since were developed together with Claude, Anthropic's AI assistant, in chat sessions during 2026.

What Claude did. Wrote most of the code, tests, documentation, and gallery since 0.2, delivered as patches; drafted design documents; ran numerical checks and profiling; and looked up and checked citations.

What I did. Decided what sonore is for and what goes in it, including its API conventions, the texture work and its milestones, and the roadmap and architecture. I chose and documented the texture recordings and set the working rules: implement from the papers, verify every claim numerically, document every deviation and data choice, and write a design document before large features. I reviewed and applied each patch. The design principles that came out of this are summarized in docs/design/philosophy.md.

How it is verified. I have not read every line by hand. What I rely on instead is the following:

• The test suite, with one file per module.
• Finite-difference and dense-matrix checks of the mathematics.
• Cross-checks against independent implementations (see "Reference implementations").
• Written records of every decision (DIFFERENCES_FROM_TOOLBOX, docs/textures/SOURCES.md, docs/design/).
• The listening gallery, since these are sounds and should be heard.

I am responsible for sonore's correctness. If something is wrong, please open an issue.

License and citation

MIT; see LICENSE. If sonore is useful in your research, please cite it using CITATION.cff; the Cite this repository button in the GitHub sidebar gives the same citation in APA and BibTeX.

Every release is archived on Zenodo. The all-versions DOI always points to the latest version. Each version also has its own DOI; cite the version you used.

• 0.6.0:
• 0.5.0:
• 0.4.0:
• 0.3.1: