py-scrcpy-sdk 0.1.1

Minimal scrcpy-based Android screen and control SDK for Python

py-scrcpy-sdk

一个基于 scrcpy-server 通信协议提纯出来的最小化 Python SDK，聚焦三件事：

• 实时获取指定 Android 设备画面
• 保存当前画面为 jpg，录制片段为 gif
• 向设备发送点击、长按、拖动、文本、按键、滚动等操作

这个项目直接复用 adb + scrcpy-server + Python socket 的链路，不依赖桌面版 scrcpy 窗口截图。

安装

要求：

• Python 3.10+
• 本机可执行 adb
• Android 设备已开启 USB 调试

安装：

pip install py-scrcpy-sdk

本地开发：

pip install -e .

快速开始

from py_scrcpy_sdk import ScrcpyClient, ScrcpyConfig

config = ScrcpyConfig(serial="YOUR_DEVICE_SERIAL")

with ScrcpyClient(config) as client:
    frame = client.wait_until_ready()
    print(frame.shape)

    client.save_screenshot("artifacts/screen.jpg")
    client.save_gif("artifacts/demo.gif", seconds=3, fps=8)

    client.tap(300, 600)
    client.long_press(300, 900, duration=1.2)
    client.drag(200, 1000, 800, 1000, duration_ms=400)

常用 API

from py_scrcpy_sdk import ScrcpyClient, ScrcpyConfig, list_devices

print(list_devices())

client = ScrcpyClient(ScrcpyConfig(serial="YOUR_DEVICE_SERIAL"))
client.start()

frame = client.get_frame()
for next_frame in client.frames():
    # 实时处理视频帧
    pass

def on_frame(frame):
    print(frame.shape)
    return True

client.listen(on_frame)

listener = client.start_frame_listener(on_frame)
listener.join(timeout=3)

client.show()  # OpenCV 窗口预览，q / Esc 退出
client.save_screenshot("screen.jpg")
client.save_gif("clip.gif", seconds=5, fps=10)

client.tap(100, 200)
client.long_press(100, 400, duration=1.0)
client.drag(100, 500, 900, 500)
client.swipe(100, 900, 900, 900)
client.scroll(500, 1200, vertical=12)
client.input_text("hello")
client.press_key(4)  # Android BACK

client.stop()

设计说明

• 仅保留 SDK 必需能力，不包含 CLI、模板识别、服务编排等 POC 功能
• 当前固定使用 h264 解码，便于稳定接入 PyAV
• 默认优先走 adb reverse，失败后自动回退到 adb forward
• 触控坐标以当前解码后的视频帧分辨率为基准

回调式监听

• listen(callback)：阻塞式逐帧回调，适合当前线程直接消费画面
• start_frame_listener(callback)：后台线程持续回调，适合嵌入其他系统
• 回调返回 False 时可自动停止监听

可运行示例见 examples/basic.py

交互式预览示例

• examples/interactive_control.py
• 基于 Tkinter 实时显示设备画面，不依赖 OpenCV HighGUI
• 鼠标左键单击发送点击，左键拖动发送滑动
• 键盘 s 保存 jpg 截图，g 保存 gif，q / Esc 退出

包含内容

• 内置 scrcpy-server v3.3.4
• 安装后可直接被其他 Python 项目 pip install 引用

典型使用场景

• 自动化项目中实时拉取设备画面做识别
• 识别后回写点击、拖动、长按等控制动作
• 保存调试截图和回放 GIF 作为证据