Skip to main content

vpstream

On-demand video streaming from a VPS. The public port opens only while a stream runs, and everything is controlled over SSH or a private dashboard.

Status: early development. This release contains only the measuring tools:

Command What it does
vpstream bench FILE Measures how fast this host copies, transcodes and burns in subtitles for a file
vpstream caps Serves a test page that checks what a TV browser can play
vpstream selftest Runs the tests shipped with the package (--integration uses the real ffmpeg)

Requirements

  • Linux, Python 3.12 or newer
  • ffmpeg and ffprobe on PATH (not bundled), with libx264; libx265 and an AV1 encoder (libsvtav1 or libaom-av1) for the full caps test set
  • Optional: mkvtoolnix (sudo apt install mkvtoolnix), only for WebVTT subtitle tracks written by mkvmerge, which ffmpeg cannot read; vpstream says when a file needs it

Install

pipx install "vpstream[dev]"     # the dev extra adds pytest for `vpstream selftest`
vpstream --version
vpstream selftest --integration

vpstream bench FILE

Encodes a sample of the file (120 seconds from about 10% in, --sample to change) at low CPU and I/O priority, and reports the speed of each step as a multiple of real time, with the estimated time for the whole file:

  • copy: the video copied into fMP4 HLS, audio converted to AAC
  • transcode: H.264 at the source resolution, for each x264 preset in --presets (default veryfast,medium); HDR sources are tone mapped
  • burn-in: the first image, ASS or SSA subtitle track (or --sub N) drawn into the video; for ASS tracks, font substitutions reported by libass are listed

--json PATH saves the results.

vpstream caps

Generates short test clips (H.264, HEVC and AV1 in 8 and 10 bit, two audio tracks, WebVTT), then serves a page on port 1337 (--port) that a TV browser opens at http://<server-ip>:1337/caps. The page is driven with the arrow keys and OK. It tests MP4 and HLS playback (hls.js and native), a subtitle overlay, audio track switching, download speed, and records which remote keys reach the page. Results are sent back and saved to caps-results-*.json. The server stops after 60 minutes (--ttl).

Clips are cached under ~/.cache/vpstream. --clips DIR must be a new or empty folder, or one that vpstream caps made before; any other folder is refused, never cleared. --regen makes the clips again.

The port must be reachable: open it in your firewall for the test and close it afterwards.

Development

python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest                  # unit tests
.venv/bin/pytest --integration    # also the tests that run ffmpeg
git config core.hooksPath .githooks

Pull requests need a Conventional Commit title (feat: ..., fix: ...). Releases are made from main by python-semantic-release.

hls.js (Apache-2.0) is bundled in src/vpstream/assets, with its version in hls.js.version. python scripts/update-hlsjs.py updates it from npm (checked against npm's sha512 integrity; --version X for a given release, --check to only compare). A weekly workflow runs the same script and opens a pull request when a new release is out.

License

MIT

Metadata

Release files for vpstream 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vpstream 0.1.1
File Size Uploaded Provenance Actions
vpstream-0.1.1.tar.gz 243.6 kB With provenance Details for vpstream-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vpstream 0.1.1
File Interpreter ABI Platform Actions
vpstream-0.1.1-py3-none-any.whl Python 3 none any Details for vpstream-0.1.1-py3-none-any.whl

Total release size: 498.0 kB

Release files / vpstream-0.1.1.tar.gz

Download URL vpstream-0.1.1.tar.gz
Size 243.6 kB
Tags Source
SHA-256 checksum
How to use checksums
846032acfbd6dbe0a741d1f575b13bd1ca069563fab3406e52cfa749569329aa
BLAKE2b-256 checksum
How to use checksums
8ab178b1f849c7a3108a19a47ee4ecf276bac6f6b465da828da0d9d111b48b11
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / vpstream-0.1.1-py3-none-any.whl

Download URL vpstream-0.1.1-py3-none-any.whl
Size 254.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fe35d62745f3bd0dc7c1cec3f5e9ba19a38302a17f284250d114db030f6b7cdc
BLAKE2b-256 checksum
How to use checksums
b11572b706e0b8c92bc5572cc2cfe721d957030f8bf888b26a2f866a4eaa3343
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for vpstream 0.1.1

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for vpstream-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page