MovieBox-TUI

A fast, lightweight terminal client for streaming and downloading movies, TV shows, anime, and live TV — powered by your local media player.

moviebox-tui.webm

MovieBox-TUI replaces ad-heavy streaming websites and clunky browser players with a clean, keyboard-driven terminal interface. It scrapes stream links directly from multiple sources and launches playback in your native media player with hardware acceleration, audio track switching, and automatic subtitle synchronization.

Features

• Multi-Source Streaming: Search and stream titles across MovieBox, 4KHDHub, BDIX mirrors, custom IPTV playlists, and community Stremio HTTP addons. Press Ctrl+P on the Details screen to switch providers in-place.
• Hardware-Accelerated Playback: Direct playback in mpv, IINA (macOS), or VLC with stream authentication headers forwarded automatically.
• Automatic Subtitles: Automatically searches, downloads, and syncs subtitles in your preferred language directly into your player.
• Season Batch Downloads: Download individual episodes or entire seasons with one keypress (d), with HTTP range resume support and clean folder structure (Movies/ and Series/).
• Interactive Settings Hub: Configure your default media player, download folder, content modes, and themes inside an in-app visual modal via /settings (Ctrl+S).
• Modes: Switch instantly between standard Streaming, Live TV (Ctrl+T), and Addon Mode (Ctrl+A).
• Ergonomics & Themes: Full keyboard navigation (vim-style j/k, /, Tab) and mouse support (click, scroll, drag) with 6 built-in themes (Catppuccin, TokyoNight, Nord, Dracula, Gruvbox, Rosé Pine) and terminal theme autodetection.

Prerequisites

MovieBox-TUI delegates video decoding to an external media player. Install at least one of the following:

Player	Platform	Quick Install
mpv (Recommended)	Linux, macOS, Windows	brew install mpv / sudo apt install mpv / winget install mpv
IINA	macOS (Native GUI)	brew install --cask iina
VLC	Cross-platform	brew install --cask vlc / sudo apt install vlc / winget install VideoLAN.VLC
Android Player	Android (Termux)	pkg install termux-tools (launches VLC or Nova)

Installation

macOS & Linux

Install via the automated script:

curl -fsSL https://raw.githubusercontent.com/mesamirh/MovieBox-Tui/main/install.sh | bash

macOS users can also install via Homebrew:

brew tap mesamirh/moviebox-tui https://github.com/mesamirh/MovieBox-Tui
brew trust mesamirh/moviebox-tui
brew install moviebox-tui

Windows

Install via PowerShell:

irm https://raw.githubusercontent.com/mesamirh/MovieBox-Tui/main/install.ps1 | iex

Android (Termux)

Install Termux tools, run the installer, and grant storage permissions:

pkg update && pkg install termux-tools
curl -fsSL https://raw.githubusercontent.com/mesamirh/MovieBox-Tui/main/install.sh | bash
termux-setup-storage

Manual & Developer Builds (Cargo)

Install directly from crates.io:

cargo install moviebox-tui --locked

Or compile from source:

git clone https://github.com/mesamirh/MovieBox-Tui.git
cd MovieBox-Tui
cargo build --release --locked

Verify Release Integrity

sha256sum -c SHA256SUMS --ignore-missing
gh attestation verify <archive-file> -R mesamirh/MovieBox-Tui

Quick Start

Launch the application:

moviebox-tui

• Interactive Help: Press ? inside the app anytime to view the mode-aware keyboard shortcuts and mouse guide.
• Settings: Type /settings or press Ctrl+S to configure your default player, download directory, and content modes.
• Controls Reference: See docs/controls.md for the complete list of keybindings, mouse actions, and slash commands.

Documentation

Comprehensive guides are available in the docs/ directory:

• Controls & Shortcuts — Complete keybindings, navigation, and slash commands
• Media Players — Player options, custom paths, and launch flags
• Downloads & Organization — Multi-segment download engine and folder layout
• Live TV — Adding and managing custom M3U playlists
• Addon Mode — Installing and managing Stremio HTTP addons
• Configuration — config.json reference and MOVIEBOX_* environment variables
• Providers — Supported content sources and resolver protocols
• Architecture — Subsystem map, event loop, and caching model
• Documentation Index — Full documentation directory

Contributing

Contributions are welcome! Please review CONTRIBUTING.md before submitting pull requests.

If you encounter a bug or have a feature request, feel free to open an issue.

Optional Support

If you would like to support ongoing development directly:

Network / Asset	Address
USDT (TRC20)	TL4yW73qmbKZpBWwbEFgjBpwVkPDFTkJgV
Bitcoin (BTC)	3MEAtqtRWrQBhnaMi3Zuf5nt2efNUS2LUQ
Ethereum / EVM	0x7ea20d5fa29d87f33195f5a3b211ff94038d794c
Solana (SOL)	6ctm5WFv73MNywoCKAz3xK72yizSspHa72rFNygooU6

License

Licensed under either MIT or Apache-2.0.

Disclaimer

This project does not host or store any media. It is an independent client for playing publicly available streams. Users are responsible for complying with the laws of their country.