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.3.tar.gz (129.0 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.3-py3-none-any.whl (43.7 kB view details)

Uploaded Python 3

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

Uploaded CPython 3.15Windows x86-64

vsremote-0.2.3-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.3-cp315-cp315-macosx_15_0_arm64.whl (97.1 kB view details)

Uploaded CPython 3.15macOS 15.0+ ARM64

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

Uploaded CPython 3.14Windows x86-64

vsremote-0.2.3-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.3-cp314-cp314-macosx_15_0_arm64.whl (97.0 kB view details)

Uploaded CPython 3.14macOS 15.0+ ARM64

vsremote-0.2.3-cp313-cp313-win_amd64.whl (61.4 kB view details)

Uploaded CPython 3.13Windows x86-64

vsremote-0.2.3-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.3-cp313-cp313-macosx_15_0_arm64.whl (152.0 kB view details)

Uploaded CPython 3.13macOS 15.0+ ARM64

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

Uploaded CPython 3.12Windows x86-64

vsremote-0.2.3-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.3-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.3.tar.gz.

File metadata

  • Download URL: vsremote-0.2.3.tar.gz
  • Upload date:
  • Size: 129.0 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.3.tar.gz
Algorithm Hash digest
SHA256 e6791be97feebb91a9ccb230c849d297c2d7d04c5da5121069ffcd43d0c63da0
MD5 9ab651a3658f7bf5e8c5dbb4f47a33e5
BLAKE2b-256 e3134686d47b45a0546f71dd1356736a1cb1ed1997cf07205f3b203dd707e59e

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: vsremote-0.2.3-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.3-py3-none-any.whl
Algorithm Hash digest
SHA256 e0f2854a03231a5c5b8d9cee5bddf278ca0364a7076385f35676b52afc549f6b
MD5 c952e28dd76554f5cbb11637112b9508
BLAKE2b-256 0944df3b1c847db27481c83f7b93a78102c724a7d4e97af453d8b36e0d692035

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: vsremote-0.2.3-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.3-cp315-cp315-win_amd64.whl
Algorithm Hash digest
SHA256 e4f170816d48c987e9ea17c2227ea222ccf1bebeff2294db6641c2ff57aa2a3c
MD5 ac8c271d05ab66d5657514f2b550df8b
BLAKE2b-256 a76daa7a42a2d6d8b102466ba6305d1d22c5a1eabe30096ed3d1c81c29742b60

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.2.3-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 f2e84beaa2c5376977c611aa8e0291fbae863b70a4272f45d6ee65ae0fa6b504
MD5 b0994253eee3d3fed5db2bd06c263ca6
BLAKE2b-256 ff610d9e5c8d6ec05748082286d6b8fbd16dc29cb35865faff632427f649b778

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.2.3-cp315-cp315-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 373db1e58c1baed10d1c4e674765ee5d7da7acddf99449a80812bbdf02ffc5a8
MD5 fa8d6e862f34d24c7448bc9f4e8c090c
BLAKE2b-256 328d12ba848fa38d632d184a8449652c20aaf26612bb543bfa34e314afd4839a

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: vsremote-0.2.3-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.3-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 58937f0317597e60016935a5fa237105ad825d16355f8b67c9513def8def5beb
MD5 36674f779a3cdd2b75aace2d761c03e6
BLAKE2b-256 4fca5954212ff5b8d977894c57d7412ad5b82ab0f770a8f62aa27f7a133578e5

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.2.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 f5e7f492aac9023d66b122f87d20c6f8c8f30960e383f537327f5bf299674277
MD5 d29b087a1aa2505b8778bbe1992039db
BLAKE2b-256 0cf29d5be95a4fe105de8b58c0161680f81100eded33778bdef7d35238e4b15d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.2.3-cp314-cp314-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 97308fa1be03d9525972d31446020115173d6393247417069ff333f9905dc870
MD5 b4c42dc8df61ca20454a186e272e03d7
BLAKE2b-256 c640a5a289b7e6a83661b965879f4ea7504304f2166a87fc6f0dd44717c7f640

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: vsremote-0.2.3-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 61.4 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.3-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 c1a2015031a74f1e5c404c7ba03c7767bd7a66b4fa71a3335889e1b8b3375ab5
MD5 66033326b6e312d19a7d4c35a5118d66
BLAKE2b-256 7c9710613f9906130b37af4e310f22652d6824998c22165cb3faa245dbfbf795

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.2.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 ff8ca6ac4f5561499c5e07fd1f85316e408872cb4b9ab7f42b169bd30d71ad55
MD5 6430dc9482f4f70421ca6fb73cd903b7
BLAKE2b-256 d884893d61e3fa5850496afb4187e6913e9b972fa49146dfe0778a735105f383

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.2.3-cp313-cp313-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 9a70ebd9ec6790884b1982e58279929ab12e25de2c33982a0cf4ae1f44c41ccc
MD5 5a87246934b409f9d62065ad1c6d4a32
BLAKE2b-256 2a5ead667eccc35f033745047fd0aed4c027e1e26396da35556ab149392e837c

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: vsremote-0.2.3-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.3-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 9efa6e568b5cb3ec9514120f081532a98a22a675c471983f1f7cf394529bd49d
MD5 c2ab6a31982a5d697468e784c3e756c6
BLAKE2b-256 1a25bba707966ec5274688df60312d05f733f1de3b84c630e386a4a8942d106b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.2.3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 a547996fc05183b07d28f7244c9ace7884ed79fa879908bd1b9b57bd90541f0f
MD5 ea2e9a6644c05e19cf986c673cf182a8
BLAKE2b-256 c43123dd04fa9a75bd96076384760ac1ba0c5ddf4f1f8f0935cafabeb92424dc

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.2.3-cp312-cp312-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 70732090df360f0a1035d229c47f394c4db2fb8b40a0babdf3912bc0fe64dfa2
MD5 90914a295dc2be3148302698e47d1850
BLAKE2b-256 02d7646921df369f03112263cb76f83d05aca6d53f1bdb70291a82ca3348bb61

See more details on using hashes here.

Provenance

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

This release

0.2.3 This release

14 files

0.2.2

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