Troubleshooting

What to do when OnKey won't start, can't hear, can't name a song, or is out of time with your headphones.

It stays on "Starting OnKey…"

This normally takes a few seconds. If it's still there after a minute, quit OnKey (⌘Q) and open it again. If that doesn't help, report a problem.

Permission questions

OnKey asks for three things in setup:

• Microphone: if you said no, go to System Settings → Privacy & Security → Microphone and turn OnKey on.
• System audio recording: needed to hear the music app. If you said no, or OnKey says it "can't hear … yet", go to System Settings → Privacy & Security → Screen & System Audio Recording and turn OnKey on under System Audio Recording Only.
• Control of Spotify and Apple Music: setup asks macOS for each app that's open. An app that isn't open asks the first time you play a song in it. If the question doesn't appear, click Carry on. macOS asks the first time you play a song there. To change your answer, go to System Settings → Privacy & Security → Automation → OnKey, or use Let OnKey control in OnKey's Settings.

The buttons in OnKey's messages open the right page of System Settings. macOS may ask you to reopen OnKey after you change a permission.

A new song takes a while to be named

New songs are named by Shazam, which needs an internet connection, and the first answer after installing can be slow. Keep the song playing, as OnKey keeps asking. If it says Shazam can't be reached, check your connection. Songs you've already learned are still recognised on your Mac. Allowing control of Spotify or Apple Music is quicker, as OnKey can ask the app what's playing.

No notes on a song

OnKey learns a song after its first play ends, and the Sing button says "Learning…" until it's done. One song is learned at a time, so others say "Waiting to learn". Learning also pauses while you sing a song OnKey already knows ("Waiting while you sing"), so the notes stay smooth. A song counts as learned once OnKey has heard about 70% of it, so if you skipped around, play it through once more.

The notes are dim and say "Lining up with the song…"

OnKey keeps the notes dimmed until the music confirms where you are, so you never sing to notes in the wrong place. It usually takes a few seconds after a song starts or after you skip. If it stays dim, check the music app's own volume isn't turned right down, as OnKey needs to hear it. Turn the app up and use your Mac's volume instead.

On a first play the lyrics show a whole line at a time

That's expected. Until a song is learned, OnKey doesn't know when each word is sung, so it shows the whole line. From the next play the words are on the note bars.

Lyrics early or late on headphones?

OnKey allows for how long your headphones or speakers take to play the sound, using the figure macOS reports for each output. In my tests that was close enough, Bluetooth included, so there’s nothing to set.

If the notes still look early or late, OnKey may not have lined up with the song yet. Give it a few seconds, or skip back a little. Your score isn’t affected either way, as OnKey works out your delay after each song. If it keeps happening on one pair of headphones, please tell me which ones.

No lyrics, or the wrong ones

Lyrics come from LRCLIB, a free, community-run database. Some songs aren't in it, or only in a different version. When it finds nothing, OnKey asks again after a day.

Your Mac feels busy

Learning a new song is the heavy part, so OnKey does it after the song ends, at low priority. Singing a learned song is light. Two settings help:

• Save battery while singing (on by default): on battery, the notes are drawn 30 times a second instead of 60.
• Keep learning models ready (on by default only with 32 GB or more): turn it off and the models (about 1.5 GB) are unloaded after each song. On 8 GB Macs it isn't shown, as they're always unloaded.

Where the logs are

OnKey writes a plain-text log to $TMPDIR/onkey.log. To open it, run this in Terminal:

open $TMPDIR/onkey.log

It also keeps each day's log and a short summary of each play (timings, CPU, memory, build, and Mac) in the records/ folder of its data folder, for 30 days and at most 200 MB. They hold no audio or lyrics, but they do name the songs you played.

Report a problem

1. Choose Report a problem in Settings or Help → Report a Problem…, or Report a problem with this take on a take's page.
2. OnKey shows you what goes in the zip: the last three days of its log and a summary of each play. No lyrics, audio, recordings, user name, or home folder. Add a note if you like, then Save it on your Mac. Nothing is uploaded.
3. Choose Open a GitHub issue (or go to GitHub), say what happened and with which song, and attach the zip if you're happy to.

More answers in the FAQ. Or ask in OnKey's Discord.