982584e470
- Android 6-14 兼容说明 - 可配置设备名 + UIBC 触摸回传 - 分辨率/帧率设置 + SPS 自动检测 - 三级延迟模式配置表 - 完整技术栈说明、设置项使用指南、常见问题
11 KiB
11 KiB
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字段
构建说明
前置条件
- Android Studio (Hedgehog 2023.1.1 或更新版本)
- JDK 17
- Android SDK 34
构建步骤
# 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
直接安装
# 通过 ADB 安装到 Android TV
adb install -r app/build/outputs/apk/debug/app-debug.apk
使用说明
Android TV 端
- 安装后打开 AirDisplay 应用
- 等待屏幕显示"等待连接"和设备名称
- 应用会自动启动 Wi-Fi Direct 和 RTSP 服务
设置项
按遥控器菜单键或方向键导航至「设置」入口：
- 设备名称：自定义设备名，未配置时使用系统默认名
- 分辨率/帧率：
- 手动模式：从预设列表选择（640×480~1920×1080 @ 24/30/60fps）
- 自动模式：从 Windows 端视频流 SPS 自动检测实际分辨率
- 延迟模式：
- 低延迟（游戏）：最小缓冲，激进的丢帧策略
- 平衡（推荐）：日常使用兼顾画质与延迟
- 兼容（弱网络）：大缓冲抗网络抖动
Windows 端
- 按
Win + K打开"投屏"面板 - 在设备列表中查找 Android TV 设备名
- 点击连接
- 等待握手完成，电视屏幕将显示 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)
- Android Wi-Fi Direct API
- Android MediaCodec
- ITU-T H.264 Specification
- UIBC Generic Input PDU Format
License
MIT