OnKey: Transforming Bad Singers into Vocalists

OnKey is a complimentary, open-source vocal training application designed specifically for macOS. It allows users to practice their favorite songs by analyzing the audio playing on their system in real-time.

🎵 Overview

The app is designed to "save shower singers from themselves" (starting in 2026). Whether you are using Spotify, Apple Music, or YouTube via a web browser, OnKey helps you visualize your pitch accuracy.

The User Experience

1. The Learning Phase: During your first playback, the app provides lyrics and analyzes the lead singer's melody once the track concludes.
2. The Practice Phase: On subsequent plays, the notes scroll toward you. Your live pitch is mapped over the target notes, and you receive a performance score with a detailed line-by-line report.

---

🛠️ Installation & Setup

System Requirements

Getting Started

• Download OnKey.dmg from the latest GitHub release.
• Drag the OnKey icon into your /Applications folder.
• Grant permission for Microphone access (to capture your voice).
• Grant permission for System Audio Recording (to capture the music).
• Select the integration level for Spotify/Apple Music (choose Listen only to identify songs via audio alone).

---

⚙️ How It Works

OnKey utilizes a sophisticated pipeline to turn raw audio into a singing guide.

Technical Nuances

• Pitch Flexibility: The app recognizes singing an octave lower as correct.
• Timing: Minor delays in your delivery are not penalized.
• Local Processing: Your recordings and learned song data are stored locally on your Mac.
• The Science of Pitch: The app essentially tracks the fundamental frequency $f$, where $f = \frac{1}{T}$ (with $T$ being the period of the waveform), to determine your note accuracy.

External Data Requests

To function fully, OnKey communicates with the following services:

Privacy Note: You can toggle Shazam, lyrics, and update checks within the Settings menu. A full list of web addresses is available in scripts/release-hosts.txt.

---

⚖️ Fair Use & Legalities

OnKey is intended for private home practice using music you are legally entitled to play.

• Transcriptions: Melody transcriptions are for personal use; please do not publish or share them.
• Social Media: When sharing the app's voice/pitch videos, please use Instagram's licensed music library to add the backing track.
• Audio Quality: For the best results, use headphones. Using speakers may cause the music to bleed into your vocal recording.
• Contact: Rights holders can reach the developer at hello@singonkey.app (see LEGAL.md).

---

🆘 Support & Contribution

Reporting Issues

If you encounter a bug, use the Help menu or the report tool on a specific "take" page. The app generates a .zip file containing logs and numerical data (no audio recordings are included) to attach to your GitHub issue.

Building from Source

For those who prefer to compile their own binary, ensure you have an Apple Silicon Mac with Xcode command line tools, Rust, Node, and Python 3.

# Clone and install dependencies
git clone https://github.com/dsmurrell/onkey
cd onkey
npm install
npm --prefix ui install

# Setup Python environment and models
python3 -m venv .venv
.venv/bin/pip install -r scripts/requirements-models.txt
PYTHON=.venv/bin/python scripts/fetch-models.sh

# Build the application
npx tauri build

Note: Self-built versions cannot use the Shazam identification feature, as that requires a specific Apple signature.

Credits & Licensing

OnKey is released under the MIT License. It leverages the following technologies:

• CREPE & GAME
• wav2vec 2.0
• UVR's MDX-Net Karaoke 2

If you build upon this code, a backlink to the original repository is appreciated.