movie-box

Python CLI movie downloader & async API — by parthmax v1.0.1

pip install "movie-box-dl[cli]"

movie-box is an educational open-source Python tool for searching, downloading, and streaming movies and TV series from the terminal. It ships a cyberpunk interactive shell, an async Python API with Pydantic models, subtitle support, and a multi-version backend (v1 / v2 / v3).

⚡

Interactive Shell

Type movie-box and get a cyberpunk slash-command shell with autocomplete

🎬

Movies & TV Series

Download or stream any movie or TV episode at up to 1080p

📝

Subtitle Support

Download multi-language subtitles alongside video or separately

▶️

Direct Streaming

Stream via MPV or VLC without saving to disk

🚀

5× Faster Downloads

Parallel chunked downloads with resumable part files

🐍

Async Python API

Clean async API with Pydantic models, sync wrappers available

🔧

v1 / v2 / v3 Backends

Multiple API versions for different providers and content types

🖥️

Textual Dashboard

Full-screen TUI app via movie-box app

Installation

CLI (recommended for end users)

pip install "movie-box-dl[cli]"

Installs the base package plus Rich, PromptToolkit, pyfiglet, and Textual for the full terminal experience.

Base package (Python API only)

pip install movie-box-dl

With uv (faster)

uv pip install "movie-box-dl[cli]"
# or add to project
uv add "movie-box[cli]"

From source (latest unreleased)

pip install "git+https://github.com/parthmax2/movie-box.git[cli]"

Termux / Android

pip install movie-box-dl --no-deps
pip install "pydantic==2.9.2"
pip install rich click bs4 httpx throttlebuster

Optional — Media Players for Streaming

Install MPV or VLC to enable direct streaming without downloading.

sudo apt install mpv          # Ubuntu/Debian
sudo dnf install mpv          # Fedora/RHEL
sudo pacman -S mpv            # Arch

brew install mpv

Download the installer from mpv.io/installation or install via Scoop:

scoop install mpv

Quick Start

Check your setup

movie-box doctor

Open the interactive shell

Tip

Typing movie-box or moviebox alone (no subcommand) goes straight into the interactive cyberpunk shell. No extra arguments needed.

movie-box      # or just: moviebox

One-shot commands

# Search and show a colored results table
movie-box search "Avatar"

# Download a movie (best quality, auto-select first result)
movie-box movie "Avatar" -Y

# Download a TV series episode
movie-box series "Game of Thrones" -s 1 -e 1

# Stream without downloading (requires MPV)
movie-box movie "Avatar" --stream-via mpv

# Stream with a dub language
movie-box series "Money Heist" --dub "English" --stream-via vlc

Python one-liner

import asyncio
from movie_box.v1 import MovieAuto

async def main():
    auto = MovieAuto()
    movie_file, subtitle = await auto.run("Avatar")
    print(movie_file.saved_to)

asyncio.run(main())

Interactive Shell UI

movie-box ships a cyberpunk interactive shell. It remembers your last search, supports PromptToolkit autocomplete, and provides a slash-command interface for searching, browsing, and downloading — all from one prompt.

Launch

movie-box           # recommended — no subcommand needed
moviebox            # identical
movie-box ui        # explicit subcommand (same result)
movie-box ui --no-animation   # skip the startup splash

┌──────────────────────────────────────────────┐

│ * Welcome to MOVIE-BOX CLI v1.0.1 │

│ movie-box — by parthmax │

└──────────────────────────────────────────────┘

movie-box > /search Inception

# Title Year IMDb Type

1 Inception 2010 8.8 Movie

2 Inception (Parody) 2011 - Movie

movie-box > 1

╭─── Selected ────────────────╮

│ Inception (2010) · IMDb 8.8 │

╰─────────────────────────────╯

movie-box > /download 1

Downloading Inception (2010).mp4 …

movie-box > /exit

session closed

Shell Commands

