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 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 public 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: Enable CurveZMQ (Curve25519) encryption and pre-shared token authentication:

    # Server
    vsremote serve script.vpy --address tcp://192.168.1.100:5555 --curve --auth-token "secret"
    
    # Client
    vsremote info --address tcp://192.168.1.100:5555 --curve-server-key "<SERVER_PUBLIC_KEY>" --auth-token "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.1.0.tar.gz (122.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.1.0-py3-none-any.whl (38.8 kB view details)

Uploaded Python 3

vsremote-0.1.0-cp315-cp315-win_amd64.whl (55.8 kB view details)

Uploaded CPython 3.15Windows x86-64

vsremote-0.1.0-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (92.7 kB view details)

Uploaded CPython 3.15manylinux: glibc 2.17+ x86-64

vsremote-0.1.0-cp315-cp315-macosx_15_0_arm64.whl (92.1 kB view details)

Uploaded CPython 3.15macOS 15.0+ ARM64

vsremote-0.1.0-cp314-cp314-win_amd64.whl (55.8 kB view details)

Uploaded CPython 3.14Windows x86-64

vsremote-0.1.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (92.7 kB view details)

Uploaded CPython 3.14manylinux: glibc 2.17+ x86-64

vsremote-0.1.0-cp314-cp314-macosx_15_0_arm64.whl (92.0 kB view details)

Uploaded CPython 3.14macOS 15.0+ ARM64

vsremote-0.1.0-cp313-cp313-win_amd64.whl (56.3 kB view details)

Uploaded CPython 3.13Windows x86-64

vsremote-0.1.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (92.5 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

vsremote-0.1.0-cp313-cp313-macosx_15_0_arm64.whl (147.1 kB view details)

Uploaded CPython 3.13macOS 15.0+ ARM64

vsremote-0.1.0-cp312-cp312-win_amd64.whl (56.4 kB view details)

Uploaded CPython 3.12Windows x86-64

vsremote-0.1.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (93.1 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

vsremote-0.1.0-cp312-cp312-macosx_15_0_arm64.whl (148.6 kB view details)

Uploaded CPython 3.12macOS 15.0+ ARM64

File details

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

File metadata

  • Download URL: vsremote-0.1.0.tar.gz
  • Upload date:
  • Size: 122.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.1.0.tar.gz
Algorithm Hash digest
SHA256 10b3fb1cfb7357a41b7aa7875c48a50b748236f585cff465b00de57148a2593a
MD5 66dd6a721c26067bd53e926ad8e0af73
BLAKE2b-256 7f17e6e07c7f8aa2e83b9c2f855eb7319dd92dff084bfcd6b718bd5b8a089ab8

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: vsremote-0.1.0-py3-none-any.whl
  • Upload date:
  • Size: 38.8 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.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 1825fb2c6d86c8fb09356538fe4a94988712fe52899c9beb7a8d8c7aa3e57638
MD5 746d3d79fca7130431262c3b42889063
BLAKE2b-256 0c1a64093609b4a0ca153fffcba7be7ffe2d766f03600e4e163020ee6cbbe93d

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: vsremote-0.1.0-cp315-cp315-win_amd64.whl
  • Upload date:
  • Size: 55.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.1.0-cp315-cp315-win_amd64.whl
Algorithm Hash digest
SHA256 40856c042f089827fc7b4d7a4768fd06d2390a2aa34de5580526859158ce39e8
MD5 71d0614c256a64821b45dfce71ec8d06
BLAKE2b-256 0c2055d52ddc6d1c0e1a1a6e7b16f8ce231e35339dea28283aacdb5c2a565052

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.1.0-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 89eb610ee1a83385caa40b7ba10c300ab538ec20aa4def838706412c08f70d65
MD5 deeac895a14b586b9608a512fdeb9a14
BLAKE2b-256 3f7660dd93dbd22a04048b40e7b8d1e8cd2ed7a694aab162fab6bd978bb04c7a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.1.0-cp315-cp315-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 5ba8f5cdcfe4d339ad9946541e5891dd7a1c8f304e535fab52999dfd73ea1b0b
MD5 26a9841b6c8a14bd927cff1825312c53
BLAKE2b-256 75087ddc5eaa5ec9a78e89e707303c392bc5c555ea51708689e283cb5fc78416

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: vsremote-0.1.0-cp314-cp314-win_amd64.whl
  • Upload date:
  • Size: 55.8 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.1.0-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 c8dd49d449fefcbdfa2a7778d4560741fd789589415e9724b230f92dc4c604d6
MD5 792d16869f99140783dc1f81727f0d86
BLAKE2b-256 d9c1cf0b2abe1542ec823b0899c7ff484c7d1380c2b69fbdb90a132e69b19a83

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.1.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 62efef74ab41531b31fed8506b3bd7f87e7d32ae2956754b4a2a210987a362b6
MD5 91d4dd1b159cf9a7dcd83c6e27ee515b
BLAKE2b-256 7a215be602a14c61f44b9898bbf0dd664a08c9623b0b67f0b927a82254bba8a8

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.1.0-cp314-cp314-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 8abd2f0d80ede6be0a0cf9ca2fdfb25dd40f28b7123a009c7d5777efe11588ca
MD5 dd65f8e680acde7b2ae4e80e8ce7ca86
BLAKE2b-256 7a97c1270d2f76e2adb63f73b3f76db603b5e737f7bfa77e5e167fc5798d3cd5

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: vsremote-0.1.0-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 56.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.1.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 21d814626f90d6bb877356fdab287a40bfdafececcdd66bf3df1bb488cbf7f3f
MD5 186231e0e097e9835d518c88f88548e1
BLAKE2b-256 97806fe514f4e8602e808ae2e44b283c7af9443de81c3c0be429737a7a021058

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.1.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 3252e2f25a15804891d4d25390ac7da7268b5af54c1392143e9dacf63e677216
MD5 6aaa1ab26832c2c25e733ed181e3f84b
BLAKE2b-256 5afea19683657a22afb462a179b31d25fde7c5990b11db430614643174d4ac9d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.1.0-cp313-cp313-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 506ea6972d218d126d808cc5c858c8dffff081ab9b39a981807fd0869d0f61ad
MD5 6dcc9ed0156e792aa5f99b62f78611db
BLAKE2b-256 c1b8c11661599e553a0dd158a92d9e1d713724a55e63eae09fae174180502377

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: vsremote-0.1.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 56.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.1.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 44e3002e92b3a0f1f43c99c61aba4708660430c7c6f9716857633e58fea3a303
MD5 f1165aa87e7d2b073a592593c4bfa6f2
BLAKE2b-256 e5fc31a614f10a938d3a5973985d29cb118f42c0a8027676e9307f72fef365fe

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.1.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 afba8eee95c7d3a3e2812b3b8469e3fa3e97670e09261546339391180a923669
MD5 fb7de1e9454134bba3d814f734d2c7d9
BLAKE2b-256 c550929c9b0f561bb43aa6bf59cbc3b30f199a484be4576b6dbfcee607bc2026

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.1.0-cp312-cp312-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 5704ac8bef723295f53e92261497cac791b1461fc12a02aa625df9e822560abd
MD5 333592f2411a333715a65a2b1f6bd482
BLAKE2b-256 47ba1b5ad5e8f4d1b1db901483f23eb10c973595d12af6fcfbc6e961313b4edb

See more details on using hashes here.

Provenance

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

0.2.0

14 files

This release

0.1.0 This release

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