vidpickr
Official Python SDK for the VidPickr API. Download YouTube videos with a single function call.
from vidpickr import VidPickr
vp = VidPickr(api_key="vpk_live_...")
vp.download(
"https://www.youtube.com/watch?v=dQw4w9WgXcQ",
out="video.mp4",
quality=1080,
)
That's it. The SDK:
- Resolves the URL through
/api/v1/info - Picks the best 1080p video track and the highest-bitrate audio track
- Exchanges the merge token via
/api/v1/split_token - Streams both tracks in parallel from
/api/v1/stream - Muxes them into one MP4 with
ffmpeg -c copy(no re-encoding) - Writes the result to
video.mp4and cleans up temp files
Requirements
- Python 3.9+
- A VidPickr Plus subscription ($1/mo) and an API key, minted at vidpickr.com/account/api-keys
- ffmpeg on PATH — or use the bundled-ffmpeg extra below
Install
pip install vidpickr
If you don't have ffmpeg installed system-wide and don't want to:
pip install 'vidpickr[bundled-ffmpeg]'
That pulls imageio-ffmpeg, which ships a pre-built ffmpeg binary inside the wheel (~50 MB extra disk).
API
VidPickr(api_key, *, base_url=None, session=None)
Construct the client. session accepts a requests.Session if you want to share connection pooling or pin a User-Agent.
vp.download(url, *, out, quality='best', video_codec=None, on_progress=None) -> str
Resolve, stream, mux, and write to disk. Returns the output path.
| Argument | Type | Default | Description |
|---|---|---|---|
out |
str |
— | Output MP4 path. Parent directory must exist. |
quality |
'best' | 'highest' | 'lowest' | int |
'best' |
Target height (e.g. 1080) or preset. |
video_codec |
'av1' | 'vp9' | 'avc' | 'hevc' | None |
None |
Preferred codec when multiple are available at the same height. |
on_progress |
Callable[[dict], None] | None |
None |
Called between phases with {"phase": ..., "video_bytes": ..., ...}. |
vp.info(url) -> dict
Resolve only. Returns the VideoInfo JSON. Use when you want to inspect formats before deciding.
vp.raw
Access the low-level VidPickrClient for custom pipelines (e.g. piping audio bytes into Whisper without writing to disk).
Errors
from vidpickr import APIError, FFmpegMissingError, NoFormatError
try:
vp.download(url, out="x.mp4")
except APIError as e:
if e.code == "rate_limited":
print(f"Retry in {e.retry_after}s")
elif e.code == "plus_required":
print("Subscribe to Plus first.")
else:
raise
except FFmpegMissingError as e:
print(e) # tells you exactly how to install ffmpeg
except NoFormatError as e:
print(f"Requested format unavailable: {e}")
Subtitles
info = vp.info(url)
en_track = next(s for s in info["subtitles"] if s["code"] == "en" and not s["is_auto"])
srt = vp.raw.subtitle(en_track["download_token"], fmt="srt")
with open("captions.srt", "w", encoding="utf-8") as f:
f.write(srt)
Why no Rust extension yet?
The 0.1.0 release uses ffmpeg as a subprocess — fastest path to a working SDK. A future release will ship a tiny Rust extension via PyO3 for in-process MP4 muxing, dropping the ffmpeg dependency entirely (target install footprint ~500 KB instead of 50 MB).
License
MIT
Metadata
Release files for vidpickr 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vidpickr-0.1.0.tar.gz | 11.5 kB | Without provenance | Details for vidpickr-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vidpickr-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for vidpickr-0.1.0-py3-none-any.whl |
Total release size: 22.9 kB
Release files / vidpickr-0.1.0.tar.gz
| Download URL | vidpickr-0.1.0.tar.gz |
|---|---|
| Size | 11.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
615aa2175ac4f0e19b48fcc223afe0e1d61287ca8f82baf8e81c1873360e1334
|
|
BLAKE2b-256 checksum How to use checksums |
beedac3def618ff15d3a585963524f3f8baf93c9a4a371b4c87f84d5e37c287f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Release files / vidpickr-0.1.0-py3-none-any.whl
| Download URL | vidpickr-0.1.0-py3-none-any.whl |
|---|---|
| Size | 11.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e8c8d951558f4203c2f58a402deb0de01a1847b6256efdea6858ba00558b2b4f
|
|
BLAKE2b-256 checksum How to use checksums |
33149c295d5602ddacc500527ae9a8abe028f6dd1e42933441a4859e44e1f9d5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Security for vidpickr 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.