All commands start with /. Omitting the slash on a bare word auto-triggers a search. Type a result number to preview it.

/help

Show the command deck

/search <title>

Search all content types, get a numbered table

/movie <title>

Search movies and preview the top match

/series <title>

Search TV series and preview the top match

/select <n>

Preview result #n from last search

/download <n>

Download movie result #n from last search

/config

Show saved defaults (quality, dir, language)

/doctor

Hint to run full environment check

/clear

Clear terminal and redisplay header

/exit

Close the shell

Shortcuts

# bare word = /search
Inception

# result number = /select N
/search Inception
2               # previews result #2

# /download from last search
/download 2

Autocomplete

With movie-box[cli] installed, start typing / and press Tab to cycle through available commands. The shell uses PromptToolkit with a neon style.

Full-Screen Textual App

For a full-screen terminal dashboard (requires movie-box[cli]), use:

movie-box app

Press q or Escape to quit the Textual app.

Info

The Textual app is a visual launcher. For downloading, use the interactive shell (movie-box) or the one-shot CLI commands.

Friendly CLI Reference

The top-level movie-box / moviebox commands use the v3 backend internally and add a richer search table, numbered selection, previews, saved defaults, and the interactive shell.

Command	Description
`movie-box` / `moviebox`	Launch the interactive shell (no subcommand needed)
`movie-box ui`	Same as above — explicit alias
`movie-box ui --no-animation`	Skip the startup splash
`movie-box app`	Full-screen Textual dashboard
`movie-box search <query>`	Colored results table with optional selection
`movie-box movie <title>`	Search, select, download, or stream a movie
`movie-box series <title>`	Search, select, download, or stream TV series episodes
`movie-box config`	Manage saved defaults
`movie-box doctor`	Check Python, dependencies, and media players

movie-box search

movie-box search "Avatar"
movie-box search "Avatar" --select          # prompt to pick one
movie-box search "Avatar" -t movie          # filter by type: movie|series|anime|music|education|all
movie-box search "Avatar" -y 2009           # filter by year
movie-box search "Avatar" -l 5             # limit to 5 results

movie-box movie

movie-box movie "Inception"
movie-box movie "Inception" -q 1080P        # quality: best|1080P|720P|480P|360P
movie-box movie "Inception" -d ~/Movies     # save directory
movie-box movie "Inception" -x English -x Hindi   # subtitle languages
movie-box movie "Inception" --dub "Hindi"   # dub language
movie-box movie "Inception" --caption       # also download subtitles
movie-box movie "Inception" --caption-only  # subtitles only
movie-box movie "Inception" --stream-via mpv
movie-box movie "Inception" --dry-run       # preview without downloading
movie-box movie "Inception" -Y              # skip confirmation prompt

movie-box series

movie-box series "Merlin" -s 1 -e 1         # season 1 episode 1
movie-box series "Merlin" -s 1 -e 1 -l 5   # download 5 episodes
movie-box series "Merlin" -s 1 -e 1 -q 720P
movie-box series "Merlin" -s 1 -e 1 --stream-via vlc
movie-box series "Merlin" -s 1 -e 1 -Y     # skip prompt

moviebox-v1 CLI

Legacy v1 CLI. Supports movies and TV series. Includes popular-search and mirror-hosts commands not in v2/v3.

Env Prefix

MOVIEBOX_ — e.g. MOVIEBOX_API_HOST=https://h5.aoneroom.com

Commands

Command	Description
`download-movie`	Search and download or stream a movie
`download-series`	Search and download or stream a TV series
`item-details`	Show details for a specific title
`homepage-content`	Show Moviebox landing page content
`popular-search`	Show currently trending searches
`mirror-hosts`	Discover available mirror hosts

download-movie examples

