https://github.com/zblauser/ytcli
Youtube music from the terminal, no auth.
https://github.com/zblauser/ytcli
audio-player cli music music-player terminal terminal-music-player tui youtube youtube-music youtube-music-tui yt-dlp zig
Last synced: about 3 hours ago
JSON representation
Youtube music from the terminal, no auth.
- Host: GitHub
- URL: https://github.com/zblauser/ytcli
- Owner: zblauser
- License: mit
- Created: 2026-05-31T05:46:01.000Z (25 days ago)
- Default Branch: main
- Last Pushed: 2026-06-01T05:52:56.000Z (24 days ago)
- Last Synced: 2026-06-01T07:24:04.463Z (24 days ago)
- Topics: audio-player, cli, music, music-player, terminal, terminal-music-player, tui, youtube, youtube-music, youtube-music-tui, yt-dlp, zig
- Language: Zig
- Homepage:
- Size: 10.9 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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.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 ``)
+ readme fix: `brew install mpv` already pulls in `yt-dlp`, `libmpv-dev` however does not
previous
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
```sh
zig build # → zig-out/bin/ytcli
zig build install --prefix ~/.local # → ~/.local/bin/ytcli
```
## dependencies
```sh
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, Linux, and FreeBSD binaries are attached to each [release](../../releases). windows: run under WSL (no native build currently).
## run
```sh
ytcli # TUI
ytcli # play first hit
ytcli -s # 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:
```sh
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 ` 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