Terminal interface to find, download, and stream movies, TV shows, and live TV using local media players.
docs: streamline user guide, prune static assets, and align mode configuration
Samir Hossainsf60d2d2761ec
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ff706ca..ca69482 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,16 @@- Scoped `Ctrl+P` strictly to Streaming Mode for provider cycling, eliminating redundant `Ctrl+P` handling in TV and Addon modes.- Streamlined `/config` as a direct alias for `/settings`.+- **Automation Workflows & Installer Hardening**:+ - Added bounded execution timeouts (`timeout-minutes`) across all CI and release pipeline jobs to prevent runner hangs.+ - Accelerated release preflight by eliminating redundant cross-compilation target toolchain downloads during source packaging.+ - Streamlined Homebrew formula updater (`homebrew.yml`) by parsing the release's attested `SHA256SUMS` manifest directly with strict 64-char hex validation, eliminating redundant ~50MB archive downloads.+ - Added on-device binary execution smoke tests to `install.ps1` and enhanced `install.sh` error diagnostics with API version resolution fallbacks.+- **Documentation & User Guide Streamlining**:+ - Overhauled root `README.md` into a developer-focused technical guide, pruning marketing copy, redundant comparison tables, and promotional buzzwords.+ - Added structured media player setup guide with package manager commands (`brew`, `apt`, `winget`).+ - Updated macOS Homebrew installation with explicit `brew trust` step required by Homebrew 6.0+ for third-party taps.+ - Streamlined quickstart section to reference in-app interactive help (`?`) and `docs/controls.md`, preventing documentation drift.### Fixed- **Direct Playback & Header Compatibility**:- Eliminated vestigial in-stream "Open with" popup that blocked playback when only VLC was installed, routing playback directly to the preferred compatible player.@@ -32,6 +42,7 @@- Added automated ELF `e_type` and `PT_TLS` validation checks to `.github/workflows/release.yml` and a post-installation execution smoke test to `install.sh`.### Removed- Removed vestigial `ShowPlaybackPicker` and `ShowPlayerPicker` action variants and playback picker state fields in favor of direct compatible player dispatch.+- Removed unreferenced static screenshot assets (`assets/`), reducing repository clone size by ~1.3MB.- **Redundant Slash Commands**:- Pruned 10+ legacy slash commands (`/download-dir`, `/clear-cache`, `/update`, `/github`, `/probe`, `/toggle-update`, `/toggle-bdix`, `/toggle-streaming`, `/toggle-tv`, `/toggle-addons`, `/enable-*`, `/disable-*`) superseded by the interactive Settings Hub.- Removed 300+ lines of redundant command execution and file write probing in `src/tui/app/search.rs`.diff --git a/Cargo.toml b/Cargo.tomlindex 0b3443e..3591735 100644--- a/Cargo.toml+++ b/Cargo.toml@@ -1,7 +1,6 @@[package]name = "moviebox-tui"exclude = [- "assets/","docs/","Formula/",".github/",diff --git a/README.md b/README.mdindex 1cbb2c7..7ccfcbb 100644--- a/README.md+++ b/README.md@@ -1,119 +1,73 @@-<div align="center">-# MovieBox-TUI-Watch and download movies, TV shows, anime, and live TV right in your terminal — without opening a browser.--[](https://crates.io/crates/moviebox-tui)-[](https://crates.io/crates/moviebox-tui)-[](https://github.com/mesamirh/MovieBox-Tui/actions/workflows/ci.yml)-[](#license)--</div>+A fast, lightweight terminal client for streaming and downloading movies, TV shows, anime, and live TV — powered by your local media player.[moviebox-tui demo.mp4](https://github.com/user-attachments/assets/60b5fab9-cf7a-4a59-9bbf-b2357c345091)-## Why MovieBox-TUI?--Searching and watching media through web browsers often means dealing with heavy memory usage from multiple open tabs, intrusive popups, tracking scripts, and clunky web players.+MovieBox-TUI replaces ad-heavy streaming websites and clunky browser players with a clean, keyboard-driven terminal interface. It scrapes stream links directly from multiple sources and launches playback in your native media player with hardware acceleration, audio track switching, and automatic subtitle synchronization.-**MovieBox-TUI replaces the web browser workflow with a lightweight terminal interface.** It extracts stream links directly and launches them in your preferred local media player (`mpv`, `VLC`, or macOS `IINA`), with no ads or popups inside the application.+## Features-### Quick Comparison+- **Multi-Source Streaming**: Search and stream titles across MovieBox, 4KHDHub, BDIX mirrors, custom IPTV playlists, and community Stremio HTTP addons. Press `Ctrl+P` on the Details screen to switch providers in-place.+- **Hardware-Accelerated Playback**: Direct playback in `mpv`, `IINA` (macOS), or `VLC` with stream authentication headers forwarded automatically.+- **Automatic Subtitles**: Automatically searches, downloads, and syncs subtitles in your preferred language directly into your player.+- **Season Batch Downloads**: Download individual episodes or entire seasons with one keypress (`d`), with HTTP range resume support and clean folder structure (`Movies/` and `Series/`).+- **Interactive Settings Hub**: Configure your default media player, download folder, content modes, and themes inside an in-app visual modal via `/settings` (`Ctrl+S`).+- **Modes**: Switch instantly between standard Streaming, Live TV (`Ctrl+T`), and Addon Mode (`Ctrl+A`).+- **Ergonomics & Themes**: Full keyboard navigation (vim-style `j`/`k`, `/`, `Tab`) and mouse support (click, scroll, drag) with 6 built-in themes (Catppuccin, TokyoNight, Nord, Dracula, Gruvbox, Rosé Pine) and terminal theme autodetection.-| Feature | Streaming in a Web Browser | MovieBox-TUI in Your Terminal |-| :--- | :--- | :--- |-| **Resource Usage** | Heavy browser process overhead | **~5 MB RAM (no web engine required)** |-| **In-App Experience** | Popups, redirects, and tracking scripts | **No ads or popups inside the application** |-| **Video Player** | Browser web player | **Direct playback in mpv, VLC, or IINA** |-| **Account & Login** | Forced account creation & signups | **No account or login required** |-| **Subtitles** | Manual search and file renaming | **Automatic subtitle downloads in your language** |-| **Downloads** | Manual single-file downloads | **1-click full season batch downloads** |-| **File Organization** | Cluttered downloads folder | **Clean, organized Movies and Series folders** |--## Features at a Glance--- **Search Everything:** Find movies, TV shows, anime, and live TV channels across multiple sources (MovieBox, 4KHDHub, BDIX mirrors, community HTTP addons, and custom IPTV playlists). Features dynamic rotating search suggestions, precision vertical beam cursor with typing debounce, grapheme-safe input, and autocomplete discovery.-- **Stream Details & Media Badges:** Responsive multi-tier details layout with adaptive selector panes (Audio, Seasons, Episodes), color-coded resolution badges (4K UHD, 1080p FHD, 720p HD, SD), and audio/codec tags (`HDR`, `DV`, `ATMOS`, `5.1`, `HEVC`, `AV1`, `BluRay`, `WEB-DL`, `REMUX`) with smooth horizontal pane navigation (`←`/`→`/`h`/`l`/`Tab`).-- **Addon Mode:** Install community HTTP addon manifests for custom catalog metadata (Cinemeta, Anime Kitsu) and direct stream resolution.-- **Smooth Video Playback:** Plays directly in **mpv** or **VLC**, with **IINA** available on macOS, using your computer's hardware for smooth video.-- **Easy Downloads:** Download single episodes or entire seasons with one keypress. Completed episodes are skipped automatically.-- **Favorites:** Favorite any movie or series with `f` and reach it instantly from a dedicated row on the home screen, or view the full list with `/favorites`.-- **Refined Terminal Interface:** Full keyboard and mouse support, responsive multi-column grid, compact single-column narrow terminal fallbacks, fluid 10-frame Braille loading spinners, WCAG AA contrast light/dark themes (Catppuccin Latte/Mocha, Nord, TokyoNight, Dracula, Gruvbox, Rosé Pine), contextual window titles, and modal-gated poster art.-- **Zero-JSON Engine & MessagePack Binary Caching:** 100% strongly typed native domain pipeline with zero heap-allocated JSON boxing in the UI render loop, multi-tier in-memory L1 LRU caching, and sub-millisecond on-disk binary caching powered by `rmp-serde`.-## Installation+## Prerequisites-A media player (**[mpv](https://mpv.io)** or **[VLC](https://www.videolan.org/vlc/)**; **[IINA](https://iina.io)** on macOS) is recommended for video playback.+MovieBox-TUI delegates video decoding to an external media player. Install at least one of the following:-### macOS--Using **Homebrew**:-```bash-brew tap mesamirh/moviebox-tui https://github.com/mesamirh/MovieBox-Tui-brew install mesamirh/moviebox-tui/moviebox-tui-```--Or using the automated installer:-```bash-curl -fsSL https://raw.githubusercontent.com/mesamirh/MovieBox-Tui/main/install.sh -o install.sh && bash install.sh-```--*(Or download the prebuilt `MovieBox_macOS_Universal.tar.gz` from [GitHub Releases](https://github.com/mesamirh/MovieBox-Tui/releases/latest))*+| Player | Platform | Quick Install |+| :--- | :--- | :--- |+| **mpv** *(Recommended)* | Linux, macOS, Windows | `brew install mpv` / `sudo apt install mpv` / `winget install mpv` |+| **IINA** | macOS (Native GUI) | `brew install --cask iina` |+| **VLC** | Cross-platform | `brew install --cask vlc` / `sudo apt install vlc` / `winget install VideoLAN.VLC` |+| **Android Player** | Android (Termux) | `pkg install termux-tools` *(launches VLC or Nova)* |----+## Installation-### Linux+### macOS & Linux-Using the automated installer (installs prebuilt static binary to `~/.local/bin`):+Install via the automated script:```bash-curl -fsSL https://raw.githubusercontent.com/mesamirh/MovieBox-Tui/main/install.sh -o install.sh && bash install.sh+curl -fsSL https://raw.githubusercontent.com/mesamirh/MovieBox-Tui/main/install.sh | bash```-Or manual installation:+*macOS users can also install via Homebrew:*```bash-curl -LO https://github.com/mesamirh/MovieBox-Tui/releases/latest/download/MovieBox_Linux_x64.tar.gz-tar -xzf MovieBox_Linux_x64.tar.gz-mkdir -p ~/.local/bin && mv moviebox-tui ~/.local/bin/+brew tap mesamirh/moviebox-tui https://github.com/mesamirh/MovieBox-Tui+brew trust mesamirh/moviebox-tui+brew install moviebox-tui```-----### Windows-Using **PowerShell**:+Install via PowerShell:```powershellirm https://raw.githubusercontent.com/mesamirh/MovieBox-Tui/main/install.ps1 | iex```-Or manual installation:-1. Download `MovieBox_Windows_x64.zip` (or `MovieBox_Windows_arm64.zip`) from [GitHub Releases](https://github.com/mesamirh/MovieBox-Tui/releases/latest).-2. Extract the archive and place `moviebox-tui.exe` in your PATH (e.g. `%LOCALAPPDATA%\Programs\MovieBox-Tui\bin`).--*(Note: If Windows SmartScreen displays an "Unknown Publisher" prompt on first launch, click **More info** → **Run anyway**)*------### Android (Termux)-Install Termux tools and run the automated installer:+Install Termux tools, run the installer, and grant storage permissions:```bashpkg update && pkg install termux-tools-curl -fsSL https://raw.githubusercontent.com/mesamirh/MovieBox-Tui/main/install.sh -o install.sh && bash install.sh+curl -fsSL https://raw.githubusercontent.com/mesamirh/MovieBox-Tui/main/install.sh | bashtermux-setup-storage```-*(Installing `termux-tools` provides `termux-open`, allowing MovieBox-TUI to automatically launch your preferred Android video player app like VLC, MX Player, or Nova).*--*(Or compile natively via Cargo: `pkg install rust && cargo install moviebox-tui --locked`)*-----<details>-<summary><b>From Source / Cargo (Developers)</b></summary>+<summary><b>Manual & Developer Builds (Cargo)</b></summary>+Install directly from crates.io:```bashcargo install moviebox-tui --locked```+Or compile from source:```bashgit clone https://github.com/mesamirh/MovieBox-Tui.gitcd MovieBox-Tui@@ -123,58 +77,45 @@ cargo build --release --locked</details><details>-<summary><b>Verify Release Integrity & Provenance</b></summary>+<summary><b>Verify Release Integrity</b></summary>```bashsha256sum -c SHA256SUMS --ignore-missing-```--```bashgh attestation verify <archive-file> -R mesamirh/MovieBox-Tui```</details>-## Usage--Start the app:+## Quick Start+Launch the application:```bashmoviebox-tui```-- **Interactive Help:** Press `?` inside the app anytime to view contextual keyboard shortcuts and mouse controls.-- **Mouse & Keyboard:** Full mouse navigation and keyboard controls are supported throughout the application.-- **Complete Reference:** See [Controls & Shortcuts](docs/controls.md) for the full list of keybindings, mouse actions, and slash commands.-## Documentation-All in-depth guides and technical details are available in the [`docs/`](docs/) directory:+- **Interactive Help**: Press `?` inside the app anytime to view the mode-aware keyboard shortcuts and mouse guide.+- **Settings**: Type `/settings` or press `Ctrl+S` to configure your default player, download directory, and content modes.+- **Controls Reference**: See [`docs/controls.md`](docs/controls.md) for the complete list of keybindings, mouse actions, and slash commands.-- [Controls & Shortcuts](docs/controls.md) — Complete keyboard shortcuts, mouse actions, and slash commands-- [Architecture & Data Flow](docs/architecture.md) — How the app works under the hood-- [Media Players](docs/players.md) — Supported players, custom paths, and launch options-- [Downloads & Organization](docs/downloads.md) — Folder layout, batch downloading, and subtitles-- [Live TV & Playlists](docs/tv-mode.md) — How to add and manage custom M3U playlists-- [Addon Mode & HTTP Addons](docs/addons-mode.md) — How to install and manage community HTTP addon manifests-- [Configuration Reference](docs/config.md) — Config files and environment variables-- [Providers](docs/providers.md) — Supported content sources and protocols-- [Troubleshooting & Debugging](docs/debugging.md) — Fixing common issues and reporting bugs-- [Testing & QA Architecture](docs/testing.md) — Testing philosophy, unit/integration suites, and QA guidelines-- [Contributing Guide](CONTRIBUTING.md) — How to contribute code and submit PRs+## Documentation-## Roadmap+Comprehensive guides are available in the [`docs/`](docs/) directory:-- [x] **Terminal UI (TUI):** Interactive terminal application with mouse and keyboard navigation, stream playback, and batch downloading.-- [ ] **Command-Line Interface (CLI):** Direct command-line flags and arguments for headless searching, streaming, and scripted downloading.-- [ ] **Desktop GUI Client:** Dedicated graphical desktop application powered by the same backend stream engine.+- [Controls & Shortcuts](docs/controls.md) — Complete keybindings, navigation, and slash commands+- [Media Players](docs/players.md) — Player options, custom paths, and launch flags+- [Downloads & Organization](docs/downloads.md) — Multi-segment download engine and folder layout+- [Live TV](docs/tv-mode.md) — Adding and managing custom M3U playlists+- [Addon Mode](docs/addons-mode.md) — Installing and managing Stremio HTTP addons+- [Configuration](docs/config.md) — `config.json` reference and `MOVIEBOX_*` environment variables+- [Providers](docs/providers.md) — Supported content sources and resolver protocols+- [Architecture](docs/architecture.md) — Subsystem map, event loop, and caching model+- [Documentation Index](docs/README.md) — Full documentation directory-## Feedback & Support+## Contributing-If you find the project useful, here are a few simple ways to support it:+Contributions are welcome! Please review [CONTRIBUTING.md](CONTRIBUTING.md) before submitting pull requests.-- **Star the repository** on GitHub to help others discover it.-- **Report bugs or request features** by opening an [issue](https://github.com/mesamirh/MovieBox-Tui/issues).-- **Share the project** with friends, colleagues, or terminal enthusiasts.-- **Contribute improvements** to scrapers, performance, or docs via [pull requests](CONTRIBUTING.md).+If you encounter a bug or have a feature request, feel free to open an [issue](https://github.com/mesamirh/MovieBox-Tui/issues).<details><summary><b>Optional Support</b></summary>@@ -192,7 +133,7 @@ If you would like to support ongoing development directly:## License-Licensed under either [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE), at your option.+Licensed under either [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE).## Disclaimerdiff --git a/assets/screenshots/01-home-screen.jpg b/assets/screenshots/01-home-screen.jpgdeleted file mode 100644index a0bc519..0000000Binary files a/assets/screenshots/01-home-screen.jpg and /dev/null differdiff --git a/assets/screenshots/02-search-suggestions.jpg b/assets/screenshots/02-search-suggestions.jpgdeleted file mode 100644index a410e53..0000000Binary files a/assets/screenshots/02-search-suggestions.jpg and /dev/null differdiff --git a/assets/screenshots/03-search-results.jpg b/assets/screenshots/03-search-results.jpgdeleted file mode 100644index 4a9d8c4..0000000Binary files a/assets/screenshots/03-search-results.jpg and /dev/null differdiff --git a/assets/screenshots/04-movie-details.jpg b/assets/screenshots/04-movie-details.jpgdeleted file mode 100644index 05bf9ec..0000000Binary files a/assets/screenshots/04-movie-details.jpg and /dev/null differdiff --git a/assets/screenshots/05-series-details.jpg b/assets/screenshots/05-series-details.jpgdeleted file mode 100644index b93a179..0000000Binary files a/assets/screenshots/05-series-details.jpg and /dev/null differdiff --git a/assets/screenshots/06-live-tv-mode.jpg b/assets/screenshots/06-live-tv-mode.jpgdeleted file mode 100644index 8c1b743..0000000Binary files a/assets/screenshots/06-live-tv-mode.jpg and /dev/null differdiff --git a/assets/screenshots/07-stream-mirrors.jpg b/assets/screenshots/07-stream-mirrors.jpgdeleted file mode 100644index 5a46282..0000000Binary files a/assets/screenshots/07-stream-mirrors.jpg and /dev/null differdiff --git a/assets/screenshots/08-subtitles-picker.jpg b/assets/screenshots/08-subtitles-picker.jpgdeleted file mode 100644index d7b490c..0000000Binary files a/assets/screenshots/08-subtitles-picker.jpg and /dev/null differdiff --git a/assets/screenshots/09-series-seasons-episodes.jpg b/assets/screenshots/09-series-seasons-episodes.jpgdeleted file mode 100644index 4fd37ad..0000000Binary files a/assets/screenshots/09-series-seasons-episodes.jpg and /dev/null differdiff --git a/assets/screenshots/10-global-help.jpg b/assets/screenshots/10-global-help.jpgdeleted file mode 100644index 66ca0d5..0000000Binary files a/assets/screenshots/10-global-help.jpg and /dev/null differdiff --git a/docs/README.md b/docs/README.mdindex bd4c41d..d27b511 100644--- a/docs/README.md+++ b/docs/README.md@@ -1,6 +1,6 @@# MovieBox-Tui Documentation-This folder documents the project so that anyone — human or AI — can understand how it+This folder documents the project so that anyone can understand how itworks without reading the whole codebase. The documents summarize the current modulelayout, runtime behavior, and operational workflows in prose tied to the source tree.diff --git a/docs/controls.md b/docs/controls.mdindex 162bbba..291a312 100644--- a/docs/controls.md+++ b/docs/controls.md@@ -113,6 +113,8 @@ Type these commands directly into the search bar:| `/list` | TV | View live TV channels || `/exit` | All | Exit application and return to shell (aliases `/quit`, `/q`) |+## Help Menu Overlay+- Open with `?`; close with `?`, `Esc`, or `q`.- `↑`/`↓`, `PageUp`/`PageDown`, and the mouse wheel scroll long content.- Other keys are ignored while help is open.diff --git a/docs/cross-platform.md b/docs/cross-platform.mdindex 2d0939f..5e88aa3 100644--- a/docs/cross-platform.md+++ b/docs/cross-platform.md@@ -44,9 +44,9 @@ prevent escape sequence probe leakage (`Gi=31...`):types) is requested at start and popped on exit; unsupported terminalsignore it. Real input cursor styling (`SetCursorStyle::SteadyBar`) activatesduring text editing modes on supported terminals.-- **Loading & Progress Animations**: Fluid 10-frame Unicode Braille loading- spinners (`⠋ ⠙ ⠹ ...`) render during search, metadata discovery, and stream- fetching, falling back to clean text indicators (`..`) on basic/dumb terminals.+- **Loading & Progress Indicators**: Unicode Braille loading spinners (`⠋ ⠙ ⠹ ...`)+ render during search, metadata discovery, and stream fetching, falling back to+ clean text indicators (`..`) on basic/dumb terminals.- **Window Titles**: Contextual terminal emulator window titles are emitted dynamicallyreflecting active navigation mode and title (`MovieBox-Tui — Streaming`,`MovieBox-Tui — Live TV`, `MovieBox-Tui — Addons`, `MovieBox-Tui — {Title}`).diff --git a/docs/modules.md b/docs/modules.mdindex 2357501..a25744f 100644--- a/docs/modules.md+++ b/docs/modules.md@@ -103,6 +103,7 @@ src/input.rs Single-line text input field rendering with grapheme cursor and truncation.modal.rs Modal dialog frame builder (ModalFrame) and centered footer key action bars.scrollbar.rs Viewport-accurate vertical scrollbars.+ settings.rs Interactive 4-tab Settings Hub modal widget.tui/app/ The application object (App) and all behavior.mod.rs App struct, App::new, and small helpers.diff --git a/docs/providers.md b/docs/providers.mdindex 7434d3b..d82ea76 100644--- a/docs/providers.md+++ b/docs/providers.md@@ -29,7 +29,7 @@ in `providers/mod.rs` give every client a shared, strictly-typed async trait sha- `ReleaseProvider::episode_streams(&self, id: &str, season: usize, episode: usize) -> Result<Vec<Release>, ProviderError>`: Returns the typed `Release` list for release-based providers.- `ProviderError`: Standardized error boundary (`Network`, `RateLimited`, `NotFound`, `Parsing`, `Unavailable`) with `.user_message(provider)` generating clean UI toast notifications.-### 100% Zero-JSON Architecture & High-Performance Binary Caching+### Strongly Typed Architecture & Binary Disk CachingAll internal state (`AppState`), UI screens (`details.rs`, `home.rs`), and the action event bus transport native Rust structs directly:- `CatalogItem` / `SearchResult` for search results and discover catalogs.diff --git a/src/tui/app/search.rs b/src/tui/app/search.rsindex 782ddef..e01dace 100644--- a/src/tui/app/search.rs+++ b/src/tui/app/search.rs@@ -120,6 +120,15 @@ impl App {Some(true)}crate::tui::commands::ParsedCommand::Settings => {+ if trimmed.eq_ignore_ascii_case("/config") {+ if self.state.is_tv_mode {+ self.action_sender.send(Action::ShowTvConfig).ok();+ return Some(true);+ } else if self.state.is_addon_mode {+ self.action_sender.send(Action::ShowAddonManager).ok();+ return Some(true);+ }+ }self.action_sender.send(Action::ToggleSettingsPopup).ok();Some(true)}