Fret

Desktop app for guitar note detection, fretboard visualization, related scale lookup, and piano mirroring.

Built with Electron, React, TypeScript, Canvas, and Web Audio.

Live Web App

Use it прямо в браузере:

https://kroq86.github.io/fret/

No installation required.

What It Does

• Detects guitar notes from microphone input in real time
• Lets you freeze live input and click notes manually on the fretboard
• Clears the current note set so you can build scales manually
• Finds the most likely matching scale from the last detected/selected notes
• Shows related scales and lets you select one explicitly
• Mirrors the currently selected scale on a two-octave piano view
• Supports switching between audio input devices
• Includes a watch-based local dev mode for fast iteration

Download

Prebuilt desktop releases are published on the Releases page.

• macOS: download the .dmg
• Windows: download the .exe

Web Version

A browser version can be deployed for free through GitHub Pages.

Expected URL for this repository:

https://kroq86.github.io/fret/

GitHub Pages deploys from the workflow in .github/workflows/pages.yml.

Install Notes

This project currently ships as an unsigned desktop build. That keeps releases simple and free, but macOS and Windows may warn before opening the app.

macOS

If macOS says the app is "damaged" or refuses to open it:

1. Download the .dmg from Releases.
2. Drag Fret.app into Applications.
3. Open Terminal.
4. Run:

xattr -dr com.apple.quarantine /Applications/Fret.app

5. Open Fret again from Applications.

If macOS still blocks it, try:

sudo xattr -dr com.apple.quarantine /Applications/Fret.app

You may also need to allow microphone access in: System Settings -> Privacy & Security -> Microphone

Windows

Windows SmartScreen may warn that the app is from an unknown publisher.

To continue:

1. Download the installer from Releases.
2. Open it.
3. If SmartScreen appears, click More info.
4. Click Run anyway.

Local Development

Requirements

• Node.js 20+ recommended
• npm
• Microphone access

Setup

git clone <repo>
cd fret
npm install

Run

npm run dev

npm run dev starts:

• TypeScript watch for the Electron main process
• webpack watch for the renderer
• automatic Electron restart when built files change

Other Useful Scripts

npm start         # run Electron from current build
npm run build     # production build into dist/
npm run watch     # renderer watch only
npm run watch:main

Build Releases

npm run build:mac
npm run build:win
npm run build:all

Artifacts are written to release/.

Release Flow

Releases are created through GitHub Actions when a version tag is pushed.

Current flow:

1. Bump version in package.json
2. Commit changes
3. Create a tag like v0.1.5
4. Push main
5. Push the tag

The workflow in .github/workflows/release.yml then:

• builds Windows .exe
• builds macOS .dmg
• uploads both to a GitHub Release

GitHub Pages Deployment

This repository also supports a free web deployment through GitHub Pages.

Use:

npm run build:web

For local browser-only development:

npm run dev:web

To enable Pages on GitHub:

1. Open Settings -> Pages
2. Set Source to GitHub Actions
3. Push to main

The workflow will build the web app and publish dist/ automatically.

Project Structure

• src/components/NoteDetector.tsx Main app state, note aggregation, device selection, freeze/manual mode, selected scale sync
• src/components/Fretboard.tsx Guitar fretboard rendering, played-note highlight, related scale selection
• src/components/PianoKeyboard.tsx Two-octave piano mirror for the currently selected scale
• src/utils/pitchyProcessor.ts Microphone capture and pitch detection
• src/utils/scales.ts Scale definitions and compatibility lookup

Known Limitations

• macOS builds are not signed or notarized
• Windows builds are unsigned
• Scale detection is heuristic and based on the current played/manual note set
• Piano view mirrors the selected scale from Related Scales; it is not a full piano trainer

License

MIT