Skip to main content

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)

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 up again; 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

  1. Install Python 3.12 or newer from python.org (tick "Add python.exe to PATH").

  2. 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.

  3. 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 doctor checks 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, /ALIAS is 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-wait queues 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, --stale or --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-unblock clears that, sudo vpstream dash-pass sets a new password.
  • sudo vpstream init --tailscale goes 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 Linux sudo 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 first init.
  • Nobody gets in from outside (VPS): open 1337/tcp in your provider's firewall too.
  • start cannot read a video (Linux): it says how to give the service access; vpstream revoke takes 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 --http meanwhile.
  • GitHub's API limit for this IP is used up: wait an hour, or set GITHUB_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)

Source distribution for vpstream 0.17.1
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)

Table of built distributions (wheels) for vpstream 0.17.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 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.17.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