vid/ytm-player: YouTube Music TUI client with vim keybindings, synced lyrics, and cross-platform media keys

YouTube Music TUI client with vim keybindings, synced lyrics, and cross-platform media keys https://ytm-player.com/

cli mpv music-player python terminal textual tui vim-keybindings youtube-music

Python 99.4%
Nix 0.5%

Find a file

Vid Plavšić ee16e69024 Some checks failed CI / lint (push) Successful in 1m6s Details CI / typecheck (push) Successful in 1m34s Details CI / test (ubuntu-latest, 3.10) (push) Failing after 1m58s Details CI / test (ubuntu-latest, 3.14) (push) Failing after 1m36s Details CI / test (macos-latest, 3.10) (push) Has been cancelled Details CI / test (macos-latest, 3.14) (push) Has been cancelled Details CI / test (windows-latest, 3.10) (push) Has been cancelled Details CI / test (windows-latest, 3.14) (push) Has been cancelled Details Merge branch 'master' into worktree-album-art-reload # Conflicts: # CLAUDE.md		2026-08-19 04:15:45 +02:00
.github	chore(deps): bump actions/setup-python in the gha-major group (#120 )	2026-08-13 20:22:46 +04:00
aur	chore(aur): bump PKGBUILD pkgver to 2.0.0	2026-07-05 04:08:47 +02:00
docs	fix(stream): stop resolving URLs mpv is forbidden to open	2026-08-19 03:38:37 +02:00
scripts	feat(release): add Python .SRCINFO regenerator (no Arch required)	2026-04-29 23:54:03 +02:00
src/ytm_player	Merge branch 'master' into worktree-album-art-reload	2026-08-19 04:15:45 +02:00
tests	Merge branch 'master' into worktree-album-art-reload	2026-08-19 04:15:45 +02:00
.gitattributes	chore: .gitattributes for line endings + expand .gitignore	2026-04-17 04:47:48 +02:00
.gitignore	chore: gitignore local reasoning/ working notes	2026-06-28 20:31:06 +02:00
.pre-commit-config.yaml	chore(tooling): adds pre-commit, pyright CI, and dbus-fast migration (#83 )	2026-05-04 16:17:58 +02:00
CHANGELOG.md	fix(stream): stop resolving URLs mpv is forbidden to open	2026-08-19 03:38:37 +02:00
CLAUDE.md	Merge branch 'master' into worktree-album-art-reload	2026-08-19 04:15:45 +02:00
CONTRIBUTING.md	feat(mpris): bundle dbus-fast as a core Linux dependency	2026-06-28 20:31:06 +02:00
flake.lock	chore(flake): bump nixpkgs pin to a Hydra-built channel rev	2026-06-12 08:00:25 +02:00
flake.nix	fix(nix): make `ytm`, `pytest` and `ruff` actually work in the dev shell	2026-08-19 02:27:21 +02:00
LICENSE	fix: comprehensive 8-phase audit — security, performance, DRY, UX	2026-02-10 22:47:16 +01:00
pyproject.toml	chore: prune unused responses dev dep, fix stale docs	2026-07-03 01:24:01 +02:00
README.md	chore(release): v1.9.4	2026-06-19 10:38:02 +02:00
RELEASING.md	docs(release): AUR pkgver is now derived from __version__ by CI	2026-07-05 04:22:57 +02:00
SECURITY.md	docs: SECURITY.md (private vuln reporting) and CONTRIBUTING.md (dev guide)	2026-04-17 04:51:36 +02:00

README.md

ytm-player — YouTube Music in your terminal — synced lyrics, vim keys, mpv backend. Runs on Linux, macOS, Windows. Free-tier supported.

Available on PyPI, AUR, NixOS, and Gentoo — actively maintained with cross-platform support.

Features

Vim-style keybindings — j/k movement, multi-key sequences (g s for search, g l for 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-player

# Arch / 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, @Gimar250, @Wiibleyde, @szx19970521, @aaguilar-hub, @TheoBassaw, @holstvoogd, and @ProfessionalGriefer for bug reports, fixes, packaging, and platform support.

Changelog

See CHANGELOG.md for the full release history.