Guitar Tap

---

Tap-tone spectrum analysis for luthiers, running entirely in the browser. Tap a guitar, tonewood plate, or brace; Guitar Tap captures the sound, runs a high-resolution FFT, and reveals the resonant peaks and material properties that guide bracing, mass distribution, and plate thickness — the methodology from Contemporary Acoustic Guitar Design and Build by Trevor Gore and Gerard Gilet.

This is the web edition of Guitar Tap. It is a long-term parallel port of the Apple edition (GuitarTap, Swift — the canonical reference for both algorithm and UX), alongside the desktop edition (guitar_tap, Python). All three are kept at numeric and behavioural parity (see Parity below) and are open source under the GNU GPL v3.

Everything runs client-side: the DSP happens in the browser, and your saved measurement library lives in the browser's IndexedDB — no server, no accounts, no tracking. It installs as a Progressive Web App for an app window, offline use, and durable storage.

Features

• Guitar mode — identify Air (Helmholtz), Top, Back and other body resonances, each labelled with frequency, pitch, and Q, plus the tap-tone ratio and ring-out.
• Plate mode — Young's modulus (along/across grain), speed of sound, specific modulus, radiation ratio, a quality grade, and a Gore target thickness.
• Brace mode — fast single-tap stiffness, speed of sound, specific modulus.
• Live spectrum with automatic tap capture, multi-tap averaging, calibration (UMIK-1), comparison overlays, PDF/image/.guitartap export, and a saved library.
• Installable PWA; keyboard, mouse, touch, and iPhone/iPad layouts.

Tech stack

• Vite + React 18 + TypeScript (strict).
• Pure DSP in src/dsp (no DOM/audio), unit-tested against a shared oracle.
• Live audio via an AudioWorklet (public/spectrum-processor.js).
• Library persistence in IndexedDB; files in the .guitartap JSON format.
• vite-plugin-pwa (Workbox) for the installable/offline app.
• Vitest for the test suite.
• ESLint with eslint-plugin-react-hooks — a focused lint for React Hook dependency arrays (types/unused are covered by the strict TypeScript check).

Project structure

src/
  dsp/           Pure DSP core — FFT, gated capture, peak finding, classify,
                 material properties, pitch, calibration. No DOM/audio; oracle-tested.
  audio/         AudioWorklet-driven engine: mic capture, tap detection, playback.
  components/    React UI — spectrum chart, peak cards, panels, sheets, settings.
  measurement/   .guitartap read/write + the IndexedDB library store.
  presentation/  Rendering/export helpers (PDF report, spectrum image, mode colours).
  hooks/ format/ Small shared utilities.
  App.tsx        Top-level app: toolbar, live view, results, state.
public/
  spectrum-processor.js   AudioWorklet (microphone → FFT frames).
  icons/                  PWA + favicon assets.
test/            Vitest oracle-driven parity tests (g0–g11 + regressions).
  fixtures/parity-oracle.json   Expected values, generated from the Swift reference.
tooling/sync-oracle.sh          Maintainer script: refresh the vendored oracle.

Setting up on a new machine

All commands run in bash: Terminal on macOS, a shell on Linux, Cygwin bash (or Git Bash) on Windows. Every repo has its own Python environment, .venv, made from its own requirements files; nothing uses another repo's Python or the system's. The repo's scripts find .venv themselves (.venv/bin, or .venv/Scripts on Windows) and stop if it is missing; PYTHON=… names another interpreter.

1. Prerequisites: Node.js at the version in .nvmrc (pinned: other versions have broken the build — nvm install / nvm use reads it), Python 3.14, and git.
2. Windows only — npm scripts in bash. npm runs package scripts in cmd.exe on Windows, and ours are bash (npm run build stops with "'.' is not recognized…"). Once per machine, from any folder:

   npm config set script-shell "$(cygpath -w "$(which bash)")"
   

   It is saved in your user ~/.npmrc, so it holds for every project; npm config get script-shell shows it.
3. Clone and install:

   git clone https://github.com/dwsdolce/GuitarTapWeb.git
   cd GuitarTapWeb
   npm ci                              # exact, lockfile-pinned install
   npx playwright install chromium     # the browser the end-to-end and export tests drive
   

4. Python environment — the export checker (tooling/export-check/), run by npm run test:exports:

   python3.14 -m venv .venv
   .venv/bin/pip install -r requirements-dev.txt        # on Windows: .venv/Scripts/pip
   

5. VS Code: open the folder and select .venv as the Python interpreter.
6. Check it works: npm run test:fast.

Day to day:

npm run dev          # start the dev server (http://localhost:5173)
npm test             # run the Vitest parity suite
npm run typecheck    # strict TypeScript check (no emit)
npm run lint         # ESLint — React Hook dependency-array checks

Grant microphone permission when prompted — audio is analysed locally and never leaves the browser.

Soak / stress testing

tooling/soak.sh is an on-demand dev tool (not CI) that loops the fast Vitest suite many times to surface nondeterministic teardown/async races (React effect-cleanup) that a single run hides:

./tooling/soak.sh 200        # 200 runs; exits non-zero on any failure or hang
./tooling/soak.sh 200 15000  # …with a 15 s per-test timeout (default 10 s)

Runs under bash on macOS, Linux, and Windows (Cygwin / Git-Bash). A green soak is confidence, not proof — use a few hundred to ~1000 runs. Why it works the way it does, and what it detects, is in the script's own header.

Build

npm run build        # tsc --noEmit && vite build  →  dist/
npm run preview      # serve the production build locally to smoke-test it

This is the beginning of the README. Read the rest at the original. Read the full README ↗