Skip to content

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.md
index 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.md
index 15a7ca0..7f202b9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -23,7 +23,7 @@ git config core.hooksPath .githooks
cargo 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.md
index c68a821..4a5eb26 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -44,11 +44,13 @@ src/
episode-stream actions
navigation.rs list navigation, submit actions, provider helpers
tv.rs TV mode: playlist manager + playback
+ addons.rs Addon mode: addon manager + HTTP addon actions
keyboard.rs raw key-event handling
mouse.rs mouse click handling and hitbox routing
system.rs help, refresh, cache, theme, updates, focus, resize
state.rs AppState: all UI state + in-memory LRU caches
action.rs the Action enum (event/message model)
+ commands.rs Slash command registry, parsing, and suggestions
event.rs EventHandler: input events + tick → Action channel
overlay.rs popups, pickers, notifications
screens/ 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.md
index 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, addons
search/<hash>.json
details/details_<hash>.json
streams/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 from
different 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 never
leaves a corrupt cache entry.
- **Validation**: search/stream entries are only cached (and only served) if they
diff --git a/docs/config.md b/docs/config.md
index 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.md
index 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.md
index 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 uses
The 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.md
index 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, network
results, 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 the
PlayerKind 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.md
index 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`).