Terminal interface to find, download, and stream movies, TV shows, and live TV using local media players.
docs: update architecture, controls, config schemas, and changelog
Samir Hossains5b01bd6b5206
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex b855681..8246d1a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -15,6 +15,11 @@- Intercepted all `/` slash commands to guarantee zero remote catalog network requests.- Added warning toast notifications for unrecognized slash commands (`"Command '/xyz' is not recognized. Type '/' to view available commands."`).- Added platform-aware mode-guidance toasts (`^T` / `^S` / `^A` on macOS, `Ctrl+T` / `Ctrl+S` / `Ctrl+A` on Linux/Windows) for mode-restricted commands.+- **Active Mode & Provider State Persistence**:+ - Added `active_mode` configuration field in `config.json` automatically persisting and restoring the last active mode (`streaming`, `tv`, `addon`) and active provider across app restarts.+- **Configurable Mode Navigation**:+ - Added `/enable-streaming`, `/disable-streaming`, `/enable-tv`, and `/disable-tv` slash commands alongside `/enable-addons` and `/disable-addons`.+ - Enforced safety validation ensuring at least one mode remains active and gracefully migrating focus when disabling the current mode.- **Dynamic Multi-Source Host & Resolver Resolution**:- Added 100% dynamic domain-based host extractor (`extract_domain_label`) and stream tag parser (`detect_stream_host`) identifying and formatting direct hosts (Pixeldrain, Hubcloud, Fast Download, Google Drive, Mega, etc.) and debrid resolvers without hardcoded tables.- **Full Emoji & Symbol Sanitization**:@@ -46,6 +51,13 @@- Maintained visibility of Audio Languages, Seasons, and Episodes selector tabs side-by-side in standard ~80-column terminals when focusing Streams, preventing tabs from disappearing when 0 streams are available.### Changed+- **Modular TV Provider Architecture**:+ - Reorganized Live TV / IPTV provider into a dedicated module directory (`src/providers/tv/`) with separated `models.rs` and `parser.rs`.+- **Core Infrastructure Consolidation**:+ - Centralized atomic file operations (`atomic_write_file`, `atomic_write_file_async`), MD5 digest formatting (`md5_hex`), and text extraction helpers in `cache.rs` and `service.rs`.+ - Centralized application paths, border type resolution, and mode status announcements across TUI modules.+- **Addon Manager UI Optimization**:+ - Compacted the Addon Manager dialog with an aligned two-tier layout placing `[ Add Manifest URL ]` and `[ Done ]` action buttons side-by-side.- **Multi-System Core Module Decoupling**:- Promoted `player.rs` (process management & detection), `config.rs` (shared configuration), and `updater.rs` (release checks) to core modules in `src/`, preparing the architecture for upcoming CLI and GUI frontends with full backward compatibility.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 15a7ca0..7f202b9 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -23,7 +23,7 @@ git config core.hooksPath .githookscargo run --release```-To test playback and download features locally, install `mpv` (see the [README](README.md#requirements)).+To test playback and download features locally, install `mpv` (see [Media Players](docs/players.md)).## Project layout@@ -34,11 +34,12 @@ Short version:- `src/tui/app/`: The application object (`App`). `run.rs` holds the thin`handle_action` dispatcher that routes every `Action` to a `handle_*` method in its- module (`run.rs`, `requests.rs`, `playback.rs`, `download.rs`, `navigation.rs`,- `tv.rs`, `system.rs`, `keyboard.rs`, `network.rs`).-- `src/tui/`: UI state, event loop plumbing, player commands, screens, themes.-- `src/providers/`: HTTP clients for the streaming sources (`moviebox`, `fourkhdhub`,- `bdix`), plus `m3u.rs` for TV playlists.+ module (`run.rs`, `requests.rs`, `search.rs`, `playback.rs`, `download.rs`,+ `navigation.rs`, `tv.rs`, `addons.rs`, `keyboard.rs`, `mouse.rs`, `system.rs`, `network.rs`).+- `src/tui/`: UI state, event loop plumbing, slash commands (`commands.rs`), screens, themes.+- `src/providers/`: HTTP clients for streaming sources (`moviebox`, `fourkhdhub`,+ `bdix`), community HTTP addons (`addons/`), and Live TV playlists (`tv/`).+- `src/service.rs`: Unified headless multi-provider client & engine.- `src/download.rs`: Background media downloading.- `src/cache.rs`: Local disk caching to minimize API calls.diff --git a/docs/architecture.md b/docs/architecture.mdindex c68a821..4a5eb26 100644--- a/docs/architecture.md+++ b/docs/architecture.md@@ -44,11 +44,13 @@ src/episode-stream actionsnavigation.rs list navigation, submit actions, provider helperstv.rs TV mode: playlist manager + playback+ addons.rs Addon mode: addon manager + HTTP addon actionskeyboard.rs raw key-event handlingmouse.rs mouse click handling and hitbox routingsystem.rs help, refresh, cache, theme, updates, focus, resizestate.rs AppState: all UI state + in-memory LRU cachesaction.rs the Action enum (event/message model)+ commands.rs Slash command registry, parsing, and suggestionsevent.rs EventHandler: input events + tick → Action channeloverlay.rs popups, pickers, notificationsscreens/ render-only modules (home, details, help)@@ -105,7 +107,8 @@ interval, forwarding them into the action channel (capacity 128).## Configuration and persistence-- `config.json` — settings (theme, provider, auto-update, `default_player`, BDIX) in the config dir.+- `config.json` — settings (mode persistence, mode toggles, theme, provider, auto-update, `default_player`, download directory, BDIX) in the config dir.+- `addons_config.json` — installed HTTP community addons in the config dir.- `tv_config.json` — user M3U playlist sources (URLs or file paths) in the config dir.- `history.json` — watch history in the system data dir.- Cache lives under the system cache dir, keyed per provider.diff --git a/docs/cache.md b/docs/cache.mdindex 08b501f..7ecd460 100644--- a/docs/cache.md+++ b/docs/cache.md@@ -6,7 +6,7 @@ Disk caching lives in `cache.rs`; in-memory caches live in `AppState`.```<cache dir>/moviebox-tui/- <provider>/ moviebox, fourkhdhub, bdix_circleftp, bdix_dhakaflix+ <provider>/ moviebox, fourkhdhub, bdix_circleftp, bdix_dhakaflix, addonssearch/<hash>.jsondetails/details_<hash>.jsonstreams/v3_<hash>_<season>_<episode>.json (v3_ prefix only for 4KHD)@@ -24,10 +24,12 @@ The cache directory is `dirs::cache_dir()/moviebox-tui` (macOS- **Provider namespacing**: keys include `provider.cache_key()`, so results fromdifferent providers never collide. Image caches are namespaced by provider (or- `iptv` for channel logos).-- **TTL**: streams expire after 2h; search/details/captions/images after 24h;- homepage after 1h; remote TV playlist snapshots after 24h. Local file playlists are- reread directly instead of being served from the cache.+ `iptv` for channel logos) with fallback resolution across `posters`, `moviebox`,+ `fourkhdhub`, `iptv`, `circleftp`, and `dhakaflix`.+- **TTL**: streams expire after 2h; search/details/captions after 24h;+ homepage after 1h; remote TV playlist snapshots after 24h; images after 30 days+ (`IMAGE_CACHE_EXPIRY_SECS`). Local file playlists are reread directly instead of+ being served from the cache.- **Atomic writes**: data is written to a temp file then renamed, so a crash neverleaves a corrupt cache entry.- **Validation**: search/stream entries are only cached (and only served) if theydiff --git a/docs/config.md b/docs/config.mdindex 987d22e..6de25f8 100644--- a/docs/config.md+++ b/docs/config.md@@ -9,10 +9,13 @@ macOS `~/Library/Application Support/moviebox-tui`, Linux `~/.config/moviebox-tu| ------------------- | -------------- | ----------------------------------------------------------------------------------------------------------- || `auto_update` | bool | Check for updates on startup (max once/hour). || `last_update_check` | u64 | Epoch seconds of the last update check. |+| `active_mode` | string | Last active mode (`streaming`, `tv`, `addon`) restored on startup. || `active_provider` | string | Last provider (`moviebox`, `fourkhdhub`, …). || `active_theme` | string | Theme name. || `bdix_enabled` | bool | Show BDIX providers (Bangladesh-only). |-| `addons_enabled` | bool | Enable Addon Mode (HTTP community addons). |+| `streaming_enabled` | bool | Enable Streaming Mode navigation in bottom dock (`/enable-streaming`, `/disable-streaming`). |+| `tv_enabled` | bool | Enable TV Mode navigation in bottom dock (`/enable-tv`, `/disable-tv`). |+| `addons_enabled` | bool | Enable Addon Mode navigation in bottom dock (`/enable-addons`, `/disable-addons`). || `default_player` | string or null | Preferred player: `mpv`, `iina`, `vlc`, `android`; absent/null until you choose one from the in-app picker. || `download_dir` | string or null | Custom directory for video and subtitle downloads (null uses OS default). |diff --git a/docs/controls.md b/docs/controls.mdindex 525cfac..4beb442 100644--- a/docs/controls.md+++ b/docs/controls.md@@ -64,10 +64,14 @@ Type these commands directly into the search bar:| `/browse` | Streaming / Addon | Browse curated views (Trending, Popular) or Addon catalogs (Top Movies, Top Series) || `/history` | Streaming | View watch history with latest progress || `/list` | TV | View live TV channels |-| `/reload` | TV / Streaming / Addon | Reload active playlist, catalog, or search results |+| `/reload` | TV / Streaming / Addon | Reload active playlist (TV) or refresh catalog & search results || `/config` | TV / Addon | Manage IPTV playlists (TV) or Addon Manager (Addon Mode) || `/addons` | Addon / Streaming | Open Addon Manager dialog |-| `/enable-addons` | All | Enable Addon Mode navigation |+| `/enable-streaming` | All | Enable Streaming Mode navigation in bottom dock |+| `/disable-streaming` | All | Disable Streaming Mode navigation |+| `/enable-tv` | All | Enable TV Mode navigation in bottom dock |+| `/disable-tv` | All | Disable TV Mode navigation |+| `/enable-addons` | All | Enable Addon Mode navigation in bottom dock || `/disable-addons` | All | Disable Addon Mode navigation || `/download-dir` | All | View, change, or reset the download directory || `/theme` | All | Open theme picker (Mocha, Latte, Macchiato, Frappe, Nord, TokyoNight) |diff --git a/docs/cross-platform.md b/docs/cross-platform.mdindex 162bd9b..c9647ca 100644--- a/docs/cross-platform.md+++ b/docs/cross-platform.md@@ -16,20 +16,21 @@ Supported: macOS, Linux, Windows, and Android (Termux). The codebase usesThe app probes the terminal at startup via `ratatui_image`:-- **Poster rendering**: High-resolution graphics via Sixel, Kitty, and iTerm2 protocols when supported by the terminal. Non-graphics terminals (for example Apple Terminal.app or basic xterm) display text placeholders (`Poster unavailable` / `No Art`). Image queries can be disabled via `MOVIEBOX_NO_IMAGE=1`.+- **Poster rendering**: High-resolution graphics via Sixel, Kitty, and iTerm2 protocols when supported by the terminal. Non-graphics terminals (for example Apple Terminal.app or basic xterm) display a clean, centered `No Poster` label. Image queries can be disabled via `MOVIEBOX_NO_IMAGE=1`.- **Terminal classification**: `TERM=dumb`/`linux` fall back to a basic UI.- Focus events (focus loss/gain) are used to re-render in place without clearing.## Network & TLS portability-- **TLS Engine**: Uses pure-Rust `rustls` across all targets (macOS, Linux, Windows, Android/Termux), eliminating external C dependencies on OpenSSL.+- **TLS Engine**: Uses pure-Rust `rustls` with embedded Mozilla roots (`webpki-roots`) across all targets (macOS, Linux, Windows, Android/Termux), eliminating external C dependencies on OpenSSL and avoiding platform verifier crashes in Android/Termux CLI environments.- **DNS Resolution**: Uses standard POSIX/WinSock system DNS (`getaddrinfo`) on all platforms, without requiring JNI or `ndk-context`.## Things to verify per release- Player launch on each OS (mpv/VLC/IINA/Android intent) — window sizing, subtitles,headers.-- Poster rendering across Sixel (Windows Terminal, foot), Kitty, and half-block- terminals.+- Poster rendering across Sixel (Windows Terminal, foot), Kitty, iTerm2, and basic+ non-graphics terminals.- TV mode with a sample M3U playlist (URL and local file).+- Addon Mode with sample HTTP addon manifests (Cinemeta, torrent/stream addons).- Termux: on-device check that Play opens the Android chooser and the stream plays.diff --git a/docs/modules.md b/docs/modules.mdindex e499cc8..4db0211 100644--- a/docs/modules.md+++ b/docs/modules.md@@ -14,8 +14,9 @@ src/cache.rs Disk cache: provider-namespaced directories, TTL expiry,atomic temp-file writes, payload validation, background purge.- config.rs Config struct: load/save config.json (provider, theme,- auto-update, default player, bdix flag).+ config.rs Config struct: load/save config.json (mode persistence,+ mode toggles, provider, theme, auto-update, default player,+ download directory, bdix flag).download.rs Download engine (pure, async): resume via .part files,HTTP ranges, optional multi-segment download, retries, cancel@@ -63,6 +64,8 @@ src/tui/action.rs The Action enum: every UI event/message (input, networkresults, downloads, playback, tv, system).+ commands.rs Slash command registry (SlashCommand enum, argument parsing,+ availability filters, dynamic suggestions, descriptions).state.rs AppState: all UI state, LRU image/preview caches, and thePlayerKind enum + label()/parse(), tv manager row model.event.rs EventHandler: crossterm event stream + tick interval,diff --git a/docs/tv-mode.md b/docs/tv-mode.mdindex b31547d..21db18b 100644--- a/docs/tv-mode.md+++ b/docs/tv-mode.md@@ -37,5 +37,8 @@ namespace.## Commands in TV mode-Only `/config` and `/list` are active. Other slash commands are streaming-mode only;-the app tells you to switch modes instead of silently doing nothing.+- `/list` — display all loaded TV channels.+- `/config` — open the TV Playlist Manager dialog.+- `/reload` (or `[r]`) — reload all active M3U playlist sources.+- Global commands (`/theme`, `/download-dir`, `/update`, `/toggle-update`, `/clear-cache`, `/github`, `/enable-tv`, `/disable-tv`, `/enable-streaming`, `/disable-streaming`, `/enable-addons`, `/disable-addons`) are active across all modes.+- Streaming/Addon-only commands (e.g. `/browse`, `/history`, `/enable-bdix`) display friendly guidance notifications prompting you to switch modes (`Ctrl+S` or `Ctrl+A`).