Keyboard shortcuts

Press or to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction

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

moviebox-tui walkthrough.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:

PlayerPlatformQuick Install
mpv (Recommended)Linux, macOS, Windowsbrew install mpv / sudo apt install mpv / winget install mpv
IINAmacOS (Native GUI)brew install --cask iina
VLCCross-platformbrew install --cask vlc / sudo apt install vlc / winget install VideoLAN.VLC
Android PlayerAndroid (Termux)pkg install -y termux-tools termux-am (launches external player)

Documentation Directory Map

Getting Started

GuideDescription
InstallationPlatform installation instructions, package managers, and binary verification
Keyboard & ControlsComplete keybindings, vim navigation, text editing, and slash commands
Configuration Guideconfig.json schema, settings hub options, and environment variables

Features & Modes

GuideDescription
Content ProvidersBuilt-in providers, scrapers, stream extractors, and authentication headers
Hardware PlayersMedia player detection, launch flags, stream headers, and watch tracking
Batch DownloadsMulti-segment download engine, range resume, and folder layout
Stremio AddonsAddon manifest installation, catalog browsing, and stream resolution
Live TV & IPTVM3U playlist manager, channel parsing, and live stream playback

Architecture & Internals

GuideDescription
System ArchitectureSubsystem diagrams, async event loop, and task cancellation
Module BreakdownCrate structure, module responsibilities, and call boundaries
Caching StrategyBinary disk caching, TTL policies, and LRU memory management
Logging SystemFile logging, log rotation, and tracing diagnostics
Cross-Platform OperationsPlatform compatibility matrix across macOS, Linux, Windows, and Termux

Reference & Maintenance

GuideDescription
Testing SuiteUnit tests, integration tests, and verification gates
Debugging GuideTroubleshooting common issues, terminal rendering, and player errors
Release ChecklistPre-release validation, binary packaging, and deployment workflow
Known IssuesTracked limitations, terminal quirks, and workarounds
Contributing GuideContribution guidelines, code standards, and PR process
ChangelogComplete release history and unreleased changes