ytplay-cli 0.5.0

Stream, browse, and play YouTube videos from any terminal — Linux, macOS, Windows, and Termux

yt-cli

Search, preview, and stream YouTube from any terminal.

yt-cli is a lightweight command-line tool to search YouTube, browse results interactively with a live preview panel, and play or download videos — all without leaving the terminal. It works on Linux, macOS, Windows, and Android (Termux).

yt "lofi hip hop"
yt "duvet x vagabond" --audio
yt queue add "chill beats" && yt queue play

---

What's new in v0.5.0

• Android / Termux full video support — extracts direct stream URLs via yt-dlp and opens them in the mpv-android app for hardware-decoded playback
• Persistent queue — add songs across sessions, play them in order
• Cache layer — search results cached to disk (TTL configurable), instant re-searches
• Cross-platform browser launch — works on Linux, macOS, Windows, and Android
• Termux-X11 support — GPU context correctly configured (x11egl) for X11 video
• Audio volume fix on Android — system volume keys now control playback
• fzf Esc safety — cancelling any menu no longer crashes mpv
• Removed jq dependency — preview panel is pure Python

---

Features

• Search YouTube and browse results with fzf interactive fuzzy finder
• Live preview panel — title, channel, views, duration, upload date
• Optional thumbnail rendering with chafa or timg
• Play video at selected quality (360p → 1080p)
• Play audio only — volume keys work on Android
• Download with yt-dlp (merged mp4 output)
• Open in browser — works on all platforms including Android
• Playlist playback — pass any YouTube playlist URL
• Queue — add videos across sessions, play in order
• History — searchable log of past queries
• Disk cache — avoids repeated network calls for same query
• Runs on Linux, macOS, Windows, Android/Termux

---

Requirements

These must be installed separately (yt-cli checks and installs them on first run):

Tool	Purpose	Install
mpv	Video/audio playback	apt install mpv / brew install mpv / pkg install mpv
fzf	Interactive search UI	apt install fzf / brew install fzf / pkg install fzf
yt-dlp	YouTube metadata + streams	installed automatically via pip

Android only: Install the mpv for Android app from the Play Store for full video playback.

---

Installation

Recommended — pipx (isolated, globally available)

pipx install ytplay-cli

Install pipx first if needed:

# Ubuntu / Debian
sudo apt install pipx && pipx ensurepath

# macOS
brew install pipx && pipx ensurepath

# Termux
pkg install python && pip install pipx

Alternative — pip

pip install ytplay-cli

From source

git clone https://github.com/naveen07-c/yt-cli
cd yt-cli
pip install -e .

---

Usage

yt <query>                Search and play a video
yt <query> --audio        Play audio only
yt <query> --download     Download the video
yt <query> --no-cache     Skip cache, fetch fresh results

yt playlist <url>         Play a full YouTube playlist

yt queue add <query>      Add top result to queue
yt queue list             Show queued videos
yt queue play             Play all queued videos
yt queue clear            Clear the queue

yt history                Show past searches
yt cache clear            Delete cached search results
yt --version              Show version

Examples

yt "synthwave mix"
yt "lofi hip hop" --audio
yt "duvet bôa" --download
yt playlist https://youtube.com/playlist?list=PLxxxxx
yt queue add "chill beats"
yt queue add "night drive music"
yt queue play

---

Android / Termux setup

# 1. Install dependencies in Termux
pkg install python mpv fzf

# 2. Install yt-cli
pip install ytplay-cli

# 3. Install mpv for Android from the Play Store
#    (search "mpv for Android" — package: is.xyz.mpv)

# 4. Play
yt "your favourite song"

yt-cli automatically extracts the direct stream URL using yt-dlp and sends it to the mpv Android app — no Termux-X11 needed for video.

---

Configuration

Config file is created automatically at ~/.config/yt-cli/config.json on first run.

{
  "default_quality": "1080",
  "default_speed": "1",
  "cache_ttl_minutes": 30,
  "termux_mode": "auto",
  "new_window": false,
  "result_limit": 30
}

Key	Values	Description
default_quality	360 480 720 1080 best	Default video quality
default_speed	0.5 – 2	Default playback speed
cache_ttl_minutes	any integer	How long search results are cached
termux_mode	auto tct	auto = detect X11/APK; tct = force audio-only
result_limit	any integer	Number of search results shown

---

Cache Management

yt-cli caches search results to disk so repeated searches are instant. The cache lives at ~/.cache/yt-cli/ and expires automatically based on cache_ttl_minutes (default 30 minutes).

Clear the entire cache from the terminal:

yt cache clear

You'll see a confirmation like:

✓ Removed 12 cached result(s).

Skip the cache for a single search (fetches fresh results without clearing everything):

yt "lofi hip hop" --no-cache

When you should clear the cache:

• Search results feel stale or outdated
• A video you know exists is not showing up
• You want to see updated view counts or titles
• After updating yt-dlp with pip install -U yt-dlp

The cache files are plain JSON stored at ~/.cache/yt-cli/. You can also wipe them manually if needed:

# Linux / macOS / Termux
rm -rf ~/.cache/yt-cli/

# Windows (PowerShell)
Remove-Item -Recurse "$env:LOCALAPPDATA\yt-cli\cache"

---

Links

• PyPI: https://pypi.org/project/ytplay-cli/
• GitHub: https://github.com/naveen07-c/yt-cli
• Issues: https://github.com/naveen07-c/yt-cli/issues