Metadata-Version: 2.4
Name: py-scrcpy-sdk
Version: 0.1.2
Summary: Minimal scrcpy-based Android screen and control SDK for Python
Author: OpenCode
License-Expression: MIT
Project-URL: Homepage, https://github.com/183181731/py-scrcpy-sdk
Project-URL: Repository, https://github.com/183181731/py-scrcpy-sdk
Project-URL: Issues, https://github.com/183181731/py-scrcpy-sdk/issues
Keywords: android,adb,scrcpy,automation,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: av>=12.0.0
Requires-Dist: imageio>=2.34.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: opencv-python>=4.9.0.80
Dynamic: license-file

# py-scrcpy-sdk

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

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

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

## 安装

要求：

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

安装：

```bash
pip install py-scrcpy-sdk
```

本地开发：

```bash
pip install -e .
```

## 快速开始

```python
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

```python
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 作为证据
