TrumpetPracticeHero is an interactive, browser-based and desktop-native trumpet tutor designed to help brass musicians master pitch intonation, sight-reading, and piston valve fingerings.
This project is powered by Featherless AI to run advanced language models locally and in the cloud for practice evaluation, personalized coaching feedback, and dynamic sheet music analysis.
TrumpetPracticeHero integrates with the Featherless.ai serverless inference API to query open-weights models (specifically Qwen-2.5-7B-Instruct) for key educational metrics:
- Practice Performance Analysis: After each session, the application compiles your notes played, cents deviation, and missed notes, sending them to the Featherless AI Coach for a natural language critique and diagnostic tips.
- Dynamic Sheet Music Analysis: When you upload a custom MusicXML, MuseScore, or MIDI score, the client queries Featherless AI to analyze the complexity of the piece, classify its difficulty, and provide custom learning tips.
If no Featherless API key is configured, the application falls back to robust local rule-based evaluations, supporting offline use.
- High-Contrast Scrolling Staff: Thicker, high-contrast staff lines (2.0px) with dynamic ledger lines, rests, and note flags (eighth/sixteenth notes).
- Zero-Lag Intonation Gauge: Real-time autocorrelation pitch tracking optimized for brass frequencies (130Hz - 1200Hz) running at a throttled 22 FPS to prevent main-thread lag.
- Late-Hit Latency Window: A 200ms reaction buffer compensates for natural delay, ensuring late blows are still credited correctly instead of resulting in false misses.
- Popular Practice Library: Built-in interactive lessons for Ode to Joy, Amazing Grace, Twinkle Twinkle Little Star, Jingle Bells, and Happy Birthday.
- Dynamic Intonation Tolerances: Select relaxed (plus/minus 45 cents), normal (plus/minus 35 cents), or strict (plus/minus 20 cents) tuning tolerances.
- Smart Prompt Suppression: Displays piston valves only when playing a wrong pitch; if you are playing the correct note name but are slightly out of tune, the fingering prompt is suppressed so you can focus on centering the pitch.
- Trailing Note History: Expanded playhead layout keeps 3+ beats of completed notes visible on screen so you can track your accuracy history.
Ensure you have Node.js installed.
npm installCreate a .env file in the root directory and add your API key:
VITE_FEATHERLESS_API_KEY=your_featherless_api_key_herenpm run dev- Development Mode (with Live Reload):
npm run electron:start
- Production Mode (loads local compiled code):
npm run electron:build
To compile a standalone Windows folder containing the executable binary (TrumpetPracticeHero.exe):
npm run electron:packThe packaged binary will be generated under the dist-desktop/TrumpetPracticeHero-win32-x64/ directory.
src/modules/audio-engine.js: Web Audio API pitch-tracking and autocorrelation module.src/modules/game-engine.js: Staff canvas rendering, rhythmic notes, ledger lines, and game scoring loop.src/modules/music-parser.js: Parsers for MusicXML, MuseScore, and standard binary MIDI sheets.src/modules/featherless-client.js: Client connector for the Featherless.ai completions endpoint.src/modules/ai-advisor.js: Visualizes cent graphs and prepares analytics summaries.electron-main.cjs: Electron desktop container shell entry point.