### Install moviebox-api from source with CLI extras using uv

Source: https://moviebox-api-docs.netlify.app/installation

Install the moviebox-api package directly from its GitHub repository, including CLI extras, using the uv tool. Requires git to be installed.

```bash
uv pip install git+https://github.com/Simatwa/moviebox-api.git[cli]

```

--------------------------------

### Install moviebox-api with CLI extras using uv

Source: https://moviebox-api-docs.netlify.app/installation

Install the moviebox-api package along with command-line utility dependencies using the uv tool.

```bash
uv pip install "moviebox-api[cli]"

```

--------------------------------

### Install moviebox-api with uv

Source: https://moviebox-api-docs.netlify.app/installation

Use this command to install the moviebox-api package with its required dependencies using the uv tool.

```bash
uv pip install moviebox-api

```

--------------------------------

### Termux Installation for moviebox-api

Source: https://moviebox-api-docs.netlify.app/installation

Install moviebox-api and specific dependencies in a Termux environment. This method installs the package without its dependencies and then manually installs required libraries.

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

```

--------------------------------

### Download Movie: Best Quality, Auto Resume

Source: https://moviebox-api-docs.netlify.app/v1/cli

Example of downloading a movie with the best available quality and automatic resume detection.

```bash
# Download best quality, auto-detect resume
moviebox-v1 download-movie "Inception"
```

--------------------------------

### Output mirror hosts as JSON

Source: https://moviebox-api-docs.netlify.app/v1/cli

Use the -J flag to get a list of discovered mirror hosts in JSON format.

```bash
moviebox-v1 mirror-hosts -J
```

--------------------------------

### Output full details as JSON

Source: https://moviebox-api-docs.netlify.app/v1/cli

Combine the -J and -F flags to get all available details for an item in JSON format.

```bash
moviebox-v1 item-details "Inception" -J -F
```

--------------------------------

### Add moviebox-api from source with CLI extras to project using uv

Source: https://moviebox-api-docs.netlify.app/installation

Add the moviebox-api package from its GitHub repository, including CLI extras, to your project using the uv tool. Requires git to be installed.

```bash
uv add git+https://github.com/Simatwa/moviebox-api.git[cli]

```

--------------------------------

### Get Downloadable Movie Files Detail (Async)

Source: https://moviebox-api-docs.netlify.app/v1/movies

Fetch details for downloadable movie files, including file URLs, sizes, and quality, along with subtitle information. This is done asynchronously.

```python
from moviebox_api.v1 import (
    DownloadableMovieFilesDetail,
    MovieDetails,
    Search,
    Session,
    SubjectType,
)


async def downloadable_movie_file_details():
    client_session = Session()
    search = Search(client_session, "avatar", subject_type=SubjectType.MOVIES)

    search_results = await search.get_content_model()
    target_movie = search_results.first_item

    target_movie_details_instance = MovieDetails(
        target_movie, client_session
    )  # 

    target_movie_details_model = (
        await target_movie_details_instance.get_content_model()
    )

    downloadable_files = DownloadableMovieFilesDetail(
        client_session, target_movie_details_model
    )
    downloadable_files_detail = await downloadable_files.get_content_model()

    print(type(downloadable_files_detail))  # 

    subtitles = downloadable_files_detail.captions

    videos = downloadable_files_detail.downloads


if __name__ == "__main__":
    import asyncio

    asyncio.run(downloadable_movie_file_details())

```

--------------------------------

### Get Downloadable Movie Files Detail (Sync)

Source: https://moviebox-api-docs.netlify.app/v1/movies

Fetch details for downloadable movie files synchronously. This includes file URLs, sizes, quality, and subtitle information.

```python
from moviebox_api.v1 import (
    DownloadableMovieFilesDetail,
    MovieDetails,
    Search,
    Session,
    SubjectType,
)


def downloadable_movie_file_details():
    client_session = Session()
    search = Search(client_session, "avatar", subject_type=SubjectType.MOVIES)

    search_results = search.get_content_model_sync()
    target_movie = search_results.first_item

    target_movie_details_instance = MovieDetails(
        target_movie, client_session
    )  # (1)

    target_movie_details_model = (
        target_movie_details_instance.get_content_model_sync()
    )

    downloadable_files = DownloadableMovieFilesDetail(
        client_session, target_movie_details_model
    )
    downloadable_files_detail = downloadable_files.get_content_model_sync()

    print(type(downloadable_files_detail))  # (2)

    subtitles = downloadable_files_detail.captions

    videos = downloadable_files_detail.downloads


if __name__ == "__main__":
    downloadable_movie_file_details()

```

--------------------------------

### Navigate to Previous Search Results Page Asynchronously

Source: https://moviebox-api-docs.netlify.app/v1/movies

After fetching search results, use this to navigate to the previous page of results asynchronously. This example shows navigating from page 3.

```python
async def search_movie():
    search = Search(Session(), query="avatar" page=3, per_page=5)

    contents:  SearchResultsModel = await search.get_content_model()  # 

    previous_search: Search = search.previous_page(contents)  # 

    previous_contents:  SearchResultsModel = await previous_search.get_content_model()  # 

```

--------------------------------

### Get TV Series Downloadable File Details (Async)

Source: https://moviebox-api-docs.netlify.app/v1/tv_series

Retrieves metadata for downloadable files (videos and subtitles) for a specific TV series episode. Requires an active client session and TV series details.

```python
from moviebox_api.v1 import (
    DownloadableTVSeriesFilesDetail,
    Search,
    Session,
    SubjectType,
    TVSeriesDetails,
)


