yt-tui 1.0.0

Terminal-native YouTube client — search, preview, and stream videos, no API key needed

YT-TUI

A lightweight, terminal-native YouTube client
Search, preview, and stream videos — no API key required, no browser needed.

---

Quick Install (from PyPI)

# Install globally (recommended — use from anywhere)
pip install yt-tui

# Or with uv (faster)
uv tool install yt-tui

# Then run
yt-tui

Before running: make sure mpv and chafa are installed on your system (see Requirements). These system binaries cannot be installed via pip.

---

Features

• Universal Search — keywords or direct YouTube video/playlist URLs
• Side Navigation — switch between Search and History views
• Persistent History — searches and watch history saved across sessions
• Playlist Support — auto-extract and list all videos from playlist links
• Playback Options — Video or Audio-only mode per session
• Autoplay — auto-advance through playlist tracks
• Incognito Mode — run without saving search or watch history
• Asynchronous Thumbnails — high-performance ANSI-art previews, non-blocking

Requirements

• Python 3.10+
• mpv — video & audio playback
• chafa — thumbnail rendering (optional — thumbnails silently skip if missing)

Install System Dependencies

# Fedora
sudo dnf install mpv chafa

# Ubuntu / Debian
sudo apt install mpv chafa

# Arch
sudo pacman -S mpv chafa

# macOS (Homebrew)
brew install mpv chafa

# Windows (Scoop)
scoop install mpv chafa

# Windows (Winget)
winget install shinchiro.mpv chafa

Installation

YT-TUI uses uv (a fast Python package manager) to install itself as a global tool — works from any directory, no virtual environment activation needed.

Quickest way: Run the setup script for your OS — it installs everything and prompts you to choose your preferred download quality (video resolution + audio bitrate). Skip the prompt to keep the defaults.

Unix/Linux/macOS

git clone https://github.com/Yashwanth-Kumar-26/yt-tui.git
cd yt-tui
chmod +x setup.sh
./setup.sh

Windows

git clone https://github.com/Yashwanth-Kumar-26/yt-tui.git
cd yt-tui
setup.cmd

Manual Install (any OS)

If you already have uv installed and want to skip the quality prompt:

cd yt-tui
uv tool install .

Note: The setup scripts automatically install uv if missing, resolve Python 3.10+, install system deps (mpv, chafa), install yt-tui globally, and prompt you to configure download quality.

Usage

# Normal mode — history is saved
yt-tui

# Incognito mode — no search/watch history saved
yt-tui incog

The TUI launches with the search bar focused. Type a keyword or paste a YouTube URL and press Enter.

Playback Flow

1. Search results appear as a table
2. Navigate with ↑ / ↓ — thumbnail preview updates live
3. Press Enter on a video
4. Choose Video or Audio mode
5. mpv launches for playback
6. Press q inside mpv to return to YT-TUI

If autoplay is ON (toggle with a), the next video starts automatically when the current one ends.

Keyboard Reference

Key	Action
F1	Toggle help screen
/	Focus search bar
s	Switch to Search tab
h	Switch to History tab
a	Toggle Autoplay (ON / OFF)
↑ / ↓	Navigate results
Enter	Choose play mode and play selected video
Ctrl+Q	Quit

mpv Playback Controls

Key	Action
Space	Pause / resume
← / →	Seek backward / forward
↑ / ↓	Volume up / down
q	Stop playback and return to YT-TUI

Running Tests

cd yt-tui
pip install pytest
pytest tests/ -v

Or via uv:

cd yt-tui
uv run -- pytest tests/ -v

Acknowledgement

YT-TUI is built on top of the incredible yt-dlp project. Massive thanks to the yt-dlp maintainers and community for keeping YouTube accessible and open.

Notes

• Uses yt-dlp for YouTube access — no API key needed
• All user data stored in ~/.yt-tui/ as flat JSON
• Cross-Platform: tested on Linux, Windows, and macOS
• Thumbnails: require a terminal with Unicode/ANSI support (Windows Terminal, iTerm2, modern Linux terminal). Silently disabled if chafa is not installed
• Audio Mode: mpv runs with --no-video to save bandwidth
• Incognito Mode: yt-tui incog skips all history writes for the session

Download Quality

YT-TUI uses different format strings for Video and Audio playback modes. Both are configurable independently via env vars.

Defaults

Mode	Format String	Meaning
Video	bestvideo[height<=1080]+bestaudio/bestvideo+bestaudio/best	1080p video + best audio, falls back to best available
Audio	bestaudio/best	Highest quality audio stream only (no video data wasted)

Configuration

The setup scripts (setup.sh / setup.cmd) prompt you to pick separate video resolution and audio bitrate during installation. These values get combined into a single YT_TUI_QUALITY env var, which is used for both modes — audio-only mode automatically strips the video part.

Video Quality Options

Preset	Height Cap	Format Part
4K	2160p	bestvideo[height<=2160]
1440p	1440p	bestvideo[height<=1440]
1080p	1080p	bestvideo[height<=1080]
720p	720p	bestvideo[height<=720]
480p	480p	bestvideo[height<=480]
360p	360p	bestvideo[height<=360]
Best	no cap	bestvideo

Audio Quality Options

Preset	Bitrate Cap	Format Part
320 kbps	320	bestaudio[abr<=320]
256 kbps	256	bestaudio[abr<=256]
192 kbps	192	bestaudio[abr<=192]
128 kbps	128	bestaudio[abr<=128]
Best	no cap	bestaudio

How Audio-Only Mode Works

When you select Audio in the TUI, YT-TUI builds a format string that only requests audio streams — no video data is downloaded:

• If YT_TUI_AUDIO_BITRATE is set (e.g. 320): bestaudio[abr<=320]/bestaudio/best
• Otherwise: bestaudio/best

This means your audio bitrate preference is honored in both Video and Audio modes, but Audio mode doesn't waste bandwidth downloading video.

Fallback Behavior

The Video mode format includes a fallback chain. For example, if you pick 4K video + 320 kbps audio:

bestvideo[height<=2160]+bestaudio[abr<=320]/bestvideo+bestaudio/best

1. Try your chosen combo (e.g. 2160p video + 320kbps audio)
2. If unavailable, try best video + best audio (uncapped)
3. If still fails, pick the best single stream that works

Manual Override

After install, change quality anytime via the YT_TUI_QUALITY env var:

# 720p + 192kbps
export YT_TUI_QUALITY="bestvideo[height<=720]+bestaudio[abr<=192]/bestvideo+bestaudio/best"
yt-tui

# Best video + 320kbps audio
export YT_TUI_QUALITY="bestvideo+bestaudio[abr<=320]/bestvideo+bestaudio/best"
yt-tui

# Best available (no limits at all)
export YT_TUI_QUALITY="bestvideo+bestaudio/best"
yt-tui

To persist:

• Linux/macOS: edit YT_TUI_QUALITY in ~/.bashrc, ~/.zshrc, or ~/.profile
• Windows: run setx YT_TUI_QUALITY "format-string" (then restart terminal)

Publishing to PyPI

To publish a new release:

# Install build tools
pip install build twine

# Build
python -m build

# Upload to PyPI
twine upload dist/*

Requires a PyPI account and API token. The package is pure Python (py3-none-any wheel) and includes ui.tcss automatically. Before publishing, bump the version in yt_tui/__init__.py and pyproject.toml.