sonore

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.

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

A first tour you can run in the browser, with nothing to install: stimuli, spectrograms, the cepstrum, a phase vocoder, ripples and binaural cues.

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.10, numpy, scipy ≥ 1.12, matplotlib, and soundfile.

To try it without installing anything, open the starter notebook on Google Colab: its first cell installs sonore from PyPI.

A short tour

import sonore as so
from sonore import dB

fs = 44100

# Stimuli: every generator returns a Sound with RMS = 1
tone = so.pure_tone(0.5, fs, 1000).ramp(10e-3)
complex_ = so.harmonic_complex(0.5, fs, f0=200, harmonics=range(1, 21), phases="schroeder+")
noise = so.gaussian_noise(0.5, fs, band=(100, 8000), tilt=-3, rng=0)  # pink, band-limited

# Levels are dB units: + changes level, + with a Sound mixes
target_in_noise = tone + (noise + 5 * dB)  # tone at -5 dB SNR
quieter = complex_ - 12 * dB

# Time is in seconds
middle = target_in_noise[0.1:0.4]

# Binaural: positive ITD/ILD = toward the right
lateral = so.apply_itd_ild(noise, itd=300e-6, ild=6)
cues = so.interaural_cues(lateral, win_dur=20e-3)
cues.plot()

# Time and pitch (phase vocoder)
longer = so.time_stretch(complex_, 1.5)  # same pitch, 50% longer
up_a_fifth = so.pitch_shift(complex_, 7)  # same duration, +7 semitones

# Analysis
so.overview(target_in_noise)  # waveform, spectrum, spectrogram, modulation spectrum
target_in_noise  # in a notebook: an audio player

Every example in the gallery is a runnable script like this one, with its code shown beside the sound it makes.

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 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, 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

• Classic stimuli: ▶ speech-shaped noise, beats and roughness, and ▶ binaural beats 🎧.
• Iterated rippled noise: a pitch made from noise and a delay (Yost, 1996), from ▶ one iteration to ▶ sixteen.
• Spectrotemporal ripples: moving ripples on different carriers, and a ▶ dynamic moving ripple.
• Sound textures: recordings and their syntheses from statistics (McDermott & Simoncelli, 2011), such as a ▶ stream.

Seeing and changing sound

• Seeing speech: a short course in time-frequency analysis on one sentence, from ▶ window length to ▶ reassignment.
• Analysis and resynthesis: a filterbank's ▶ perfect reconstruction, and the ▶ ideal binary mask.
• Hearing through a vocoder: cochlear-implant simulation, from ▶ one band to ▶ sixteen.
• Modulation spectrogram: how fast and how deeply each band's envelope moves, moment by moment, from a ▶ gliding modulation rate to ▶ speech, babble and noise.
• Phase vocoder: how it works, and duration, pitch and partials changed independently, such as ▶ up a fifth.

Voices

• Formant synthesis: Klatt's synthesizer taken apart, from ▶ the source alone through ▶ five formants, then ▶ six vowels and ▶ /da/ from its formant transitions, and ▶ one vowel in three voices from LF glottal pulses.
• Cepstral analysis: separating a voice's pitch from its timbre, ▶ envelope only and ▶ harmonics only, and the same sentence as ▶ MFCCs.
• Voices from harmonics: a voice rebuilt from a pitch track and a spectral envelope, from ▶ a buzz on the pitch track to the ▶ full resynthesis, then ▶ up a fifth with the formants kept.
• Source, filter and aperiodicity: how much of a voice is noise, frequency by frequency, from ▶ a breathy vowel whose aperiodicity is known to the sentence ▶ rebuilt by WORLD's synthesis and ▶ whispered.
• Changing a voice: pitch and formants moved separately, from ▶ a higher pitch and ▶ higher formants to ▶ one talker toward another, with the pitch and the envelope from different analyses.

Spatial hearing

• Binaural cues 🎧: ▶ timing alone, and correlation that changes, such as ▶ Oscor.
• Synthetic reverberation: rooms built from the statistics of real ones (Traer & McDermott, 2016), from a ▶ natural room to ones that break the rules, such as a ▶ time-reversed decay.
• Moving talkers 🎧: three talkers rendered through measured HRIRs, ▶ one of them moving, a talker ▶ walking in, in a room, and a ▶ pass-by.

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.

Roadmap

What is planned comes first, in the order it will be done; finished work is listed at the end.

