QtScrcpy 技术文档

1. 安装指南

系统要求

• 操作系统：Windows / macOS / Linux
• Android 设备要求：API >= 21 (Android 5.0+)
• 需在设备上启用 [USB调试模式]

下载方式

1. Windows/macOS用户：

   • 访问GitHub Releases页面下载预编译包
   • 解压后即可使用（包含完整ADB环境）

2. Linux用户：

   • Arch Linux可通过AUR安装：yay -Syu qtscrcpy
   • 其他发行版下载预编译包或通过GitHub Actions获取

2. 项目使用说明

基础连接方式

USB连接步骤：

1. 通过USB线连接设备与电脑
2. 打开QtScrcpy程序
3. 点击"刷新设备"按钮
4. 选择检测到的设备
5. 点击"启动服务"

无线连接步骤：

1. 确保手机与PC在同一局域网
2. 先用USB线连接设备
3. 点击"获取设备IP"
4. 点击"启动adbd"
5. 点击"无线连接"
6. 再次刷新设备后选择带IP地址的设备
7. 点击"启动服务"

界面功能说明

• 顶部工具栏：

  • 屏幕旋转/全屏/置顶窗口
  • 截图/录屏控制
  • 剪贴板同步开关

• 侧边控制面板：

  • 分辨率/码率设置
  • 后台录制开关
  • 熄屏模式开关
  • 按键映射管理

3. 项目API使用文档

ADB命令接口

通过"adb命令"输入框可执行非阻塞式ADB命令，例如：

adb shell pm list packages

按键映射API

自定义映射脚本存放在keymap目录，语法规则：

-- 示例：PUBG移动版键位映射
KEYMAP = {
    -- 开火键
    {key="left mouse", action="touch", pos="100,200"},
    -- 移动控制
    {key="WASD", action="rocker", pos="50,50", size="100"}
}

群控指令

通过TCP协议可实现对多设备的批量控制：

import socket
# 连接到QtScrcpy控制端口
sock = socket.socket()
sock.connect(('127.0.0.1', 27183))
sock.send(b'GROUP_ACTION:SCREENSHOT')

4. 项目安装方式

Windows系统安装

1. 下载QtScrcpy-win64-x.x.x.zip
2. 解压至任意目录
3. 双击运行QtScrcpy.exe

macOS系统安装

1. 下载QtScrcpy-mac-x.x.x.dmg
2. 挂载镜像后拖拽应用至Applications文件夹
3. 首次运行需在系统设置中允许未知来源应用

Linux系统编译安装

# 安装依赖
sudo apt install qtbase5-dev libusb-1.0-0-dev ffmpeg
# 克隆仓库
git clone https://github.com/barry-ran/QtScrcpy.git
cd QtScrcpy
# 编译
mkdir build && cd build
qmake ..
make -j4
# 安装
sudo make install

注意事项

1. 首次使用需在Android设备开启USB调试授权
2. 无线连接需要先通过USB完成adbd初始化
3. 高分辨率设备建议设置码率为8-12Mbps
4. 游戏场景建议关闭"剪贴板同步"功能