audionotch

A command-line tool for tailor-made notched music training (TMNMT), a sound therapy for tonal tinnitus. It measures your tinnitus frequency with an interactive reference tone (or hiss, since most tinnitus is narrowband noise rather than a pure tone), then cuts that frequency band out of your own music files. You listen to the result in any music player, on any device.

Zero dependencies. Builds with the Swift toolchain alone. MIT licensed.

How the therapy works

The working theory: hearing damage leaves a band of frequencies under-activated in the auditory pathways, the brain turns the gain up around that band, and you hear the result as tinnitus. TMNMT removes exactly the frequencies inside that band from your music while boosting the edges, aiming to retrain the gain through lateral inhibition. You still hear all your music; the band around your tinnitus frequency is simply silent, with its neighbors played a little louder.

Requirements

macOS 14+ and the Xcode Command Line Tools:

xcode-select --install

Install

git clone https://github.com/Ryce/audionotch.git
cd audionotch
swift run audionotch --help

Or build once and put the binary on your PATH:

swift build -c release
sudo cp .build/release/audionotch /usr/local/bin/

Usage

1. Measure your tinnitus frequency

swift run audionotch tune

A steady stimulus plays continuously. Adjust until it matches your ringing:

Key	Action
← →	±25 cents
↑ ↓	±100 cents
, .	±1 octave
- =	volume
space	mute the stimulus (hear your ringing alone)
t / n	reference: tone / hiss
s	hiss type: white → pink → brown
w / W	stimulus bandwidth: 1/3 → 1/2 → 1/4 → 1/8 → 1/16 → 1/32 → full; W steps back
o	octave check: plays f/2, f, 2f, you pick which matches
c	jump to 1 kHz
↵ / q	save the measurement / quit

The reference can be a pure tone or a narrowband noise centered on the tone frequency, because most people's tinnitus sounds like hiss, and comparing hiss against a sine is harder than comparing like with like. If your ringing feels higher than everything, use the octave check; octave errors are the most common pitch-matching mistake.

The notch frequency is the median of your last 10 measurements. The study protocol measured twice a day for 5 days, because single pitch matches wobble: in Stein's 100-patient trial the within-subject standard deviation was about 1,341 Hz.

2. Apply the notch to your music

swift run audionotch notch ~/Music/album/*.mp3

Reads mp3/m4a/wav/aiff/flac, writes <name> (notched).m4a (AAC 320 kbps) next to each file. Flags:

--freq HZ        notch this frequency instead of the measured one
--width OCT      notch width in octaves (default 0.5; the studies used 1, 0.5 and 0.25)
--boost DB       notch-edge amplification in dB (default 20; 0 disables it)
--edge-width OCT width of the amplified shoulders (default 0.375, as in Stein 2015)
--lossless       write WAV instead of AAC (use if your frequency is above ~16 kHz)
--out DIR        write results to DIR instead of alongside the sources
--force          overwrite existing outputs

Everything it applies is also editable live in tune (keys x, b, v), and those settings become the defaults here.

3. Listen

The protocol used in the trials: 2 hours per day, 3 months minimum, comfortable volume, headphones, the ringing still faintly audible under the music. Attentive but relaxed; the Stein 2016 instructions specifically allowed reading and browsing, but not work. AirDrop the notched files to your phone and play them in any player, they are ordinary AAC files.

4. Watch your numbers

swift run audionotch show

Lists your measurements, the median the notch will use, and the spread. When the median stops moving between sessions, that is your working frequency. Re-measure every week or two while treating.

What the DSP actually does

Three stages on the decoded signal, following Stein 2016 minus their equalization step (see Limitations):

1. A unit-gain digital notch, exactly zero at the target frequency, its -3 dB corners at the requested width (default 1/2 octave, i.e. ±1/4 octave).
2. Peaking-EQ shoulders at both notch edges: +20 dB gain, 3/8 octave wide. The +20 dB figure is the pleasantness ceiling Stein 2015 established; louder shoulders sounded worse, not better.
3. Peak normalization to -1 dBFS so edge boosting never clips.

All of it is float32 biquads, chained, state carried across read chunks, no external DSP libraries. The smoke report tells you how much energy the notch actually removed from a given track; near zero means your frequency sits where the recording has no content.

Testing

swift test

Covers the biquad design (notch depth at center, -3 dB corners exactly at the stated bandwidth, edge-boost gain, stability of the high-Q variants at 1/16 octave) and an end-to-end test: synthesize stereo, write WAV, process, read back, measure tones with Goertzel.

Limitations

• The evidence base for TMNMT is genuinely mixed. The trial above (n=100, CONSORT, placebo-controlled) missed its primary endpoints; several later trials found plain unnotched music scoring similarly; a 2024 meta-analysis of 7 trials found pooled THI changes not significant. Expect, at best, a 10-20% loudness reduction after 3+ months. If someone tells you this cures tinnitus, they are selling something.
• Frequencies above ~8 kHz: music has almost no energy there, so the therapy quietly does less. Both the tuner and the notch warn you.
• No spectral equalization step (Stein 2016 equalized the music's energy distribution before notching; this tool leaves the original balance).
• Apple Music / DRM streams cannot be processed; you need files you own.
• 1-2 channel audio, mono or stereo.

References

• Okamoto et al., "Listening to tailor-made notched music reduces tinnitus loudness and tinnitus-related cortical activity" (PNAS 2010). PMC2824261
• Teismann et al., "Short and intensive tailor-made notched music training against tinnitus" (PLoS ONE 2011). PMC3174191
• Stein et al., "Enhancing inhibition-induced plasticity in tinnitus" (PLoS ONE 2015, the +20 dB edge-boost study). PMC4423974
• Wunderlich et al., "Impact of Spectral Notch Width on Neurophysiological Plasticity and Clinical Effectiveness of the Tailor-Made Notched Music Training" (PLoS ONE 2015; width 1 vs 1/2 vs 1/4 octave made no difference, and the source of this tool's median-based frequency estimate). PMC4583393
• Stein et al., "Clinical trial on tonal tinnitus with tailor-made notched music training" (BMC Neurology 2016, the n=100 double-blind RCT). PMC4797223
• Tavanai et al., "Effects of notched music training: a systematic review" (Eur Arch Otorhinolaryngol 2024). PubMed 38847844

License

MIT, see LICENSE.