⚠️ EXPERIMENTAL SOFTWARE — NOT A MEDICAL DEVICE
This program has not been reviewed, tested, or approved by any medical authority, regulatory body (FDA, CE, etc.), or healthcare organization. It is provided as-is for experimental and educational purposes only. Use entirely at your own risk. Do not use this as a substitute for professional medical advice, diagnosis, or treatment. If you have concerns about your hearing or tinnitus, consult a qualified audiologist or physician.

A free, open-source tinnitus assessment and therapy tool built on peer-reviewed TMNMT research.
No account, no subscription, no data sent anywhere. Everything runs locally in your browser — or as a native Android app.

🌐 Live app: aaronminer1.github.io/tinnitus-suite

Just open your browser and go to:

https://aaronminer1.github.io/tinnitus-suite/ 

Works on Chrome, Edge, Firefox, and Safari. Use headphones for the hearing test.

Note: The system-wide streaming notch filter requires the Android native app (see below). The web version has all other features.

• Node.js v18 or higher (includes npm)
• A modern browser

git clone https://github.com/Aaronminer1/tinnitus-suite.git cd tinnitus-suite npm install npm start

Then open http://localhost:5173.

Don't have Git? Download the ZIP from the green Code button above, extract it, then run npm install && npm start.

• Node.js v18+
• Android SDK (API 28+ for DynamicsProcessing, API 36 for full feature set)
• Java 17+

npm run build npx cap sync android cd android ./gradlew assembleDebug

Install via ADB:

adb install -r app/build/outputs/apk/debug/app-debug.apk

• System-wide notch filter using Android DynamicsProcessing (API 28+)
• Foreground service with persistent notification for background operation
• Silent audio keep-alive prevents Samsung/OEM process killing
• Battery optimization exemption requested on first enable
• Service survives task removal (stopWithTask=false + onTaskRemoved restart)

This is how I personally deploy to my phones — no Android Studio needed. You just clone the repo, plug in your phone, and ask the AI to deploy it.

1. VS Code — Download here
2. GitHub Copilot — Install the GitHub Copilot extension in VS Code (requires a GitHub Copilot subscription). I use Claude Opus 4.6 as the model — you can select it in Copilot's model picker
3. Node.js v18+ — Download here
4. Java 17+ — sudo apt install openjdk-17-jdk (Linux) or download from Adoptium
5. Android SDK — Install via Android Studio's SDK Manager, or use sdkmanager from command-line tools. You need API 28+ (API 36 for full feature set)
6. ADB — Comes with Android SDK platform-tools. Make sure it's in your PATH
7. A USB-C cable (or USB-A to USB-C) to connect your phone

1. Enable Developer Options:
   • Go to Settings → About phone → Software information
   • Tap Build number 7 times — you'll see "Developer mode has been enabled"
2. Enable USB Debugging:
   • Go to Settings → Developer options
   • Turn on USB debugging
3. Connect your phone via USB cable
4. Authorize the connection — a popup will appear on your phone asking "Allow USB debugging?" — tap Allow (check "Always allow from this computer" for convenience)
5. Verify the connection — open a terminal and run adb devices. You should see your device listed

1. Clone the repo and install dependencies:

   git clone https://github.com/Aaronminer1/tinnitus-suite.git cd tinnitus-suite npm install

2. Open the folder in VS Code:

   code .

3. Open GitHub Copilot Chat (click the Copilot icon in the sidebar or press Ctrl+Shift+I)

4. Select Claude Opus 4.6 as your model in the Copilot model picker (dropdown at the top of the chat panel)

5. Plug in your Android phone via USB and accept the debugging prompt if it appears

6. Type this in Copilot Chat:

   Deploy to my connected Android phone

   That's it. Copilot will:

   • Build the web assets (npx vite build)
   • Sync them to the Android project (npx cap sync android)
   • Build the APK (./gradlew assembleDebug)
   • Install it on your phone (adb install)

7. Open the app on your phone — it'll appear as "Tinnitus Suite" in your app drawer

When there's a new version:

cd tinnitus-suite git pull npm install

Then just tell Copilot: "Deploy to my connected phone" — it handles the rest.

npm run build npm run preview

The dist/ folder contains a fully static site you can host anywhere.

1. Create a profile — multi-user support, all data stays local
2. Calibrate your volume — 6-step guide with a 1 kHz reference tone
3. Take the hearing test — Quick (9 freqs), Standard (12), or Fine (16 up to 16 kHz)
4. Review your audiogram — per-ear thresholds, asymmetry warnings, NIHL detection
5. Find your tinnitus tone — logarithmic sweep starting at your worst frequency
6. Start therapy — choose in-app notched noise OR system-wide streaming filter
7. For streaming: enable the notch, open Spotify/YouTube/Pandora — the filter applies to all audio

This app implements Tailor-Made Notched Music Training (TMNMT) based on:

• Okamoto et al. 2010 — "Listening to tailor-made notched music reduces tinnitus loudness and tinnitus-related auditory cortex activity" (PNAS)
• Pantev, Okamoto & Teismann 2012 — "Music-induced cortical plasticity and lateral inhibition in the human auditory cortex as foundations for tonal tinnitus treatment" (Frontiers in Systems Neuroscience)

Key implementation details from the research:

• 1-octave notch width (ERB-scaled) — wider than the 0.5-octave many apps use
• Music carrier preferred — the studies used music, not noise
• 12–20 dB notch depth — deeper notches had no additional benefit
• 1–2 hours daily — the clinical protocol duration

See TINNITUS_RESEARCH.md for the research notes that informed the current implementation.

Sound therapy — including TMNMT — can produce adverse effects. Users should be aware of:

If your tinnitus consistently worsens after sessions, stop using sound therapy and consult an audiologist.

See TINNITUS_RESEARCH.md for full adverse reaction data and references.

Requires Web Audio API (all modern browsers support this).

• No server. No analytics. No cookies.
• All data (audiogram, sessions, calibration) is stored only in your browser's localStorage.
• The Android app stores nothing beyond what the WebView's localStorage holds.
• Clearing browser/app data removes all stored results.

Pull requests welcome. To run the dev server with hot reload:

npm run dev

MIT — free to use, modify, and distribute.

THIS IS EXPERIMENTAL SOFTWARE. USE AT YOUR OWN RISK.

• This tool is not a medical device
• It has not been approved, certified, or reviewed by any medical authority, government agency, or regulatory body (including but not limited to the FDA, CE, TGA, MHRA, or Health Canada)
• It is not intended to diagnose, treat, cure, or prevent any disease or medical condition
• Results from this tool should not be used to make medical or clinical decisions
• The authors and contributors accept no liability for any harm, hearing damage, or adverse effects arising from use of this software
• Do not use headphone volumes that cause discomfort — stop immediately if you experience pain or worsening symptoms
• Always consult a qualified audiologist or ENT specialist for professional hearing assessment and tinnitus management

Known adverse effects: Sound therapy, including the notched sound techniques implemented in this app, has been documented to cause temporary increases in tinnitus loudness (rebound effect), new or changed tinnitus tones, and residual excitation in a subset of users. Approximately 32% of participants in one NMT study reported adverse reactions. Users with reactive tinnitus or hyperacusis are at elevated risk. See the Known Side Effects & Safety section and TINNITUS_RESEARCH.md for details and references.