Metadata-Version: 2.4
Name: movie-box-dl
Version: 1.0.0
Summary: movie-box by parthmax: an educational Python CLI movie downloader and API client with subtitle support
Project-URL: homepage, https://github.com/parthmax2/movie-box
Project-URL: repository, https://github.com/parthmax2/movie-box
Project-URL: documentation, https://github.com/parthmax2/movie-box
Project-URL: issues, https://github.com/parthmax2/movie-box/issues
Project-URL: source, https://github.com/parthmax2/movie-box
Author-email: smartwa <smartwacaleb@gmail.com>
License-Expression: Unlicense
License-File: LICENSE
Keywords: asyncio,best movie downloader,cli,cli movie downloader,downloader,httpx,media-downloader,movie downloader,movie-box,moviebox,parthmax,parthmax2,pydantic,python-cli,saksham pathak,subtitle-downloader
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: File Sharing
Classifier: Topic :: Internet
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: bs4>=0.0.2
Requires-Dist: httpx[socks]>=0.28.1
Requires-Dist: pydantic>=2.11.7
Requires-Dist: throttlebuster>=0.1.12
Provides-Extra: cli
Requires-Dist: click>=8.2.1; extra == 'cli'
Requires-Dist: prompt-toolkit>=3.0.43; extra == 'cli'
Requires-Dist: pyfiglet>=1.0.2; extra == 'cli'
Requires-Dist: rich>=13.7.1; extra == 'cli'
Requires-Dist: textual>=0.89.1; extra == 'cli'
Description-Content-Type: text/markdown

<div align="center">

# movie-box

**movie-box by parthmax: CLI movie downloader and Python API**  
Search, inspect, download, stream, and manage subtitles from one Python tool.

