AsyncVNC2: Asynchronous VNC for Python v2¶

https://img.shields.io/badge/source-github-orange

https://readthedocs.org/projects/asyncvnc2/badge/?version=latest&style=flat-square

https://img.shields.io/pypi/v/asyncvnc2?style=flat-square

This project is a spin-off from the AsyncVNC project, which is still maintained by Barney Gale.: AsyncVNC by Barney Gale

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

import asyncio, asyncvnc2

async def run_client():
    with asyncvnc2.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 most popular encoding types for image.
- Raw
- CopyRect
- zlib
- TRLE
- ZRLE

Installation¶

This package requires Python 3.7+.

Install AsyncVNC2 by running:

pip install asyncvnc2

Connecting to a server¶

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

import asyncio, asyncvnc2

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

asyncio.run(run_client())

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

async with asyncvnc2.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, asyncvnc2

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

asyncio.run(run_client())

Selecting list of acceptable encodings¶

RAW encoding is always allowed and supported by all sides. Other encodings from the list of supported asyncvnc2 can be controlled by explicitly allowing them or excluding them from the list. And also by raising the priority.

Allow all supported encodings in default order:

async with asyncvnc2.connect('localhost') as client:
    print(client)
async with asyncvnc2.connect('localhost', encodings=None) as client:
    print(client)
async with asyncvnc2.connect('localhost', encodings=EncList()) as client:
    print(client)

Allow only RAW encoding:

async with asyncvnc2.connect('localhost', encodings=[]) as client:
    print(client)

Allow RAW and only one non-RAW encoding:

async with asyncvnc2.connect('localhost', encodings=Enc.ZLIB) as client:
    print(client)

Allow the encodings list:

async with asyncvnc2.connect('localhost', encodings=[Enc.ZLIB, Enc.TRLE] ) as client:
    print(client)

Rise the priority for the ZLIB encoding:

async with asyncvnc2.connect('localhost', encodings=EncList()+Enc.ZLIB) as client:
    print(client)

Exclude the ZLIB encoding from the allowed encodings list:

async with asyncvnc2.connect('localhost', encodings=EncList()-Enc.ZLIB) as client:
    print(client)

Show the list of the supported encodings:

import asyncvnc2
print(asyncvnc2.EncList())

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, asyncvnc2
from PIL import Image

async def run_client():
    async with asyncvnc2.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¶

asyncvnc2.connect(host: str, port: int = 5900, username: str | None = None, password: str | None = None, host_key: RSAPublicKey | None = None, encodings: list | None = None, opener=None)¶: Make a VNC client connection. This is an async context manager that returns a connected Client instance.

class asyncvnc2.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 asyncvnc2.Clipboard¶

Shared clipboard.

text: str = ''¶: The clipboard text.

write(text: str)¶: Sends clipboard text to the server.

class asyncvnc2.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 asyncvnc2.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 asyncvnc2.Video¶

Video buffer.

name: str¶: Desktop name.

width: int¶: Width in pixels.

height: int¶: Height in pixels.

mode: str¶: Colour channel order.

encodings: list | None = None¶: Allowed encodings list

serial = 0¶: Serial number

data: ndarray | None = None¶: 3D numpy array of colour data.

get_rect(x: int = 0, y: int = 0, width: int | None = None, height: int | None = None) → tuple¶: Crops the rectangle according to the video buffer.

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(x: int = 0, y: int = 0, width: int | None = None, height: int | None = None) → ndarray¶: Returns the video buffer or the selected part of it as a 3D RGBA array.

is_complete(x: int = 0, y: int = 0, width: int | None = None, height: int | None = None)¶: Returns true if the video buffer or the selected part of it is entirely opaque.

detect_screens() → List[Screen]¶: Detect physical screens by inspecting the alpha channel.

class asyncvnc2.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.

class asyncvnc2.StreamZReader¶

aio StreamReader wrapper for zlib

async read(n: int = -1) → bytes¶: Read up to a maximum of n bytes. If n is not provided, or set to -1, read until EOF and return all read bytes. When n is provided, data will be returned as soon as it is available.

async readexactly(n: int) → bytes¶: Read exactly n bytes. Raise an asyncio.IncompleteReadError if the end of the stream is reached before n can be read.

class asyncvnc2.UpdateType¶

Update from server to client.

VIDEO = 0¶: Video update.

BELL = 2¶: Bell update.

CLIPBOARD = 3¶: Clipboard update.

class asyncvnc2.Enc¶

Supported encodings

Default priority order is ZRLE, TRLE, ZLIB, COPY, RAW.

ZRLE = 16¶: ZRLE encoding.

TRLE = 15¶: TRLE encoding.

ZLIB = 6¶: Raw encoding with zlib compession.

COPY = 1¶: CopyRect encoding.

RAW = 0¶: Raw encoding.

classmethod default()¶: Get a list of supported encodings expect RAW.

class asyncvnc2.EncList¶

A list of Supported encodings and the simple operations:

“-” – Exclude from the list

“+” – Add to list or rise priority

EncList() – default encoding list

EncList(Enc.ZLIB) – encoding list with one encoding

EncList([Enc.ZLIB,Enc.TRLE]) – encoding list with two encodings

EncList() - Enc.ZLIB – default encoding list except Enc.ZLIB

EncList() + Enc.ZLIB – default encoding list with hi-priority of Enc.ZLIB