AsyncVNC: Asynchronous VNC for Python

AsyncVNC is a Python package which provides an asynchronous client implementation of the VNC (RFB) protocol on top of the asyncio framework.

import asyncio, asyncvnc

async def run_client():
    with asyncvnc.connect('localhost', 5900, 'username', 'password') as client:
        client.keyboard.write('hello world!')

asyncio.run(run_client())

Features

• Full support for keyboard, mouse, video and clipboard updates.

  • The frame buffer can be exported as an RGBA numpy array.

  • Keyboard keys are specified by name or character.

• Compatibility with traditional VNC servers (RealVNC, TightVNC, TigerVNC, etc).

  • Including unauthenticated connections.

  • Including password authentication with Triple DES.

• Compatibility with the built-in macOS Remote Desktop server.

  • Including username/password authentication with 2048-bit RSA keys and 128-bit AES.

  • Connects to the desktop, not the login screen.

• Detection of multi-head frame buffer data using a novel algorithm.

• Support for tunneling VNC over SSH with AsyncSSH.

• Support for image data compression with zlib.

Installation

This package requires Python 3.7+.

Install AsyncVNC by running:

pip install asyncvnc

Connecting to a server

This snippet connects to a local unauthenticated VNC server, prints information, and disconnects:

import asyncio, asyncvnc

async def run_client():
    async with asyncvnc.connect('localhost') as client:
        print(client)

asyncio.run(run_client())

To log in to a macOS server, supply username and password arguments:

async with asyncvnc.connect('localhost', username='user123', password='h4x0r'):
    ...

For traditional authenticated VNC servers, the password argument is required but not username.

Warning

Traditional VNC authentication is woefully insecure. For best results, configure your VNC server to listen only on 127.0.0.1. If you need external access, use an SSH tunnel.

To tunnel VNC over SSH, use the AsyncSSH package (after which this package is modelled):

import asyncio, asyncssh, asyncvnc

async def run_client():
    async with asyncssh.connect('myserver') as conn:
        async with asyncvnc.connect('localhost', opener=conn.open_connection) as client:
            print(client)

asyncio.run(run_client())

Sending events

Keyboard and mouse objects provide context managers for holding down keys and buttons:

with client.keyboard.hold('Ctrl'):
    ...

with client.mouse.hold():
    ...

The keyboard has methods for pressing keys and writing text:

client.keyboard.press('Ctrl', 'c')  # keys are stacked
client.keyboard.write('hi there!')  # keys are queued

The mouse has methods for moving the cursor and clicking:

client.mouse.move(100, 200)
client.mouse.click()
client.mouse.right_click()
client.mouse.scroll_up()

Taking a screenshot

To retrieve an image from the VNC server and save it as a PNG file:

import asyncio, asyncvnc
from PIL import Image

async def run_client():
    async with asyncvnc.connect('localhost') as client:
        # Retrieve pixels as a 3D numpy array
        pixels = await client.screenshot()

        # Save as PNG using PIL/pillow
        image = Image.fromarray(pixels)
        image.save('screenshot.png')

asyncio.run(run_client())

The macOS VNC server composites attached monitors/screens into a single frame buffer. It does not send updates for unoccupied regions; we can use this information to detect screens:

pixels = client.video.as_rgba()
for screen in client.video.detect_screens():
    screen_pixels = pixels[screen.slices]

API reference

asyncvnc.connect(host: str, port: int = 5900, username: str | None = None, password: str | None = None, host_key: RSAPublicKey | None = None, opener=None)

Make a VNC client connection. This is an async context manager that returns a connected Client instance.

class asyncvnc.Client

VNC client.

clipboard: Clipboard

The shared clipboard.

keyboard: Keyboard

The virtual keyboard.

mouse: Mouse

The virtual mouse.

video: Video

The video buffer.

host_key: RSAPublicKey | None

The server’s public key (Mac only)

async read() → UpdateType

Reads an update from the server and returns its type.

async drain()

Waits for data to be written to the server.

async screenshot(x: int = 0, y: int = 0, width: int | None = None, height: int | None = None)

Takes a screenshot and returns a 3D RGBA array.

class asyncvnc.UpdateType

Update from server to client.

VIDEO = 0

Video update.

CLIPBOARD = 2

Clipboard update.

BELL = 3

Bell update.

class asyncvnc.Clipboard

Shared clipboard.

text: str = ''

The clipboard text.

write(text: str)

Sends clipboard text to the server.

class asyncvnc.Keyboard

Virtual keyboard.

hold(*keys: str)

Context manager that pushes the given keys on enter, and releases them (in reverse order) on exit.

press(*keys: str)

Pushes all the given keys, and then releases them in reverse order.

write(text: str)

Pushes and releases each of the given keys, one after the other.

class asyncvnc.Mouse

Virtual mouse.

hold(button: int = 0)

Context manager that presses a mouse button on enter, and releases it on exit.

click(button: int = 0)

Presses and releases a mouse button.

middle_click()

Presses and releases the middle mouse button.

right_click()

Presses and releases the right mouse button.

scroll_up(repeat=1)

Scrolls the mouse wheel upwards.

scroll_down(repeat=1)

Scrolls the mouse wheel downwards.

move(x: int, y: int)

Moves the mouse cursor to the given co-ordinates.

class asyncvnc.Video

Video buffer.

name: str

Desktop name.

width: int

Width in pixels.

height: int

Height in pixels.

mode: str

Colour channel order.

data: ndarray | None = None

3D numpy array of colour data.

refresh(x: int = 0, y: int = 0, width: int | None = None, height: int | None = None)

Sends a video buffer update request to the server.

as_rgba() → ndarray

Returns the video buffer as a 3D RGBA array.

is_complete()

Returns true if the video buffer is entirely opaque.

detect_screens() → List[Screen]

Detect physical screens by inspecting the alpha channel.

class asyncvnc.Screen

Computer screen.

x: int

Horizontal position in pixels.

y: int

Vertical position in pixels.

width: int

Width in pixels.

height: int

Height in pixels.

property slices: Tuple[slice, slice]

Object that can be used to crop the video buffer to this screen.

property score: float

A measure of our confidence that this represents a real screen. For screens with standard aspect ratios, this is proportional to its pixel area. For non-standard aspect ratios, the score is further multiplied by the ratio or its reciprocal, whichever is smaller.