moviebox-api 0.5.4

Unofficial Python wrapper for Moviebox websites and Android app - download movies and tv series with their subtitles

moviebox-api

Unofficial Python wrapper for Moviebox websites and Android app
Search, discover, download, and stream movies & TV series with subtitles

Features • Installation • Quick Start • Usage • Documentation

Features

• Multi-Version Support : Access multiple API versions (v1, v2, v3) for different provider services
• 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 : Up to 5× 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)

uv tool install 'moviebox-api[cli]'

Base package (for developers)

uv add moviebox-api

Termux (Android)

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

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.

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

# Stream with specific audio dub
moviebox v3 download-series "Money Heist" --dub "English" -X vlc

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

This is just a brief usage information. For more details visit official docs - https://moviebox-api-docs.netlify.app/

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"
moviebox-v3 download-movie "avengers endgame" 

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

Downloading TV Series

Basic usage:

moviebox v2 download-series "Game of Thrones" -s 1 -e 1
moviebox-v3 download-series "A Knight of the Seven Kingdoms"

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

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.

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

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(tasks=1)
    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())

Further Examples

• V1 Examples
• v2 Examples

Mirror Hosts

h5.aoneroom.com 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

Alternatives

1. Movies - fzmovies-api
2. TV-Series - fzseries-api

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

Long live Moviebox spirit.

Made with ❤️