Terminal interface to find, download, and stream movies, TV shows, and live TV using local media players.
docs: overhaul readme structure and optimize media
Samir Hossainsaeafcc319962
diff --git a/README.md b/README.mdindex 0bc36e0..dedff58 100644--- a/README.md+++ b/README.md@@ -2,27 +2,42 @@# MovieBox-TUI-Search, browse, play, and download movies and series from a keyboard-first terminal interface.+Search, browse, play, and download movies, series, anime, and IPTV streams from a keyboard-first terminal interface using external media players.[](https://crates.io/crates/moviebox-tui)[](https://github.com/mesamirh/MovieBox-Tui/actions/workflows/ci.yml)+[](#requirements)[](#license)-<img src="https://raw.githubusercontent.com/mesamirh/MovieBox-Tui/main/assets/screenshots/01-home-blocky.jpg" alt="MovieBox-TUI home screen" width="85%">+<video src="https://raw.githubusercontent.com/mesamirh/MovieBox-Tui/main/assets/screenshots/demo.mp4" alt="MovieBox-TUI demo" width="85%" autoplay loop muted></video></div>## Features-- MovieBox and 4KHDHub catalogs with isolated search, details, stream, and image caches-- Movie, series, anime, episode, quality, and subtitle browsing-- Playback through mpv, VLC, or IINA-- HTTP header forwarding for protected playback sources-- Resumable downloads with progress, retry, cancellation, and partial-file preservation-- Sequential full-season download queue with one subtitle-language preference-- IPTV playlists, categories, search, and local playlist configuration-- Kitty, Sixel, iTerm2, and text poster rendering where supported-- Configurable themes, update checks, and automatic cache cleanup+### Catalogs & Browsing++- Search and browse movies, TV series, and anime from multiple content catalogs+- Filter search results by resolution and subtitle availability++### Playback++- Play streams directly in your local media player (mpv, VLC, or IINA)+- Play protected streams seamlessly without manual configuration++### Downloads++- Download full seasons or episodes with automatic subtitle language selection+- Resume interrupted downloads without losing progress++### IPTV++- Watch live TV by loading local `.m3u` playlists organized by category++### User Interface & App++- View rich graphical posters in supported terminals (Kitty, iTerm2, Sixel) or fallback to text art+- Let the app automatically manage configuration and clean up expired cachesMovieBox-TUI resolves links from upstream services. Availability can change when those services change.@@ -33,50 +48,53 @@ MovieBox-TUI resolves links from upstream services. Availability can change when- One supported player: mpv, VLC, or IINA- Internet connection-Release binaries currently cover:+## Installation-| Platform | Architectures |-| --- | --- |-| macOS | Intel and Apple Silicon universal binary |-| Linux | x86_64 and ARM64 static musl binaries |-| Windows | x86_64 and ARM64 |+Prebuilt binaries are available for all supported platforms. All official installers verify the release SHA-256 checksum automatically.-## Installation+### macOS or Linux-### Homebrew — macOS or Linux+#### Homebrew```bashbrew tap mesamirh/moviebox-tui https://github.com/mesamirh/MovieBox-Tui+brew trust mesamirh/moviebox-tuibrew install moviebox-tui```The formula selects the correct macOS, Linux x86_64, or Linux ARM64 release.-### Install script — macOS or Linux+#### Install script```bashcurl -fsSL https://raw.githubusercontent.com/mesamirh/MovieBox-Tui/main/install.sh | bash```-The script detects OS and CPU architecture, verifies the release SHA-256 checksum, then installs to `/usr/local/bin`. Without write access or `sudo`, it uses `~/.local/bin`.+The script detects OS and CPU architecture, then installs to `/usr/local/bin`. Without write access or `sudo`, it uses `~/.local/bin`.-### PowerShell — Windows+### Windows-```powershell-irm https://raw.githubusercontent.com/mesamirh/MovieBox-Tui/main/install.ps1 | iex+Works in PowerShell or Command Prompt (cmd):++```cmd+powershell -Command "irm https://raw.githubusercontent.com/mesamirh/MovieBox-Tui/main/install.ps1 | iex"```-The installer selects x86_64 or ARM64, verifies SHA-256, installs under `%LOCALAPPDATA%\MovieBox-Tui`, and adds that directory to the user PATH. Open a new terminal after first installation.+The installer selects x86_64 or ARM64, installs under `%LOCALAPPDATA%\MovieBox-Tui`, and adds that directory to the user PATH. Open a new terminal after first installation.-### Cargo+<details>+<summary><b>Cargo</b></summary>-Requires Rust 1.90 or newer:+Requires Rust 1.90 or newer (this only applies to Cargo and source builds; binary users do not need Rust installed):```bashcargo install moviebox-tui --locked```-### Build from source+</details>++<details>+<summary><b>Build from source</b></summary>```bashgit clone https://github.com/mesamirh/MovieBox-Tui.git@@ -86,23 +104,25 @@ cargo build --release --lockedBinary location: `target/release/moviebox-tui` (`moviebox-tui.exe` on Windows).-## Player setup+</details>++## Supported PlayersMovieBox-TUI checks standard application locations, PATH executables, and Linux Flatpak installations.Detected automatically:-- macOS: `/Applications`, `~/Applications`, Homebrew/PATH-- Linux: PATH, Flatpak mpv, Flatpak VLC-- Windows: PATH, common Program Files locations, Microsoft Store aliases+- **macOS:** `/Applications`, `~/Applications`, Homebrew/PATH+- **Linux:** PATH, Flatpak mpv, Flatpak VLC+- **Windows:** PATH, common Program Files locations, Microsoft Store aliasesPortable or custom installations can be selected with environment variables:-| Player | Variable |-| --- | --- |-| mpv | `MOVIEBOX_MPV_PATH` |-| VLC | `MOVIEBOX_VLC_PATH` |-| IINA | `MOVIEBOX_IINA_PATH` |+| Player | Variable |+| ------ | -------------------- |+| mpv | `MOVIEBOX_MPV_PATH` |+| VLC | `MOVIEBOX_VLC_PATH` |+| IINA | `MOVIEBOX_IINA_PATH` |macOS/Linux example:@@ -128,34 +148,34 @@ Run:moviebox-tui```-### Main controls+### Keyboard shortcuts-| Key | Action |-| --- | --- |+| Key | Action |+| ---------- | ----------------------------------------------------- || Arrow keys | Navigate lists, grids, seasons, episodes, and dialogs |-| Enter | Open or confirm selection |-| Esc / `b` | Close dialog or go back |-| `o` | Choose another player |-| `d` | Download selected episode or season |-| `r` | Refresh current content |-| `Ctrl+P` | Switch content provider |-| `Ctrl+T` | Toggle IPTV mode |-| `?` | Show help |-| `q` | Quit |--### Commands--| Command | Action |-| --- | --- |-| `/discover`, `/home` | Open discovery view |-| `/movies` | Browse movies |-| `/shows` | Browse series |-| `/anime` | Browse anime |-| `/list` | Show IPTV channels |-| `/config` | Configure IPTV playlists |-| `/update` | Check for a newer release |-| `/toggle-update` | Enable or disable automatic update checks |-| `/clear-cache` | Remove cached application data |+| Enter | Open or confirm selection |+| Esc / `b` | Close dialog or go back |+| `o` | Choose another player |+| `d` | Download selected episode or season |+| `r` | Refresh current content |+| `Ctrl+P` | Switch content provider |+| `Ctrl+T` | Toggle IPTV mode |+| `?` | Show help |+| `q` | Quit |++### Slash commands++| Command | Action |+| -------------------- | ----------------------------------------- |+| `/discover`, `/home` | Open discovery view |+| `/movies` | Browse movies |+| `/shows` | Browse series |+| `/anime` | Browse anime |+| `/list` | Show IPTV channels |+| `/config` | Configure IPTV playlists |+| `/update` | Check for a newer release |+| `/toggle-update` | Enable or disable automatic update checks |+| `/clear-cache` | Remove cached application data |`/update` checks availability and shows the release location; it does not replace the running binary. Re-run the installer or Homebrew upgrade command to update.@@ -169,23 +189,25 @@ MovieBox-TUI/└── Series/<title>/Season <number>/```-Season downloads run sequentially to limit disk and network pressure. After choosing a subtitle language for the first episode, the same language is requested for remaining episodes when available. Missing subtitles do not discard completed video files.+- **Sequential downloads:** Entire seasons are downloaded one by one to limit disk and network pressure.+- **Smart subtitles:** Your subtitle language choice for the first episode is applied to the remaining episodes. Missing subtitles do not discard completed video files.+- **Robust resuming:** Interrupted downloads preserve `.part` and metadata files, and can be resumed without losing progress.-Interrupted downloads preserve `.part` and resume metadata files. Starting the same download again attempts to resume it.--## Configuration and cache+## Configuration & CacheMovieBox-TUI uses standard OS directories:-| Platform | Configuration | Cache |-| --- | --- | --- |-| Linux | `${XDG_CONFIG_HOME:-~/.config}/moviebox-tui` | `${XDG_CACHE_HOME:-~/.cache}/moviebox-tui` |-| macOS | `~/Library/Application Support/moviebox-tui` | `~/Library/Caches/moviebox-tui` |-| Windows | `%APPDATA%\moviebox-tui` | `%LOCALAPPDATA%\moviebox-tui` |+| Platform | Configuration | Cache |+| -------- | -------------------------------------------- | ------------------------------------------ |+| Linux | `${XDG_CONFIG_HOME:-~/.config}/moviebox-tui` | `${XDG_CACHE_HOME:-~/.cache}/moviebox-tui` |+| macOS | `~/Library/Application Support/moviebox-tui` | `~/Library/Caches/moviebox-tui` |+| Windows | `%APPDATA%\moviebox-tui` | `%LOCALAPPDATA%\moviebox-tui` |Catalog providers use separate cache namespaces. Expired or invalid cache entries are discarded automatically; files older than seven days are cleaned at startup.-## Updating+## Updates++Automatic update checks only notify you about new releases. They do not update the application automatically.Homebrew:@@ -194,7 +216,11 @@ brew updatebrew upgrade moviebox-tui```-Script installations: run the same install command again. Cargo installations:+Script installation: run the install command again.++Windows PowerShell: run the install command again.++Cargo:```bashcargo install moviebox-tui --locked --force@@ -232,34 +258,57 @@ Configuration and cache directories remain until removed manually.## Troubleshooting-### No media player found+<details>+<summary><b>No media player found</b></summary>-Confirm player runs from terminal:+MovieBox-TUI relies on external players. If it says none are found:-```bash-mpv --version-vlc --version-```+1. Ensure you have installed **mpv**, **VLC**, or **IINA**.+2. Verify it is in your system PATH by running `mpv --version` or `vlc --version` in your terminal.+3. If using a portable or non-standard installation, set the corresponding environment variable before running (e.g., `MOVIEBOX_MPV_PATH=/path/to/mpv`).++</details>++<details>+<summary><b>Images do not render / Only text is shown</b></summary>-For portable installs, set corresponding `MOVIEBOX_*_PATH` variable.+MovieBox-TUI supports inline images via Kitty, Sixel, and iTerm2 protocols.-### Images do not render+- If images don't show, ensure you are using a compatible terminal emulator (like Kitty, WezTerm, iTerm2, or Windows Terminal Preview).+- If your terminal does not support graphics, the UI gracefully falls back to text-based posters and remains fully usable.+- If you experience crashes when resizing the window (specifically with Sixel), please report it with your OS, terminal name, and version.-Image support depends on terminal protocol. Text UI remains usable without graphics. Resize/focus crashes involving Sixel should be reported with OS, terminal name, and `moviebox-tui --version`.+</details>-### Linux command not found after script install+<details>+<summary><b>"moviebox-tui: command not found" (Linux / macOS)</b></summary>-Add local binary directory to shell PATH:+If you installed via the script without `sudo`, the binary was placed in `~/.local/bin`. You need to add this to your PATH. Add this line to your `~/.bashrc` or `~/.zshrc`:```bashexport PATH="$HOME/.local/bin:$PATH"```-Persist that line in shell profile when needed.+Then restart your terminal.++</details>++<details>+<summary><b>Windows PowerShell script fails (Execution Policy)</b></summary>++If you receive an error about running scripts being disabled on your system when installing via PowerShell, run this command as Administrator first:++```powershell+Set-ExecutionPolicy RemoteSigned -Scope CurrentUser+```++Then try the installation command again.++</details>## Development-Before submitting changes:+Before submitting changes, ensure your code is formatted, linted, audited for security vulnerabilities, and packages correctly:```bashcargo fmt --check@@ -270,10 +319,10 @@ cargo package --lockedSee [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidance.-## Legal--MovieBox-TUI does not host media. It is not affiliated with MovieBox, 4KHDHub, IPTV providers, player projects, or terminal vendors. Users are responsible for complying with laws and service terms applicable to them.-## LicenseLicensed under either [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE), at your option.++## Legal++MovieBox-TUI does not host media. It is not affiliated with any specific content sources, IPTV providers, player projects, or terminal vendors. Users are responsible for complying with laws and service terms applicable to them.diff --git a/assets/screenshots/demo.mp4 b/assets/screenshots/demo.mp4new file mode 100644index 0000000..dd2b282Binary files /dev/null and b/assets/screenshots/demo.mp4 differ