Just-Dance-Like

一个基于摄像头人体骨架的舞蹈节奏游戏原型，玩法目标类似 Just Dance： 玩家站在摄像头前跳舞，程序实时提取人体姿态，把最近一段动作和谱面中的 参考动作进行比较，然后给出分数、连击和命中反馈。

当前项目更准确地说是一个 MVP 制谱 + 游玩工具包，不是完整商业游戏：

• 可以从歌曲和参考舞蹈视频生成草稿谱面。
• 可以训练一个小型参考动作库，例如 wave、squat、start。
• 可以用 OpenCV 编辑谱面、改动作名、调整命中窗口。
• 可以在编辑器和游玩运行时直接播放谱面引用的音乐。
• 可以打开摄像头实时识别人体 Pose，并按音乐时间打分。
• 动作编码器使用确定性的姿态、速度和位移描述；动作库会记录编码器版本和参数。

运行原理

歌曲音频 + 参考舞蹈视频
        |
        +--> audio.py                 估计 BPM / 拍点
        +--> skeleton_extractor.py    MediaPipe 提取 33 点人体骨架
        |
        v
auto_choreographer.py                 根据参考视频动作能量生成草稿谱面
        |
        v
editor.py                             手动修谱：插入、删除、重命名动作、调整窗口
        |
        v
play_chart.py / runtime.py            摄像头实时 Pose -> 动作窗口 -> ProtoGCN embedding
        |
        v
scoring.py                            和参考动作库比较，计算相似度 / 节拍误差 / 总分

运行时会在摄像头画面上显示骨架和调试 HUD：

• POSE OK：MediaPipe 在当前帧识别到了人体。
• NO POSE：当前帧没有识别到人体。
• frames=a/b：总帧数中有多少帧成功识别到 Pose。
• window=x/y：当前动作滚动窗口里有多少帧。
• last HIT/MISS：最近一次谱面动作的判定。
• sim：玩家动作和参考动作的余弦相似度。
• beat：当前时间离目标节拍有多近。

项目结构

just_dance_like/
├── README.md
├── requirements.txt
├── create_chart.py              # 从歌曲 + 参考舞蹈视频生成草稿谱面
├── edit_chart.py                # 打开 OpenCV 谱面编辑器
├── train_moves.py               # 从视频片段训练参考动作库
├── play_chart.py                # 摄像头实时游玩 / 打分
├── test_pipeline.py             # 无摄像头、无真实音频的合成端到端测试
├── models/
│   └── pose_landmarker.task     # MediaPipe Pose 模型，需单独下载
├── data/
│   ├── ref_moves/               # 参考动作库，保存 *.movetab.npz
│   ├── charts/                  # 谱面 JSON
│   └── songs/                   # 可放歌曲文件
├── demos/                       # 可放参考动作或参考舞蹈视频
└── package/
    ├── audio.py
    ├── audio_playback.py
    ├── auto_choreographer.py
    ├── chart.py
    ├── editor.py
    ├── move_tables.py
    ├── runtime.py
    ├── scoring.py
    └── lib/
        ├── dataset.py
        ├── protogcn_model.py
        └── skeleton_extractor.py

注意：data/ 下的歌曲、视频、谱面、动作库，以及 models/*.task 通常都被 .gitignore 忽略。换机器或重新 clone 后，需要重新准备这些文件。

环境准备

1. 进入项目目录

所有命令默认在 just_dance_like/ 目录内运行：

cd just_dance_like

2. 创建并激活虚拟环境

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

Windows PowerShell:

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip