docs(android): 任务说明、DSH 约束与交付文档
This commit is contained in:
+182
@@ -0,0 +1,182 @@
|
||||
================================================================
|
||||
OpenDance Studio —— Android 辅助 App v0.1.0 使用说明
|
||||
================================================================
|
||||
|
||||
手机端姿态采集器：用摄像头做**端侧**姿态推理，把 33 个骨骼关键点通过
|
||||
WebSocket 推送给 Windows 客户端，由后者驱动 VRM 角色并实时评分。
|
||||
|
||||
隐私：画面不会离开手机。通过网络发送的只有 33 个关键点坐标。
|
||||
|
||||
----------------------------------------------------------------
|
||||
一、安装
|
||||
----------------------------------------------------------------
|
||||
|
||||
方式一（推荐）：直接安装随附的 app-release.apk
|
||||
- 在手机上允许「安装未知来源应用」
|
||||
- 点击 APK 安装
|
||||
|
||||
方式二：用 adb 安装
|
||||
adb install -r app-release.apk
|
||||
|
||||
要求：Android 10（API 29）或更高版本。
|
||||
|
||||
----------------------------------------------------------------
|
||||
二、快速开始
|
||||
----------------------------------------------------------------
|
||||
|
||||
1. 在 Windows 电脑上启动 OpenDance Studio 客户端
|
||||
（Windows 客户端会自动监听 8765 端口）
|
||||
|
||||
2. 确保手机与电脑连在**同一个 WiFi**
|
||||
|
||||
3. 打开本应用，进入「连接设置」页
|
||||
|
||||
4. 填写电脑的 IP 地址，或直接点「扫描局域网」自动发现
|
||||
（扫描会探测局域网内开放 8765 端口的主机，约 2~3 秒）
|
||||
|
||||
5. 可点「测试连接」确认端口可达
|
||||
|
||||
6. 按需调整推流参数（见下）
|
||||
|
||||
7. 点「开始推流」，授予相机权限
|
||||
|
||||
8. 站到画面中央，屏幕上会出现骨架叠加：
|
||||
- 黄色圆点 = 识别良好的关节
|
||||
- 红色圆点/红色连线 = 置信度低（光线不足或被遮挡）
|
||||
|
||||
9. 在 Windows 客户端上确认已连接，即可开始跟练
|
||||
|
||||
----------------------------------------------------------------
|
||||
三、推流参数
|
||||
----------------------------------------------------------------
|
||||
|
||||
分辨率
|
||||
低（480×360） 最省电，适合老机型
|
||||
中（640×480） 推荐，识别精度与功耗平衡
|
||||
高（1280×720） 最清晰，但推理更慢、更耗电
|
||||
|
||||
目标帧率
|
||||
默认 30 FPS。低端机若「识别帧率」明显低于目标值，可降到 20 或 15。
|
||||
|
||||
镜像画面
|
||||
默认开启。前置摄像头的常见用法。
|
||||
注意：本应用发送的是**未镜像的原始坐标**，是否镜像由帧头 flags.bit0 声明，
|
||||
Windows 客户端据此正确还原左右。因此无论开关如何，动作方向都不会错。
|
||||
|
||||
仅上半身模式
|
||||
下半身关键点置信度置 0（显示为红点），Windows 端会插值。
|
||||
带宽或算力不足时开启可明显降负载。
|
||||
|
||||
----------------------------------------------------------------
|
||||
四、运行页状态说明
|
||||
----------------------------------------------------------------
|
||||
|
||||
连接状态 未连接 / 连接中 / 已连接 / 重连中（第 N 次）/ 已断开
|
||||
目标 正在连接的 WebSocket 地址
|
||||
会话 服务端返回的会话 ID
|
||||
已发送 累计发送帧数
|
||||
已丢弃 因推理或连接跟不上而丢弃的帧数（>0 说明设备吃力）
|
||||
发送帧率 实际推流帧率
|
||||
识别帧率 实际推理帧率
|
||||
推理耗时 单帧 MediaPipe 推理毫秒数
|
||||
人体识别 已识别 / 未识别到人体
|
||||
平均置信度 < 70% 时转黄，提示改善光线或减少遮挡
|
||||
最近错误 连接或推理的错误原因
|
||||
|
||||
网络中断时会**自动重连**（1s → 2s → 4s … 最长 15s 退避），
|
||||
无需手动操作。
|
||||
|
||||
----------------------------------------------------------------
|
||||
五、常见问题
|
||||
----------------------------------------------------------------
|
||||
|
||||
Q: 扫描不到电脑
|
||||
A: 1) 确认手机与电脑在同一 WiFi（不是手机热点）
|
||||
2) 确认 Windows 客户端已启动并正在监听 8765
|
||||
3) 在 Windows 防火墙放行 OpenDance.exe 的 TCP 8765 入站
|
||||
4) 部分路由器开启了「AP 隔离」，会阻断设备互访，需在路由器关闭
|
||||
|
||||
Q: 显示「已连接」但电脑端没有画面
|
||||
A: 查看运行页的「已发送」是否在增长。若为 0，说明相机或推理没出帧；
|
||||
若「人体识别」一直是「未识别到人体」，请站到画面中央并保证光线充足。
|
||||
|
||||
Q: 帧率很低 / 已丢弃帧数持续增长
|
||||
A: 依次尝试：降低分辨率 → 降低目标帧率 → 开启「仅上半身模式」→ 关闭其他后台应用。
|
||||
|
||||
Q: 关键点抖动明显
|
||||
A: 正常现象，Windows 端有 DTW 带状对齐与平滑处理，不要求逐帧完全一致。
|
||||
改善光照可显著提高稳定性。
|
||||
|
||||
Q: 应用退到后台会怎样？
|
||||
A: 返回键或离开运行页会立即停止推流并释放相机，不会在后台占用摄像头。
|
||||
|
||||
----------------------------------------------------------------
|
||||
六、从源码构建
|
||||
----------------------------------------------------------------
|
||||
|
||||
环境要求：
|
||||
JDK 17 AGP 8.7.3 要求（JDK 25 未经测试）
|
||||
Android SDK platforms;android-34 与 build-tools;34.0.0
|
||||
Gradle 8.9 已随 gradlew 提供
|
||||
|
||||
构建：
|
||||
|
||||
export JAVA_HOME=/path/to/jdk17
|
||||
export ANDROID_HOME=/path/to/android-sdk
|
||||
|
||||
# 生成发布签名密钥库（首次；文件不会入库，请自行备份）
|
||||
bash build/gen-keystore.sh
|
||||
|
||||
# 构建并校验产物
|
||||
bash build/build-apk.sh all
|
||||
|
||||
# 一键验证（单元测试 → 构建 → 产物校验）
|
||||
bash build/verify.sh
|
||||
|
||||
产物：
|
||||
app/build/outputs/apk/debug/app-debug.apk
|
||||
app/build/outputs/apk/release/app-release.apk
|
||||
|
||||
Android Studio 路径：
|
||||
打开本目录 → Build → Generate Signed Bundle / APK → APK → 选择 keystore → release
|
||||
|
||||
----------------------------------------------------------------
|
||||
七、测试
|
||||
----------------------------------------------------------------
|
||||
|
||||
./gradlew testDebugUnitTest
|
||||
|
||||
19 项单元测试（JVM，无需设备），核心是**金标准字节向量测试**：
|
||||
用 opendance-web 已通过验收的 TypeScript 实现产出的 239 字节向量，
|
||||
断言本端 Kotlin 实现逐位相同 —— 这是三端契约一致性的硬证据。
|
||||
|
||||
测试报告：app/build/reports/tests/testDebugUnitTest/index.html
|
||||
|
||||
----------------------------------------------------------------
|
||||
八、目录结构
|
||||
----------------------------------------------------------------
|
||||
|
||||
settings.gradle.kts / build.gradle.kts 工程与插件配置
|
||||
gradle/wrapper/ Gradle 8.9 wrapper
|
||||
project.yaml 任务清单与状态
|
||||
DSH.md 本项目 DSH 执行约束
|
||||
tasks/ 单任务说明书（T-AND-001 ~ 009）
|
||||
contracts/ 只读契约快照（来源 opendance-web v0.1.0）
|
||||
app/src/main/java/com/opendance/studio/
|
||||
MainActivity.kt 三页导航
|
||||
model/ 239 字节帧编解码 + 33 点拓扑
|
||||
camera/ CameraX 采集
|
||||
pose/ MediaPipe 端侧推理
|
||||
net/ WebSocket 推流 + 主机发现
|
||||
data/ 设置
|
||||
ui/ 连接页 / 运行页 / 关于页
|
||||
app/src/main/assets/pose_landmarker_lite.task MediaPipe 模型
|
||||
build/ 打包与验证脚本
|
||||
|
||||
----------------------------------------------------------------
|
||||
九、许可
|
||||
----------------------------------------------------------------
|
||||
|
||||
本应用代码以 MIT 许可发布。第三方开源项目声明见 THIRD_PARTY.md
|
||||
（应用内「关于」页同样可查看）。
|
||||
未使用 SMPL 模型及其衍生拓扑，统一采用 MediaPipe 33 点拓扑。
|
||||
Reference in New Issue
Block a user