async def downloadable_tv_series_file_details():
    client_session = Session()
    search = Search(client_session, "Merlin", subject_type=SubjectType.TV_SERIES)
    search_results = await search.get_content_model()
    target_series = search_results.first_item

    target_series_details_instance = TVSeriesDetails(
        target_series, client_session
    )
    target_series_details_model = (
        await target_series_details_instance.get_content_model()
    )

    downloadable_files = DownloadableTVSeriesFilesDetail(
        client_session, target_series_details_model
    )

    downloadable_files_detail = await downloadable_files.get_content_model(
        season=1, episode=1
    )

    print(type(downloadable_files_detail))  # 

    subtitles = downloadable_files_detail.captions

    videos = downloadable_files_detail.downloads


if __name__ == "__main__":
    import asyncio

    asyncio.run(downloadable_tv_series_file_details())

```

--------------------------------

### Get Movie Details Using Page URL (Sync)

Source: https://moviebox-api-docs.netlify.app/v1/movies

Retrieve detailed content model for a movie using its page URL synchronously. Requires an active session.

```python
from moviebox_api.v1 import MovieDetails, Session


def movie_details_using_page_url():
    page_url = "/detail/avatar-WLDIi21IUBa?id=8906247916759695608"  # 

    client_session = Session()

    md = MovieDetails(
        page_url,
        session=client_session,
    )

    details = md.get_content_model_sync()
    print(type(details))  # 


if __name__ == "__main__":
    movie_details_using_page_url()

```

--------------------------------

### Get Movie Details Using Page URL (Async)

Source: https://moviebox-api-docs.netlify.app/v1/movies

Retrieve detailed content model for a movie using its page URL asynchronously. Requires an active session.

```python
from moviebox_api.v1 import MovieDetails, Session


async def movie_details_using_page_url():
    page_url = "/detail/avatar-WLDIi21IUBa?id=8906247916759695608"  # 

    client_session = Session()

    md = MovieDetails(
        page_url,
        session=client_session,
    )

    details = await md.get_content_model()
    print(type(details))  # 


if __name__ == "__main__":
    import asyncio

    asyncio.run(movie_details_using_page_url())

```

--------------------------------

### Get TV Series Details using Item Page URL (Async)

Source: https://moviebox-api-docs.netlify.app/v1/tv_series

Retrieves detailed information for a TV series using its page URL.

```APIDOC
## Get TV Series Details using Item Page URL (Async)

### Description
Retrieves detailed information about a specific TV series by providing its page URL. This method is useful when the URL is already known or cached.

### Method
`TVSeriesDetails.get_content_model()`

### Parameters
- `page_url` (string): The URL of the TV series detail page.
- `session` (Session): The client session object.

### Request Example
```python
from moviebox_api.v1 import (
    Search,
    Session,
    SubjectType,
    TVSeriesDetails,
)


async def tv_series_details_using_item_page_url():

    page_url = "/detail/merlin-sMxCiIO6fZ9?id=8382755684005333552"
    client_session = Session()

    details_inst = TVSeriesDetails(
        page_url,
        session=client_session,
    )

    series_details = await details_inst.get_content_model()
    print(type(series_details))


if __name__ == "__main__":
    tv_series_details_using_item_page_url()
```

### Response
#### Success Response
- `series_details` (ItemJsonDetailsModel): A model containing detailed information about the TV series.

#### Response Example
```
<class 'moviebox_api.v1.extractor.models.json.ItemJsonDetailsModel'>
```
```

--------------------------------

### Get Movie Details (Using Search Result Item - Async)

Source: https://moviebox-api-docs.netlify.app/v1/movies

Fetches detailed information about a movie using an item from search results asynchronously.

```APIDOC
## Get Movie Details (Using Search Result Item - Async)

### Description
Fetches detailed movie information asynchronously by providing a specific item obtained from a previous search.

### Method
`MovieDetails.get_content_model()`

### Parameters
- `item` (dict or SearchResultItem): The search result item for the movie.
- `session` (Session): An active session object.

### Request Example
```python
from moviebox_api.v1 import MovieDetails, Search, Session, SubjectType

async def movie_details_using_search_results_item():
    client_session = Session()
    search = Search(client_session, query="avatar", subject_type=SubjectType.MOVIES)
    search_results = await search.get_content_model()
    target_item = search_results.first_item
    md = MovieDetails(target_item, session=client_session)
    details = await md.get_content_model()
    print(details)

import asyncio
asyncio.run(movie_details_using_search_results_item())
```

### Response
#### Success Response (200)
- `ItemJsonDetailsModel`: A Pydantic model containing detailed movie information.
```

--------------------------------

### Get TV Series Downloadable File Details (Sync)

Source: https://moviebox-api-docs.netlify.app/v1/tv_series

Retrieves metadata for downloadable files (videos and subtitles) for a specific TV series episode synchronously. Requires an active client session and TV series details.

```python
from moviebox_api.v1 import (
    DownloadableTVSeriesFilesDetail,
    Search,
    Session,
    SubjectType,
    TVSeriesDetails,
)


def downloadable_tv_series_file_details():
    client_session = Session()
    search = Search(client_session, "Merlin", subject_type=SubjectType.TV_SERIES)
    search_results = search.get_content_model_sync()
    target_series = search_results.first_item

    target_series_details_instance = TVSeriesDetails(
        target_series, client_session
    )
    target_series_details_model = (
        target_series_details_instance.get_content_model_sync()
    )

    downloadable_files = DownloadableTVSeriesFilesDetail(
        client_session, target_series_details_model
    )

    downloadable_files_detail = downloadable_files.get_content_model_sync(
        season=1, episode=1
    )

    print(type(downloadable_files_detail))  # 

    subtitles = downloadable_files_detail.captions

    videos = downloadable_files_detail.downloads


if __name__ == "__main__":
    downloadable_tv_series_file_details()

```

--------------------------------

### Get Movie Details (Using Search Result Item - Sync)

Source: https://moviebox-api-docs.netlify.app/v1/movies

Fetches detailed information about a movie using an item from search results synchronously.

```APIDOC
## Get Movie Details (Using Search Result Item - Sync)

### Description
Fetches detailed movie information synchronously by providing a specific item obtained from a previous search.

