{"id":30839122,"url":"https://github.com/simatwa/moviebox-api","last_synced_at":"2026-06-06T03:04:26.270Z","repository":{"id":307146416,"uuid":"1018899535","full_name":"Simatwa/moviebox-api","owner":"Simatwa","description":"Unofficial wrapper for moviebox.ph - download movies, tv series and their subtitles.","archived":false,"fork":false,"pushed_at":"2025-09-03T01:03:09.000Z","size":1020,"stargazers_count":9,"open_issues_count":8,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-03T02:31:58.681Z","etag":null,"topics":["moviebox","movies","tv-series"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Simatwa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-13T09:49:27.000Z","updated_at":"2025-09-03T00:59:45.000Z","dependencies_parsed_at":"2025-08-25T08:22:23.229Z","dependency_job_id":null,"html_url":"https://github.com/Simatwa/moviebox-api","commit_stats":null,"previous_names":["simatwa/moviebox-api"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/Simatwa/moviebox-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Simatwa%2Fmoviebox-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Simatwa%2Fmoviebox-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Simatwa%2Fmoviebox-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Simatwa%2Fmoviebox-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Simatwa","download_url":"https://codeload.github.com/Simatwa/moviebox-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Simatwa%2Fmoviebox-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273948884,"owners_count":25196400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-06T02:00:13.247Z","response_time":2576,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["moviebox","movies","tv-series"],"created_at":"2025-09-06T18:55:11.185Z","updated_at":"2026-06-06T03:04:26.265Z","avatar_url":"https://github.com/Simatwa.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# moviebox-api\n\n**Unofficial Python wrapper for Moviebox websites and Android app**  \nSearch, discover, download, and stream movies \u0026 TV series with subtitles\n\n[![PyPI version](https://badge.fury.io/py/moviebox-api.svg)](https://pypi.org/project/moviebox-api)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/moviebox-api)](https://pypi.org/project/moviebox-api)\n![Coverage](https://raw.githubusercontent.com/Simatwa/moviebox-api/refs/heads/main/assets/coverage.svg)\n[![PyPI - License](https://img.shields.io/pypi/l/moviebox-api)](https://pypi.org/project/moviebox-api)\n[![Downloads](https://pepy.tech/badge/moviebox-api)](https://pepy.tech/project/moviebox-api)\n[![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)\n\n[Features](#features) • [Installation](#installation) • [Quick Start](#quick-start) • [Usage](#usage) • [Documentation](https://moviebox-api-docs.netlify.app/)\n\n\u003c/div\u003e\n\n## Features\n\n* **Multi-Version Support** : Access multiple API versions (`v1`, `v2`, `v3`) for different provider services\n* **Download Movies \u0026 TV Series** : High-quality downloads with multiple resolution options\n* **Subtitle Support** : Download subtitles in multiple languages\n* **Direct Streaming** : Stream via MPV or VLC without downloading (CLI only)\n* **Faster Downloads** : Up to 5× faster than standard downloads\n* **Async \u0026 Sync Support** : Fully asynchronous with synchronous fallback\n* **Search \u0026 Discovery** : Find movies, trending content, and popular searches\n* **Developer-Friendly** : Python API with Pydantic models\n\n## Installation\n\n### CLI (for end users)\n\n```sh\nuv tool install 'moviebox-api[cli]'\n```\n\n### Base package (for developers)\n\n```sh\nuv add moviebox-api\n```\n\n### Termux (Android)\n\n```sh\npip install moviebox-api --no-deps\npip install 'pydantic==2.9.2'\npip install rich click bs4 httpx throttlebuster\n```\n\n### Media Players (optional, required for streaming)\n\nTo stream content directly without downloading, install [MPV](https://mpv.io/installation) or [VLC](https://www.videolan.org):\n\n\u003cdetails\u003e\n\u003csummary\u003eLinux\u003c/summary\u003e\n\n```sh\n# Ubuntu/Debian\nsudo apt install mpv\n\n# Fedora/RHEL\nsudo dnf install mpv\n\n# Arch Linux\nsudo pacman -S mpv\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003emacOS\u003c/summary\u003e\n\n```sh\nbrew install mpv\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eWindows\u003c/summary\u003e\n\nDownload from [mpv.io/installation](https://mpv.io/installation/).\n\u003c/details\u003e\n\n## Quick Start\n\n### Command Line\n\n```sh\n# Download a movie\nmoviebox v2 download-movie \"Avatar\"\n\n# Download a TV series episode\nmoviebox v2 download-series \"Game of Thrones\" -s 1 -e 1\n\n# Stream a movie (requires MPV)\nmoviebox v2 download-movie \"Avatar\" --stream-via mpv\n\n# Stream with specific audio dub\nmoviebox v3 download-series \"Money Heist\" --dub \"English\" -X vlc\n```\n\n### Python API\n\n```python\nfrom moviebox_api.v1 import MovieAuto\nimport asyncio\n\nasync def main():\n    auto = MovieAuto()\n    movie_file, subtitle_file = await auto.run(\"Avatar\")\n    print(f\"Movie: {movie_file.saved_to}\")\n    print(f\"Subtitle: {subtitle_file.saved_to}\")\n\nasyncio.run(main())\n```\n\n## [Usage](https://moviebox-api-docs.netlify.app/)\n\nThis is just a brief usage information. For more details visit official docs - [https://moviebox-api-docs.netlify.app/](https://moviebox-api-docs.netlify.app/)\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003ch3\u003eCommand Line Interface\u003c/h3\u003e\u003c/summary\u003e\n\n```sh\nmoviebox v2 --help\n```\n\n| Command | Description |\n|-|-|\n| `download-movie` | Search, download, or stream movies, anime, music, and educational content |\n| `download-series` | Search and download or stream TV series |\n| `homepage-content` | Show contents displayed on the landing page |\n| `item-details` | Show details of a particular movie or TV series |\n| `mirror-hosts` | Discover available Moviebox mirror hosts |\n\n\n\n#### Downloading Movies\n\n**Basic usage:**\n```sh\nmoviebox v2 download-movie \"Avatar\"\nmoviebox-v3 download-movie \"avengers endgame\" \n```\n\n**Common options:**\n```sh\nmoviebox v2 download-movie \"Avatar\" --quality 1080p\nmoviebox v2 download-movie \"Avatar\" --year 2009\nmoviebox v2 download-movie \"Avatar\" --dir ~/Movies\nmoviebox v2 download-movie \"Avatar\" --no-caption\nmoviebox v2 download-movie \"Avatar\" --yes\n```\n\n| Option | Description |\n|-|-|\n| `-y, --year` | Filter by release year |\n| `-q, --quality` | Video quality: `best`, `1080p`, `720p`, `480p`, `360p`, `worst` |\n| `-d, --dir` | Download directory |\n| `-x, --language` | Subtitle language (default: English) |\n| `--no-caption` | Skip subtitle download |\n| `-Y, --yes` | Auto-confirm without prompts |\n\n#### Downloading TV Series\n\n**Basic usage:**\n```sh\nmoviebox v2 download-series \"Game of Thrones\" -s 1 -e 1\nmoviebox-v3 download-series \"A Knight of the Seven Kingdoms\"\n```\n\n**Multiple episodes:**\n```sh\n# Download 5 episodes starting from S01E01\nmoviebox v2 download-series \"Game of Thrones\" -s 1 -e 1 -l 5\n\n# Download entire season\nmoviebox v2 download-series \"Game of Thrones\" -s 1 -e 1 -l 100\n\n# Download all remaining seasons\nmoviebox v2 download-series \"Merlin\" -s 1 -e 1 --auto-mode\n```\n\n| Option | Description |\n|-|-|\n| `-s, --season` | Season number (required) |\n| `-e, --episode` | Starting episode number (required) |\n| `-l, --limit` | Number of episodes to download (default: 1) |\n| `-q, --quality` | Video quality |\n| `-x, --language` | Subtitle language |\n| `--no-caption` | Skip subtitles |\n| `-Y, --yes` | Auto-confirm |\n| `-A, --auto-mode` | Download all remaining seasons when `--limit` is 1 |\n\n#### Streaming via Media Players\n\nStream content directly without downloading (requires MPV or VLC):\n\n```sh\n# Stream a movie\nmoviebox v2 download-movie \"Avatar\" --stream-via vlc\n\n# Stream with subtitles in a specific language\nmoviebox v2 download-movie \"Avatar\" --stream-via mpv --language French\n\n# Stream a series episode\nmoviebox v2 download-series \"Game of Thrones\" -s 1 -e 1 --stream-via vlc\n\n# Stream with specific quality\nmoviebox v2 download-series \"Breaking Bad\" -s 1 -e 1 --stream-via vlc --quality 1080p\n```\n\nStreaming requires the `moviebox-api[cli]` installation and MPV or VLC installed on the system. Temporary files are cleaned up automatically.\n\n### Command Shortcuts\n\n```sh\n# Full form\npython -m moviebox_api v2 download-movie \"Avatar\"\n\n# Short forms\nmovebox v2 download-movie \"Avatar\"\nmovebox-v2 download-movie \"Avatar\"\nmovebox-v1 download-movie \"Avatar\"\n```\n\n### Episode Organization\n\n**Group format** - episodes organized into season subfolders:\n\n```sh\nmoviebox v2 download-series Merlin -s 1 -e 1 --auto-mode --format group\n```\n\n```\nMerlin (2009)/\n  S1/\n    Merlin S1E1.mp4\n    Merlin S1E2.mp4\n  S2/\n    Merlin S2E1.mp4\n```\n\n**Struct format** - hierarchical directory structure using episode numbers as filenames:\n\n```sh\nmoviebox v2 download-series Merlin -s 1 -e 1 --auto-mode --format struct\n```\n\n```\nMerlin (2009)/\n  S1/\n    E1.mp4\n    E2.mp4\n  S2/\n    E1.mp4\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ch3\u003ePython API\u003c/h3\u003e\u003c/summary\u003e\n\n#### Simple Auto-Download\n\n```python\nfrom moviebox_api.v1 import MovieAuto\nimport asyncio\n\nasync def main():\n    auto = MovieAuto()\n    movie_file, subtitle_file = await auto.run(\"Avatar\")\n    print(f\"Movie saved to: {movie_file.saved_to}\")\n    print(f\"Subtitle saved to: {subtitle_file.saved_to}\")\n\nasyncio.run(main())\n```\n\n#### Download with Progress Tracking\n\n```python\nfrom moviebox_api.v1 import DownloadTracker, MovieAuto\nimport asyncio\n\nasync def progress_callback(progress: DownloadTracker):\n    percent = (progress.downloaded_size / progress.expected_size) * 100\n    print(f\"[{percent:.2f}%] Downloading {progress.saved_to.name}\", end=\"\\r\")\n\nasync def main():\n    auto = MovieAuto(tasks=1)\n    await auto.run(\"Avatar\", progress_hook=progress_callback)\n\nasyncio.run(main())\n```\n\n#### Download with Manual Confirmation\n\n```python\nfrom moviebox_api.v1.cli import Downloader\nimport asyncio\n\nasync def main():\n    downloader = Downloader()\n    movie_file, subtitle_files = await downloader.download_movie(\"Avatar\")\n    print(f\"Downloaded: {movie_file}\")\n    print(f\"Subtitles: {subtitle_files}\")\n\nasyncio.run(main())\n```\n\n#### Download TV Series Episodes\n\n```python\nfrom moviebox_api.v1.cli import Downloader\nimport asyncio\n\nasync def main():\n    downloader = Downloader()\n    episodes_map = await downloader.download_tv_series(\n        \"Merlin\",\n        season=1,\n        episode=1,\n        limit=2,\n        # auto_mode=True  # Download entire remaining seasons when limit=1\n    )\n    print(f\"Downloaded episodes: {episodes_map}\")\n\nasyncio.run(main())\n```\n\n#### Custom Configuration\n\n```python\nfrom moviebox_api.v1 import MovieAuto\nimport asyncio\n\nasync def main():\n    auto = MovieAuto(\n        caption_language=\"Spanish\",\n        quality=\"720p\",\n        download_dir=\"~/Downloads\"\n    )\n    movie_file, subtitle_file = await auto.run(\"Avatar\")\n\nasyncio.run(main())\n```\n\n#### Further Examples\n\n- [V1 Examples](./docs/v1/examples/)\n- [v2 Examples](./docs/v2/examples/)\n\n\u003c/details\u003e\n\n## Mirror Hosts\n\nh5.aoneroom.com has ~~[multiple mirror hosts](https://github.com/Simatwa/moviebox-api/issues/27)~~. To use a specific mirror:\n\n```sh\n# v1\nexport MOVIEBOX_API_HOST=\"h5.aoneroom.com\"\n\n# v2\nexport MOVIEBOX_API_HOST_V2=\"h5-api.aoneroom.com\"\n```\n\nDiscover available mirrors:\n\n```sh\nmoviebox v1 mirror-hosts\n```\n\n## Alternatives\n\n1. Movies - [fzmovies-api](https://github.com/Simatwa/fzmovies-api)\n2. TV-Series - [fzseries-api](https://github.com/Simatwa/fzseries-api)\n\n## Contributors\n\n\u003cdiv align=\"center\"\u003e\n\n\u003ca href=\"https://github.com/Simatwa/moviebox-api/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=Simatwa/moviebox-api\" /\u003e\n\u003c/a\u003e\n\n\u003c/div\u003e\n\n\n\u003ch2 align=\"center\"\u003e Disclaimer \u003c/h2\u003e\n\n\u003e \"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.\"  \n\u003e - *moviebox.ph*\n\n\u003cdiv align=center\u003e\n\n**Long live Moviebox spirit.**\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003eMade with ❤️ \u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimatwa%2Fmoviebox-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimatwa%2Fmoviebox-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimatwa%2Fmoviebox-api/lists"}