# android-display

**Repository Path**: luozn19/android-display

## Basic Information

- **Project Name**: android-display
- **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-08-07
- **Last Updated**: 2026-08-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ADSP — Android USB 扩展屏

把闲置的 Android 手机用一根 USB 数据线变成 Windows 的第二块屏幕。开源、全本地、**只传画面，不做输入**。

> Turn any USB-connected Android phone into an extra Windows display — open source, fully local, pixels only, no input.

## 特性

- **纯 USB 链路**：走 RNDIS USB 网络共享，不依赖 Wi-Fi
- **硬件编码**：ffmpeg 封装 AMF / NVENC / QSV（按可用 GPU 自动选择），H.264 低延迟预设
- **扩展屏**：Windows 虚拟显示器（VDD）随客户端连接自动创建、断开自动卸载
- **低带宽**：VFR 静态降帧（~15fps）、CBR 码率上限、关键帧请求恢复
- **保活**：Android 前台服务（切后台/锁屏不断流）、自动重连（3 次退避）
- **恢复**：锁屏/睡眠/合盖唤醒后自动重建采集并强制关键帧

## 架构

```
Windows PC                                 Android 手机
┌───────────────────────┐                 ┌──────────────────────┐
│ adsp_server (C++)      │  USB RNDIS      │ adsp (Kotlin/Compose) │
│ DXGI 采集 → 硬件编码    │◄══════════════►│ UDP 收流 → MediaCodec │
│ UDP 控制面+视频面(48080)│  172.20.x.x    │ 解码 → Surface 全屏   │
│ VDD 虚拟显示器 (MttVDD) │                 │ 前台服务保活+自动重连  │
└───────────────────────┘                 └──────────────────────┘
```

协议契约见 `proto/protocol.md`，设计文档见 `docs/design.md`。

## 目录结构

```
server/    C++ 服务端（DXGI 采集、ffmpeg 编码、UDP、VDD 控制、托盘）
android/   Kotlin + Compose 客户端（连接管理器、前台服务、解码渲染）
driver/    Virtual-Display-Driver fork 基线（上游 MIT）
proto/     协议定义（C++/Kotlin 双端，唯一契约）
docs/      设计文档与实施计划
```

## 硬件/系统要求

- Windows 10 2004+ / Windows 11（IddCx 1.10）
- GPU 硬件编码三选一：**NVIDIA NVENC / AMD AMF / Intel QSV**；硬件编码不可用时自动回退 **libopenh264 软编**（保证任何机器都能出画面，CPU 占用更高）
- Android 8.0 (API 26)+，支持 MediaCodec H.264 硬件解码
- 支持 USB 网络共享（tethering）的 Android 手机 + 数据线

## 构建

### 服务端（Windows）

依赖：Visual Studio 2022（C++17）、CMake ≥3.20、ffmpeg dev 库（BtbN 或自编译，LGPL）。

```powershell
# 1. 拉取 ffmpeg 到 third_party/ffmpeg（Windows 共享版含 dll + lib + include）
powershell -ExecutionPolicy Bypass -File tools/fetch_ffmpeg.ps1

# 2. 配置 + 构建
cd server
cmake -B build -A x64
cmake --build build --config Release
# 产物：server/build/Release/adsp_server.exe（ffmpeg DLL 自动拷贝到同目录）
```

### Android 客户端

依赖：Android Studio（或命令行 SDK + JDK 17），本地 SDK 路径。

```powershell
cd android
.\gradlew.bat :app:assembleDebug
# 产物：android/app/build/outputs/apk/debug/app-debug.apk
```

## 安装虚拟显示器驱动（自动）

驱动随仓库自带：`driver/SignedDrivers/x86/VDD/`（预签名 `MttVDD.inf` + `MttVDD.dll` + `mttvdd.cat` + `devcon.exe`，无需 testsigning/重启）。

**服务端启动时自动安装**：首次运行（或驱动库缺失）时，`adsp_server` 会自动执行：

```powershell
pnputil /add-driver "<仓库>\driver\SignedDrivers\x86\VDD\MttVDD.inf" /install
devcon install "<仓库>\driver\SignedDrivers\x86\VDD\MttVDD.inf" Root\MttVDD
```

