vs-remote

Remote execution server and frame proxy for VapourSynth.

vs-remote runs VapourSynth scripts on a remote machine (e.g. headless server or workstation) and streams frames to a local client for previewing or encoding.

It mirrors remote clips as local VideoNode proxies, streaming frames on demand with asynchronous prefetching, uses ZeroMQ for communication and supports multiple independent outputs.

Limitations

  • AudioNode outputs are not supported.

  • Variable resolution and format clips are not supported.

  • Frame property serialization only preserves primitive types (int, float, str, bytes, and lists of primitives).

    Non-primitive objects such as embedded VideoFrame references (_Alpha) fall back to their string repr().

Installation

uv add vsremote

Or with pip:

pip install vsremote

Quick Start

1. Start the Remote Server

On the machine hosting VapourSynth and source media:

vsremote serve path/to/script.vpy --address tcp://127.0.0.1:5555

Or programmatically in Python:

import vsremote

vsremote.serve("script.vpy", address="tcp://127.0.0.1:5555")

2. Connect from the Client

On the local machine:

# client_script.vpy
import vapoursynth as vs
import vsremote

# Mirror output 0 from the remote server
clip = vsremote.source("tcp://192.168.1.100:5555", output=0)

clip.set_output()

Open client_script.vpy in vsview, or pipe directly via the CLI:

# Preview in vsview
vsview client_script.vpy

# Pipe directly from CLI
vsremote pipe tcp://192.168.1.100:5555 --output 0 | ffmpeg -i - -c:v libx264 out.mp4

CLI Reference

Command Description Example
serve Host a .vpy script or execution server vsremote serve script.vpy --address tcp://127.0.0.1:5555
ping Test connection and measure round-trip latency vsremote ping tcp://192.168.1.100:5555
info Display metadata for all outputs on the remote server vsremote info tcp://192.168.1.100:5555
pipe Stream frames directly to stdout as Y4M or raw planes vsremote pipe tcp://192.168.1.100:5555 --y4m --output 0 | x265 --y4m - -o out.hevc
keygen Generate a Curve25519 keypair for CurveZMQ encryption & client auth vsremote keygen

Python API Reference

Client API

vsremote.source(...)

Create a local vs.VideoNode proxy mirroring a remote output:

import vsremote

clip = vsremote.source(
    address="tcp://192.168.1.100:5555",
    output=0,
    compression="zstd",  # "zstd" or "none"
    prefetch=4,  # Frames to asynchronously prefetch ahead
    auth_token=None,  # Optional authentication token
    curve_server_key=None,  # Optional CurveZMQ server public key
    curve_public_key=None,  # Optional CurveZMQ client public key
    curve_secret_key=None,  # Optional CurveZMQ client secret key
    forward_logs=True,  # Stream remote logs to local logging
)

vsremote.RemoteClient

Client for output introspection, dynamic script loading, and multi-output retrieval:

import asyncio

import vsremote

with vsremote.RemoteClient("tcp://192.168.1.100:5555") as client:
    # Introspect available outputs
    outputs = client.list_outputs().result()
    for item in outputs:
        print(f"[{item.index}] {item.name}: {item.info.width}x{item.info.height}")

    # Get proxies for specific or all clips
    clip0 = client.get_output(0)
    all_clips = client.get_outputs()  # dict[int, vs.VideoNode]


async def main() -> None:
    # Also usable as asynchronous context manager
    async with vsremote.RemoteClient("tcp://192.168.1.100:5555") as client:
        # Dynamic control (requires server started with --allow-eval)
        await client.reload()  # Reload script from disk
        await client.load_script("/path/to/another.vpy")  # Switch active script
        await client.load_code("import vapoursynth as vs; vs.core.std.BlankClip().set_output()")


asyncio.run(main())

Remote Script Authoring API

When authoring .vpy scripts served by vsremote, use vsremote.set_output to register named outputs:

# server_script.vpy
import vapoursynth as vs

from vsremote import is_preview, set_output

core = vs.core

src = core.bs.VideoSource("source.mkv")
noartifact = core.noise.Add(src, var=2000)

set_output(src)
set_output(noartifact)

if is_preview():
    print("Running inside vsremote server environment")

Security