moviebox-v1 download-movie "Inception"
moviebox-v1 download-movie "Inception" -q 720p -Y -d ~/Movies
moviebox-v1 download-movie "The Batman" -y 2022 -q 1080p -I
moviebox-v1 download-movie "Inception" -X mpv         # stream
moviebox-v1 download-movie "Inception" -O              # captions only
moviebox-v1 download-movie "Inception" -T              # test, no download

download-series examples

moviebox-v1 download-series "Merlin" -s 1 -e 1
moviebox-v1 download-series "Merlin" -s 2 -e 3 -l 5 -q 720p -f group
moviebox-v1 download-series "The Last Kingdom" -s 1 -e 1 -A   # auto all episodes
moviebox-v1 download-series "Into the Badlands" -s 1 -e 1 -X vlc
moviebox-v1 download-series "Merlin" -s 1 -e 1 -l 13 -f struct -Y

Key Options

Option	Type	Default	Description
`-q, --quality`	best\|1080p\|720p\|480p\|360p\|worst	best	Video quality
`-y, --year`	INTEGER	0	Filter by release year
`-d, --dir`	DIRECTORY	$PWD	Download directory
`-x, --language`	TEXT	English	Subtitle language
`-X, --stream-via`	mpv\|vlc	—	Stream directly
`-Y, --yes`	flag	—	Skip confirmation
`-T, --test`	flag	—	Test without downloading
`-O, --caption-only`	flag	—	Captions only
`-A, --auto-mode`	flag	—	Download all remaining episodes
`-s, --season`	INTEGER	required	Season number (series)
`-e, --episode`	INTEGER	required	Start episode (series)
`-l, --limit`	INTEGER	1	Number of episodes (series)
`-f, --format`	standard\|group\|struct	—	Folder layout (series)
`-t, --tasks`	INTEGER (1–1000)	5	Parallel download tasks

moviebox-v2 CLI

v2 adds support for anime, music, and educational content in download-movie via the -s / --subject-type flag.

Env Prefix

MOVIEBOX_API_HOST_V2=https://mirror.example.com

Subject types (v2 download-movie)

movies · anime · music · education

Examples

moviebox-v2 download-movie "Inception"
moviebox-v2 download-movie "Demon Slayer" -s anime -q 720p -Y
moviebox-v2 download-movie "Cosmos" -s education -d ~/Videos/Docs
moviebox-v2 download-movie "Kendrick Lamar Concert" -s music -X mpv
moviebox-v2 download-series "Merlin" -s 2 -e 3 -l 5 -q 720p -f group

v2 vs v1

v2 is identical to v1 except: download-movie supports extra subject types, and there is no popular-search command.

moviebox-v3 CLI

v3 is the newest backend. It adds dub language selection, --limit -1 for unlimited episodes, and an unknown subject type.

Env Prefix

MOVIEBOX_V3_ — no API host override required for v3.

Key additions over v1/v2

Feature	v1	v2	v3
Dub language (`-u`)	✗	✗	✓
`--limit -1` (unlimited)	✗	✗	✓
Subject type `unknown`	✗	✗	✓
Season/episode defaults	required	required	`1` / `1`

download-movie examples

moviebox-v3 download-movie "Avatar" -YT                    # test, skip prompt
moviebox-v3 download-movie "Avatar" -x en -x filipino -YT  # multiple subtitle langs
moviebox-v3 download-movie "Avatar" --dub hi -YT            # Hindi dub
moviebox-v3 download-movie "walker" -s music -YT            # music content
moviebox-v3 download-movie "Demon Slayer" -s anime -q 1080p -Y -d ~/Videos
moviebox-v3 download-movie "Avengers Endgame" -X mpv        # stream

download-series examples

moviebox-v3 download-series "Merlin" -A                      # all episodes
moviebox-v3 download-series "Merlin" -s 1 -e 1 -l -1        # same as -A
moviebox-v3 download-series "Merlin" -s 2 -e 3 -l 5 -q 720p -f group
moviebox-v3 download-series "Into the Badlands" -s 1 -e 1 -X vlc
moviebox-v3 download-series "Merlin" -A -f struct -Y -d ~/Series