### Method
`MovieDetails.get_content_model_sync()`

### Parameters
- `item` (dict or SearchResultItem): The search result item for the movie.
- `session` (Session): An active session object.

### Request Example
```python
from moviebox_api.v1 import MovieDetails, Search, Session, SubjectType
from moviebox_api.v1.extractor.models.json import ItemJsonDetailsModel
from moviebox_api.v1.models import SearchResultsModel

def movie_details_using_search_results_item():
    client_session = Session()
    search = Search(client_session, query="avatar", subject_type=SubjectType.MOVIES)
    search_results: SearchResultsModel = search.get_content_model_sync()
    target_item = search_results.first_item
    md = MovieDetails(target_item, session=client_session)
    details: ItemJsonDetailsModel = md.get_content_model_sync()
    print(details)

movie_details_using_search_results_item()
```

### Response
#### Success Response (200)
- `ItemJsonDetailsModel`: A Pydantic model containing detailed movie information.
```

--------------------------------

### Get TV Series Details using Item Page URL (Sync)

Source: https://moviebox-api-docs.netlify.app/v1/tv_series

Synchronously retrieves detailed information for a TV series using its page URL.

```APIDOC
## Get TV Series Details using Item Page URL (Sync)

### Description
Synchronously retrieves detailed information about a specific TV series by providing its page URL. This method is useful when the URL is already known or cached.

### Method
`TVSeriesDetails.get_content_model_sync()`

### Parameters
- `page_url` (string): The URL of the TV series detail page.
- `session` (Session): The client session object.

### Request Example
```python
from moviebox_api.v1 import (
    Search,
    Session,
    SubjectType,
    TVSeriesDetails,
)


def tv_series_details_using_item_page_url():

    page_url = "/detail/merlin-sMxCiIO6fZ9?id=8382755684005333552"
    client_session = Session()

    details_inst = TVSeriesDetails(
        page_url,
        session=client_session,
    )

    series_details = details_inst.get_content_model_sync()
    print(type(series_details))


if __name__ == "__main__":
    tv_series_details_using_item_page_url()
```

### Response
#### Success Response
- `series_details` (ItemJsonDetailsModel): A model containing detailed information about the TV series.

#### Response Example
```
<class 'moviebox_api.v1.extractor.models.json.ItemJsonDetailsModel'>
```
```

--------------------------------

### Get TV Series Details using Search Results Item (Async)

Source: https://moviebox-api-docs.netlify.app/v1/tv_series

Retrieves detailed information for a TV series using an item obtained from search results.

```APIDOC
## Get TV Series Details using Search Results Item (Async)

### Description
Retrieves detailed information about a specific TV series by using an item that was previously obtained from a search result. This method fetches details like episode counts per season, available video resolutions, and cast information.

### Method
`TVSeriesDetails.get_content_model()`

### Parameters
- `target_item` (object): An item object obtained from `Search.get_content_model()`.
- `session` (Session): The client session object.

### Request Example
```python
from moviebox_api.v1 import (
    Search,
    Session,
    SubjectType,
    TVSeriesDetails,
)


async def tv_series_details_using_search_results_item():
    client_session = Session()
    search = Search(
        client_session, query="Merlin", subject_type=SubjectType.TV_SERIES
    )

    search_results = await search.get_content_model()
    target_item = search_results.first_item

    details_inst = TVSeriesDetails(
        target_item,
        session=client_session,
    )

    series_details = await details_inst.get_content_model()
    print(type(series_details))


if __name__ == "__main__":
    import asyncio
    asyncio.run(tv_series_details_using_search_results_item())
```

### Response
#### Success Response
- `series_details` (ItemJsonDetailsModel): A model containing detailed information about the TV series.

#### Response Example
```
<class 'moviebox_api.v1.extractor.models.json.ItemJsonDetailsModel'>
```
```

--------------------------------

### Get TV Series Details using Search Results Item (Sync)

Source: https://moviebox-api-docs.netlify.app/v1/tv_series

Synchronously retrieves detailed information for a TV series using an item obtained from search results.

```APIDOC
## Get TV Series Details using Search Results Item (Sync)

### Description
Synchronously retrieves detailed information about a specific TV series by using an item that was previously obtained from a search result. This method fetches details like episode counts per season, available video resolutions, and cast information.

### Method
`TVSeriesDetails.get_content_model_sync()`

### Parameters
- `target_item` (object): An item object obtained from `Search.get_content_model_sync()`.
- `session` (Session): The client session object.

### Request Example
```python
from moviebox_api.v1 import (
    Search,
    Session,
    SubjectType,
    TVSeriesDetails,
)


def tv_series_details_using_search_results_item():
    client_session = Session()
    search = Search(
        client_session, query="Merlin", subject_type=SubjectType.TV_SERIES
    )

    search_results = search.get_content_model_sync()
    target_item = search_results.first_item

    details_inst = TVSeriesDetails(
        target_item,
        session=client_session,
    )

    series_details = details_inst.get_content_model_sync()
    print(type(series_details))


if __name__ == "__main__":
    tv_series_details_using_search_results_item()
```

### Response
#### Success Response
- `series_details` (ItemJsonDetailsModel): A model containing detailed information about the TV series.

#### Response Example
```
<class 'moviebox_api.v1.extractor.models.json.ItemJsonDetailsModel'>
```
```

--------------------------------

### Moviebox-v1 CLI Global Options

Source: https://moviebox-api-docs.netlify.app/v1/cli

Displays the version and help information for the moviebox-v1 CLI.

```bash
moviebox-v1 [OPTIONS] COMMAND [ARGS]...
```

--------------------------------

### List available mirror hosts

Source: https://moviebox-api-docs.netlify.app/v1/cli

Run the mirror-hosts command without options to discover available Moviebox mirror hosts.

```bash
moviebox-v1 mirror-hosts
```

--------------------------------

### Add moviebox-api with CLI extras to project using uv

Source: https://moviebox-api-docs.netlify.app/installation

Add the moviebox-api package and its command-line utility dependencies to your project using the uv tool.

```bash
uv add "moviebox-api[cli]"

