NAME
ytm-player — YouTube Music TUI client with vim keybindings, synced lyrics, and cross-platform media keys
SYNOPSIS
pip install ytm-playerINFO
DESCRIPTION
YouTube Music TUI client with vim keybindings, synced lyrics, and cross-platform media keys
README
Available on PyPI, AUR, NixOS, and Gentoo — actively maintained with cross-platform support.
Features
- Vim-style keybindings — j/k movement, multi-key sequences (
g sfor search,g lfor library), count prefixes (5j) - Synced lyrics — live-highlighted with LRCLIB fallback for tracks YouTube doesn't have, with title sanitization for better LRCLIB matches
- mpv backend — gapless audio, stream prefetching, broad codec support
- Cross-platform native integrations — MPRIS (Linux), Now Playing (macOS), media keys (Windows)
- Theming — 18+ Textual themes plus per-app color overrides in
theme.toml - Spotify import — pull playlists in via API or scraper fallback
- CLI + IPC — control a running TUI from another terminal (
ytm play,ytm pause, etc.) - Free-tier support — works without YouTube Music Premium
- Session resume — last-playing track + queue restored on launch
- Local cache — LRU audio cache for offline-like replay of previously heard tracks
- Discord + Last.fm — Rich Presence and scrobbling
Requirements
- Python 3.10+
- mpv (audio playback backend, must be installed system-wide)
- A YouTube Music account (free or Premium)
Install
# PyPI (Linux / macOS / Windows) pip install ytm-playerArch / CachyOS / Manjaro (AUR)
yay -S ytm-player-git
For NixOS, Gentoo, Windows-specific mpv DLL setup, source builds, and optional extras (Discord, Last.fm, Spotify import, etc.), see docs/installation.md.
Quickstart
ytm setup # one-time auth (auto-detects browser cookies)
ytm # launch the TUI
Windows: replace ytm with py -m ytm_player.
Documentation
| Topic | Link |
|---|---|
| Per-platform install + optional extras | docs/installation.md |
config.toml + theme.toml reference | docs/configuration.md |
| Full keyboard + mouse keybindings | docs/keybindings.md |
All ytm CLI subcommands | docs/cli-reference.md |
| Spotify playlist import | docs/spotify-import.md |
| Troubleshooting (mpv / auth / MPRIS / macOS / cache) | docs/troubleshooting.md |
| File layout + stack | docs/architecture.md |
| Contributing | CONTRIBUTING.md |
| Security policy | SECURITY.md |
Contributors
Thanks to @dmnmsc, @Villoh, @valkyrieglasc, @dsafxP, @Thayrov, @glywil, @Kineforce, @CarterSnich, @Tohbuu, @nitsujri, @uhs-robert, @moschi, @firedev, @wgordon17, @gitiy1, @hanandewa5, @aimar-a, and @Gimar250 for bug reports, fixes, packaging, and platform support.
Changelog
See CHANGELOG.md for the full release history.