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.1.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.1-py3-none-any.whl (43.7 kB view details)

Uploaded Python 3

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

Uploaded CPython 3.15Windows x86-64

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

Uploaded CPython 3.15macOS 15.0+ ARM64

vsremote-0.2.1-cp314-cp314-win_amd64.whl (60.8 kB view details)

Uploaded CPython 3.14Windows x86-64

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

Uploaded CPython 3.14macOS 15.0+ ARM64

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

Uploaded CPython 3.13Windows x86-64

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

Uploaded CPython 3.13macOS 15.0+ ARM64

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

Uploaded CPython 3.12Windows x86-64

vsremote-0.2.1-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.1-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.1.tar.gz.

File metadata

  • Download URL: vsremote-0.2.1.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.1.tar.gz
Algorithm Hash digest
SHA256 3bd0a1f17d499cced30e7064ab800dec09cfb517d8ee419dab361a83d44e4827
MD5 7b0af96c3693af0ae802c7d2e797a5a5
BLAKE2b-256 b27d90c4f3c58629085b429cc9319c9320baae28538e9c9d8029a5ca0b5a1ae4

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: vsremote-0.2.1-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.1-py3-none-any.whl
Algorithm Hash digest
SHA256 ea187eef6c40ec343ddddad4925a03879879411a8347ae32a5c74a1ccae96e26
MD5 971589c62b57e9efcf08083792e91fd0
BLAKE2b-256 2e67c76d286d3f7d1af33221464343347550d0a542e8d662855552d748899718

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: vsremote-0.2.1-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.1-cp315-cp315-win_amd64.whl
Algorithm Hash digest
SHA256 a2b9aea3f39b5f641ea427cdba8fe0b4c3d471a6131370876286664c7269e03b
MD5 260eb5d4fd96380df3da1b2f709d95e2
BLAKE2b-256 c11968d5ff096756267681e15c14c95f65b164b87534b81903b1d44d7cbdcde7

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.2.1-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 ec46889a4fc3bdb9478d5ce8f9d82bc5d02e91ac0cbfdf1079c398aa249c18d6
MD5 8d06bc80a4f40e4311864733137c3511
BLAKE2b-256 c5a49ce689283a278636f2c3f95b2e098a7f4aad1f88c14ace1dac9a83b2bfbc

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.2.1-cp315-cp315-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 cdd6532581b93a111273e34bdf60d50ca0219b383541042f029b1a5f472487a9
MD5 f93700bc056c8c8c62a7d0bf48772a33
BLAKE2b-256 5ec74b6a080042ba296b08feb96771dbba99c041b2df2e0a5d51700f14305752

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: vsremote-0.2.1-cp314-cp314-win_amd64.whl
  • Upload date:
  • Size: 60.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.2.1-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 f4e3e6cff70845b5aa4b4178e979f396d334db2a88e95f682b0a52ac041a1c19
MD5 0343bca4d83776d1fea24fba43d0ce37
BLAKE2b-256 d9a278f20f6eff2f46c4153834d6d907464b8d9f629720b9511054d3418fb0b0

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.2.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 ca28b5aaccf637b8915d1074eec195fe9e6bf293e40137fd9f644a4a182a6b6d
MD5 caea95a12ba92e3904e0232cc63f975b
BLAKE2b-256 b30922ed6c6146e49f38090e234b2a27c958d03469c0206e449672a425cb38ab

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.2.1-cp314-cp314-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 61a55863eb5d916e55d52763cecf08424bfa732e951608bf60b3ce5b2ab1b98a
MD5 e08e73106dc00887db784fe5cee9dae7
BLAKE2b-256 d26af18570a997cdfaa438bff60de6347fc15cae44fad5cc915a6009f4e4c9d8

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: vsremote-0.2.1-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.1-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 9e531628645bb95f6e71a81d83f561c854668082ec4d1c7646b7db015485f258
MD5 d4952bef14348ba9ba594929a54b698b
BLAKE2b-256 fd1441fc917a1076beb18b674fcdae79a69b52df537c5f9b1cde54dba1194a07

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.2.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 f5fb6ee66a74f8a18638c71cad729f082e62f54102062387329e5230570989ed
MD5 1897cbcf10c1f3f4fbe5972feb78b757
BLAKE2b-256 b3452feb6fbbe03bc843eb0c87475dab1dd8b983b51bca44224f9febe8ef5e09

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.2.1-cp313-cp313-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 d3c3bb81db19ca9c33833fcf5f540b87fdd2ef4c880f16d4a843d81fdaa11280
MD5 091f005839a19e23a568abb2f6fc98c8
BLAKE2b-256 bf17db94e1e4bba99d812fd7c374d5b419acf9e72dd0f1dbb5b66eca8473a704

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: vsremote-0.2.1-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.1-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 1a1665bb6321f27fd975ea6281a7018826c889a5efe2f286ba6814a289b87669
MD5 7e1b42d92f66a76c957338bdcdd255ce
BLAKE2b-256 2434a3e5209729d49501fcc4a94e43222f9f6ab174a6fa164a6e60f714534529

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.2.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 04c91286a9ff22bcf10d4520bbffe15e6456c38bebe0fd824d53c3364b5d73c6
MD5 2513f58efeb42e52eebe299fedddc951
BLAKE2b-256 9a6286eb0639b13f051e4131a83536a9170ac42c1b3259e3d0aac8dae7f1928f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for vsremote-0.2.1-cp312-cp312-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 560ee7511ccd84401662b45bf8666206f4f3859f5c8dd4d25f584e88fb8b0c11
MD5 dc289546fb57458f3c432fb75f9c8359
BLAKE2b-256 5fc58da0993b7544fe0b7cce1c43dcde2fa2be66698b0803a485d24d50189fb4

See more details on using hashes here.

Provenance

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

This release

0.2.1 This release

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