MovieBox-Tui is a terminal UI I built to search MovieBox's public catalog and stream the results in my favorite video player, without leaving the terminal. It talks to the MovieBox API directly, resolves the video URLs it returns, and hands them off to mpv, IINA, or VLC.

No browsers, no ads, no login walls, no configuration. Type a title, pick a quality, watch.

Note: This project is a client for a third-party service. It does not host, store, or redistribute any media. It only resolves the links the upstream API returns. It is intended strictly for educational and personal use. You are responsible for complying with copyright law in your jurisdiction.

A short walkthrough of the app in action:

• What it can do
• Screenshots
• Platform support
• Requirements
• Install
• Getting started
• Keybindings
• How it works
• Project layout
• Troubleshooting
• Contributing
• Acknowledgements
• License

Search and discovery

• Type-to-search with live, debounced suggestions.
• Slash commands to browse curated feeds: /movies, /shows, /anime, /discover.
• Each result shows a poster, release year, and (when highlighted) IMDb rating and genres.

Playback

• Detects mpv, IINA, and VLC at startup. You get a picker for whatever you have installed.
• Full season and episode browsing for TV series and anime, with per-episode stream resolution.
• Multiple resolutions (1080p, 720p, 480p, 360p) are fetched in parallel and listed by quality.
• Attach external subtitle tracks, and switch between available audio dubs before playing.
• If a stream fails or expires, hit R to re-resolve it.

Downloading and sharing

• Built-in multi-connection downloader. Uses up to 16 parallel connections when the source allows range requests, with live speed, ETA, progress bar, and cancel.
• Copy any direct stream URL to your clipboard with a single keystroke.
• Downloads go to your system Downloads folder.

The interface

• Real poster art rendered inline in terminals that support graphics (Kitty, WezTerm, iTerm2, Ghostty, foot, etc.).
• In-app notification when a newer version is published to crates.io.
• The details view shows the poster, IMDb rating, year, genres, duration, country, and full description alongside the season, episode, and stream panels.

Home and search

Home	Search results

Details view

Movie	TV series

Discover feeds

Movies	Series	Anime

You need three things:

1. A video player. mpv is the default and the most reliable. IINA (macOS) and VLC also work. The app detects whichever you have installed.
2. A terminal at least 85×24. Anything smaller and the app will show a message asking you to enlarge it.
3. Rust 1.85 or newer (edition 2024), only if you want to build from source. See rustup.rs. If you install from crates.io, you already have it.

For inline poster art, you'll want a terminal that speaks a graphics protocol: Kitty, WezTerm, iTerm2, Ghostty, or foot. Other terminals still work fine, you just get placeholder blocks instead of images.

# macOS
brew install mpv
# or, for a native-feel alternative
brew install --cask iina

# Debian / Ubuntu
sudo apt install mpv

# Arch Linux
sudo pacman -S mpv

# Fedora
sudo dnf install mpv

# Windows (Chocolatey)
choco install mpv

The recommended way is to install from crates.io:

cargo install moviebox-tui

Make sure ~/.cargo/bin is on your PATH, then run:

moviebox-tui

git clone https://github.com/mesamirh/MovieBox-Tui.git
cd MovieBox-Tui
cargo install --path .

cargo run --release

Launch the app:

moviebox-tui

You'll land on the home screen. From there:

1. Just start typing. The search bar activates automatically and live suggestions appear as you type.
2. Or use a discover command: type /movies, /shows, /anime, or /discover and press Enter to browse curated feeds.
3. Move through results with Up/Down. The selected result loads a poster preview with IMDb rating and genres.
4. Press Enter to open the details view.
5. For a TV series, pick a season and episode. If multiple language dubs are available, you'll be asked to pick one.
6. Choose a stream quality and hit Enter to play in mpv, or o to pick a different player.

Press ? at any time to see all keybindings.

The app has two layers.

The provider layer (src/providers/moviebox/) is a small HTTP client for the MovieBox API. It rotates through a pool of API hosts, signs each request with an HMAC-MD5 signature, and retries automatically on transient failures. When you open a title, it fires off requests for every resolution in parallel and deduplicates the results. That is why picking a quality feels instant.

The TUI layer (src/tui/) is where everything you see happens. It is built on Ratatui and driven by an async event loop. Every keystroke, network response, and background task becomes an Action on a single channel, so the interface never blocks. Poster images decode on background tasks and get cached in an LRU so scrolling through search results stays smooth.

Playback is not reinvented. The app just spawns your video player with the resolved URL and any subtitle track you picked. That means all the polish (hotkeys, subtitles, seeking) comes from mpv, IINA, or VLC, exactly as you would expect them to behave.

src/
├── main.rs                     Binary entry: terminal + tokio setup
├── lib.rs                      Library root
├── providers/
│   └── moviebox/
│       ├── client.rs           HTTP client, host-pool failover, retries
│       ├── crypto.rs           HMAC-MD5 request signing + device spoofing
│       └── mod.rs              High-level API calls
└── tui/
    ├── app.rs                  Event loop and Action handlers
    ├── action.rs               The Action enum (every event in one place)
    ├── event.rs                Crossterm to Action bridge
    ├── state.rs                Application state
    ├── theme.rs                Colors
    └── screens/
        ├── home.rs             Home, search, and result list
        ├── details.rs          Movie / series detail view
        └── help.rs             Keybindings overlay

If you're poking around the code, src/tui/app.rs is the map. Every user action, network response, and background task funnels through its match statement.

Contributions are welcome. If you're planning something bigger than a small fix, please open an issue first so we can talk it through.

git clone https://github.com/<your-username>/MovieBox-Tui.git
cd MovieBox-Tui
cargo build

# Before opening a PR:
cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings

Commits follow Conventional Commits (feat:, fix:, docs:, etc.). See CONTRIBUTING.md for the full guide.

Built with Ratatui, crossterm, ratatui-image, tokio, and reqwest. Playback is powered by mpv, IINA, and VLC.

Dual-licensed under MIT or Apache 2.0 at your option.