982584e470
- Android 6-14 兼容说明 - 可配置设备名 + UIBC 触摸回传 - 分辨率/帧率设置 + SPS 自动检测 - 三级延迟模式配置表 - 完整技术栈说明、设置项使用指南、常见问题
257 lines
11 KiB
Markdown
257 lines
11 KiB
Markdown
# AirDisplay — Android TV 无线显示器
|
||
|
||
将 Android TV 变成支持 **Microsoft 无线显示适配器**（Miracast/Wi-Fi Display）的无线显示器。
|
||
|
||
## 功能概述
|
||
|
||
- **Wi-Fi Direct P2P**：Android TV 作为 Group Owner，Windows 直接发现并连接
|
||
- **Miracast 协议**：完整实现 RTSP M1-M8 握手（TCP 7236）
|
||
- **硬件解码**：基于 Android MediaCodec 的 H.264/H.265 硬件加速解码
|
||
- **TS 解复用**：MPEG2-TS 流实时解析与音视频分离
|
||
- **低延迟渲染**：SurfaceView 输出 + AudioTrack 音频播放
|
||
- **UIBC 触摸回传**：支持触控/鼠标/键盘事件从 Android TV 回传至 Windows 端
|
||
- **可配置设备名**：自定义设备名称，未配置时自动使用系统设备名（Build.MODEL）
|
||
- **分辨率/帧率选择**：支持手动选择预设 + 自动从 SPS 检测源端分辨率
|
||
- **三级延迟模式**：低延迟（游戏）/ 平衡（推荐）/ 兼容（弱网络）
|
||
- **Android TV UI**：Leanback 主题，遥控器友好设置界面
|
||
|
||
## 系统要求
|
||
|
||
| 项目 | 要求 |
|
||
|------|------|
|
||
| Android TV | Android 6.0 (API 23) 或更高 |
|
||
| 硬件 | 支持 Wi-Fi Direct 的 Wi-Fi 芯片 |
|
||
| Windows | Windows 10/11 内置"无线显示器"功能 |
|
||
| 网络 | 无需路由器，Wi-Fi Direct 直连 |
|
||
|
||
## 工作原理
|
||
|
||
```
|
||
┌─ Windows (Source) ─────────────────────────────────┐
|
||
│ Win + K → 连接到无线显示器 │
|
||
│ ↓ Wi-Fi Direct │
|
||
│ ↓ TCP 7236 (RTSP M1-M8 握手) │
|
||
│ ↓ UDP RTP/MPEG2-TS (音视频流) │
|
||
│ ↑ TCP 7237 (UIBC 触控/鼠标/键盘回传) │
|
||
└─────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─ Android TV (Sink) ────────────────────────────────┐
|
||
│ DeviceNameManager — 设备名管理 │
|
||
│ ResolutionManager — 分辨率/帧率管理 │
|
||
│ LatencyManager — 三级延迟模式控制 │
|
||
│ WiFiDirectManager — Wi-Fi Direct P2P Group Owner │
|
||
│ → RtspServer (7236 M1-M8 握手 + 能力协商) │
|
||
│ → RtpReceiver (UDP 接收 + 可调缓冲水位) │
|
||
│ → TsDemuxer (188B TS 解析 + SPS 自动分辨率检测) │
|
||
│ → MediaCodec (H.264/H.265 解码 + 低延迟模式) │
|
||
│ → SurfaceView + AudioTrack │
|
||
│ → UibcServer (7237 触控/鼠标/键盘事件注入) │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 完成改造一览
|
||
|
||
### ✅ Android 6–14 兼容性改造（V2）
|
||
| 项目 | 方案 |
|
||
|------|------|
|
||
| `minSdk=23` (Android 6.0) | 全项目最低 API 要求 |
|
||
| `targetSdk=34` | 适配 Android 14 目标 API |
|
||
| `foregroundServiceType` | `tools:targetApi=34` 条件声明 |
|
||
| `FOREGROUND_SERVICE_MEDIA_PLAYBACK` | `maxSdkVersion=34` |
|
||
| `KEY_LOW_LATENCY` | API 29+（Android Q+）守卫 |
|
||
| 通知渠道 | API 26+（Android O+）守卫 |
|
||
|
||
### ✅ 可配置设备名（V2）
|
||
- **DeviceNameManager**：SharedPreferences 持久化，未配置时回退 `Build.MODEL`
|
||
- **SettingsActivity** + **activity_settings.xml**：Leanback 风格设置界面，32 字符限制
|
||
- **RTSP 握手**：M1 响应 `Server:` 头注入设备名
|
||
- **通知栏**：前台服务通知标题使用设备名
|
||
- **Wi-Fi Direct**：反射尝试设置 P2P 设备名
|
||
|
||
### ✅ UIBC 触摸回传（V2）
|
||
- **UibcServer**：TCP 7237 接收 Windows 端 Generic Input PDU
|
||
- 触控事件（Generic Input PDU type 4 + 5）
|
||
- 鼠标移动/左键/右键（type 4）
|
||
- 键盘输入（type 2）
|
||
- InputManager 注入（Android 10+ 新增触摸序列 API）
|
||
- 回调模式（Android 6–9 兼容）
|
||
- **WfdParser**：`buildUibcCapability` / `parseUibcCapability` 编码解码
|
||
- **RTSP M3 握手**：协商 UIBC 能力，端口 7237
|
||
|
||
### ✅ 分辨率/帧率设置+自动模式（V3）
|
||
- **ResolutionManager**：SharedPreferences 持久化
|
||
- 7 个预设（640×480@60 ~ 1920×1080@60）
|
||
- 自动模式 / 手动模式切换
|
||
- 自动模式从 SPS 解析实际分辨率
|
||
- **动态 WFD 参数**：`WfdParser.buildVideoFormats(width, height, fps)` 根据设置动态编码
|
||
- **设置 UI**：ResolutionSelector (RadioGroup) + 预设 Spinner
|
||
- **SPS 自动检测**：TsDemuxer 完整 H.264 SPS 解析（宽/高 + frame_cropping），`onResolutionDetected` 回调
|
||
|
||
### ✅ 延迟优化（V3）
|
||
- **LatencyManager**：三级模式配置持久化
|
||
| 参数 | 低延迟（游戏） | 平衡（推荐） | 兼容（弱网络） |
|
||
|------|:-:|:-:|:-:|
|
||
| RTP 缓冲水位 | 3 包 | 8 包 | 20 包 |
|
||
| 队列上限 | 30 帧 | 60 帧 | 120 帧 |
|
||
| 低延迟解码 (KEY_LOW_LATENCY) | ✅ | ✅ | ❌ |
|
||
| 丢帧阈值 | 15 帧 | 30 帧 | 60 帧 |
|
||
| 每次丢帧比例 | 50% | 30% | 10% |
|
||
| 解码超时 | 3ms | 10ms | 20ms |
|
||
- **MediaRenderer**：`updateLatencyConfig()` 动态调参，`configureVideoCodec` 条件启用低延迟
|
||
- **RtpReceiver**：可配置 `bufferWatermark` 字段
|
||
|
||
## 构建说明
|
||
|
||
### 前置条件
|
||
|
||
1. **Android Studio** (Hedgehog 2023.1.1 或更新版本)
|
||
2. **JDK 17**
|
||
3. **Android SDK 34**
|
||
|
||
### 构建步骤
|
||
|
||
```bash
|
||
# 1. 克隆项目
|
||
git clone https://git.privserv.eu.org/yuqianhe/airdisplay.git
|
||
cd airdisplay
|
||
|
||
# 2. 生成调试 APK
|
||
./gradlew assembleDebug
|
||
|
||
# 3. 生成的 APK 位置
|
||
# app/build/outputs/apk/debug/app-debug.apk
|
||
```
|
||
|
||
### 直接安装
|
||
|
||
```bash
|
||
# 通过 ADB 安装到 Android TV
|
||
adb install -r app/build/outputs/apk/debug/app-debug.apk
|
||
```
|
||
|
||
## 使用说明
|
||
|
||
### Android TV 端
|
||
|
||
1. 安装后打开 **AirDisplay** 应用
|
||
2. 等待屏幕显示"等待连接"和设备名称
|
||
3. 应用会自动启动 Wi-Fi Direct 和 RTSP 服务
|
||
|
||
### 设置项
|
||
|
||
按遥控器菜单键或方向键导航至「设置」入口：
|
||
|
||
- **设备名称**：自定义设备名，未配置时使用系统默认名
|
||
- **分辨率/帧率**：
|
||
- 手动模式：从预设列表选择（640×480~1920×1080 @ 24/30/60fps）
|
||
- 自动模式：从 Windows 端视频流 SPS 自动检测实际分辨率
|
||
- **延迟模式**：
|
||
- 低延迟（游戏）：最小缓冲，激进的丢帧策略
|
||
- 平衡（推荐）：日常使用兼顾画质与延迟
|
||
- 兼容（弱网络）：大缓冲抗网络抖动
|
||
|
||
### Windows 端
|
||
|
||
1. 按 `Win + K` 打开"投屏"面板
|
||
2. 在设备列表中查找 Android TV 设备名
|
||
3. 点击连接
|
||
4. 等待握手完成，电视屏幕将显示 Windows 桌面
|
||
|
||
### UIBC 触摸回传
|
||
|
||
连接后，Android TV 遥控器/触摸板可控制 Windows：
|
||
- **触控滑动**：模拟鼠标移动
|
||
- **点击**：鼠标左键
|
||
- **菜单键**：鼠标右键
|
||
- **键盘输入**：通过 USB/蓝牙键盘输入
|
||
|
||
### 注意事项
|
||
|
||
- 确保 Android TV 和 Windows PC 的 Wi-Fi 都已开启
|
||
- Wi-Fi Direct 不需要连接同一路由器
|
||
- 首次连接可能需要 5-15 秒
|
||
- 如果找不到设备，可尝试重启应用
|
||
- 部分 Android TV 设备可能需要在设置中开启 Wi-Fi Direct 权限
|
||
- 延迟模式切换后需要重新连接才能生效（解码器低延迟参数）
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
airdisplay/
|
||
├── app/
|
||
│ ├── build.gradle.kts # App 构建配置 (compileSdk=34, minSdk=23)
|
||
│ └── src/main/
|
||
│ ├── AndroidManifest.xml # 权限、组件声明
|
||
│ ├── res/ # 资源文件
|
||
│ └── java/com/qwenpaw/miracast/
|
||
│ ├── MiracastService.kt # ☰ 核心服务（全生命周期管理）
|
||
│ ├── DeviceNameManager.kt # 设备名管理（持久化 + 默认回退）
|
||
│ ├── ResolutionManager.kt # 分辨率/帧率管理（预设 + 自动检测）
|
||
│ ├── LatencyManager.kt # 三级延迟模式控制
|
||
│ ├── wifidirect/
|
||
│ │ ├── WiFiDirectManager.kt # Wi-Fi Direct P2P 管理
|
||
│ │ └── WiFiDirectBroadcastReceiver.kt # P2P 广播接收
|
||
│ ├── rtsp/
|
||
│ │ ├── RtspServer.kt # TCP 7236 服务器
|
||
│ │ ├── RtspSession.kt # M1-M8 握手状态机（含 UIBC 协商）
|
||
│ │ └── WfdParser.kt # WFD 参数编解码（动态分辨率）
|
||
│ ├── media/
|
||
│ │ ├── RtpReceiver.kt # UDP RTP 接收（可调缓冲水位）
|
||
│ │ ├── TsDemuxer.kt # MPEG2-TS 解复用（SPS 自动分辨率检测）
|
||
│ │ └── MediaRenderer.kt # MediaCodec 解码渲染（低延迟模式）
|
||
│ ├── uibc/
|
||
│ │ └── UibcServer.kt # UIBC 触控/鼠标/键盘回传（TCP 7237）
|
||
│ └── ui/
|
||
│ ├── MainActivity.kt # Android TV 主界面
|
||
│ ├── SettingsActivity.kt # 设备名 + 分辨率设置界面
|
||
│ └── activity_settings.xml
|
||
├── build.gradle.kts # 项目构建配置
|
||
├── settings.gradle.kts # 项目设置
|
||
└── gradle.properties # Gradle 属性
|
||
```
|
||
|
||
## 协议栈
|
||
|
||
| 层级 | 协议/技术 | 端口 | 功能 |
|
||
|------|-----------|------|------|
|
||
| 发现/连接 | Wi-Fi Direct (P2P) | - | 设备发现与连接 |
|
||
| 控制 | RTSP (Miracast M1-M8) | TCP 7236 | 握手、能力协商（分辨率/UIBC） |
|
||
| 传输 | RTP/AVP | UDP 19000+ | 媒体数据传输 |
|
||
| 封装 | MPEG2-TS | - | 音视频复用 |
|
||
| 编码 | H.264/H.265 | - | 视频压缩 |
|
||
| 编码 | AAC/AC3 | - | 音频压缩 |
|
||
| 回传 | UIBC (Generic Input PDU) | TCP 7237 | 触控/鼠标/键盘事件回传 |
|
||
|
||
## 常见问题
|
||
|
||
**Q: Windows 搜索不到设备？**
|
||
A: 确认 Android TV 支持 Wi-Fi Direct。首次启动需等待 5-10s 完成 Wi-Fi Direct 初始化。可在设置中自定义设备名以方便识别。
|
||
|
||
**Q: 连接后黑屏？**
|
||
A: 检查 Android TV 是否开启了"允许覆盖其他应用"的权限。部分设备需要手动授权。尝试切换延迟模式为"兼容"。
|
||
|
||
**Q: 声音没有输出？**
|
||
A: 检查 Android TV 的音量设置。部分 AAC 编码需要额外的解码器支持。
|
||
|
||
**Q: 延迟高？**
|
||
A: 默认使用"平衡"模式，延迟约 100-200ms。切换至"低延迟（游戏）"模式可降至 50-100ms（牺牲抗抖动能力）。确保 Wi-Fi 信号强度良好。
|
||
|
||
**Q: UIBC 触摸不生效？**
|
||
A: Android TV 遥控器触控板作为触摸输入源。部分 Android TV 系统可能需要开启"辅助功能"权限才能使用 InputManager 注入。
|
||
|
||
**Q: 分辨率自动模式不准确？**
|
||
A: 自动模式从 H.264 SPS 中解析视频宽高。极少数编码器可能不包含完整 SPS 信息，此时回退至手动模式设置的分辨率。
|
||
|
||
## 技术参考
|
||
|
||
- [Miracast Specification (Wi-Fi Alliance)](https://www.wi-fi.org/discover-wi-fi/wi-fi-certified-miracast)
|
||
- [Android Wi-Fi Direct API](https://developer.android.com/guide/topics/connectivity/wifip2p)
|
||
- [Android MediaCodec](https://developer.android.com/reference/android/media/MediaCodec)
|
||
- [ITU-T H.264 Specification](https://www.itu.int/rec/T-REC-H.264)
|
||
- [UIBC Generic Input PDU Format](https://source.android.com/docs/core/connect/wifi-display)
|
||
|
||
## License
|
||
|
||
MIT
|