README.md

---

title: GameMaster Mocap
emoji: 🕺
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.31.0
app_file: app.py
python_version: "3.12"

---

# 🎭 MotionBERT MoCap Studio

Convert any single-person video into a full-body **motion capture animation** exported as:

| File | Use |
|------|-----|
| `motion_capture.glb` | Blender armature import / three.js / Godot import |
| `animation.tres` | Godot 4 AnimationLibrary — text resource |
| `animation.res` | Godot 4 AnimationLibrary — binary resource |

> ⏱ **CPU space**: processing takes ~3-8 minutes per video depending on length.  
> Upload a short clip (5-15 seconds) for the fastest results.

---

## Pipeline

| Step | Component |
|------|-----------|
| 1 | Frame extraction — up to 243 frames at uniform stride |
| 2 | Person detection — DETR (`facebook/detr-resnet-50`) every 15 frames |
| 3 | 2-D pose — ViTPose (`usyd-community/vitpose-base-simple-coco`) |
| 4 | 3-D lift — MotionBERT DSTformer (`walterzhu/MotionBERT`) |
| 5 | Export — GLB skeleton + Godot 4 `.tres` / `.res` |

---

## Bone Hierarchy (17 bones)

```
Hips  ← root
├── Spine
│   └── Chest
│       ├── Neck → Head
│       ├── LeftUpperArm → LeftLowerArm → LeftHand
│       └── RightUpperArm → RightLowerArm → RightHand
├── LeftUpperLeg → LeftLowerLeg → LeftFoot
└── RightUpperLeg → RightLowerLeg → RightFoot
```

---

## Using in Godot 4

```gdscript
var lib := load("res://animation.tres") as AnimationLibrary
$AnimationPlayer.add_animation_library("mocap", lib)
$AnimationPlayer.play("mocap/mocap")
```

## Using in Blender

File → Import → glTF 2.0 → select `motion_capture.glb`