# 无线投屏

**Repository Path**: lp9906/wireless-cast

## Basic Information

- **Project Name**: 无线投屏
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-30
- **Last Updated**: 2026-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 无线投屏（WireCast）

> 一款安卓设备间的**低延时无线投屏**应用：手机、平板、电视互投，扫码即连，画面清晰流畅。
> 自研实时链路（H.264 硬编 → RTP/UDP → 硬解直出），端到端延时低至 ~100ms 级别。

---

## 产品介绍

把一台安卓设备的屏幕**实时投到另一台安卓设备**上：

- 手机投手机、手机投电视、电视投手机，双向皆可
- **二维码扫码连接**，无需输入 IP，接收端自动监听、即开即用
- 内置**系统声音内录**（非麦克风），投屏同时传声，音画同步
- 单 App 两页合一：接收端 / 发送端（设置并入发送页），一部手机即可当"投屏器"
- **配置由发送端控制**：发送页调整码率、缓冲及各功能开关，自动同步给接收端

**典型场景**：会议投屏、演示分享、影音播放、远程看屏、手机内容上大屏。

---

## 核心优势

| 优势 | 说明 |
|---|---|
| **低延时** | 硬编硬解 + 零拷贝直出渲染，画面跟手不拖影 |
| **即开即用** | 接收端打开即自动监听，发送端扫码即投，无复杂配置 |
| **旋转自动全屏** | 横竖屏切换自动适配接收端全屏显示，**无需重新授权、无弹窗打断** |
| **稳定不黑屏** | 断流自动恢复、编码异常自愈、静态画面停摆自愈——长时间投屏不黑屏不花屏 |
| **流畅不积压** | 智能重排序 + 攒时缓冲 + 播放节流（按帧间时间差播放），120Hz 高刷源在 60Hz 屏上依然平稳无积压 |
| **画质自由调** | 码率 / 缓冲时长 / 各功能开关均在发送页调整，**配置自动同步至接收端**并持久保存 |
| **工程化内核** | 链路功能全部插件化 + 双链引擎编排（发送链/接收链），发送页底部内置**插件树实时诊断** |
| **省心省电** | 屏幕常亮、自动恢复监听，投着不管也安心 |

---

## 快速开始

### 环境要求

- 两端安卓设备处于**同一 Wi-Fi 局域网**
- Android 10 及以上（API 29+）

### 使用步骤

1. **接收端**：打开 App → 停留在"接收"页（自动开始监听，显示二维码与本机 IP）
2. **发送端**：打开 App → "发送"页 → 扫码接收端二维码（或手动输入 IP）→ 按系统提示授权 → 开始投屏
3. **调参数**（可选）：发送页下方可直接调码率、缓冲时长及各功能开关，**变更实时同步到接收端**
4. **看状态**（可选）：发送页底部「插件树」只读区 1s 刷新显示双链各插件启用态与实时状态

> 投屏中旋转发送端手机，接收端画面自动横屏/竖屏全屏适配（无需重新授权）。

### 构建安装（开发者）

```bash
# 经 ASCII junction 路径构建（项目路径含中文会导致本机 Gradle/单测问题）
cd C:\VsCodeProjects\wireless-cast2
gradlew.bat :app:all:assembleDebug     # debug 包
gradlew.bat :app:all:assembleRelease   # release 包
adb install -r app\all\build\outputs\apk\release\*.apk
```

---

## 技术概览（简述）

- **链路**：屏幕采集 → H.264/AAC 硬件编码 → RTP/UDP 实时传输 → 硬件解码 → 屏幕直出
- **双链引擎（P-DES-005/006）**：发送链 TxChain（打包 → 入队 → 发送）与接收链 RxChain
  （重排 → 重组 → 门控 → 出口）编排全部**功能插件**（ChainPlugin：RTP 分片 / 关键帧优先 /
  重排序 / 渲染门控 / PLI 恢复 / 抖动缓冲…），插件启用态运行时读 DebugConfig（热生效）