Next, in order

1. Release 0.4.0, with the moved import paths and the to_sound renames in its notes.
2. Texture modulation convergence. Rebalance the objective so modulation power converges (see Texture synthesis below).

Texture synthesis

• Rebalance the objective so modulation power converges (it reaches 30 dB SNR when imposed without the correlation classes, but 18-23 dB in full synthesis); try joint imposition of all channels.
• Impose several channels at once; the per-channel objective is overhead-bound (about 2 s per iteration for 5 s of sound).
• Validate against the MATLAB toolbox's published examples by running both on the same original recordings.

Architecture

• Folders follow meaning, and imports between modules never form a cycle; tests/test_layers.py keeps enforcing it. A voice is not a separate kind of sound, so there is no voice subpackage: synthesizers live in sources and analyses of a voice in views. Heavy dependencies go in optional extras.
• Split a component into its own distribution only when it needs a heavy dependency, a different release cadence, or a separate audience.
• Bayesian inference of sound sources will be a separate package built on sonore (JAX plus a probabilistic-programming layer), using sonore's generators, frames and texture statistics as its differentiable forward model.

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.
• Free-form modulation patterns: specify a modulation spectrum and synthesize it.
• A decimated, invertible constant-Q transform (nonstationary Gabor frames in frequency).
• Peak-based sinusoidal modeling (McAulay & Quatieri, 1986) alongside the channel oscillator bank.
• 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

Each entry is the citation and a link to the work: the DOI where one is confirmed, otherwise the publisher or another stable page. After it come tags naming the module(s) in What's in it that implement or follow the work, linked to the source: a tag such as representations.reassigned_spectrogram goes to that definition, a bare module name to the whole file. Last, set apart by a ·, are the gallery pages (▶) and roadmap items that cite it. Works with no tag are not implemented yet.

