Tap-tone analysis for luthiers — capture a tap, run an FFT, and reveal a guitar's resonant modes and a tonewood's stiffness.
Download · Website · User Manual
Guitar Tap captures the brief ring-out after you tap a guitar, a tonewood plate, or a brace, runs a high-resolution FFT, and reveals the resonant peaks and material properties that matter to guitar builders. Use the results to guide your bracing, mass distribution, and plate thickness.
It implements the tap-tone methodology from Contemporary Acoustic Guitar Design and Build by Trevor Gore in collaboration with Gerard Gilet — built to improve reproducibility in guitar building.
This is the desktop edition of Guitar Tap: free and open source, written in Python 3 with PySide6, for Windows, macOS, and Linux. The Apple edition for iPhone, iPad, and Mac is on the App Store, and the web edition runs in any modern browser — all three are open source (see Related projects).
- Guitar mode — identify the key body resonances (Air/Helmholtz, Top, Back, and more), each labeled with frequency, pitch, and Q factor, plus the tap-tone ratio.
- Plate mode — measure a tonewood blank: Young's modulus along and across the grain, speed of sound, specific modulus, radiation ratio, a quality grade, and a Gore target thickness.
- Brace mode — a fast single-tap measurement of a brace strip's stiffness, speed of sound, specific modulus, and quality.
- Real-time spectrum that freezes automatically the instant a tap is detected.
- Multi-tap averaging and side-by-side comparison of saved measurements.
- Save measurements and export spectra, images, and PDF reports.
- Microphone calibration support for measurement mics.
Prebuilt installers for macOS and Windows are on the releases page. Please note that the macOS installer only runs on systems newer than Big Sur (11.0), due to the end of life of the earlier systems.
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. On Windows, write .venv/Scripts/ where these
commands say .venv/bin/.
- Python 3.14 or later from https://www.python.org/, and git.
- System packages:
- macOS:
brew install portaudio - Linux (Debian/Ubuntu):
sudo apt update && sudo apt install portaudio19-dev libxcb-cursor-dev - Windows: none.
- macOS:
- For the Quick Start Guide (testing and installers only): a native Pango library — macOS
brew install pango, Linuxsudo apt install libpango-1.0-0 libpangoft2-1.0-0, Windows the GTK runtime (seepackaging/generate_guide.py). For the release-notes PDF (macOS installer):brew install pandocandbrew install --cask basictex(xelatex).
git clone https://github.com/dwsdolce/guitar_tap
cd guitar_tap
python3.14 -m venv .venvEach file includes requirements.txt, the application's own list; packages for one platform only (pyobjc on
macOS, comtypes on Windows) install there automatically.
| To | Install |
|---|---|
| Run from source | .venv/bin/pip install -r requirements.txt |
| Test and develop | .venv/bin/pip install -r requirements-dev.txt |
| Build installers | .venv/bin/pip install -r requirements-packaging.txt |
Then, for any of them: .venv/bin/pip install -e . --no-deps (the app's own package, from src/).
.venv/bin/python -m guitar_tap- VS Code: open the folder and select
.venvas the Python interpreter. - Check a test setup works:
Tooling/test-fast.sh.
Tooling/test-fast.sh runs the whole pytest suite except the two tests that replay every recording —
the playback regression (tests/test_file_playback_regression.py) and the self-regression
(tests/test_self_regression.py), which are most of the suite's time — for use while working.
Run the full suite (pytest) before a commit. The same split: web npm run test:fast, Swift
Tooling/test-fast.sh.
Tooling/soak.sh is an on-demand dev tool (not CI) that loops the fast pytest
suite many times to surface nondeterministic teardown/GC races (e.g. QObject
finalisation) that a single run hides:
./Tooling/soak.sh 200 # 200 runs; exits non-zero on any failure or hangIt runs under bash on macOS, Linux, and Windows (Cygwin / Git-Bash), with this repo's .venv
(.venv/bin, or .venv/Scripts on Windows).
A green soak is confidence, not proof — use a few hundred to ~1000 runs.
Set up for building installers (requirements-packaging.txt, see Setting up on a new machine).
Then run the platform script from the repository root:
- Linux: ./packaging/build_linux
- macOS: ./packaging/build_mac
- Windows: ./packaging/build_win (Cygwin bash)
Linux (AppImage): the build script invokes appimagetool. Install it once:
- wget -O ~/bin/appimagetool https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage
- chmod +x ~/bin/appimagetool
- If appimagetool is elsewhere, set APPIMAGETOOL=/path/to/appimagetool before running build_linux.
- On Ubuntu 22.04+ you may also need sudo apt install libfuse2 for appimagetool to run.
- For broadest compatibility, build inside a container running the oldest glibc you want to support (e.g. Ubuntu 22.04 LTS).
Windows: the installer step uses Inno Setup 6 — install it in its default folder (C:\Program Files (x86)\Inno Setup 6), where build_win runs ISCC.exe. The Windows build is not code-signed.
macOS: code signing and notarization require an Apple Developer ID. The spec file (packaging/guitar-tap.spec) references the certificate identity — adjust it for your own developer account.
Behaviour is pinned to the canonical Swift app, not to this code:
- Numeric outputs match to 2–3 decimal places; categorical outputs match exactly;
.guitartapfiles round-trip across all three editions. - The contract is the oracle (
tests/parity-oracle.json), which is committed to this repository — so the test suite is self-contained and needs nothing else to run. It is a vendored copy of the shared oracle, generated in the Swift app;Tooling/sync-oracle.shrefreshes it, and the suite (tests/test_gated_fft_parity.py,tests/test_file_playback_regression.py, …) checks every DSP result against it. - Each mirrored module carries a
@parityslug the maintainer uses to keep the Swift, Python, and web implementations in step.
When an algorithm changes, it is designed once and applied to Swift, Python, and web together, with the oracle regenerated.
The full User Manual covers every measurement mode, the settings and controls reference, troubleshooting, and a glossary.
Design and cross-platform project docs (specs, parity map, roadmap) live in the project's own repository, which is private.
On startup Guitar Tap checks this repository's public releases for a newer version and shows a dismissible banner when one is available. The request reads GitHub's public release list and sends no personal data, no audio, and no measurements. It runs at most once a day, and you can turn it off in Settings → About & Help → Check for updates at startup. See the privacy policy for details.
- GuitarTap — the Apple edition: the native app for iPhone, iPad, and Mac (Swift; the canonical reference), on the App Store.
- GuitarTapWeb — the web edition, in any modern browser: https://www.dolcesfogato.com/guitar_tap/guitar_tap_web/.
Issues and pull requests are welcome. Before opening a PR, please run the full test suite
(.venv/bin/python -m pytest). Because this is a parity port, changes to DSP or behaviour must preserve
the oracle contract. If you're proposing an intentional behaviour change, please open an issue first so it
can be coordinated across all three editions and the oracle is regenerated by the maintainer.
Copyright © 2026 Dolce Sfogato (David Smith).
Licensed under the GNU General Public License v3.0 — see LICENSE.