Skip to main content

vpstream

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

Status: early development. Streams a file or a folder as it is, for players such as VLC and mpv (direct mode). Playing in a TV browser comes next.

Install

Needs Linux, Python 3.12+, Caddy, ufw, Tailscale (with HTTPS certificates) and systemd. ffmpeg is used by bench and caps; mkvtoolnix and the acl package are optional (see below). vpstream doctor checks all of it and prints the fix for anything missing.

sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install "vpstream[dev]"
vpstream doctor
sudo vpstream init

The install must be system-wide (the service runs as its own user). Upgrade with the same prefix and pipx upgrade vpstream, then sudo vpstream init again.

Commands

Command What it does
vpstream start --file F / --dir D Starts a stream of one video, or of a folder's videos
vpstream stop / status Stops the stream, or shows its addresses and state
vpstream devices [enable|disable ADDRESS | lock | unlock] Who asked for the stream, and who gets in
vpstream alias NAME Changes the short name in the address
vpstream revoke Takes back file access a stream that ended by itself left behind
vpstream doctor Checks this host
sudo vpstream init / uninstall Sets the service up, or removes it (--purge also the cache)
vpstream bench FILE Measures how fast this host copies, transcodes and burns in subtitles
vpstream caps Serves a page that tests what a TV browser can play
vpstream install ffmpeg / update ffmpeg Installs or updates a current static ffmpeg build
vpstream selftest [--integration] Runs the tests shipped with the package

Streaming

vpstream start --file /srv/media/film.mkv            # http://<ip>:1337/abc
vpstream start --dir /srv/media/show --alias show    # /show (index or playlist), /show/1, /show/2 ...
vpstream stop
  • Addresses: /ALIAS plays a --file stream. For --dir it is an episode list in a browser and an M3U playlist in a player; videos are numbered in natural order of their names.
  • Who gets in: --policy open (default; disable single addresses), approval (only those you approve; others wait, marked WL) or locked (only enabled ones). Change it live with vpstream devices or the dashboard. An address that tries 20 wrong paths is shut out.
  • Time limit: --ttl MINUTES, default 180, 0 for none.
  • Your files: the service reads videos as its own user. If it cannot, start gives it read access with an ACL entry for that user alone (needs the acl package and you owning the files); stop takes it back.
  • Seeking: MKV files whose seek index has no audio entries (most of them) make VLC for Android resume by reading from the start. vpstream serves such a file from a copy with a full index, made once with mkvmerge (no re-encoding, about a minute per GB) and kept in /var/cache/vpstream/index; until it is ready the address says to try again. Without mkvtoolnix the file is served as it is.
  • Safety: Caddy runs only while a stream does and asks the daemon about every request. Stop, the time limit and stopping the service close the port; after a crash the stream is taken up again, never after a reboot. The stream is plain HTTP.

Configuration

/etc/vpstream/config.toml: port (1337) and host (the address shown in URLs) under [stream], port (1338) under [dashboard]. Restart the service after a change.

The dashboard listens on 127.0.0.1 and init publishes it with tailscale serve at https://<tailnet name>:1338/. The stream port is opened and closed by a small root helper, vpstream-fw, which only runs ufw allow / ufw delete allow for that one port.

Development

python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest [--integration]
git config core.hooksPath .githooks

Pull request titles are Conventional Commits; releases are made from main by python-semantic-release. hls.js (Apache-2.0) is bundled; scripts/update-hlsjs.py updates it.

License

MIT

Metadata

Release files for vpstream 0.8.4

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.8.4
File Size Uploaded Provenance Actions
vpstream-0.8.4.tar.gz 360.8 kB With provenance Details for vpstream-0.8.4.tar.gz

Built distribution (wheel)

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

Total release size: 754.6 kB

Release files / vpstream-0.8.4.tar.gz

Download URL vpstream-0.8.4.tar.gz
Size 360.8 kB
Tags Source
SHA-256 checksum
How to use checksums
5fdae4a19038215244a55bd92507d125442bcabaa1b2c45c0d2ccea121d2f194
BLAKE2b-256 checksum
How to use checksums
a5fbc8849b00c4ad2d64efa4d26c88378e0f41155483d8d1b01d54e0afd2f433
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 11, 2026.

Transparency log

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

Download URL vpstream-0.8.4-py3-none-any.whl
Size 393.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6b67c2d8faf5017b741a5188cf6430e2e3c7c1b0d939fcc77588239e67c9584e
BLAKE2b-256 checksum
How to use checksums
41090fdd71cffb3d8b55fe2cf48b83d13387957668cc5123b836f97244798186
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 11, 2026.

Transparency log

Security for vpstream 0.8.4

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.8.4.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 11, 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.8.4 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