• Atlas & Shamma (2003). Joint acoustic and modulation frequency. EURASIP J. Appl. Signal Processing 2003(7). doi:10.1155/S1110865703305013. modspectrogram.ModulationSpectrogram.at · ▶ Modulation spectrogram
• Auger & Flandrin (1995). Improving the readability of time-frequency and time-scale representations by the reassignment method. IEEE Trans. Signal Processing 43(5). doi:10.1109/78.382394. reassigned.reassigned_spectrogram · ▶ Seeing speech
• Bagshaw, Hiller & Jack (1993). Enhanced pitch tracking and the processing of F0 contours for computer aided intonation teaching. Proc. Eurospeech 1993. CSTR, FDA database. Its laryngograph F0 is the reference in tools/check_f0_fda.py (data not in the repository). f0.f0_track
• Balazs, Dörfler, Jaillet, Holighaus & Velasco (2011). Theory, implementation and applications of nonstationary Gabor frames. J. Comput. Appl. Math. 236(6). doi:10.1016/j.cam.2011.09.011. gabor.TVGaborFrame
• Boersma & Weenink. Praat: doing phonetics by computer (computer program). praat.org. Cross-checks Cepstrum (see Reference implementations). · ▶ Cepstral analysis
• Bogert, Healy & Tukey (1963). The quefrency alanysis of time series for echoes: cepstrum, pseudo-autocovariance, cross-cepstrum and saphe cracking. In M. Rosenblatt (ed.), Time Series Analysis, Wiley. Semantic Scholar. cepstrum.Cepstrum · ▶ Cepstral analysis
• Brandtsegg, Saue & Lazzarini (2018). Live convolution with time-varying filters. Applied Sciences 8(1), 103. MDPI. Reviews the ways of filtering with a changing filter; move_sound is one of them. spatialization.move_sound · ▶ Moving talkers · Roadmap
• Byrne et al. (1994). An international comparison of long-term average speech spectra. JASA 96(4), 2108–2120. doi:10.1121/1.410152. spectrum.long_term_spectrum · ▶ Classic stimuli
• Chi, Gao, Guyton, Ru & Shamma (1999). Spectro-temporal modulation transfer functions and speech intelligibility. JASA 106. JASA. ripples.Ripple modulation.ModulationSpectrum · ▶ Spectrotemporal ripples
• Carlile & Leung (2016). The perception of auditory motion. Trends in Hearing 20. doi:10.1177/2331216516644254. Reviews which cues listeners use to judge motion; level and interaural differences outweigh Doppler. · ▶ Moving talkers
• Cho & Kidd (2022). Auditory motion as a cue for source segregation and selection in a "cocktail party" listening environment. JASA 152(3), 1684–1694. doi:10.1121/10.0013990. Its experiment code is archived at choyun1/MSM. spatialization.move_sound binaural.interaural_cues · ▶ Moving talkers · Roadmap
• Christensen (2003). An Introduction to Frames and Riesz Bases. Birkhäuser. doi:10.1007/978-0-8176-8224-8. frame.Frame
• Cuevas-Rodríguez, Picinali, González-Toledo et al. (2019). 3D Tune-In Toolkit: an open-source library for real-time binaural spatialisation. PLOS ONE 14(3), e0211899. doi:10.1371/journal.pone.0211899. Removes the interaural delay before interpolating HRIRs, as sonore's onset alignment does. spatialization.HRIRSet · ▶ Moving talkers
• Davis & Mermelstein (1980). Comparison of parametric representations for monosyllabic word recognition in continuously spoken sentences. IEEE Trans. Acoust., Speech, Signal Process. 28(4), 357–366. mfcc.MFCC · ▶ Cepstral analysis ▶ Changing a voice
• Daubechies, Grossmann & Meyer (1986). Painless nonorthogonal expansions. J. Math. Phys. 27(5). doi:10.1063/1.527388. gabor.GaborFrame
• Dau, Kollmeier & Kohlrausch (1997). Modeling auditory processing of amplitude modulation. I. Detection and masking with narrow-band carriers. JASA 102(5), 2892–2905. PubMed. modulation.HannModulationFilterbank · ▶ Modulation spectrogram
• de Cheveigné & Kawahara (2002). YIN, a fundamental frequency estimator for speech and music. JASA 111(4). doi:10.1121/1.1458024. f0.f0_track · ▶ Voices from harmonics
• Dolson (1986). The phase vocoder: A tutorial. Computer Music Journal 10(4). Semantic Scholar. phasevocoder · ▶ Phase vocoder
• Dorman, Loizou & Rainey (1997). Speech intelligibility as a function of the number of channels of stimulation for signal processors using sine-wave and noise-band outputs. JASA 102(4), 2403–2411. doi:10.1121/1.420354. envelopes.noise_vocode · ▶ Hearing through a vocoder
• Escabí & Schreiner (2002). Nonlinear spectrotemporal sound analysis by neurons in the auditory midbrain. J. Neurosci. 22. doi:10.1523/JNEUROSCI.22-10-04114.2002. ripples.DynamicRipple · ▶ Spectrotemporal ripples
• Fant (1995). The LF-model revisited. Transformations and frequency domain analysis. STL-QPSR 36(2–3), 119–156. The Rd parameter. waveforms.glottal_source klatt.klatt_synthesize · ▶ Formant synthesis · Roadmap
• Fant, Liljencrants & Lin (1985). A four-parameter model of glottal flow. STL-QPSR 26(4), 1–13. waveforms.lf_harmonics waveforms.lf_pulse · ▶ Formant synthesis · Roadmap
• Flanagan & Golden (1966). Phase vocoder. Bell System Technical Journal 45. doi:10.1002/j.1538-7305.1966.tb01706.x. phasevocoder · ▶ Phase vocoder
• Friesen, Shannon, Baskent & Wang (2001). Speech recognition in noise as a function of the number of spectral channels: comparison of acoustic hearing and cochlear implants. JASA 110(2), 1150–1163. PubMed. envelopes.noise_vocode · ▶ Hearing through a vocoder
• Gabor (1946). Theory of communication. Part 1: The analysis of information. J. IEE 93(26). doi:10.1049/ji-3-2.1946.0074. gabor.GaborFrame · ▶ Seeing speech
• Gamper (2013). Head-related transfer function interpolation in azimuth, elevation, and distance. JASA 134(6), EL547. doi:10.1121/1.4828983. The HRIR interpolation used in Cho & Kidd (2022); sonore interpolates onset-aligned responses instead. spatialization.HRIRSet.at
• Glasberg & Moore (1990). Derivation of auditory filter shapes from notched-noise data. Hearing Research 47. doi:10.1016/0378-5955(90)90170-T. filterbank.ERBFilterbank · ▶ Seeing speech ▶ Classic stimuli
• Gordon & Strawn (1985). An introduction to the phase vocoder. In J. Strawn (ed.), Digital Audio Signal Processing: An Anthology. Also Stanford CCRMA report STAN-M-55. CCRMA. phasevocoder · ▶ Phase vocoder
• Greenberg & Kingsbury (1997). The modulation spectrogram: in pursuit of an invariant representation of speech. Proc. ICASSP 1997, vol. 3, 1647–1650. Semantic Scholar. modspectrogram.ModulationSpectrogram · ▶ Modulation spectrogram
• Griffin & Lim (1984). Signal estimation from modified short-time Fourier transform. IEEE TASSP 32. doi:10.1109/TASSP.1984.1164317. gabor.STFT.griffin_lim
• Hillenbrand, Getty, Clark & Wheeler (1995). Acoustic characteristics of American English vowels. JASA 97(5), 3099–3111. doi:10.1121/1.411872. Male and female formants, used for the synthetic vowels in tools/compare_voice_methods.py. · ▶ Source, filter and aperiodicity ▶ Changing a voice
• Kawahara, Masuda-Katsuse & de Cheveigné (1999). Restructuring speech representations using a pitch-adaptive time-frequency smoothing and an instantaneous-frequency-based F0 extraction. Speech Communication 27. doi:10.1016/S0167-6393(98)00085-5. gabor.TVGaborFrame.pitch_adaptive · Roadmap
• Kawahara et al. (2011). Technical foundations of TANDEM-STRAIGHT, a speech analysis, modification and synthesis framework. Sādhanā 36(5). doi:10.1007/s12046-011-0043-3. spectrum.tandem_power · ▶ Seeing speech
• Kingsbury, Morgan & Greenberg (1998). Robust speech recognition using the modulation spectrogram. Speech Communication 25(1–3), 117–132. doi:10.1016/S0167-6393(98)00032-6. modspectrogram.ModulationSpectrogram · ▶ Modulation spectrogram
• Klatt (1980). Software for a cascade/parallel formant synthesizer. JASA 67(3). doi:10.1121/1.383940. klatt.klatt_synthesize processing.resonator · ▶ Formant synthesis · Roadmap
• Klatt & Klatt (1990). Analysis, synthesis, and perception of voice quality variations among female and male talkers. JASA 87(2), 820–857. doi:10.1121/1.398894. The SS source switch. klatt.klatt_synthesize · ▶ Formant synthesis · Roadmap
• Kodera, Gendrin & de Villedary (1978). Analysis of time-varying signals with small BT values. IEEE Trans. ASSP 26(1). doi:10.1109/TASSP.1978.1163047. reassigned.reassigned_spectrogram · ▶ Seeing speech
• Kominek & Black (2004). The CMU Arctic speech databases. Proc. 5th ISCA Speech Synthesis Workshop (SSW5), 223–224. ISCA Archive. The gallery's speech (speakers bdl and rms; see docs/speech/SOURCES.md). · ▶ Seeing speech ▶ Cepstral analysis ▶ Hearing through a vocoder ▶ Moving talkers ▶ Synthetic reverberation ▶ Phase vocoder ▶ Classic stimuli ▶ Modulation spectrogram ▶ Voices from harmonics ▶ Changing a voice
• Kowalski, Depireux & Shamma (1996). Analysis of dynamic spectra in ferret primary auditory cortex. I. J. Neurophysiol. 76. doi:10.1152/jn.1996.76.5.3503. ripples.Ripple · ▶ Spectrotemporal ripples
• Laroche & Dolson (1999). Improved phase vocoder time-scale modification of audio. IEEE Trans. Speech Audio Process. 7(3). IEEE Xplore. phasevocoder.time_stretch · ▶ Phase vocoder
• Licklider, Webster & Hedlun (1950). On the frequency limits of binaural beats. JASA 22(4), 468–473. doi:10.1121/1.1906629. · ▶ Classic stimuli
• McAulay & Quatieri (1986). Speech analysis/synthesis based on a sinusoidal representation. IEEE TASSP 34. Internet Archive. · Roadmap
• McDermott & Simoncelli (2011). Sound texture perception via statistics of the auditory periphery. Neuron 71. doi:10.1016/j.neuron.2011.06.032. texture filterbank.CosineFilterbank modulation · ▶ Sound textures
• Morise (2015). CheapTrick, a spectral envelope estimator for high-quality speech synthesis. Speech Communication 67. doi:10.1016/j.specom.2014.09.003. spectral_envelope.cheaptrick gabor.TVGaborFrame.pitch_adaptive · ▶ Cepstral analysis ▶ Voices from harmonics ▶ Source, filter and aperiodicity ▶ Changing a voice · Roadmap
• Morise (2016). D4C, a band-aperiodicity estimator for high-quality speech synthesis. Speech Communication 84, 57–65. doi:10.1016/j.specom.2016.09.001. aperiodicity.d4c · ▶ Source, filter and aperiodicity ▶ Changing a voice · Roadmap
• Morise (2017). Harvest: a high-performance fundamental frequency estimator from speech signals. Proc. Interspeech 2017. doi:10.21437/Interspeech.2017-68. Compared with f0_track in tools/check_f0_fda.py. · ▶ Voices from harmonics ▶ Source, filter and aperiodicity ▶ Changing a voice
• Morise, Yokomori & Ozawa (2016). WORLD: A vocoder-based high-quality speech synthesis system for real-time applications. IEICE Trans. Inf. & Syst. E99-D(7). doi:10.1587/transinf.2015EDP7457. Its synthesis is reproduced by world_synthesize, and its StoneMask refinement followed by f0_track. world.world_synthesize f0.f0_track · ▶ Cepstral analysis ▶ Voices from harmonics ▶ Source, filter and aperiodicity ▶ Changing a voice · Roadmap
• Noll (1967). Cepstrum pitch determination. JASA 41(2). PubMed. cepstrum.Cepstrum.f0 · ▶ Cepstral analysis ▶ Voices from harmonics ▶ Changing a voice
• Oppenheim & Schafer (2010). Discrete-Time Signal Processing, 3rd ed., ch. 13. Pearson. Pearson. cepstrum.Cepstrum.to_stft
• Patterson, Robinson, Holdsworth, McKeown, Zhang & Allerhand (1992). Complex sounds and auditory images. In Auditory Physiology and Perception (Proc. 9th International Symposium on Hearing). doi:10.1016/B978-0-08-041847-6.50054-X. filterbank.GammatoneFilterbank
• Perraudin, Balazs & Søndergaard (2013). A fast Griffin-Lim algorithm. IEEE WASPAA. doi:10.1109/WASPAA.2013.6701851. gabor.STFT.griffin_lim
• Peterson & Barney (1952). Control methods used in a study of the vowels. JASA 24(2), 175–184. ASA. Average formant frequencies of ten vowels. · ▶ Formant synthesis ▶ Cepstral analysis
• Plomp & Levelt (1965). Tonal consonance and critical bandwidth. JASA 38(4), 548–560. doi:10.1121/1.1909741. · ▶ Classic stimuli
• Qu et al. (2009). Distance-dependent head-related transfer functions measured with high spatial resolution using a spark gap. IEEE TASLP 17. PKU Scholar. spatialization.HRIRSet.from_pku_ioa hrir_data.load_hrirs · ▶ Moving talkers
• Schroeder (1970). Synthesis of low-peak-factor signals and binary sequences with low autocorrelation. IEEE Trans. Inf. Theory 16. doi:10.1109/TIT.1970.1054411. waveforms.schroeder_complex · ▶ Voices from harmonics
• Shannon et al. (1995). Speech recognition with primarily temporal cues. Science 270. doi:10.1126/science.270.5234.303. envelopes.noise_vocode · ▶ Hearing through a vocoder ▶ Voices from harmonics
• Singh & Theunissen (2003). Modulation spectra of natural sounds and ethological theories of auditory processing. JASA 114(6). doi:10.1121/1.1624067. modulation.ModulationSpectrum envelopes.Envelopes.modulation_spectrum · ▶ Spectrotemporal ripples
• Siveke et al. (2008). Psychophysical and physiological evidence for fast binaural processing. J. Neurosci. 28. J. Neurosci.. binaural.oscor binaural.phasewarp · ▶ Binaural cues
• Traer & McDermott (2016). Statistics of natural reverberation enable perceptual separation of sound and space. PNAS 113. doi:10.1073/pnas.1612524113. reverb.synth_ir · ▶ Synthetic reverberation
• Wang (2005). On ideal binary mask as the computational goal of auditory scene analysis. In Speech Separation by Humans and Machines. doi:10.1007/0-387-22794-6_12. mask.ideal_binary_mask · ▶ Analysis and resynthesis
• Wilson, Finley, Lawson, Wolford, Eddington & Rabinowitz (1991). Better speech recognition with cochlear implants. Nature 352, 236–238. PubMed. envelopes.noise_vocode · ▶ Hearing through a vocoder
• Yost (1996). Pitch of iterated rippled noise. JASA 100. JASA (PDF). waveforms.iterated_ripple_noise · ▶ Iterated rippled noise