VapourSynth scripts are Python code. Evaluating untrusted .vpy scripts or enabling --allow-eval grants arbitrary code execution privileges within the server process.

  • Defaults: The server binds to 127.0.0.1 with --allow-eval disabled by default.

  • Remote / WAN (Recommended): Use SSH port forwarding so no ZeroMQ ports are exposed to the internet:

    # Remote server (bind to localhost)
vsremote serve script.vpy --address tcp://127.0.0.1:5555

# Local client (SSH tunnel)
ssh -N -L 5555:127.0.0.1:5555 user@remote-server.com

# Connect locally
vsremote info --address tcp://127.0.0.1:5555

  • Direct LAN (Encryption Only): Enable CurveZMQ (Curve25519) encryption and optional pre-shared token authentication:

    # Server (generate ephemeral keypair or provide static secret key)
vsremote serve script.vpy --address tcp://192.168.1.100:5555 --curve-secret-key "<SERVER_SECRET>" --auth-token "secret"

# Client
vsremote info tcp://192.168.1.100:5555 --curve-server-key "<SERVER_PUBLIC>" --auth-token "secret"

  • Direct LAN (Mutual Authentication & Whitelisting): Whitelist authorized client public keys on the server:

    # Server (whitelist allowed client public keys)
vsremote serve script.vpy --address tcp://192.168.1.100:5555 --curve-secret-key "<SERVER_SECRET>" --curve-allowed-keys "<CLIENT_PUBLIC>"

# Client (connect with client keypair)
vsremote info tcp://192.168.1.100:5555 --curve-server-key "<SERVER_PUBLIC>" --curve-public-key "<CLIENT_PUBLIC>" --curve-secret-key "<CLIENT_SECRET>"

  • Untrusted Scripts/Code: Run vsremote in a rootless container with read-only mounts and dropped capabilities.

Architecture

flowchart BT
    subgraph Client ["Client Machine"]
        SRC["vsremote.source / RemoteClient"]
        CT["ClientTransport (DEALER)"]
        SUB["Stream Subscriber (SUB)"]

        SRC -->|"ModifyFrame"| CT
    end

    ZMQ{{"ZeroMQ Transport\n(TCP / IPC)"}}

    subgraph Server ["Rendering Server"]
        SD["ServerDaemon (ROUTER)"]
        VSE["VapourSynth Core / vsengine"]

        SD -->|"get_frame_async"| VSE
        VSE -->|"vs.VideoFrame"| SD
    end

    CT <-->|"Requests & Frames"| ZMQ
    ZMQ <-->|"Render Requests"| SD
    SD -->|"PUB Logs & Output"| ZMQ
    ZMQ -->|"Events"| SUB

Notes

This project was developed with the assistance of AI coding tools.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.3)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Ichunjo from gravatar.com Ichunjo

Credits

Author: Vardë

Requires

Python >=3.12

Tags