```

--------------------------------

### Set host via environment variable

Source: https://moviebox-api-docs.netlify.app/v1/cli

Configure the API host using the MOVIEBOX_API_HOST environment variable before running the mirror-hosts command.

```bash
MOVIEBOX_API_HOST=https://mirror.example.com moviebox-v1 mirror-hosts
```

--------------------------------

### Add moviebox-api to project with uv

Source: https://moviebox-api-docs.netlify.app/installation

Use this command to add the moviebox-api package to your project's dependencies using the uv tool.

```bash
uv add moviebox-api

```

--------------------------------

### Download Movie: Specific Quality, Skip Confirmation, Custom Directory

Source: https://moviebox-api-docs.netlify.app/v1/cli

Downloads a movie in 720p quality, bypasses the confirmation prompt, and saves it to a specified directory.

```bash
# Download 720p, skip confirmation, save to ~/Movies
moviebox-v1 download-movie "Inception" -q 720p -Y -d ~/Movies
```

--------------------------------

### Look up a movie

Source: https://moviebox-api-docs.netlify.app/v1/cli

Use the item-details command to find information about a specific movie or TV series by its title.

```bash
moviebox-v1 item-details "Inception"
```

--------------------------------

### Download TV Series Video File (Async)

Source: https://moviebox-api-docs.netlify.app/v1/tv_series

Downloads the best available media file for a specific TV series episode asynchronously. Requires an active client session and TV series details. The downloaded file path is printed upon completion.

```python
from moviebox_api.v1 import (
    DownloadableTVSeriesFilesDetail,
    Search,
    Session,
    SubjectType,
    TVSeriesDetails,
)
from moviebox_api.v1.download import MediaFileDownloader


async def download_tv_series_video_file():
    client_session = Session()
    search = Search(client_session, "Merlin", subject_type=SubjectType.TV_SERIES)
    search_results = await search.get_content_model()
    target_series = search_results.first_item

    target_series_details_instance = TVSeriesDetails(
        target_series, client_session
    )
    target_series_details_model = (
        await target_series_details_instance.get_content_model()
    )

    downloadable_files = DownloadableTVSeriesFilesDetail(
        client_session, target_series_details_model
    )
    downloadable_files_detail = await downloadable_files.get_content_model(
        season=1, episode=1
    )
    target_media_file = downloadable_files_detail.best_media_file  # 

    media_file_downloader = MediaFileDownloader()
    downloaded_file = await media_file_downloader.run(
        target_media_file, filename=target_series, season=1, episode=1
    )

    print(downloaded_file.saved_to)


if __name__ == "__main__":
    import asyncio

    asyncio.run(download_tv_series_video_file())

```

--------------------------------

### Download TV Series Video File (Sync)

Source: https://moviebox-api-docs.netlify.app/v1/tv_series

Downloads the best available media file for a specific TV series episode synchronously. Requires an active client session and TV series details. The downloaded file path is printed upon completion.

```python
from moviebox_api.v1 import (
    DownloadableTVSeriesFilesDetail,
    Search,
    Session,
    SubjectType,
    TVSeriesDetails,
)
from moviebox_api.v1.download import MediaFileDownloader


def download_tv_series_video_file():
    client_session = Session()
    search = Search(client_session, "Merlin", subject_type=SubjectType.TV_SERIES)
    search_results = search.get_content_model_sync()
    target_series = search_results.first_item

    target_series_details_instance = TVSeriesDetails(
        target_series, client_session
    )
    target_series_details_model = (
        target_series_details_instance.get_content_model_sync()
    )

    downloadable_files = DownloadableTVSeriesFilesDetail(
        client_session, target_series_details_model
    )
    downloadable_files_detail = downloadable_files.get_content_model_sync(
        season=1, episode=1
    )
    target_media_file = downloadable_files_detail.best_media_file  # 

    media_file_downloader = MediaFileDownloader()
    downloaded_file = media_file_downloader.run_sync(
        target_media_file, filename=target_series, season=1, episode=1
    )

    print(downloaded_file.saved_to)


if __name__ == "__main__":
    download_tv_series_video_file()

```

--------------------------------

### Moviebox-v1 download-series Command Usage

Source: https://moviebox-api-docs.netlify.app/v1/cli

Basic usage for searching and downloading or streaming a TV series by its title.

```bash
moviebox-v1 download-series [OPTIONS] TITLE
```

--------------------------------

### Moviebox-v1 download-movie Command Usage

Source: https://moviebox-api-docs.netlify.app/v1/cli

Basic usage for searching and downloading or streaming a movie by its title.

```bash
moviebox-v1 download-movie [OPTIONS] TITLE
```

--------------------------------

### Download Movie: Specific Year, Quality, Ignore Missing Subtitles

Source: https://moviebox-api-docs.netlify.app/v1/cli

Downloads a movie from a specific year and quality, and continues even if subtitles are missing.

```bash
# Download 1080p from a specific year, ignore missing subtitles
moviebox-v1 download-movie "The Batman" -y 2022 -q 1080p -I
```

--------------------------------

### Async TV Series Details using Item Page URL

Source: https://moviebox-api-docs.netlify.app/v1/tv_series

Retrieves asynchronous TV series details using a provided page URL. Requires session and TVSeriesDetails initialization.

```python
from moviebox_api.v1 import (
    Search,
    Session,
    SubjectType,
    TVSeriesDetails,
)


async def tv_series_details_using_item_page_url():

    page_url = "/detail/merlin-sMxCiIO6fZ9?id=8382755684005333552"  # 
    client_session = Session()

    details_inst = TVSeriesDetails(
        page_url,
        session=client_session,
    )

    series_details = await details_inst.get_content_model()

    print(type(series_details))  # 


