📺 cli-tv

A blazing fast, lightweight terminal IPTV browser and player built in Rust.

cli-tv lets you seamlessly browse, search, filter, and stream thousands of publicly available live channels from the iptv-org project without ever leaving your terminal. Powered by a fluid, keyboard-driven Ratatui interface, it delegates high-performance, stutter-free playback to mpv.

---

✨ Features

• ⚡ Zero-Lag UI: Background synchronization and health probing ensure the interface never blocks on network I/O.
• 🔍 Fuzzy Search: Context-aware, ultra-fast fuzzy matching over channel names, alternative titles, countries, and categories powered by nucleo-matcher.
• 📊 Live Health Status: Active stream probing dynamically flags streams in your list (● Live, ◐ Slow, ○ Dead, • Unconfirmed).
• ⭐ Favorites & History: Instantly bookmark (f) your frequent streams, backed by a persistent local SQLite cache.
• 🎨 Modern TUI Styling: Beautiful phosphor color palette with truecolor support, an automatic 256-color fallback, and a high-contrast accessibility variant.
• 🛠️ Guided Player Setup: Built-in interactive setup hooks your local package manager to fetch mpv dynamically if it isn't found in your runtime path.

---

🏗️ Architecture & Data Flow

cli-tv is structured as a robust Cargo workspace, isolating concerns into small, single-responsibility crates for peak reliability and testability:

• cli-tv (bin): The thin CLI entry point that handles argument parsing and initializes the event loop.
• ui: Evaluates the terminal-safe event loop, manages the state machine, and renders responsive Ratatui widgets.
• data: Orchestrates concurrent upstream syncing (channels, streams, countries, blocklists), caches data using SQLite, and manages async stream health probing.
• player: Manages environment path detection, provides guided binary configuration, and fires target hooks asynchronously with secure header passthroughs.
• core: Contains pure domain models and fuzzy-search criteria with no internal I/O side effects.

---

🚀 Installation & Setup

📦 Option 1: Download Pre-compiled Binaries (Recommended)

Grab the latest optimized release built automatically via GitHub Actions for your specific platform on the Releases Page.

Supported targets include:

• Linux: x86_64 (GNU/MUSL), aarch64 (GNU)
• macOS: x86_64 (Intel), aarch64 (Apple Silicon)
• Windows: x86_64 (MSVC)

🛠️ Option 2: Build from Source

If you prefer building locally, ensure you have Rust 1.74 or newer installed:

# Clone the repository
git clone [https://github.com/webwurst9000/cli-tv.git](https://github.com/webwurst9000/cli-tv.git)
cd cli-tv

# Run with cached data
cargo run --release

# Force a clean sync from upstream on startup
cargo run --release -- --refresh

🎬 Interactive mpv Auto-Detection

The media player mpv is required for video stream playback. If mpv is missing from your system PATH, cli-tv features a built-in guided setup. It will safely detect your operating system environment, display the correct system installation command, and offer to run it for you:

• macOS: Installs via Homebrew (brew install mpv)
• Linux: Installs via your native package manager (apt, dnf, or pacman)
• Windows: Installs via Windows Package Manager (winget install mpv)

⚠️ Note: cli-tv never installs dependencies silently. It will explicitly show you the command and wait for confirmation before interacting with your terminal environment.

---

⌨️ Keybindings & Flags

cli-tv uses intuitive, Vim-inspired keybindings to keep your hands on the home row.

Interface Navigation

Key	Action
Tab	Switch focus between the Sidebar and the Channel List
h / l or ← / →	Explicitly focus Sidebar (left) or Channel List (right)
j / k or ↓ / ↑	Move selection up or down within the active pane
b	Toggle sidebar visibility entirely (ideal for narrow windows)

Filtering & Browsing

Key	Action
c / g	Switch sidebar taxonomy to Countries or Categories
[ / ]	Cycle through open sidebar tabs
1 - 9	Jump directly to the $N$-th category and apply it as a filter
Enter	Apply sidebar selection as a filter, or play a highlighted channel
x	Clear all active country and category filters

Search, Playback & Favorites

Key	Action
/	Open contextual fuzzy search (filters whichever pane is focused)
Esc	Close search input / clear ongoing text filter
f	Toggle favorite status (★) on the selected channel
?	Toggle the built-in, full-screen keybindings help overlay
q	Safely clean up background processes and close cli-tv

Command-Line Arguments

Tailor the application runtime by appending these flags upon launch:

• --refresh: Forces an immediate local cache update from upstream APIs.
• --no-health-check: Disables background async stream health URL probing.
• --debug: Outputs comprehensive, daily-rotating trace logs to your platform's XDG state directory.

---

📜 License

This project is licensed under the MIT License — see the LICENSE file for details.