- **事件总线**：PLI 请求 / 关键帧输出 / 会话节拍经链事件广播（跨插件信号，不直连）
- **低延时设计**：零拷贝渲染、定时排空解码积压
- **高刷适配**：播放节流（播放时钟门控——帧时间戳与播放时间对比，过时帧跳过显示，无损），
  120Hz 源在 60Hz 屏不积压
- **可靠性设计**：渲染门控（坏帧隔离）、PLI 快速恢复、重排序窗、攒时缓冲、解码异常自愈、
  编码停摆自愈（投静态画面时源端自然低帧率属 VirtualDisplay 正常行为）
- **配置工程化（P-DES-006）**：ConfigSchema 集中登记全部配置键（归属/热语义），
  「热生效 / 下次会话生效」提示由 schema 驱动；插件 configKeys 由 schema 推导（防漂移）
- **易用设计**：二维码连接、sink 自动监听、旋转免授权全屏适配、配置持久化、
  **发送端配置动态同步接收端**
- 编码帧率固定 60（厂商编码器按屏幕节奏全速出帧，软件层钳制无效）

---

## 项目结构

```
app/all/      应用（接收/发送两页面，设置并入发送页）
core/         核心模块（chain 链引擎与插件 / codec 编解码 / transport 传输 / common 公共）
core/chain    双链引擎 + 全功能插件 + 事件总线（产品/单测共用同一插件实例）
docs/         项目文档（开发规范/计划/记录/台账）
```

---

## 开发者文档

面向开发者的完整文档（需求、设计、测试、缺陷记录、发布信息）见 [docs/](./docs/README.md)：

| 文档 | 内容 |
|---|---|
| [产物台账](./docs/reports/产物台账.md) | 全部产物与工作项登记 |
| [R-FLOW-002 投屏渲染流程](./docs/reports/R-FLOW-002-投屏渲染流程.md) | 渲染链路设计 |
| [R-REL-001 发布信息](./docs/reports/R-REL-001-发布信息.md) | 发布内容与协议说明 |
| [P-DES-005/006](./docs/plans/) | 链路引擎化与功能收敛方案（批 A-D 台账） |
| [R-PRB-019/020/021/022](./docs/reports/) | 黑屏 / 旋转全屏 / 卡顿 / PLI 风暴问题分析与修复记录 |

---

## 当前进度（2026-09-02，release 0.2.7）

- ✅ 二合一 App（接收/发送两页，设置并入发送页）+ 自动监听 + 二维码连接
- ✅ **配置由发送端控制，动态同步至接收端**（信令 SETTINGS，变更即推送）
- ✅ 旋转自动全屏适配（免授权）
- ✅ 黑屏 / 花屏 / 延时增长 / 间歇性卡顿问题全部修复并经真机验证
- ✅ **播放节流**：120Hz 高刷源持续输出时接收端按帧间时间差播放，画面不积压（真机验证）
- ✅ **全流程插件化 + 双链引擎（P-DES-005/006 批 A）**：TxChain/RxChain 引擎基线，传统手写
  发送/接收段已删除，事件总线接入（PLI/IDR 输出/会话节拍）
- ✅ **测试影子合并（批 B）**：删除测试侧影子插件族，JVM 用例与产品共用同一插件实例；
  主侧引擎用例 TxChainTest/RxChainTest 落地；全量单测 184 例（仅既有花屏率数据门禁 1 例失败）
- ✅ **插件树诊断（批 C）**：发送页底部只读插件树（1s 刷新，双链分组/启用态/实时状态）
- ✅ **ConfigSchema（批 D）**：配置键集中登记 + 热语义检查器（热生效文案由 schema 驱动）
- ✅ sink 黑屏 hotfix：接收链 RxChain 建链回归修复（三星→联想真机验证出画正常）
- 📌 批 A-D 真机 A/B 完整回归待做（联想发 → 三星收方向，对照 0.2.5 行为）
- 📌 正式 release 签名 keystore 待配置

## AI 协作

本项目在开发过程中由 AI 辅助编码完成：

- **模型**：DeepSeek v4 Flash（`deepseek-v4-flash`）
- **模型**：DeepSeek v4 Pro（`deepseek-v4-pro`）
- **开发框架**：DeepSeek Harness（`deepseek-harness`）