# opendance-android

OpenDance Studio **阶段三**：Android 辅助 App（Kotlin + MediaPipe 端侧推理）。

> **状态：占位仓库**。按《DSH 开发文档：OpenDance Studio》的开发顺序
> （Web 服务端 → Windows 客户端 → Android 辅助 App），本仓库将在阶段二
> （`opendance-windows`）冻结 WebSocket 关键点协议后开始开发。

## 计划技术栈

| 组件 | 选型 |
|---|---|
| 语言 | Kotlin |
| 相机 | CameraX (Apache 2.0) |
| 推理 | MediaPipe Pose (Apache 2.0) |
| 通信 | OkHttp WebSocket (Apache 2.0) |
| UI | Jetpack Compose (Apache 2.0) |

## 计划任务

`T-AND-001` 骨架 → `T-AND-002` CameraX 采集 → `T-AND-003` MediaPipe Pose 推理 →
`T-AND-004` 33 点 → 239 字节帧序列化 → `T-AND-005` WebSocket 推流 + 自动重连 →
`T-AND-006` 连接页 + 主机发现 → `T-AND-007` 运行页 + 状态指示 →
`T-AND-008` 关于页 + 开源声明 → `T-AND-009` APK 打包

## 依赖的契约（已冻结于 opendance-web，v0.1.0）

- `contracts/websocket-keypoints.md` — **239 字节关键点帧**编码规则（本端为发送方）
  - 帧头 8 字节：`magic(u16)=0x4F44` + `version(u8)=1` + `flags(u8)` + `frame_id(u32)`
  - 33 点 × 7 字节：`x(i16) y(i16) z(i16) conf(u8)`，小端序，归一化系数 32767
  - 文本控制帧：`hello` / `welcome` / `config` / `stats` / `bye`
- `contracts/skeleton-topology.md` — MediaPipe 33 点顺序与坐标语义（**顺序一旦冻结不得重排**）
- `contracts/open-source-credits.md` — 关于页必须展示的开源声明（三端共用）

契约地址：https://gitea.kasugano.cn/zijunchiang/opendance-web/src/branch/main/contracts

参考实现：`opendance-web/web-server/src/preprocess/keypoint-codec.ts` 中的
`encodeBinaryFrame()` 即本端序列化器的权威参考。

**任何跨端契约变更必须先回到 `opendance-web` 修改 `contracts/` 并提升版本**，
再在本仓库创建适配任务。

## 关键约束

- 仅使用 MediaPipe 33 点拓扑，**不使用 SMPL**（规避非商用许可限制）
- 本端不做评分与渲染：只负责采集、端侧推理、编码、推流
- 视频帧不离开设备，仅发送 33 个关键点
- 发布产物必须包含关于页开源声明