diff --git a/DSH.md b/DSH.md index 0361cc1..f6e278d 100644 --- a/DSH.md +++ b/DSH.md @@ -51,9 +51,9 @@ WebSocket 推给 Windows 客户端。 | 项 | 建议值 | |--|--| -| 单任务文件数 | ≤ 6 | -| 单任务代码行数 | ≤ 1500 | -| 单任务 Token | ≤ 12K | +| 单任务文件数 | <= 6 | +| 单任务代码行数 | <= 1500 | +| 单任务 Token | <= 12K | | 契约引用 | 只引用锚点，不加载全文 | ## 5. 目录结构 diff --git a/README.md b/README.md index b4348e5..a89d76d 100644 --- a/README.md +++ b/README.md @@ -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` | diff --git a/README.txt b/README.txt index 2f33010..6a54463 100644 --- a/README.txt +++ b/README.txt @@ -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。 diff --git a/contracts/data-models.md b/contracts/data-models.md index 978f5f3..f377aea 100644 --- a/contracts/data-models.md +++ b/contracts/data-models.md @@ -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`** | diff --git a/contracts/model-formats.md b/contracts/model-formats.md index c8db38d..4155755 100644 --- a/contracts/model-formats.md +++ b/contracts/model-formats.md @@ -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. 上传限制 diff --git a/contracts/skeleton-topology.md b/contracts/skeleton-topology.md index d8c9db0..2fd6624 100644 --- a/contracts/skeleton-topology.md +++ b/contracts/skeleton-topology.md @@ -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`）在插值阶段由相邻帧线性补全，不参与代价计算。 diff --git a/contracts/websocket-keypoints.md b/contracts/websocket-keypoints.md index fd40f48..ce1ec53 100644 --- a/contracts/websocket-keypoints.md +++ b/contracts/websocket-keypoints.md @@ -27,7 +27,7 @@ ws://: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 ``` diff --git a/tasks/002-camera-x.md b/tasks/002-camera-x.md index ae89b6a..289d5e6 100644 --- a/tasks/002-camera-x.md +++ b/tasks/002-camera-x.md @@ -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 声明镜像语义 | diff --git a/tasks/004-keypoint-serializer.md b/tasks/004-keypoint-serializer.md index 7544444..6040bb5 100644 --- a/tasks/004-keypoint-serializer.md +++ b/tasks/004-keypoint-serializer.md @@ -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 循环内零对象分配 diff --git a/tasks/006-connect-ui.md b/tasks/006-connect-ui.md index 7d918ee..0f16c69 100644 --- a/tasks/006-connect-ui.md +++ b/tasks/006-connect-ui.md @@ -37,7 +37,7 @@ HTTP 端点发现。因此： | 项 | 说明 | |--|--| | IP / 端口 | 默认 8765，与契约一致 | -| 分辨率 | 480×360 / 640×480 / 1280×720 | +| 分辨率 | 480x360 / 640x480 / 1280x720 | | 目标帧率 | 写入 hello 的 targetFps | | 镜像画面 | 写入 flags.bit0 | | 仅上半身模式 | 写入 flags.bit2 | diff --git a/tasks/008-about-page.md b/tasks/008-about-page.md index b2e1825..5424981 100644 --- a/tasks/008-about-page.md +++ b/tasks/008-about-page.md @@ -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。