Set up YouTube search
Search for a song on a fresh install and HomeKaraoke answers with a screen headed “YouTube Search Not Configured”. It wants one of two things, and you only need one of them. The in-app screen walks you through the first; this page covers both, including where yt-dlp has to sit before the app can find it. Playing video files you already own needs neither.
Pick one
A YouTube Data API key
Free, official, and nothing extra to install. You create a key in the Google Cloud console and paste it into Settings. Google allows roughly 100 searches a day at no cost. This is the one to pick on Windows.
yt-dlp
A separate program you install yourself, plus a setting to switch afterwards. No key, no daily limit, and it unlocks the higher-quality playback mode. HomeKaraoke may fail to find it on Windows.
Route 1: a YouTube Data API key
1. Create a Google Cloud project
Open the Google Cloud console and create a project. The name does not matter.
2. Enable YouTube Data API v3
Find it in the API library and enable it for the project you just created.
3. Create an API key
Under Credentials, create an API key and copy it.
4. Paste it into HomeKaraoke
Open Settings, go to the YouTube tab, and paste the key. Search works from that moment.
Google gives each project 10,000 free units a day and charges 100 units per search, which comes to about 100 searches. Queueing, playback and your local library do not touch that quota.
Route 2: yt-dlp
yt-dlp is a command-line tool that HomeKaraoke can use for both search and playback. It needs no key and has no daily limit. It also unlocks the yt-dlp playback mode, which streams video into the player instead of embedding YouTube and lets you choose a quality up to 1080p.
# macOS, with Homebrew
brew install yt-dlp
# Any system with Python
pip install --user yt-dlpHomeKaraoke can also do it for you. Open Settings, go to Advanced, and use the installer there; it offers Homebrew, pip and a direct download.
Installing it is only half the job
HomeKaraoke will not pick yt-dlp up on its own. The search method is a setting, and a fresh install has it on the API key. Until you open Settings, go to the YouTube tab and switch the search method to yt-dlp, the app never even checks whether the binary is there, and search keeps reporting that it is not configured.
Then where you put it matters
Once you have flipped that switch, HomeKaraoke goes looking, and it does not read your PATH. It checks ~/.local/bin and four fixed directories: /opt/homebrew/bin, /usr/local/bin, /usr/bin and /bin. Both commands above land in one of those, which is why they work. Put yt-dlp anywhere else and the app will not see it, on any system. The same lookup finds ffmpeg, so it applies there too.
Windows: expect this to fail
Every directory in that list is a Unix path, and the app looks for a file named yt-dlp with no .exe suffix, so on Windows there is nowhere you can put it that HomeKaraoke will check. We found this in the code and no user has reported it, so try it if you want, but use the API key if search stays empty.
What works without either
Adding folders of video files, browsing your library, the queue, singers, favourites and playback of local files all work with no key and no yt-dlp. So does YouTube playback itself, because the default player embeds YouTube directly, which means songs your guests request during a hosted session play without any of this. Only the search box needs one of the two routes above.
Questions
- I searched and got "YouTube Search Not Configured".
- That screen means HomeKaraoke has no way to reach YouTube search yet. Add a YouTube Data API key or install yt-dlp and the search box starts working. Nothing is broken, and there is no account to create with us. The in-app screen only describes the API key route, so if you would rather use yt-dlp, follow route 2 below.
- Is the API key free?
- Yes. Google gives each project 10,000 units a day and one search costs 100, so you get roughly 100 searches a day at no cost. You need a Google account and a project in the Google Cloud console; the free quota does not require a paid plan.
- Which should I pick, the key or yt-dlp?
- The key takes about five minutes and then stays out of your way. yt-dlp removes the daily search limit and unlocks the higher-quality playback mode, at the cost of installing a separate program, remembering to switch the search method afterwards, and updating the binary yourself. On Windows, pick the key.
- Do I need yt-dlp to play anything?
- No. The default player embeds YouTube and needs nothing extra. yt-dlp playback is a separate mode under Settings, Advanced: it streams the video into the player instead of embedding it, and lets you choose a quality up to 1080p.
- I installed yt-dlp and the app still does not see it.
- Check the setting first. HomeKaraoke does not pick yt-dlp up automatically: open Settings, go to the YouTube tab and switch the search method to yt-dlp, because until you do that the app never looks for it. If you have switched and it is still not found, the location is the next suspect. HomeKaraoke ignores your PATH and only checks ~/.local/bin, /opt/homebrew/bin, /usr/local/bin, /usr/bin and /bin, so move or symlink the binary into one of those. On Windows none of those paths exist, so use the API key instead.
- What does ffmpeg do?
- It only touches your local library. HomeKaraoke calls ffmpeg while scanning your folders, to read how long each file is and to generate a thumbnail. Without it your files still play; they just show no thumbnail and no duration.
- I added the key and search still finds nothing.
- Check that YouTube Data API v3 is enabled on the same Google Cloud project the key belongs to, and that the key went into Settings, YouTube rather than somewhere else. If you were counting on yt-dlp under Windows, switch to the key.