即把驱动入驱动库 + 创建 `Root\MttVDD` 根设备（需要提权，首次弹 UAC）。之后驱动已入库则跳过。

也可手动触发：`adsp_server.exe --vdd-install`（admin）。上游包（winget `VirtualDrivers.Virtual-Display-Driver`）只是驱动来源，winget 只下载不建设备，因此不作为安装手段。

驱动配置文件 `C:\VirtualDisplayDriver\vdd_settings.xml`：首模式 1920x1080@60（不要把非 1080p 模式放第一个）。**缺失时服务端会自动创建**（含手机常用竖屏分辨率 1080x1440/1080x2400 等），无需手动配置；已存在则不覆盖。

## 运行

**直接双击 `adsp_server.exe` 即可**（无参数默认：serve + VDD 虚拟屏 + 托盘 + 日志写到 exe 同目录 `adsp.log`，首次会弹 UAC 提权用于设备级虚拟屏卸载）。命令行方式（高级/诊断）：

```powershell
adsp_server.exe --serve --display mtt --pos 3840,0 --tray --log adsp.log
adsp_server.exe --console   # 保留控制台窗口（默认托盘模式隐藏窗口）
```

参数说明：

| 参数 | 说明 |
|------|------|
| `--serve` | 会话服务器（默认） |
| `--display <N\|名称>` | 采集目标：数字索引或 PnP ID 子串（VDD = `mtt`） |
| `--pos <X,Y>` | 把虚拟屏放到物理屏右侧（如 3840,0，依赖机器物理分辨率） |
| `--tray` | 启用托盘图标（状态/断开/重连/退出） |
| `--vdd-disable <n>` | 设备级卸载 VDD 适配器（需 admin/UAC） |
| `--vdd-enable <n>` | 设备级恢复 VDD 适配器（需 admin/UAC） |
| `--vdd-install` | 手动触发驱动安装：pnputil /add-driver + devcon install（启动时缺失会自动执行） |
| `--log <文件>` | stdout/stderr 重定向到文件（提权子进程也写同一文件） |
| `--install-firewall` | 添加入站 UDP 48080 防火墙规则（管理员） |

手机端：开启 **USB 网络共享**（设置 → 网络 → USB 网络共享）→ 打开 App → 点"连接"。首次需确认"允许 USB 网络共享"。

**虚拟屏生命周期**：客户端连接 → 服务器启用 VDD 设备并接入桌面（位置自动记忆）；客户端断开/心跳超时（约 12s）→ 服务器禁用 VDD 设备，第 3 屏从 Windows 完全消失。

## 诊断

```powershell
adsp_server.exe --list-displays        # 枚举输出（确认 VDD 是哪个索引）
adsp_server.exe --display-disconnect mtt   # CCD 桌面级断开（无需管理员）
adsp_server.exe --display-connect mtt      # CCD 桌面级接入
adsp_server.exe --vdd-disable mtt          # 设备级卸载 VDD（提权）
adsp_server.exe --vdd-enable mtt           # 设备级恢复 VDD（提权）
adsp_server.exe --selftest2                # 会话链路回环自测
adsp_server.exe --snapshot out.bmp --display mtt   # 抓一帧诊断
```

日志关键词：`[vdd]`（设备操作）、`[serve]`（会话/采集）、`[display]`（拓扑）。

## 已知限制 / 路线图

- 分辨率固定 1920x1080（动态 EDID 跟随手机原生分辨率未实现，`--resolution` 仅 1080p 安全）
- 无输入回传（触控/键鼠）、无音频
- 虚拟显示器上不支持 Windows Hello；DRM/HDCP 内容可能黑屏
- 自动降级：客户端按丢包率自动降 fps/码率（60fps→30fps），不会自动切分辨率
- 当前为个人开发阶段，未发布签名包；驱动使用上游预签名版本

## 许可

- 主仓库：MIT
- `driver/`：保留上游 Virtual-Display-Driver 的 MIT 许可与版权声明
- ffmpeg：仅库调用（LGPL 合规），不静态链接