moviebox-api 0.4.0

Unofficial wrapper for moviebox.ph - search, discover and download movies, tv-series and their subtitles.

moviebox-api

Unofficial Python wrapper for moviebox.ph
Search, discover, download, and stream movies & TV series with subtitles

Features • Installation • Quick Start • Usage • Documentation

Features

• Download Movies & TV Series : High-quality downloads with multiple resolution options
• Subtitle Support : Download subtitles in multiple languages
• Direct Streaming : Stream via MPV or VLC without downloading (CLI only)
• Faster Downloads : Over 5x faster than standard downloads
• Async & Sync Support : Fully asynchronous with synchronous fallback
• Search & Discovery : Find movies, trending content, and popular searches
• Developer-Friendly : Python API with Pydantic models

Installation

CLI (for end users)

pip install "moviebox-api[cli]"

Base package (for developers)

pip install "moviebox-api"

Media Players (optional, required for streaming)

To stream content directly without downloading, install MPV or VLC:

Linux

# Ubuntu/Debian
sudo apt install mpv

# Fedora/RHEL
sudo dnf install mpv

# Arch Linux
sudo pacman -S mpv

macOS

brew install mpv

Windows

Download from mpv.io/installation.

Termux (Android)

pip install moviebox-api --no-deps
pip install 'pydantic==2.9.2'
pip install rich click bs4 httpx throttlebuster

Quick Start

Command Line

# Download a movie
moviebox v2 download-movie "Avatar"

# Download a TV series episode
moviebox v2 download-series "Game of Thrones" -s 1 -e 1

# Stream a movie (requires MPV)
moviebox v2 download-movie "Avatar" --stream-via mpv

Python API

from moviebox_api.v1 import MovieAuto
import asyncio

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())

Usage

Command Line Interface

moviebox v2 --help

| Command | Description | ||| | download-movie | Search, download, or stream movies, anime, music, and educational content | | download-series | Search and download or stream TV series | | homepage-content | Show contents displayed on the landing page | | item-details | Show details of a particular movie or TV series | | mirror-hosts | Discover available Moviebox mirror hosts |

Downloading Movies

Basic usage:

moviebox v2 download-movie "Avatar"

Common options:

moviebox v2 download-movie "Avatar" --quality 1080p
moviebox v2 download-movie "Avatar" --year 2009
moviebox v2 download-movie "Avatar" --dir ~/Movies
moviebox v2 download-movie "Avatar" --no-caption
moviebox v2 download-movie "Avatar" --yes

| Option | Description | ||| | -y, --year | Filter by release year | | -q, --quality | Video quality: best, 1080p, 720p, 480p, 360p, worst | | -d, --dir | Download directory | | -x, --language | Subtitle language (default: English) | | --no-caption | Skip subtitle download | | -Y, --yes | Auto-confirm without prompts |

All options

Usage: python -m moviebox_api v2 download-movie [OPTIONS] TITLE

  Search, download or stream items under movie/anime/music/education subject-types.

Options:
  -s, --subject-type [movies|education|music|anime]
                                  Subject type filter  [default: MOVIES]
  -y, --year INTEGER              Year filter  [default: 0]
  -q, --quality [worst|best|360p|480p|720p|1080p]
                                  Media quality  [default: BEST]
  -d, --dir DIRECTORY             Download directory
  -D, --caption-dir DIRECTORY     Caption download directory
  -m, --mode [start|resume|auto]  Download mode  [default: auto]
  -x, --language TEXT             Caption language  [default: English]
  -M, --movie-filename-tmpl TEXT  Movie filename template  [default: {title} ({release_year}).{ext}]
  -C, --caption-filename-tmpl TEXT
                                  Caption filename template  [default: {title} ({release_year}).{lan}.{ext}]
  -t, --tasks INTEGER RANGE       Parallel download tasks  [default: 5; 1<=x<=1000]
  -P, --part-dir DIRECTORY        Temporary parts directory
  -E, --part-extension TEXT       Part file extension  [default: .part]
  -N, --chunk-size INTEGER        Chunk size in kilobytes  [default: 256]
  -R, --timeout-retry-attempts INTEGER
                                  Retry attempts on timeout  [default: 10]
  -B, --merge-buffer-size INTEGER RANGE
                                  Merge buffer size in kilobytes  [1<=x<=102400]
  -X, --stream-via [mpv|vlc]      Stream via media player instead of downloading
  -c, --colour TEXT               Progress bar colour  [default: cyan]
  -U, --ascii                     Use unicode blocks for progress bar
  -z, --disable-progress-bar      Hide progress bar
  -I, --ignore-missing-caption    Continue download when caption is missing
  --leave / --no-leave            Keep progress bar leaves  [default: no-leave]
  --caption / --no-caption        Download caption  [default: caption]
  -O, --caption-only              Download caption only
  -S, --simple                    Show percentage and bar only
  -T, --test                      Test download without saving
  -V, --verbose                   Show detailed output
  -Q, --quiet                     Suppress interactive output
  -Y, --yes                       Skip confirmation prompt
  -h, --help                      Show this message and exit.

