pyVHL

A Python library for uploading short clips to video and file hosting services.

pyVHL can also download clips from a growing list of sources (via youtube-dl) and upload them to a mirror host of your choice — or pick one at random for you.

Supported Hosts

Supported Download Sources

pyVHL delegates extraction to youtube-dl, with dedicated handling for:

• Twitch clips
• YouTube
• Facebook
• Generic video pages (any site supported by youtube-dl's generic extractor)

Installation

pyVHL requires Python 3.10+.

pip install pyVHL

Or install from source with uv:

git clone https://github.com/problemxl/pyVHL.git
cd pyVHL
uv sync

Quickstart

Download a clip and mirror it to a random host:

from pyVHL.pyvhl import pyvhl

client = pyvhl()

# Download a clip and collect its metadata
video = client.get_video("https://clips.twitch.tv/FantasticTenaciousLlamaVoteYea-i8q-ElNjPqIFx7eA")

# Upload it to a randomly selected host
mirror = client.upload_video(video["title"], video["filename"])

print(f"Mirrored to {mirror.host}: {mirror.url}")

Skip the download and only inspect the metadata:

video = client.get_video(video_url, download=False)

Upload to a specific host and delete the local file afterwards:

mirror = client.upload_video(video["title"], video["filename"], host="streamable", delete_file=True)

API Reference

pyvhl()

The main client. Initialize it once and reuse it.

get_video(video_url: str, download: bool = True) -> dict

Extracts (and by default downloads) a clip via youtube-dl and returns its metadata as a dict:

If the URL cannot be processed, the values are None.

upload_video(clip_title: str, filename: str, host: str = "", delete_file: bool = False) -> VideoClient

Uploads a local file to a mirror host.

• clip_title — title passed to the host (used by Streamable).
• filename — path to the local video file.
• host — one of the identifiers in Supported Hosts. An empty string picks a random host.
• delete_file — remove the local file after a successful upload.

Returns a VideoClient subclass (StreamableVideo, CatboxVideo, QuaxVideo, PoneVideo, KappaVideo, or SegsVideo) with:

• host — the host identifier,
• url — the public mirror URL,
• shortcode — the host-specific short ID.

Raises ValueError for an unsupported host and FileNotFoundError if the file does not exist. Failed uploads are retried automatically.

Development

The project uses uv for dependency management, pytest for tests, and ruff for linting.

uv sync          # install dependencies
uv run pytest    # run the test suite
uv run ruff check pyvhl tests

Contributions follow GitFlow: branch off develop (feature/..., fix/..., doc/...) and open a pull request back into develop. Releases are cut through release/* branches into main.

License

This project does not currently include a license file. Please contact the maintainer if you intend to redistribute or reuse the code.