Skip to main content

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.

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.0.tar.gz (128.4 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.0-py3-none-any.whl (43.9 kB view details)

Uploaded Python 3

vsremote-0.2.0-cp315-cp315-win_amd64.whl (61.1 kB view details)

Uploaded CPython 3.15Windows x86-64

vsremote-0.2.0-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (97.8 kB view details)

Uploaded CPython 3.15manylinux: glibc 2.17+ x86-64

vsremote-0.2.0-cp315-cp315-macosx_15_0_arm64.whl (97.3 kB view details)

Uploaded CPython 3.15macOS 15.0+ ARM64

vsremote-0.2.0-cp314-cp314-win_amd64.whl (61.1 kB view details)

Uploaded CPython 3.14Windows x86-64

vsremote-0.2.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (97.9 kB view details)

Uploaded CPython 3.14manylinux: glibc 2.17+ x86-64

vsremote-0.2.0-cp314-cp314-macosx_15_0_arm64.whl (97.2 kB view details)

Uploaded CPython 3.14macOS 15.0+ ARM64

vsremote-0.2.0-cp313-cp313-win_amd64.whl (61.6 kB view details)

Uploaded CPython 3.13Windows x86-64

vsremote-0.2.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (97.7 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

vsremote-0.2.0-cp313-cp313-macosx_15_0_arm64.whl (152.2 kB view details)

Uploaded CPython 3.13macOS 15.0+ ARM64

vsremote-0.2.0-cp312-cp312-win_amd64.whl (61.6 kB view details)

Uploaded CPython 3.12Windows x86-64

vsremote-0.2.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (98.2 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

vsremote-0.2.0-cp312-cp312-macosx_15_0_arm64.whl (153.8 kB view details)

Uploaded CPython 3.12macOS 15.0+ ARM64

File details

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

File metadata

  • Download URL: vsremote-0.2.0.tar.gz
  • Upload date:
  • Size: 128.4 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.0.tar.gz
Algorithm Hash digest
SHA256 8d1fd8711701f228965b622c7a59297cdf1f2f0dd9b0846e27ce2747177d96ef
MD5 dbdc71299d36843d4ff1152affc5a329
BLAKE2b-256 abae2c9ff6ce1573ffa38f81a0ca35c1db20015e8c328a1644f74f64aa6f403a

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.0.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.0-py3-none-any.whl.

File metadata

  • Download URL: vsremote-0.2.0-py3-none-any.whl
  • Upload date:
  • Size: 43.9 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.0-py3-none-any.whl
Algorithm Hash digest
SHA256 8d96f91a9bc38f61ba28e6350c0fc365d205e3785647d8541c024f6971a71d1d
MD5 73478fa938b8869ed7f4c7cb7d7997fb
BLAKE2b-256 24d9c8a5e53c851a7eb8793772066d47a7bc430b3cba8fafdd5b85d2feafe825

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.0-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.0-cp315-cp315-win_amd64.whl.

File metadata

  • Download URL: vsremote-0.2.0-cp315-cp315-win_amd64.whl
  • Upload date:
  • Size: 61.1 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.0-cp315-cp315-win_amd64.whl
Algorithm Hash digest
SHA256 02b8c086c370bf53ef098f348add4bc1a30b290e7afd68fe869b936c8ba904d1
MD5 3fb8b4ffcfdda30796ffd593217e09dc
BLAKE2b-256 ebd8bd1a3460b3e1b2af88c4c1b2ae77ddc249ed4ec531119c0b4f41a9afdb76

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.0-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.0-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for vsremote-0.2.0-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 2ed466ecfa0ed17f1877e25bd0c7c07c53df6c1712361f6e4b4cdf425b7c34c6
MD5 e48fb5a5a21ef0c046cbefa88e9df017
BLAKE2b-256 574eada502a9451e3c9a35102d8a57fb222d8ab30d9d777a35cacd4762e7ead2

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.0-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.0-cp315-cp315-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for vsremote-0.2.0-cp315-cp315-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 9b1a8b62862059a84fd3644fa125ca2701d232cf66e4dc437bdcbae4294f0c4e
MD5 33c1a6844d2608f332ebf1052b84b507
BLAKE2b-256 6ac6266349b4415e9c1f0afdb1dcae601b9cb8439daa7cfd39b0a0f33404fe52

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.0-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.0-cp314-cp314-win_amd64.whl.

File metadata

  • Download URL: vsremote-0.2.0-cp314-cp314-win_amd64.whl
  • Upload date:
  • Size: 61.1 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.0-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 09729a786e0cb9e1cd6446a2e5a9122b53543f7b194476bb9205e79531eef3d4
MD5 a911423b5ce17d03684610ddc1bbe9ea
BLAKE2b-256 bc3998e4126c9fe718e752953006d517e05480e26bfdc282632916526a208d10

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.0-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.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for vsremote-0.2.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 5f1f45573f3cc6e3f2e83fd89586ed94dbe45b7c7a57fd43b2091710ea5eaf09
MD5 2ec899ca3af59bbe31a29659384a9fab
BLAKE2b-256 e7e0bce63a2160986a33e40a9bfd852188f8e3d51af19aef7a1311458964c0f6

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.0-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.0-cp314-cp314-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for vsremote-0.2.0-cp314-cp314-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 237f5d89459e98c2f19c7c77c1b6206225dc2b7db859e05c00d25650919da262
MD5 ccd737080af8c3c290f0ab4a5518e7f6
BLAKE2b-256 3ddbb08b9e9b99196f65785300b727e34093786e64956acb2b5767f7052d3653

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.0-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.0-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: vsremote-0.2.0-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 61.6 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.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 c13071ea4b546f52714dca69948f322df154e406c9ac85d6dd8c9e90d6534d25
MD5 358ce06b5e4e275744ec54a84756122f
BLAKE2b-256 c7365e683c2dc9e331bddf45d9697e4662b2e416c77e10fcc85feb8491520ca3

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.0-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.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for vsremote-0.2.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 b3df70de4b8efc0c12e0180a067c5fde131c93490fbb10618ceb588095673fd3
MD5 f041cf41108a224d1b7639d7ae4f4814
BLAKE2b-256 7152b856a2eec5aa2fd1842209b46a04ff378b14ca7f7886263c28128aff5ef6

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.0-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.0-cp313-cp313-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for vsremote-0.2.0-cp313-cp313-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 1bc1c6968976320497abd2406bb0e75fc7a85feeb3e195d427e35fc0906a78bb
MD5 30425b17082ff2b170caa755b5719e69
BLAKE2b-256 a7e2e3a3cb9ceac0e3d1adcec29f9c69ca9730c46068e8b609a52f295fb3c793

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.0-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.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: vsremote-0.2.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 61.6 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.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 ad884cedc890c5d68b6a7bf848b2d095dcd4daa9fec45d11829a8e4683410c5c
MD5 04daf3060326249578cae0d3f63a2178
BLAKE2b-256 cac18b68f7823e257a2a93c07239fa6b5ac88a9bf1eea76f8a6218fb02b6b660

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.0-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.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for vsremote-0.2.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 4253fdeb9cdbfeceb5209c32195c66d45e2dc3f7048ea4cf512767930cb50d82
MD5 fb53ce62115ac368bcb32aed60254471
BLAKE2b-256 71dd50b8d9b53c28eab275fe425835b1b89a437cb46a76fc4077bf3bca5cc69a

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.0-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.0-cp312-cp312-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for vsremote-0.2.0-cp312-cp312-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 7fcad1614f8381899ce2d1080ed23ecdf9f522482f0c4b95ba45ece6d601dbe0
MD5 632fdbba450cfae485731e65349c0aae
BLAKE2b-256 cc41b7b217636c1ff7375a0dc0b8415f9fb4b9c98228e27442df71ef7b786f8b

See more details on using hashes here.

Provenance

The following attestation bundles were made for vsremote-0.2.0-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

0.2.2

14 files

0.2.1

14 files

This release

0.2.0 This release

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