vpstream
Stream a video file or a folder on demand, to VLC and other players (direct mode) or to a TV's web browser (browser mode). The stream's port is open only while a stream runs.
| Where | How it serves | Controlled from |
|---|---|---|
| Linux server (VPS) | the internet, or your home network | SSH, and a dashboard on your tailnet |
| Android, in Termux | your home network only | the terminal, and a dashboard on the phone's Wi-Fi |
| Windows | your home network only | a desktop window |
Termux and Windows serve your private local network only (192.168.x.x, 10.x.x.x, 172.16-31.x.x). Use them on your own Wi-Fi, never on public Wi-Fi: anyone on the network can reach the stream.
Contents
- Linux server (VPS): install, update, uninstall
- Android (Termux)
- Windows
- Streaming (Linux and Termux): direct mode, browser mode, who may watch
- Commands
- More on Linux: configuration, public dashboard, local network mode, HTTPS for streams
- Troubleshooting
- Development
Linux server (VPS)
Tested on Ubuntu Server 24.04. Needs systemd, Python 3.12+, ufw, Caddy (2.10+ for HTTPS
streams) and Tailscale (not needed for a public dashboard). vpstream doctor checks all of it
and prints the fix for anything missing.
Install
sudo apt install pipx ufw acl mkvtoolnix
sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install "vpstream[dev]"
vpstream install caddy # the current Caddy (Ubuntu's 2.6.2 serves plain HTTP only)
vpstream install ffmpeg # a current ffmpeg, for browser mode
sudo vpstream init # the service, its user, the firewall helper, the dashboard
# log out and in again: init added you to the vpstream group
vpstream doctor
vpstream selftest --integration
The install must be system-wide: the service runs as its own user. The dashboard is at
https://<tailnet name>:1338/.
Update
vpstream stop
sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx upgrade vpstream
sudo vpstream init # restarts the service on the new version
vpstream doctor
Settings, the dashboard's password and certificate, the stream's HTTPS certificate and the
prepared videos are kept. vpstream update caddy and vpstream update ffmpeg update those.
Uninstall
vpstream stop
vpstream revoke # file access a stream that ended by itself left behind
sudo vpstream uninstall --purge # --purge: also the prepared videos and vpstream's ffmpeg
sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx uninstall vpstream
It removes the service, its user, the firewall rules it opened and /etc/vpstream and
/var/lib/vpstream. Your videos, the apt packages and your provider's firewall rules stay.
Android (Termux)
The phone streams to a TV or another phone on the same Wi-Fi. No root, no service.
Install and set up
pkg install python ffmpeg caddy mkvtoolnix
termux-setup-storage # lets Termux read the phone's videos
pip install "vpstream[dev]"
vpstream init # the configuration, and what is left to do
vpstream dash-pass # the dashboard's password
vpstream up # the daemon in the background; keeps the phone awake
vpstream doctor
Update
vpstream down
pip install --upgrade "vpstream[dev]"
vpstream up
Stop: vpstream down stops the daemon and lets the phone sleep.
- Private network only: vpstream listens on the phone's Wi-Fi address, which must be private. Android has no firewall, so use your own Wi-Fi only. Turning the Wi-Fi off stops a running stream.
- Dashboard:
http://<phone's address>:1338/, behind the password. - Files: configuration
~/.config/vpstream/config.toml, log~/.local/state/vpstream/daemon.log, prepared videos~/.cache/vpstream/. - If Android stops Termux: run
vpstream upagain; a running stream comes back. If a stream stops by itself on Android 12+, turn off "child process restrictions" in the developer options (or see the Termux wiki on "phantom processes"). - A phone serves one or two devices. Transcoding is slow: prepare ahead, or use direct mode.
Streaming works as on Linux: see Streaming.
Windows
A desktop window that streams, prepares videos for browsers and installs the programs it needs. Windows 10 or 11, 64-bit.
Install
-
Install Python 3.12 or newer from python.org (tick "Add python.exe to PATH").
-
In a terminal:
py -m pip install vpstream py -m vpstream
Windows asks to let vpstream make changes (it adds a firewall rule while a stream runs): choose Yes. A vpstream icon is put on the desktop; open it from there next time.
-
On first open, the window offers to install ffmpeg, Caddy and MKVToolNix. Press Install.
Update: close the window, then py -m pip install --upgrade vpstream. The programs it
uses are updated from the window's Tools tab.
Uninstall: py -m vpstream windows-uninstall (the programs it installed and the desktop
icon), then py -m pip uninstall vpstream.
The window
- Stream: pick a file or a folder, choose VLC or a web browser/TV and who may watch, then Start. The address to open on the TV or phone is shown big, with Copy. Devices are listed as they connect; select one to Let in, Keep out or Rename.
- Prepare for browsers: pick a video and its subtitles; Prepare queues it. The queue shows each video's progress; the prepared ones can be streamed or removed.
- Tools: which ffmpeg, Caddy and MKVToolNix are used, and vpstream's own copies: install, update to the latest release (checked against its published SHA-256) or remove.
Good to know
- Private network only: the stream listens on this PC's private address. The window warns when Windows treats your Wi-Fi as Public (phones cannot reach the PC then) and offers to make it private.
- Files: settings in
%APPDATA%\vpstream; programs, prepared videos and the log (vpstream.log, with Open log in the window) in%LOCALAPPDATA%\vpstream. py -m vpstream doctorchecks the install.
Streaming (Linux and Termux)
Direct mode
For VLC, mpv and other players. The file is served as it is.
vpstream start --file /srv/media/film.mkv # http://<ip>:1337/abc
vpstream start --dir /srv/media/show --alias show # /show (a list), /show/1, /show/2 ...
vpstream status
vpstream stop
--ttl MINUTES: stops by itself after this long (default 180, 0 for never).- For a folder,
/ALIASis an episode list in a browser and a playlist in a player. - MKV files are given a full seek index (mkvmerge, once, no re-encoding), so VLC for Android resumes them quickly.
Browser mode
For a TV's web browser: the video is prepared as HLS first, with a player page made for a TV remote.
vpstream track-info /srv/media/film.mkv # its tracks, with their numbers
vpstream prepare --file /srv/media/film.mkv --sub 1,3 # the base version and 2 subtitles
vpstream prepare --dir /srv/media/show --sub eng # a folder; English subtitles
vpstream prepared # what is prepared
vpstream start --file /srv/media/film.mkv --mode browser --audio eng --sub 1
- Prepare: copies the video when browsers can play it, else transcodes it to H.264. Text
subtitles become soft subtitles; image and ASS subtitles are burned in (one encode each). It
asks first when it would take longer than the film (
--yes);--no-waitqueues it and returns. - Player: play, ±10 s, audio, subtitles, episodes, next, full screen.
vpstream clients(or the dashboard's Viewers tab) changes the audio, subtitles or position of a TV from afar. - Remove:
vpstream prepared rm PATH,--staleor--all.
Who may watch
--policy open (anyone; the default in direct mode), approval (you let each one in; the
default in browser mode, where a waiting TV shows a 4-digit code) or locked (only those let
in). vpstream devices lists them and lets them in or keeps them out, live:
vpstream devices # who asked, and their state
vpstream devices enable DEVICE # let in (disable: keep out)
vpstream devices lock # nobody new from now on
Commands
| Command | What it does |
|---|---|
vpstream start --file F / --dir D |
Starts a stream (--mode browser, --alias, --ttl, --policy, --audio, --sub, --http) |
vpstream stop, vpstream status [--json] |
Stops the stream; shows its addresses and state |
vpstream ls [FOLDER] |
A folder's videos, their tracks and what is prepared |
vpstream track-info FILE |
A file's tracks, with the numbers prepare and start take for subtitles and audio |
vpstream prepare --file F / --dir D |
Prepares for browser mode (--sub 1,3 / eng / none, --yes, --no-wait) |
vpstream prepared [rm PATH | --stale | --all | cancel] |
Lists, removes or cancels prepared versions |
vpstream devices [enable|disable DEVICE | lock | unlock] |
Who asked for the stream, and who gets in |
vpstream clients [set DEVICE... | --all] |
Browser mode: what each TV plays; --audio, --sub, --seek, --start-at (--video in a folder), --name |
vpstream alias NAME |
Changes the name in the address |
vpstream doctor |
Checks this machine, and says how to fix what is missing |
vpstream up, vpstream down |
Termux: starts or stops the daemon |
sudo vpstream init [--local | --https | --no-tailscale] |
Linux: sets the service up (see More on Linux) |
sudo vpstream dash-pass [--dash-pass-file FILE] |
Linux: a new dashboard password (--dash-pass takes it on the command line, and leaves it in shell history) |
sudo vpstream uninstall [--purge] |
Linux: removes it |
vpstream install ffmpeg|caddy [--yes] [--tmp DIR], vpstream update ffmpeg|caddy |
Linux: installs or updates them; they ask first unless --yes, and --tmp DIR puts the download on another disk |
vpstream windows-install [PROGRAM...] [--yes], vpstream windows-uninstall [--yes] |
Windows: the programs it needs, and the desktop icon |
vpstream bench FILE |
How fast this machine copies, transcodes and burns in (--sample, --presets, --sub, --json, --tmp, --no-nice) |
vpstream caps |
A page that tests what a TV browser can play (--host, --port, --ttl, --out, --clips, --regen) |
vpstream selftest [--integration] |
Runs the tests shipped with the package |
More on Linux
Configuration
/etc/vpstream/config.toml, written by init with every setting explained: stream port
(1337), dashboard port (1338), the address shown, HTTPS, prepare speeds (vpstream bench FILE
measures them) and the media folder. vpstream doctor names a wrong setting. After a change:
sudo systemctl restart vpstream (after a dashboard port change: sudo vpstream init).
Public dashboard
sudo vpstream init --no-tailscale puts the dashboard on the internet at https://<ip>:1338/
behind a password (asked for, or --dash-pass-file FILE; --dash-pass leaves it in shell
history), with a certificate authority made
for this host's addresses only.
- Install the authority on your phone first:
vpstream dashboard-cert > vpstream-ca.crt(Android: Settings, Security, Install a certificate, CA certificate). - The password never crosses the network (challenge-response). Logins from one address wait
after 5 wrong passwords;
vpstream dash-unblockclears that,sudo vpstream dash-passsets a new password. sudo vpstream init --tailscalegoes back to the tailnet.
Local network mode
sudo vpstream init --local [--address IP] serves your home network only, at a private
address, with the dashboard at http://<address>:1338/ behind a password. Plain
sudo vpstream init goes back.
HTTPS for streams
sudo vpstream init --https serves streams at https://<ip>:1337/ALIAS with a Let's Encrypt
certificate for the address (Caddy 2.10+: vpstream install caddy). Port 80 is opened only
while a certificate is asked for; let 80/tcp in your provider's firewall too. A certificate is
kept while it lasts (Let's Encrypt allows 5 a week per address). vpstream start --http starts
one stream over plain HTTP. sudo vpstream init --no-https turns it off.
Troubleshooting
- First look:
vpstream doctor,vpstream status, and on Linuxsudo journalctl -u vpstream -n 50 --no-pager(Windows: Open log in the window). no permission to use /run/vpstream/daemon.sock: log out and in again after the firstinit.- Nobody gets in from outside (VPS): open 1337/tcp in your provider's firewall too.
startcannot read a video (Linux): it says how to give the service access;vpstream revoketakes back what a stream that ended by itself left.- No HTTPS certificate: port 80 is blocked, or Let's Encrypt's limit is reached; the log
is
/var/lib/vpstream/caddy/certificate/caddy.log.vpstream start --httpmeanwhile. GitHub's API limit for this IP is used up: wait an hour, or setGITHUB_TOKEN.- Windows: phones cannot reach the PC: the window's warning about a Public network; press Make it private.
Development
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest -n auto [--integration] # -n auto: on every core
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.17.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.17.1.tar.gz | 710.6 kB | With provenance | Details for vpstream-0.17.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vpstream-0.17.1-py3-none-any.whl | Python 3 | none | any | Details for vpstream-0.17.1-py3-none-any.whl |
Total release size: 1.5 MB
Release files / vpstream-0.17.1.tar.gz
| Download URL | vpstream-0.17.1.tar.gz |
|---|---|
| Size | 710.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
381ee6f3a3f1c3f9bd0ef074774112874c505d1991fa5d98ab386bca81ff9183
|
|
BLAKE2b-256 checksum How to use checksums |
a54deecc97dfddbe3d164fa5ae4d8a9c2316e0874205cb153d308e6c85607c5b
|
| 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 19, 2026.
Transparency logRelease files / vpstream-0.17.1-py3-none-any.whl
| Download URL | vpstream-0.17.1-py3-none-any.whl |
|---|---|
| Size | 796.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9d9b0f59852faed09291cc80de111a1cac0d3d2a71ff5939ce10a0b190033f35
|
|
BLAKE2b-256 checksum How to use checksums |
dcb10fe1a39840253de654de15cd1c120fbcfaf7ef781c88747434a4092b2927
|
| 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 19, 2026.
Transparency logSecurity for vpstream 0.17.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.17.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 19, 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.