if __name__ == "__main__":
    tv_series_details_using_item_page_url()

```

--------------------------------

### Asynchronous Movie Download with Progress Callback

Source: https://moviebox-api-docs.netlify.app/v1/introduction

Download a movie asynchronously and track the download progress using a callback function. The callback receives download status updates.

```python
from moviebox_api.v1 import DownloadTracker, MovieAuto


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)


if __name__ == "__main__":
    import asyncio

    asyncio.run(main)

```

--------------------------------

### Show banner items

Source: https://moviebox-api-docs.netlify.app/v1/cli

Use the -B flag to display only banner items.

```bash
moviebox-v1 homepage-content -B
```

--------------------------------

### Synchronous Movie Download with Progress Callback

Source: https://moviebox-api-docs.netlify.app/v1/introduction

Download a movie synchronously and track the download progress using a callback function. The callback receives download status updates.

```python
from moviebox_api.v1 import DownloadTracker, MovieAuto


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


def main():
    auto = MovieAuto(tasks=1)
    auto.run_sync("Avatar", progress_hook=progress_callback)


if __name__ == "__main__":
    main()

```

--------------------------------

### Async TV Series Details using Search Results Item

Source: https://moviebox-api-docs.netlify.app/v1/tv_series

Retrieves asynchronous TV series details using an item obtained from search results. Requires session and Search initialization.

```python
from moviebox_api.v1 import (
    Search,
    Session,
    SubjectType,
    TVSeriesDetails,
)


async def tv_series_details_using_search_results_item():
    client_session = Session()
    search = Search(
        client_session, query="Merlin", subject_type=SubjectType.TV_SERIES
    )

    search_results = await search.get_content_model()

    target_item = search_results.first_item  # 

    details_inst = TVSeriesDetails(
        target_item,
        session=client_session,
    )

    series_details = await details_inst.get_content_model()

    print(type(series_details))  # 


if __name__ == "__main__":
    import asyncio

    asyncio.run(tv_series_details_using_search_results_item())

```

--------------------------------

### Sync TV Series Details using Item Page URL

Source: https://moviebox-api-docs.netlify.app/v1/tv_series

Retrieves synchronous TV series details using a provided page URL. Requires session and TVSeriesDetails initialization.

```python
from moviebox_api.v1 import (
    Search,
    Session,
    SubjectType,
    TVSeriesDetails,
)


def tv_series_details_using_item_page_url():

    page_url = "/detail/merlin-sMxCiIO6fZ9?id=8382755684005333552"  # 
    client_session = Session()

    details_inst = TVSeriesDetails(
        page_url,
        session=client_session,
    )

    series_details = details_inst.get_content_model_sync()

    print(type(series_details))  # 


if __name__ == "__main__":
    tv_series_details_using_item_page_url()

```

--------------------------------

### Test Movie Download Viability

Source: https://moviebox-api-docs.netlify.app/v1/cli

Tests if a movie download is viable without actually downloading the file.

```bash
# Test download without fetching
moviebox-v1 download-movie "Inception" -T
```

--------------------------------

### Download Series Episodes

Source: https://moviebox-api-docs.netlify.app/v1/cli

Use this command to download specific episodes or ranges of episodes for a series. Options include quality selection, file organization, and automatic mode for downloading remaining episodes.

```bash
moviebox-v1 download-series "Merlin" -s 1 -e 1
```

```bash
moviebox-v1 download-series "Merlin" -s 2 -e 3 -l 5 -q 720p -f group
```

```bash
moviebox-v1 download-series "The Last Kingdom" -s 1 -e 1 -A
```

```bash
moviebox-v1 download-series "Into the Badlands" -s 1 -e 1 -X vlc
```

```bash
moviebox-v1 download-series "Merlin" -s 3 -e 1 -O
```

```bash
moviebox-v1 download-series "Merlin" -s 1 -e 1 -l 13 -f struct -Y -d ~/Series
```

--------------------------------

### Retrieve Homepage Content

Source: https://moviebox-api-docs.netlify.app/v1/cli

Command to fetch content displayed on the Moviebox landing page. Supports filtering by title keyword and outputting details in JSON format.

```bash
moviebox-v1 homepage-content
```

```bash
moviebox-v1 homepage-content -T "action"
```

--------------------------------

### Download TV Series Subtitle (Async)

Source: https://moviebox-api-docs.netlify.app/v1/tv_series

Use this asynchronous function to download English subtitle files for a specific TV series episode. It requires setting up a client session, searching for the series, retrieving its details, and then using the CaptionFileDownloader.

```python
from moviebox_api.v1 import (
    DownloadableTVSeriesFilesDetail,
    Search,
    Session,
    SubjectType,
    TVSeriesDetails,
)
from moviebox_api.v1.download import CaptionFileDownloader


async def download_tv_series_subtitle_file():
    client_session = Session()
    search = Search(client_session, "Merlin", subject_type=SubjectType.TV_SERIES)
    search_results = await search.get_content_model()
    target_series = search_results.first_item

    target_series_details_instance = TVSeriesDetails(
        target_series, client_session
    )
    target_series_details_model = (
        await target_series_details_instance.get_content_model()
    )

    downloadable_files = DownloadableTVSeriesFilesDetail(
        client_session, target_series_details_model
    )
    downloadable_files_detail = await downloadable_files.get_content_model(
        season=1, episode=1
    )
    target_media_file = downloadable_files_detail.english_subtitle_file

    caption_file_downloader = CaptionFileDownloader()
    downloaded_file = await caption_file_downloader.run(
        target_media_file, filename=target_series, season=1, episode=1
    )

    print(downloaded_file.saved_to)


if __name__ == "__main__":
    import asyncio

    asyncio.run(download_tv_series_subtitle_file())