Direct Streaming

Stream content directly into MPV or VLC without writing a file to disk. Requires movie-box[cli] and the player installed.

# Friendly CLI
movie-box movie "Avatar" --stream-via mpv
movie-box movie "Avatar" --stream-via vlc
movie-box series "Game of Thrones" -s 1 -e 1 --stream-via vlc

# v1 / v2 / v3 CLI
moviebox-v1 download-movie "Inception" -X mpv
moviebox-v2 download-movie "Avatar" -X vlc
moviebox-v3 download-series "Merlin" -s 1 -e 1 -X mpv

Note

Temporary files are cleaned up automatically after the player exits.

Python API Overview

movie-box exposes a clean async Python API with Pydantic models. All core classes have two methods: .get_content() (raw dict) and .get_content_model() (Pydantic model). Sync wrappers are provided via _sync variants.

Requirements

The base pip install movie-box-dl is sufficient for the Python API — the [cli] extra is only needed for the terminal UI.

v1 API — Auto Download

MovieAuto — simplest usage

import asyncio
from movie_box.v1 import MovieAuto

async def main():
    auto = MovieAuto()
    movie_file, subtitle_file = await auto.run("Avatar")
    print(f"Movie:    {movie_file.saved_to}")
    print(f"Subtitle: {subtitle_file.saved_to}")

asyncio.run(main())

Behind the scenes MovieAuto does: search → prompt to pick a result → download movie + subtitle.

Custom configuration

from movie_box.v1 import MovieAuto
import asyncio

async def main():
    auto = MovieAuto(
        caption_language="Spanish",
        quality="720p",
        download_dir="~/Downloads"
    )
    movie_file, subtitle = await auto.run("Avatar")

asyncio.run(main())

TV Series download

from movie_box.v1.cli import Downloader
import asyncio

async def main():
    d = Downloader()
    episodes = await d.download_tv_series(
        "Merlin",
        season=1,
        episode=1,
        limit=3,
    )
    print(episodes)

asyncio.run(main())

Search API

Search movies

import asyncio
from movie_box.v1.core import Session, Search

async def main():
    async with Session() as session:
        search = Search(session, query="avatar")
        results = await search.get_content_model()
        for item in results.items:
            print(item.title, item.page_url)

asyncio.run(main())

Pagination

async with Session() as session:
    search = Search(session, query="avatar")
    page1 = await search.get_content_model()

    if page1.pager.hasMore:
        search2 = search.next_page(page1)
        page2 = await search2.get_content_model()

Movie details

from movie_box.v1.core import Session, Search, MovieDetails

async with Session() as session:
    search = Search(session, query="inception")
    results = await search.get_content_model()
    target = results.items[0]

    details = MovieDetails(session, target)
    info = await details.get_content_model()
    print(info.title, info.imdb_rating)

Progress Hooks

import asyncio
from movie_box.v1 import DownloadTracker, MovieAuto

async def on_progress(progress: DownloadTracker):
    pct = (progress.downloaded_size / progress.expected_size) * 100
    print(f"\r[{pct:5.1f}%] {progress.saved_to.name}", end="", flush=True)

async def main():
    auto = MovieAuto(tasks=5)   # 5 parallel download tasks
    await auto.run("Avatar", progress_hook=on_progress)
    print()

asyncio.run(main())

Saved Defaults

Use movie-box config to persist defaults so you don't have to pass flags every time. Settings are read by all friendly CLI commands and the interactive shell.

movie-box config set quality 720P
movie-box config set language English Hindi   # multiple values
movie-box config set dir ~/Movies
movie-box config set dub "Original Audio"
movie-box config set caption_dir ~/Subs

movie-box config show    # print current config as JSON
movie-box config get quality
movie-box config reset   # delete saved config

Available keys

