Piano Helper

Overview

Piano Helper is a local Windows studio. The README describes it as open source for adult pianists: it listens through a microphone or MIDI, waits for the correct note, shows which finger to use, and imports sheet music the player already has. Practice data stays on the machine. The license is MIT.

The repo has no homepage URL. The product runs on the computer, not as a hosted site.

Problem

The README's approach is a teacher that will not run ahead of the player. Notes, fingers, and progress stay next to the score on that PC, in %APPDATA%\Piano Helper\. The repository itself contains no credentials.

What he built

The monorepo is split the way the README tables it:

• apps/desktop — the Electron and Vite studio.
• apps/web — an optional marketing site. It does not run optical music recognition or store API keys.
• packages/shared — lesson schema, pitch math, fingering, and the matcher.
• packages/bridge — the piano-helper CLI and MCP tools.
• packages/starters — public-domain starter lessons.

npm run studio serves the app to other devices on the same Wi-Fi, with a QR code in the terminal. On Windows, Piano Helper.cmd installs and builds on first run. A one-time mic check per device measures room noise and how far the piano is in tune, including whether the mic hears the extreme keys an octave off.

Import is a photograph of a page. The computer runs Codex or Claude Code once to read notes, rhythm, hand, and fingering. The README says the answer is saved beside the photo and reused after that, including when the same photo is uploaded again, and that API keys are stripped so the call bills the player's own ChatGPT or Claude plan. Learn mode draws a hand on the keys. Play-along follows the player's tempo instead of a fixed track.

Process

Development commands in the README are npm install, npm test, and npm run dev. The desktop UI is documented at http://localhost:5173. Tests can run with stand-in CLIs. npm run test:live is the path that uses a signed-in Claude Code or Codex against two sample scores. From Claude Code in the folder, /piano starts the studio, and the MCP tools (push_lesson, open_piece, get_session, and others) drive the device currently practising.