```

--------------------------------

### Asynchronous Movie File Download

Source: https://moviebox-api-docs.netlify.app/v1/movies

Use this snippet to asynchronously download the best available media file for a movie. Ensure you have the necessary imports and an active session.

```python
from moviebox_api.v1 import (
    DownloadableMovieFilesDetail,
    MovieDetails,
    Search,
    Session,
    SubjectType,
)
from moviebox_api.v1.download import MediaFileDownloader


async def download_movie_file():
    client_session = Session()
    search = Search(client_session, "avatar", subject_type=SubjectType.MOVIES)
    search_results = await search.get_content_model()
    target_movie = search_results.first_item

    target_movie_details_instance = MovieDetails(target_movie, client_session)
    target_movie_details_model = (
        await target_movie_details_instance.get_content_model()
    )

    downloadable_files = DownloadableMovieFilesDetail(
        client_session, target_movie_details_model
    )
    downloadable_files_detail = await downloadable_files.get_content_model()
    target_media_file = downloadable_files_detail.best_media_file

    media_file_downloader = MediaFileDownloader()
    downloaded_file = await media_file_downloader.run(
        target_media_file,
        filename=target_movie,
    )

    print(downloaded_file.saved_to)


if __name__ == "__main__":
    import asyncio

    asyncio.run(download_movie_file())

```

--------------------------------

### Navigate Search Results (Next Page)

Source: https://moviebox-api-docs.netlify.app/v1/movies

Navigates to the next page of search results.

```APIDOC
## Navigate Search Results (Next Page)

### Description
Navigates to the next page of search results based on the current search results.

### Method
`Search.next_page()`

### Parameters
- `contents` (SearchResultsModel): The current search results model.

### Request Example
```python
async def search_movie():
    # ... previous search setup ...
    contents: SearchResultsModel = await search.get_content_model()
    next_search: Search = search.next_page(contents)
    next_contents: SearchResultsModel = await next_search.get_content_model()
```

### Response
#### Success Response (200)
- `Search`: A new `Search` object configured for the next page.
- `SearchResultsModel`: The search results for the next page.
```

--------------------------------

### Asynchronous Subtitle File Download

Source: https://moviebox-api-docs.netlify.app/v1/movies

This snippet demonstrates how to asynchronously download the English subtitle file for a movie. It involves searching for the movie, retrieving its details, and then initiating the subtitle download.

```python
from moviebox_api.v1 import (
    DownloadableMovieFilesDetail,
    MovieDetails,
    Search,
    Session,
    SubjectType,
)
from moviebox_api.v1.download import CaptionFileDownloader


async def download_subtitle_file():
    session = Session()
    search = Search(session, "avatar", subject_type=SubjectType.MOVIES)

    search_results = await search.get_content_model()
    target_movie = search_results.first_item

    target_movie_details_instance = MovieDetails(target_movie, session)

    target_movie_details_model = (
        await target_movie_details_instance.get_content_model()
    )

    downloadable_files = DownloadableMovieFilesDetail(
        session, target_movie_details_model
    )
    downloadable_files_detail = await downloadable_files.get_content_model()
    target_caption_file = downloadable_files_detail.english_subtitle_file

    caption_file_downloader = CaptionFileDownloader()

    downloaded_file = await caption_file_downloader.run(
        target_caption_file, filename=target_movie
    )

    print(downloaded_file.saved_to)


if __name__ == "__main__":
    import asyncio

    asyncio.run(download_subtitle_file())

```

--------------------------------

### Synchronous Movie File Download

Source: https://moviebox-api-docs.netlify.app/v1/movies

Use this snippet to synchronously download the best available media file for a movie. This is suitable for environments where asynchronous operations are not required or feasible. Ensure all necessary imports are present.

```python
from moviebox_api.v1 import (
    DownloadableMovieFilesDetail,
    MovieDetails,
    Search,
    Session,
    SubjectType,
)
from moviebox_api.v1.download import MediaFileDownloader


def download_movie_file():
    client_session = Session()
    search = Search(client_session, "avatar", subject_type=SubjectType.MOVIES)
    search_results = search.get_content_model_sync()
    target_movie = search_results.first_item

    target_movie_details_instance = MovieDetails(target_movie, client_session)
    target_movie_details_model = (
        target_movie_details_instance.get_content_model_sync()
    )

    downloadable_files = DownloadableMovieFilesDetail(
        client_session, target_movie_details_model
    )
    downloadable_files_detail = downloadable_files.get_content_model_sync()
    target_media_file = downloadable_files_detail.best_media_file

    media_file_downloader = MediaFileDownloader()
    downloaded_file = media_file_downloader.run_sync(
        target_media_file,
        filename=target_movie,
    )

    print(downloaded_file.saved_to)


if __name__ == "__main__":
    download_movie_file()

```

--------------------------------

### Show popular searches (tabulated)

Source: https://moviebox-api-docs.netlify.app/v1/cli

Execute the popular-search command to view currently trending searches in a tabulated format.

```bash
moviebox-v1 popular-search
```

--------------------------------

### Download Caption File Only

Source: https://moviebox-api-docs.netlify.app/v1/cli

Downloads only the caption file for a movie, skipping the movie download.

```bash
# Download caption file only
moviebox-v1 download-movie "Inception" -O
```

--------------------------------

### Navigate Search Results (Previous Page)

Source: https://moviebox-api-docs.netlify.app/v1/movies

Navigates to the previous page of search results.

```APIDOC
## Navigate Search Results (Previous Page)

### Description
Navigates to the previous page of search results based on the current search results.

### Method
`Search.previous_page()`

### Parameters
- `contents` (SearchResultsModel): The current search results model.

### Request Example
```python
async def search_movie():
    # ... search setup with page number ...
    contents: SearchResultsModel = await search.get_content_model()
    previous_search: Search = search.previous_page(contents)
    previous_contents: SearchResultsModel = await previous_search.get_content_model()
```

