# AndroidCtrl

**Repository Path**: duzc2/android-ctrl

## Basic Information

- **Project Name**: AndroidCtrl
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-04
- **Last Updated**: 2026-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AndroidCtrl — Android 手机 USB 控制台

通过 USB 调试在电脑上一个窗口内镜像并控制 Android 手机。

- **单窗口镜像**：手机画面直接嵌在控制台窗口中，右侧是图标侧边栏
- **防熄屏**：程序运行期间，手机接入 USB 时屏幕保持常亮；断开或退出后自动恢复原设置
- **方向跟随**：手机横竖屏切换时画面自动跟随（scrcpy 协议原生）
- **窗口缩放**：主窗口自由缩放，画面在窗口内等比缩放留黑边
- **真实触控**：点击、拖拽、长按、滚轮都是 scrcpy 协议原生事件（按下/移动/抬起），
  按住不动即长按，拖拽实时跟手
- **图标侧边栏**：返回 / 主屏 / 多任务 / 通知栏 / 音量±（按住连调）/
  电源（短按熄屏亮屏，**长按触发系统电源长按行为**）/ 截图 / 旋转画面
- **画质即时生效**：切换“高/中/低”时自动用新参数重启镜像连接（约 1~2 秒）
- **一键截图**：直接保存当前帧，无需额外向设备请求
- **麦克风录音**：一键录制手机麦克风，原始 PCM 无压缩音质（可选降噪档位），
  点停止后整段音频保存为 WAV 到 `recordings/`

设备端使用官方 [scrcpy](https://github.com/Genymobile/scrcpy) server（Apache-2.0，
scrcpy-client 包自带）；电脑端画面解码渲染与触控注入为本项目自研实现。

## 环境要求

- Windows 10/11，Python 3.10 ~ 3.12（开发验证用 3.10）
- 一台开启“USB 调试”的 Android 手机 + 数据线

## 安装

`.venv` 为 conda 环境：`python.exe` 位于 `.venv\` 根目录，`Scripts\` 下只有
pip、pyside6-* 等命令行工具，没有 python。

```bat
conda create -p .venv python=3.10 -y
.venv\python.exe -m pip install -r requirements.txt
.venv\python.exe -m pip install --no-deps scrcpy-client==0.4.7
```

> scrcpy-client 的元数据把 av 锁在 <10（该版本已无 Windows wheel），但其被锁定的
> `parse()` 恰恰在 av 12+ 上会切坏 H264 包。本项目已用自己的访问单元切分解码循环
> 绕开该缺陷（`app/mirror.py` 的 `QuietClient`），因此 av 用 12~13 即可，
> scrcpy-client 以 `--no-deps` 安装。

## 运行

```bat
.\.venv\python.exe main.py
```

加 `--auto-start` 可在检测到设备后自动启动镜像。

1. 手机首次连接时，在手机上允许 USB 调试（可勾选“一律允许”）。
2. 程序检测到设备后自动开启防熄屏（状态栏可见）。
3. 点“启动”，镜像画面出现在主窗口中，直接用鼠标操作即可。

## 操作说明

- 鼠标在画面上：左键点击/拖拽/长按即手机的点击/拖拽/长按；滚轮即滚动。
- **Ctrl+滚轮**：在光标位置模拟双指捏合缩放（放大/缩小网页、相册照片等）。
- `F11` 全屏/还原；侧边栏**图钉按钮** 📌 切换窗口置顶。
- 侧边栏图标：`↩`返回 `⌂`主屏 `▦`多任务 `🔔`通知栏 `🔊/🔉`音量（可按住连调）
  `⏻`电源（短按=熄屏/亮屏，按住≥0.5秒=系统电源长按行为）
  `📷`截图 `🎙`录音 `↻`旋转设备画面。
- **`🎙`录音**：点开始录手机麦克风，按钮变 `⏹`，再点停止即把完整音频保存到电脑
  （`recordings/` 下按时间戳命名，WAV 48kHz）。顶栏“音源”下拉可选
  原始（手机不做降噪，最保真）/ 默认（系统默认处理）/ 通话降噪。
  录音中拔线会自动保存已录到的部分；录音与镜像可同时进行。
- 画质默认“高”（设备原生分辨率，渐变/细节保留最好）；切换立即生效（重连约 1~2 秒）。
- 颜色：解码强制按 BT.601 矩阵解释（V2230A 等机型编码器声明 709 实际 601，
  按 709 解会色相偏移、观感过饱和），选择依据见 `scripts/color_probe.py`。

## 已知限制

- 部分国产 ROM（小米/华为等）需在开发者选项中额外开启“USB 调试（安全设置）”才允许注入输入。
- 设备显示 `unauthorized` 时，请在手机上确认授权弹窗；scrcpy 首次连接需确认一次 RSA 指纹。
- 手机熄屏时视频流为黑帧（属正常现象），点侧边栏电源键或手机电源键点亮即可。
- 录音时手机状态栏会出现系统级“麦克风使用中”提示（绿点），属系统行为，无法隐藏。
- 录音音源选“原始”（mic-unprocessed）需设备硬件支持，不支持时启动失败（日志有提示），可改用“默认”。

## 目录结构

```
main.py                 程序入口
app/adb.py              adb 子进程封装（设备轮询、shell、exec-out）
app/power.py            防熄屏管理（stay_on_while_plugged_in）
app/mirror.py           嵌入式镜像：MirrorWidget 渲染 + MirrorManager 生命周期
app/recorder.py         麦克风录音（scrcpy v4.1 仅音频通道，原始 PCM → WAV）
app/screenshot.py       adb screencap 截图（画面不可用时兜底）
app/ui_main.py          主窗口界面（单窗口 + 图标侧边栏）
scripts/fetch_scrcpy.py 下载 scrcpy 发行包（提供 adb.exe）
scripts/audio_probe.py  音频协议探针（v4.1 握手与音频流格式实测）
scripts/selftest.py     真机自检脚本
scripts/capture_window.ps1  窗口截图（开发调试用）
tools/scrcpy/           adb.exe、scrcpy-server v4.1（scrcpy 发行包内）
screenshots/            截图输出目录
recordings/             录音输出目录
```