vncx 1.0.1

A lightweight VNC client library for Python

vncx

轻量级 Python VNC 客户端库，支持标准 RFB 协议、键盘鼠标操作、区域截图功能。

特性

• ✅ 支持标准 RFB 3.8 协议
• ✅ 同步 TCP 连接，逻辑简单可靠
• ✅ 全屏截图和区域截图
• ✅ 返回 OpenCV 可用的 numpy 数组
• ✅ 鼠标移动、点击、滚轮操作
• ✅ 键盘按键输入
• ✅ 依赖最少（仅 numpy 和 opencv-python）
• ✅ 跨平台支持（Windows、macOS、Linux）

安装

pip install vncx

或者从源码安装：

pip install -e .

快速开始

from vncx import VNCClient

# 创建客户端
client = VNCClient("127.0.0.1", 5900)

# 连接到 VNC 服务器
client.connect()

# 截取全屏
img = client.capture_screen()
print(f"Screen shape: {img.shape}")

# 保存截图
client.save_img("screen.png")

# 截取指定区域
region_img = client.capture_region(100, 100, 300, 200)

# 鼠标操作
client.mouse_move(200, 200)  # 移动到坐标 (200, 200)
client.mouse_click(1)        # 左键点击

# 键盘操作
client.key_press(ord('H'))   # 按 H 键
client.key_press(ord('i'))   # 按 i 键

# 断开连接
client.disconnect()

API 参考

VNCClient

__init__(host: str = "127.0.0.1", port: int = 5900, password: Optional[str] = None)

创建 VNC 客户端实例。

connect()

连接到 VNC 服务器并进行 RFB 协议握手。

disconnect()

断开与 VNC 服务器的连接。

capture_screen() -> np.ndarray

截取全屏并返回 numpy 数组 (height, width, 3) RGB。

capture_region(x: int, y: int, width: int, height: int) -> np.ndarray

截取指定区域并返回 numpy 数组。

save_img(filename: str)

保存当前 framebuffer 为图片文件。

mouse_move(x: int, y: int)

移动鼠标到指定坐标。

mouse_click(button: int)

点击鼠标按键 (1=左键, 2=中键, 4=右键)。

mouse_down(button: int)

按下鼠标按键。

mouse_up(button: int)

释放鼠标按键。

mouse_roll_up()

鼠标滚轮向上。

mouse_roll_down()

鼠标滚轮向下。

key_down(key_code: int)

按下键盘按键。

key_up(key_code: int)

释放键盘按键。

key_press(key_code: int)

按下并释放键盘按键。

开发

项目结构

vncx/
├── vncx/           # 核心库
│   ├── __init__.py
│   ├── client.py   # VNCClient 主类
│   └── protocol.py # RFB 协议相关
├── tests/          # 单元测试
├── examples/       # 使用示例
├── setup.py        # 安装配置
├── requirements.txt # 依赖列表
└── README.md       # 项目文档

运行测试

python -m pytest tests/

运行示例

python examples/basic_usage.py

依赖

• Python 3.7+
• numpy
• opencv-python

协议支持

• RFB 3.8 协议
• 安全类型：无认证、VNC 认证
• 编码：RAW 编码

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！