Metadata-Version: 2.4
Name: bentu-downloader
Version: 0.1.2
Summary: A standalone Python video downloader toolkit for public platform media and direct streams.
Author: Bentu Contributors
License-Expression: MIT
Project-URL: Homepage, https://example.com/bentu-downloader
Project-URL: Repository, https://example.com/bentu-downloader
Project-URL: Issues, https://example.com/bentu-downloader/issues
Keywords: video,download,downloader,hls,media
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
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: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Bentu Downloader

Bentu is a standalone, importable Python downloader toolkit for public platform media, direct streams, and pages that expose downloadable video or audio.

It is designed for videos and media that you own, created yourself, have permission to download, or are otherwise legally allowed to save. It does not bypass DRM, paywalls, logins, captchas, private APIs, or other access controls.

## What works in this first version

- Importable Python API: `from bentu import download`
- CLI command: `bentu URL -o "%(title)s.%(ext)s"`
- Standalone runtime: no required third-party Python packages
- Direct media URLs such as `.mp4`, `.webm`, `.m4a`, `.mp3`, `.mov`
- Simple unencrypted HLS playlists (`.m3u8`)
- Generic HTML pages that expose media via `<video>`, `<source>`, `og:video`, Twitter cards, JSON-LD, or visible script data
- Public platform pages when they expose a normal downloadable media URL
- PyPI update check on CLI startup
- Retries, progress output, custom headers, output templates
- Provider architecture for adding dedicated site extractors

## Install locally

```bash
python -m pip install -e .
```

## Build for PyPI

Every PyPI upload needs a version that has never been uploaded before:

```bash
python scripts/bump_version.py 0.1.2
```

```bash
python -m pip install build
python -m build
```

The build output will be in `dist/`.

## Upload to PyPI

Install Twine once:

```bash
python -m pip install twine
```

Upload:

```bash
python -m twine upload dist/*
```

## CLI examples

```bash
bentu "https://example.com/video.mp4"
bentu "https://example.com/video.mp4" -o "downloads/%(title)s.%(ext)s"
bentu "https://example.com/page-with-video" --print-info
bentu "https://example.com/stream.m3u8" --no-update-check
bentu "https://example.com/video.mp4" --add-header "Referer:https://example.com/"
```

Useful options:

```bash
bentu --help
```

## Python examples

After installing from PyPI, the package name uses a dash:

```bash
python -m pip install bentu-downloader
```

Python imports cannot contain a dash, so use the import name with an underscore:

```python
import bentu_downloader

result = bentu_downloader.download("https://example.com/video.mp4")
print(result.path)
```

Short import name also works:

```python
import bentu

result = bentu.download("https://example.com/video.mp4")
print(result.path)
```

```python
from bentu_downloader import download

result = download("https://example.com/video.mp4", output="videos/%(title)s.%(ext)s")
print(result.path)
```

Or use the downloader object:

```python
from bentu_downloader import Downloader, DownloadOptions

downloader = Downloader()
info = downloader.extract_info("https://example.com/page-with-video")
print(info.title, info.formats)

result = downloader.download(
    "https://example.com/page-with-video",
    DownloadOptions(output="%(title)s.%(ext)s"),
)
```

## Flexible option wrapper

```python
from bentu_downloader import BentuDL

options = {
    "output": "downloads/%(title)s.%(ext)s",
    "format": "best",
    "quiet": False,
}

with BentuDL(options) as bdl:
    info = bdl.extract_info("https://example.com/video.mp4", download=True)
    print(info["filepath"])
```

## Adding a provider

Create a provider by subclassing `Provider` and returning a `MediaInfo` object:

```python
from bentu.models import MediaFormat, MediaInfo
from bentu.providers import Provider


class MyProvider(Provider):
    name = "my-site"

    def supports(self, url: str) -> bool:
        return "example.com" in url

    def extract(self, url: str, context):
        return MediaInfo(
            webpage_url=url,
            title="Example Video",
            formats=[MediaFormat(format_id="best", url="https://example.com/video.mp4", ext="mp4")],
        )
```

Then pass it to `Downloader(providers=[MyProvider()])`.

## Platform support

Bentu can download from platform pages when the page exposes a normal public media URL. That includes public pages on platforms such as YouTube, TikTok, Instagram, VOE, Filmora, Vimeo, X, Facebook, and similar sites when a direct media file or simple stream is visible to the page. Dedicated providers can be added for sites that need custom parsing. Sites that require DRM, login, captchas, protected private APIs, regional checks, or non-public stream signatures are reported clearly instead of being bypassed.

## Publishing checklist

Before uploading, change the package metadata in `pyproject.toml`:

- `name`, if you want a different PyPI project name
- `authors`
- `Homepage`, `Repository`, and `Issues`
- `version`, every time you publish a new release