Reference implementations

Implementations by a paper's authors or widely used ports, with how sonore relates to each. "Cross-checked" means a script in tools/ compares the two numerically; "consulted" means the code was read for behavior but not copied.

• Sound Texture Synthesis Toolbox v1.7 (MATLAB), McDermott lab: the authors' implementation of McDermott & Simoncelli (2011). Consulted; sonore is a clean-room implementation from the paper, and every deliberate difference is listed in so.texture.DIFFERENCES_FROM_TOOLBOX. texture filterbank.CosineFilterbank modulation
• wil-j-wil/texture_stats (Python, MIT): a port of the toolbox's statistics. Cross-checked by tools/crosscheck_texture_stats.py. texture.TextureStats
• mcdermottLab/pycochleagram (Python): the lab's port of the toolbox's cochleagram code, including the cosine filterbank. Not yet cross-checked. filterbank.CosineFilterbank
• LTFAT (MATLAB/Octave, GPLv3): frsynabs with 'fgriflim' is the fast Griffin-Lim from the group of Perraudin, Balazs & Søndergaard (2013); librosa.griffinlim is a widely used Python version. Neither is cross-checked yet. gabor.STFT.griffin_lim
• SciPy ShortTimeFFT (BSD-3): wrapped by GaborFrame. Its frame operator, bounds and least-squares inverse are cross-checked against dense matrices in the tests and in tools/check_frames_step1_claims.py (docs/design/frames.md, step 1). gabor.GaborFrame gabor.STFT
• Gammatone filterbanks in Slaney's Auditory Toolbox and MATLAB's gammatoneFilterBank are time-domain IIR approximations; GammatoneFilterbank uses the exact frequency response instead (derivation in docs/design/frames.md, step 2). Consulted for conventions only. filterbank.GammatoneFilterbank
• SciPy minimum_phase (homomorphic method), the real-cepstrum definition MATLAB's rceps documents, and Praat's PowerCepstrogram through parselmouth (GPLv3): cross-checked by tools/crosscheck_cepstrum.py, Praat at development time only. cepstrum.Cepstrum
• Kaldi's compute-mfcc-feats, through kaldi-native-fbank (Apache-2.0), a C++ re-implementation of Kaldi's feature code: its MFCCs and log mel energies are stored by tools/make_kaldi_fixtures.py, and the tests compare MFCC with them to float32 precision (no DC removal, pre-emphasis or energy, which sonore leaves to the sound). The primary reference, standing in for HTK, whose download site was unreachable. mfcc.MFCC
• librosa (ISC) feature.mfcc, feature.melspectrogram and feature.delta: their output for three settings is stored by tools/make_mfcc_fixtures.py, and the tests compare MFCC with it (mel power to 3e-7, coefficients to 1e-8, both relative to the largest value). tools/crosscheck_mfcc.py also reproduces python_speech_features 0.6 exactly. Both are development-time only. mfcc.MFCC
• LTFAT (GPLv3) and nsgt (Artistic License 2.0): frame theory in code, for dev-time cross-checks only because of their licenses. Not yet cross-checked. frame

Migrating from sigtools

sonore was previously sigtools, renamed to avoid a clash with an unrelated PyPI package of that name. Version 0.2 also redesigned the API:

Results computed with 0.1 can differ, because these 0.1 bugs were fixed: spectrum and STFT "dB" were half the true value; the bandpass filter filtered stereo across channels; SimpleBIR was a sample short and got louder with larger ITDs; SynthIR's DRR had no effect and its resynthesis filters were shifted in frequency; tone frequencies were off by a factor of (n-1)/n; move_sound summed ~100 unwindowed overlapping convolutions per sample; and IAC was never computed. The ILD in apply_itd_ild is now split ±ILD/2 across the ears (0.1 applied it to the right ear only).

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. 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. 10.5281/zenodo.23086165 always points to the latest version; each version also has its own DOI, listed on that page (0.3.1 is 10.5281/zenodo.23086166). Cite the version you used.