zijunchiang/opendance-android
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

docs: 其余易混淆字符（x/>=/<=/~/OK 取代 × − ≥ ≤ ≈ ✓）

Browse Source
This commit is contained in:
zijunchiang
2026-09-15 21:34:50 +08:00
parent 264786134c
commit 91e56135fc
11 changed files with 31 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DSH.md
+3 -3
View File
@@ -51,9 +51,9 @@ WebSocket 推给 Windows 客户端。
| 项 | 建议值 |
|--|--|
| 单任务文件数 | ≤ 6 |
| 单任务代码行数 | ≤ 1500 |
| 单任务 Token | ≤ 12K |
| 单任务文件数 | <= 6 |
| 单任务代码行数 | <= 1500 |
| 单任务 Token | <= 12K |
| 契约引用 | 只引用锚点，不加载全文 |
## 5. 目录结构
README.md
+9 -9
View File
@@ -13,13 +13,13 @@ OpenDance Studio **阶段三**：Android 辅助 App（Kotlin + CameraX + MediaPi
| 验收项 | 结果 |
|--|--|
| 单元测试 | ✓ **30 项全部通过**（JVM，无需设备） |
| **跨端金标准** | ✓ Kotlin 序列化器与 Web 端 TypeScript 实现**逐位一致** |
| `./gradlew assembleRelease` | ✓ 生成**已签名** APK（28.6 MB） |
| 签名校验 | ✓ `apksigner` 退出码 0，v2 方案，CN=OpenDance Studio Dev |
| 包信息 | ✓ `com.opendance.studio` v0.1.0，minSdk 29（Android 10+）/ targetSdk 34 |
| 模型随包分发 | ✓ `assets/pose_landmarker_lite.task` 5.7 MB（Stored 未压缩） |
| ABI 覆盖 | ✓ arm64-v8a + armeabi-v7a（debug 额外含 x86/x86_64） |
| 单元测试 | OK **30 项全部通过**（JVM，无需设备） |
| **跨端金标准** | OK Kotlin 序列化器与 Web 端 TypeScript 实现**逐位一致** |
| `./gradlew assembleRelease` | OK 生成**已签名** APK（28.6 MB） |
| 签名校验 | OK `apksigner` 退出码 0，v2 方案，CN=OpenDance Studio Dev |
| 包信息 | OK `com.opendance.studio` v0.1.0，minSdk 29（Android 10+）/ targetSdk 34 |
| 模型随包分发 | OK `assets/pose_landmarker_lite.task` 5.7 MB（Stored 未压缩） |
| ABI 覆盖 | OK arm64-v8a + armeabi-v7a（debug 额外含 x86/x86_64） |
## 快速开始
@@ -183,8 +183,8 @@ IP 地址：192.0.2.10 # RFC 5737 文档示例网段，实际填你电脑
| # | 命令 | 预期输出 |
|--|--|--|
| 1 | `./gradlew testDebugUnitTest` | `BUILD SUCCESSFUL`，全部用例通过；报告在 `app/build/reports/tests/testDebugUnitTest/index.html` |
| 2 | `bash build/build-apk.sh debug` | 末尾打印 `✓ Debug APK：app/build/outputs/apk/debug/app-debug.apk` 及其大小与签名信息 |
| 3 | `bash build/build-apk.sh all` | debug 与 release 均 `✓`；release 显示 `已签名（APK Signature Scheme v2）` |
| 2 | `bash build/build-apk.sh debug` | 末尾打印 `OK Debug APK：app/build/outputs/apk/debug/app-debug.apk` 及其大小与签名信息 |
| 3 | `bash build/build-apk.sh all` | debug 与 release 均 `OK`；release 显示 `已签名（APK Signature Scheme v2）` |
| 4 | `$ANDROID_HOME/build-tools/34.0.0/apksigner verify app/build/outputs/apk/release/app-release.apk` | 退出码 0（无输出即通过） |
| 5 | `unzip -l app/build/outputs/apk/release/app-release.apk \| grep pose_landmarker_lite.task` | 列出 `assets/pose_landmarker_lite.task`（约 5.7 MB，Stored 未压缩） |
| 6 | `adb install -r app/build/outputs/apk/debug/app-debug.apk` | `Success` |
README.txt
+4 -4
View File
@@ -132,7 +132,7 @@ WebSocket 推送给 Windows 客户端，由后者驱动 VRM 角色并实时评
报告：app/build/reports/tests/testDebugUnitTest/index.html
bash build/build-apk.sh all
预期：debug 与 release 均显示 "✓ ... APK"，release 显示
预期：debug 与 release 均显示 "OK ... APK"，release 显示
"已签名（APK Signature Scheme v2）"
$ANDROID_HOME/build-tools/34.0.0/apksigner verify app/build/outputs/apk/release/app-release.apk
@@ -193,9 +193,9 @@ WebSocket 推送给 Windows 客户端，由后者驱动 VRM 角色并实时评
--
分辨率
低（480×360） 最省电，适合老机型
中（640×480） 推荐，识别精度与功耗平衡
高（1280×720） 最清晰，但推理更慢、更耗电
低（480x360） 最省电，适合老机型
中（640x480） 推荐，识别精度与功耗平衡
高（1280x720） 最清晰，但推理更慢、更耗电
目标帧率
默认 30 FPS。低端机若「识别帧率」明显低于目标值，可降到 20 或 15。
contracts/data-models.md
+5 -5
View File
@@ -54,9 +54,9 @@ rejected 已驳回
| 字段 | 类型 | 必填 | 说明 |
|--|--|--|--|
| `id` | number | 读 | |
| `title` | string | ✅ | 曲名，≤200 |
| `artist` | string | ✅ | 演唱者，≤200 |
| `album` | string | | 专辑，≤200 |
| `title` | string | ✅ | 曲名，<=200 |
| `artist` | string | ✅ | 演唱者，<=200 |
| `album` | string | | 专辑，<=200 |
| `language` | string | | `zh` / `en` / `ja` / `ko` / `instrumental` |
| `durationMs` | number | | 时长毫秒 |
| `bpm` | number | | 节拍 |
@@ -74,7 +74,7 @@ rejected 已驳回
|--|--|--|--|
| `id` | number | 读 | |
| `songId` | number\|null | | 关联曲目 |
| `name` | string | ✅ | 动作名称，≤200 |
| `name` | string | ✅ | 动作名称，<=200 |
| `format` | enum | ✅ | `bvh` / `vmd` / `fbx` / `gltf` / `glb` / `keypoints-json` |
| `fileUrl` | string | 读 | 原始动作文件 |
| `fileSize` | number | 读 | 字节 |
@@ -95,7 +95,7 @@ rejected 已驳回
| 字段 | 类型 | 必填 | 说明 |
|--|--|--|--|
| `id` | number | 读 | |
| `name` | string | ✅ | 模型名称，≤200 |
| `name` | string | ✅ | 模型名称，<=200 |
| `format` | enum | ✅ | `glb` / `vrm`（主力）/ `gltf` / `fbx`（历史数据）。上传的 PMX/FBX 会被服务端转换成 glb 或 vrm 再入库，见 model-formats.md 1.1 |
| `vrmVersion` | string\|null | 读 | `0.x` / `1.0`，非 VRM 为 null |
| `isPrimary` | boolean | | 全局默认模型；**同一时刻全库至多一个 `true`** |
contracts/model-formats.md
+2 -2
View File
@@ -126,7 +126,7 @@ VRM 版本识别：读取 GLB 的 JSON chunk，检查 `extensions.VRM`（0.x）
VMD 是二进制格式：文件头 `Vocaloid Motion Data 0002`（30 字节）+ 模型名（20 字节，
Shift-JIS）+ 骨骼关键帧数组（每条 **111 字节**：15 字节骨骼名、uint32 帧号、
float32×3 位移、float32×4 旋转四元数、64 字节贝塞尔插值参数）+ morph / 相机 /
float32x3 位移、float32x4 旋转四元数、64 字节贝塞尔插值参数）+ morph / 相机 /
灯光 / 自阴影 / IK / 可见性段落。**VMD 不含骨骼长度**，只有旋转（少数骨骼带位移），
因此服务端必须自带一套标准 MMD 骨架才能做 FK。
@@ -161,7 +161,7 @@ FK 旋转）。两份示例文件分别命中两种路径。
**标准骨架数值来源**：解析参考模型的 PMX 骨骼段实测得到（而非凭经验估计），
再去掉模型自身原点偏移并抹平左右不对称。关键比例：足首 1.43 / ひざ 6.57 /
髋 11.50 / センター 10.88 / 首 16.21 / 頭 17.16（总高约 19.4，髋高比约 59%）；
大腿 4.94 + 小腿 5.15 ≈ 腿长 10.07。
大腿 4.94 + 小腿 5.15 ~ 腿长 10.07。
## 3. 上传限制
contracts/skeleton-topology.md
+1 -1
View File
@@ -121,5 +121,5 @@ spine = angle(neck, pelvis, midpoint(left_ankle, right_ankle))
`angle(a, b, c)` = 向量 `ba` 与 `bc` 的夹角余弦，即
`dot(normalize(a-b), normalize(c-b))`，落在 `[-1, 1]`。
**DTW 序列结构（冻结）**：每帧 = `[33 × (x, y, z), 9 个关节角余弦] = 108 维`。
**DTW 序列结构（冻结）**：每帧 = `[33 x (x, y, z), 9 个关节角余弦] = 108 维`。
低置信度点（`visibility < 0.5`）在插值阶段由相邻帧线性补全，不参与代价计算。
contracts/websocket-keypoints.md
+1 -1
View File
@@ -27,7 +27,7 @@ ws://<windows-host>:8765/pose
bit2 = 上半身模式(仅 0..22 有效)
bit3-7 保留，必须为 0
4 4 frame_id u32 LE 单调递增，从 0 开始
8 231 keypoints 33 × 7B 见下
8 231 keypoints 33 x 7B 见下
--
合计 239
```
tasks/002-camera-x.md
+1 -1
View File
@@ -25,7 +25,7 @@ app/src/main/java/com/opendance/studio/data/AppSettings.kt
|---|---|---|
| 背压策略 | `STRATEGY_KEEP_ONLY_LATEST` | 推理慢时自动丢帧，预览不卡顿 |
| 输出格式 | `OUTPUT_IMAGE_FORMAT_RGBA_8888` | MediaPipe 需要 Bitmap，避免 YUV 转换 |
| 分辨率 | 三档（480×360 / 640×480 / 1280×720），`FALLBACK_RULE_CLOSEST_LOWER_THEN_HIGHER` | 低端机可降档保帧率 |
| 分辨率 | 三档（480x360 / 640x480 / 1280x720），`FALLBACK_RULE_CLOSEST_LOWER_THEN_HIGHER` | 低端机可降档保帧率 |
| 分析线程 | 单线程 Executor | 推理串行，避免并发抢占 |
| 镜像 | 预览镜像由 PreviewView 处理；**发送原始未镜像坐标** | 契约要求由 flags.bit0 声明镜像语义 |
tasks/004-keypoint-serializer.md
+3 -3
View File
@@ -25,7 +25,7 @@ app/src/main/java/com/opendance/studio/model/SkeletonTopology.kt
2 1 version u8 = 1
3 1 flags u8 bit0 镜像 | bit1 低置信度 | bit2 上半身
4 4 frame_id u32 LE
8 231 keypoints 33 × 7B：s16 x, s16 y, s16 z, u8 conf
8 231 keypoints 33 x 7B：s16 x, s16 y, s16 z, u8 conf
合计 239
```
@@ -57,8 +57,8 @@ console.log(buf.toString('hex'));
## 关键实现
- `ByteBuffer.order(LITTLE_ENDIAN)`，避免手动移位出错
- 定点换算 `round(v × 32767)` 并 `coerceIn(-32768, 32767)`
- 置信度 `round(v × 255)`，阈值 0.5 含端点（`>=`）
- 定点换算 `round(v x 32767)` 并 `coerceIn(-32768, 32767)`
- 置信度 `round(v x 255)`，阈值 0.5 含端点（`>=`）
- 输入超范围时裁剪而非抛异常（相机抖动可能产生轻微越界值）
- 并行 FloatArray 存储，30 FPS 循环内零对象分配
tasks/006-connect-ui.md
+1 -1
View File
@@ -37,7 +37,7 @@ HTTP 端点发现。因此：
| 项 | 说明 |
|--|--|
| IP / 端口 | 默认 8765，与契约一致 |
| 分辨率 | 480×360 / 640×480 / 1280×720 |
| 分辨率 | 480x360 / 640x480 / 1280x720 |
| 目标帧率 | 写入 hello 的 targetFps |
| 镜像画面 | 写入 flags.bit0 |
| 仅上半身模式 | 写入 flags.bit2 |
tasks/008-about-page.md
+1 -1
View File
@@ -31,6 +31,6 @@ app/src/main/java/com/opendance/studio/ui/Credits.kt
## 验收
`CreditsTest`（JVM 单元测试）断言：
条目数 ≥ 10、文档要求的 10 项全部在列、每条有许可证与 https 链接、
条目数 >= 10、文档要求的 10 项全部在列、每条有许可证与 https 链接、
已知项目的许可证正确、本端自身依赖（MediaPipe/OkHttp/CameraX/Compose）均在列、
项目名不重复、契约版本为 0.1.0。