Key	Description	Example
`quality`	Default video quality	`720P`
`language`	Default subtitle language(s)	`English Hindi`
`dir`	Default download directory	`~/Movies`
`caption_dir`	Default subtitle save directory	`~/Subs`
`dub`	Default dub language	`Original Audio`

Config file location

Platform	Default Path
Windows	`%APPDATA%\movie-box\config.json`
macOS / Linux	`~/.config/movie-box/config.json`

Environment Variables

Variable	Used by	Description
`MOVIEBOX_API_HOST`	v1	Override the v1 API / mirror host
`MOVIEBOX_API_HOST_V2`	v2	Override the v2 API / mirror host
`MOVIEBOX_CONFIG_PATH`	friendly CLI	Full path to the config JSON file
`MOVIEBOX_CONFIG_HOME`	friendly CLI	Directory containing `config.json`
`DEBUG=1`	all	Enable full stack traces on errors

# Override API host (v1)
export MOVIEBOX_API_HOST=https://h5.aoneroom.com

# Store config in a custom location
export MOVIEBOX_CONFIG_PATH=~/.dotfiles/moviebox.json

# Enable debug output
DEBUG=1 movie-box movie "Avatar"

Filename Templates

Customize output filenames using -M (movie), -L (episode), and -C (caption) flags.

Default templates

Movie file:      {title} ({release_year}).{ext}
Movie caption:   {title} ({release_year}).{lan}.{ext}
Episode file:    {title} S{season}E{episode}.{ext}
Episode caption: {title} S{season}E{episode}.{lan}.{ext}

Available placeholders

Placeholder	Description	Scope
`{title}`	Title of the movie or series	all
`{release_year}`	Release year	all
`{release_date}`	Full release date	all
`{resolution}`	Video resolution e.g. `1080p`	video
`{ext}`	File extension	all
`{size_string}`	Human-readable file size	all
`{season}`	Season number	series
`{episode}`	Episode number	series
`{episode_title}`	Episode title	series
`{duration}`	Media duration	video
`{codec_name}`	Video codec name	video
`{lan}`	Caption language code e.g. `en`	caption
`{lan_name}`	Caption language full name	caption
`{delay}`	Caption sync delay value	caption

Custom template examples

moviebox-v3 download-movie "Avatar" -M "{title}.{resolution}.{ext}"
moviebox-v3 download-series "Merlin" -L "{title}.S{season}E{episode}.{resolution}.{ext}"
moviebox-v3 download-movie "Avatar" -C "{title}.{release_year}.{lan_name}.{ext}"

Environment Check (doctor)

Run movie-box doctor to verify your installation before reporting issues.

movie-box doctor

Checks and prints: movie-box version, Python version, required packages (httpx, pydantic, click, etc.), module availability (v1/v2/v3), and media player paths (MPV, VLC).

Mirror Hosts

h5.aoneroom.com has multiple mirror hosts. Use these commands to discover and select one:

# List mirrors
moviebox-v1 mirror-hosts
moviebox-v2 mirror-hosts

# Set mirror via environment variable
export MOVIEBOX_API_HOST=https://h5.aoneroom.com   # v1
export MOVIEBOX_API_HOST_V2=https://mirror.example.com  # v2

v1 / v2 / v3 Comparison

Feature	v1	v2	v3
Subtitle/caption support	✓	✓	✓
Dub language (`-u`)	✗	✗	✓
Anime / music / education	✗	✓	✓
Subject type `unknown`	✗	✗	✓
`--limit -1` (unlimited)	✗	✗	✓
`popular-search` command	✓	✗	✗
`mirror-hosts` command	✓	✓	✗
Season / episode defaults	required	required	`1` / `1`
Env prefix	`MOVIEBOX_`	`MOVIEBOX_`	`MOVIEBOX_V3_`
API host env var	`MOVIEBOX_API_HOST`	`MOVIEBOX_API_HOST_V2`	not needed