Metadata-Version: 2.1
Name: ytplay-cli
Version: 0.5.0
Summary: Stream, browse, and play YouTube videos from any terminal — Linux, macOS, Windows, and Termux
Author: Naveen
Project-URL: Homepage, https://github.com/naveen07-c/yt-cli
Project-URL: Repository, https://github.com/naveen07-c/yt-cli
Project-URL: Issues, https://github.com/naveen07-c/yt-cli/issues
Keywords: youtube,cli,terminal,mpv,fzf,termux,streaming,playlist
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: yt-dlp
Requires-Dist: emoji

# 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)

```bash
pipx install ytplay-cli
```

Install pipx first if needed:

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

# macOS
brew install pipx && pipx ensurepath

# Termux
pkg install python && pip install pipx
```

### Alternative — pip

```bash
pip install ytplay-cli
```

### From source

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

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

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

```json
{
  "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:**

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

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

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