Skip to content

Terminal interface to find, download, and stream movies, TV shows, and live TV using local media players.

chore: harden cross-platform release readiness

Samir Hossains90dba2934820
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index a9ad65d..aee2867 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -5,9 +5,10 @@
## Checklist
- [ ] `cargo fmt --check` succeeds
-- [ ] `cargo clippy --all-targets --locked -- -D warnings` succeeds
-- [ ] `cargo check --locked` succeeds
+- [ ] `cargo clippy --all-targets --all-features --locked -- -D warnings` succeeds
+- [ ] `cargo check --all-targets --all-features --locked` succeeds
+- [ ] `cargo test --all-features --locked` succeeds
- [ ] Docs updated if this changes features, keybindings, or usage
-- [ ] No placeholder test step was added; this repo currently has no unit-test suite
+- [ ] Platform-specific changes include or update deterministic tests where possible
> Formatting and linting are enforced automatically by the pre-commit hook and CI.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 2ff09e5..47aaec6 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -26,7 +26,10 @@ jobs:
with:
prefix-key: "ci-hygiene"
- run: cargo fmt --check
- - run: cargo clippy --all-targets --locked -- -D warnings
+ - name: Validate Unix installer syntax
+ run: bash -n install.sh
+ - run: cargo check --all-targets --all-features --locked
+ - run: cargo clippy --all-targets --all-features --locked -- -D warnings
- name: Audit dependencies
uses: taiki-e/install-action@v2
with:
@@ -50,5 +53,18 @@ jobs:
- uses: Swatinem/rust-cache@v2
with:
prefix-key: "ci-build-test-${{ matrix.os }}"
- - run: cargo build --locked
- - run: cargo test --locked
+ - run: cargo build --all-features --locked
+ - run: cargo test --all-features --locked
+ - name: Smoke-test binary startup
+ run: cargo run --all-features --locked -- --version
+ - name: Validate Windows installer syntax
+ if: runner.os == 'Windows'
+ shell: pwsh
+ run: |
+ $tokens = $null
+ $errors = $null
+ [System.Management.Automation.Language.Parser]::ParseFile("install.ps1", [ref]$tokens, [ref]$errors) | Out-Null
+ if ($errors.Count -gt 0) {
+ $errors | Format-List
+ exit 1
+ }
diff --git a/.github/workflows/homebrew.yml b/.github/workflows/homebrew.yml
index 326d6ee..73a284e 100644
--- a/.github/workflows/homebrew.yml
+++ b/.github/workflows/homebrew.yml
@@ -8,7 +8,7 @@ on:
workflow_dispatch:
inputs:
tag:
- description: "Release tag to mirror into Homebrew (e.g. v0.1.12)"
+ description: "Release tag to mirror into Homebrew (e.g. v0.1.13)"
required: true
jobs:
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index d120a11..a5398ea 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -8,7 +8,7 @@ on:
workflow_dispatch:
inputs:
tag:
- description: "Release tag to publish (e.g. v0.1.12)"
+ description: "Release tag to publish (e.g. v0.1.13)"
required: true
permissions:
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 82a9ce9..8295238 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -95,11 +95,11 @@ jobs:
- name: Build Linux binary
if: matrix.os == 'ubuntu-latest'
- run: cross build --release --locked --target ${{ matrix.target }}
+ run: cross build --release --all-features --locked --target ${{ matrix.target }}
- name: Build macOS or Windows binary
if: matrix.os != 'ubuntu-latest'
- run: cargo build --release --locked --target ${{ matrix.target }}
+ run: cargo build --release --all-features --locked --target ${{ matrix.target }}
- name: Archive Unix
if: matrix.os != 'windows-latest'
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5b0b43e..676edb2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,13 @@
- Added mouse support for the landing Favorites row (select/open rows, open the full list via the overflow line).
- Extracted cross-provider title-identity matching into `SubjectIdentity` (`src/models.rs`), now shared by watch history and Favorites so remakes, cross-provider duplicates, and movie/series title collisions are deduplicated identically.
+### Fixed
+- **External player failure reporting**: Treat every non-zero player exit, including exits after several seconds or without stderr output, as a playback error instead of reconciling false watch progress.
+- **Playback state safety**: Sanitize provider and subject identifiers before using them in tracker state filenames.
+- **Cross-platform release validation**: Run all-feature locked builds/tests, binary startup smoke tests, Unix and Windows installer syntax checks, and release-target builds in CI.
+- **Documentation accuracy**: Document Android intent limitations, the actual Termux binary model, macOS-only IINA support, native runtime verification requirements, and the current automated test count.
+- **Installer checksum handling**: Compare SHA-256 values case-insensitively on macOS, Linux, and Termux shells.
+
## [0.1.13] - 2026-08-21
### Added
diff --git a/README.md b/README.md
index a2fa451..4eeaa50 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@ https://github.com/user-attachments/assets/60b5fab9-cf7a-4a59-9bbf-b2357c345091
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 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 `IINA`), with no ads or popups inside the application.
+**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.
### Quick Comparison
@@ -35,14 +35,14 @@ Searching and watching media through web browsers often means dealing with heavy
- **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).
- **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**, **VLC**, or **IINA** using your computer's hardware for smooth video.
+- **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:** Star any movie or series with `*` (or `f` on the details screen) and reach it instantly from a dedicated row on the home screen, or view the full list with `/favorites`.
- **Simple Terminal Interface:** Full keyboard and mouse support, beautiful color themes, and movie poster art.
## Installation
-A media player (**[mpv](https://mpv.io)**, **[VLC](https://www.videolan.org/vlc/)**, or **[IINA](https://iina.io)**) is recommended for video playback.
+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.
### macOS
diff --git a/docs/cross-platform.md b/docs/cross-platform.md
index c1ed9ae..ae00f75 100644
--- a/docs/cross-platform.md
+++ b/docs/cross-platform.md
@@ -1,16 +1,21 @@
# Cross-platform
-Supported: macOS, Linux, Windows, and Android (Termux). The codebase uses
+Build targets: macOS, Linux, Windows, and Android (Termux via the Linux ARM64
+binary). The codebase uses
`crossterm` (all platforms), `ratatui`, and a couple of small per-OS branches.
+"Build target" does not mean every runtime integration is verified on every
+device. Desktop builds are covered by CI; external players and Termux require
+the release checks in [`release-checklist.md`](release-checklist.md).
+
## OS notes
| Platform | Notes |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| macOS | IINA preferred player (via bundled `iina-cli`); VLC/mpv `.app` paths detected. `process_group(0)` on spawn. |
+| macOS | IINA preferred player (via the installed IINA `iina-cli`); VLC/mpv `.app` paths detected. `process_group(0)` on spawn. |
| Windows | mpv/VLC detected via Program Files + `%LOCALAPPDATA%`; players spawned with `CREATE_NO_WINDOW`; path-safe file stems; static MSVC CRT linking (`+crt-static`) for zero-dependency standalone binaries. |
| Linux | Flatpak mpv/VLC supported (`flatpak run …`); xdg data/cache dirs. |
-| Android (Termux) | Dynamic filesystem checks for `/system/bin/am` or `termux-open`; playback strips `LD_LIBRARY_PATH` and `LD_PRELOAD` before launching the chooser. Real-device chooser behavior should be confirmed separately because the release pipeline is desktop-focused; Proot/Termux X11 behavior is environment-dependent. |
+| Android (Termux) | Uses the Linux ARM64 binary and dynamically checks for `/system/bin/am` or `termux-open`; playback strips `LD_LIBRARY_PATH` and `LD_PRELOAD` before launching the chooser. Android intent playback cannot forward stream headers or attach subtitles. Real-device chooser behavior is a release prerequisite; Proot/Termux X11 behavior is unsupported unless separately tested. |
## Terminal capabilities
@@ -22,7 +27,7 @@ The app probes the terminal at startup via `ratatui_image`:
## Network & TLS portability
-- **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.
+- **TLS Engine**: Uses `rustls` with embedded Mozilla roots (`webpki-roots`) across all targets (macOS, Linux, Windows, Android/Termux). The release binary has no OpenSSL runtime dependency; the `ring` cryptography backend is compiled into the binary by the platform build toolchain.
- **DNS Resolution**: Uses standard POSIX/WinSock system DNS (`getaddrinfo`) on all platforms, without requiring JNI or `ndk-context`.
## Things to verify per release
diff --git a/docs/known-issues.md b/docs/known-issues.md
index a4d46b4..226abc2 100644
--- a/docs/known-issues.md
+++ b/docs/known-issues.md
@@ -26,6 +26,6 @@ Tracked here so future work and issue reports reference the same facts.
## Verification
-- Automated testing is enforced via `cargo test --locked` covering 132 unit and integration tests across 16 test suites (see [`docs/testing.md`](testing.md)).
-- Static correctness is enforced by strict compiler type checking, the lint gate (`cargo clippy --all-targets --all-features -- -D warnings`), formatting (`cargo fmt --check`), dependency vulnerability scanning (`cargo audit`), and packaging verification (`cargo package --locked`).
+- Automated testing is enforced via `cargo test --all-features --locked` covering 169 unit and integration tests across 16 test suites (see [`docs/testing.md`](testing.md)). The count is updated when tests change; it does not replace real-player and real-device verification.
+- Static correctness is enforced by strict compiler type checking, the lint gate (`cargo clippy --all-targets --all-features --locked -- -D warnings`), formatting (`cargo fmt --check`), dependency vulnerability scanning (`cargo audit`), and packaging verification (`cargo package --locked`).
- Runtime and platform-specific behavior (terminal resize, focus handling, external player launch, and Termux chooser) are verified through the release checklist in [`release-checklist.md`](release-checklist.md).
diff --git a/docs/players.md b/docs/players.md
index f2fccc6..e3c3be0 100644
--- a/docs/players.md
+++ b/docs/players.md
@@ -24,7 +24,7 @@ detected player and saves the chosen player as the next default unless
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| mpv | `mpv --autofit=WxH --geometry=50%:50% --idle=no --keep-open=no [--start=..] [--script=..] [--script-opts=..] [--http-header-fields=..] [--sub-file=..] <url>` | Window sized to the terminal. Injects `moviebox_tracker.lua` for position tracking and resume. Flatpak mpv is launched via `flatpak run`. |
| VLC | `vlc --width=W --height=H --play-and-exit [--start-time=..] [--http-referrer=..] [--http-user-agent=..] [--sub-file=..] <url>` | Supports start time resume via `--start-time`. |
-| IINA | `iina-cli --keep-running --no-stdin --mpv-autofit=.. [--mpv-start=..] --mpv-http-header-fields=.. --mpv-sub-files=.. <url>` | Uses the bundled `iina-cli`; falls back to `open -a IINA <url>` only if the CLI is absent. |
+| IINA | `iina-cli --keep-running --no-stdin --mpv-autofit=.. [--mpv-start=..] --mpv-http-header-fields=.. --mpv-sub-files=.. <url>` | Uses the installed IINA `iina-cli`; falls back to `open -a IINA <url>` only if the CLI is absent. |
| Android / Proot | `termux-open --chooser --content-type video/* <url>` (or absolute `/system/bin/am start` fallback, ensuring `.so` injections are dropped) | Opens an app chooser on the device. Device-specific chooser behavior should be confirmed for each release. |
Window size is derived from the live terminal size times the font cell size reported
@@ -60,4 +60,5 @@ reconciled into `history.json`.
`launch_player` spawns the player with null stdin/stdout, piped stderr, and its own
process group (Unix) or no-console flag (Windows). A blocking task reads stderr and
-reports a crash if the process exits non-zero within a few seconds with output.
+reports every non-zero process exit as a player error, including failures with no
+diagnostic output. Watch progress is reconciled only after a successful exit.
diff --git a/docs/release-checklist.md b/docs/release-checklist.md
index 244a13b..70f7c89 100644
--- a/docs/release-checklist.md
+++ b/docs/release-checklist.md
@@ -11,13 +11,17 @@ Run the repository checks first:
```bash
cargo fmt --check
cargo clippy --all-targets --all-features --locked -- -D warnings
-cargo check --locked
-cargo test --locked
+cargo check --all-targets --all-features --locked
+cargo test --all-features --locked
cargo audit
cargo package --locked
```
-Confirm the entire unit and integration test suite passes cleanly across all targets (`docs/testing.md`).
+Confirm the entire unit and integration test suite passes on the CI host matrix
+(`docs/testing.md`). Release targets that are cross-compiled must at least build
+cleanly on the release runners; they still require native runtime checks before
+release certification. A local host without the target C/linker toolchain cannot
+substitute for that runner result.
Confirm the main GitHub Actions workflows are green:
diff --git a/docs/testing.md b/docs/testing.md
index 35972b5..d3982c1 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -66,21 +66,21 @@ Integration tests live in the `tests/` directory and test externally observable
Run the full test suite (all unit and integration tests):
```bash
-cargo test
+cargo test --all-features --locked
```
Run only unit tests:
```bash
-cargo test --lib
+cargo test --lib --all-features --locked
```
Run a specific integration test:
```bash
-cargo test --test history_reconciliation
-cargo test --test player_integration
-cargo test --test m3u_integration
+cargo test --test history_reconciliation --all-features --locked
+cargo test --test player_integration --all-features --locked
+cargo test --test m3u_integration --all-features --locked
```
---
@@ -94,10 +94,10 @@ Every commit and pull request must pass all hygiene checks:
cargo fmt -- --check
# Compiler check
-cargo check
+cargo check --all-targets --all-features --locked
# Clippy linter with warnings treated as errors
-cargo clippy --all-targets --all-features -- -D warnings
+cargo clippy --all-targets --all-features --locked -- -D warnings
# Security vulnerability scan
cargo audit
diff --git a/install.sh b/install.sh
index e5c5033..af6dcc0 100755
--- a/install.sh
+++ b/install.sh
@@ -56,7 +56,7 @@ USAGE:
./install.sh [OPTIONS]
OPTIONS:
- -v, --version <tag> Install a specific version (e.g. v0.1.12)
+ -v, --version <tag> Install a specific version (e.g. v0.1.13)
--dir <path> Install binary to a custom directory
-f, --force Reinstall even if already at the latest version
--dry-run Perform preflight checks without writing files
@@ -442,7 +442,8 @@ verify_checksum() {
return 1
fi
- [ "$actual_sha" = "$expected_sha" ]
+ [ "$(printf '%s' "$actual_sha" | tr '[:upper:]' '[:lower:]')" = \
+ "$(printf '%s' "$expected_sha" | tr '[:upper:]' '[:lower:]')" ]
}
run_spinner "[3/4] Verifying SHA256 checksum" verify_checksum || exit 1
diff --git a/src/player.rs b/src/player.rs
index 1757225..62b7ebb 100644
--- a/src/player.rs
+++ b/src/player.rs
@@ -668,4 +668,47 @@ mod tests {
let opts = format_mpv_script_opts("moviebox", "123", 1, 1, &unix_path);
assert!(opts.contains("moviebox-state_file=/home/user/.local/share/moviebox-tui/playback/moviebox_123_1_1.json"));
}
+
+ #[test]
+ fn vlc_command_preserves_supported_playback_options() {
+ let command = vlc_command(
+ "https://example.test/video.m3u8",
+ Some("/tmp/subtitle.srt"),
+ &[
+ ("Referer".into(), "https://example.test/".into()),
+ ("User-Agent".into(), "MovieBox-Test".into()),
+ ("Cookie".into(), "ignored=by-vlc-filter".into()),
+ ],
+ Some((1280, 720)),
+ Some(42),
+ );
+ let args = command
+ .get_args()
+ .map(|arg| arg.to_string_lossy().into_owned())
+ .collect::<Vec<_>>();
+
+ assert!(args.contains(&"--width=1280".into()));
+ assert!(args.contains(&"--height=720".into()));
+ assert!(args.contains(&"--play-and-exit".into()));
+ assert!(args.contains(&"--start-time=42".into()));
+ assert!(args.contains(&"--http-referrer=https://example.test/".into()));
+ assert!(args.contains(&"--http-user-agent=MovieBox-Test".into()));
+ assert!(args.contains(&"--sub-file=/tmp/subtitle.srt".into()));
+ assert!(!args.iter().any(|arg| arg.starts_with("--http-cookie")));
+ assert_eq!(
+ args.last().map(String::as_str),
+ Some("https://example.test/video.m3u8")
+ );
+ }
+
+ #[test]
+ fn header_support_rejects_android_and_unsupported_vlc_headers() {
+ let headers = vec![("Cookie".into(), "session=secret".into())];
+ assert!(!supports_headers(PlayerKind::AndroidIntent, &headers));
+ assert!(!supports_headers(PlayerKind::Vlc, &headers));
+ assert!(supports_headers(
+ PlayerKind::Vlc,
+ &[("referer".into(), "https://example.test/".into())]
+ ));
+ }
}
diff --git a/src/player/tracker.rs b/src/player/tracker.rs
index 7b7db36..df9399a 100644
--- a/src/player/tracker.rs
+++ b/src/player/tracker.rs
@@ -94,7 +94,29 @@ pub fn state_file_path(
if !dir.exists() {
let _ = fs::create_dir_all(&dir);
}
- let sanitized_id = subject_id.replace(['/', '\\', ':', ' '], "_");
- let filename = format!("{provider}_{sanitized_id}_{season}_{episode}.json");
+ let sanitized_provider = sanitize_component(provider);
+ let sanitized_id = sanitize_component(subject_id);
+ let filename = format!("{sanitized_provider}_{sanitized_id}_{season}_{episode}.json");
Some(dir.join(filename))
}
+
+fn sanitize_component(value: &str) -> String {
+ value.replace(['/', '\\', ':', ' '], "_")
+}
+
+#[cfg(test)]
+mod tests {
+ use super::sanitize_component;
+
+ #[test]
+ fn state_file_components_are_safe_for_filenames() {
+ assert_eq!(
+ sanitize_component("provider/with\\separators"),
+ "provider_with_separators"
+ );
+ assert_eq!(
+ sanitize_component("subject:with space"),
+ "subject_with_space"
+ );
+ }
+}
diff --git a/src/tui/app/playback.rs b/src/tui/app/playback.rs
index 2ae57c9..12b1a5b 100644
--- a/src/tui/app/playback.rs
+++ b/src/tui/app/playback.rs
@@ -238,16 +238,8 @@ impl App {
let result = child.wait();
- if let Ok(status) = result {
- let clean_error = error_output.trim().to_string();
- if !status.success()
- && start_time.elapsed().as_secs() < 3
- && !clean_error.is_empty()
- {
- sender
- .send(Action::PlayerCrashed(status.code(), clean_error))
- .ok();
- } else {
+ match result {
+ Ok(status) if status.success() => {
sender.send(Action::ReconcileHistory).ok();
if let Some(item) = history_item {
@@ -275,6 +267,21 @@ impl App {
}
}
}
+ Ok(status) => {
+ let clean_error =
+ clean_player_error(status.code(), error_output.trim());
+ sender
+ .send(Action::PlayerCrashed(status.code(), clean_error))
+ .ok();
+ }
+ Err(error) => {
+ sender
+ .send(Action::PlayerCrashed(
+ None,
+ format!("Failed waiting for player process: {error}"),
+ ))
+ .ok();
+ }
}
if let Some(path) = temporary_subtitle {
@@ -305,6 +312,15 @@ impl App {
}
}
+fn clean_player_error(code: Option<i32>, stderr: &str) -> String {
+ if !stderr.is_empty() {
+ return stderr.to_string();
+ }
+
+ code.map(|value| format!("Player exited with status code {value}."))
+ .unwrap_or_else(|| "Player exited unsuccessfully without error output.".to_string())
+}
+
impl App {
pub(super) async fn handle_playback(&mut self, action: Action) -> Option<()> {
match action {
@@ -690,3 +706,28 @@ impl App {
None
}
}
+
+#[cfg(test)]
+mod tests {
+ use super::clean_player_error;
+
+ #[test]
+ fn failed_player_with_stderr_keeps_diagnostic() {
+ assert_eq!(
+ clean_player_error(Some(1), "VLC failed to open the stream"),
+ "VLC failed to open the stream"
+ );
+ }
+
+ #[test]
+ fn failed_player_without_stderr_still_reports_failure() {
+ assert_eq!(
+ clean_player_error(Some(1), ""),
+ "Player exited with status code 1."
+ );
+ assert_eq!(
+ clean_player_error(None, ""),
+ "Player exited unsuccessfully without error output."
+ );
+ }
+}