encoding server vapoursynth video video-processing

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vsremote-0.2.2.tar.gz (128.6 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

vsremote-0.2.2-py3-none-any.whl (43.7 kB view details)

Uploaded Python 3

vsremote-0.2.2-cp315-cp315-win_amd64.whl (60.8 kB view details)

Uploaded CPython 3.15Windows x86-64

vsremote-0.2.2-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (97.6 kB view details)

Uploaded CPython 3.15manylinux: glibc 2.17+ x86-64

vsremote-0.2.2-cp315-cp315-macosx_15_0_arm64.whl (97.1 kB view details)

Uploaded CPython 3.15macOS 15.0+ ARM64

vsremote-0.2.2-cp314-cp314-win_amd64.whl (60.9 kB view details)

Uploaded CPython 3.14Windows x86-64

vsremote-0.2.2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (97.7 kB view details)

Uploaded CPython 3.14manylinux: glibc 2.17+ x86-64

vsremote-0.2.2-cp314-cp314-macosx_15_0_arm64.whl (97.0 kB view details)

Uploaded CPython 3.14macOS 15.0+ ARM64

vsremote-0.2.2-cp313-cp313-win_amd64.whl (61.3 kB view details)

Uploaded CPython 3.13Windows x86-64

vsremote-0.2.2-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (97.5 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

vsremote-0.2.2-cp313-cp313-macosx_15_0_arm64.whl (152.0 kB view details)

Uploaded CPython 3.13macOS 15.0+ ARM64

vsremote-0.2.2-cp312-cp312-win_amd64.whl (61.4 kB view details)

Uploaded CPython 3.12Windows x86-64

vsremote-0.2.2-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (98.0 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

vsremote-0.2.2-cp312-cp312-macosx_15_0_arm64.whl (153.6 kB view details)

Uploaded CPython 3.12macOS 15.0+ ARM64

File details

Details for the file vsremote-0.2.2.tar.gz.

File metadata

  • Download URL: vsremote-0.2.2.tar.gz
  • Upload date:
  • Size: 128.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for vsremote-0.2.2.tar.gz
Algorithm Hash digest
SHA256 117e432fba25e95e3610d4ea74a3c90a246872749c7142fee190ad6be9a1a8f0
MD5 e93b1d1dfbec54cc3f9f2e446637cf7b
BLAKE2b-256 6d65444850c28b9e3de92edfba99e7f28756850a24c704abbbebd25ae75aaef7

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.2.tar.gz:

Publisher: cd.yml on Ichunjo/vs-remote

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vsremote-0.2.2-py3-none-any.whl.

File metadata

  • Download URL: vsremote-0.2.2-py3-none-any.whl
  • Upload date:
  • Size: 43.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for vsremote-0.2.2-py3-none-any.whl
Algorithm Hash digest
SHA256 5225da49776f1ad18370eb5ee6f953ecf665d792f524be0dc09d3393584ebee8
MD5 d1399370328d735e867561dd9e556eaf
BLAKE2b-256 edbae72d36fa2de0c044f2a9435d8ad7cfe25008e7667bc033dd57802e08397a

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.2-py3-none-any.whl:

Publisher: cd.yml on Ichunjo/vs-remote

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vsremote-0.2.2-cp315-cp315-win_amd64.whl.

File metadata

  • Download URL: vsremote-0.2.2-cp315-cp315-win_amd64.whl
  • Upload date:
  • Size: 60.8 kB
  • Tags: CPython 3.15, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for vsremote-0.2.2-cp315-cp315-win_amd64.whl
Algorithm Hash digest
SHA256 cdc60ea90878653fa2bd9ac79f9203a7a5edbf6e7bc07dba6a298e3703bc359b
MD5 34e4d3d63b91548510167282f316e0b9
BLAKE2b-256 55057f067e6e8c4db3509e4e8d879b5809dc71358774f928d1949a9a55bf3b3c

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.2-cp315-cp315-win_amd64.whl:

Publisher: cd.yml on Ichunjo/vs-remote

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vsremote-0.2.2-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for vsremote-0.2.2-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 fbb4fd7c1cff84f1f323756eb4fcf1bb4f6f75fa5cd5741a6cdbe487fef7b1a3
MD5 7899c76f4839143307992246fc68d46b
BLAKE2b-256 d116d1070e75f2d998f452fb8e49991ba54b88a58768840439450990752ef662

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.2-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.whl:

Publisher: cd.yml on Ichunjo/vs-remote

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vsremote-0.2.2-cp315-cp315-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for vsremote-0.2.2-cp315-cp315-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 625c7fe034add2083cdc4a42b2f5b4baafe82c0522c6dc170c0ac7035b26b697
MD5 695785a14ecc30e7a9ed6f1cd885635a
BLAKE2b-256 32763881aafc1af70b8283e8d222b2cd9a68658e381509a365e1baf770defca0

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.2-cp315-cp315-macosx_15_0_arm64.whl:

Publisher: cd.yml on Ichunjo/vs-remote

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vsremote-0.2.2-cp314-cp314-win_amd64.whl.

File metadata

  • Download URL: vsremote-0.2.2-cp314-cp314-win_amd64.whl
  • Upload date:
  • Size: 60.9 kB
  • Tags: CPython 3.14, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for vsremote-0.2.2-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 f4dfe6df532b108392b3440c405e87fe9c9215e3168a93f6ba0254af4a8bd436
MD5 366fd2b2f3761ad520c52d36575a8880
BLAKE2b-256 8b2680a7b8a8d82cde8c58efaced91ac6567fa4e05d6219fa04ade773549c7c3

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.2-cp314-cp314-win_amd64.whl:

Publisher: cd.yml on Ichunjo/vs-remote

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vsremote-0.2.2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for vsremote-0.2.2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 380ff45b9132c6dc2801b4a553a10889fc881e573f49de02a28e469b4b85fc43
MD5 16de675a2ce948358d88fd26a71a095f
BLAKE2b-256 9c9b159734bd16644a98cfa5a9693b9edef00832a3b0e58d63891113cee5e14d

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl:

Publisher: cd.yml on Ichunjo/vs-remote

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vsremote-0.2.2-cp314-cp314-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for vsremote-0.2.2-cp314-cp314-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 bf8ded2b5f29944d31777a2865b8935ddfe28a62aed4330a00a2be47fb88bf71
MD5 d9dda1ad8d1030f091e38d4d8cc7ea34
BLAKE2b-256 899b70cd4580a4bf1e9bd566b304b46408a1e6c055fec5f22bacabf8f8673a1e

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.2-cp314-cp314-macosx_15_0_arm64.whl:

Publisher: cd.yml on Ichunjo/vs-remote

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vsremote-0.2.2-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: vsremote-0.2.2-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 61.3 kB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for vsremote-0.2.2-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 c4b2511d8e4bacaec623171be636ced8620b9d653772d3371d888cd0c260dd7d
MD5 eeeeddc5764de42de98bca58abbbd05f
BLAKE2b-256 dc63ae4c3cb5a8e56def0c11e533c75f1ea76748b75e0acea42618c94ad26c49

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.2-cp313-cp313-win_amd64.whl:

Publisher: cd.yml on Ichunjo/vs-remote

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vsremote-0.2.2-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for vsremote-0.2.2-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 2f50fba77df81f217314bd46cdb34213d5cd553e17bfffb8259e402addfef394
MD5 3768392d05a6b59b51dd48ab04923bb4
BLAKE2b-256 1fdcc18930b20c22ef72019443ef1d43c5f8407fc5f6978ed148e2ef42a00573

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.2-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl:

Publisher: cd.yml on Ichunjo/vs-remote

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vsremote-0.2.2-cp313-cp313-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for vsremote-0.2.2-cp313-cp313-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 7db0429077a5024386fcf2e7e2bca7ea2cf9c0c31eea950ebaace5425d6d7ee0
MD5 73ecb3ccad9e4d0e9265bc4b46a81c9c
BLAKE2b-256 e8435c4e01d5dc95ef3440d72d63b1427c615dacc7a5caed06f2826796546741

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.2-cp313-cp313-macosx_15_0_arm64.whl:

Publisher: cd.yml on Ichunjo/vs-remote

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vsremote-0.2.2-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: vsremote-0.2.2-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 61.4 kB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for vsremote-0.2.2-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 3e7c15955f7775b00081f88b26de224e5dc406de1daefb94ce3353655cba6cf4
MD5 9aa64a3730eaa122217a02a40117d4bb
BLAKE2b-256 78bb45a5aca8ae5f9a8d454faf5061d3fa4a3ec72fc3f92d021d999dd617e69c

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.2-cp312-cp312-win_amd64.whl:

Publisher: cd.yml on Ichunjo/vs-remote

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vsremote-0.2.2-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for vsremote-0.2.2-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 8680e17627b87bef02ec110bb640b4b39f6646d300c02565b603c0de3a9d8c5d
MD5 693d0943336dcb7c22ee4e66cf84ce7a
BLAKE2b-256 358e11f80491a19612451feaba28330bfe1af68c02627f88ede6e58924e2961d

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.2-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl:

Publisher: cd.yml on Ichunjo/vs-remote

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vsremote-0.2.2-cp312-cp312-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for vsremote-0.2.2-cp312-cp312-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 67ded90ca79434fd8260fb2c7b91a4e6798a6fbae7fe28c84e2794cda89b9238
MD5 386ff6b98319795670dddb7f548226be
BLAKE2b-256 fd9c36cc9471779ceaa0299723bac72533ce7667242d36396369f6c85b419d31

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.2-cp312-cp312-macosx_15_0_arm64.whl:

Publisher: cd.yml on Ichunjo/vs-remote

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.2.3

14 files

This release

0.2.2 This release

14 files

0.2.1

14 files

0.2.0

14 files

0.1.0

14 files

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