ytcli

TUI client for yt music
search, browse, and play from your terminal

zig 0.16, single binary

• libmpv for audio
• shells out to curl and yt-dlp
  
• astats lavfi filter for visualizer via ffmpeg

version

v0.1.3

• selecting a track stops audio immediately + shows connecting to YouTube… in the now-playing footer
• fix album view mislabeling tracks with a related artist (reads album header, not first channel link)
• fix freeBSD release build (zig 0.16 translate-c: headers pulling <sys/time.h>, and __ssp fortify wrappers → std.c + _FORTIFY_SOURCE=0)
• macOS release is now one universal binary (arm64 + x86_64), cross-built + lipo'd on a single runner — no more scarce Intel-runner queue
• release CI timeout-minutes (fail fast instead of 24h runner-await hangs)

previous

v0.1.2

• failures log to ~/.local/share/ytcli/log (timestamp + cause)
  
• ctrl+c restores cleanly to terminal in all cases
  
• play video ids beginning with - (yt-dlp -- arg fix)
  
• fix freeBSD build (terminal size via std, not <sys/ioctl.h>)
  
• readme fix: brew install mpv already pulls in yt-dlp, libmpv-dev however does not

v0.1.1

• github actions for release builds
  
• prebuilt binaries: macOS, linux, freeBSD
  
• hardened temp writes (mkstemp, 0600)

v0.1

• autoplays through result list
• drills into albums
• handful of color themes

build/install

zig build                              # → zig-out/bin/ytcli
zig build install --prefix ~/.local    # → ~/.local/bin/ytcli

dependencies

install ex.
brew install mpv ffmpeg                # macOS (mpv pulls in yt-dlp)
apt install libmpv-dev yt-dlp ffmpeg   # Debian/Ubuntu

[ ! ] currently requires mpv, ffmpeg and yt-dlp particularly on PATH

releases

macOS (universal: arm64 + x86_64), Linux (arm64/x86_64), and FreeBSD binaries are attached to each release. windows: run under WSL (no native build currently).

run

ytcli               # TUI
ytcli <query>       # play first hit
ytcli -s <query>    # search, print results
ytcli history       # past queries
ytcli --theme cyan  # red (default) | cyan | mono | dracula | nord | gruvbox
ytcli --themes      # list themes
ytcli -h | -v

commands

made an effort to use commands that felt intuitive

view

typing:

• text to query ↑/↓
• pick suggestion tab/→
• accept completion ⏎ search
• esc clear
• Ctrl+T cycle filter (all/songs/videos/albums/artists)

results:

• j/k or ↑/↓ move
• g/G top/end
• Ctrl+F/B page
• h/esc back

playback/anytime:

• Ctrl+P/space pause
• Ctrl+N next
• Ctrl+S stop
• [/] seek ±10s
• {/} ±60s
• -/= volume ±5
• Ctrl+Y theme

storage/config

• $XDG_DATA_HOME/ytcli/history - query log (falls back to ~/.local/share/ytcli/history).
• $XDG_DATA_HOME/ytcli/log - timestamped failures (search/album/stream) with the underlying error and any curl/yt-dlp stderr. check here first when something says (see log).
• $XDG_CONFIG_HOME/ytcli/config - key=value settings.

history is just newline-delimited text - grep/cat it, or seed it so the TUI autocompletes your favorites from the first keystroke:

ex.
printf '%s\n' "elephant gym" "autechre" "john zorn" >> ~/.local/share/ytcli/history
grep -i jazz ~/.local/share/ytcli/history

[ ! ] loads newest-first and dedups, so re-seeding or reordering is harmless.

ytcli -s <query> prints title — artist [video_id], one per line; pipe it anywhere. YTCLI_THEME sets the theme without a flag.

[ ! ] requests written to /tmp/ytcli_body* (mkstemp, 0600, unlinked after) per call + audio streamed/buffered via mpv; not written to disk.

visualizer

simple spectrum bars via astats lavfi filter
dB to linear/modulated per bar - not a true per-band FFT

contribution

please feel free to contribute, not a guarantee it will be merged

[ ! ] thank you for your attention