prerequisites

freqhole can use ffmpeg and yt-dlp.

these are optional, but recommended.

---

ffmpeg

ffmpeg handles generating audio waveform images and using ffprobe for metadata. freqhole will look for it in your PATH and common install locations (/opt/homebrew/bin, /usr/local/bin, etc.).

macOS:

brew install ffmpeg

Linux:

sudo apt install ffmpeg   # debian/ubuntu
sudo dnf install ffmpeg   # fedora

---

yt-dlp

needed only if you want freqhole to fetch music from URLs. install via pip or download the binary directly,

see github.com/yt-dlp/yt-dlp for best installation instructions.

# pip (into a venv or with --break-system-packages on newer distros)
pip install yt-dlp

# or download the binary directly
curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o ~/.local/bin/yt-dlp
chmod +x ~/.local/bin/yt-dlp

freqhole will find yt-dlp automatically if it’s in your PATH or a common install location. for non-standard paths, set it explicitly in freqhole-config.toml:

[server.fetch_music]
fetch_command = "/full/path/to/yt-dlp ..."
precheck_command = "yt-dlp --print-json --no-download"

precheck_command enables the add-music review step before the actual download starts. use a metadata-only yt-dlp command here so freqhole can show you what will be fetched first.