[![PyPI version](https://badge.fury.io/py/movie-box.svg)](https://pypi.org/project/movie-box)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/movie-box)](https://pypi.org/project/movie-box)
![Coverage](https://raw.githubusercontent.com/parthmax2/movie-box/refs/heads/main/assets/coverage.svg)
[![PyPI - License](https://img.shields.io/pypi/l/movie-box)](https://pypi.org/project/movie-box)
[![Downloads](https://pepy.tech/badge/movie-box)](https://pepy.tech/project/movie-box)
[![CI](https://github.com/parthmax2/movie-box/actions/workflows/ci.yml/badge.svg)](https://github.com/parthmax2/movie-box/actions/workflows/ci.yml)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[Install](#installation) | [Quick Start](#quick-start) | [CLI](#usage) | [Python API](#python-api) | [Disclaimer](#disclaimer) | [Docs](https://moviebox.parthmax.in)

![movie-box CLI](assets/cli.png)


</div>


## Why movie-box?

`movie-box` is built for people who want a scriptable downloader with a clean
CLI, async Python API, subtitle handling, resumable downloads, and media-player
streaming support. It is easy to try from the terminal and easy to automate
from Python.

Created and maintained by **Saksham Pathak**, also known as **parthmax** , this project focuses on being a polished educational Python
movie downloader CLI and API client.

```sh
pip install "movie-box[cli]"
movie-box doctor
movie-box                        # launches the interactive UI
movie-box search "Avatar" --select
moviebox v3 download-movie "Avatar" --yes
```

## 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 5x faster than standard downloads
* **Async & Sync Support** : Fully asynchronous with synchronous fallback
* **Search & Discovery** : Find movies, trending content, and popular searches
* **Cyberpunk CLI UI** : Rich neon startup splash, PromptToolkit command shell, and optional Textual app
* **Developer-Friendly** : Python API with Pydantic models
* **Environment Checks** : Run `movie-box doctor` to verify Python, dependencies, and media players

## Installation

### CLI (for end users)

```sh
pip install 'movie-box[cli]'
```

### Base package (for developers)

```sh
pip install movie-box
```

### Termux (Android)

```sh
pip install movie-box --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](https://mpv.io/installation) or [VLC](https://www.videolan.org):

<details>
<summary>Linux</summary>

```sh
# Ubuntu/Debian
sudo apt install mpv

# Fedora/RHEL
sudo dnf install mpv

# Arch Linux
sudo pacman -S mpv
```
</details>

<details>
<summary>macOS</summary>

```sh
brew install mpv
```
</details>

<details>
<summary>Windows</summary>

Download from [mpv.io/installation](https://mpv.io/installation/).
</details>

## Quick Start

### Command Line

```sh
# Check setup
movie-box doctor

# Launch the interactive cyberpunk shell (both commands are identical)
movie-box
moviebox

# Launch without the startup animation
movie-box ui --no-animation

# Open the full-screen Textual dashboard
movie-box app

# Search with a colorful table and optional selection prompt
movie-box search "Avatar" --select

# Download a movie
movie-box movie "Avatar"

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

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

# Stream with specific audio dub
movie-box series "Money Heist" --dub "English" --stream-via vlc
```

### Python API

```python
from movie_box.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())
```

## Disclaimer

`movie-box` is provided for educational purposes only. Use it only with content
you are legally allowed to access, stream, inspect, or download. The project does
not host media files, does not bypass access controls, and is not affiliated with
or endorsed by MovieBox or any related provider. See [DISCLAIMER.md](DISCLAIMER.md).

## [Usage](https://moviebox.parthmax.in)

This is just a brief usage information. For more details visit official docs - [https://moviebox.parthmax.in](https://moviebox.parthmax.in)

<details open>
<summary><h3>Command Line Interface</h3></summary>

```sh
moviebox v2 --help
```

| Command | Description |
|-|-|
| `movie-box` / `moviebox` | Launch the interactive cyberpunk shell (no subcommand needed) |
| `movie-box search` | Search with colored results and optional numbered selection |
| `movie-box movie` | Search, select, download, or stream a movie |
| `movie-box series` | Search, select, download, or stream TV series episodes |
| `movie-box config` | Save defaults such as quality, language, and download directory |
| `movie-box ui` | Open the animated cyberpunk interactive shell (alias for the above) |
| `movie-box app` | Open the full-screen Textual dashboard |
| `movie-box doctor` | Check Python, dependencies, package imports, and media players |
| `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 |

#### Friendly CLI

The top-level commands use v3 internally and add a cleaner search table,
numbered selection, previews, a cyberpunk startup surface, and saved defaults:

```sh
# Open the interactive shell — typing movie-box or moviebox alone is enough
movie-box
moviebox

# You can also use the explicit subcommand; it is identical
movie-box ui

# Open instantly without the startup animation
movie-box ui --no-animation

# Open the full-screen Textual app
movie-box app

# Search only
movie-box search "Avatar"

# Search and choose from a colored numbered list
movie-box search "Avatar" --select

# Preview the selected movie without downloading
movie-box movie "Avatar" --dry-run

# Download after selecting from search results
movie-box movie "Avatar" -q 1080P -x English

# Download one TV episode
movie-box series "Merlin" -s 1 -e 1

# Save defaults
movie-box config set quality 720P
movie-box config set language English Hindi
movie-box config set dir D:\Movies
movie-box config show
```

Config is stored in your user config directory. Set `MOVIEBOX_CONFIG_PATH` or
`MOVIEBOX_CONFIG_HOME` if you want to choose a custom location.

#### CLI Architecture

The premium terminal interface is split into reusable modules:

| Module | Purpose |
|-|-|
| `movie_box.tui.theme` | Central neon cyberpunk color system |
| `movie_box.tui.art` | Startup banner, ASCII typography, pyfiglet fallback, command deck |
| `movie_box.tui.splash` | Async Rich startup animation and glow simulation |
| `movie_box.tui.command_engine` | Slash-command registry and parser |
| `movie_box.tui.textual_app` | Optional full-screen Textual dashboard |

The CLI extra installs `Rich`, `PromptToolkit`, `pyfiglet`, and `Textual` so the
terminal experience can scale from normal command output to an interactive app.



#### Downloading Movies

**Basic usage:**
```sh
moviebox v2 download-movie "Avatar"
moviebox-v3 download-movie "avengers endgame" 
```

**Common options:**
```sh
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:**
```sh
moviebox v2 download-series "Game of Thrones" -s 1 -e 1
moviebox-v3 download-series "A Knight of the Seven Kingdoms"
```

**Multiple episodes:**
```sh
# 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):

```sh
# 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 `movie-box[cli]` installation and MPV or VLC installed on the system. Temporary files are cleaned up automatically.

### Command Shortcuts

```sh
# Full form
python -m movie_box v2 download-movie "Avatar"

# Short forms
movie-box v2 download-movie "Avatar"
moviebox-v2 download-movie "Avatar"
moviebox-v1 download-movie "Avatar"
```

### Episode Organization

**Group format** - episodes organized into season subfolders:

```sh
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:

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

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

</details>

<details>
<summary><h3>Python API</h3></summary>

#### Simple Auto-Download

```python
from movie_box.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

```python
from movie_box.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

```python
from movie_box.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

```python
from movie_box.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

```python
from movie_box.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](./docs/v1/examples/)
- [v2 Examples](./docs/v2/examples/)

</details>

## Mirror Hosts

h5.aoneroom.com has ~~[multiple mirror hosts](https://github.com/parthmax2/movie-box/issues/27)~~. To use a specific mirror:

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

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

Discover available mirrors:

```sh
moviebox v1 mirror-hosts
```

## Alternatives

1. Movies - [fzmovies-api](https://github.com/parthmax2/fzmovies-api)
2. TV-Series - [fzseries-api](https://github.com/parthmax2/fzseries-api)

## Maintainer

This project is maintained by **Saksham Pathak**, also known as
**parthmax** / **parthmax2** on GitHub.

## Contributors

<div align="center">

<a href="https://github.com/parthmax2/movie-box/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=parthmax2/movie-box" />
</a>

</div>


<h2 align="center"> Disclaimer </h2>

`movie-box` is for educational purposes only. Use it only where you have the
legal right to access or download content. The project does not host media files
and is not affiliated with MovieBox or any related provider.

<div align=center>

**Long live Moviebox spirit.**
</div>

<div align="center">Made with ❤️ </div>
