Installation Guide

Download HTK from htk.rocks/download, then follow the steps for your platform below.

Windows Installation

HTK runs as a standalone .exe — no Python required. You just need to install two free external tools first.

1 Install FFmpeg

FFmpeg handles all audio and video processing. Open a terminal (Command Prompt or PowerShell) and run:

winget install Gyan.FFmpeg

If you don't have winget, download FFmpeg manually from gyan.dev/ffmpeg/builds — grab the release full build, extract it (e.g. to C:\ffmpeg), and add the bin folder to your system PATH.

2 Install Node.js

Node.js is needed for YouTube video downloads. Install it with:

winget install OpenJS.NodeJS.LTS

Or download the LTS installer from nodejs.org.

3 Verify both installs

Open a new terminal window and run:

ffmpeg -version
node --version

Both should print version info. If either says "not recognized", restart your terminal or check your PATH.

4 Run HTK

Double-click HTK.exe. On first launch it creates its data folders automatically.

Windows SmartScreen warning? Click "More info" then "Run anyway". This appears because the app isn't code-signed — it's safe to run.

macOS Installation

HTK comes as a standard .app bundle. Install two dependencies via Homebrew and you're ready.

1 Install Homebrew

If you don't already have Homebrew, open Terminal and paste:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2 Install FFmpeg & Node.js

brew install ffmpeg node

3 Verify

ffmpeg -version
node --version

4 Run HTK

Move HTK.app to your Applications folder and double-click it.

Gatekeeper blocks the app? Since HTK isn't signed with an Apple Developer certificate, macOS will warn you on first launch. Right-click the app → Open → Open. Or go to System Settings → Privacy & Security and click "Open Anyway".

"HTK.app is damaged"? This is a quarantine flag, not actual damage. Fix it with:

xattr -cr /Applications/HTK.app

Raspberry Pi Installation

Tested on Raspberry Pi 5 with Raspberry Pi OS Trixie (64-bit). HTK ships as a standalone binary — no Python, venv, or pip required. You just need a handful of system libraries.

1 Install system libraries

HTK bundles Python and its Python packages, but still needs a few shared libraries from the OS (FFmpeg for media decoding, Qt/X11 libraries for the UI, Node.js for yt-dlp). Copy-paste this block into a terminal:

sudo apt update
sudo apt install -y \
    ffmpeg nodejs \
    libasound2 libportaudio2 \
    libegl1 libgl1 libglib2.0-0 libfontconfig1 libdbus-1-3 \
    libxkbcommon0 libxkbcommon-x11-0 \
    libxcb-xinerama0 libxcb-cursor0 \
    libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 \
    libxcb-render-util0 libxcb-shape0 libxcb-xfixes0

Optionally, remove the Wayland on-screen keyboard — it pops up over text fields and gets in the way on a KJ rig:

sudo apt remove --purge -y squeekboard

2 Download & extract

Grab the Raspberry Pi build from the download page and extract it wherever you want HTK to live (e.g. your home directory):

unzip htk_*_rpi.zip
cd HTK

3 Launch HTK

./HTK

On first launch HTK creates its data folders (downloads/, library/, banners/, logs/) next to the executable.

Dual-screen setup: The app auto-detects HDMI outputs. Plug your TV or projector into HDMI-1 (the second port) for lyrics, and HTK's control panel stays on your primary display. If the display window lands on the wrong screen, pick the right one in the Output tab — the choice is saved for next time.

Desktop shortcut & proper icon: HTK installs its own .desktop entry automatically on first launch — it writes ~/.local/share/applications/htk.desktop (so the taskbar and task switcher show the real icon instead of a generic genie lamp) and a double-click shortcut at ~/Desktop/HTK.desktop. Both entries point at wherever you extracted HTK. If you later move the HTK folder, just launch from the new location once — HTK detects the stale path and rewrites both entries.

Troubleshooting

"ffmpeg not found" or audio doesn't play

Make sure ffmpeg and ffprobe are on your system PATH. Open a terminal and run ffmpeg -version to verify.

YouTube downloads fail

This is usually caused by an outdated version of yt-dlp. A new build of HTK will include the latest version — check the download page for updates.

App doesn't start or crashes immediately

Check the logs folder next to the app for error details. The most common causes are missing FFmpeg, missing Node.js, or antivirus interference.

Display window doesn't appear on second screen

Go to the Output tab inside HTK and select the correct display. The app looks for HDMI-connected screens automatically but you can override it.

Next Steps

HTK is installed — now set up your profile, import your songs, and get ready to run your first show.

Read the Documentation →