Metadata-Version: 2.4
Name: yt-tui
Version: 1.0.0
Summary: Terminal-native YouTube client — search, preview, and stream videos, no API key needed
Author-email: Yashwanth Kumar <yashwanthkumarniat@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/yashwanth-kumar-26/yt-tui
Project-URL: Repository, https://github.com/yashwanth-kumar-26/yt-tui
Project-URL: Bug Tracker, https://github.com/yashwanth-kumar-26/yt-tui/issues
Keywords: youtube,tui,terminal,yt-dlp,mpv,streaming
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: yt-dlp>=2024.1.1
Requires-Dist: textual>=0.52.0
Requires-Dist: httpx>=0.27.0
Dynamic: license-file

<p align="center">
  <img src="yt_tui/yt-tui.png" alt="YT-TUI Logo" width="512" />
</p>

<h1 align="center">YT-TUI</h1>

<p align="center">
  <strong>A lightweight, terminal-native YouTube client</strong><br/>
  Search, preview, and stream videos — no API key required, no browser needed.
</p>

<p align="center">
  <a href="https://github.com/Yashwanth-Kumar-26/yt-tui"><img src="https://img.shields.io/badge/Python-3.10+-blue?logo=python" /></a>
  <a href="https://github.com/Yashwanth-Kumar-26/yt-tui"><img src="https://img.shields.io/badge/Textual-TUI-green?logo=terminal" /></a>
  <a href="https://github.com/Yashwanth-Kumar-26/yt-tui"><img src="https://img.shields.io/badge/License-MIT-yellow?logo=law" /></a>
  <a href="https://github.com/Yashwanth-Kumar-26/yt-tui"><img src="https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-blue?logo=terminal" /></a>
</p>

---

## Quick Install (from PyPI)

```bash
# 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](https://mpv.io/) and [chafa](https://hpjansson.org/chafa/) are installed on your system (see [Requirements](#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](https://mpv.io/)** — video & audio playback
- **[chafa](https://hpjansson.org/chafa/)** — thumbnail rendering (optional — thumbnails silently skip if missing)

### Install System Dependencies

```bash
# 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](https://docs.astral.sh/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

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

### Windows

```cmd
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:

```bash
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

```bash
# 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

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

Or via `uv`:
```bash
cd yt-tui
uv run -- pytest tests/ -v
```

## Acknowledgement

YT-TUI is built on top of the incredible [yt-dlp](https://github.com/yt-dlp/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:

```bash
# 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:

```bash
# Install build tools
pip install build twine

# Build
python -m build

# Upload to PyPI
twine upload dist/*
```

Requires a [PyPI account](https://pypi.org/account/register/) 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`.