### Response
#### Success Response (200)
- `Search`: A new `Search` object configured for the previous page.
- `SearchResultsModel`: The search results for the previous page.
```

--------------------------------

### Search Movies (Async)

Source: https://moviebox-api-docs.netlify.app/v1/movies

Asynchronously searches for movies based on a query and returns raw dictionary results or Pydantic models.

```APIDOC
## Search Movies (Async)

### Description
Asynchronously searches for movies using the `Search` class. It provides methods to get raw dictionary results or structured Pydantic models.

### Method
`Search.get_content()` and `Search.get_content_model()`

### Parameters
- `session` (Session): An active session object.
- `query` (str): The search term for the movie.
- `subject_type` (SubjectType): The type of subject to search for (e.g., `SubjectType.MOVIES`).

### Request Example
```python
from moviebox_api.v1.core import Search, Session, SubjectType

async def search_movie():
    client_session = Session()
    search = Search(session=client_session, query="avatar", subject_type=SubjectType.MOVIES)
    search_results = await search.get_content_model()
    print(search_results.items)

import asyncio
asyncio.run(search_movie())
```

### Response
#### Success Response (200)
- `dict`: Raw dictionary containing search results.
- `SearchResultsModel`: Pydantic model containing structured search results.
```

--------------------------------

### Sync TV Series Details using Search Results Item

Source: https://moviebox-api-docs.netlify.app/v1/tv_series

Retrieves synchronous TV series details using an item obtained from search results. Requires session and Search initialization.

```python
from moviebox_api.v1 import (
    Search,
    Session,
    SubjectType,
    TVSeriesDetails,
)


def tv_series_details_using_search_results_item():
    client_session = Session()
    search = Search(
        client_session, query="Merlin", subject_type=SubjectType.TV_SERIES
    )

    search_results = search.get_content_model_sync()

    target_item = search_results.first_item  # 

    details_inst = TVSeriesDetails(
        target_item,
        session=client_session,
    )

    series_details = details_inst.get_content_model_sync()

    print(type(series_details))  # 


if __name__ == "__main__":
    tv_series_details_using_search_results_item()

```

--------------------------------

### Async TV Series Search

Source: https://moviebox-api-docs.netlify.app/v1/tv_series

Performs an asynchronous search for TV series using a query and subject type. Requires session initialization.

```python
from moviebox_api.v1.core import Search, Session, SubjectType


async def search_tv_series():
    client_session = Session()
    search = Search(
        client_session, query="Merlin", subject_type=SubjectType.TV_SERIES
    )

    search_results = await search.get_content()

    print(type(search_results))  # 

    modelled_search_results = await search.get_content_model()

    print(type(modelled_search_results))  # 


if __name__ == "__main__":
    import asyncio

    asyncio.run(search_tv_series())

```

--------------------------------

### Fetch Movie Details Using Search Results Item Synchronously

Source: https://moviebox-api-docs.netlify.app/v1/movies

Retrieve detailed movie information synchronously by using an item from previous search results. This method is suitable when you already have a search result item.

```python
# Extra imports for type hints since *_sync() methods lacks such

from moviebox_api.v1 import MovieDetails, Search, Session, SubjectType
from moviebox_api.v1.extractor.models.json import ItemJsonDetailsModel
from moviebox_api.v1.models import SearchResultsModel


def movie_details_using_search_results_item():
    client_session = Session()
    search = Search(
        client_session, query="avatar", subject_type=SubjectType.MOVIES
    )

    search_results: SearchResultsModel = search.get_content_model_sync()

    target_item = search_results.first_item  # 

    md = MovieDetails(
        target_item,
        session=client_session,
    )

    details: ItemJsonDetailsModel = md.get_content_model_sync()
    print(type(details))  # 


if __name__ == "__main__":
    movie_details_using_search_results_item()

```

--------------------------------

### Search for Movies Synchronously

Source: https://moviebox-api-docs.netlify.app/v1/movies

Use this to search for movies synchronously. It returns raw dictionary results and Pydantic-modeled results.

```python
from moviebox_api.v1.core import Search, Session, SubjectType


def search_movie():
    client_session = Session()

    search = Search(
        session=client_session, query="avatar", subject_type=SubjectType.MOVIES
    )

    search_results = search.get_content_sync()
    print(type(search_results))  # 

    modelled_search_results = search.get_content_model_sync()  # 

    print(type(modelled_search_results))  # 


if __name__ == "__main__":
    search_movie()

```

--------------------------------

### Navigate to Next Search Results Page Asynchronously

Source: https://moviebox-api-docs.netlify.app/v1/movies

After fetching search results, use this to navigate to the next page of results asynchronously. Ensure `search_results.pager.hasMore` is true before calling.

```python
async def search_movie():
    ...
    contents: SearchResultsModel = await search.get_content_model() # 

    next_search: Search = search.next_page(contents)  # 

    next_contents: SearchResultsModel = await next_search.get_content_model()  # 

```

--------------------------------

### Fetch Movie Details Using Search Results Item Asynchronously

Source: https://moviebox-api-docs.netlify.app/v1/movies

Retrieve detailed movie information asynchronously by using an item from previous search results. This method is suitable when you already have a search result item.

```python
from moviebox_api.v1 import MovieDetails, Search, Session, SubjectType


async def movie_details_using_search_results_item():
    client_session = Session()
    search = Search(
        client_session, query="avatar", subject_type=SubjectType.MOVIES
    )

    search_results = await search.get_content_model()

    target_item = search_results.first_item  # 

    md = MovieDetails(
        target_item,
        session=client_session,
    )

    details = await md.get_content_model()
    print(type(details))  # 


if __name__ == "__main__":
    import asyncio

    asyncio.run(movie_details_using_search_results_item())

```

--------------------------------

### Search TV Series (Async)

Source: https://moviebox-api-docs.netlify.app/v1/tv_series

Asynchronously searches for TV series using a query and returns raw and modelled search results.

```APIDOC
## Search TV Series (Async)

