Skip to content

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

2.0 KB
Raw Blame

Binary Cache & Storage

MovieBox-TUI uses a disk-backed binary MessagePack caching engine to minimize network requests while maintaining fast startup times.

Cache Directory

  • Linux / macOS / Termux: ~/.cache/moviebox-tui/
  • Windows: %LOCALAPPDATA%\MovieBox-Tui\cache\

Override with the MOVIEBOX_CACHE_DIR environment variable.

Binary Cache Architecture

Cache files use a structured MessagePack envelope preceded by a 4-byte magic signature (MBC1):

[ 0x4D 0x42 0x43 0x31 ] [ MessagePack Encoded Envelope ]

The envelope stores the expiration timestamp (expires_at: u64) alongside the serialized payload. On read, if the current time exceeds expires_at or the file age exceeds the TTL, the cache is invalidated and refetched.

Cache TTLs

Namespace TTL Description
homepage 1 Hour Trending, popular, and curated /browse feeds
search 24 Hours Search query results per provider
details Dynamic (CloudFront TTL) Subject details, cast, and signed streaming cookies (auto-adapts to upstream cookie expiration, min 1h, max 24h)
streams Dynamic (Cookie Expiration) Direct streaming and DASH manifest URLs (auto-adapts to CloudFront-Policy and Edge-Cache-Cookie expiration timestamp :t=, min 1m, max 2h)
captions 24 Hours Aggregated MovieBox external subtitle lists (primary + sibling dubs, background-prefetched on Details load)
posters 30 Days Downloaded poster image buffers
tv 24 Hours Remote M3U playlist text snapshots

Durability & Safety

  • Atomic File Writes: All cache entries write to a temporary sidecar file (.tmp-<pid>-<stamp>) and rename atomically to the destination so interrupted writes never corrupt cache files.
  • Automatic Purging: Stale cache entries older than 7 days are automatically removed by a background worker at startup.
  • Manual Purge: Enter /settings → Maintenance → Clear Disk Cache to immediately wipe all cached files, images, and playlist snapshots.