bester-ytm

A local terminal YouTube Music companion: search, queue, and play music through mpv with DJ-style dual-deck crossfades, build playlists from plain English briefs with the AI provider of your choice, and publish them to your YouTube Music account.

• Terminal player — a Textual TUI with search, album browsing, an editable queue, local playlists, favorites, local audio files, web radio with live song names, and audio-reactive visuals.
• DJ transitions — the next track is prebuffered on a second silent mpv deck and blended in with an equal-power crossfade.
• Playlist builder — turn seed songs or a prose brief ("15 songs in the style of Blind Guardian, save as powermetal-15") into a reviewed plan, then create the real playlist in your account.
• AI, your way — briefs and similar-track suggestions run through the Codex CLI, the Claude Code CLI, any OpenAI-compatible endpoint (OpenRouter, Ollama, vLLM), the Anthropic API, or a fully offline heuristic.
• Local-first — credentials, plans, playlists, and settings live under your home directory; nothing leaves your machine except requests to YouTube Music and the AI provider you configure.

Runs on Linux and macOS (mpv is controlled over a Unix socket; on Windows use WSL2).

Quick start

Install the dependencies (uv, mpv, yt-dlp):

brew install uv mpv yt-dlp                  # macOS
sudo apt-get install -y mpv yt-dlp          # Ubuntu/Debian (uv: astral.sh/uv)
sudo pacman -S --needed uv mpv yt-dlp       # Arch Linux

Then, from a clone of this repository:

./install.sh    # registers the bester-ytm command (uv tool install)
bester-ytm      # launch the TUI

Search and playback work immediately — no account needed:

bester-ytm search "Beach House Myth"
bester-ytm play search "Beach House Myth" --seconds 20

In the TUI, radio: in the search box lists web radio stations (ByteFM and KALX built in, more via config) and shows the live song name while one plays; pasting a path like ~/Music lists and plays your local audio files.

Logging in (for account features)

Library playlists, playlist create/edit/delete, and liking songs on YouTube Music (f mirrors your local favorites as YTM likes, including the song a radio station is playing) need a login. The default takes seconds and no Google Cloud setup: sign in at music.youtube.com in any browser, then run bester-ytm auth login — it reads the login straight from your browser and verifies it. No browser access on this machine? bester-ytm auth login --paste takes a DevTools Copy as cURL request instead. Prefer a self-refreshing token? Create free Google OAuth credentials once and use bester-ytm auth login --oauth.

Both flows, step by step: Getting Started.

Documentation

Full documentation lives at fmschulz.github.io/bester-ytm:

• Getting Started — install and login
• Usage — TUI keys, search syntax, CLI commands
• Playlist Builder & AI — plans, briefs, AI providers
• Configuration — config.toml, data locations
• Architecture — the dual-deck engine

Development

uv sync
uv run pytest -q     # fast: no network, no mpv
uv run ruff check .
uv run mypy src

CI gates lint, types, and 80% test coverage on Python 3.11 and 3.13. See Development for layout and conventions, and CONTRIBUTING.md for how to propose changes.

License

MIT — see LICENSE.