### Description
Asynchronously searches for TV series based on a query. It provides both raw dictionary results and modelled results.

### Method
`Search.get_content()` and `Search.get_content_model()`

### Parameters
- `query` (string): The search term for TV series.
- `subject_type` (SubjectType.TV_SERIES): Specifies that the search is for TV series.

### Request Example
```python
from moviebox_api.v1.core import Search, Session, SubjectType


async def search_tv_series():
    client_session = Session()
    search = Search(
        client_session, query="Merlin", subject_type=SubjectType.TV_SERIES
    )

    search_results = await search.get_content()
    modelled_search_results = await search.get_content_model()

    print(type(search_results))
    print(type(modelled_search_results))


if __name__ == "__main__":
    import asyncio
    asyncio.run(search_tv_series())
```

### Response
#### Success Response
- `search_results` (dict): Raw search results.
- `modelled_search_results` (SearchResultsModel): Modelled search results.

#### Response Example
```
<class 'dict'>
<class 'moviebox_api.v1.models.SearchResultsModel'>
```
```

--------------------------------

### Search Movies (Sync)

Source: https://moviebox-api-docs.netlify.app/v1/movies

Synchronously searches for movies based on a query and returns raw dictionary results or Pydantic models.

```APIDOC
## Search Movies (Sync)

### Description
Synchronously searches for movies using the `Search` class. It provides methods to get raw dictionary results or structured Pydantic models.

### Method
`Search.get_content_sync()` and `Search.get_content_model_sync()`

### Parameters
- `session` (Session): An active session object.
- `query` (str): The search term for the movie.
- `subject_type` (SubjectType): The type of subject to search for (e.g., `SubjectType.MOVIES`).

### Request Example
```python
from moviebox_api.v1.core import Search, Session, SubjectType

def search_movie():
    client_session = Session()
    search = Search(session=client_session, query="avatar", subject_type=SubjectType.MOVIES)
    search_results = search.get_content_model_sync()
    print(search_results.items)

search_movie()
```

### Response
#### Success Response (200)
- `dict`: Raw dictionary containing search results.
- `SearchResultsModel`: Pydantic model containing structured search results.
```

--------------------------------

### Synchronous Subtitle File Download

Source: https://moviebox-api-docs.netlify.app/v1/movies

This snippet shows how to synchronously download the English subtitle file for a movie. It's useful when asynchronous operations are not preferred. Ensure all required modules are imported.

```python
from moviebox_api.v1 import (
    DownloadableMovieFilesDetail,
    MovieDetails,
    Search,
    Session,
    SubjectType,
)
from moviebox_api.v1.download import CaptionFileDownloader


def download_subtitle_file():
    session = Session()
    search = Search(session, "avatar", subject_type=SubjectType.MOVIES)

    search_results = search.get_content_model_sync()
    target_movie = search_results.first_item

    target_movie_details_instance = MovieDetails(target_movie, session)

    target_movie_details_model = (
        target_movie_details_instance.get_content_model_sync()
    )

    downloadable_files = DownloadableMovieFilesDetail(
        session, target_movie_details_model
    )
    downloadable_files_detail = downloadable_files.get_content_model_sync()
    target_caption_file = downloadable_files_detail.english_subtitle_file

    caption_file_downloader = CaptionFileDownloader()

    downloaded_file = caption_file_downloader.run_sync(
        target_caption_file, filename=target_movie
    )

    print(downloaded_file.saved_to)


if __name__ == "__main__":
    download_subtitle_file()

```

--------------------------------

### Skip confirmation prompt

Source: https://moviebox-api-docs.netlify.app/v1/cli

Use the -Y flag to bypass the confirmation prompt when looking up an item.

```bash
moviebox-v1 item-details "The Batman" -y 2022 -Y
```

--------------------------------

### Download TV Series Subtitle (Sync)

Source: https://moviebox-api-docs.netlify.app/v1/tv_series

This synchronous function downloads English subtitle files for a TV series episode. It mirrors the asynchronous approach but uses synchronous methods for API calls. Ensure the CaptionFileDownloader is initialized before use.

```python
from moviebox_api.v1 import (
    DownloadableTVSeriesFilesDetail,
    Search,
    Session,
    SubjectType,
    TVSeriesDetails,
)
from moviebox_api.v1.download import CaptionFileDownloader


def download_tv_series_subtitle_file():
    client_session = Session()
    search = Search(client_session, "Merlin", subject_type=SubjectType.TV_SERIES)
    search_results = search.get_content_model_sync()
    target_series = search_results.first_item

    target_series_details_instance = TVSeriesDetails(
        target_series, client_session
    )
    target_series_details_model = (
        target_series_details_instance.get_content_model_sync()
    )

    downloadable_files = DownloadableTVSeriesFilesDetail(
        client_session, target_series_details_model
    )
    downloadable_files_detail = downloadable_files.get_content_model_sync(
        season=1, episode=1
    )
    target_media_file = downloadable_files_detail.english_subtitle_file

    caption_file_downloader = CaptionFileDownloader()
    downloaded_file = caption_file_downloader.run_sync(
        target_media_file, filename=target_series, season=1, episode=1
    )

    print(downloaded_file.saved_to)


if __name__ == "__main__":
    download_tv_series_subtitle_file()

```

--------------------------------

### Output popular searches as JSON

Source: https://moviebox-api-docs.netlify.app/v1/cli

Use the -J flag with the popular-search command to retrieve trending searches in JSON format.

```bash
moviebox-v1 popular-search -J
```

--------------------------------

### Asynchronous Movie Download

Source: https://moviebox-api-docs.netlify.app/v1/introduction

Use this asynchronous function to download a movie and its subtitle file. It requires the movie title as input and prints the save locations.

```python
from moviebox_api.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}")


if __name__ == "__main__":
    import asyncio

    asyncio.run(main())

```