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), or as prepared HLS versions with a player page for TV browsers (browser mode).
Install
Needs Linux, Python 3.12+, Caddy, ufw, Tailscale (with HTTPS certificates) and systemd.
ffmpeg is used by browser mode, 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 ls [FOLDER] |
Lists a folder's videos (default [media] folder, /srv/media), their tracks and what is prepared |
vpstream track-info FILE |
Lists a file's tracks with the numbers --sub and --audio take |
vpstream prepare --file F / --dir D |
Makes the versions browser mode plays (--sub 1,3, eng, none) |
vpstream prepared [rm PATH | --stale | --all | cancel [PATH]] |
Lists, removes or cancels prepared versions |
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:
/ALIASplays a--filestream. For--dirit 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) orlocked(only enabled ones). Change it live withvpstream devicesor 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,
startgives it read access with an ACL entry for that user alone (needs theaclpackage and you owning the files);stoptakes 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.
Browser mode
vpstream track-info /srv/media/film.mkv # tracks, and how each is prepared
vpstream prepare --file /srv/media/film.mkv --sub 1,3 # base version and two subtitle tracks
vpstream start --file /srv/media/film.mkv --mode browser --audio eng --sub 1
- Versions: the base copies the video when browsers play it (H.264 8-bit, HEVC, AV1),
else transcodes it to H.264 at its own size; every audio track becomes an AAC alternate.
Plain text subtitles (SRT, mov_text, WebVTT) become soft WebVTT; image, ASS and SSA tracks
get a burned-in version, one full encode each. Without
--sub, every plain text track is prepared and nothing is burned in. A prepare runs in the service at low priority, one job after the other, and asks first when it would take longer than the film (--yes). - Start: a missing base version is made by
startitself when it is a copy (minutes); a transcode is asked about first. Until it is ready the address says how far it got. - Dashboard: shows the plan of a prepare (what it makes, how long, the tracks it found) before it is queued, then its progress.
- Player: large buttons for a TV remote that works as a pointer: play, ±10 s, audio (each track, then Off), subtitles (Off, then each prepared one), episodes and next. Other players get the HLS playlist at the same address.
- Who gets in: approval by default; a waiting browser shows a 4-digit code, which
vpstream devicesand the dashboard show next to its address. - Cache:
/var/cache/vpstream/prepared, kept untilvpstream prepared rm. A changed file is prepared again; its old versions are listed as stale.
Configuration
/etc/vpstream/config.toml: port (1337) and host (the address shown in URLs) under
[stream], port (1338) under [dashboard], and copy_speed and encode_speed under
[prepare] for the time estimates (vpstream bench FILE prints the values for this host), and
folder under [media], the folder vpstream ls lists by default (/srv/media).
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.9.1
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 |
|---|---|---|---|---|
| vpstream-0.9.1.tar.gz | 424.7 kB | With provenance | Details for vpstream-0.9.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vpstream-0.9.1-py3-none-any.whl | Python 3 | none | any | Details for vpstream-0.9.1-py3-none-any.whl |
Total release size: 893.3 kB
Release files / vpstream-0.9.1.tar.gz
| Download URL | vpstream-0.9.1.tar.gz |
|---|---|
| Size | 424.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bd3d2ac7cbbefd9e69265310ccd7894a1de568c27b9fcb7b33eb5cb564a4b705
|
|
BLAKE2b-256 checksum How to use checksums |
739fa164b831ad2d70fc447dfe02b0711c7925d3808cd0466c7d69ab88f381ac
|
| 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 logRelease files / vpstream-0.9.1-py3-none-any.whl
| Download URL | vpstream-0.9.1-py3-none-any.whl |
|---|---|
| Size | 468.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9ced295ca6f50caae98a782114f3d50b106d0b5de1485cea8e6bc9919cd407aa
|
|
BLAKE2b-256 checksum How to use checksums |
8ddd5ba136063facc8641034e33f12907b5ee044ce974640bf9583756ab1ee76
|
| 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 logSecurity for vpstream 0.9.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.
Attestation for vpstream-0.9.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 11, 2026.
Transparency logA 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.