Downloading TV Series

Basic usage:

moviebox v2 download-series "Game of Thrones" -s 1 -e 1

Multiple episodes:

# Download 5 episodes starting from S01E01
moviebox v2 download-series "Game of Thrones" -s 1 -e 1 -l 5

# Download entire season
moviebox v2 download-series "Game of Thrones" -s 1 -e 1 -l 100

# Download all remaining seasons
moviebox v2 download-series "Merlin" -s 1 -e 1 --auto-mode

| Option | Description | ||| | -s, --season | Season number (required) | | -e, --episode | Starting episode number (required) | | -l, --limit | Number of episodes to download (default: 1) | | -q, --quality | Video quality | | -x, --language | Subtitle language | | --no-caption | Skip subtitles | | -Y, --yes | Auto-confirm | | -A, --auto-mode | Download all remaining seasons when --limit is 1 |

All options

Usage: python -m moviebox_api v2 download-series [OPTIONS] TITLE

  Search and download or stream tv series.

Options:
  -y, --year INTEGER              Year filter  [default: 0]
  -s, --season INTEGER RANGE      Season number  [1<=x<=1000; required]
  -e, --episode INTEGER RANGE     Starting episode  [1<=x<=1000; required]
  -l, --limit INTEGER RANGE       Episodes to download  [default: 1; 1<=x<=1000]
  -q, --quality [worst|best|360p|480p|720p|1080p]
                                  Media quality  [default: BEST]
  -x, --language TEXT             Caption language  [default: English]
  -d, --dir DIRECTORY             Download directory
  -D, --caption-dir DIRECTORY     Caption download directory
  -m, --mode [start|resume|auto]  Download mode  [default: auto]
  -L, --episode-filename-tmpl TEXT
                                  Episode filename template  [default: {title} S{season}E{episode}.{ext}]
  -C, --caption-filename-tmpl TEXT
                                  Caption filename template  [default: {title} S{season}E{episode}.{lan}.{ext}]
  -t, --tasks INTEGER RANGE       Parallel download tasks  [default: 5; 1<=x<=1000]
  -P, --part-dir DIRECTORY        Temporary parts directory
  -f, --format [standard|group|struct]
                                  Episode organization format
  -E, --part-extension TEXT       Part file extension  [default: .part]
  -N, --chunk-size INTEGER        Chunk size in kilobytes  [default: 256]
  -R, --timeout-retry-attempts INTEGER
                                  Retry attempts on timeout  [default: 10]
  -B, --merge-buffer-size INTEGER RANGE
                                  Merge buffer size in kilobytes  [1<=x<=102400]
  -X, --stream-via [mpv|vlc]      Stream via media player instead of downloading
  -c, --colour TEXT               Progress bar colour  [default: cyan]
  -U, --ascii                     Use unicode blocks for progress bar
  -z, --disable-progress-bar      Hide progress bar
  -I, --ignore-missing-caption    Continue download when caption is missing
  --leave / --no-leave            Keep progress bar leaves  [default: no-leave]
  --caption / --no-caption        Download caption  [default: caption]
  -O, --caption-only              Download caption only
  -A, --auto-mode                 Download all remaining seasons when limit=1
  -S, --simple                    Show percentage and bar only
  -T, --test                      Test download without saving
  -V, --verbose                   Show detailed output
  -Q, --quiet                     Suppress interactive output
  -Y, --yes                       Skip confirmation prompt
  -h, --help                      Show this message and exit.

