Repository navigation
Getting started
- A computer: a Mac (Apple Silicon or Intel), a Windows 10/11 PC, or a Linux PC (x86-64).
- A TV or projector as a second screen. One screen also works; the video then opens in a window.
- Speakers, ideally connected with a cable (see Sound and delay).
- One or more microphones: USB microphones, a wireless microphone receiver, an audio interface, or a phone (see Phones).
- An internet connection: songs come from YouTube.
Download the installer from the latest release.
macOS. The package is not signed with a paid Apple certificate yet, so remove the download quarantine first, in Terminal:
xattr -d com.apple.quarantine ~/Downloads/YTKTV-*-macos-universal.pkgThen open the package. If the installed app still will not open, run
sudo xattr -dr com.apple.quarantine /Applications/YTKTV.app.
Windows. Run the setup program. If SmartScreen stops it, choose More info → Run anyway.
Linux. Make the AppImage executable (chmod +x YTKTV-*.AppImage) and run it.
- If mpv, the free video player YTKTV uses, is not installed yet, YTKTV offers to install
it: with Homebrew on macOS (
brew install mpv; without Homebrew it shows how to get it), by downloading the Windows build listed on mpv.io on Windows, or with your package manager on Linux. This happens once and needs the internet. - A short setup asks three things, each applied as soon as you choose it:
- Sound: the speakers. Press Play Test Sound to check.
- MV Screen: the TV. The music video moves there at once.
- Microphone: the microphone for channel 1. Say something; the bar moves when it hears you.
- On Windows and Linux, YTKTV may offer to download the vocal separation runtime that fits your graphics card. It is needed for the Instrumental mode and for scoring.
You can run the setup again at any time from Settings → Setup.
AirPlay and Miracast. The TV becomes a second display over Wi-Fi and gets the whole MV, lyrics and effects included. On a Mac: Control Centre → Screen Mirroring → pick the TV, then Use As Separate Display. On Windows: press Win + K and pick the TV. See Settings → TV Without a Cable.
Chromecast. A Chromecast (or a TV with Chromecast built in) cannot be a second display, so YTKTV films the MV screen and sends it as a live video instead: in Settings → TV Without a Cable → Chromecast, press Search, pick the TV and press Cast to Chromecast; Stop Casting (or quitting YTKTV) ends it, and the TV's own stop button ends it too.
- Picture only. The sound stays on the computer's speakers, where the microphones are mixed in; the TV gets a silent sound track.
- The picture arrives about 1–3 seconds late. Turn Picture delay of the TV up to its highest so the lyrics stay closer to what you hear.
- The computer and the Chromecast must be on the same network, and the MV screen must be open on the computer (it may sit behind other windows). Casting uses some processor time.
- Press Search, type a song, and press Select on a result (or Priority to play it next).
- The song appears on the TV. The first song of the evening takes a moment to load; the ones after it are prepared while the previous one plays.
- Choose Original or Instrumental in the control bar. Instrumental needs the vocal separation; until it is ready, the song waits ("Preparing instrumental").
- Turn on Lyrics and Score in the control bar if you like. While scoring, Guide shows the original singer's melody on the MV screen with your voice drawn on top; turn it off to keep the screen clean (the score still counts).
Guests can queue songs from their phones by scanning the QR code in the top right corner of the console or on the TV while nothing plays. See Phones.
Settings → Local Songs → Add Folder… adds a folder of video files (MP4, MKV, WebM, AVI, MOV,
MPG, VOB and more, in subfolders too). They show first when you search, and the Local page
lists them all. A file named Artist - Title.mkv shows the artist under the title.
- Two audio tracks (most karaoke MKVs): the instrumental track is copied out of the file, so Instrumental works at once, even on a computer without vocal separation. A track titled 伴奏, karaoke or instrumental is taken as the instrumental; otherwise the second one is.
- One audio track: the vocals are removed by the vocal separation, like a YouTube song.
-
Lyrics: put an
.lrcfile with the same name next to the video.
Press Look Again after adding files to a folder.
Press ⬇ on any song (or Downloads → Download All Favorites) to keep it on the computer: the video, its lyrics and its instrumental. Downloaded songs play from disk, so they work with no internet at all, and Downloads lists them with how much space they take. Remove deletes one.
Party → Duet colours the lyrics on the TV by who sings each line: blue for one singer, pink for the other, gold when both sing. The parts come from the marks many duet lyrics have (男/女/合, or M/F); lyrics without marks switch singer at each verse.
| Group | Buttons |
|---|---|
| Vocals | Original, Instrumental, More (Vocal Cut, Left Only, Right Only for old split-track videos) |
| Playback | Replay, Play/Pause, Skip, Score, Guide (the pitch guide), Lyrics, and the arrows that move the lyrics 0.1 s earlier or later |
| Key, Tempo | Key down/up (±6 semitones), slower/faster |
| Guide, Music, Mic | How much of the original singer stays in Instrumental mode; music volume; microphone volume |
| Crowd | Applause, Cheer, Air Horn, Drum Roll, Lights |
You can run the music without touching the mouse, in any YTKTV window (not while typing in a box):
| Keys | Does |
|---|---|
| Space, ⏯ | Play / pause |
| N, ⏭ | Next song |
| R, ⏮ | Sing it again |
| V, Enter / OK | Original / instrumental |
| ↑ ↓ (or + −) | Music louder / softer |
| → ← (or ] [) | Key up / down |
| L | Lyrics on / off |
| S | Scoring on / off |
USB and Bluetooth remotes and "air mouse" remotes send these same keys, so they work as they
are. A TV remote can drive YTKTV on a Raspberry Pi connected by HDMI: turn on the TV's
HDMI-CEC (it has a brand name such as Anynet+, SimpLink, Bravia Sync or EasyLink), then run
cec-ctl -d /dev/cec0 --playback once after the Pi starts. The remote's arrows, OK and play
keys then arrive like keyboard keys; which keys a TV passes on depends on the TV. Most desktop
computers have no CEC, so this does not work on them.
Choose the speakers in Mixer → MAIN OUT. Use speakers connected with a cable (HDMI to the TV, USB, or the headphone jack). AirPlay delays sound by one to two seconds and Bluetooth by a few hundred milliseconds: fine for watching, but you hear your own voice late when you sing. That delay is part of how wireless audio works and cannot be tuned away.
Keep microphones away from the speakers and do not point them at each other, or the sound will feed back (a loud squeal). The feedback guard helps, but distance helps more.
This page is copied from docs/guide in the repository. To change it, edit the file there (a pull request is welcome); edits made only here would be overwritten by the next copy.