Streaming via Media Players

Stream content directly without downloading (requires MPV or VLC):

# Stream a movie
moviebox v2 download-movie "Avatar" --stream-via vlc

# Stream with subtitles in a specific language
moviebox v2 download-movie "Avatar" --stream-via mpv --language French

# Stream a series episode
moviebox v2 download-series "Game of Thrones" -s 1 -e 1 --stream-via vlc

# Stream with specific quality
moviebox v2 download-series "Breaking Bad" -s 1 -e 1 --stream-via vlc --quality 1080p

Streaming requires the moviebox-api[cli] installation and MPV or VLC installed on the system. Temporary files are cleaned up automatically.

Python API

Simple Auto-Download

from moviebox_api.v1 import MovieAuto
import asyncio

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

asyncio.run(main())

Download with Progress Tracking

from moviebox_api.v1 import DownloadTracker, MovieAuto
import asyncio

async def progress_callback(progress: DownloadTracker):
    percent = (progress.downloaded_size / progress.expected_size) * 100
    print(f"[{percent:.2f}%] Downloading {progress.saved_to.name}", end="\r")

async def main():
    auto = MovieAuto()
    await auto.run("Avatar", progress_hook=progress_callback)

asyncio.run(main())

Download with Manual Confirmation

from moviebox_api.v1.cli import Downloader
import asyncio

async def main():
    downloader = Downloader()
    movie_file, subtitle_files = await downloader.download_movie("Avatar")
    print(f"Downloaded: {movie_file}")
    print(f"Subtitles: {subtitle_files}")

asyncio.run(main())

Download TV Series Episodes

from moviebox_api.v1.cli import Downloader
import asyncio

async def main():
    downloader = Downloader()
    episodes_map = await downloader.download_tv_series(
        "Merlin",
        season=1,
        episode=1,
        limit=2,
        # auto_mode=True  # Download entire remaining seasons when limit=1
    )
    print(f"Downloaded episodes: {episodes_map}")

asyncio.run(main())

Custom Configuration

from moviebox_api.v1 import MovieAuto
import asyncio

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

asyncio.run(main())

Advanced Configuration

Mirror Hosts

Moviebox.ph has multiple mirror hosts. To use a specific mirror:

# v1
export MOVIEBOX_API_HOST="h5.aoneroom.com"

# v2
export MOVIEBOX_API_HOST_V2="h5-api.aoneroom.com"

Discover available mirrors:

moviebox v1 mirror-hosts

Command Shortcuts

# Full form
python -m moviebox_api v2 download-movie "Avatar"

# Short forms
movebox v2 download-movie "Avatar"
movebox-v2 download-movie "Avatar"
movebox-v1 download-movie "Avatar"

Episode Organization

Group format — episodes organized into season subfolders:

moviebox v2 download-series Merlin -s 1 -e 1 --auto-mode --format group

Merlin (2009)/
  S1/
    Merlin S1E1.mp4
    Merlin S1E2.mp4
  S2/
    Merlin S2E1.mp4

Struct format — hierarchical directory structure using episode numbers as filenames:

moviebox v2 download-series Merlin -s 1 -e 1 --auto-mode --format struct

Merlin (2009)/
  S1/
    E1.mp4
    E2.mp4
  S2/
    E1.mp4

Note: V2 is recommended — it has no geo-restrictions at the time of writing.

Examples

• Download Movie CLI
• Download Series CLI

Contributors

Disclaimer

"All videos and pictures on MovieBox are from the Internet, and their copyrights belong to the original creators. We only provide webpage services and do not store, record, or upload any content."
— moviebox.ph

Made with love