diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index 5d721cd73..6b0021f64 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -733,6 +733,8 @@ jobs:
         host: 'linux'
         target: 'desktop'
         arch: 'linux_gcc_64'
+        # qtmultimedia: performance capture (ENABLE_MOCAP, epic #869)
+        modules: 'qtmultimedia'
 
     - name: change folder permissions
       run: |
@@ -781,6 +783,7 @@ jobs:
             -DCMAKE_CXX_FLAGS="-g" -DCMAKE_C_FLAGS="-g" \
             -DENABLE_STABLE_DIFFUSION=ON \
             -DENABLE_ONNX=ON \
+            -DENABLE_MOCAP=ON \
             -DENABLE_AUTO_UPDATER=OFF \
             -DASSIMP_DIR=/usr/local/lib/cmake/assimp-${{ env.ASSIMP_DIR_VERSION }} \
             -DASSIMP_INCLUDE_DIR=/usr/local/include/assimp \
@@ -958,6 +961,8 @@ jobs:
         host: 'linux'
         target: 'desktop'
         arch: 'linux_gcc_64'
+        # qtmultimedia: performance capture (ENABLE_MOCAP, epic #869)
+        modules: 'qtmultimedia'
 
     - name: change folder permissions
       run: |
@@ -1074,7 +1079,8 @@ jobs:
             -DBUILD_QT_MESH_EDITOR=OFF \
             -DENABLE_SENTRY=OFF \
             -DENABLE_PS1_RIP=ON \
-            -DENABLE_ONNX=ON
+            -DENABLE_ONNX=ON \
+            -DENABLE_MOCAP=ON
 
     - name: Run build-wrapper
       env:
@@ -1799,6 +1805,8 @@ jobs:
         target: 'desktop'
         arch: 'clang_64'
         tools: 'tools_cmake'
+        # qtmultimedia: performance capture (ENABLE_MOCAP, epic #869)
+        modules: 'qtmultimedia'
 
     - name: Debug Qt Installation
       run: |
@@ -1885,6 +1893,7 @@ jobs:
             -DCMAKE_CXX_FLAGS="-g" -DCMAKE_C_FLAGS="-g" \
             -DENABLE_STABLE_DIFFUSION=ON \
             -DENABLE_ONNX=ON \
+            -DENABLE_MOCAP=ON \
             -DCMAKE_OSX_ARCHITECTURES="$(uname -m)" \
             -DCMAKE_OSX_DEPLOYMENT_TARGET=11.0 \
             -DASSIMP_DIR=/usr/local/lib/cmake/assimp-${{ env.ASSIMP_DIR_VERSION }} \
@@ -2135,10 +2144,24 @@ jobs:
                 ls -la ${{github.workspace}}/bin/QtMeshEditor.app/Contents/MacOS/
             fi
             
-            # Finally sign the entire app bundle
-            echo "Signing app bundle..."
-            sudo codesign --force --sign - ${{github.workspace}}/bin/QtMeshEditor.app || echo "Failed to sign app bundle (non-fatal)"
-            
+            # Finally sign the entire app bundle WITH the camera/microphone
+            # entitlements (epic #869). NOTE: this is still an ad-hoc signature
+            # (`--sign -`); macOS only PROMPTS for camera access when the app
+            # is signed with a real Apple Developer ID + notarized. Until this
+            # pipeline gains a Developer ID cert (secret) + notarization step,
+            # the live-camera capture will be blocked on end-user machines the
+            # same way it is on an ad-hoc dev build (the CLI `qtmesh mocap`
+            # video path and file-based capture are unaffected). The
+            # entitlements + Info.plist NSCameraUsageDescription are in place so
+            # that flipping to a Developer ID signature is the ONLY remaining
+            # step to enable the prompt. See docs/MOCAP.md.
+            echo "Signing app bundle (with camera entitlements)..."
+            ENT="${{github.workspace}}/cfg/QtMeshEditor.entitlements"
+            sudo codesign --force --sign - --entitlements "$ENT" \
+                ${{github.workspace}}/bin/QtMeshEditor.app \
+                || sudo codesign --force --sign - ${{github.workspace}}/bin/QtMeshEditor.app \
+                || echo "Failed to sign app bundle (non-fatal)"
+
             echo "Code signing process completed"
             
             # Verify the signing
diff --git a/.gitignore b/.gitignore
index d704d1614..9a56429a7 100755
--- a/.gitignore
+++ b/.gitignore
@@ -96,6 +96,7 @@ docs/*
 !docs/IMAGE_TO_3D_QUALITY.md
 !docs/TRIPOSG_EXPORT_NOTES.md
 !docs/MESH_SEGMENTATION_STRATEGY.md
+!docs/MOCAP.md
 !docs/FACE_RIG.md
 !docs/FACE_RIG_SPIKE.md
 !docs/TELEMETRY.md
@@ -157,3 +158,6 @@ __pycache__/
 !docs/img/twist_bar_90_lbs.png
 !docs/img/twist_bar_90_lbs_vp.png
 !docs/img/twist_bar_90_dqs_vp.png
+!docs/MOCAP_SPIKE.md
+.mocap_work/
+.venv-mocap/
diff --git a/CLAUDE.md b/CLAUDE.md
index a65d61dd5..ff0f77f59 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -157,6 +157,11 @@ qtmesh segment tree.glb --category vegetation  # force a category (skip the poin
 qtmesh segment car.glb --category vehicle      # vehicle_body/wheel/window/wing/rotor; `building` = wall/roof/window/door/chimney/foundation
 qtmesh segment model.fbx --no-model --up-axis y  # force the deterministic geometric fallback (skip the ONNX models; auto → body)
 qtmesh segment rigged.fbx --dump-training-data sample.json  # mine EXACT rig-prior labels from a SKINNED mesh → training sample (#410; feed to export-meshseg-onnx.py --real-data)
+qtmesh mocap talk.mp4 --face --mesh avatar.glb -o out.glb    # performance capture (#869, needs -DENABLE_MOCAP): facial expressions -> ARKit-blendshape weight keyframes + head rotation (Head bone or node); models download on first use
+qtmesh mocap dance.mp4 --body --mesh rigged.fbx -o out.glb   # full-body pose -> skeletal clip on the humanoid rig (root locked; --algo sam3dbody|pose-ik, sam3dbody falls back to pose-ik while its checkpoints are gated; --no-model forces the fallback)
+qtmesh mocap take.mp4 --face --body --mesh char.glb -o out.glb  # both in one decode pass ("<clip>_Body" for the body clip)
+qtmesh mocap clip.mp4 --face --mesh head.glb --map overrides.json --no-head --json  # custom channel mapping sidecar; JSON report (matched/unmatched channels always listed)
+qtmesh mocap x.mp4 --face --mesh m.glb --frames-dir frames/  # image-sequence input (headless CI/debug; no video decode)
 qtmesh cloud login                            # device flow (prints URL + code); stores session locally
 qtmesh cloud login --api-key <token>          # direct API-key login (CI)
 qtmesh cloud logout                           # revoke + clear saved session
@@ -177,7 +182,7 @@ qtmesh ps1 dump-vram game.cue --bios scph1001.bin --frames 300 -o vram.png  # sn
 #   xvfb-run -a qtmesh ps1 capture game.cue --bios scph1001.bin -o out.gltf
 ```
 
-CLI mode is activated by: (1) invoking via the `qtmesh` symlink, (2) passing `--cli`, or (3) using a recognized subcommand (`info`, `fix`, `convert`, `anim`, `validate`, `lod`, `pose`, `turntable`, `isometric`, `scan`, `material`, `hdri`, `light`, `pack-textures`, `normal-from-height`, `atlas`, `atlas-apply`, `memory`, `analyze`, `vertex-cache`, `decimate`, `optimize`, `uv`, `retopo`, `skin`, `rig`, `facerig`, `segment`, `generate3d`, `ps1`, `cloud`) as the first argument. Use `--verbose` to see Ogre/engine debug output. Use `--no-telemetry` to permanently opt out of anonymous usage data collection.
+CLI mode is activated by: (1) invoking via the `qtmesh` symlink, (2) passing `--cli`, or (3) using a recognized subcommand (`info`, `fix`, `convert`, `anim`, `validate`, `lod`, `pose`, `turntable`, `isometric`, `scan`, `material`, `hdri`, `light`, `pack-textures`, `normal-from-height`, `atlas`, `atlas-apply`, `memory`, `analyze`, `vertex-cache`, `decimate`, `optimize`, `uv`, `retopo`, `skin`, `rig`, `facerig`, `segment`, `generate3d`, `mocap`, `ps1`, `cloud`) as the first argument. Use `--verbose` to see Ogre/engine debug output. Use `--no-telemetry` to permanently opt out of anonymous usage data collection.
 
 If Xcode SDK is updated, clear CMake cache (`rm build_local/CMakeCache.txt`) and reconfigure.
 
@@ -340,6 +345,17 @@ The animation pipeline started skeleton-only; the #517 epic broadens it. Slices
 - **ScanEngine** (`src/ScanEngine.h/cpp`): Directory scanner for 3D asset linting. Loads every asset through `MeshImporterExporter` (the editor's own loader) and walks the resulting Ogre scene with `CLIPipeline::extractMeshInfo` — the same extractor `MeshInfoOverlay` uses, so the scan, the CLI `info` subcommand and the in-app overlay all report identical counts for the same asset. Redundant-keyframe analysis (and the `--fix` write-back since slice C4) goes through `AnimationMerger::analyzeRedundantKeyframes` / `simplifyAnimation`, the same code path as `qtmesh anim --simplify` and the Inspector "Simplify" button. The fix path re-exports via `MeshImporterExporter::exporter` for every supported format (FBX/glTF/glb/DAE/OBJ/PLY/STL/.mesh) — no `Assimp::Exporter`. ACMR is folded into the same Ogre walk so each file is loaded once per scan. Assimp's only remaining role is a no-process `ReadFile` to enumerate `aiMaterial::GetTexture` references that Ogre's TUS-name walk wouldn't see when a referenced texture file is missing on disk (needed for `require_textures_exist`). Quality rules driven by the Ogre walk: `max_texture_resolution` (largest texture dimension cap), `require_uv_channels` (per-submesh UV-set minimum), `detect_zero_weight_bones` (Mixamo bloat — bones with no vertex weights), `detect_overlapping_uvs_pct` (UV0 AABB sweep — lightmap quality), `detect_non_manifold_edges_pct` (edges shared by != 2 faces — boolean / printing safety). Enumerates files via glob patterns, evaluates configurable rules, produces text/JSON/SARIF reports. Per-file cleanup happens in `clearOgreSceneForScanImport` which destroys scene nodes and flushes MeshManager / SkeletonManager so a 1000-asset scan doesn't accumulate state.
 - **ScanConfig** (`src/ScanConfig.h/cpp`): Config loader for `qtmesh.yml`/`.json`. Includes a minimal YAML parser for the specific config schema (scalars, inline/block lists, one level of section nesting). Supports scan paths, rule configuration, fix behavior, and report output settings.
 
+### Performance capture (epic #869, `ENABLE_MOCAP`)
+
+Video/webcam -> facial morph + head + skeletal body animation, built on the existing ONNX/model-download/retarget/morph-keyframe infrastructure. Everything lives in `src/Mocap/`; the CMake flag `ENABLE_MOCAP` (default OFF; ON for macOS/Linux release + the Linux test lane) requires `ENABLE_ONNX` and pulls in **Qt6::Multimedia** (a new dependency — Windows/MinGW pending verification, so OFF there). Non-mocap builds print "rebuild with -DENABLE_MOCAP" on every surface.
+
+- **VideoFrameSource** (`src/Mocap/VideoFrameSource.{h,cpp}`): the frame abstraction — `FileFrameSource` (QMediaPlayer+QVideoSink, targetFps decimation, playback-driven), `CameraFrameSource` (QCamera, device enumeration, latest-wins `FrameMailbox` so live inference never falls behind), `ImageSequenceFrameSource` (headless test double / CLI `--frames-dir`). `FrameDecimator`/`FrameMailbox` are pure + tested.
+- **FaceCapPredictor** (ONNX consumer #9): 3 sessions (BlazeFace detector 128² [-1,1] -> Face Mesh V2 rotated 256² crop [0,1] -> 478 landmarks -> 146-subset px coords -> 52 blendshape scores) with detector-skip tracking (next ROI from previous landmarks). **PoseCapPredictor** (consumer #10): BlazePose detector+landmarks -> 33 world landmarks; tracking from the model's aux alignment landmarks. Both download to `AppData/ai_models/mocap/{face,pose}/` (`QTMESH_MOCAP_MODEL_BASE_URL` / `ai/mocapModelBaseUrl` / `QTMESH_MOCAP_NO_DOWNLOAD`). The exact pre/post-processing contract (anchors, letterbox, weighted NMS, **cv2-integer-index plain bilinear — never antialiased**, projection) was parity-proven in the Slice A spike: `docs/MOCAP_SPIKE.md`, `scripts/export-facecap-onnx.py` (converts AND asserts parity ≤0.6px/≤0.015 blendshape/≤1cm world).
+- **Pure-data core** (all headless-tested): `FaceCapGeom` (letterbox/anchors/decode/NMS/ROI/crop/projection), `FaceCapPose` (Horn quaternion weighted rigid fit + embedded canonical face model — no Eigen), `FaceCapMapper` (ARKit-52 -> mesh target names, side-suffix normalization + alias table + JSON override; unmatched ALWAYS reported), `OneEuroFilter` (scalar + hemisphere-aligned quat), `PoseIKSolver` (33 world landmarks -> 22 canonical WORLD quats; torso basis + parallel-transported limb twist reference — continuous, no candy-wrap), `FaceCapCanonicalData.h` (generated constants).
+- **MocapRecorder** (the Ogre-touching piece): `recordFace` writes weight keys via `MorphAnimationManager::writeWeightKeyOn` (the entity-explicit static the #519 path now delegates to) with epsilon suppression + gap hold-keys; head deltas (neutral = first confident frame) land on the Head bone (`<clip>_Head` on the MESH skeleton) or node TRS. `recordBody` feeds `[frame][22]` world quats into `AnimationMerger::applyMotionClip(worldFrame=true)` — the #411 retarget, no fork. `RecordMocapClipCommand`/`RecordBodyClipCommand` make a take ONE undo step (keyframe-level snapshots).
+- **MocapController** (QML_SINGLETON, `PropertiesPanel 1.0`): live mode — camera -> mailbox -> inference worker thread -> queued samples -> main-thread live drive (morph `setWeight` + manual Head bone) with EXACT snapshot/restore (weights, bone state, enabled AnimationStates) around the preview session. Panel: `qml/PropertiesPanel.qml` "Performance Capture" section (Animation-mode Mode Tools). SAM 3D Body is the declared body quality path but its checkpoints are HF-gated — dispatch falls back to pose-ik with `algorithmUsed`/`fallbackReason` until the export is hosted (decision record in `THIRD_PARTY_AI_MODELS.md`).
+- **Surfaces**: CLI `qtmesh mocap` (`src/Mocap/MocapCLI.cpp`, the SceneLightsCLI pattern); MCP `capture_face_from_video`/`capture_body_from_video` (heavy) + `list_capture_devices`/`start_live_capture`/`stop_live_capture` (GUI-attached). Sentry `ai.assist.mocap_face|mocap_body|mocap_live`; gamification cluster `mocap` (cloud-side `DISCOVERY_FEATURES` coordination required). Hosting: `scripts/upload-mocap-models.sh` -> HF models repo `mocap/{face,pose}/` (+ Apache NOTICE). User guide: `docs/MOCAP.md`.
+
 ### PS1 formats (static) and runtime extraction (experimental)
 
 - **Static parsers** (`src/PS1/`): `PS1TMD`, `PS1TIM`, `PS1RSD`, `PS1PLY`, `PS1MAT` for known PlayStation mesh/texture formats.
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 7d40753f4..ca828ea0b 100755
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -324,6 +324,29 @@ else()
     message(STATUS "Alembic vertex-animation import disabled (VAT_POSE playback still available)")
 endif()
 ##############################################################
+#  Performance capture — video/webcam mocap (epic #869)
+##############################################################
+# Slice B (#871): brings in Qt Multimedia (camera + video decode) and the
+# src/Mocap/ frame-source layer. Default OFF: Qt Multimedia is a new runtime
+# dependency (FFmpeg backend) that packaging has to carry per platform. The
+# ONNX predictors (Slices C/E) additionally require ENABLE_ONNX; requiring it
+# here keeps a single "mocap build" configuration instead of a half-working
+# one. Non-mocap builds print "rebuild with -DENABLE_MOCAP" on every surface.
+option(ENABLE_MOCAP "Enable performance capture (video/webcam mocap)" OFF)
+
+if(ENABLE_MOCAP)
+    if(NOT ENABLE_ONNX)
+        message(FATAL_ERROR "ENABLE_MOCAP requires ENABLE_ONNX (the face/pose "
+                "predictors run on ONNX Runtime). Configure with "
+                "-DENABLE_ONNX=ON -DENABLE_MOCAP=ON.")
+    endif()
+    find_package(Qt6 REQUIRED COMPONENTS Multimedia)
+    add_definitions(-DENABLE_MOCAP)
+    message(STATUS "Performance capture enabled (Qt Multimedia ${Qt6Multimedia_VERSION})")
+else()
+    message(STATUS "Performance capture disabled (rebuild with -DENABLE_MOCAP=ON -DENABLE_ONNX=ON)")
+endif()
+##############################################################
 #  PS1 runtime geometry extraction (experimental)
 ##############################################################
 option(ENABLE_PS1_RIP "Enable experimental PS1 runtime geometry extraction" OFF)
diff --git a/DEBIAN-control.in b/DEBIAN-control.in
index 68fd1dbd9..63ff981dd 100644
--- a/DEBIAN-control.in
+++ b/DEBIAN-control.in
@@ -6,7 +6,7 @@ Installed-Size: 757000
 Architecture: amd64 
 Bugs: https://github.com/fernandotonon/QtMeshEditor/issues
 Homepage: https://github.com/fernandotonon/QtMeshEditor 
-Depends: libxcb-cursor0, libqt6core6, libqt6gui6, libqt6widgets6, libqt6network6, libqt6opengl6, libqt6qml6, libqt6quick6
+Depends: libxcb-cursor0, libqt6core6, libqt6gui6, libqt6widgets6, libqt6network6, libqt6opengl6, libqt6qml6, libqt6quick6, libqt6multimedia6
 Maintainer: Fernando Tonon de Rossi <tonon.fernando@hotmail.com> 
 Description: Free 3D asset tool for indie game developers
  Merge Mixamo animations, convert between 40+ 3D formats, edit materials
diff --git a/README.md b/README.md
index 8ac2ee432..e433ff14b 100755
--- a/README.md
+++ b/README.md
@@ -286,6 +286,7 @@ Split View|Skeleton Animation Controls
 - **Material editor** — visual editing with AI-assisted generation; PBR + HDR/IBL materials look correct on first import (bundled studio HDRI, ACES tonemap, env intensity/tint per material)
 - **Skeleton inspection** — bone weights, debug overlays, animation preview
 - **Scene management** — duplicate (Ctrl+D), group (Ctrl+G), snap, pivot modes
+- **Performance capture** — video/webcam → facial morph animation (ARKit blendshapes), head pose, and full-body skeletal capture onto humanoid rigs; live preview + record in the editor, `qtmesh mocap` on the CLI (`-DENABLE_MOCAP` builds)
 - **AI chat** — natural language scene editing via local LLMs
 - **MCP server** — 57+ tools for AI agents (Claude, Cursor, etc.), including HDR/IBL (`set_hdr_environment`, `set_tonemap`, …) and QtMesh Cloud (`cloud_*`)
 - **REST API** — HTTP interface for external automation
diff --git a/THIRD_PARTY_AI_MODELS.md b/THIRD_PARTY_AI_MODELS.md
index 27af2d523..cc53c3569 100644
--- a/THIRD_PARTY_AI_MODELS.md
+++ b/THIRD_PARTY_AI_MODELS.md
@@ -14,7 +14,13 @@ the binary). Attribution + licenses for the models and their training data:
 > [`QtMeshEditor-pbrify-onnx`](https://huggingface.co/fernandotonon/QtMeshEditor-pbrify-onnx),
 > [`QtMeshEditor-realesrgan-onnx`](https://huggingface.co/fernandotonon/QtMeshEditor-realesrgan-onnx),
 > [`QtMeshEditor-u2net-onnx`](https://huggingface.co/fernandotonon/QtMeshEditor-u2net-onnx),
-> [`QtMeshEditor-smolvlm-gguf`](https://huggingface.co/fernandotonon/QtMeshEditor-smolvlm-gguf)
+> [`QtMeshEditor-smolvlm-gguf`](https://huggingface.co/fernandotonon/QtMeshEditor-smolvlm-gguf),
+> and the five performance-capture (#869) MediaPipe graphs
+> [`QtMeshEditor-blazeface-onnx`](https://huggingface.co/fernandotonon/QtMeshEditor-blazeface-onnx),
+> [`QtMeshEditor-facemesh-onnx`](https://huggingface.co/fernandotonon/QtMeshEditor-facemesh-onnx),
+> [`QtMeshEditor-faceblendshapes-onnx`](https://huggingface.co/fernandotonon/QtMeshEditor-faceblendshapes-onnx),
+> [`QtMeshEditor-blazepose-onnx`](https://huggingface.co/fernandotonon/QtMeshEditor-blazepose-onnx),
+> [`QtMeshEditor-poselandmarks-onnx`](https://huggingface.co/fernandotonon/QtMeshEditor-poselandmarks-onnx)
 > (plus the in-house
 > [`QtMeshEditor-rmib-inbetween`](https://huggingface.co/fernandotonon/QtMeshEditor-rmib-inbetween),
 > [`QtMeshEditor-mesh-segmentation`](https://huggingface.co/fernandotonon/QtMeshEditor-mesh-segmentation),
@@ -330,6 +336,65 @@ the binary). Attribution + licenses for the models and their training data:
   2d106det) were rejected — their weights carry research-only / non-commercial
   terms; MediaPipe FaceMesh (Apache-2.0) is the clean choice.
 
+## Performance capture (epic #869)
+
+### MediaPipe Face Landmarker + Pose Landmarker — face/pose capture (#870/#872/#874)
+
+- **Models:** Google MediaPipe `face_landmarker.task` (BlazeFace short-range
+  detector + Face Mesh V2 478-landmark model + 52-blendshape MLP-Mixer) and
+  `pose_landmarker_full.task` (BlazePose detector + 39-landmark model with
+  world coordinates), converted TFLite → ONNX.
+- **License:** **Apache-2.0, code AND models** (Google's MediaPipe release —
+  the stack the entire VTuber ecosystem builds on). Ship the Apache-2.0
+  notice next to the hosted weights.
+- The ONNX export is produced by `scripts/export-facecap-onnx.py` (one-time,
+  offline dev tool — not shipped), which also **asserts numerical parity**
+  against the Python `mediapipe` reference (landmarks ≤ 0.59 px, blendshapes
+  ≤ 0.0148 abs, pose world landmarks ≤ 1.02 cm on the test set). Conversion
+  recipe, pre/post-processing contracts and measured latencies:
+  `docs/MOCAP_SPIKE.md`. The app runs the five graphs via ONNX Runtime,
+  downloading them on first use to `AppData/ai_models/mocap/{face,pose}/`.
+- **Rejected face alternatives:** DECA / EMOCA / SPECTRE (all regress the
+  FLAME 3DMM — research-only license), ARKit (iOS-only), OpenSeeFace (MIT
+  code but weaker blendshape story).
+
+### SAM 3D Body + MHR — body capture quality path (#870/#874) — decision record
+
+- **MHR (Momentum Human Rig)** — the 127-joint parametric rig SAM 3D Body
+  poses — is **Apache-2.0** (https://github.com/facebookresearch/MHR, assets
+  v1.0.1). Skeleton definition (names, hierarchy, pre-rotations, derived rest
+  world pose) extracted to `mhr_skeleton.json` by
+  `scripts/export-bodycap-onnx.py --mhr-assets`. Apache-2.0 permits use,
+  modification, and redistribution (including our derived `mhr_skeleton.json`)
+  for any purpose incl. commercial, provided the LICENSE + NOTICE are retained
+  and modifications are marked — we ship the Apache-2.0 notice next to the
+  derived skeleton on the HF repo. No copyleft, no field-of-use restriction.
+- **SAM 3D Body checkpoints** (`facebook/sam-3d-body-dinov3`, 2.1 GB) are
+  under the **SAM License** (2025-11-19 text reviewed in full, 2026-07-12).
+  **Verdict: PASS with conditions** — usable as an OPTIONAL,
+  downloaded-on-first-use backend, never bundled:
+  - §1.a grants use/reproduction/distribution/modification (ONNX conversion
+    is a permitted modification, not the prohibited "reverse engineering" of
+    §1.b.iv). §1.b.i permits redistributing derivatives **only under the SAM
+    License with a copy attached** — rehosting converted ONNX on our HF repo
+    is compliant with the license file shipped next to the weights.
+  - **No non-commercial clause; model outputs are unrestricted** (§3 only
+    disclaims warranty over outputs). No EU exclusion (unlike Hunyuan3D).
+  - Conditions/risks recorded: the SAM backend is NOT permissive-equivalent —
+    users of that one optional feature are bound by the SAM License
+    (AUP-style trade-controls/military restrictions pass through); Meta may
+    unilaterally amend the terms (§8); upstream access is gated (HF
+    click-through sharing contact info with Meta).
+  - **Status:** checkpoint download blocked pending the gated-access
+    acceptance on the HF model page (our token is not yet on the authorized
+    list). Export recipe proven by the community port
+    (AmmarkoV/SAM3DBody-cpp: DINOv3-H+ backbone ~4.8 GB fp32 + 93 MB decoder
+    → 519 MHR params). Until unblocked the body path ships **MediaPipe Pose +
+    analytic IK only** (Apache-2.0, zero conditions).
+- **Rejected body alternatives:** WHAM / GVHMR / TRAM / 4D-Humans (all regress
+  **SMPL** — weights non-commercial, Meshcapade sells the commercial
+  license), OpenPose (CMU non-commercial), FreeMoCap (AGPL).
+
 All of the above clear QtMeshEditor's permissive-redistribution bar (MIT app,
 distributed via Homebrew / WinGet / Snap / Docker). GPL/CC-BY-NC/unlicensed
 models are deliberately excluded (e.g. RigNet was rejected for #408 — GPL code +
diff --git a/action.yml b/action.yml
index 94880a853..3e86059c5 100644
--- a/action.yml
+++ b/action.yml
@@ -8,7 +8,7 @@ branding:
 
 inputs:
   command:
-    description: 'Subcommand: scan, info, validate, convert, fix, anim, lod, pose, turntable, isometric, generate3d'
+    description: 'Subcommand: scan, info, validate, convert, fix, anim, lod, pose, turntable, isometric, generate3d, mocap'
     required: true
   input-file:
     description: 'Directory or file to scan (relative to workspace). Defaults to . (workspace root).'
diff --git a/cfg/QtMeshEditor.entitlements b/cfg/QtMeshEditor.entitlements
new file mode 100644
index 000000000..4498a5ca1
--- /dev/null
+++ b/cfg/QtMeshEditor.entitlements
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <!-- Performance capture (epic #869) reads the camera for live face/body
+         capture. With the hardened runtime (required for notarization), macOS
+         only presents the camera-permission prompt when the app is signed
+         with this device-camera entitlement. Paired with
+         NSCameraUsageDescription in Info.plist. -->
+    <key>com.apple.security.device.camera</key>
+    <true/>
+    <key>com.apple.security.device.microphone</key>
+    <true/>
+    <!-- Qt/QML + JIT-capable frameworks need these under the hardened runtime
+         so the notarized bundle still launches (V8/QML, plugin loading). -->
+    <key>com.apple.security.cs.allow-jit</key>
+    <true/>
+    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
+    <true/>
+    <key>com.apple.security.cs.disable-library-validation</key>
+    <true/>
+</dict>
+</plist>
diff --git a/docs/MOCAP.md b/docs/MOCAP.md
new file mode 100644
index 000000000..8f442e120
--- /dev/null
+++ b/docs/MOCAP.md
@@ -0,0 +1,120 @@
+# Performance Capture (mocap)
+
+Record a video of yourself — or point a webcam at yourself live — and
+reproduce the performance on a mesh: facial expressions land as morph-target
+weight keyframes, head rotation on the Head bone (or the node for static
+meshes), and full-body pose as a skeletal clip on a humanoid rig. Everything
+is recorded as ordinary animation clips: they play on the timeline, show in
+the dope sheet, undo with a single Ctrl+Z, and export through the normal
+exporters.
+
+Requires a build with `-DENABLE_MOCAP=ON -DENABLE_ONNX=ON` (release macOS +
+Linux builds ship with it; Windows/MinGW is pending Qt Multimedia
+verification). Models (all Apache-2.0 Google MediaPipe conversions, ~31 MB
+total) download on first use to `<AppData>/ai_models/mocap/{face,pose}/`.
+
+## Quick start
+
+```bash
+# facial performance from a video onto an ARKit-blendshape head:
+qtmesh mocap talk.mp4 --face --mesh avatar.glb -o out.glb
+
+# full-body performance onto a rigged humanoid:
+qtmesh mocap dance.mp4 --body --mesh rigged.fbx -o out.glb
+
+# both in one pass over the same video:
+qtmesh mocap take.mp4 --face --body --mesh character.glb -o out.glb
+```
+
+Live mode: **Animation Mode → Mode Tools → Performance Capture** — pick a
+camera, `Preview` drives the selection in real time, `● Record` writes the
+take as a clip (status line shows the result; Ctrl+Z discards it).
+
+## What the mesh needs
+
+- **Face capture** drives **ARKit-style blendshape morph targets**
+  (`jawOpen`, `mouthSmileLeft`, `eyeBlinkRight`, `browInnerUp`, … — the
+  52-name vocabulary MediaPipe/ARKit standardized). Sources of compatible
+  heads: [Ready Player Me](https://readyplayer.me) avatars export all 52;
+  Character Creator / iClone heads use recognized aliases (`Jaw_Open`,
+  `Mouth_Smile_L`, …). You can also author targets manually in the
+  Edit-Mode **Vertex Morph Animation** section.
+  Name matching is forgiving (case/separators/`_L`/`.R` side suffixes all
+  normalize), and **unmatched channels are always reported**, never silently
+  dropped. Custom names bind via a JSON override sidecar:
+
+  ```json
+  { "map": { "jawOpen": "MyJawTarget" }, "ignore": ["tongueOut"] }
+  ```
+
+  passed as `--map overrides.json` (CLI) / `map_path` (MCP).
+
+- **Head pose** needs a bone that resolves as the canonical Head
+  (`Head`, `mixamorig:Head`, …). Static meshes get node-TRS keyframes
+  instead. The take's first confident frame calibrates neutral ("look at
+  the camera at the start"); in live mode the `Neutral` button re-bases it.
+
+- **Body capture** needs a **humanoid skeleton** resolving at least half of
+  the 22 canonical roles (hips/spine/neck/head, both arms, both legs —
+  Mixamo and most generic naming conventions resolve). Unrigged meshes: run
+  `qtmesh rig --skeleton humanoid --skin` first. The root stays locked to
+  the standing pose (v1 accepts some foot slide).
+
+## Backends
+
+- **Face / head / body-fallback**: converted Google MediaPipe models
+  (Apache-2.0), small and fast — the face pipeline runs ~90 fps on an
+  M-series CPU.
+- **Body quality path (`--algo sam3dbody`)**: Meta's SAM 3D Body is wired as
+  the preferred backend but its checkpoints are gated behind a license
+  click-through, so today every request falls back to the analytic
+  **pose-ik** backend with `algorithmUsed`/`fallbackReason` in the report.
+  See `THIRD_PARTY_AI_MODELS.md` for the licensing decision record.
+  `--algo pose-ik` / `--no-model` force the fallback explicitly.
+
+## Tuning
+
+- `--fps N` (default 30): capture rate; video frames are decimated to it.
+- `--smooth-cutoff HZ` (default 1.0) / `--no-smooth`: One-Euro filter
+  minimum cutoff — lower is smoother at rest, `beta` tracks fast motion.
+  The live panel exposes the same smoothing.
+- `--clip-name NAME`: default `FaceCap` / `BodyCap` (`<name>_Head` for the
+  head track, `<name>_Body` when `--face --body` run together).
+- `--frames-dir DIR`: use an image sequence instead of a video (headless
+  debugging/CI; no video decode involved).
+- Model base URL override: `QTMESH_MOCAP_MODEL_BASE_URL` /
+  `QSettings ai/mocapModelBaseUrl`; offline guard `QTMESH_MOCAP_NO_DOWNLOAD`.
+
+## macOS camera permission
+
+On first **Preview**, macOS asks to allow camera access; click Allow and the
+app then appears under System Settings → Privacy & Security → Camera. For the
+prompt to appear the app must be **signed with an Apple Developer ID and
+notarized** — macOS silently denies camera access to ad-hoc-signed apps
+(no dialog, and the app never shows in the Camera list). The entitlements
+(`cfg/QtMeshEditor.entitlements`) and `NSCameraUsageDescription` are in place,
+so an official notarized release build prompts normally; a locally-built /
+ad-hoc dev build will NOT get the prompt. If you hit that on a dev build, use
+the file-based capture (`qtmesh mocap <video>`) instead — it needs no camera
+permission and exercises the identical pipeline.
+
+## Known limitations (v1)
+
+- Single person per frame; the highest-scoring detection wins.
+- Head pose is camera-relative — walking around the camera reads as head
+  rotation. Keep the camera static.
+- Body root is locked (no root motion); some foot slide is expected.
+- Live mode drives face, head, and (humanoid rig) body; the SAM 3D Body
+  quality backend is offline-only (CLI/MCP), body-live uses pose-ik.
+- Live camera needs a notarized build on macOS (see above); the CLI/MCP
+  video paths work regardless.
+- Video decode is playback-driven (a 60 s video takes 60 s to capture).
+- Reimporting an exported glTF loses morph-target NAMES (they come back as
+  `Shape_N` — an Assimp exporter gap); re-capturing onto a reimported mesh
+  needs a `--map` sidecar.
+
+## MCP tools
+
+`capture_face_from_video`, `capture_body_from_video` (heavy, file in /
+scene-or-file out), `list_capture_devices`, `start_live_capture`,
+`stop_live_capture` (GUI-attached sessions only).
diff --git a/docs/MOCAP_SPIKE.md b/docs/MOCAP_SPIKE.md
new file mode 100644
index 000000000..79340c178
--- /dev/null
+++ b/docs/MOCAP_SPIKE.md
@@ -0,0 +1,194 @@
+# Performance capture — Spike Findings & Contracts (#869 / slice A #870)
+
+**Epic:** [#869 — AI: Performance capture: video/webcam → facial morph + skeletal body animation](https://github.com/fernandotonon/QtMeshEditor/issues/869)
+**Slice:** [#870 — Spike: model conversion + licensing due diligence](https://github.com/fernandotonon/QtMeshEditor/issues/870) (de-risk first)
+**Status:** Spike — **GO** for the face path and the MediaPipe-Pose-IK body
+fallback (both risks fully retired, parity proven). SAM 3D Body: **license
+passes with conditions**, export recipe proven by a community port, but the
+checkpoint download is **gated** behind a per-account HF click-through we have
+not completed yet — Slice E starts with Pose-IK and lights the SAM backend up
+when access is granted (the UniRig "plumbing first, hosting later" precedent).
+
+---
+
+## TL;DR
+
+- **MediaPipe → ONNX conversion — DONE, parity proven.** All five TFLite
+  models (face detector / face landmarks / face blendshapes / pose detector /
+  pose landmarks) convert with `tf2onnx` and load under ONNX Runtime.
+  `scripts/export-facecap-onnx.py` converts AND asserts parity against the
+  Python `mediapipe` reference in one run:
+  - face landmarks: worst **0.59 px** (target ≤ 2 px), typical 0.01–0.12 px mean
+  - blendshapes: worst **0.0148** abs (target ≤ 0.02), typical ≤ 0.003 mean
+  - pose world landmarks: worst **1.02 cm** (target ≤ 2 cm)
+- **Latency (M-series CPU, ONNX Runtime CPU EP, detector every frame):**
+  face full pipeline **11.2 ms/frame (~89 fps)**, pose full **17.2 ms (~58 fps)**.
+  Live-mode ≥15 fps target clears with 5× headroom before detector-skip.
+- **Model sizes:** face 6.4 MB total (0.4 + 4.9 + 1.1), pose 24.7 MB
+  (11.9 + 12.8). Trivial hosting/download.
+- **Licenses:** all five MediaPipe models Apache-2.0 (code AND weights).
+  MHR rig definition Apache-2.0. SAM 3D Body weights under the **SAM License**
+  — verdict + conditions in `THIRD_PARTY_AI_MODELS.md`.
+- **MHR skeleton — DONE.** 127-joint definition (names, hierarchy,
+  translation offsets, pre-rotations, derived rest world rotations/positions)
+  extracted from the Apache-2.0 `mhr_model.pt` by
+  `scripts/export-bodycap-onnx.py --mhr-assets` → `mhr_skeleton.json`.
+
+---
+
+## Conversion recipe (pinned versions)
+
+Python 3.12 venv (arm64): `mediapipe 0.10.35`, `tensorflow 2.21.0`,
+`tf2onnx 1.17.0`, `onnx 1.22.0`, `onnxruntime 1.27.0`, opencv (mediapipe dep).
+
+```bash
+# .task bundles are zips of TFLite models (Apache-2.0):
+# https://storage.googleapis.com/mediapipe-models/face_landmarker/face_landmarker/float16/1/face_landmarker.task
+# https://storage.googleapis.com/mediapipe-models/pose_landmarker/pose_landmarker_full/float16/1/pose_landmarker_full.task
+python scripts/export-facecap-onnx.py \
+    --face-task .mocap_work/models/face_landmarker.task \
+    --pose-task .mocap_work/models/pose_landmarker_full.task \
+    --images .mocap_work/images --out-dir .mocap_work/out
+```
+
+Three conversion gotchas, all handled inside the script:
+
+1. **`pose_detector.tflite` has fp16 block-sparse weights behind DENSIFY ops**
+   which tf2onnx cannot parse (`ValueError: cannot reshape array...`). Fix:
+   run the TFLite interpreter with `experimental_preserve_all_tensors=True`
+   **and `BUILTIN_WITHOUT_DEFAULT_DELEGATES`** (XNNPACK folds DENSIFY away and
+   `get_tensor()` then reads garbage — this cost an hour), capture each
+   DENSIFY output, rewrite the flatbuffer dense, drop the DENSIFY ops.
+2. **`face_blendshapes.tflite` (MLP-Mixer) converts but tf2onnx's optimizer
+   emits a graph ORT rejects** (transpose optimizer breaks a LayerNorm Mul →
+   `ShapeInferenceError`). Fix: convert that model with optimizers disabled
+   (auto-fallback in `convert_with_fallback`).
+3. **Resampling fidelity is the parity maker-or-breaker**: PIL's antialiased
+   BILINEAR gave 2.5 px / 0.31-blendshape errors on a rotated face; switching
+   letterbox + rotated-crop to cv2 `warpAffine` (plain bilinear, exact float
+   matrices, BORDER_ZERO — what MediaPipe itself does) collapsed errors to
+   0.01 px. **Slice C must use non-antialiased bilinear in C++.**
+
+## The pre/post-processing contract (what Slice C implements)
+
+Machine-readable copy: `mocap_contract.json` (written next to the converted
+models). Landmark/blendshape name tables live in the script constants.
+
+### Face (three sessions)
+
+1. **Detector** (BlazeFace short-range): letterbox (keep aspect, centre, zero
+   border) to **128×128**, RGB `/127.5 - 1` → `regressors [1,896,16]`,
+   `classificators [1,896,1]`. SSD anchors: strides `[8,16,16,16]`,
+   min/max scale 0.1484375/0.75, offset 0.5, fixed size, interpolated aspect
+   1.0 → 896 anchors (each `[cx,cy]`). Decode: `xy = raw/128 + anchor`,
+   `wh = raw/128`; 6 keypoints (right eye, left eye, nose, mouth, right ear,
+   left ear) same decode; score `sigmoid(clip(raw,-100,100))`, threshold 0.5,
+   **weighted** NMS at IoU 0.3. Un-letterbox all coords.
+2. **ROI**: rotation `θ = normalize(-atan2(-(eyeL.y-eyeR.y), eyeL.x-eyeR.x))`
+   (target angle 0, y-down image coords, R(θ)=[[c,-s],[s,c]]); rect = detection
+   box centre, side `max(w,h)·1.5` (square_long → scale). Crop: sample the
+   rotated rect to **256×256**, RGB `/255` (range [0,1]), zero border:
+   `p_img = centre + R(θ)·((u/256-0.5)·w, (v/256-0.5)·h)`.
+3. **Landmarks** (Face Mesh V2): outputs `[N,1,1,1434]` = **478 landmarks ×
+   (x,y,z) in 256-crop pixels** (no attention-refinement assembly needed — V2
+   is single-tensor), `[N,1,1,1]` face-presence **logit** (apply sigmoid),
+   `[N,1]` unused aux. Project back: divide by 256, then
+   `x' = cx + dx·w·cosθ - dy·h·sinθ` (same R(θ)); `z' = z·w`.
+4. **Blendshapes**: gather the 146-landmark subset (indices in the script /
+   contract JSON), feed **pixel coords** `(x·imgW, y·imgH)` as `[1,146,2]` →
+   `[52]` scores in [0,1]. Order = MediaPipe's canonical 52 (ARKit-compatible,
+   `_neutral` first) — the `FaceCap::kBlendshapeNames` vocabulary.
+5. **Head pose**: weighted Kabsch/Umeyama fit of the 468 canonical face model
+   vertices (`canonical_face_model.obj`, cm) onto screen landmarks
+   `(x·W, -y·H, -z·W)` using MediaPipe's 33 Procrustes basis weights
+   (`geometry_pipeline_metadata_landmarks.pbtxt`); keep rotation (+translation),
+   solve-and-discard scale. Convention: +X right, +Y up, camera looks -Z;
+   identity = facing the camera. This intentionally replaces MediaPipe's
+   perspective geometry pipeline — measured delta vs its facial transformation
+   matrix is 4–9.3° on the test images (fine for driving a Head bone; the
+   deltas are systematic, not jitter, and the recorder calibrates the first
+   confident frame as neutral anyway).
+
+**Detector-skip strategy (live mode):** re-run the detector only when the
+landmark presence drops below ~0.5; otherwise derive the next ROI from the
+previous frame's landmarks (bounding box of the 478 points, same 1.5×
+square-long expansion, rotation from eye corners 33→263 — MediaPipe's own
+tracking mode).
+
+### Pose (two sessions)
+
+1. **Detector** (BlazePose): letterbox to **224×224**, `/127.5 - 1` →
+   `[1,2254,12]` + `[1,2254,1]`. Anchors: strides `[8,16,32,32,32]`, same
+   scale params → 2254. 4 keypoints; decode identical to face (scale 224).
+2. **ROI**: centre = keypoint 0 (mid-hip), radius = |kp1 − kp0|,
+   box = square of side `2·radius·1.25`, rotation
+   `θ = normalize(π/2 − atan2(-(dy), dx))` (target angle 90°).
+3. **Landmarks**: crop 256×256, `/255` → `[1,195]` = **39 × (x,y,z,
+   visibility-logit, presence-logit)** in 256-crop pixels (apply sigmoid to
+   vis/presence; landmarks 33..38 are auxiliary — drop), `[1,1]` pose-presence
+   (**already a probability** — do NOT sigmoid, unlike the face flag),
+   `[1,256,256,1]` segmentation (ignore), `[1,64,64,39]` heatmap (ignore),
+   `[1,117]` = **39 × (x,y,z) world landmarks in metres, hip-centred**.
+   Screen landmarks project like face; world landmarks are rotated by the ROI
+   rotation ONLY (no scale/translate).
+4. Landmark index → body part table: 0 nose, 1-6 eyes, 7/8 ears, 9/10 mouth,
+   11/12 shoulders, 13/14 elbows, 15/16 wrists, 17-22 fingers, 23/24 hips,
+   25/26 knees, 27/28 ankles, 29/30 heels, 31/32 foot index (L/R = odd/even).
+
+## Parity numbers (2026-07-12, the script asserts these on every run)
+
+| image | landmarks mean/max (px) | blendshapes mean/max | head-pose Δ |
+|---|---|---|---|
+| portrait.jpg | 0.01 / 0.03 | 0.0002 / 0.0009 | 5.1° |
+| portrait_rotated.jpg | 0.01 / 0.08 | 0.0004 / 0.0016 | 9.3° |
+| portrait_small.jpg | 0.02 / 0.09 | 0.0011 / 0.0080 | 5.4° |
+| face_stylizer_raw_face_demo.png | 0.12 / 0.59 | 0.0026 / 0.0148 | 4.0° |
+| pose.jpg (world landmarks) | 0.61 cm mean / 1.02 cm max | — | — |
+
+Test images are MediaPipe's own Apache-2.0 test assets
+(`storage.googleapis.com/mediapipe-assets`).
+
+## SAM 3D Body (the body quality path)
+
+- **License verdict — PASS with conditions** (full analysis in
+  `THIRD_PARTY_AI_MODELS.md`): the SAM License permits modification (ONNX
+  conversion) and redistribution of derivatives **only under the SAM License
+  with a copy attached** — rehosting converted weights on our HF repo is
+  compliant if the license file ships next to them. No non-commercial clause;
+  outputs unrestricted. Conditions to carry: license text alongside weights +
+  surfaced in-app, AUP-style trade-controls restrictions pass through to
+  users, Meta may unilaterally amend (§8).
+- **Access — BLOCKED on a human click-through**: the HF repo
+  (`facebook/sam-3d-body-dinov3`, 2.1 GB `model.ckpt`) is gated; our token
+  reads repo metadata but file downloads return "not in the authorized list".
+  Action item (Slice E): accept the SAM License on the model page with the
+  project's HF account, then run the export.
+- **Export feasibility — proven by a community port**:
+  [SAM3DBody-cpp / Fast-SAM-3D-Body](https://github.com/AmmarkoV/SAM3DBody-cpp)
+  already runs the model under ONNX Runtime as `backbone.onnx` (DINOv3-H+,
+  ~4.8 GB fp32, image → [1280,32,32] features) + `decoder.onnx` (~93 MB,
+  → [B,1024] token → FFN heads → **519 MHR params: global 6D rotation,
+  per-joint Euler XYZ, shape, hands, face**). ~150–200 ms/frame on an RTX
+  3090 ⇒ seconds/frame on M-series CPU — offline video only, never live.
+  fp16 (~2.4 GB) is the realistic hosting tier (SkinTokens 2.3 GB precedent).
+- **MHR (Momentum Human Rig) — Apache-2.0, extracted**: 127 joints
+  (73 core + twist/null helpers), parent-before-child ordered,
+  `(x,y,z,w)` pre-rotation quats, translation offsets in cm, rest pose ≈
+  A-pose standing at Y-up ~185 cm. `scripts/export-bodycap-onnx.py
+  --mhr-assets` writes `mhr_skeleton.json` with derived
+  `restWorldRotation`/`restWorldPosition` per joint — the `W · clip · W⁻¹`
+  conjugation input Slice E's retarget needs (the `cmuRestWorld` analogue).
+  Momentum rest semantics: `worldRot(j) = worldRot(parent)·preRot(j)`,
+  `worldPos(j) = worldPos(parent) + worldRot(parent)·offset(j)`; animated
+  local rotation composes AFTER the pre-rotation.
+
+## Go/No-Go
+
+- **Face path: GO.** Conversion + parity + latency all retired; Slice C is a
+  wiring job against the contract above.
+- **Pose-IK body fallback: GO.** Models converted with the same parity bar;
+  world landmarks are the IK solver's input (Slice E).
+- **SAM 3D Body backend: GO-when-unblocked.** License compatible (with the
+  redistribution conditions recorded), recipe proven externally, skeleton
+  data in hand. Blocked solely on the gated-access acceptance; Slice E ships
+  Pose-IK first regardless (the epic's degrade-don't-die plan).
diff --git a/qml/PropertiesPanel.qml b/qml/PropertiesPanel.qml
index ea8cfc6af..eb5f786bf 100644
--- a/qml/PropertiesPanel.qml
+++ b/qml/PropertiesPanel.qml
@@ -613,6 +613,37 @@ Rectangle {
                 Component.onCompleted: content = skinningToolsComponent
             }
 
+            // ---- Performance Capture (Animation mode, epic #869) ----
+            // Live webcam capture: preview drives the selected entity's
+            // morph targets, Head bone, and (humanoid rig) full body in real
+            // time via the Face/Head/Body toggles; Record writes ordinary
+            // undoable clips. Gated on a selection with morph targets, a Head
+            // bone, or a humanoid rig; disabled
+            // builds show the rebuild hint inside the section.
+            CollapsibleSection {
+                id: performanceCaptureSection
+                title: "Performance Capture"
+                // hasMeshInSelection (not hasEntitySelection): true also when a
+                // scene NODE with an attached entity is selected — the common
+                // case, since the Scene tree selects nodes. The controller
+                // resolves the same entity via getResolvedEntities(), so the
+                // gate and the capture target stay consistent.
+                sectionVisible: root.currentTab === root.modeToolsTab
+                    && root.modeToolMatches(EditorModeController.AnimationMode)
+                    && PropertiesPanelController.hasMeshInSelection
+                expanded: false
+
+                Component.onCompleted: content = performanceCaptureComponent
+
+                // never leave the camera running when the section disappears
+                // (mode change / deselect) — the AutoRig marker-session
+                // precedent.
+                onSectionVisibleChanged: if (!sectionVisible
+                        && MocapController.available
+                        && MocapController.state !== 0)
+                    MocapController.stopPreview()
+            }
+
             // ---- Rigging (Animation mode) ----
             // Issue #407: native auto-rig. Shown in Animation Mode for a
             // STATIC (skeleton-less) selection — embedding a skeleton is the
@@ -2279,6 +2310,303 @@ Rectangle {
     // Issue #402: auto skin weights. The "Compute Skin Weights…"
     // button opens the dialog; it disables on static meshes
     // (no skeleton). The operation is undoable (Ctrl+Z).
+    Component {
+        id: performanceCaptureComponent
+
+        Column {
+            width: parent ? parent.width : 200
+            padding: 8
+            spacing: 6
+
+            readonly property bool mocapReady: MocapController.available
+            readonly property bool previewing: MocapController.state >= 2
+            readonly property bool recording: MocapController.state === 3
+
+            Text {
+                width: parent.width - 16
+                wrapMode: Text.Wrap
+                opacity: 0.8
+                color: PropertiesPanelController.textColor
+                font.pixelSize: 10
+                text: mocapReady
+                    ? "Webcam performance capture: Preview drives the selection's "
+                      + "morph targets, Head bone, and (on a humanoid rig) full "
+                      + "body live; Record writes undoable clips onto the timeline."
+                    : MocapController.unavailableReason
+            }
+
+            // Face / Head / Body channel toggles. Each is enabled only when the
+            // selection actually supports it; body needs a humanoid rig.
+            Row {
+                width: parent.width - 16
+                spacing: 12
+                visible: mocapReady
+                enabled: MocapController.state === 0  // lock during a session
+
+                InspectorCheckBox {
+                    text: "Face"
+                    checked: MocapController.faceEnabled
+                    enabled: MocapController.matchedChannelCount > 0
+                    onToggled: MocapController.faceEnabled = checked
+                }
+                InspectorCheckBox {
+                    text: "Head"
+                    checked: MocapController.headEnabled
+                    enabled: MocapController.headAvailable
+                    onToggled: MocapController.headEnabled = checked
+                }
+                InspectorCheckBox {
+                    text: "Body"
+                    checked: MocapController.bodyEnabled
+                    enabled: MocapController.bodyAvailable
+                    onToggled: MocapController.bodyEnabled = checked
+                }
+            }
+
+            // device picker + preview toggle
+            Row {
+                width: parent.width - 16
+                spacing: 6
+                visible: mocapReady
+
+                ThemedComboBox {
+                    id: mocapDeviceCombo
+                    width: parent.width - previewBtn.width - 6
+                    height: 26
+                    font.pixelSize: 11
+                    model: MocapController.availableDevices
+                    textRole: "description"
+                    valueRole: "id"
+                    enabled: MocapController.state === 0
+                    Component.onCompleted: MocapController.refreshDevices()
+                }
+
+                Rectangle {
+                    id: previewBtn
+                    width: 70
+                    height: 26
+                    radius: 3
+                    color: previewMa.containsMouse
+                        ? PropertiesPanelController.highlightColor
+                        : PropertiesPanelController.headerColor
+                    border.color: PropertiesPanelController.borderColor
+                    border.width: 1
+                    Text {
+                        anchors.centerIn: parent
+                        color: PropertiesPanelController.textColor
+                        font.pixelSize: 11
+                        text: MocapController.state === 0 ? "Preview" : "Stop"
+                    }
+                    MouseArea {
+                        id: previewMa
+                        anchors.fill: parent
+                        hoverEnabled: true
+                        onClicked: {
+                            if (MocapController.state === 0)
+                                MocapController.startPreview(
+                                    mocapDeviceCombo.currentValue !== undefined
+                                        ? mocapDeviceCombo.currentValue : "")
+                            else
+                                MocapController.stopPreview()
+                        }
+                    }
+                }
+            }
+
+            // Video-file source — the path for macOS where the camera is
+            // blocked/unavailable. Picks a file and drives the selection from
+            // it (same live preview + recording as the webcam).
+            Rectangle {
+                id: loadVideoBtn
+                visible: mocapReady
+                width: parent.width - 16
+                height: 26
+                radius: 3
+                enabled: MocapController.state === 0
+                opacity: enabled ? 1.0 : 0.5
+                color: loadVideoMa.containsMouse
+                    ? PropertiesPanelController.highlightColor
+                    : PropertiesPanelController.headerColor
+                border.color: PropertiesPanelController.borderColor
+                border.width: 1
+                Text {
+                    anchors.centerIn: parent
+                    color: PropertiesPanelController.textColor
+                    font.pixelSize: 11
+                    text: "Load Video…  (use instead of camera)"
+                }
+                MouseArea {
+                    id: loadVideoMa
+                    anchors.fill: parent
+                    hoverEnabled: true
+                    enabled: MocapController.state === 0
+                    onClicked: {
+                        var path = MocapController.openVideoDialog()
+                        if (path && path.length > 0)
+                            MocapController.startPreviewFromVideo(path)
+                    }
+                }
+            }
+
+            // camera preview + HUD
+            Rectangle {
+                width: parent.width - 16
+                height: visible ? 140 : 0
+                visible: mocapReady && MocapController.previewDataUrl !== ""
+                color: "black"
+                radius: 3
+
+                Image {
+                    anchors.fill: parent
+                    anchors.margins: 2
+                    fillMode: Image.PreserveAspectFit
+                    source: MocapController.previewDataUrl
+                    cache: false
+                }
+                // face-detected (top) + body-detected (below, only when body on)
+                Rectangle {
+                    id: faceDot
+                    width: 10; height: 10; radius: 5
+                    anchors.top: parent.top
+                    anchors.right: parent.right
+                    anchors.margins: 6
+                    color: MocapController.faceDetected ? "#4caf50" : "#f44336"
+                }
+                Rectangle {
+                    width: 10; height: 10; radius: 5
+                    anchors.top: faceDot.bottom
+                    anchors.right: parent.right
+                    anchors.topMargin: 4
+                    anchors.rightMargin: 6
+                    visible: MocapController.bodyEnabled
+                    color: MocapController.bodyDetected ? "#2196f3" : "#f44336"
+                }
+                Text {
+                    anchors.bottom: parent.bottom
+                    anchors.left: parent.left
+                    anchors.margins: 4
+                    color: "white"
+                    font.pixelSize: 10
+                    style: Text.Outline
+                    styleColor: "black"
+                    text: MocapController.liveFps.toFixed(0) + " fps"
+                        + (recording
+                           ? "  ● REC " + MocapController.recordingSeconds.toFixed(1) + "s"
+                           : "")
+                }
+            }
+
+            // channel summary
+            Text {
+                width: parent.width - 16
+                wrapMode: Text.Wrap
+                visible: mocapReady && previewing
+                opacity: 0.8
+                color: PropertiesPanelController.textColor
+                font.pixelSize: 10
+                text: {
+                    var parts = []
+                    if (MocapController.faceEnabled && MocapController.matchedChannelCount > 0)
+                        parts.push(MocapController.matchedChannelCount + " morph channels")
+                    if (MocapController.headEnabled && MocapController.headAvailable)
+                        parts.push("Head bone")
+                    if (MocapController.bodyEnabled && MocapController.bodyAvailable)
+                        parts.push("body rig")
+                    var s = "Driving: " + (parts.length ? parts.join(" + ") : "nothing")
+                    // The common confusion: Face is on but the mesh has no
+                    // matching ARKit morph targets, so 51/52 channels can't
+                    // bind. Say what to do instead of just a count.
+                    if (MocapController.faceEnabled
+                        && MocapController.matchedChannelCount === 0)
+                        s += "\n⚠ This mesh has no matching ARKit blendshapes — "
+                           + "the face won't animate. Run “✨ Add ARKit "
+                           + "Blendshapes (AI)” in the Vertex Morph Animation "
+                           + "section first, or uncheck Face."
+                    else if (MocapController.unmatchedChannels.length > 0)
+                        s += " (" + MocapController.unmatchedChannels.length
+                             + " capture channels unmatched)"
+                    return s
+                }
+            }
+
+            // clip name + record controls
+            Row {
+                width: parent.width - 16
+                spacing: 6
+                visible: mocapReady && previewing
+
+                TextField {
+                    id: mocapClipName
+                    width: parent.width - calibrateBtn.width - recordBtn.width - 12
+                    text: MocapController.clipName
+                    font.pixelSize: 11
+                    enabled: !recording
+                    onEditingFinished: MocapController.clipName = text
+                }
+                Rectangle {
+                    id: calibrateBtn
+                    width: 64
+                    height: 26
+                    radius: 3
+                    color: calibrateMa.containsMouse
+                        ? PropertiesPanelController.highlightColor
+                        : PropertiesPanelController.headerColor
+                    border.color: PropertiesPanelController.borderColor
+                    border.width: 1
+                    Text {
+                        anchors.centerIn: parent
+                        color: PropertiesPanelController.textColor
+                        font.pixelSize: 11
+                        text: "Neutral"
+                    }
+                    MouseArea {
+                        id: calibrateMa
+                        anchors.fill: parent
+                        hoverEnabled: true
+                        onClicked: MocapController.calibrateNeutral()
+                    }
+                }
+                Rectangle {
+                    id: recordBtn
+                    width: 70
+                    height: 26
+                    radius: 3
+                    color: recording ? "#b23b3b"
+                        : (recordMa.containsMouse
+                           ? PropertiesPanelController.highlightColor
+                           : PropertiesPanelController.headerColor)
+                    border.color: PropertiesPanelController.borderColor
+                    border.width: 1
+                    Text {
+                        anchors.centerIn: parent
+                        color: recording ? "white" : PropertiesPanelController.textColor
+                        font.pixelSize: 11
+                        text: recording ? "■ Stop" : "● Record"
+                    }
+                    MouseArea {
+                        id: recordMa
+                        anchors.fill: parent
+                        hoverEnabled: true
+                        onClicked: recording ? MocapController.stopRecording()
+                                             : MocapController.startRecording()
+                    }
+                }
+            }
+
+            // status line
+            Text {
+                width: parent.width - 16
+                wrapMode: Text.Wrap
+                visible: mocapReady && MocapController.statusMessage !== ""
+                color: PropertiesPanelController.textColor
+                opacity: 0.9
+                font.pixelSize: 10
+                font.italic: true
+                text: MocapController.statusMessage
+            }
+        }
+    }
+
     Component {
         id: skinningToolsComponent
 
diff --git a/scripts/create-mocap-mirror-repos.sh b/scripts/create-mocap-mirror-repos.sh
new file mode 100755
index 000000000..a92eabbcf
--- /dev/null
+++ b/scripts/create-mocap-mirror-repos.sh
@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+# Create the five dedicated per-graph Hugging Face mirror repos for the
+# performance-capture models (epic #869) and push each .onnx + its own model
+# card. ONE-TIME, run by a maintainer with HF write access.
+#
+# The aggregate repo fernandotonon/QtMeshEditor-models (mocap/{face,pose}/) is
+# the SOURCE OF TRUTH the app downloads from; these mirrors carry standalone
+# model cards for discoverability (the per-model repo convention documented in
+# THIRD_PARTY_AI_MODELS.md and scripts/sync-hf-model-repos.sh). After a
+# re-export + re-upload to the aggregate, refresh weights with
+# scripts/sync-hf-model-repos.sh (the mocap-* mirrors were added there).
+#
+# All five graphs are converted Google MediaPipe models — Apache-2.0 code AND
+# weights.
+#
+# Prereqs:
+#   pip install -U huggingface_hub
+#   hf auth login                  # a token with write access under the owner
+#   OUT_DIR holds face/*.onnx + pose/*.onnx (scripts/export-facecap-onnx.py)
+#
+# Usage:
+#   OUT_DIR=.mocap_work/out ./scripts/create-mocap-mirror-repos.sh
+set -euo pipefail
+
+OWNER="${OWNER:-fernandotonon}"
+OUT_DIR="${OUT_DIR:?set OUT_DIR to the export output dir (face/*.onnx + pose/*.onnx)}"
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+# model-key → "repo-name|local-onnx|upstream-source|one-line-summary"
+make_repo() {
+    local repo="$1" src="$2" card="$3"
+    echo "=== $OWNER/$repo"
+    hf repo create "$OWNER/$repo" --repo-type model -y >/dev/null 2>&1 || true
+    printf '%s\n' "$card" > "$WORK/README.md"
+    hf upload "$OWNER/$repo" "$WORK/README.md" README.md >/dev/null
+    hf upload "$OWNER/$repo" "$src" "$(basename "$src")" >/dev/null
+    echo "    -> https://huggingface.co/$OWNER/$repo"
+}
+
+COMMON_FOOTER='
+## License
+
+Apache-2.0 — this graph is a direct ONNX conversion of a Google
+[MediaPipe](https://developers.google.com/mediapipe) model (Apache-2.0 code
+AND weights). Conversion + numerical-parity proof (vs the Python `mediapipe`
+reference): [`scripts/export-facecap-onnx.py`](https://github.com/fernandotonon/QtMeshEditor/blob/master/scripts/export-facecap-onnx.py),
+contract in [`docs/MOCAP_SPIKE.md`](https://github.com/fernandotonon/QtMeshEditor/blob/master/docs/MOCAP_SPIKE.md).
+
+## How it is used
+
+Mirror of one graph from [`fernandotonon/QtMeshEditor-models`](https://huggingface.co/fernandotonon/QtMeshEditor-models)
+(`mocap/…`), which [QtMeshEditor](https://github.com/fernandotonon/QtMeshEditor)
+downloads on first use for its **Performance Capture** feature (video/webcam →
+facial morph + head + full-body skeletal animation, epic #869). This standalone
+repo is for discoverability; the app fetches from the aggregate repo.'
+
+make_repo "QtMeshEditor-blazeface-onnx" "$OUT_DIR/face/face_detector.onnx" \
+"---
+license: apache-2.0
+tags: [onnx, mediapipe, face-detection, blazeface, qtmesheditor]
+---
+
+# BlazeFace short-range face detector (ONNX)
+
+Google MediaPipe's BlazeFace short-range detector, from the Face Landmarker
+\`.task\` bundle, converted to ONNX.
+
+- **Input** \`input\` \`[1,128,128,3]\` RGB, normalized to \`[-1,1]\`, keep-aspect
+  letterboxed (zero border).
+- **Outputs** \`regressors\` \`[1,896,16]\` (box + 6 keypoints per anchor),
+  \`classificators\` \`[1,896,1]\` (score logits). SSD anchors: strides
+  \`[8,16,16,16]\`, min/max scale 0.1484375/0.75 → 896 anchors; decode + weighted
+  NMS at IoU 0.3.
+- Feeds the face ROI (rotation from the eye keypoints, 1.5× square-long) to the
+  Face Mesh landmark model.
+$COMMON_FOOTER"
+
+make_repo "QtMeshEditor-facemesh-onnx" "$OUT_DIR/face/face_landmarks.onnx" \
+"---
+license: apache-2.0
+tags: [onnx, mediapipe, face-landmarks, face-mesh, qtmesheditor]
+---
+
+# Face Mesh V2 landmark model (ONNX)
+
+Google MediaPipe's Face Landmarks Detector (Face Mesh V2), converted to ONNX.
+
+- **Input** \`[N,256,256,3]\` RGB in \`[0,1]\` — the rotated, cropped face ROI.
+- **Outputs** \`[N,1,1,1434]\` = **478 landmarks × (x,y,z)** in 256-crop pixels,
+  plus a face-presence logit. Landmarks project back through the inverse ROI
+  transform; a 146-landmark subset feeds the blendshape model.
+$COMMON_FOOTER"
+
+make_repo "QtMeshEditor-faceblendshapes-onnx" "$OUT_DIR/face/face_blendshapes.onnx" \
+"---
+license: apache-2.0
+tags: [onnx, mediapipe, blendshapes, arkit, face-capture, qtmesheditor]
+---
+
+# Face blendshapes MLP-Mixer (ONNX)
+
+Google MediaPipe's face blendshape model (MLP-Mixer), converted to ONNX.
+
+- **Input** \`[1,146,2]\` — the 146-landmark subset as **pixel coords**
+  (\`x·imgW, y·imgH\`).
+- **Output** \`[52]\` — **52 ARKit-compatible blendshape scores** in \`[0,1]\`,
+  in MediaPipe order (\`_neutral\`, \`browDownLeft\`, … \`jawOpen\`, …
+  \`mouthSmileLeft/Right\`, … \`eyeBlinkLeft/Right\`, …). These drive ARKit-style
+  morph targets directly.
+
+Converted with tf2onnx optimizers disabled (the optimized graph broke a
+LayerNorm under ONNX Runtime — see the spike doc).
+$COMMON_FOOTER"
+
+make_repo "QtMeshEditor-blazepose-onnx" "$OUT_DIR/pose/pose_detector.onnx" \
+"---
+license: apache-2.0
+tags: [onnx, mediapipe, pose-detection, blazepose, qtmesheditor]
+---
+
+# BlazePose person detector (ONNX)
+
+Google MediaPipe's BlazePose detector, from the Pose Landmarker \`.task\`
+bundle, converted to ONNX.
+
+- **Input** \`[1,224,224,3]\` RGB in \`[-1,1]\`, letterboxed.
+- **Outputs** \`[1,2254,12]\` + \`[1,2254,1]\`. Anchors: strides
+  \`[8,16,32,32,32]\` → 2254. The ROI is centred on the mid-hip keypoint,
+  sized from the hip→scale keypoint distance, target angle 90°, 1.25× square.
+
+The detector ships fp16 **block-sparse** weights behind DENSIFY ops that
+tf2onnx can't parse; the export densifies them via the TFLite interpreter
+first (see the export script).
+$COMMON_FOOTER"
+
+make_repo "QtMeshEditor-poselandmarks-onnx" "$OUT_DIR/pose/pose_landmarks.onnx" \
+"---
+license: apache-2.0
+tags: [onnx, mediapipe, pose-landmarks, blazepose, body-capture, qtmesheditor]
+---
+
+# BlazePose full landmark model (ONNX)
+
+Google MediaPipe's Pose Landmarks Detector (BlazePose full), converted to
+ONNX.
+
+- **Input** \`[1,256,256,3]\` RGB in \`[0,1]\` — the rotated, cropped person ROI.
+- **Outputs** \`[1,195]\` = 39 × (x,y,z,visibility,presence) screen landmarks
+  in 256-crop pixels; \`[1,1]\` pose-presence probability; \`[1,256,256,1]\`
+  segmentation; \`[1,64,64,39]\` heatmap; **\`[1,117]\` = 39 × (x,y,z) WORLD
+  landmarks in metres, hip-centred** (the input to the analytic body-pose /
+  IK solver — landmarks 0–32 are the 33 real body joints).
+$COMMON_FOOTER"
+
+echo "done. Refresh weights later via scripts/sync-hf-model-repos.sh"
diff --git a/scripts/export-bodycap-onnx.py b/scripts/export-bodycap-onnx.py
new file mode 100644
index 000000000..9050dceb9
--- /dev/null
+++ b/scripts/export-bodycap-onnx.py
@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""SAM 3D Body / MHR spike tooling for performance capture (#870 / #874).
+
+ONE-TIME, OFFLINE developer tool — NOT shipped with the app, and the app never
+runs Python. See docs/MOCAP_SPIKE.md for the full spike record and
+THIRD_PARTY_AI_MODELS.md for the SAM License verdict.
+
+WHAT IT DOES TODAY
+  --mhr-assets <dir>   Extract the Momentum Human Rig (MHR, Apache-2.0)
+                       skeleton definition from the released mhr_model.pt
+                       (assets.zip of https://github.com/facebookresearch/MHR,
+                       v1.0.1) into mhr_skeleton.json:
+                         { "joints": [ { "name", "parent",           # index, -1 root
+                                         "translationOffset": [x,y,z],  # cm, parent-relative
+                                         "preRotation": [x,y,z,w],      # parent-relative
+                                         "restWorldRotation": [x,y,z,w],
+                                         "restWorldPosition": [x,y,z] } ] }
+                       Slice E's retarget needs restWorldRotation for the same
+                       W . clip . W^-1 conjugation AnimationMerger::applyMotionClip
+                       does with cmuRestWorld. Momentum rest-pose semantics:
+                         worldRot(j)  = worldRot(parent) * preRotation(j)
+                         worldPos(j)  = worldPos(parent) + worldRot(parent) * translationOffset(j)
+                       (joint local animation rotations compose AFTER the
+                       pre-rotation: local = preRot * eulerXYZ(joint_params)).
+
+  --ckpt <model.ckpt>  SAM 3D Body ONNX export. NOT RUNNABLE YET in this repo:
+                       the checkpoints on HF (facebook/sam-3d-body-dinov3) are
+                       GATED — the account whose token sits in
+                       ~/.cache/huggingface/token must click through the SAM
+                       License acceptance on the model page first (as of
+                       2026-07 our token gets 403 on file downloads). The
+                       community port that proves the export path is
+                       https://github.com/AmmarkoV/Fast-SAM-3D-Body /
+                       SAM3DBody-cpp: backbone.onnx (DINOv3-H+, ~4.8 GB fp32,
+                       [1,3,H,W] -> [1280,32,32] features), decoder.onnx
+                       (~93 MB, 6-layer transformer -> [B,1024] pose token ->
+                       FFN heads -> 519 MHR params: global 6D rotation +
+                       per-joint Euler XYZ + shape + hands + face).
+                       When access is granted, follow that recipe here and
+                       validate against the python inference from
+                       https://github.com/facebookresearch/sam-3d-body.
+
+USAGE
+    python scripts/export-bodycap-onnx.py --mhr-assets .mocap_work/mhr_assets/assets \
+        --out .mocap_work/out/mhr_skeleton.json
+"""
+
+import argparse
+import json
+import os
+import sys
+
+
+def quat_mul(a, b):
+    """(x,y,z,w) Hamilton product a*b."""
+    ax, ay, az, aw = a
+    bx, by, bz, bw = b
+    return (
+        aw * bx + ax * bw + ay * bz - az * by,
+        aw * by - ax * bz + ay * bw + az * bx,
+        aw * bz + ax * by - ay * bx + az * bw,
+        aw * bw - ax * bx - ay * by - az * bz,
+    )
+
+
+def quat_rotate(q, v):
+    qv = (v[0], v[1], v[2], 0.0)
+    qc = (-q[0], -q[1], -q[2], q[3])
+    r = quat_mul(quat_mul(q, qv), qc)
+    return (r[0], r[1], r[2])
+
+
+def extract_mhr_skeleton(assets_dir, out_path):
+    import torch  # local import: only needed for this mode
+
+    # Create the output directory up front — the documented default
+    # (.mocap_work/out/…) does not exist on a fresh checkout, and the json
+    # dump below would otherwise FileNotFoundError after the (slow) load.
+    os.makedirs(os.path.dirname(os.path.abspath(out_path)), exist_ok=True)
+
+    # SECURITY: torch.jit.load deserializes the archive. This is an offline
+    # dev tool and the operator supplies their OWN MHR assets from the
+    # official facebookresearch/MHR release (Apache-2.0), so we load directly;
+    # do NOT point --mhr-assets at an untrusted download.
+    mhr_model = f"{assets_dir}/mhr_model.pt"
+    if not os.path.isfile(mhr_model):
+        sys.exit(f"MHR model not found: {mhr_model} "
+                 f"(pass --mhr-assets pointing at the official MHR v1.0.1 assets)")
+    model = torch.jit.load(mhr_model, map_location="cpu")
+    sk = model.character_torch.skeleton
+    names = list(sk.joint_names)
+    parents = sk.joint_parents.tolist()
+    offsets = sk.joint_translation_offsets.tolist()
+    prerot = sk.joint_prerotations.tolist()  # (x,y,z,w), parent-relative
+    n = len(names)
+    assert len(parents) == len(offsets) == len(prerot) == n
+
+    world_rot = [None] * n
+    world_pos = [None] * n
+    joints = []
+    for j in range(n):
+        p = parents[j]
+        assert p < j, "joints must be parent-before-child ordered"
+        if p < 0:
+            world_rot[j] = tuple(prerot[j])
+            world_pos[j] = tuple(offsets[j])
+        else:
+            world_rot[j] = quat_mul(world_rot[p], tuple(prerot[j]))
+            off = quat_rotate(world_rot[p], tuple(offsets[j]))
+            wp = world_pos[p]
+            world_pos[j] = (wp[0] + off[0], wp[1] + off[1], wp[2] + off[2])
+        joints.append({
+            "name": names[j],
+            "parent": p,
+            "translationOffset": [round(v, 6) for v in offsets[j]],
+            "preRotation": [round(v, 8) for v in prerot[j]],
+            "restWorldRotation": [round(v, 8) for v in world_rot[j]],
+            "restWorldPosition": [round(v, 6) for v in world_pos[j]],
+        })
+
+    doc = {
+        "format": "qtmesh-mhr-skeleton-v1",
+        "source": "facebookresearch/MHR v1.0.1 assets (Apache-2.0)",
+        "units": "cm",
+        "quaternionOrder": "xyzw",
+        "jointCount": n,
+        "joints": joints,
+    }
+    with open(out_path, "w") as f:
+        json.dump(doc, f, indent=1)
+    print(f"{n} joints -> {out_path}")
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--mhr-assets", help="dir containing mhr_model.pt")
+    ap.add_argument("--out", default=".mocap_work/out/mhr_skeleton.json")
+    ap.add_argument("--ckpt", help="SAM 3D Body model.ckpt (gated; see header)")
+    args = ap.parse_args()
+
+    if args.mhr_assets:
+        extract_mhr_skeleton(args.mhr_assets, args.out)
+    if args.ckpt:
+        sys.exit("SAM 3D Body ONNX export: checkpoint access is gated (see the "
+                 "header comment). Accept the SAM License on "
+                 "https://huggingface.co/facebook/sam-3d-body-dinov3 with the "
+                 "HF account of ~/.cache/huggingface/token, then implement the "
+                 "Fast-SAM-3D-Body recipe here (tracked in #874).")
+    if not args.mhr_assets and not args.ckpt:
+        sys.exit("nothing to do: pass --mhr-assets and/or --ckpt")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/export-facecap-onnx.py b/scripts/export-facecap-onnx.py
new file mode 100644
index 000000000..c904cb511
--- /dev/null
+++ b/scripts/export-facecap-onnx.py
@@ -0,0 +1,806 @@
+#!/usr/bin/env python3
+"""Convert MediaPipe Face/Pose Landmarker TFLite models to ONNX, with parity proof (#870).
+
+ONE-TIME, OFFLINE developer tool — NOT shipped with the app, and the app never
+runs Python. The app runs the resulting .onnx files in C++ via ONNX Runtime
+(src/Mocap/FaceCapPredictor.cpp / PoseIK pipeline), downloading them on first
+use to AppData/ai_models/mocap/{face,pose}/.
+
+WHAT IT PRODUCES (in --out-dir, default .mocap_work/out)
+  face/face_detector.onnx      BlazeFace short-range:  in [1,128,128,3] RGB in [-1,1]
+                               out regressors [1,896,16], classificators [1,896,1]
+  face/face_landmarks.onnx     Face Mesh V2:           in [N,256,256,3] RGB in [0,1]
+                               out [N,1,1,1434] (478 xyz landmarks, px in 256-space),
+                                   [N,1,1,1] face-presence logit, [N,1] (unused aux)
+  face/face_blendshapes.onnx   MLP-Mixer blendshapes:  in [1,146,2] (x*W, y*H pixel coords
+                               of the 146-landmark subset), out [52] scores in [0,1]
+  pose/pose_detector.onnx      BlazePose detector:     in [1,224,224,3] RGB in [-1,1]
+                               out [1,2254,12], [1,2254,1]
+  pose/pose_landmarks.onnx     BlazePose full:         in [1,256,256,3] RGB in [0,1]
+                               out [1,195] (39 x,y,z,visibility,presence in 256-space),
+                                   [1,1] pose-presence, [1,256,256,1] seg, [1,64,64,39] heatmap,
+                                   [1,117] world landmarks (39 xyz, metres, hip-centred)
+
+DATA + LICENSE
+  All five models are Google MediaPipe models, Apache-2.0 (code AND weights) —
+  see THIRD_PARTY_AI_MODELS.md. Downloaded .task bundles are zip files
+  containing the TFLite graphs this script converts.
+
+CONVERSION NOTES (discovered empirically, kept for reproducibility)
+  * tf2onnx 1.17.0 + tensorflow 2.21 + python 3.12 work.
+  * pose_detector.tflite ships fp16 block-SPARSE weights behind DENSIFY ops,
+    which tf2onnx cannot parse. densify_tflite() runs the TFLite interpreter
+    with experimental_preserve_all_tensors, captures each DENSIFY output, and
+    rewrites the flatbuffer with dense buffers + the DENSIFY ops removed.
+  * face_blendshapes.tflite converts, but tf2onnx's post-conversion optimizer
+    produces a graph onnxruntime rejects (transpose optimizer breaks a
+    LayerNorm Mul). We convert that model with optimizers DISABLED.
+
+PRE/POST-PROCESSING CONTRACT (the spec Slice C implements in C++; also in
+docs/MOCAP_SPIKE.md):
+  * Detector input: letterbox (keep aspect, centre, pad both sides) to the
+    input size, RGB, normalize to [-1,1] ((v/255)*2-1).
+  * Face SSD anchors: 4 layers, strides [8,16,16,16], 2 anchors on the two
+    16x16 layers' merged... generated by gen_ssd_anchors() below (896 anchors,
+    all 1.0 aspect, fixed size). Pose: 5 layers, strides [8,16,32,32,32]
+    (2254 anchors). Decode: offsets / input_size scaled around anchor centres;
+    score = sigmoid(clip(raw, -100, 100)); weighted NMS at IoU 0.3.
+  * Face ROI: rotation from detector keypoint 0 (right eye) -> 1 (left eye),
+    target angle 0; rect = detection box made square-long then scaled 1.5x.
+  * Pose ROI: centre = detector keypoint 0 (mid-hip), radius = |kp1-kp0|,
+    box = 2*radius square, rotation target angle 90 deg, then scaled 1.25x.
+  * Landmark crop: rotated rect resampled to 256x256, RGB in [0,1].
+  * Landmark decode: xyz / 256 -> normalized crop coords -> rotate/scale back
+    through the ROI transform (landmark projection); z scaled by rect w.
+  * Blendshape input: the 146-subset landmark (x*imgW, y*imgH) pixel coords.
+  * Pose world landmarks: rotate x,y by the ROI rotation only (no scale).
+  * Head pose: weighted Umeyama/Kabsch fit of the 468 canonical-face-model
+    vertices (Procrustes basis weights) against screen landmarks
+    (x*W, -y*H, -z*W); rotation kept, scale discarded. This intentionally
+    replaces MediaPipe's perspective geometry pipeline; parity vs its
+    facial_transformation_matrix is reported in degrees (a few deg is fine).
+
+USAGE (offline, in a venv with mediapipe tensorflow tf2onnx onnx onnxruntime pillow):
+    python scripts/export-facecap-onnx.py \
+        --face-task .mocap_work/models/face_landmarker.task \
+        --pose-task .mocap_work/models/pose_landmarker_full.task \
+        --images .mocap_work/images --out-dir .mocap_work/out
+"""
+
+import argparse
+import json
+import math
+import os
+import shutil
+import sys
+import zipfile
+
+import numpy as np
+
+# ---------------------------------------------------------------------------
+# constants extracted from MediaPipe source (Apache-2.0), pinned here so the
+# C++ side and this script share one source of truth (also emitted to JSON).
+# ---------------------------------------------------------------------------
+
+# mediapipe/tasks/cc/vision/face_landmarker/face_blendshapes_graph.cc
+BLENDSHAPE_LANDMARK_SUBSET = [
+    0, 1, 4, 5, 6, 7, 8, 10, 13, 14, 17, 21, 33, 37, 39,
+    40, 46, 52, 53, 54, 55, 58, 61, 63, 65, 66, 67, 70, 78, 80,
+    81, 82, 84, 87, 88, 91, 93, 95, 103, 105, 107, 109, 127, 132, 133,
+    136, 144, 145, 146, 148, 149, 150, 152, 153, 154, 155, 157, 158, 159, 160,
+    161, 162, 163, 168, 172, 173, 176, 178, 181, 185, 191, 195, 197, 234, 246,
+    249, 251, 263, 267, 269, 270, 276, 282, 283, 284, 285, 288, 291, 293, 295,
+    296, 297, 300, 308, 310, 311, 312, 314, 317, 318, 321, 323, 324, 332, 334,
+    336, 338, 356, 361, 362, 365, 373, 374, 375, 377, 378, 379, 380, 381, 382,
+    384, 385, 386, 387, 388, 389, 390, 397, 398, 400, 402, 405, 409, 415, 454,
+    466, 468, 469, 470, 471, 472, 473, 474, 475, 476, 477,
+]
+
+BLENDSHAPE_NAMES = [
+    "_neutral", "browDownLeft", "browDownRight", "browInnerUp",
+    "browOuterUpLeft", "browOuterUpRight", "cheekPuff", "cheekSquintLeft",
+    "cheekSquintRight", "eyeBlinkLeft", "eyeBlinkRight", "eyeLookDownLeft",
+    "eyeLookDownRight", "eyeLookInLeft", "eyeLookInRight", "eyeLookOutLeft",
+    "eyeLookOutRight", "eyeLookUpLeft", "eyeLookUpRight", "eyeSquintLeft",
+    "eyeSquintRight", "eyeWideLeft", "eyeWideRight", "jawForward", "jawLeft",
+    "jawOpen", "jawRight", "mouthClose", "mouthDimpleLeft", "mouthDimpleRight",
+    "mouthFrownLeft", "mouthFrownRight", "mouthFunnel", "mouthLeft",
+    "mouthLowerDownLeft", "mouthLowerDownRight", "mouthPressLeft",
+    "mouthPressRight", "mouthPucker", "mouthRight", "mouthRollLower",
+    "mouthRollUpper", "mouthShrugLower", "mouthShrugUpper", "mouthSmileLeft",
+    "mouthSmileRight", "mouthStretchLeft", "mouthStretchRight",
+    "mouthUpperUpLeft", "mouthUpperUpRight", "noseSneerLeft", "noseSneerRight",
+]
+
+# MediaPipe pose landmark index -> body part (33 real landmarks; the model
+# emits 39, the last 6 are auxiliary and dropped).
+POSE_LANDMARK_NAMES = [
+    "nose", "left_eye_inner", "left_eye", "left_eye_outer", "right_eye_inner",
+    "right_eye", "right_eye_outer", "left_ear", "right_ear", "mouth_left",
+    "mouth_right", "left_shoulder", "right_shoulder", "left_elbow",
+    "right_elbow", "left_wrist", "right_wrist", "left_pinky", "right_pinky",
+    "left_index", "right_index", "left_thumb", "right_thumb", "left_hip",
+    "right_hip", "left_knee", "right_knee", "left_ankle", "right_ankle",
+    "left_heel", "right_heel", "left_foot_index", "right_foot_index",
+]
+
+
+# ---------------------------------------------------------------------------
+# TFLite -> ONNX conversion
+# ---------------------------------------------------------------------------
+
+def densify_tflite(src, dst):
+    """Rewrite a TFLite flatbuffer with all DENSIFY'd sparse constants dense.
+
+    tf2onnx cannot parse TFLite block-sparse tensors. The TFLite interpreter
+    can (XNNPACK densifies at prepare time), so we run it once with
+    experimental_preserve_all_tensors, read back each DENSIFY output, store it
+    as a dense buffer on the op's input tensor, rewire consumers and drop the
+    DENSIFY ops. Returns the number of ops removed (0 = no rewrite needed).
+    """
+    import tensorflow as tf
+    from tensorflow.lite.tools import flatbuffer_utils
+    from tensorflow.lite.python import schema_py_generated as schema
+
+    names = {v: k for k, v in schema.BuiltinOperator.__dict__.items()
+             if isinstance(v, int)}
+    model = flatbuffer_utils.read_model(src)
+    sg = model.subgraphs[0]
+
+    def is_densify(op):
+        code = model.operatorCodes[op.opcodeIndex]
+        bc = max(code.builtinCode, getattr(code, "deprecatedBuiltinCode", 0))
+        return names.get(bc) == "DENSIFY"
+
+    if not any(is_densify(op) for op in sg.operators):
+        shutil.copyfile(src, dst)
+        return 0
+
+    interp = tf.lite.Interpreter(
+        model_path=src,
+        experimental_preserve_all_tensors=True,
+        # XNNPACK folds DENSIFY away and get_tensor() then reads garbage —
+        # run pure-builtin so every intermediate tensor is materialized.
+        experimental_op_resolver_type=tf.lite.experimental.OpResolverType
+        .BUILTIN_WITHOUT_DEFAULT_DELEGATES)
+    interp.allocate_tensors()
+    inp = interp.get_input_details()[0]
+    interp.set_tensor(inp["index"], np.zeros(inp["shape"], dtype=inp["dtype"]))
+    interp.invoke()
+
+    kept = []
+    removed = 0
+    for op in sg.operators:
+        if not is_densify(op):
+            kept.append(op)
+            continue
+        removed += 1
+        ti, to = int(op.inputs[0]), int(op.outputs[0])
+        dense = interp.get_tensor(to)
+        tensor = sg.tensors[ti]
+        # type 1 == FLOAT16 in the tflite schema; keep the storage dtype.
+        data = np.ascontiguousarray(
+            dense.astype(np.float16 if tensor.type == 1 else dense.dtype)
+        ).tobytes()
+        buf = schema.BufferT()
+        buf.data = np.frombuffer(data, dtype=np.uint8)
+        model.buffers.append(buf)
+        tensor.buffer = len(model.buffers) - 1
+        tensor.sparsity = None
+        for other in sg.operators:
+            if other is not op:
+                other.inputs = [ti if int(x) == to else int(x)
+                                for x in other.inputs]
+    sg.operators = kept
+    flatbuffer_utils.write_model(model, dst)
+    return removed
+
+
+def convert_tflite_to_onnx(tflite_path, onnx_path, optimize=True):
+    """tf2onnx conversion via the python API so the optimizer can be skipped."""
+    import onnx
+    from tf2onnx.tfonnx import process_tf_graph
+    from tf2onnx import optimizer as tf2onnx_optimizer
+
+    g = process_tf_graph(None, opset=18, tflite_path=tflite_path)
+    if optimize:
+        g = tf2onnx_optimizer.optimize_graph(g, catch_errors=True)
+    model_proto = g.make_model(os.path.basename(onnx_path))
+    onnx.save(model_proto, onnx_path)
+
+
+def ort_session(path):
+    import onnxruntime as ort
+    return ort.InferenceSession(path, providers=["CPUExecutionProvider"])
+
+
+def convert_with_fallback(tflite_path, onnx_path):
+    """Convert; if onnxruntime rejects the optimized graph, retry unoptimized."""
+    work = tflite_path
+    dense = onnx_path + ".dense.tflite"
+    removed = densify_tflite(tflite_path, dense)
+    if removed:
+        print(f"    densified {removed} sparse tensors")
+        work = dense
+    try:
+        convert_tflite_to_onnx(work, onnx_path, optimize=True)
+        ort_session(onnx_path)
+        mode = "optimized"
+    except Exception as exc:  # noqa: BLE001 - any ORT load failure
+        print(f"    optimized graph rejected ({type(exc).__name__}); "
+              "retrying with tf2onnx optimizers disabled")
+        convert_tflite_to_onnx(work, onnx_path, optimize=False)
+        ort_session(onnx_path)
+        mode = "unoptimized"
+    if os.path.exists(dense):
+        os.remove(dense)
+    print(f"    -> {onnx_path} ({mode}, "
+          f"{os.path.getsize(onnx_path) / 1e6:.1f} MB)")
+
+
+# ---------------------------------------------------------------------------
+# shared pipeline math (this is the contract Slice C reimplements in C++)
+# ---------------------------------------------------------------------------
+
+def letterbox(img, size):
+    """Keep-aspect centre letterbox to size x size (BORDER_ZERO, plain
+    bilinear — cv2, NOT an antialiased resampler; matches MediaPipe's
+    ImageToTensor). Returns (uint8 HxWx3 array, pad).
+
+    pad = (pad_x, pad_y, fx, fy): normalized padding on each leading side of
+    the letterboxed square and the fraction of the square the image occupies.
+    """
+    import cv2
+    arr = np.asarray(img)
+    h, w = arr.shape[:2]
+    s = size / max(w, h)
+    ox, oy = (size - w * s) / 2.0, (size - h * s) / 2.0
+    m = np.array([[s, 0, ox], [0, s, oy]], dtype=np.float64)
+    out = cv2.warpAffine(arr, m, (size, size), flags=cv2.INTER_LINEAR,
+                         borderMode=cv2.BORDER_CONSTANT, borderValue=0)
+    return out, (ox / size, oy / size, w * s / size, h * s / size)
+
+
+def unletterbox_points(pts, pad):
+    """Map normalized letterbox-square coords -> normalized original coords."""
+    pad_x, pad_y, fx, fy = pad
+    out = pts.copy()
+    out[..., 0] = (pts[..., 0] - pad_x) / fx
+    out[..., 1] = (pts[..., 1] - pad_y) / fy
+    return out
+
+
+def gen_ssd_anchors(input_size, strides, min_scale=0.1484375, max_scale=0.75,
+                    anchor_offset=0.5, interpolated_scale_aspect_ratio=1.0):
+    """MediaPipe SsdAnchorsCalculator with aspect_ratios=[1.0], fixed size."""
+    def scale_for(i, n):
+        if n == 1:
+            return (min_scale + max_scale) * 0.5
+        return min_scale + (max_scale - min_scale) * i / (n - 1)
+
+    anchors = []
+    n = len(strides)
+    layer = 0
+    while layer < n:
+        # merge consecutive identical strides into one layer
+        last = layer
+        scales = []
+        while last < n and strides[last] == strides[layer]:
+            scales.append(scale_for(last, n))
+            if interpolated_scale_aspect_ratio > 0.0:
+                nxt = 1.0 if last == n - 1 else scale_for(last + 1, n)
+                scales.append(math.sqrt(scales[-1] * nxt))
+            last += 1
+        stride = strides[layer]
+        fm = int(math.ceil(input_size / stride))
+        for y in range(fm):
+            for x in range(fm):
+                for _ in scales:
+                    anchors.append(((x + anchor_offset) / fm,
+                                    (y + anchor_offset) / fm))
+        layer = last
+    return np.array(anchors, dtype=np.float32)
+
+
+def decode_detections(raw_boxes, raw_scores, anchors, input_size, num_keypoints,
+                      min_score=0.5):
+    """MediaPipe TensorsToDetections: fixed anchor size, no box flip."""
+    scores = sigmoid(raw_scores[..., 0])
+    keep = scores >= min_score
+    boxes = raw_boxes[keep]
+    scores = scores[keep]
+    anc = anchors[keep]
+    if boxes.shape[0] == 0:
+        return []
+    cx = boxes[:, 0] / input_size + anc[:, 0]
+    cy = boxes[:, 1] / input_size + anc[:, 1]
+    w = boxes[:, 2] / input_size
+    h = boxes[:, 3] / input_size
+    kps = np.stack([boxes[:, 4 + 2 * k:6 + 2 * k] / input_size + anc
+                    for k in range(num_keypoints)], axis=1)
+    dets = []
+    for i in range(boxes.shape[0]):
+        dets.append({
+            "score": float(scores[i]),
+            "box": (float(cx[i] - w[i] / 2), float(cy[i] - h[i] / 2),
+                    float(w[i]), float(h[i])),
+            "keypoints": kps[i].astype(float),
+        })
+    return weighted_nms(dets)
+
+
+def weighted_nms(dets, min_suppression_threshold=0.3):
+    """MediaPipe weighted non-max-suppression."""
+    def iou(a, b):
+        ax, ay, aw, ah = a
+        bx, by, bw, bh = b
+        x1, y1 = max(ax, bx), max(ay, by)
+        x2, y2 = min(ax + aw, bx + bw), min(ay + ah, by + bh)
+        inter = max(0.0, x2 - x1) * max(0.0, y2 - y1)
+        union = aw * ah + bw * bh - inter
+        return inter / union if union > 0 else 0.0
+
+    remaining = sorted(dets, key=lambda d: -d["score"])
+    out = []
+    while remaining:
+        best = remaining[0]
+        cluster = [d for d in remaining if iou(d["box"], best["box"])
+                   > min_suppression_threshold]
+        remaining = [d for d in remaining if d not in cluster]
+        total = sum(d["score"] for d in cluster)
+        box = np.zeros(4)
+        kps = np.zeros_like(np.asarray(best["keypoints"]))
+        for d in cluster:
+            wgt = d["score"] / total
+            box += wgt * np.array(d["box"])
+            kps += wgt * np.asarray(d["keypoints"])
+        merged = dict(best)
+        merged["box"] = tuple(box)
+        merged["keypoints"] = kps
+        out.append(merged)
+    return out
+
+
+def rect_from_face_detection(det, img_w, img_h):
+    """DetectionsToRects (kp0 right eye -> kp1 left eye, target 0 deg) +
+    RectTransformation(scale 1.5, square_long). rotation follows MediaPipe:
+    theta = normalize(target - atan2(-(dy), dx)), y down, CCW-positive in the
+    R(theta) = [[c,-s],[s,c]] image-coordinate sense."""
+    x, y, w, h = det["box"]
+    cx, cy = x + w / 2, y + h / 2
+    kp = det["keypoints"]
+    dx = (kp[1][0] - kp[0][0]) * img_w
+    dy = (kp[1][1] - kp[0][1]) * img_h
+    angle = normalize_angle(-math.atan2(-dy, dx))  # target angle 0
+    side = max(w * img_w, h * img_h) * 1.5
+    return cx * img_w, cy * img_h, side, side, angle
+
+
+def rect_from_pose_detection(det, img_w, img_h):
+    """AlignmentPointsRects (centre kp0, radius |kp1-kp0|, target 90 deg) +
+    RectTransformation(scale 1.25, square_long). Same rotation convention as
+    rect_from_face_detection."""
+    kp = det["keypoints"]
+    cx, cy = kp[0][0] * img_w, kp[0][1] * img_h
+    dx = kp[1][0] * img_w - cx
+    dy = kp[1][1] * img_h - cy
+    radius = math.sqrt(dx * dx + dy * dy)
+    angle = normalize_angle(math.pi / 2 - math.atan2(-dy, dx))
+    side = 2 * radius * 1.25
+    return cx, cy, side, side, angle
+
+
+def normalize_angle(a):
+    return a - 2 * math.pi * math.floor((a + math.pi) / (2 * math.pi))
+
+
+def crop_rotated_rect(img, rect, out_size):
+    """Sample the rotated rect (cx,cy,w,h px + MediaPipe rotation) into an
+    out_size x out_size RGB uint8 array. Output (u,v) maps to image point
+    centre + R(theta) . ((u/out - 0.5) * w, (v/out - 0.5) * h); plain bilinear,
+    BORDER_ZERO — MediaPipe's GetRotatedSubRectToRectTransformMatrix."""
+    import cv2
+    arr = np.asarray(img)
+    cx, cy, w, h, angle = rect
+    ca, sa = math.cos(angle), math.sin(angle)
+    sx, sy = w / out_size, h / out_size
+    # input <- output affine, then invert for warpAffine's dst<-src semantics
+    m = np.array([
+        [ca * sx, -sa * sy, cx - (ca * sx + -sa * sy) * (out_size / 2.0)],
+        [sa * sx, ca * sy, cy - (sa * sx + ca * sy) * (out_size / 2.0)],
+    ], dtype=np.float64)
+    return cv2.warpAffine(arr, m, (out_size, out_size),
+                          flags=cv2.INTER_LINEAR | cv2.WARP_INVERSE_MAP,
+                          borderMode=cv2.BORDER_CONSTANT, borderValue=0)
+
+
+def project_landmarks(pts_norm, rect, img_w, img_h):
+    """LandmarkProjection: normalized crop coords -> image pixel coords
+    (x' = cx + dx*w*cos - dy*h*sin, same R(theta) as the crop)."""
+    cx, cy, w, h, angle = rect
+    x = pts_norm[:, 0] - 0.5
+    y = pts_norm[:, 1] - 0.5
+    ca, sa = math.cos(angle), math.sin(angle)
+    px = cx + x * w * ca - y * h * sa
+    py = cy + x * w * sa + y * h * ca
+    out = pts_norm.copy()
+    out[:, 0] = px
+    out[:, 1] = py
+    if out.shape[1] > 2:
+        out[:, 2] = pts_norm[:, 2] * w
+    return out
+
+
+def sigmoid(x):
+    x = np.clip(x, -100, 100)
+    return np.where(x >= 0, 1.0 / (1.0 + np.exp(-x)),
+                    np.exp(x) / (1.0 + np.exp(x)))
+
+
+def umeyama_rotation(src, dst, weights):
+    """Weighted Kabsch: rotation R (+ translation) with dst ~= s*R*src + t.
+    Returns (R 3x3, t 3, s). Scale solved then discarded by callers that only
+    want the pose."""
+    w = weights / weights.sum()
+    mu_s = (src * w[:, None]).sum(axis=0)
+    mu_d = (dst * w[:, None]).sum(axis=0)
+    sc = src - mu_s
+    dc = dst - mu_d
+    cov = (dc * w[:, None]).T @ sc
+    U, S, Vt = np.linalg.svd(cov)
+    d = np.sign(np.linalg.det(U @ Vt))
+    D = np.diag([1.0, 1.0, d])
+    R = U @ D @ Vt
+    var = (w[:, None] * sc * sc).sum()
+    s = (S * [1, 1, d]).sum() / var if var > 0 else 1.0
+    t = mu_d - s * (R @ mu_s)
+    return R, t, s
+
+
+# ---------------------------------------------------------------------------
+# ONNX pipelines (ours) — mirror of what Slice C does in C++
+# ---------------------------------------------------------------------------
+
+class OnnxFacePipeline:
+    def __init__(self, out_dir, canonical_obj, procrustes_pbtxt):
+        self.det = ort_session(os.path.join(out_dir, "face", "face_detector.onnx"))
+        self.lmk = ort_session(os.path.join(out_dir, "face", "face_landmarks.onnx"))
+        self.bs = ort_session(os.path.join(out_dir, "face", "face_blendshapes.onnx"))
+        self.det_size = self.det.get_inputs()[0].shape[1]
+        self.lmk_size = self.lmk.get_inputs()[0].shape[1]
+        self.anchors = gen_ssd_anchors(self.det_size, [8, 16, 16, 16])
+        assert self.anchors.shape[0] == self.det.get_outputs()[0].shape[1], \
+            f"anchor count {self.anchors.shape[0]} != model {self.det.get_outputs()[0].shape[1]}"
+        self.canonical = load_canonical_obj(canonical_obj)
+        ids, wgt = load_procrustes_basis(procrustes_pbtxt)
+        self.basis_ids = ids
+        self.basis_w = wgt
+
+    def __call__(self, img):
+        from PIL import Image
+        img = img.convert("RGB")
+        W, H = img.size
+        # --- stage 1: detector
+        lb, pad = letterbox(img, self.det_size)
+        x = lb.astype(np.float32)[None] / 127.5 - 1.0
+        raw_box, raw_score = self.det.run(None, {self.det.get_inputs()[0].name: x})
+        dets = decode_detections(raw_box[0], raw_score[0], self.anchors,
+                                 self.det_size, num_keypoints=6)
+        if not dets:
+            return None
+        det = dets[0]
+        det["box"] = tuple(unletterbox_points(
+            np.array([[det["box"][0], det["box"][1]],
+                      [det["box"][0] + det["box"][2], det["box"][1] + det["box"][3]]]),
+            pad).reshape(-1))
+        det["box"] = (det["box"][0], det["box"][1],
+                      det["box"][2] - det["box"][0], det["box"][3] - det["box"][1])
+        det["keypoints"] = unletterbox_points(np.asarray(det["keypoints"]), pad)
+        rect = rect_from_face_detection(det, W, H)
+        # --- stage 2: landmarks
+        crop = crop_rotated_rect(img, rect, self.lmk_size)
+        x = crop.astype(np.float32)[None] / 255.0
+        outs = self.lmk.run(None, {self.lmk.get_inputs()[0].name: x})
+        lmk_raw = outs[0].reshape(-1, 3) / self.lmk_size
+        presence = float(sigmoid(outs[1].reshape(-1)[0]))
+        pts = project_landmarks(lmk_raw, rect, W, H)  # px
+        # --- stage 3: blendshapes (146 subset, pixel coords, 2D)
+        sub = pts[BLENDSHAPE_LANDMARK_SUBSET][:, :2].astype(np.float32)
+        bs = self.bs.run(None, {self.bs.get_inputs()[0].name: sub[None]})[0]
+        bs = bs.reshape(-1)
+        # --- head pose: weighted Kabsch canonical(cm) -> camera-ish frame
+        pose_pts = np.stack([pts[:468, 0], -pts[:468, 1], -pts[:468, 2]], axis=1)
+        weights = np.zeros(468, dtype=np.float64)
+        weights[self.basis_ids] = self.basis_w
+        R, t, s = umeyama_rotation(self.canonical, pose_pts, weights)
+        return {
+            "landmarks": pts,            # 478 x 3, px (z in px, w-scaled)
+            "presence": presence,
+            "blendshapes": bs,           # 52
+            "rotation": R,               # canonical -> camera
+        }
+
+
+class OnnxPosePipeline:
+    def __init__(self, out_dir):
+        self.det = ort_session(os.path.join(out_dir, "pose", "pose_detector.onnx"))
+        self.lmk = ort_session(os.path.join(out_dir, "pose", "pose_landmarks.onnx"))
+        self.det_size = self.det.get_inputs()[0].shape[1]
+        self.lmk_size = self.lmk.get_inputs()[0].shape[1]
+        self.anchors = gen_ssd_anchors(self.det_size, [8, 16, 32, 32, 32])
+        assert self.anchors.shape[0] == self.det.get_outputs()[0].shape[1]
+
+    def __call__(self, img):
+        img = img.convert("RGB")
+        W, H = img.size
+        lb, pad = letterbox(img, self.det_size)
+        x = lb.astype(np.float32)[None] / 127.5 - 1.0
+        raw_box, raw_score = self.det.run(None, {self.det.get_inputs()[0].name: x})
+        dets = decode_detections(raw_box[0], raw_score[0], self.anchors,
+                                 self.det_size, num_keypoints=4)
+        if not dets:
+            return None
+        det = dets[0]
+        det["keypoints"] = unletterbox_points(np.asarray(det["keypoints"]), pad)
+        rect = rect_from_pose_detection(det, W, H)
+        crop = crop_rotated_rect(img, rect, self.lmk_size)
+        x = crop.astype(np.float32)[None] / 255.0
+        outs = self.lmk.run(None, {self.lmk.get_inputs()[0].name: x})
+        raw = outs[0].reshape(-1, 5)  # 39 x (x,y,z,vis,presence)
+        # unlike the face model (logit), the pose flag is already a probability
+        pose_flag = float(outs[1].reshape(-1)[0])
+        world = outs[4].reshape(-1, 3)
+        pts_norm = raw[:, :3] / self.lmk_size
+        pts = project_landmarks(pts_norm, rect, W, H)
+        vis = sigmoid(raw[:, 3])
+        # world landmarks: rotate by the rect rotation only (no scale)
+        cx, cy, w, h, angle = rect
+        ca, sa = math.cos(angle), math.sin(angle)
+        wx = world[:, 0] * ca - world[:, 1] * sa
+        wy = world[:, 0] * sa + world[:, 1] * ca
+        world_rot = np.stack([wx, wy, world[:, 2]], axis=1)
+        return {
+            "landmarks": pts[:33],
+            "visibility": vis[:33],
+            "world": world_rot[:33],
+            "presence": pose_flag,
+        }
+
+
+def load_canonical_obj(path):
+    """468 canonical face model vertices (cm), mediapipe face_geometry data."""
+    verts = []
+    with open(path) as f:
+        for line in f:
+            if line.startswith("v "):
+                verts.append([float(v) for v in line.split()[1:4]])
+    v = np.array(verts, dtype=np.float64)
+    assert v.shape == (468, 3), v.shape
+    return v
+
+
+def load_procrustes_basis(path):
+    ids, weights = [], []
+    with open(path) as f:
+        for line in f:
+            line = line.strip()
+            if line.startswith("procrustes_landmark_basis"):
+                parts = line.replace("{", " ").replace("}", " ").split()
+                ids.append(int(parts[parts.index("landmark_id:") + 1]))
+                weights.append(float(parts[parts.index("weight:") + 1]))
+    return np.array(ids), np.array(weights, dtype=np.float64)
+
+
+# ---------------------------------------------------------------------------
+# parity vs the python mediapipe reference
+# ---------------------------------------------------------------------------
+
+def run_face_parity(face_task, out_dir, images, canonical_obj, procrustes_pbtxt):
+    import mediapipe as mp
+    from mediapipe.tasks import python as mp_python
+    from mediapipe.tasks.python import vision as mp_vision
+    from PIL import Image
+
+    ours = OnnxFacePipeline(out_dir, canonical_obj, procrustes_pbtxt)
+    options = mp_vision.FaceLandmarkerOptions(
+        base_options=mp_python.BaseOptions(model_asset_path=face_task),
+        output_face_blendshapes=True,
+        output_facial_transformation_matrixes=True,
+        num_faces=1)
+    ref = mp_vision.FaceLandmarker.create_from_options(options)
+
+    print("\n== FACE PARITY (ONNX pipeline vs python mediapipe) ==")
+    worst_bs, worst_px, worst_deg = 0.0, 0.0, 0.0
+    n_ok = 0
+    n_mismatch = 0
+    for path in images:
+        img = Image.open(path)
+        mp_img = mp.Image(image_format=mp.ImageFormat.SRGB,
+                          data=np.asarray(img.convert("RGB")))
+        res = ref.detect(mp_img)
+        mine = ours(img)
+        # Detection DISAGREEMENTS are parity failures, not skips: if we only
+        # require n_ok > 0, one matching image can hide mismatches on every
+        # other asset. Count them and assert none remain at the end.
+        if not res.face_landmarks:
+            if mine is not None:
+                print(f"  {os.path.basename(path)}: MISMATCH — reference found "
+                      f"no face, we did")
+                n_mismatch += 1
+            else:
+                print(f"  {os.path.basename(path)}: no face (both agree)")
+            continue
+        if mine is None:
+            print(f"  {os.path.basename(path)}: MISMATCH — reference found a "
+                  f"face, we did NOT")
+            n_mismatch += 1
+            continue
+        W, H = img.size
+        ref_pts = np.array([[pt.x * W, pt.y * H] for pt in res.face_landmarks[0]])
+        d_px = np.linalg.norm(ref_pts - mine["landmarks"][:, :2], axis=1)
+        ref_bs = np.array([b.score for b in res.face_blendshapes[0]])
+        d_bs = np.abs(ref_bs - mine["blendshapes"])
+        deg = np.nan
+        if res.facial_transformation_matrixes:
+            Rref = np.array(res.facial_transformation_matrixes[0])[:3, :3]
+            # our R maps canonical -> camera, so compare directly
+            dR = Rref.T @ mine["rotation"]
+            deg = math.degrees(math.acos(np.clip((np.trace(dR) - 1) / 2, -1, 1)))
+        print(f"  {os.path.basename(path)}: landmarks mean {d_px.mean():.2f}px "
+              f"max {d_px.max():.2f}px | blendshapes mean {d_bs.mean():.4f} "
+              f"max {d_bs.max():.4f} | head-pose delta {deg:.2f} deg "
+              f"| presence {mine['presence']:.3f}")
+        worst_bs = max(worst_bs, d_bs.max())
+        worst_px = max(worst_px, d_px.max())
+        if not math.isnan(deg):
+            worst_deg = max(worst_deg, deg)
+        n_ok += 1
+    ref.close()
+    assert n_ok > 0, "no face image produced a reference result"
+    assert n_mismatch == 0, (
+        f"{n_mismatch} image(s) disagreed on face detection — parity FAILED")
+    print(f"  WORST: blendshapes {worst_bs:.4f} (target <= 0.02), "
+          f"landmarks {worst_px:.2f}px (target <= 2px on the tracked face), "
+          f"head-pose {worst_deg:.2f} deg (informational)")
+    return {"worst_blendshape_abs": worst_bs, "worst_landmark_px": worst_px,
+            "worst_headpose_deg": worst_deg, "images": n_ok}
+
+
+def run_pose_parity(pose_task, out_dir, images):
+    import mediapipe as mp
+    from mediapipe.tasks import python as mp_python
+    from mediapipe.tasks.python import vision as mp_vision
+    from PIL import Image
+
+    ours = OnnxPosePipeline(out_dir)
+    options = mp_vision.PoseLandmarkerOptions(
+        base_options=mp_python.BaseOptions(model_asset_path=pose_task),
+        num_poses=1)
+    ref = mp_vision.PoseLandmarker.create_from_options(options)
+
+    print("\n== POSE PARITY (ONNX pipeline vs python mediapipe) ==")
+    worst_world = 0.0
+    n_ok = 0
+    for path in images:
+        img = Image.open(path)
+        mp_img = mp.Image(image_format=mp.ImageFormat.SRGB,
+                          data=np.asarray(img.convert("RGB")))
+        res = ref.detect(mp_img)
+        mine = ours(img)
+        if not res.pose_world_landmarks:
+            print(f"  {os.path.basename(path)}: no pose (reference)")
+            continue
+        if mine is None:
+            print(f"  {os.path.basename(path)}: REFERENCE found a pose, we did NOT")
+            continue
+        ref_world = np.array([[pt.x, pt.y, pt.z]
+                              for pt in res.pose_world_landmarks[0]])
+        d = np.linalg.norm(ref_world - mine["world"], axis=1)
+        print(f"  {os.path.basename(path)}: world landmarks mean "
+              f"{d.mean() * 100:.2f}cm max {d.max() * 100:.2f}cm "
+              f"| presence {mine['presence']:.3f}")
+        worst_world = max(worst_world, d.max())
+        n_ok += 1
+    ref.close()
+    assert n_ok > 0, "no pose image produced a reference result"
+    print(f"  WORST: world {worst_world * 100:.2f}cm (target <= 2cm)")
+    return {"worst_world_m": worst_world, "images": n_ok}
+
+
+# ---------------------------------------------------------------------------
+# main
+# ---------------------------------------------------------------------------
+
+def extract_task(task_path, dest):
+    os.makedirs(dest, exist_ok=True)
+    with zipfile.ZipFile(task_path) as z:
+        z.extractall(dest)
+    return {os.path.splitext(n)[0]: os.path.join(dest, n)
+            for n in os.listdir(dest) if n.endswith(".tflite")}
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--face-task", help="face_landmarker.task path")
+    ap.add_argument("--pose-task", help="pose_landmarker_full.task path")
+    ap.add_argument("--images", required=True,
+                    help="dir with test images (face parity uses images whose "
+                         "name doesn't start with 'pose', pose parity the rest)")
+    ap.add_argument("--out-dir", default=".mocap_work/out")
+    ap.add_argument("--canonical-obj", default=".mocap_work/canonical_face_model.obj")
+    ap.add_argument("--procrustes", default=".mocap_work/geometry_pipeline_metadata_landmarks.pbtxt")
+    ap.add_argument("--verify-only", action="store_true",
+                    help="skip conversion, only run parity on existing out-dir")
+    args = ap.parse_args()
+
+    imgs = sorted(os.path.join(args.images, f) for f in os.listdir(args.images)
+                  if f.lower().endswith((".jpg", ".jpeg", ".png")))
+    face_imgs = [p for p in imgs if not os.path.basename(p).startswith("pose")]
+    pose_imgs = [p for p in imgs if os.path.basename(p).startswith("pose")]
+
+    report = {}
+    if args.face_task:
+        face_out = os.path.join(args.out_dir, "face")
+        os.makedirs(face_out, exist_ok=True)
+        if not args.verify_only:
+            print("== converting face models ==")
+            tflites = extract_task(args.face_task, os.path.join(args.out_dir, "_face_tflite"))
+            convert_with_fallback(tflites["face_detector"],
+                                  os.path.join(face_out, "face_detector.onnx"))
+            convert_with_fallback(tflites["face_landmarks_detector"],
+                                  os.path.join(face_out, "face_landmarks.onnx"))
+            convert_with_fallback(tflites["face_blendshapes"],
+                                  os.path.join(face_out, "face_blendshapes.onnx"))
+        report["face"] = run_face_parity(args.face_task, args.out_dir, face_imgs,
+                                         args.canonical_obj, args.procrustes)
+        assert report["face"]["worst_blendshape_abs"] <= 0.02, "blendshape parity FAILED"
+        # The documented contract advertises a 2px landmark target; enforce it
+        # so parity can't silently regress while the script prints success.
+        assert report["face"]["worst_landmark_px"] <= 2.0, (
+            f"landmark parity FAILED "
+            f"({report['face']['worst_landmark_px']:.2f}px > 2px)")
+
+    if args.pose_task:
+        pose_out = os.path.join(args.out_dir, "pose")
+        os.makedirs(pose_out, exist_ok=True)
+        if not args.verify_only:
+            print("== converting pose models ==")
+            tflites = extract_task(args.pose_task, os.path.join(args.out_dir, "_pose_tflite"))
+            convert_with_fallback(tflites["pose_detector"],
+                                  os.path.join(pose_out, "pose_detector.onnx"))
+            convert_with_fallback(tflites["pose_landmarks_detector"],
+                                  os.path.join(pose_out, "pose_landmarks.onnx"))
+        report["pose"] = run_pose_parity(args.pose_task, args.out_dir, pose_imgs)
+        assert report["pose"]["worst_world_m"] <= 0.02, "pose world parity FAILED"
+
+    # contract dump for the C++ side / spike doc
+    contract = {
+        "blendshape_names": BLENDSHAPE_NAMES,
+        "blendshape_landmark_subset": BLENDSHAPE_LANDMARK_SUBSET,
+        "pose_landmark_names": POSE_LANDMARK_NAMES,
+        "face_detector": {"input": 128, "range": [-1, 1],
+                          "anchors": {"strides": [8, 16, 16, 16], "count": 896},
+                          "keypoints": ["right_eye", "left_eye", "nose", "mouth",
+                                        "right_ear", "left_ear"],
+                          "roi": {"rotation_kp": [0, 1], "target_angle_deg": 0,
+                                  "scale": 1.5, "square_long": True}},
+        "face_landmarks": {"input": 256, "range": [0, 1],
+                           "outputs": "1434=478*xyz in 256-space; presence logit"},
+        "face_blendshapes": {"input": "[1,146,2] (x*W, y*H) px", "output": 52},
+        "pose_detector": {"input": 224, "range": [-1, 1],
+                          "anchors": {"strides": [8, 16, 32, 32, 32], "count": 2254},
+                          "roi": {"center_kp": 0, "radius_kp": 1,
+                                  "target_angle_deg": 90, "scale": 1.25}},
+        "pose_landmarks": {"input": 256, "range": [0, 1],
+                           "outputs": "195=39*(x,y,z,vis,presence); world 117=39*xyz metres"},
+        "parity": report,
+    }
+    os.makedirs(args.out_dir, exist_ok=True)
+    with open(os.path.join(args.out_dir, "mocap_contract.json"), "w") as f:
+        json.dump(contract, f, indent=2)
+    print(f"\ncontract + parity report -> {os.path.join(args.out_dir, 'mocap_contract.json')}")
+    print("ALL PARITY CHECKS PASSED")
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/sync-hf-model-repos.sh b/scripts/sync-hf-model-repos.sh
index 029c24d05..a8d56bcee 100755
--- a/scripts/sync-hf-model-repos.sh
+++ b/scripts/sync-hf-model-repos.sh
@@ -29,6 +29,12 @@
 #   segveh     → QtMeshEditor-mesh-segmentation-vehicle    (CC-BY-4.0, in-house #818 B2)
 #   segbld     → QtMeshEditor-mesh-segmentation-building   (CC-BY-4.0, in-house #818 B2)
 #   segcls     → QtMeshEditor-mesh-segmentation-category   (CC-BY-4.0, in-house #818 B2 Auto dispatcher)
+#   mocap-* (5, #869; Apache, converted Google MediaPipe graphs):
+#     blazeface       → QtMeshEditor-blazeface-onnx       (face detector)
+#     facemesh        → QtMeshEditor-facemesh-onnx        (478 face landmarks)
+#     faceblendshapes → QtMeshEditor-faceblendshapes-onnx (52 ARKit blendshapes)
+#     blazepose       → QtMeshEditor-blazepose-onnx       (person detector)
+#     poselandmarks   → QtMeshEditor-poselandmarks-onnx   (33 world landmarks)
 set -euo pipefail
 
 OWNER=fernandotonon
@@ -50,6 +56,11 @@ declare -A REPOS=(
   [segveh]=QtMeshEditor-mesh-segmentation-vehicle
   [segbld]=QtMeshEditor-mesh-segmentation-building
   [segcls]=QtMeshEditor-mesh-segmentation-category
+  [blazeface]=QtMeshEditor-blazeface-onnx
+  [facemesh]=QtMeshEditor-facemesh-onnx
+  [faceblendshapes]=QtMeshEditor-faceblendshapes-onnx
+  [blazepose]=QtMeshEditor-blazepose-onnx
+  [poselandmarks]=QtMeshEditor-poselandmarks-onnx
 )
 declare -A FILES=(
   [pbrify]="1x-PBRify_NormalV3.onnx 1x-PBRify_RoughnessV2.onnx 1x-PBRify_Height.onnx"
@@ -65,6 +76,11 @@ declare -A FILES=(
   [segveh]="segment/meshseg_vehicle.onnx"
   [segbld]="segment/meshseg_building.onnx"
   [segcls]="segment/meshseg_category.onnx"
+  [blazeface]="mocap/face/face_detector.onnx"
+  [facemesh]="mocap/face/face_landmarks.onnx"
+  [faceblendshapes]="mocap/face/face_blendshapes.onnx"
+  [blazepose]="mocap/pose/pose_detector.onnx"
+  [poselandmarks]="mocap/pose/pose_landmarks.onnx"
 )
 
 sync_one() {
@@ -72,8 +88,9 @@ sync_one() {
   echo "=== $model → $repo"
   for f in ${FILES[$model]}; do
     echo "  $f"
-    huggingface-cli download "$AGG" "$f" --local-dir "$WORK" --quiet
-    huggingface-cli upload "$repo" "$WORK/$f" "$(basename "$f")" --quiet
+    # `hf` replaces the removed `huggingface-cli` (huggingface_hub >= 1.0).
+    hf download "$AGG" "$f" --local-dir "$WORK" --quiet
+    hf upload "$repo" "$WORK/$f" "$(basename "$f")" --quiet
     rm -f "$WORK/$f"          # multi-GB files — don't accumulate
   done
 }
diff --git a/scripts/upload-mocap-models.sh b/scripts/upload-mocap-models.sh
new file mode 100755
index 000000000..49335ea01
--- /dev/null
+++ b/scripts/upload-mocap-models.sh
@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Upload the performance-capture models to the QtMeshEditor HF models repo
+# (epic #869, slice #876 — model hosting). ONE-TIME, run by a maintainer with
+# write access.
+#
+# The app downloads these on first use from
+#   https://huggingface.co/fernandotonon/QtMeshEditor-models/resolve/main/mocap/{face,pose}/...
+# so the file names + subfolders below MUST match FaceCapPredictor /
+# PoseCapPredictor's kDetectorFile/kLandmarksFile/kBlendshapesFile.
+#
+# All five graphs are converted Google MediaPipe models — Apache-2.0 code AND
+# weights (see THIRD_PARTY_AI_MODELS.md). The Apache-2.0 LICENSE/NOTICE is
+# uploaded next to the weights as the license requires.
+#
+# Prereqs:
+#   pip install -U huggingface_hub
+#   hf auth login                  # a token with write access to the repo
+#   scripts/export-facecap-onnx.py already run → OUT_DIR holds face/ + pose/
+#
+# Usage:
+#   OUT_DIR=.mocap_work/out ./scripts/upload-mocap-models.sh
+set -euo pipefail
+
+REPO="${REPO:-fernandotonon/QtMeshEditor-models}"
+OUT_DIR="${OUT_DIR:?set OUT_DIR to the export output dir (face/*.onnx + pose/*.onnx)}"
+
+upload() {  # <local> <repo-path>
+    local src="$1" dst="$2"
+    # Every mocap graph is REQUIRED — a partial upload produces a broken
+    # model release (the app downloads all five). Fail hard rather than
+    # skipping, so `set -e` aborts before a half-published set goes live.
+    if [ ! -f "$src" ]; then
+        echo "!! ABORT: required model missing: $src" >&2
+        exit 1
+    fi
+    echo ">> uploading $src -> $REPO:$dst"
+    # `hf upload <repo> <local> <path-in-repo>` (huggingface_hub >= 1.0;
+    # the old `huggingface-cli upload` was removed).
+    hf upload "$REPO" "$src" "$dst"
+}
+
+# Face bundle (FaceCapPredictor): detector + landmarks + blendshapes.
+upload "$OUT_DIR/face/face_detector.onnx"    "mocap/face/face_detector.onnx"
+upload "$OUT_DIR/face/face_landmarks.onnx"   "mocap/face/face_landmarks.onnx"
+upload "$OUT_DIR/face/face_blendshapes.onnx" "mocap/face/face_blendshapes.onnx"
+
+# Pose bundle (PoseCapPredictor): detector + landmarks.
+upload "$OUT_DIR/pose/pose_detector.onnx"   "mocap/pose/pose_detector.onnx"
+upload "$OUT_DIR/pose/pose_landmarks.onnx"  "mocap/pose/pose_landmarks.onnx"
+
+# Apache-2.0 notice next to the weights (MediaPipe attribution).
+NOTICE="$(mktemp)"
+cat > "$NOTICE" <<'EOF'
+These ONNX graphs are converted from Google MediaPipe's Face Landmarker and
+Pose Landmarker models (https://developers.google.com/mediapipe), released
+under the Apache License, Version 2.0:
+  https://www.apache.org/licenses/LICENSE-2.0
+Conversion: QtMeshEditor scripts/export-facecap-onnx.py (numerical parity
+asserted against the Python mediapipe reference; see docs/MOCAP_SPIKE.md in
+https://github.com/fernandotonon/QtMeshEditor).
+EOF
+upload "$NOTICE" "mocap/NOTICE.txt"
+rm -f "$NOTICE"
+
+echo "done. Verify: curl -sI https://huggingface.co/$REPO/resolve/main/mocap/face/face_detector.onnx | head -1"
diff --git a/src/AIModelCatalog.cpp b/src/AIModelCatalog.cpp
index 0452d85c2..c0ed056fb 100644
--- a/src/AIModelCatalog.cpp
+++ b/src/AIModelCatalog.cpp
@@ -162,6 +162,11 @@ QList<AIModelCatalog::ModelSpec> AIModelCatalog::specs() const
 #else
     constexpr bool captionAvailable = false;
 #endif
+#ifdef ENABLE_MOCAP
+    constexpr bool mocapAvailable = true;
+#else
+    constexpr bool mocapAvailable = false;
+#endif
 
     const QString pbrBase = resolveBaseUrl(
         "ai/pbrModelBaseUrl", "QTMESH_PBR_MODEL_BASE_URL",
@@ -196,6 +201,17 @@ QList<AIModelCatalog::ModelSpec> AIModelCatalog::specs() const
     const QString captionBase = resolveBaseUrl(
         "ai/captionModelBaseUrl", "QTMESH_CAPTION_MODEL_BASE_URL",
         "https://huggingface.co/fernandotonon/QtMeshEditor-models/resolve/main/caption/");
+    // Mocap models live under mocap/face and mocap/pose; the predictors read a
+    // single "ai/mocapModelBaseUrl" and append "face/"/"pose/" themselves, so
+    // bake those suffixes onto the catalog base after resolving the shared key.
+    const QString mocapBase = resolveBaseUrl(
+        "ai/mocapModelBaseUrl", "QTMESH_MOCAP_MODEL_BASE_URL",
+        "https://huggingface.co/fernandotonon/QtMeshEditor-models/resolve/main/mocap/");
+    const QString mocapFaceBase = joinUrl(mocapBase, QStringLiteral("face/"));
+    const QString mocapPoseBase = joinUrl(mocapBase, QStringLiteral("pose/"));
+    const QString facerigBase = resolveBaseUrl(
+        "ai/facerigModelBaseUrl", "QTMESH_FACERIG_MODEL_BASE_URL",
+        "https://huggingface.co/fernandotonon/QtMeshEditor-models/resolve/main/facerig/");
 
     QList<ModelSpec> out;
     out << ModelSpec{
@@ -332,6 +348,30 @@ QList<AIModelCatalog::ModelSpec> AIModelCatalog::specs() const
             file(QStringLiteral("caption"), QStringLiteral("SmolVLM-500M-Instruct-Q8_0.gguf"), captionBase, QStringLiteral("Caption SmolVLM-500M-Instruct-Q8_0.gguf")),
             file(QStringLiteral("caption"), QStringLiteral("mmproj-SmolVLM-500M-Instruct-Q8_0.gguf"), captionBase, QStringLiteral("Caption mmproj-SmolVLM-500M-Instruct-Q8_0.gguf")),
         }};
+    out << ModelSpec{
+        QStringLiteral("facerig-arkit"), tr("ARKit Face Rig Template"), tr("Rigging"),
+        tr("ICT-FaceKit template used to auto-generate the 52 ARKit blendshapes on a humanoid face mesh."),
+        QStringLiteral("Small"), QString(), true,
+        { file(QStringLiteral("facerig"), QStringLiteral("arkit_template.bin"), facerigBase, QStringLiteral("ARKit face-rig template")) }};
+    out << ModelSpec{
+        QStringLiteral("mocap-face"), tr("Performance Capture — Face"), tr("Animation"),
+        tr("MediaPipe face detector, mesh, and blendshape ONNX models used to capture facial expressions and head pose from video/webcam."),
+        QStringLiteral("~7 MB"), mocapAvailable ? QString() : tr("Requires a mocap-enabled build"),
+        mocapAvailable,
+        {
+            file(QStringLiteral("mocap/face"), QStringLiteral("face_detector.onnx"), mocapFaceBase, QStringLiteral("Face detector")),
+            file(QStringLiteral("mocap/face"), QStringLiteral("face_landmarks.onnx"), mocapFaceBase, QStringLiteral("Face landmarks")),
+            file(QStringLiteral("mocap/face"), QStringLiteral("face_blendshapes.onnx"), mocapFaceBase, QStringLiteral("Face blendshapes")),
+        }};
+    out << ModelSpec{
+        QStringLiteral("mocap-body"), tr("Performance Capture — Body"), tr("Animation"),
+        tr("MediaPipe BlazePose detector and landmark ONNX models used to capture full-body pose from video/webcam."),
+        QStringLiteral("Small"), mocapAvailable ? QString() : tr("Requires a mocap-enabled build"),
+        mocapAvailable,
+        {
+            file(QStringLiteral("mocap/pose"), QStringLiteral("pose_detector.onnx"), mocapPoseBase, QStringLiteral("Pose detector")),
+            file(QStringLiteral("mocap/pose"), QStringLiteral("pose_landmarks.onnx"), mocapPoseBase, QStringLiteral("Pose landmarks")),
+        }};
     return out;
 }
 
diff --git a/src/AnimationMerger.cpp b/src/AnimationMerger.cpp
index 698ddbd3b..c1297fc07 100644
--- a/src/AnimationMerger.cpp
+++ b/src/AnimationMerger.cpp
@@ -1346,6 +1346,205 @@ TargetBindFrame readTargetBindFrame(Ogre::Skeleton* skel,
 }
 } // namespace
 
+// ── BodyRetargeter — the applyMotionClip direction-match, per single frame ──
+struct BodyRetargeter::Impl {
+    TargetBindFrame tb;
+    std::vector<int> boneToCanon;   // per bone
+    Ogre::Quaternion CtInv = Ogre::Quaternion::IDENTITY;
+    int nBones = 0;
+    int Jc = 0;
+    // Harvested STANDING pose per bone (the calmest frame of the rig's existing
+    // authored animation) — the base local rotation each frame's articulation
+    // delta is composed onto. This is what makes arms sit at the chest instead
+    // of splayed at the T-pose bind. Mirrors applyMotionClip's legacy transport.
+    std::vector<Ogre::Quaternion> standLocal;     // per bone
+    std::vector<bool> haveStand;                  // per bone
+    std::vector<Ogre::Quaternion> Mc, McInv;      // per bone (roll correction)
+    bool restsAreIdentity = true;
+    bool haveAnyStand = false;
+    // neutral (first-frame) canonical quats — the reference the per-frame
+    // local-articulation delta is taken against.
+    std::array<std::array<float, 4>, 22> neutral{};
+    bool haveNeutral = false;
+};
+
+BodyRetargeter::BodyRetargeter(Ogre::Skeleton* skel)
+{
+    if (!skel) return;
+    d = std::make_shared<Impl>();
+    d->nBones = static_cast<int>(skel->getNumBones());
+    d->Jc = MotionInbetween::canonicalJointCount();
+    d->boneToCanon.assign(static_cast<size_t>(d->nBones), -1);
+    for (int i = 0; i < d->nBones; ++i)
+        d->boneToCanon[static_cast<size_t>(i)] =
+            MotionInbetween::canonicalIndexForBone(QString::fromStdString(
+                skel->getBone(static_cast<unsigned short>(i))->getName()));
+    d->tb = readTargetBindFrame(skel, d->boneToCanon);
+    d->CtInv = d->tb.Ct.Inverse();
+
+    // ── Harvest the STANDING pose (calmest frame of the rig's first authored,
+    //    non-generated animation) — the same pose applyMotionClip's legacy
+    //    transport composes onto. Without it the live arms sit at the T-pose
+    //    bind and look splayed. ──
+    d->standLocal.assign(static_cast<size_t>(d->nBones), Ogre::Quaternion::IDENTITY);
+    d->haveStand.assign(static_cast<size_t>(d->nBones), false);
+    Ogre::Animation* ref = nullptr;
+    for (unsigned short ai = 0; ai < skel->getNumAnimations(); ++ai) {
+        Ogre::Animation* a = skel->getAnimation(ai);
+        if (a && a->getName().rfind("generated_", 0) != 0) { ref = a; break; }
+    }
+    if (ref) {
+        const float len = ref->getLength();
+        const int samples = std::clamp(
+            static_cast<int>(std::lround(len * 30.0f)) + 1, 2, 301);
+        const auto& tracks = ref->_getNodeTrackList();
+        std::vector<double> energy(static_cast<size_t>(samples), 0.0);
+        for (const auto& [h, trk] : tracks) {
+            if (!trk || trk->getNumKeyFrames() == 0) continue;
+            Ogre::Quaternion prevQ;
+            for (int f = 0; f < samples; ++f) {
+                const float t = len * static_cast<float>(f)
+                                / static_cast<float>(samples - 1);
+                Ogre::TransformKeyFrame kf(nullptr, 0.0f);
+                trk->getInterpolatedKeyFrame(ref->_getTimeIndex(t), &kf);
+                const Ogre::Quaternion q = kf.getRotation();
+                if (f > 0) {
+                    const double dd = std::min(1.0, std::abs(
+                        static_cast<double>(q.Dot(prevQ))));
+                    energy[static_cast<size_t>(f)] += 2.0 * std::acos(dd);
+                }
+                prevQ = q;
+            }
+        }
+        int calm = 1;
+        for (int f = 2; f < samples; ++f)
+            if (energy[static_cast<size_t>(f)] < energy[static_cast<size_t>(calm)])
+                calm = f;
+        const float tCalm = len * static_cast<float>(calm)
+                            / static_cast<float>(samples - 1);
+        for (const auto& [h, trk] : tracks) {
+            if (!trk || trk->getNumKeyFrames() == 0) continue;
+            if (h >= static_cast<unsigned short>(d->nBones)) continue;
+            Ogre::TransformKeyFrame f0(nullptr, 0.0f);
+            trk->getInterpolatedKeyFrame(ref->_getTimeIndex(tCalm), &f0);
+            // A NodeAnimationTrack keyframe rotation is RELATIVE — Ogre applies
+            // it as node->rotate(kf) ON TOP of the bone's reset/bind local
+            // (applyToNode accumulates, it does NOT replace). evaluateFrame
+            // returns an ABSOLUTE local for Bone::setOrientation() (which
+            // replaces), so bake the bind in here: absoluteLocal = bind · kf.
+            // Without this, non-identity-rest bones drive wrong and the figure
+            // inverts under the live setOrientation path (baked-clip playback
+            // hid it by re-accumulating the reset pose).
+            d->standLocal[h] = d->tb.bindLocal[static_cast<size_t>(h)]
+                               * f0.getRotation();
+            d->haveStand[h] = true;
+            d->haveAnyStand = true;
+        }
+    }
+    // Rig bone rests identity? (Mixamo yes → Mc heuristic valid; UniRig/template
+    // no → skip Mc, use raw delta on the standing pose.)
+    for (int i = 0; i < d->nBones && d->restsAreIdentity; ++i) {
+        Ogre::Bone* b = skel->getBone(static_cast<unsigned short>(i));
+        if (!b->getInitialOrientation().equals(Ogre::Quaternion::IDENTITY,
+                                               Ogre::Radian(0.02f)))
+            d->restsAreIdentity = false;
+    }
+    d->Mc.assign(static_cast<size_t>(d->nBones), Ogre::Quaternion::IDENTITY);
+    d->McInv.assign(static_cast<size_t>(d->nBones), Ogre::Quaternion::IDENTITY);
+
+    // valid only if at least half the canonical roles map (the humanoid gate)
+    int mapped = 0;
+    for (int c = 0; c < d->Jc; ++c)
+        if (d->tb.roleBoneIdx[static_cast<size_t>(c)] >= 0) ++mapped;
+    m_valid = mapped * 2 >= d->Jc;
+}
+
+std::vector<std::pair<unsigned short, Ogre::Quaternion>>
+BodyRetargeter::evaluateFrame(
+    const std::array<std::array<float, 4>, 22>& canonicalQuats,
+    uint32_t resolvedMask) const
+{
+    std::vector<std::pair<unsigned short, Ogre::Quaternion>> out;
+    if (!m_valid || !d) return out;
+    const TargetBindFrame& tb = d->tb;
+    const int Jc = d->Jc;
+    auto clipQ = [&](const std::array<std::array<float, 4>, 22>& src, int joint)
+        -> Ogre::Quaternion {
+        const auto& q = src[static_cast<size_t>(joint)];
+        return Ogre::Quaternion(q[3], q[0], q[1], q[2]);   // (w,x,y,z)
+    };
+    // First frame becomes the NEUTRAL reference — the clip's "calm" frame, which
+    // is what applyMotionClip's legacy transport takes its per-joint LOCAL
+    // articulation delta and its Mc roll-correction frame against. Composing the
+    // delta onto the harvested STANDING pose (arms at chest) is what makes the
+    // live preview match the Record path.
+    if (!d->haveNeutral) {
+        d->neutral = canonicalQuats;
+        d->haveNeutral = true;
+        // Mc[i] = standWorldOf(bone)⁻¹ · clipQ(neutral, c) — Mixamo-only roll
+        // correction; on non-identity-rest rigs it is left identity.
+        if (d->haveAnyStand && d->restsAreIdentity) {
+            std::vector<Ogre::Quaternion> standW(static_cast<size_t>(d->nBones),
+                                                 Ogre::Quaternion::IDENTITY);
+            for (int i : tb.order) {
+                const int pi = tb.parentIdx[static_cast<size_t>(i)];
+                const Ogre::Quaternion Wp = (pi >= 0)
+                    ? standW[static_cast<size_t>(pi)] : Ogre::Quaternion::IDENTITY;
+                const Ogre::Quaternion localRot = d->haveStand[static_cast<size_t>(i)]
+                    ? d->standLocal[static_cast<size_t>(i)]
+                    : tb.bindLocal[static_cast<size_t>(i)];
+                standW[static_cast<size_t>(i)] = Wp * localRot;
+            }
+            for (int i = 0; i < d->nBones; ++i) {
+                const int c = d->boneToCanon[static_cast<size_t>(i)];
+                if (c <= 0 || c >= Jc) continue;   // root (c==0) keeps identity Mc
+                d->Mc[static_cast<size_t>(i)] =
+                    standW[static_cast<size_t>(i)].Inverse() * clipQ(d->neutral, c);
+                d->McInv[static_cast<size_t>(i)] = d->Mc[static_cast<size_t>(i)].Inverse();
+            }
+        }
+    }
+    for (int i : tb.order) {
+        const int c = d->boneToCanon[static_cast<size_t>(i)];
+        if (c < 0 || c >= Jc) continue;
+        const int pc = MotionInbetween::canonicalParentOf(c);
+        // world -> parent-relative LOCAL articulation, current and neutral
+        auto localArtic = [&](const std::array<std::array<float, 4>, 22>& src) {
+            return (pc >= 0 && pc < Jc)
+                ? clipQ(src, pc).Inverse() * clipQ(src, c)
+                : clipQ(src, c);
+        };
+        // base = harvested standing pose local (arms at chest), else bind local.
+        const Ogre::Quaternion base = d->haveStand[static_cast<size_t>(i)]
+            ? d->standLocal[static_cast<size_t>(i)]
+            : tb.bindLocal[static_cast<size_t>(i)];
+        // UNRESOLVED role (e.g. legs of a seated subject) → hold the standing
+        // pose; never drive a bone from a role PoseIK couldn't observe.
+        const bool resolved = (resolvedMask & (1u << static_cast<unsigned>(c))) != 0u;
+        if (!resolved) {
+            out.emplace_back(static_cast<unsigned short>(i), base);
+            continue;
+        }
+        if (c == 0) {
+            // Root/hip: MediaPipe/CMU bake the whole-body FACING into the hip.
+            // Locking the root to the standing pose keeps the figure upright
+            // (applying the full hip delta folds the torso forward). A subtle
+            // pelvic sway could be re-added later; upright + stable first.
+            out.emplace_back(static_cast<unsigned short>(i), base);
+            continue;
+        }
+        const Ogre::Quaternion cur = localArtic(canonicalQuats);
+        const Ogre::Quaternion ref = localArtic(d->neutral);
+        const Ogre::Quaternion delta = ref.Inverse() * cur;
+        // roll-corrected articulation, composed onto the standing pose.
+        const Ogre::Quaternion artic =
+            d->McInv[static_cast<size_t>(i)] * delta * d->Mc[static_cast<size_t>(i)];
+        const Ogre::Quaternion local = base * artic;
+        out.emplace_back(static_cast<unsigned short>(i), local);
+    }
+    return out;
+}
+
 float AnimationMerger::currentArmSpace(Ogre::Skeleton* skel,
                                        const std::string& animName)
 {
diff --git a/src/AnimationMerger.h b/src/AnimationMerger.h
index 87834853e..6798867f6 100644
--- a/src/AnimationMerger.h
+++ b/src/AnimationMerger.h
@@ -7,6 +7,39 @@
 #include <array>
 #include <vector>
 
+// Stateful per-frame body retargeter — the SAME legacy-transport math
+// applyMotionClip bakes into a clip, exposed for LIVE drive (mocap preview)
+// so the live path and the recorded clip can never diverge. Construct once
+// from the target skeleton (captures the bind frame, torso frame Ct, per-role
+// bind directions, and the rig's harvested STANDING pose from the calmest
+// frame of its first authored animation), then call evaluateFrame() per pose.
+//
+// Input: 22 canonical-role WORLD quaternions (x,y,z,w) from PoseIK — the same
+// array recordBody feeds applyMotionClip. Each joint's parent-relative LOCAL
+// articulation delta (vs the FIRST frame, cached as the neutral reference on
+// the first call) is composed onto the standing pose, with the Mixamo roll
+// correction Mc: local = standLocal · (Mc⁻¹ · delta · Mc). The root/hip is
+// locked to standing (facing is baked into the hip); unresolved roles hold
+// standing. Output: per-bone ABSOLUTE LOCAL orientation for
+// Bone::setOrientation() (Ogre node keyframes are absolute, not deltas).
+class BodyRetargeter {
+public:
+    explicit BodyRetargeter(Ogre::Skeleton* skel);
+    bool valid() const { return m_valid; }
+    // resolvedMask bit i set => canonical role i is tracked this frame; roles
+    // not set hold the standing pose. Returns {boneHandle -> local quat}.
+    // NOTE: the FIRST call lazily caches the neutral reference + precomputes Mc
+    // (hence the const method mutates *d through the shared_ptr). Single-thread
+    // use only (the mocap live/bake paths); call frames in order.
+    std::vector<std::pair<unsigned short, Ogre::Quaternion>>
+    evaluateFrame(const std::array<std::array<float, 4>, 22>& canonicalQuats,
+                  uint32_t resolvedMask) const;
+private:
+    struct Impl;
+    std::shared_ptr<Impl> d;   // shared_ptr so the class stays copyable/movable
+    bool m_valid = false;
+};
+
 class AnimationMerger {
 public:
     AnimationMerger() = delete;
diff --git a/src/AppLaunchHandler.cpp b/src/AppLaunchHandler.cpp
index 3293263ba..3f2c75e99 100644
--- a/src/AppLaunchHandler.cpp
+++ b/src/AppLaunchHandler.cpp
@@ -32,6 +32,7 @@ bool isCliSubcommand(const QString& arg)
         QStringLiteral("generate3d"),
         QStringLiteral("morph"),
         QStringLiteral("nodeanim"), QStringLiteral("ps1"), QStringLiteral("cloud"),
+        QStringLiteral("mocap"),
     };
     return kSubcommands.contains(arg);
 }
diff --git a/src/CLIPipeline.cpp b/src/CLIPipeline.cpp
index 94ee92877..bdc3c19d0 100644
--- a/src/CLIPipeline.cpp
+++ b/src/CLIPipeline.cpp
@@ -6,6 +6,7 @@
 #include "AlembicImporter.h"
 #include "SceneLightsIO.h"
 #include "SceneLightsCLI.h"
+#include "Mocap/MocapCLI.h"
 #include "AnimationMerger.h"
 #include "MotionInbetween.h"
 #include "MotionLibrary.h"
@@ -594,7 +595,10 @@ void CLIPipeline::writeOutput(const QString& text)
 
 void CLIPipeline::writeCliError(const QString& text)
 {
-    err() << text;
+    // Explicit flush: the CLI exits via _exit(), which skips the static
+    // QTextStream's destructor — without this the error text is silently
+    // lost in the stream buffer.
+    err() << text << Qt::flush;
 }
 
 void CLIPipeline::printUsage()
@@ -876,6 +880,12 @@ void CLIPipeline::printUsage()
         "  nodeanim <file> --list [--json]   List node-animation clips on a scene (props, doors, machinery,\n"
         "                                    animated lights — anything non-skeletal). Authoring on the CLI\n"
         "                                    side needs the C5 glTF/FBX exporter round-trip first.\n"
+        "  mocap <video> [--face] [--body] --mesh <meshfile> [-o out.glb] [--clip-name NAME]\n"
+        "              [--fps N] [--smooth-cutoff HZ] [--no-smooth] [--map overrides.json]\n"
+        "              [--no-head] [--algo sam3dbody|pose-ik] [--no-model] [--frames-dir DIR] [--json]\n"
+        "                                    Performance capture (needs -DENABLE_MOCAP): --face drives the\n"
+        "                                    mesh's ARKit-style morph targets (+ head rotation); --body\n"
+        "                                    retargets the tracked full-body pose onto the humanoid rig.\n"
         "\n"
         "  ps1 capture <iso> --bios <bios> [--frames N | --scene Ns] [--script in.json]\n"
         "              [--auto-input] [--tracked-only] [--smooth] [--drop-slivers]\n"
@@ -1610,6 +1620,7 @@ int CLIPipeline::run(int argc, char* argv[])
     else if (cmd == "uv") rc = cmdUv(argc, argv);
     else if (cmd == "hdri") rc = cmdHdri(argc, argv);
     else if (cmd == "light") rc = SceneLightsCLI::run(argc, argv);
+    else if (cmd == "mocap") rc = MocapCLI::run(argc, argv);
     else if (cmd == "retopo") rc = cmdRetopo(argc, argv);
     else if (cmd == "skin") rc = cmdSkin(argc, argv);
     else if (cmd == "rig") rc = cmdRig(argc, argv);
@@ -1655,6 +1666,7 @@ int CLIPipeline::run(int argc, char* argv[])
             {QStringLiteral("generate3d"), QStringLiteral("image_to_3d")},
             {QStringLiteral("material"), QStringLiteral("material_editor")},
             {QStringLiteral("segment"), QStringLiteral("ai_assist")},
+            {QStringLiteral("mocap"), QStringLiteral("mocap")},
         };
         const QString feature = cmdFeatureMap.value(cmd);
         if (!feature.isEmpty())
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index f910afbea..9e643b8f9 100755
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -171,6 +171,18 @@ NodeAnimationManager.cpp
 PoseLibrary.cpp
 VertexAnimationManager.cpp
 AlembicImporter.cpp
+Mocap/VideoFrameSource.cpp
+Mocap/OneEuroFilter.cpp
+Mocap/FaceCapMapper.cpp
+Mocap/FaceCapPose.cpp
+Mocap/FaceCapGeom.cpp
+Mocap/FaceCapPredictor.cpp
+Mocap/MocapRecorder.cpp
+Mocap/PoseCapPredictor.cpp
+Mocap/PoseIKSolver.cpp
+Mocap/MocapCLI.cpp
+Mocap/MocapController.cpp
+commands/RecordMocapClipCommand.cpp
 ApplyAtlas.cpp
 EmbeddedTextureCache.cpp
 NormalMapGenerator.cpp
@@ -767,6 +779,23 @@ if(ENABLE_PS1_RIP AND TARGET Qt6::Gamepad)
     target_link_libraries(${CMAKE_PROJECT_NAME} Qt6::Gamepad)
 endif()
 
+# Performance capture (epic #869): Qt Multimedia for the frame sources
+if(ENABLE_MOCAP)
+    target_link_libraries(${CMAKE_PROJECT_NAME} Qt6::Multimedia)
+    # macOS: the camera/microphone PERMISSION backends ship as STATIC Qt
+    # plugins (libqdarwin*permission.a). Merely linking QtMultimedia does NOT
+    # pull them in — without an explicit import, QCameraPermission's
+    # requestPermission() logs "Could not find permission plugin" and returns
+    # Denied instantly, so macOS never shows the prompt and the app never
+    # appears under Privacy & Security → Camera. Import them so the request
+    # reaches TCC. (Qt's QDarwin{Camera,Microphone}PermissionPlugin.)
+    if(APPLE)
+        qt_import_plugins(${CMAKE_PROJECT_NAME}
+            INCLUDE Qt6::QDarwinCameraPermissionPlugin
+                    Qt6::QDarwinMicrophonePermissionPlugin)
+    endif()
+endif()
+
 if(ENABLE_AUTO_UPDATER AND TARGET qtmesh-relauncher)
     add_dependencies(${CMAKE_PROJECT_NAME} qtmesh-relauncher)
     if(APPLE)
@@ -912,6 +941,11 @@ if(BUILD_TESTS)
 
     ADD_DEPENDENCIES(UnitTests ui)
 
+    # Performance capture (epic #869): Qt Multimedia for the frame sources
+    if(ENABLE_MOCAP)
+        target_link_libraries(UnitTests Qt6::Multimedia)
+    endif()
+
     if(ENABLE_PS1_RIP)
         add_dependencies(UnitTests qtmesh_ps1core_stub)
         if(TARGET qtmesh_ps1core_libretro)
@@ -1098,7 +1132,22 @@ endif()
 #  Configure Info.plist for Mac OS X
 ##############################################################
 if(APPLE)
-    configure_file (
+    # Configure the real Info.plist into the build tree AND set it as the
+    # bundle's plist on the target, so the .app that the plain build produces
+    # carries NSCameraUsageDescription + a stable CFBundleIdentifier + the file
+    # associations — not CMake's empty MACOSX_BUNDLE default. Without this the
+    # OS refuses the camera-permission prompt (empty bundle id + no usage
+    # string) and the app never appears under Privacy & Security → Camera.
+    # (Release/deploy.yml still copies the install-prefix copy too; harmless.)
+    set(_QTMESH_BUNDLE_PLIST "${CMAKE_CURRENT_BINARY_DIR}/QtMeshEditor-Info.plist")
+    configure_file(
+        "${CMAKE_CURRENT_SOURCE_DIR}/Info.plist.in"
+        "${_QTMESH_BUNDLE_PLIST}"
+        @ONLY)
+    set_target_properties(${CMAKE_PROJECT_NAME} PROPERTIES
+        MACOSX_BUNDLE_INFO_PLIST "${_QTMESH_BUNDLE_PLIST}")
+    # Keep the install-prefix copy for the release manual-copy step.
+    configure_file(
         "${CMAKE_CURRENT_SOURCE_DIR}/Info.plist.in"
         "${CMAKE_INSTALL_PREFIX}/Info.plist"
         @ONLY)
diff --git a/src/GamificationTypes.cpp b/src/GamificationTypes.cpp
index 6e165d061..65d9ba043 100644
--- a/src/GamificationTypes.cpp
+++ b/src/GamificationTypes.cpp
@@ -33,6 +33,11 @@ const QList<FeatureInfo>& featureCatalog()
          QStringLiteral("Create and animate morph (blend shape) targets.")},
         {QStringLiteral("motion_inbetween"), QStringLiteral("AI In-Betweening"),
          QStringLiteral("Fill gaps between keyframes with smooth, plausible motion.")},
+        // NB: adding a key here requires the matching DISCOVERY_FEATURES
+        // entry in qtmesh-cloud (the CLAUDE.md contract) — 'mocap' is
+        // coordinated as part of epic #869 Slice G.
+        {QStringLiteral("mocap"), QStringLiteral("Performance Capture"),
+         QStringLiteral("Capture facial and body performance from video or a live webcam.")},
         {QStringLiteral("pose_library"), QStringLiteral("Pose Library"),
          QStringLiteral("Save and reuse skeleton poses across animations.")},
         {QStringLiteral("vat_bake"), QStringLiteral("VAT Baking"),
diff --git a/src/GamificationTypes_test.cpp b/src/GamificationTypes_test.cpp
index 25356ac6e..02b0bb633 100644
--- a/src/GamificationTypes_test.cpp
+++ b/src/GamificationTypes_test.cpp
@@ -54,7 +54,11 @@ QJsonObject sampleStatsJson()
 TEST(GamificationTypes, FeatureCatalogMatchesCloudContract)
 {
     const auto& catalog = featureCatalog();
-    EXPECT_EQ(catalog.size(), 25);  // qtmesh-cloud DISCOVERY_FEATURES count
+    // qtmesh-cloud DISCOVERY_FEATURES count. 26 since epic #869 added the
+    // 'mocap' (Performance Capture) discovery cluster — the matching
+    // DISCOVERY_FEATURES entry is coordinated on the cloud side (CLAUDE.md
+    // contract).
+    EXPECT_EQ(catalog.size(), 26);
     for (const FeatureInfo& f : catalog) {
         EXPECT_TRUE(isValidEventKey(f.key)) << f.key.toStdString();
         EXPECT_FALSE(f.title.isEmpty());
diff --git a/src/Info.plist.in b/src/Info.plist.in
index 886eab2ca..3e1e53e6f 100644
--- a/src/Info.plist.in
+++ b/src/Info.plist.in
@@ -14,7 +14,7 @@
 	<key>CFBundleSignature</key>
 	<string>QtMeshEditor</string>
 	<key>CFBundleIdentifier</key>
-	<string>QtMeshEditor</string>
+	<string>com.qtmesheditor.app</string>
 	<key>CFBundleExecutable</key>
 	<string>QtMeshEditor</string>
 
@@ -43,6 +43,9 @@
 	<key>NSSupportsAutomaticGraphicsSwitching</key>
 	<true/>
 
+	<key>NSCameraUsageDescription</key>
+	<string>QtMeshEditor uses the camera for live performance capture.</string>
+
 	<key>CFBundleDocumentTypes</key>
 	<array>
 		<dict>
diff --git a/src/MCPServer.cpp b/src/MCPServer.cpp
index cfb1b888a..9f44e3840 100644
--- a/src/MCPServer.cpp
+++ b/src/MCPServer.cpp
@@ -11,6 +11,17 @@
 #include "VATBaker.h"
 #include "MorphAnimationManager.h"
 #include "AlembicImporter.h"
+#ifdef ENABLE_MOCAP
+#include "Mocap/FaceCapMapper.h"
+#include "Mocap/FaceCapPredictor.h"
+#include "Mocap/MocapRecorder.h"
+#include "Mocap/OneEuroFilter.h"
+#include "Mocap/PoseCapPredictor.h"
+#include "Mocap/PoseIKSolver.h"
+#include "Mocap/VideoFrameSource.h"
+#include "commands/RecordMocapClipCommand.h"
+#include "Mocap/MocapController.h"
+#endif
 #include "NodeAnimationManager.h"
 #include "PoseLibrary.h"
 #include "PrimitiveObject.h"
@@ -699,6 +710,12 @@ const QMap<QString, MCPServer::ToolHandler>& MCPServer::toolHandlers()
         {QStringLiteral("list_morph_targets"), &MCPServer::toolListMorphTargets},
         {QStringLiteral("set_morph_weight"), &MCPServer::toolSetMorphWeight},
         {QStringLiteral("import_alembic"), &MCPServer::toolImportAlembic},
+        {QStringLiteral("capture_face_from_video"), &MCPServer::toolCaptureFaceFromVideo},
+        {QStringLiteral("capture_body_from_video"), &MCPServer::toolCaptureBodyFromVideo},
+        {QStringLiteral("list_capture_devices"), &MCPServer::toolListCaptureDevices},
+        {QStringLiteral("start_live_capture"), &MCPServer::toolStartLiveCapture},
+        {QStringLiteral("stop_live_capture"), &MCPServer::toolStopLiveCapture},
+        {QStringLiteral("set_capture_channels"), &MCPServer::toolSetCaptureChannels},
         {QStringLiteral("play_vertex_animation"), &MCPServer::toolPlayVertexAnimation},
         {QStringLiteral("list_node_animations"), &MCPServer::toolListNodeAnimations},
         {QStringLiteral("add_node_animation_clip"), &MCPServer::toolAddNodeAnimationClip},
@@ -752,6 +769,8 @@ bool MCPServer::isHeavyTool(const QString &name)
         QStringLiteral("bake_vat"),
         QStringLiteral("list_morph_targets"),
         QStringLiteral("import_alembic"),
+        QStringLiteral("capture_face_from_video"),
+        QStringLiteral("capture_body_from_video"),
         QStringLiteral("cloud_upload")
     };
     return heavyTools.contains(name);
@@ -818,6 +837,8 @@ QJsonObject MCPServer::callTool(const QString &name, const QJsonObject &args)
             {QStringLiteral("generate_motion"), QStringLiteral("animation_blend")},
             {QStringLiteral("merge_animations"), QStringLiteral("animation_blend")},
             {QStringLiteral("segment_mesh"), QStringLiteral("ai_assist")},
+            {QStringLiteral("capture_face_from_video"), QStringLiteral("ai_assist")},
+            {QStringLiteral("capture_body_from_video"), QStringLiteral("ai_assist")},
             {QStringLiteral("generate_mesh_from_image"), QStringLiteral("image_to_3d")},
             {QStringLiteral("generate_pbr_maps"), QStringLiteral("pbr_synth")},
             {QStringLiteral("upscale_texture"), QStringLiteral("pbr_synth")},
@@ -6747,6 +6768,441 @@ QJsonObject MCPServer::toolSetMorphWeight(const QJsonObject &args)
 // Vertex-anim B3 (#519) — Alembic import + vertex-clip playback.
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// Performance capture (epic #869, Slice D #873)
+// ---------------------------------------------------------------------------
+
+QJsonObject MCPServer::toolCaptureFaceFromVideo(const QJsonObject &args)
+{
+    SentryReporter::addBreadcrumb("ai.tool_call", "capture_face_from_video");
+#ifndef ENABLE_MOCAP
+    Q_UNUSED(args);
+    return makeErrorResult(
+        "Error: this build has no performance-capture support. Rebuild with "
+        "-DENABLE_MOCAP=ON -DENABLE_ONNX=ON.");
+#else
+    const QString videoPath = args.value("video_path").toString();
+    if (videoPath.isEmpty())
+        return makeErrorResult("Error: missing required 'video_path' argument");
+    if (!QFileInfo::exists(videoPath))
+        return makeErrorResult(QString("Error: video not found: %1").arg(videoPath));
+
+    Manager* mgr = Manager::getSingletonPtr();
+    if (!mgr) return makeErrorResult("Error: Manager not available");
+
+    const QString entityName = args.value("entity_name").toString();
+    Ogre::Entity* entity = nullptr;
+    if (entityName.isEmpty()) {
+        // Schema says the target defaults to the selected entity — honour
+        // SelectionSet, then fall back to the first entity in the scene.
+        if (auto* sel = SelectionSet::getSingleton()) {
+            const auto resolved = sel->getResolvedEntities();
+            if (!resolved.isEmpty()) entity = resolved.first();
+        }
+    }
+    if (!entity) {
+        for (auto* ent : mgr->getEntities()) {
+            if (!ent || ent->getMovableType() != "Entity") continue;
+            if (entityName.isEmpty()
+                || QString::fromStdString(ent->getName()) == entityName) { entity = ent; break; }
+        }
+    }
+    if (!entity) {
+        return makeErrorResult(entityName.isEmpty()
+            ? QString("Error: No mesh entity found")
+            : QString("Error: Entity '%1' not found").arg(entityName));
+    }
+
+    const QStringList targets =
+        MorphAnimationManager::instance()->morphTargetsFor(entity);
+    const bool head = args.value("head").toBool(true);
+    if (targets.isEmpty() && !head)
+        return makeErrorResult(
+            "Error: the entity has no morph targets and head=false — nothing to record. "
+            "Face capture drives ARKit-style blendshape targets (jawOpen, mouthSmileLeft, ...).");
+
+    const FaceCapMapper::Mapping mapping =
+        FaceCapMapper::build(targets, args.value("map_path").toString());
+    if (!mapping.error.isEmpty())
+        return makeErrorResult(QString("Error: %1").arg(mapping.error));
+
+    if (!FaceCapPredictor::modelsPresent()
+        && FaceCapPredictor::ensureModelsBlocking().isEmpty())
+        return makeErrorResult(
+            "Error: face capture models are not available (download failed, offline "
+            "guard set, or not hosted yet). Set QTMESH_MOCAP_MODEL_BASE_URL or place "
+            "the graphs in " + FaceCapPredictor::modelDir());
+    auto predictor = std::make_shared<FaceCapPredictor>();
+    if (!predictor->load())
+        return makeErrorResult(QString("Error: %1").arg(predictor->lastError()));
+
+    double fps = args.value("fps").toDouble(30.0);
+    if (fps <= 0 || fps > 240) fps = 30.0;
+    const bool smooth = args.value("smooth").toBool(true);
+
+    auto source = std::make_shared<FileFrameSource>(videoPath, fps);
+    QString openError;
+    if (!source->open(&openError))
+        return makeErrorResult(QString("Error: %1").arg(openError));
+
+    auto samples = std::make_shared<std::vector<FaceSample>>();
+    auto weightFilters = std::make_shared<std::array<OneEuroFilter, 52>>();
+    auto headFilter = std::make_shared<OneEuroQuatFilter>();
+
+    QEventLoop loop;
+    bool finished = false;
+    QString streamError;
+    QObject::connect(source.get(), &VideoFrameSource::frameReady,
+                     [&, predictor, samples, weightFilters, headFilter](const MocapFrame& frame) {
+                         FaceSample s = predictor->predict(frame.image, frame.timeSec);
+                         if (smooth && s.confidence > 0.f) {
+                             for (int c = 0; c < 52; ++c)
+                                 s.weights[c] = static_cast<float>(
+                                     (*weightFilters)[c].filter(s.weights[c], s.timeSec));
+                             s.headRotation = headFilter->filter(s.headRotation, s.timeSec);
+                         }
+                         samples->push_back(s);
+                     });
+    QObject::connect(source.get(), &VideoFrameSource::finished, [&] {
+        finished = true; loop.quit();
+    });
+    QObject::connect(source.get(), &VideoFrameSource::errorOccurred,
+                     [&](const QString& message) {
+                         streamError = message; finished = true; loop.quit();
+                     });
+    source->start();
+    if (!finished)
+        loop.exec();
+    source->stop();
+    if (!streamError.isEmpty())
+        return makeErrorResult(QString("Error: %1").arg(streamError));
+    if (samples->empty())
+        return makeErrorResult("Error: the video produced no frames");
+
+    MocapRecorder::FaceRecordOptions options;
+    options.clipName = args.value("clip_name").toString(QStringLiteral("FaceCap"));
+    options.head = head;
+
+    return runOgreOp([&]() -> QJsonObject {
+        // ONE undoable step for the whole take
+        auto* cmd = new RecordMocapClipCommand(entity->getName(), *samples,
+                                               mapping, options);
+        UndoManager::getSingleton()->push(cmd);
+        const MocapRecorder::FaceRecordReport& report = cmd->report();
+        if (!report.ok())
+            return makeErrorResult(QString("Error: %1").arg(report.error));
+
+        const QString outputPath = args.value("output_path").toString();
+        if (!outputPath.isEmpty()) {
+            Ogre::SceneNode* node = entity->getParentSceneNode();
+            const QString fmt = CLIPipeline::formatForExtension(outputPath);
+            if (!node || MeshImporterExporter::exporter(
+                    node, QFileInfo(outputPath).absoluteFilePath(), fmt) != 0)
+                return makeErrorResult(
+                    QString("Error: recorded, but export to %1 failed").arg(outputPath));
+        }
+
+        GamificationManager::noteOperation(
+            QStringLiteral("mocap_face"),
+            {{QStringLiteral("frames"), static_cast<qint64>(report.framesProcessed)},
+             {QStringLiteral("keyframes"),
+              static_cast<qint64>(report.keyframesWritten + report.headKeyframesWritten)}},
+            GamificationManager::Surface::Mcp);
+
+        QJsonObject content;
+        content["ok"] = true;
+        content["clipName"] = report.clipName;
+        content["framesProcessed"] = report.framesProcessed;
+        content["framesNoFace"] = report.framesNoFace;
+        content["keyframesWritten"] = report.keyframesWritten;
+        content["headKeyframesWritten"] = report.headKeyframesWritten;
+        content["headTarget"] = report.headTarget;
+        content["clipLength"] = report.clipLength;
+        content["matchedChannels"] = QJsonArray::fromStringList(report.matchedChannels);
+        content["unmatchedCanonical"] = QJsonArray::fromStringList(report.unmatchedCanonical);
+        content["unmatchedMesh"] = QJsonArray::fromStringList(report.unmatchedMesh);
+        if (!outputPath.isEmpty())
+            content["output"] = outputPath;
+        return makeSuccessResult(
+            QString::fromUtf8(QJsonDocument(content).toJson(QJsonDocument::Indented)));
+    });
+#endif // ENABLE_MOCAP
+}
+
+QJsonObject MCPServer::toolListCaptureDevices(const QJsonObject &args)
+{
+    Q_UNUSED(args);
+    SentryReporter::addBreadcrumb("ai.tool_call", "list_capture_devices");
+#ifndef ENABLE_MOCAP
+    return makeErrorResult(
+        "Error: this build has no performance-capture support. Rebuild with "
+        "-DENABLE_MOCAP=ON -DENABLE_ONNX=ON.");
+#else
+    QJsonArray devices;
+    for (const auto& dev : CameraFrameSource::availableDevices()) {
+        QJsonObject o;
+        o["id"] = dev.id;
+        o["description"] = dev.description;
+        devices.append(o);
+    }
+    QJsonObject content;
+    content["devices"] = devices;
+    return makeSuccessResult(
+        QString::fromUtf8(QJsonDocument(content).toJson(QJsonDocument::Indented)));
+#endif
+}
+
+QJsonObject MCPServer::toolStartLiveCapture(const QJsonObject &args)
+{
+    SentryReporter::addBreadcrumb("ai.tool_call", "start_live_capture");
+#ifndef ENABLE_MOCAP
+    Q_UNUSED(args);
+    return makeErrorResult(
+        "Error: this build has no performance-capture support. Rebuild with "
+        "-DENABLE_MOCAP=ON -DENABLE_ONNX=ON.");
+#else
+    Manager* mgr = Manager::getSingletonPtr();
+    if (!mgr || !mgr->getMainWindow())
+        return makeErrorResult(
+            "Error: live capture needs the GUI (run with --with-mcp, not --mcp).");
+    auto* c = MocapController::instance();
+    if (c->state() != MocapController::Idle)
+        return makeErrorResult("Error: a live capture session is already running");
+
+    // Optional channel toggles — set BEFORE starting so drivability is
+    // evaluated with the requested channels (default: leave as-is).
+    if (args.contains("face")) c->setFaceEnabled(args.value("face").toBool());
+    if (args.contains("head")) c->setHeadEnabled(args.value("head").toBool());
+    if (args.contains("body")) c->setBodyEnabled(args.value("body").toBool());
+
+    // video_path drives from a file (the macOS-camera-blocked path); else the
+    // webcam device_id (empty = default camera).
+    const QString videoPath = args.value("video_path").toString();
+    const bool started = videoPath.isEmpty()
+        ? c->startPreview(args.value("device_id").toString())
+        : c->startPreviewFromVideo(videoPath);
+    if (!started)
+        return makeErrorResult(QString("Error: %1").arg(c->statusMessage()));
+    QJsonObject content;
+    content["ok"] = true;
+    content["state"] = "previewing";
+    content["source"] = videoPath.isEmpty() ? "camera" : "video";
+    content["matchedChannels"] = c->matchedChannelCount();
+    content["headAvailable"] = c->headAvailable();
+    content["bodyAvailable"] = c->bodyAvailable();
+    return makeSuccessResult(
+        QString::fromUtf8(QJsonDocument(content).toJson(QJsonDocument::Indented)));
+#endif
+}
+
+QJsonObject MCPServer::toolSetCaptureChannels(const QJsonObject &args)
+{
+    SentryReporter::addBreadcrumb("ai.tool_call", "set_capture_channels");
+#ifndef ENABLE_MOCAP
+    Q_UNUSED(args);
+    return makeErrorResult(
+        "Error: this build has no performance-capture support. Rebuild with "
+        "-DENABLE_MOCAP=ON -DENABLE_ONNX=ON.");
+#else
+    auto* c = MocapController::instance();
+    if (args.contains("face")) c->setFaceEnabled(args.value("face").toBool());
+    if (args.contains("head")) c->setHeadEnabled(args.value("head").toBool());
+    if (args.contains("body")) c->setBodyEnabled(args.value("body").toBool());
+    QJsonObject content;
+    content["ok"] = true;
+    content["face"] = c->faceEnabled();
+    content["head"] = c->headEnabled();
+    content["body"] = c->bodyEnabled();
+    content["matchedChannels"] = c->matchedChannelCount();
+    content["headAvailable"] = c->headAvailable();
+    content["bodyAvailable"] = c->bodyAvailable();
+    return makeSuccessResult(
+        QString::fromUtf8(QJsonDocument(content).toJson(QJsonDocument::Indented)));
+#endif
+}
+
+QJsonObject MCPServer::toolStopLiveCapture(const QJsonObject &args)
+{
+    SentryReporter::addBreadcrumb("ai.tool_call", "stop_live_capture");
+#ifndef ENABLE_MOCAP
+    Q_UNUSED(args);
+    return makeErrorResult(
+        "Error: this build has no performance-capture support. Rebuild with "
+        "-DENABLE_MOCAP=ON -DENABLE_ONNX=ON.");
+#else
+    auto* c = MocapController::instance();
+    if (c->state() == MocapController::Idle)
+        return makeErrorResult("Error: no live capture session is running");
+    if (args.value("record").toBool(false)
+        && c->state() == MocapController::Recording)
+        c->stopRecording();
+    c->stopPreview();
+    QJsonObject content;
+    content["ok"] = true;
+    content["status"] = c->statusMessage();
+    return makeSuccessResult(
+        QString::fromUtf8(QJsonDocument(content).toJson(QJsonDocument::Indented)));
+#endif
+}
+
+QJsonObject MCPServer::toolCaptureBodyFromVideo(const QJsonObject &args)
+{
+    SentryReporter::addBreadcrumb("ai.tool_call", "capture_body_from_video");
+#ifndef ENABLE_MOCAP
+    Q_UNUSED(args);
+    return makeErrorResult(
+        "Error: this build has no performance-capture support. Rebuild with "
+        "-DENABLE_MOCAP=ON -DENABLE_ONNX=ON.");
+#else
+    const QString videoPath = args.value("video_path").toString();
+    if (videoPath.isEmpty())
+        return makeErrorResult("Error: missing required 'video_path' argument");
+    if (!QFileInfo::exists(videoPath))
+        return makeErrorResult(QString("Error: video not found: %1").arg(videoPath));
+
+    Manager* mgr = Manager::getSingletonPtr();
+    if (!mgr) return makeErrorResult("Error: Manager not available");
+
+    const QString entityName = args.value("entity_name").toString();
+    Ogre::Entity* entity = nullptr;
+    if (entityName.isEmpty()) {
+        // Schema says the target defaults to the selected entity — honour
+        // SelectionSet, then fall back to the first entity in the scene.
+        if (auto* sel = SelectionSet::getSingleton()) {
+            const auto resolved = sel->getResolvedEntities();
+            if (!resolved.isEmpty()) entity = resolved.first();
+        }
+    }
+    if (!entity) {
+        for (auto* ent : mgr->getEntities()) {
+            if (!ent || ent->getMovableType() != "Entity") continue;
+            if (entityName.isEmpty()
+                || QString::fromStdString(ent->getName()) == entityName) { entity = ent; break; }
+        }
+    }
+    if (!entity) {
+        return makeErrorResult(entityName.isEmpty()
+            ? QString("Error: No mesh entity found")
+            : QString("Error: Entity '%1' not found").arg(entityName));
+    }
+    if (!entity->hasSkeleton())
+        return makeErrorResult(
+            "Error: the entity is not skinned — body capture retargets onto a "
+            "humanoid skeleton (auto_rig with skin:true first).");
+
+    if (!PoseCapPredictor::modelsPresent()
+        && PoseCapPredictor::ensureModelsBlocking().isEmpty())
+        return makeErrorResult(
+            "Error: pose capture models are not available (download failed, offline "
+            "guard set, or not hosted yet). Set QTMESH_MOCAP_MODEL_BASE_URL or place "
+            "the graphs in " + PoseCapPredictor::modelDir());
+    auto posePredictor = std::make_shared<PoseCapPredictor>();
+    if (!posePredictor->load())
+        return makeErrorResult(QString("Error: %1").arg(posePredictor->lastError()));
+
+    double fps = args.value("fps").toDouble(30.0);
+    if (fps <= 0 || fps > 240) fps = 30.0;
+    const bool smooth = args.value("smooth").toBool(true);
+    const QString algo = args.value("algo").toString(QStringLiteral("sam3dbody"));
+
+    auto source = std::make_shared<FileFrameSource>(videoPath, fps);
+    QString openError;
+    if (!source->open(&openError))
+        return makeErrorResult(QString("Error: %1").arg(openError));
+
+    auto poseSamples = std::make_shared<std::vector<PoseSample>>();
+    QEventLoop loop;
+    bool finished = false;
+    QString streamError;
+    QObject::connect(source.get(), &VideoFrameSource::frameReady,
+                     [&, posePredictor, poseSamples](const MocapFrame& frame) {
+                         poseSamples->push_back(
+                             posePredictor->predict(frame.image, frame.timeSec));
+                     });
+    QObject::connect(source.get(), &VideoFrameSource::finished, [&] {
+        finished = true; loop.quit();
+    });
+    QObject::connect(source.get(), &VideoFrameSource::errorOccurred,
+                     [&](const QString& message) {
+                         streamError = message; finished = true; loop.quit();
+                     });
+    source->start();
+    if (!finished)
+        loop.exec();
+    source->stop();
+    if (!streamError.isEmpty())
+        return makeErrorResult(QString("Error: %1").arg(streamError));
+
+    std::vector<std::vector<std::array<float, 4>>> clipQuats;
+    {
+        std::array<OneEuroQuatFilter, PoseIK::kCanonicalRoles> roleFilters;
+        PoseIK::Solver solver;
+        for (const PoseSample& s : *poseSamples) {
+            if (s.confidence <= 0.f)
+                continue;
+            PoseIK::FrameResult fr =
+                solver.solveFrame(s.world.data(), s.visibility.data());
+            if (smooth)
+                for (int r = 0; r < PoseIK::kCanonicalRoles; ++r)
+                    fr.quats[r] = roleFilters[r].filter(fr.quats[r], s.timeSec);
+            clipQuats.push_back(std::vector<std::array<float, 4>>(
+                fr.quats.begin(), fr.quats.end()));
+        }
+    }
+    if (clipQuats.size() < 2)
+        return makeErrorResult("Error: no person tracked in the video");
+
+    MocapRecorder::BodyRecordOptions options;
+    options.clipName = args.value("clip_name").toString(QStringLiteral("BodyCap"));
+    options.algorithmUsed = QStringLiteral("pose-ik");
+    options.fallbackReason = algo == QLatin1String("pose-ik")
+        ? QString()
+        : QStringLiteral("sam3dbody model not available (checkpoint access "
+                         "pending — see THIRD_PARTY_AI_MODELS.md); used pose-ik");
+
+    return runOgreOp([&]() -> QJsonObject {
+        auto* cmd = new RecordBodyClipCommand(entity->getName(), clipQuats,
+                                              static_cast<int>(fps), options);
+        UndoManager::getSingleton()->push(cmd);
+        MocapRecorder::BodyRecordReport report = cmd->report();
+        report.framesProcessed = static_cast<int>(poseSamples->size());
+        if (!report.ok())
+            return makeErrorResult(QString("Error: %1").arg(report.error));
+
+        const QString outputPath = args.value("output_path").toString();
+        if (!outputPath.isEmpty()) {
+            Ogre::SceneNode* node = entity->getParentSceneNode();
+            const QString fmt = CLIPipeline::formatForExtension(outputPath);
+            if (!node || MeshImporterExporter::exporter(
+                    node, QFileInfo(outputPath).absoluteFilePath(), fmt) != 0)
+                return makeErrorResult(
+                    QString("Error: recorded, but export to %1 failed").arg(outputPath));
+        }
+
+        GamificationManager::noteOperation(
+            QStringLiteral("mocap_body"),
+            {{QStringLiteral("frames"), static_cast<qint64>(report.framesProcessed)},
+             {QStringLiteral("tracks"), static_cast<qint64>(report.tracksWritten)}},
+            GamificationManager::Surface::Mcp);
+
+        QJsonObject content;
+        content["ok"] = true;
+        content["clipName"] = report.clipName;
+        content["algorithmUsed"] = report.algorithmUsed;
+        if (!report.fallbackReason.isEmpty())
+            content["fallbackReason"] = report.fallbackReason;
+        content["framesProcessed"] = report.framesProcessed;
+        content["rolesResolved"] = report.rolesResolved;
+        content["tracksWritten"] = report.tracksWritten;
+        content["clipLength"] = report.clipLength;
+        if (!outputPath.isEmpty())
+            content["output"] = outputPath;
+        return makeSuccessResult(
+            QString::fromUtf8(QJsonDocument(content).toJson(QJsonDocument::Indented)));
+    });
+#endif // ENABLE_MOCAP
+}
+
 QJsonObject MCPServer::toolImportAlembic(const QJsonObject &args)
 {
     SentryReporter::addBreadcrumb("ai.tool_call", "import_alembic");
@@ -9575,6 +10031,103 @@ QJsonArray MCPServer::buildToolsList()
         );
     }
 
+    // capture_face_from_video (epic #869, Slice D #873)
+    {
+        QJsonObject props;
+        props["video_path"] = QJsonObject{{"type", "string"}, {"description", "Path to a video file of a face performance."}};
+        props["entity_name"] = QJsonObject{{"type", "string"}, {"description", "Target entity (default: first/selected entity)."}};
+        props["output_path"] = QJsonObject{{"type", "string"}, {"description", "Optional export path (e.g. out.glb) written after recording."}};
+        props["clip_name"] = QJsonObject{{"type", "string"}, {"description", "Morph weight clip name (default FaceCap)."}};
+        props["fps"] = QJsonObject{{"type", "number"}, {"description", "Capture rate; frames are decimated to this (default 30)."}};
+        props["smooth"] = QJsonObject{{"type", "boolean"}, {"description", "One-Euro smoothing (default true)."}};
+        props["map_path"] = QJsonObject{{"type", "string"}, {"description", "Optional JSON mapping-override sidecar."}};
+        props["head"] = QJsonObject{{"type", "boolean"}, {"description", "Also record head pose (default true)."}};
+        QJsonArray required;
+        required.append("video_path");
+        appendTool(
+            "capture_face_from_video",
+            "Performance capture: run the face-capture models over a video and record the "
+            "expressions as morph-target weight keyframes (plus head rotation) on the entity, "
+            "as ONE undoable clip. The entity needs ARKit-style blendshape morph targets "
+            "(jawOpen, mouthSmileLeft, ...). Unmatched channels are reported, never dropped. "
+            "Requires a build with ENABLE_MOCAP=ON; models download on first use.",
+            props,
+            required
+        );
+    }
+
+    // capture_body_from_video (epic #869, Slice E #874)
+    {
+        QJsonObject props;
+        props["video_path"] = QJsonObject{{"type", "string"}, {"description", "Path to a video of a full-body performance."}};
+        props["entity_name"] = QJsonObject{{"type", "string"}, {"description", "Target skinned entity (default: first/selected)."}};
+        props["output_path"] = QJsonObject{{"type", "string"}, {"description", "Optional export path written after recording."}};
+        props["clip_name"] = QJsonObject{{"type", "string"}, {"description", "Skeletal clip name (default BodyCap)."}};
+        props["fps"] = QJsonObject{{"type", "number"}, {"description", "Capture rate (default 30)."}};
+        props["smooth"] = QJsonObject{{"type", "boolean"}, {"description", "One-Euro smoothing (default true)."}};
+        props["algo"] = QJsonObject{{"type", "string"}, {"description", "sam3dbody (quality path; falls back while its checkpoints are gated) or pose-ik."}};
+        QJsonArray required;
+        required.append("video_path");
+        appendTool(
+            "capture_body_from_video",
+            "Performance capture: track a person in a video and record the full-body pose as a "
+            "skeletal animation on the entity's humanoid rig (rotation-only, root locked, "
+            "ONE undoable clip). Needs a skinned mesh resolving at least half of the 22 "
+            "canonical roles. Requires a build with ENABLE_MOCAP=ON; models download on first use.",
+            props,
+            required
+        );
+    }
+
+    // live capture (epic #869, Slice F #875) — GUI-attached sessions only
+    {
+        QJsonObject props;
+        appendTool(
+            "list_capture_devices",
+            "List the available camera devices for live performance capture "
+            "(id + description). Requires a build with ENABLE_MOCAP=ON.",
+            props, QJsonArray());
+    }
+    {
+        QJsonObject props;
+        props["device_id"] = QJsonObject{{"type", "string"}, {"description", "Camera id from list_capture_devices (default camera when omitted)."}};
+        props["video_path"] = QJsonObject{{"type", "string"}, {"description", "Drive from a VIDEO FILE instead of the camera (the macOS-camera-blocked path). Local path, not a URL."}};
+        props["face"] = QJsonObject{{"type", "boolean"}, {"description", "Enable Face (morph-target) drive. Default: leave current toggle."}};
+        props["head"] = QJsonObject{{"type", "boolean"}, {"description", "Enable Head-bone drive."}};
+        props["body"] = QJsonObject{{"type", "boolean"}, {"description", "Enable full-body drive (humanoid rig)."}};
+        QJsonArray required;
+        appendTool(
+            "start_live_capture",
+            "Start a live performance-capture preview driving the SELECTED entity's morph "
+            "targets + Head bone + (humanoid) body — the GUI Performance Capture panel's "
+            "session. Source is the webcam (device_id) or a video file (video_path). The "
+            "face/head/body flags toggle channels before starting. Only works in --with-mcp "
+            "(GUI) mode. Follow with stop_live_capture.",
+            props, required);
+    }
+    {
+        QJsonObject props;
+        props["face"] = QJsonObject{{"type", "boolean"}, {"description", "Enable/disable the Face (morph-target) channel."}};
+        props["head"] = QJsonObject{{"type", "boolean"}, {"description", "Enable/disable the Head-bone channel."}};
+        props["body"] = QJsonObject{{"type", "boolean"}, {"description", "Enable/disable the full-body channel."}};
+        appendTool(
+            "set_capture_channels",
+            "Set the Face/Head/Body capture channel toggles for the SELECTED entity (the "
+            "Performance Capture checkboxes). Returns each flag plus what the selection can "
+            "actually drive (matchedChannels, headAvailable, bodyAvailable). Set BEFORE "
+            "start_live_capture, or between sessions.",
+            props, QJsonArray());
+    }
+    {
+        QJsonObject props;
+        props["record"] = QJsonObject{{"type", "boolean"}, {"description", "true: stop and commit the recording in progress (if any) before stopping the preview."}};
+        appendTool(
+            "stop_live_capture",
+            "Stop the live performance-capture preview started by start_live_capture, "
+            "restoring the entity's prior state exactly.",
+            props, QJsonArray());
+    }
+
     // import_alembic
     {
         QJsonObject props;
diff --git a/src/MCPServer.h b/src/MCPServer.h
index 7400a820f..28d133e31 100644
--- a/src/MCPServer.h
+++ b/src/MCPServer.h
@@ -286,6 +286,12 @@ private slots:
     /// live scene as a VAT_POSE-animated mesh. Args: `file` (path). Heavy —
     /// decodes the cache + builds an entity. Needs a build with ENABLE_ALEMBIC.
     QJsonObject toolImportAlembic(const QJsonObject &args);
+    QJsonObject toolCaptureFaceFromVideo(const QJsonObject &args);
+    QJsonObject toolCaptureBodyFromVideo(const QJsonObject &args);
+    QJsonObject toolListCaptureDevices(const QJsonObject &args);
+    QJsonObject toolStartLiveCapture(const QJsonObject &args);
+    QJsonObject toolStopLiveCapture(const QJsonObject &args);
+    QJsonObject toolSetCaptureChannels(const QJsonObject &args);
 
     /// Vertex-anim B3 (#519): enable + play a vertex-animation clip on an
     /// entity. Args: `entity`, `animation`. Light — state poke on a live entity.
diff --git a/src/MeshImporterExporter.cpp b/src/MeshImporterExporter.cpp
index 22ee0fadc..1a3c9dd65 100755
--- a/src/MeshImporterExporter.cpp
+++ b/src/MeshImporterExporter.cpp
@@ -3060,6 +3060,13 @@ std::vector<MorphWeightClip> collectMorphWeightClips(const Ogre::Entity* entity,
                 }
             }
         }
+        if (std::getenv("QTMESH_MOCAP_DEBUG")) {
+            float mn = 1e9f, mx = -1e9f;
+            for (float w : clip.weights) { mn = std::min(mn, w); mx = std::max(mx, w); }
+            std::fprintf(stderr, "[export] clip '%s' rows=%zu targets=%d "
+                         "influenceRange=[%.3f,%.3f]\n", nm.c_str(),
+                         clip.times.size(), numTargets, mn, mx);
+        }
         out.push_back(std::move(clip));
     }
     return out;
diff --git a/src/Mocap/FaceCapCanonicalData.h b/src/Mocap/FaceCapCanonicalData.h
new file mode 100644
index 000000000..1c57cb1c0
--- /dev/null
+++ b/src/Mocap/FaceCapCanonicalData.h
@@ -0,0 +1,305 @@
+#ifndef FACECAPCANONICALDATA_H
+#define FACECAPCANONICALDATA_H
+
+// GENERATED from the MediaPipe reference data (do not hand-edit; see
+// scripts/export-facecap-onnx.py and docs/MOCAP_SPIKE.md).
+// Sources (Apache-2.0, Google MediaPipe):
+//  - canonical_face_model.obj (face_geometry module): 468 canonical
+//    face-mesh vertex positions in centimetres, +X right / +Y up / +Z
+//    toward the camera; the head-pose Procrustes reference.
+//  - geometry_pipeline_metadata_landmarks.pbtxt: the 33 weighted
+//    landmarks MediaPipe uses for its Procrustes fit.
+//  - face_blendshapes_graph.cc: the 146-landmark subset fed to the
+//    blendshape model and the canonical 52 blendshape names in the
+//    model output order.
+
+#include <array>
+
+namespace FaceCap {
+
+inline constexpr int kBlendshapeCount = 52;
+inline constexpr std::array<const char*, kBlendshapeCount> kBlendshapeNames = {
+    "_neutral", "browDownLeft", "browDownRight", "browInnerUp",
+    "browOuterUpLeft", "browOuterUpRight", "cheekPuff", "cheekSquintLeft",
+    "cheekSquintRight", "eyeBlinkLeft", "eyeBlinkRight", "eyeLookDownLeft",
+    "eyeLookDownRight", "eyeLookInLeft", "eyeLookInRight", "eyeLookOutLeft",
+    "eyeLookOutRight", "eyeLookUpLeft", "eyeLookUpRight", "eyeSquintLeft",
+    "eyeSquintRight", "eyeWideLeft", "eyeWideRight", "jawForward",
+    "jawLeft", "jawOpen", "jawRight", "mouthClose",
+    "mouthDimpleLeft", "mouthDimpleRight", "mouthFrownLeft", "mouthFrownRight",
+    "mouthFunnel", "mouthLeft", "mouthLowerDownLeft", "mouthLowerDownRight",
+    "mouthPressLeft", "mouthPressRight", "mouthPucker", "mouthRight",
+    "mouthRollLower", "mouthRollUpper", "mouthShrugLower", "mouthShrugUpper",
+    "mouthSmileLeft", "mouthSmileRight", "mouthStretchLeft", "mouthStretchRight",
+    "mouthUpperUpLeft", "mouthUpperUpRight", "noseSneerLeft", "noseSneerRight",
+};
+
+inline constexpr int kBlendshapeInputLandmarks = 146;
+inline constexpr std::array<int, kBlendshapeInputLandmarks> kBlendshapeLandmarkSubset = {
+    0, 1, 4, 5, 6, 7, 8, 10, 13, 14, 17, 21, 33, 37, 39,
+    40, 46, 52, 53, 54, 55, 58, 61, 63, 65, 66, 67, 70, 78, 80,
+    81, 82, 84, 87, 88, 91, 93, 95, 103, 105, 107, 109, 127, 132, 133,
+    136, 144, 145, 146, 148, 149, 150, 152, 153, 154, 155, 157, 158, 159, 160,
+    161, 162, 163, 168, 172, 173, 176, 178, 181, 185, 191, 195, 197, 234, 246,
+    249, 251, 263, 267, 269, 270, 276, 282, 283, 284, 285, 288, 291, 293, 295,
+    296, 297, 300, 308, 310, 311, 312, 314, 317, 318, 321, 323, 324, 332, 334,
+    336, 338, 356, 361, 362, 365, 373, 374, 375, 377, 378, 379, 380, 381, 382,
+    384, 385, 386, 387, 388, 389, 390, 397, 398, 400, 402, 405, 409, 415, 454,
+    466, 468, 469, 470, 471, 472, 473, 474, 475, 476, 477,
+};
+
+inline constexpr int kCanonicalVertexCount = 468;
+// x,y,z per vertex, centimetres.
+inline constexpr std::array<float, kCanonicalVertexCount * 3> kCanonicalFaceModel = {
+    0.000000f, -3.406404f, 5.979507f, 0.000000f, -1.126865f, 7.475604f,
+    0.000000f, -2.089024f, 6.058267f, -0.463928f, 0.955357f, 6.633583f,
+    0.000000f, -0.463170f, 7.586580f, 0.000000f, 0.365669f, 7.242870f,
+    0.000000f, 2.473255f, 5.788627f, -4.253081f, 2.577646f, 3.279702f,
+    0.000000f, 4.019042f, 5.284764f, 0.000000f, 4.885979f, 5.385258f,
+    0.000000f, 8.261778f, 4.481535f, 0.000000f, -3.706811f, 5.864924f,
+    0.000000f, -3.918301f, 5.569430f, 0.000000f, -3.994436f, 5.219482f,
+    0.000000f, -4.542400f, 5.404754f, 0.000000f, -4.745577f, 5.529457f,
+    0.000000f, -5.019567f, 5.601448f, 0.000000f, -5.365123f, 5.535441f,
+    0.000000f, -6.149624f, 5.071372f, 0.000000f, -1.501095f, 7.112196f,
+    -0.416106f, -1.466449f, 6.447657f, -7.087960f, 5.434801f, 0.099620f,
+    -2.628639f, 2.035898f, 3.848121f, -3.198363f, 1.985815f, 3.796952f,
+    -3.775151f, 2.039402f, 3.646194f, -4.465819f, 2.422950f, 3.155168f,
+    -2.164289f, 2.189867f, 3.851822f, -3.208229f, 3.223926f, 4.115822f,
+    -2.673803f, 3.205337f, 4.092203f, -3.745193f, 3.165286f, 3.972409f,
+    -4.161018f, 3.059069f, 3.719554f, -5.062006f, 1.934418f, 2.776093f,
+    -2.266659f, -7.425768f, 4.389812f, -4.445859f, 2.663991f, 3.173422f,
+    -7.214530f, 2.263009f, 0.073150f, -5.799793f, 2.349546f, 2.204059f,
+    -2.844939f, -0.720868f, 4.433130f, -0.711452f, -3.329355f, 5.877044f,
+    -0.606033f, -3.924562f, 5.444923f, -1.431615f, -3.500953f, 5.496189f,
+    -1.914910f, -3.803146f, 5.028930f, -1.131043f, -3.973937f, 5.189648f,
+    -1.563548f, -4.082763f, 4.842263f, -2.650112f, -5.003649f, 4.188483f,
+    -0.427049f, -1.094134f, 7.360529f, -0.496396f, -0.475659f, 7.440358f,
+    -5.253307f, 3.881582f, 3.363159f, -1.718698f, 0.974609f, 4.558359f,
+    -1.608635f, -0.942516f, 5.814193f, -1.651267f, -0.610868f, 5.581319f,
+    -4.765501f, -0.701554f, 3.534632f, -0.478306f, 0.295766f, 7.101013f,
+    -3.734964f, 4.508230f, 4.550454f, -4.588603f, 4.302037f, 4.048484f,
+    -6.279331f, 6.615427f, 1.425850f, -1.220941f, 4.142165f, 5.106035f,
+    -2.193489f, 3.100317f, 4.000575f, -3.102642f, -4.352984f, 4.095905f,
+    -6.719682f, -4.788645f, -1.745401f, -1.193824f, -1.306795f, 5.737747f,
+    -0.729766f, -1.593712f, 5.833208f, -2.456206f, -4.342621f, 4.283884f,
+    -2.204823f, -4.304508f, 4.162499f, -4.985894f, 4.802461f, 3.751977f,
+    -1.592294f, -1.257709f, 5.456949f, -2.644548f, 4.524654f, 4.921559f,
+    -2.760292f, 5.100971f, 5.015990f, -3.523964f, 8.005976f, 3.729163f,
+    -5.599763f, 5.715470f, 2.724259f, -3.063932f, 6.566144f, 4.529981f,
+    -5.720968f, 4.254584f, 2.830852f, -6.374393f, 4.785590f, 1.591691f,
+    -0.672728f, -3.688016f, 5.737804f, -1.262560f, -3.787691f, 5.417779f,
+    -1.732553f, -3.952767f, 5.000579f, -1.043625f, -1.464973f, 5.662455f,
+    -2.321234f, -4.329069f, 4.258156f, -2.056846f, -4.477671f, 4.520883f,
+    -2.153084f, -4.276322f, 4.038093f, -0.946874f, -1.035249f, 6.512274f,
+    -1.469132f, -4.036351f, 4.604908f, -1.024340f, -3.989851f, 4.926693f,
+    -0.533422f, -3.993222f, 5.138202f, -0.769720f, -6.095394f, 4.985883f,
+    -0.699606f, -5.291850f, 5.448304f, -0.669687f, -4.949770f, 5.509612f,
+    -0.630947f, -4.695101f, 5.449371f, -0.583218f, -4.517982f, 5.339869f,
+    -1.537170f, -4.423206f, 4.745470f, -1.615600f, -4.475942f, 4.813632f,
+    -1.729053f, -4.618680f, 4.854463f, -1.838624f, -4.828746f, 4.823737f,
+    -2.368250f, -3.106237f, 4.868096f, -7.542244f, -1.049282f, -2.431321f,
+    0.000000f, -1.724003f, 6.601390f, -1.826614f, -4.399531f, 4.399021f,
+    -1.929558f, -4.411831f, 4.497052f, -0.597442f, -2.013686f, 5.866456f,
+    -1.405627f, -1.714196f, 5.241087f, -0.662449f, -1.819321f, 5.863759f,
+    -2.342340f, 0.572222f, 4.294303f, -3.327324f, 0.104863f, 4.113860f,
+    -1.726175f, -0.919165f, 5.273355f, -5.133204f, 7.485602f, 2.660442f,
+    -4.538641f, 6.319907f, 3.683424f, -3.986562f, 5.109487f, 4.466315f,
+    -2.169681f, -5.440433f, 4.455874f, -1.395634f, 5.011963f, 5.316032f,
+    -1.619500f, 6.599217f, 4.921106f, -1.891399f, 8.236377f, 4.274997f,
+    -4.195832f, 2.235205f, 3.375099f, -5.733342f, 1.411738f, 2.431726f,
+    -1.859887f, 2.355757f, 3.843181f, -4.988612f, 3.074654f, 3.083858f,
+    -1.303263f, 1.416453f, 4.831091f, -1.305757f, -0.672779f, 6.415959f,
+    -6.465170f, 0.937119f, 1.689873f, -5.258659f, 0.945811f, 2.974312f,
+    -4.432338f, 0.722096f, 3.522615f, -3.300681f, 0.861641f, 3.872784f,
+    -2.430178f, 1.131492f, 4.039035f, -1.820731f, 1.467954f, 4.224124f,
+    -0.563221f, 2.307693f, 5.566789f, -6.338145f, -0.529279f, 1.881175f,
+    -5.587698f, 3.208071f, 2.687839f, -0.242624f, -1.462857f, 7.071491f,
+    -1.611251f, 0.339326f, 4.895421f, -7.743095f, 2.364999f, -2.005167f,
+    -1.391142f, 1.851048f, 4.448999f, -1.785794f, -0.978284f, 4.850470f,
+    -4.670959f, 2.664461f, 3.084075f, -1.333970f, -0.283761f, 6.097047f,
+    -7.270895f, -2.890917f, -2.252455f, -1.856432f, 2.585245f, 3.757904f,
+    -0.923388f, 0.073076f, 6.671944f, -5.000589f, -6.135128f, 1.892523f,
+    -5.085276f, -7.178590f, 0.714711f, -7.159291f, -0.811820f, -0.072044f,
+    -5.843051f, -5.248023f, 0.924091f, -6.847258f, 3.662916f, 0.724695f,
+    -2.412942f, -8.258853f, 4.119213f, -0.179909f, -1.689864f, 6.573301f,
+    -2.103655f, -0.163946f, 4.566119f, -6.407571f, 2.236021f, 1.560843f,
+    -3.670075f, 2.360153f, 3.635230f, -3.177186f, 2.294265f, 3.775704f,
+    -2.196121f, -4.598322f, 4.479786f, -6.234883f, -1.944430f, 1.663542f,
+    -1.292924f, -9.295920f, 4.094063f, -3.210651f, -8.533278f, 2.802001f,
+    -4.068926f, -7.993109f, 1.925119f, 0.000000f, 6.545390f, 5.027311f,
+    0.000000f, -9.403378f, 4.264492f, -2.724032f, 2.315802f, 3.777151f,
+    -2.288460f, 2.398891f, 3.697603f, -1.998311f, 2.496547f, 3.689148f,
+    -6.130040f, 3.399261f, 2.038516f, -2.288460f, 2.886504f, 3.775031f,
+    -2.724032f, 2.961810f, 3.871767f, -3.177186f, 2.964136f, 3.876973f,
+    -3.670075f, 2.927714f, 3.724325f, -4.018389f, 2.857357f, 3.482983f,
+    -7.555811f, 4.106811f, -0.991917f, -4.018389f, 2.483695f, 3.440898f,
+    0.000000f, -2.521945f, 5.932265f, -1.776217f, -2.683946f, 5.213116f,
+    -1.222237f, -1.182444f, 5.952465f, -0.731493f, -2.536683f, 5.815343f,
+    0.000000f, 3.271027f, 5.236015f, -4.135272f, -6.996638f, 2.671970f,
+    -3.311811f, -7.660815f, 3.382963f, -1.313701f, -8.639995f, 4.702456f,
+    -5.940524f, -6.223629f, -0.631468f, -1.998311f, 2.743838f, 3.744030f,
+    -0.901447f, 1.236992f, 5.754256f, 0.000000f, -8.765243f, 4.891441f,
+    -2.308977f, -8.974196f, 3.609070f, -6.954154f, -2.439843f, -0.131163f,
+    -1.098819f, -4.458788f, 5.120727f, -1.181124f, -4.579996f, 5.189564f,
+    -1.255818f, -4.787901f, 5.237051f, -1.325085f, -5.106507f, 5.205010f,
+    -1.546388f, -5.819392f, 4.757893f, -1.953754f, -4.183892f, 4.431713f,
+    -2.117802f, -4.137093f, 4.555096f, -2.285339f, -4.051196f, 4.582438f,
+    -2.850160f, -3.665720f, 4.484994f, -5.278538f, -2.238942f, 2.861224f,
+    -0.946709f, 1.907628f, 5.196779f, -1.314173f, 3.104912f, 4.231404f,
+    -1.780000f, 2.860000f, 3.881555f, -1.845110f, -4.098880f, 4.247264f,
+    -5.436187f, -4.030482f, 2.109852f, -0.766444f, 3.182131f, 4.861453f,
+    -1.938616f, -6.614410f, 4.521085f, 0.000000f, 1.059413f, 6.774605f,
+    -0.516573f, 1.583572f, 6.148363f, 0.000000f, 1.728369f, 6.316750f,
+    -1.246815f, 0.230297f, 5.681036f, 0.000000f, -7.942194f, 5.181173f,
+    0.000000f, -6.991499f, 5.153478f, -0.997827f, -6.930921f, 4.979576f,
+    -3.288807f, -5.382514f, 3.795752f, -2.311631f, -1.566237f, 4.590085f,
+    -2.680250f, -6.111567f, 4.096152f, -3.832928f, -1.537326f, 4.137731f,
+    -2.961860f, -2.274215f, 4.440943f, -4.386901f, -2.683286f, 3.643886f,
+    -1.217295f, -7.834465f, 4.969286f, -1.542374f, -0.136843f, 5.201008f,
+    -3.878377f, -6.041764f, 3.311079f, -3.084037f, -6.809842f, 3.814195f,
+    -3.747321f, -4.503545f, 3.726453f, -6.094129f, -3.205991f, 1.473482f,
+    -4.588995f, -4.728726f, 2.983221f, -6.583231f, -3.941269f, 0.070268f,
+    -3.492580f, -3.195820f, 4.130198f, -1.255543f, 0.802341f, 5.307551f,
+    -1.126122f, -0.933602f, 6.538785f, -1.443109f, -1.142774f, 5.905127f,
+    -0.923043f, -0.529042f, 7.003423f, -1.755386f, 3.529117f, 4.327696f,
+    -2.632589f, 3.713828f, 4.364629f, -3.388062f, 3.721976f, 4.309028f,
+    -4.075766f, 3.675413f, 4.076063f, -4.622910f, 3.474691f, 3.646321f,
+    -5.171755f, 2.535753f, 2.670867f, -7.297331f, 0.763172f, -0.048769f,
+    -4.706828f, 1.651000f, 3.109532f, -4.071712f, 1.476821f, 3.476944f,
+    -3.269817f, 1.470659f, 3.731945f, -2.527572f, 1.617311f, 3.865444f,
+    -1.970894f, 1.858505f, 3.961782f, -1.579543f, 2.097941f, 4.084996f,
+    -7.664182f, 0.673132f, -2.435867f, -1.397041f, -1.340139f, 5.630378f,
+    -0.884838f, 0.658740f, 6.233232f, -0.767097f, -0.968035f, 7.077932f,
+    -0.460213f, -1.334106f, 6.787447f, -0.748618f, -1.067994f, 6.798303f,
+    -1.236408f, -1.585568f, 5.480490f, -0.387306f, -1.409990f, 6.957705f,
+    -0.319925f, -1.607931f, 6.508676f, -1.639633f, 2.556298f, 3.863736f,
+    -1.255645f, 2.467144f, 4.203800f, -1.031362f, 2.382663f, 4.615849f,
+    -4.253081f, 2.772296f, 3.315305f, -4.530000f, 2.910000f, 3.339685f,
+    0.463928f, 0.955357f, 6.633583f, 4.253081f, 2.577646f, 3.279702f,
+    0.416106f, -1.466449f, 6.447657f, 7.087960f, 5.434801f, 0.099620f,
+    2.628639f, 2.035898f, 3.848121f, 3.198363f, 1.985815f, 3.796952f,
+    3.775151f, 2.039402f, 3.646194f, 4.465819f, 2.422950f, 3.155168f,
+    2.164289f, 2.189867f, 3.851822f, 3.208229f, 3.223926f, 4.115822f,
+    2.673803f, 3.205337f, 4.092203f, 3.745193f, 3.165286f, 3.972409f,
+    4.161018f, 3.059069f, 3.719554f, 5.062006f, 1.934418f, 2.776093f,
+    2.266659f, -7.425768f, 4.389812f, 4.445859f, 2.663991f, 3.173422f,
+    7.214530f, 2.263009f, 0.073150f, 5.799793f, 2.349546f, 2.204059f,
+    2.844939f, -0.720868f, 4.433130f, 0.711452f, -3.329355f, 5.877044f,
+    0.606033f, -3.924562f, 5.444923f, 1.431615f, -3.500953f, 5.496189f,
+    1.914910f, -3.803146f, 5.028930f, 1.131043f, -3.973937f, 5.189648f,
+    1.563548f, -4.082763f, 4.842263f, 2.650112f, -5.003649f, 4.188483f,
+    0.427049f, -1.094134f, 7.360529f, 0.496396f, -0.475659f, 7.440358f,
+    5.253307f, 3.881582f, 3.363159f, 1.718698f, 0.974609f, 4.558359f,
+    1.608635f, -0.942516f, 5.814193f, 1.651267f, -0.610868f, 5.581319f,
+    4.765501f, -0.701554f, 3.534632f, 0.478306f, 0.295766f, 7.101013f,
+    3.734964f, 4.508230f, 4.550454f, 4.588603f, 4.302037f, 4.048484f,
+    6.279331f, 6.615427f, 1.425850f, 1.220941f, 4.142165f, 5.106035f,
+    2.193489f, 3.100317f, 4.000575f, 3.102642f, -4.352984f, 4.095905f,
+    6.719682f, -4.788645f, -1.745401f, 1.193824f, -1.306795f, 5.737747f,
+    0.729766f, -1.593712f, 5.833208f, 2.456206f, -4.342621f, 4.283884f,
+    2.204823f, -4.304508f, 4.162499f, 4.985894f, 4.802461f, 3.751977f,
+    1.592294f, -1.257709f, 5.456949f, 2.644548f, 4.524654f, 4.921559f,
+    2.760292f, 5.100971f, 5.015990f, 3.523964f, 8.005976f, 3.729163f,
+    5.599763f, 5.715470f, 2.724259f, 3.063932f, 6.566144f, 4.529981f,
+    5.720968f, 4.254584f, 2.830852f, 6.374393f, 4.785590f, 1.591691f,
+    0.672728f, -3.688016f, 5.737804f, 1.262560f, -3.787691f, 5.417779f,
+    1.732553f, -3.952767f, 5.000579f, 1.043625f, -1.464973f, 5.662455f,
+    2.321234f, -4.329069f, 4.258156f, 2.056846f, -4.477671f, 4.520883f,
+    2.153084f, -4.276322f, 4.038093f, 0.946874f, -1.035249f, 6.512274f,
+    1.469132f, -4.036351f, 4.604908f, 1.024340f, -3.989851f, 4.926693f,
+    0.533422f, -3.993222f, 5.138202f, 0.769720f, -6.095394f, 4.985883f,
+    0.699606f, -5.291850f, 5.448304f, 0.669687f, -4.949770f, 5.509612f,
+    0.630947f, -4.695101f, 5.449371f, 0.583218f, -4.517982f, 5.339869f,
+    1.537170f, -4.423206f, 4.745470f, 1.615600f, -4.475942f, 4.813632f,
+    1.729053f, -4.618680f, 4.854463f, 1.838624f, -4.828746f, 4.823737f,
+    2.368250f, -3.106237f, 4.868096f, 7.542244f, -1.049282f, -2.431321f,
+    1.826614f, -4.399531f, 4.399021f, 1.929558f, -4.411831f, 4.497052f,
+    0.597442f, -2.013686f, 5.866456f, 1.405627f, -1.714196f, 5.241087f,
+    0.662449f, -1.819321f, 5.863759f, 2.342340f, 0.572222f, 4.294303f,
+    3.327324f, 0.104863f, 4.113860f, 1.726175f, -0.919165f, 5.273355f,
+    5.133204f, 7.485602f, 2.660442f, 4.538641f, 6.319907f, 3.683424f,
+    3.986562f, 5.109487f, 4.466315f, 2.169681f, -5.440433f, 4.455874f,
+    1.395634f, 5.011963f, 5.316032f, 1.619500f, 6.599217f, 4.921106f,
+    1.891399f, 8.236377f, 4.274997f, 4.195832f, 2.235205f, 3.375099f,
+    5.733342f, 1.411738f, 2.431726f, 1.859887f, 2.355757f, 3.843181f,
+    4.988612f, 3.074654f, 3.083858f, 1.303263f, 1.416453f, 4.831091f,
+    1.305757f, -0.672779f, 6.415959f, 6.465170f, 0.937119f, 1.689873f,
+    5.258659f, 0.945811f, 2.974312f, 4.432338f, 0.722096f, 3.522615f,
+    3.300681f, 0.861641f, 3.872784f, 2.430178f, 1.131492f, 4.039035f,
+    1.820731f, 1.467954f, 4.224124f, 0.563221f, 2.307693f, 5.566789f,
+    6.338145f, -0.529279f, 1.881175f, 5.587698f, 3.208071f, 2.687839f,
+    0.242624f, -1.462857f, 7.071491f, 1.611251f, 0.339326f, 4.895421f,
+    7.743095f, 2.364999f, -2.005167f, 1.391142f, 1.851048f, 4.448999f,
+    1.785794f, -0.978284f, 4.850470f, 4.670959f, 2.664461f, 3.084075f,
+    1.333970f, -0.283761f, 6.097047f, 7.270895f, -2.890917f, -2.252455f,
+    1.856432f, 2.585245f, 3.757904f, 0.923388f, 0.073076f, 6.671944f,
+    5.000589f, -6.135128f, 1.892523f, 5.085276f, -7.178590f, 0.714711f,
+    7.159291f, -0.811820f, -0.072044f, 5.843051f, -5.248023f, 0.924091f,
+    6.847258f, 3.662916f, 0.724695f, 2.412942f, -8.258853f, 4.119213f,
+    0.179909f, -1.689864f, 6.573301f, 2.103655f, -0.163946f, 4.566119f,
+    6.407571f, 2.236021f, 1.560843f, 3.670075f, 2.360153f, 3.635230f,
+    3.177186f, 2.294265f, 3.775704f, 2.196121f, -4.598322f, 4.479786f,
+    6.234883f, -1.944430f, 1.663542f, 1.292924f, -9.295920f, 4.094063f,
+    3.210651f, -8.533278f, 2.802001f, 4.068926f, -7.993109f, 1.925119f,
+    2.724032f, 2.315802f, 3.777151f, 2.288460f, 2.398891f, 3.697603f,
+    1.998311f, 2.496547f, 3.689148f, 6.130040f, 3.399261f, 2.038516f,
+    2.288460f, 2.886504f, 3.775031f, 2.724032f, 2.961810f, 3.871767f,
+    3.177186f, 2.964136f, 3.876973f, 3.670075f, 2.927714f, 3.724325f,
+    4.018389f, 2.857357f, 3.482983f, 7.555811f, 4.106811f, -0.991917f,
+    4.018389f, 2.483695f, 3.440898f, 1.776217f, -2.683946f, 5.213116f,
+    1.222237f, -1.182444f, 5.952465f, 0.731493f, -2.536683f, 5.815343f,
+    4.135272f, -6.996638f, 2.671970f, 3.311811f, -7.660815f, 3.382963f,
+    1.313701f, -8.639995f, 4.702456f, 5.940524f, -6.223629f, -0.631468f,
+    1.998311f, 2.743838f, 3.744030f, 0.901447f, 1.236992f, 5.754256f,
+    2.308977f, -8.974196f, 3.609070f, 6.954154f, -2.439843f, -0.131163f,
+    1.098819f, -4.458788f, 5.120727f, 1.181124f, -4.579996f, 5.189564f,
+    1.255818f, -4.787901f, 5.237051f, 1.325085f, -5.106507f, 5.205010f,
+    1.546388f, -5.819392f, 4.757893f, 1.953754f, -4.183892f, 4.431713f,
+    2.117802f, -4.137093f, 4.555096f, 2.285339f, -4.051196f, 4.582438f,
+    2.850160f, -3.665720f, 4.484994f, 5.278538f, -2.238942f, 2.861224f,
+    0.946709f, 1.907628f, 5.196779f, 1.314173f, 3.104912f, 4.231404f,
+    1.780000f, 2.860000f, 3.881555f, 1.845110f, -4.098880f, 4.247264f,
+    5.436187f, -4.030482f, 2.109852f, 0.766444f, 3.182131f, 4.861453f,
+    1.938616f, -6.614410f, 4.521085f, 0.516573f, 1.583572f, 6.148363f,
+    1.246815f, 0.230297f, 5.681036f, 0.997827f, -6.930921f, 4.979576f,
+    3.288807f, -5.382514f, 3.795752f, 2.311631f, -1.566237f, 4.590085f,
+    2.680250f, -6.111567f, 4.096152f, 3.832928f, -1.537326f, 4.137731f,
+    2.961860f, -2.274215f, 4.440943f, 4.386901f, -2.683286f, 3.643886f,
+    1.217295f, -7.834465f, 4.969286f, 1.542374f, -0.136843f, 5.201008f,
+    3.878377f, -6.041764f, 3.311079f, 3.084037f, -6.809842f, 3.814195f,
+    3.747321f, -4.503545f, 3.726453f, 6.094129f, -3.205991f, 1.473482f,
+    4.588995f, -4.728726f, 2.983221f, 6.583231f, -3.941269f, 0.070268f,
+    3.492580f, -3.195820f, 4.130198f, 1.255543f, 0.802341f, 5.307551f,
+    1.126122f, -0.933602f, 6.538785f, 1.443109f, -1.142774f, 5.905127f,
+    0.923043f, -0.529042f, 7.003423f, 1.755386f, 3.529117f, 4.327696f,
+    2.632589f, 3.713828f, 4.364629f, 3.388062f, 3.721976f, 4.309028f,
+    4.075766f, 3.675413f, 4.076063f, 4.622910f, 3.474691f, 3.646321f,
+    5.171755f, 2.535753f, 2.670867f, 7.297331f, 0.763172f, -0.048769f,
+    4.706828f, 1.651000f, 3.109532f, 4.071712f, 1.476821f, 3.476944f,
+    3.269817f, 1.470659f, 3.731945f, 2.527572f, 1.617311f, 3.865444f,
+    1.970894f, 1.858505f, 3.961782f, 1.579543f, 2.097941f, 4.084996f,
+    7.664182f, 0.673132f, -2.435867f, 1.397041f, -1.340139f, 5.630378f,
+    0.884838f, 0.658740f, 6.233232f, 0.767097f, -0.968035f, 7.077932f,
+    0.460213f, -1.334106f, 6.787447f, 0.748618f, -1.067994f, 6.798303f,
+    1.236408f, -1.585568f, 5.480490f, 0.387306f, -1.409990f, 6.957705f,
+    0.319925f, -1.607931f, 6.508676f, 1.639633f, 2.556298f, 3.863736f,
+    1.255645f, 2.467144f, 4.203800f, 1.031362f, 2.382663f, 4.615849f,
+    4.253081f, 2.772296f, 3.315305f, 4.530000f, 2.910000f, 3.339685f,
+};
+
+inline constexpr int kProcrustesBasisCount = 33;
+inline constexpr std::array<int, kProcrustesBasisCount> kProcrustesLandmarkIds = {
+    4, 6, 10, 33, 54, 67, 117, 119, 121, 127, 129, 132, 133, 136, 143, 147, 198, 205, 263, 284, 297, 346, 348, 350, 356, 358, 361, 362, 365, 372, 376, 420, 425,
+};
+inline constexpr std::array<float, kProcrustesBasisCount> kProcrustesWeights = {
+    0.070910f, 0.032100f, 0.008447f, 0.058724f, 0.007667f, 0.009078f,
+    0.009792f, 0.014565f, 0.018591f, 0.005198f, 0.120625f, 0.005560f,
+    0.053286f, 0.066890f, 0.014817f, 0.014263f, 0.025462f, 0.047252f,
+    0.058724f, 0.007667f, 0.009078f, 0.009792f, 0.014565f, 0.018591f,
+    0.005198f, 0.120625f, 0.005560f, 0.053286f, 0.066890f, 0.014817f,
+    0.014263f, 0.025462f, 0.047252f,
+};
+
+} // namespace FaceCap
+
+#endif // FACECAPCANONICALDATA_H
diff --git a/src/Mocap/FaceCapGeom.cpp b/src/Mocap/FaceCapGeom.cpp
new file mode 100644
index 000000000..320c36c73
--- /dev/null
+++ b/src/Mocap/FaceCapGeom.cpp
@@ -0,0 +1,297 @@
+#include "FaceCapGeom.h"
+
+#include <algorithm>
+#include <cmath>
+
+namespace FaceCapGeom {
+
+namespace {
+
+constexpr float kMinScale = 0.1484375f;
+constexpr float kMaxScale = 0.75f;
+constexpr float kAnchorOffset = 0.5f;
+
+float sigmoid(float x)
+{
+    x = std::clamp(x, -100.f, 100.f);
+    return x >= 0.f ? 1.f / (1.f + std::exp(-x))
+                    : std::exp(x) / (1.f + std::exp(x));
+}
+
+float normalizeAngle(float a)
+{
+    return a - 2.f * static_cast<float>(M_PI)
+                   * std::floor((a + static_cast<float>(M_PI))
+                                / (2.f * static_cast<float>(M_PI)));
+}
+
+// Bilinear sample of an RGB888 image with zero border (MediaPipe BORDER_ZERO,
+// non-antialiased — the parity requirement from the spike).
+inline void sampleBilinear(const uchar* bits, int w, int h, qsizetype stride,
+                           float x, float y, float rgb[3])
+{
+    const int x0 = static_cast<int>(std::floor(x));
+    const int y0 = static_cast<int>(std::floor(y));
+    const float fx = x - x0;
+    const float fy = y - y0;
+    float acc[3] = {0.f, 0.f, 0.f};
+    for (int dy = 0; dy < 2; ++dy) {
+        const int yy = y0 + dy;
+        if (yy < 0 || yy >= h)
+            continue;
+        const float wy = dy ? fy : 1.f - fy;
+        const uchar* row = bits + yy * stride;
+        for (int dx = 0; dx < 2; ++dx) {
+            const int xx = x0 + dx;
+            if (xx < 0 || xx >= w)
+                continue;
+            const float wgt = wy * (dx ? fx : 1.f - fx);
+            const uchar* px = row + xx * 3;
+            acc[0] += wgt * px[0];
+            acc[1] += wgt * px[1];
+            acc[2] += wgt * px[2];
+        }
+    }
+    rgb[0] = acc[0];
+    rgb[1] = acc[1];
+    rgb[2] = acc[2];
+}
+
+// Generic affine resample: out(u,v) <- img(origin + u*du + v*dv), the shared
+// core of letterbox and rotated-crop. Indices follow cv2.warpAffine's
+// integer-index convention — the one the spike's parity proof pinned down
+// (docs/MOCAP_SPIKE.md); do NOT switch to pixel-centre sampling.
+void resampleToTensor(const QImage& rgb888, int size, float lo, float hi,
+                      float originX, float originY, float dux, float duy,
+                      float dvx, float dvy, float* out)
+{
+    const uchar* bits = rgb888.constBits();
+    const int w = rgb888.width();
+    const int h = rgb888.height();
+    const qsizetype stride = rgb888.bytesPerLine();
+    const float scale = (hi - lo) / 255.f;
+    float* dst = out;
+    for (int v = 0; v < size; ++v) {
+        for (int u = 0; u < size; ++u) {
+            const float sx = originX + u * dux + v * dvx;
+            const float sy = originY + u * duy + v * dvy;
+            float rgb[3];
+            sampleBilinear(bits, w, h, stride, sx, sy, rgb);
+            *dst++ = rgb[0] * scale + lo;
+            *dst++ = rgb[1] * scale + lo;
+            *dst++ = rgb[2] * scale + lo;
+        }
+    }
+}
+
+float iou(const std::array<float, 4>& a, const std::array<float, 4>& b)
+{
+    const float x1 = std::max(a[0], b[0]);
+    const float y1 = std::max(a[1], b[1]);
+    const float x2 = std::min(a[0] + a[2], b[0] + b[2]);
+    const float y2 = std::min(a[1] + a[3], b[1] + b[3]);
+    const float inter = std::max(0.f, x2 - x1) * std::max(0.f, y2 - y1);
+    const float uni = a[2] * a[3] + b[2] * b[3] - inter;
+    return uni > 0.f ? inter / uni : 0.f;
+}
+
+}  // namespace
+
+Letterbox letterboxToTensor(const QImage& rgb888, int size, float lo, float hi,
+                            float* out)
+{
+    Letterbox lb;
+    const int w = rgb888.width();
+    const int h = rgb888.height();
+    if (w <= 0 || h <= 0)
+        return lb;
+    const float s = static_cast<float>(size) / std::max(w, h);
+    const float ox = (size - w * s) / 2.f;
+    const float oy = (size - h * s) / 2.f;
+    lb.padX = ox / size;
+    lb.padY = oy / size;
+    lb.fracX = w * s / size;
+    lb.fracY = h * s / size;
+    // output (u,v) -> input ((u - ox) / s, (v - oy) / s)
+    resampleToTensor(rgb888, size, lo, hi, -ox / s, -oy / s, 1.f / s, 0.f, 0.f,
+                     1.f / s, out);
+    return lb;
+}
+
+std::vector<std::array<float, 2>> genSsdAnchors(int inputSize,
+                                                const std::vector<int>& strides)
+{
+    std::vector<std::array<float, 2>> anchors;
+    const int n = static_cast<int>(strides.size());
+    auto scaleFor = [&](int i) {
+        return n == 1 ? (kMinScale + kMaxScale) * 0.5f
+                      : kMinScale + (kMaxScale - kMinScale) * i / (n - 1);
+    };
+    int layer = 0;
+    while (layer < n) {
+        int last = layer;
+        int scalesInLayer = 0;
+        while (last < n && strides[last] == strides[layer]) {
+            scalesInLayer += 2;  // scale + interpolated scale (aspect 1.0)
+            (void)scaleFor(last);
+            ++last;
+        }
+        const int stride = strides[layer];
+        const int fm = (inputSize + stride - 1) / stride;
+        for (int y = 0; y < fm; ++y)
+            for (int x = 0; x < fm; ++x)
+                for (int k = 0; k < scalesInLayer; ++k)
+                    anchors.push_back({(x + kAnchorOffset) / fm,
+                                       (y + kAnchorOffset) / fm});
+        layer = last;
+    }
+    return anchors;
+}
+
+std::vector<Detection> decodeDetections(
+    const float* rawBoxes, const float* rawScores,
+    const std::vector<std::array<float, 2>>& anchors, int inputSize,
+    int numKeypoints, float minScore, float iouThreshold)
+{
+    const int boxDim = 4 + 2 * numKeypoints;
+    std::vector<Detection> candidates;
+    for (size_t i = 0; i < anchors.size(); ++i) {
+        const float score = sigmoid(rawScores[i]);
+        if (score < minScore)
+            continue;
+        const float* box = rawBoxes + i * boxDim;
+        Detection d;
+        d.score = score;
+        const float cx = box[0] / inputSize + anchors[i][0];
+        const float cy = box[1] / inputSize + anchors[i][1];
+        const float w = box[2] / inputSize;
+        const float h = box[3] / inputSize;
+        d.box = {cx - w / 2.f, cy - h / 2.f, w, h};
+        d.keypoints.reserve(numKeypoints);
+        for (int k = 0; k < numKeypoints; ++k)
+            d.keypoints.push_back({box[4 + 2 * k] / inputSize + anchors[i][0],
+                                   box[5 + 2 * k] / inputSize + anchors[i][1]});
+        candidates.push_back(std::move(d));
+    }
+
+    // weighted NMS (MediaPipe): clusters above the IoU threshold merge into a
+    // score-weighted average instead of being discarded.
+    std::sort(candidates.begin(), candidates.end(),
+              [](const Detection& a, const Detection& b) { return a.score > b.score; });
+    std::vector<Detection> out;
+    std::vector<bool> used(candidates.size(), false);
+    for (size_t i = 0; i < candidates.size(); ++i) {
+        if (used[i])
+            continue;
+        std::vector<size_t> cluster{i};
+        for (size_t j = i + 1; j < candidates.size(); ++j) {
+            if (!used[j]
+                && iou(candidates[i].box, candidates[j].box) > iouThreshold)
+                cluster.push_back(j);
+        }
+        float total = 0.f;
+        Detection merged = candidates[i];
+        std::fill(merged.box.begin(), merged.box.end(), 0.f);
+        for (auto& kp : merged.keypoints)
+            kp = {0.f, 0.f};
+        for (size_t j : cluster) {
+            used[j] = true;
+            total += candidates[j].score;
+        }
+        for (size_t j : cluster) {
+            const float w = candidates[j].score / total;
+            for (int k = 0; k < 4; ++k)
+                merged.box[k] += w * candidates[j].box[k];
+            for (size_t k = 0; k < merged.keypoints.size(); ++k) {
+                merged.keypoints[k][0] += w * candidates[j].keypoints[k][0];
+                merged.keypoints[k][1] += w * candidates[j].keypoints[k][1];
+            }
+        }
+        out.push_back(std::move(merged));
+    }
+    return out;
+}
+
+RotatedRect rectFromFaceDetection(const Detection& det, int imgW, int imgH)
+{
+    RotatedRect r;
+    r.cx = (det.box[0] + det.box[2] / 2.f) * imgW;
+    r.cy = (det.box[1] + det.box[3] / 2.f) * imgH;
+    const float dx = (det.keypoints[1][0] - det.keypoints[0][0]) * imgW;
+    const float dy = (det.keypoints[1][1] - det.keypoints[0][1]) * imgH;
+    r.angle = normalizeAngle(-std::atan2(-dy, dx));  // target angle 0
+    const float side = std::max(det.box[2] * imgW, det.box[3] * imgH) * 1.5f;
+    r.w = r.h = side;
+    return r;
+}
+
+RotatedRect rectFromFaceLandmarks(const float* landmarksXyz, int count,
+                                  int imgW, int imgH)
+{
+    RotatedRect r;
+    if (count < 264)
+        return r;
+    float minX = landmarksXyz[0], maxX = landmarksXyz[0];
+    float minY = landmarksXyz[1], maxY = landmarksXyz[1];
+    for (int i = 1; i < count; ++i) {
+        minX = std::min(minX, landmarksXyz[i * 3]);
+        maxX = std::max(maxX, landmarksXyz[i * 3]);
+        minY = std::min(minY, landmarksXyz[i * 3 + 1]);
+        maxY = std::max(maxY, landmarksXyz[i * 3 + 1]);
+    }
+    r.cx = (minX + maxX) / 2.f;
+    r.cy = (minY + maxY) / 2.f;
+    // eye outer corners: 33 (right), 263 (left) — MediaPipe tracking mode
+    const float dx = landmarksXyz[263 * 3] - landmarksXyz[33 * 3];
+    const float dy = landmarksXyz[263 * 3 + 1] - landmarksXyz[33 * 3 + 1];
+    r.angle = normalizeAngle(-std::atan2(-dy, dx));
+    const float side = std::max(maxX - minX, maxY - minY) * 1.5f;
+    r.w = r.h = side;
+    (void)imgW;
+    (void)imgH;
+    return r;
+}
+
+RotatedRect rectFromPoseDetection(const Detection& det, int imgW, int imgH)
+{
+    RotatedRect r;
+    r.cx = det.keypoints[0][0] * imgW;
+    r.cy = det.keypoints[0][1] * imgH;
+    const float dx = det.keypoints[1][0] * imgW - r.cx;
+    const float dy = det.keypoints[1][1] * imgH - r.cy;
+    const float radius = std::sqrt(dx * dx + dy * dy);
+    r.angle = normalizeAngle(static_cast<float>(M_PI) / 2.f - std::atan2(-dy, dx));
+    r.w = r.h = 2.f * radius * 1.25f;
+    return r;
+}
+
+void cropRotatedRectToTensor(const QImage& rgb888, const RotatedRect& rect,
+                             int size, float lo, float hi, float* out)
+{
+    const float ca = std::cos(rect.angle);
+    const float sa = std::sin(rect.angle);
+    const float sx = rect.w / size;
+    const float sy = rect.h / size;
+    // p_img = centre + R(angle) . ((u/size - 0.5) * w, (v/size - 0.5) * h)
+    const float originX = rect.cx + ca * (-rect.w / 2.f) - sa * (-rect.h / 2.f);
+    const float originY = rect.cy + sa * (-rect.w / 2.f) + ca * (-rect.h / 2.f);
+    resampleToTensor(rgb888, size, lo, hi, originX, originY, ca * sx, sa * sx,
+                     -sa * sy, ca * sy, out);
+}
+
+void projectLandmarks(float* pts, int count, int stride, const RotatedRect& rect)
+{
+    const float ca = std::cos(rect.angle);
+    const float sa = std::sin(rect.angle);
+    for (int i = 0; i < count; ++i) {
+        float* p = pts + i * stride;
+        const float x = p[0] - 0.5f;
+        const float y = p[1] - 0.5f;
+        p[0] = rect.cx + x * rect.w * ca - y * rect.h * sa;
+        p[1] = rect.cy + x * rect.w * sa + y * rect.h * ca;
+        if (stride > 2)
+            p[2] *= rect.w;
+    }
+}
+
+}  // namespace FaceCapGeom
diff --git a/src/Mocap/FaceCapGeom.h b/src/Mocap/FaceCapGeom.h
new file mode 100644
index 000000000..bdd5481df
--- /dev/null
+++ b/src/Mocap/FaceCapGeom.h
@@ -0,0 +1,103 @@
+#ifndef FACECAPGEOM_H
+#define FACECAPGEOM_H
+
+// Image-space geometry for the mocap predictors (epic #869, Slice C #872):
+// letterbox transform + inverse, SSD anchor generation + detection decode +
+// weighted NMS, detection->ROI rects, rotated-rect crop sampling and landmark
+// re-projection. Every function mirrors the MediaPipe calculator semantics
+// proven in scripts/export-facecap-onnx.py — see docs/MOCAP_SPIKE.md for the
+// contract (incl. the "plain bilinear, never antialiased" requirement).
+// QtGui-only (QImage); no Ogre/ONNX; headless-tested.
+
+#include <QImage>
+
+#include <array>
+#include <vector>
+
+namespace FaceCapGeom {
+
+// ---- letterbox --------------------------------------------------------------
+
+struct Letterbox {
+    float padX = 0.f;   // normalized padding left of the image content
+    float padY = 0.f;   // normalized padding above the image content
+    float fracX = 1.f;  // fraction of the square the content occupies in x
+    float fracY = 1.f;
+};
+
+// Keep-aspect centre letterbox of an RGB888 image into a size x size float
+// tensor, NHWC interleaved RGB, plain bilinear, zero border. Values are
+// normalized to [lo, hi] ((v/255) * (hi-lo) + lo). out must hold
+// size*size*3 floats.
+Letterbox letterboxToTensor(const QImage& rgb888, int size, float lo, float hi,
+                            float* out);
+
+// Map a point from letterboxed-square normalized coords back to original
+// normalized image coords.
+inline void unletterbox(const Letterbox& lb, float& x, float& y)
+{
+    x = (x - lb.padX) / lb.fracX;
+    y = (y - lb.padY) / lb.fracY;
+}
+
+// ---- SSD detection decode ---------------------------------------------------
+
+struct Detection {
+    float score = 0.f;
+    // box in normalized coords of the DECODE frame (the letterboxed square
+    // until unletterboxed): x, y = top-left; w, h.
+    std::array<float, 4> box{0.f, 0.f, 0.f, 0.f};
+    std::vector<std::array<float, 2>> keypoints;
+};
+
+// MediaPipe SsdAnchorsCalculator with aspect_ratios=[1.0], fixed anchor size,
+// min/max scale 0.1484375/0.75, offset 0.5, interpolated aspect 1.0.
+// Face detector: inputSize 128, strides {8,16,16,16} -> 896 anchors.
+// Pose detector: inputSize 224, strides {8,16,32,32,32} -> 2254 anchors.
+std::vector<std::array<float, 2>> genSsdAnchors(int inputSize,
+                                                const std::vector<int>& strides);
+
+// TensorsToDetections + weighted NMS. rawBoxes is anchorCount x boxDim
+// (boxDim = 4 + 2*numKeypoints), rawScores anchorCount x 1 (logits).
+std::vector<Detection> decodeDetections(
+    const float* rawBoxes, const float* rawScores,
+    const std::vector<std::array<float, 2>>& anchors, int inputSize,
+    int numKeypoints, float minScore = 0.5f, float iouThreshold = 0.3f);
+
+// ---- ROI rects --------------------------------------------------------------
+
+struct RotatedRect {
+    float cx = 0.f, cy = 0.f;  // centre, px
+    float w = 0.f, h = 0.f;    // px
+    float angle = 0.f;         // MediaPipe rotation, rad: R = [[c,-s],[s,c]] y-down
+};
+
+// Face: rotation from detector keypoint 0 (right eye) -> 1 (left eye), target
+// angle 0; box made square-long then scaled 1.5x. Detection coords normalized
+// to the ORIGINAL image (unletterbox first).
+RotatedRect rectFromFaceDetection(const Detection& det, int imgW, int imgH);
+
+// Tracking mode: next-frame ROI from the previous frame's 478 landmarks (px):
+// bounding box -> square-long * 1.5, rotation from eye outer corners 33->263.
+RotatedRect rectFromFaceLandmarks(const float* landmarksXyz, int count,
+                                  int imgW, int imgH);
+
+// Pose: centre keypoint 0 (mid-hip), radius |kp1-kp0|, box 2*radius square,
+// target angle 90 deg, scaled 1.25x.
+RotatedRect rectFromPoseDetection(const Detection& det, int imgW, int imgH);
+
+// ---- crop + projection ------------------------------------------------------
+
+// Sample the rotated rect into a size x size float tensor (NHWC RGB, range
+// [lo, hi], plain bilinear, zero border):
+//   p_img = centre + R(angle) . ((u/size - 0.5) * w, (v/size - 0.5) * h)
+void cropRotatedRectToTensor(const QImage& rgb888, const RotatedRect& rect,
+                             int size, float lo, float hi, float* out);
+
+// LandmarkProjection: landmark (x,y[,z]) normalized to the crop -> image px
+// (z scaled by rect.w). pts is count x stride floats, mutated in place.
+void projectLandmarks(float* pts, int count, int stride, const RotatedRect& rect);
+
+}  // namespace FaceCapGeom
+
+#endif  // FACECAPGEOM_H
diff --git a/src/Mocap/FaceCapGeom_test.cpp b/src/Mocap/FaceCapGeom_test.cpp
new file mode 100644
index 000000000..39366bd14
--- /dev/null
+++ b/src/Mocap/FaceCapGeom_test.cpp
@@ -0,0 +1,194 @@
+#ifdef ENABLE_MOCAP
+
+#include <gtest/gtest.h>
+
+#include <QImage>
+
+#include <cmath>
+#include <vector>
+
+#include "Mocap/FaceCapGeom.h"
+
+using namespace FaceCapGeom;
+
+TEST(FaceCapGeom, AnchorCountsMatchTheModels)
+{
+    EXPECT_EQ(genSsdAnchors(128, {8, 16, 16, 16}).size(), 896u);   // BlazeFace
+    EXPECT_EQ(genSsdAnchors(224, {8, 16, 32, 32, 32}).size(), 2254u);  // BlazePose
+}
+
+TEST(FaceCapGeom, LetterboxPadsTheShortSideAndUnmapsBack)
+{
+    QImage img(200, 100, QImage::Format_RGB888);
+    img.fill(Qt::white);
+    std::vector<float> tensor(64 * 64 * 3);
+    const Letterbox lb = letterboxToTensor(img, 64, 0.f, 1.f, tensor.data());
+
+    EXPECT_NEAR(lb.padX, 0.f, 1e-5);
+    EXPECT_NEAR(lb.padY, 0.25f, 1e-5);  // 100/200 -> half height, centred
+    EXPECT_NEAR(lb.fracX, 1.f, 1e-5);
+    EXPECT_NEAR(lb.fracY, 0.5f, 1e-5);
+
+    // the letterbox bands are zero, the content is white
+    auto at = [&](int x, int y) { return tensor[(y * 64 + x) * 3]; };
+    EXPECT_FLOAT_EQ(at(32, 2), 0.f);    // top band
+    EXPECT_FLOAT_EQ(at(32, 61), 0.f);   // bottom band
+    EXPECT_NEAR(at(32, 32), 1.f, 0.02f);  // centre content
+
+    // centre of the letterboxed square unmaps to the image centre
+    float x = 0.5f, y = 0.5f;
+    unletterbox(lb, x, y);
+    EXPECT_NEAR(x, 0.5f, 1e-5);
+    EXPECT_NEAR(y, 0.5f, 1e-5);
+    // top of the content band unmaps to y = 0
+    x = 0.5f;
+    y = 0.25f;
+    unletterbox(lb, x, y);
+    EXPECT_NEAR(y, 0.f, 1e-5);
+}
+
+TEST(FaceCapGeom, LetterboxNormalizationRange)
+{
+    QImage img(10, 10, QImage::Format_RGB888);
+    img.fill(Qt::white);
+    std::vector<float> tensor(16 * 16 * 3);
+    letterboxToTensor(img, 16, -1.f, 1.f, tensor.data());
+    float mx = -2.f;
+    for (float v : tensor)
+        mx = std::max(mx, v);
+    EXPECT_NEAR(mx, 1.f, 0.02f);  // white -> +1 in [-1,1]
+}
+
+TEST(FaceCapGeom, DecodeDetectionsFindsTheSyntheticBox)
+{
+    const auto anchors = genSsdAnchors(128, {8, 16, 16, 16});
+    std::vector<float> boxes(anchors.size() * 16, 0.f);
+    std::vector<float> scores(anchors.size(), -10.f);  // sigmoid ~ 0
+
+    // plant one detection on anchor 100: centred on the anchor, 32px box,
+    // keypoints 4px right of centre
+    const size_t i = 100;
+    scores[i] = 10.f;  // sigmoid ~ 1
+    boxes[i * 16 + 2] = 32.f;
+    boxes[i * 16 + 3] = 32.f;
+    for (int k = 0; k < 6; ++k)
+        boxes[i * 16 + 4 + 2 * k] = 4.f;
+
+    const auto dets =
+        decodeDetections(boxes.data(), scores.data(), anchors, 128, 6);
+    ASSERT_EQ(dets.size(), 1u);
+    const auto& d = dets.front();
+    EXPECT_NEAR(d.score, 1.f, 1e-3);
+    EXPECT_NEAR(d.box[0] + d.box[2] / 2, anchors[i][0], 1e-5);  // centre = anchor
+    EXPECT_NEAR(d.box[2], 0.25f, 1e-5);                          // 32/128
+    ASSERT_EQ(d.keypoints.size(), 6u);
+    EXPECT_NEAR(d.keypoints[0][0], anchors[i][0] + 4.f / 128.f, 1e-5);
+}
+
+TEST(FaceCapGeom, WeightedNmsMergesOverlappingCluster)
+{
+    const auto anchors = genSsdAnchors(128, {8, 16, 16, 16});
+    std::vector<float> boxes(anchors.size() * 16, 0.f);
+    std::vector<float> scores(anchors.size(), -10.f);
+    // two strongly overlapping detections on nearby anchors -> ONE merged out
+    for (size_t i : {200u, 201u}) {
+        scores[i] = 5.f;
+        boxes[i * 16 + 2] = 64.f;
+        boxes[i * 16 + 3] = 64.f;
+    }
+    const auto dets =
+        decodeDetections(boxes.data(), scores.data(), anchors, 128, 6);
+    EXPECT_EQ(dets.size(), 1u);
+}
+
+TEST(FaceCapGeom, FaceRectIsSquareLongAndScaled)
+{
+    Detection det;
+    det.score = 1.f;
+    det.box = {0.4f, 0.4f, 0.2f, 0.1f};  // in a 100x100 image: 20 x 10 box
+    det.keypoints = {{0.45f, 0.45f}, {0.55f, 0.45f}};  // level eyes
+    const RotatedRect r = rectFromFaceDetection(det, 100, 100);
+    EXPECT_NEAR(r.cx, 50.f, 1e-3);
+    EXPECT_NEAR(r.cy, 45.f, 1e-3);
+    EXPECT_NEAR(r.w, 30.f, 1e-3);  // max(20,10) * 1.5
+    EXPECT_NEAR(r.h, 30.f, 1e-3);
+    EXPECT_NEAR(r.angle, 0.f, 1e-5);  // level eyes -> no rotation
+}
+
+TEST(FaceCapGeom, FaceRectRotationFollowsTheEyeLine)
+{
+    Detection det;
+    det.score = 1.f;
+    det.box = {0.4f, 0.4f, 0.2f, 0.2f};
+    // left eye 45 degrees BELOW the right eye in image coords (y down)
+    det.keypoints = {{0.45f, 0.45f}, {0.55f, 0.55f}};
+    const RotatedRect r = rectFromFaceDetection(det, 100, 100);
+    EXPECT_NEAR(r.angle, static_cast<float>(M_PI) / 4.f, 1e-4);
+}
+
+TEST(FaceCapGeom, CropIdentityRoundTrip)
+{
+    // a gradient image cropped with an axis-aligned rect the size of the
+    // image reproduces the image
+    QImage img(64, 64, QImage::Format_RGB888);
+    for (int y = 0; y < 64; ++y)
+        for (int x = 0; x < 64; ++x)
+            img.setPixel(x, y, qRgb(x * 4, y * 4, 0));
+    RotatedRect rect;
+    rect.cx = 32.f;
+    rect.cy = 32.f;
+    rect.w = 64.f;
+    rect.h = 64.f;
+    rect.angle = 0.f;
+    std::vector<float> tensor(64 * 64 * 3);
+    cropRotatedRectToTensor(img, rect, 64, 0.f, 1.f, tensor.data());
+    for (int i : {5, 20, 40, 60}) {
+        EXPECT_NEAR(tensor[(i * 64 + i) * 3 + 0], i * 4 / 255.f, 0.03f);
+        EXPECT_NEAR(tensor[(i * 64 + i) * 3 + 1], i * 4 / 255.f, 0.03f);
+    }
+}
+
+TEST(FaceCapGeom, ProjectLandmarksInvertsTheCropMapping)
+{
+    RotatedRect rect;
+    rect.cx = 100.f;
+    rect.cy = 80.f;
+    rect.w = 50.f;
+    rect.h = 50.f;
+    rect.angle = 0.5f;
+
+    // crop-space corners + centre with z
+    std::vector<float> pts = {
+        0.5f, 0.5f, 2.f,   // centre
+        0.f, 0.f, 0.f,     // top-left
+        1.f, 1.f, 0.f,     // bottom-right
+    };
+    projectLandmarks(pts.data(), 3, 3, rect);
+    EXPECT_NEAR(pts[0], 100.f, 1e-4);  // centre -> rect centre
+    EXPECT_NEAR(pts[1], 80.f, 1e-4);
+    EXPECT_NEAR(pts[2], 100.f, 1e-4);  // z scaled by rect.w
+    // the two corners are diagonal through the centre: their midpoint is it
+    EXPECT_NEAR((pts[3] + pts[6]) / 2.f, 100.f, 1e-3);
+    EXPECT_NEAR((pts[4] + pts[7]) / 2.f, 80.f, 1e-3);
+    // and the diagonal length is |(w, h)| rotated = sqrt(50^2 + 50^2)
+    const float dx = pts[6] - pts[3];
+    const float dy = pts[7] - pts[4];
+    EXPECT_NEAR(std::sqrt(dx * dx + dy * dy), std::sqrt(2.f) * 50.f, 1e-2);
+}
+
+TEST(FaceCapGeom, PoseRectFromAlignmentKeypoints)
+{
+    Detection det;
+    det.score = 1.f;
+    det.box = {0.f, 0.f, 1.f, 1.f};
+    // mid-hip at centre, alignment point straight ABOVE it (y up in image =
+    // smaller y): target angle 90 deg means this is rotation 0
+    det.keypoints = {{0.5f, 0.5f}, {0.5f, 0.3f}};
+    const RotatedRect r = rectFromPoseDetection(det, 100, 100);
+    EXPECT_NEAR(r.cx, 50.f, 1e-3);
+    EXPECT_NEAR(r.cy, 50.f, 1e-3);
+    EXPECT_NEAR(r.w, 2.f * 20.f * 1.25f, 1e-3);  // 2 * radius * 1.25
+    EXPECT_NEAR(r.angle, 0.f, 1e-4);
+}
+
+#endif  // ENABLE_MOCAP
diff --git a/src/Mocap/FaceCapMapper.cpp b/src/Mocap/FaceCapMapper.cpp
new file mode 100644
index 000000000..fa33f1e44
--- /dev/null
+++ b/src/Mocap/FaceCapMapper.cpp
@@ -0,0 +1,164 @@
+#include "FaceCapMapper.h"
+
+#include "FaceCapCanonicalData.h"
+
+#include <QFile>
+#include <QHash>
+#include <QJsonArray>
+#include <QJsonDocument>
+#include <QJsonObject>
+
+namespace FaceCapMapper {
+
+namespace {
+
+const QHash<QString, QString>& aliasTable()
+{
+    // normalized third-party name -> normalized canonical name. Only entries
+    // the side-expansion + normalization pass can NOT already resolve.
+    static const QHash<QString, QString> table = {
+        // CC/iClone
+        {QStringLiteral("mouthopen"), QStringLiteral("jawopen")},
+        {QStringLiteral("browraiseinnerleft"), QStringLiteral("browinnerup")},
+        {QStringLiteral("browraiseinnerright"), QStringLiteral("browinnerup")},
+        {QStringLiteral("browraiseouterleft"), QStringLiteral("browouterupleft")},
+        {QStringLiteral("browraiseouterright"), QStringLiteral("browouterupright")},
+        {QStringLiteral("browdropleft"), QStringLiteral("browdownleft")},
+        {QStringLiteral("browdropright"), QStringLiteral("browdownright")},
+        {QStringLiteral("eyeswideleft"), QStringLiteral("eyewideleft")},
+        {QStringLiteral("eyeswideright"), QStringLiteral("eyewideright")},
+        // common shorthand
+        {QStringLiteral("blinkleft"), QStringLiteral("eyeblinkleft")},
+        {QStringLiteral("blinkright"), QStringLiteral("eyeblinkright")},
+        {QStringLiteral("smileleft"), QStringLiteral("mouthsmileleft")},
+        {QStringLiteral("smileright"), QStringLiteral("mouthsmileright")},
+    };
+    return table;
+}
+
+// "Mouth_Smile_L" -> "mouth smile left" token stream -> normalized join.
+QString expandSideTokens(const QString& name)
+{
+    // split on separator characters AND camelCase boundaries
+    QStringList tokens;
+    QString current;
+    for (const QChar c : name) {
+        if (c == QLatin1Char('_') || c == QLatin1Char('-')
+            || c == QLatin1Char('.') || c.isSpace()) {
+            if (!current.isEmpty()) tokens << current;
+            current.clear();
+        } else if (c.isUpper() && !current.isEmpty()
+                   && current.back().isLower()) {
+            tokens << current;
+            current = c;
+        } else {
+            current += c;
+        }
+    }
+    if (!current.isEmpty()) tokens << current;
+    if (!tokens.isEmpty()) {
+        const QString last = tokens.last().toLower();
+        if (last == QLatin1String("l"))
+            tokens.last() = QStringLiteral("left");
+        else if (last == QLatin1String("r"))
+            tokens.last() = QStringLiteral("right");
+    }
+    return tokens.join(QString()).toLower();
+}
+
+}  // namespace
+
+QString normalizedName(const QString& name)
+{
+    return expandSideTokens(name);
+}
+
+Mapping build(const QStringList& meshTargetNames, const QString& overrideJsonPath)
+{
+    Mapping mapping;
+
+    QHash<QString, QString> overrideMap;  // canonical name -> mesh name
+    QSet<QString> ignore;
+    if (!overrideJsonPath.isEmpty()) {
+        QFile f(overrideJsonPath);
+        if (!f.open(QIODevice::ReadOnly)) {
+            mapping.error = QStringLiteral("cannot open mapping override: %1")
+                                .arg(overrideJsonPath);
+        } else {
+            QJsonParseError parseError;
+            const QJsonDocument doc = QJsonDocument::fromJson(f.readAll(), &parseError);
+            if (doc.isNull()) {
+                mapping.error = QStringLiteral("mapping override parse error: %1")
+                                    .arg(parseError.errorString());
+            } else {
+                const QJsonObject root = doc.object();
+                const QJsonObject map = root.value(QLatin1String("map")).toObject();
+                for (auto it = map.begin(); it != map.end(); ++it)
+                    overrideMap.insert(it.key(), it.value().toString());
+                const QJsonArray ign = root.value(QLatin1String("ignore")).toArray();
+                for (const auto& v : ign)
+                    ignore.insert(v.toString());
+            }
+        }
+    }
+
+    // normalized mesh name -> exact mesh name (first wins on collision)
+    QHash<QString, QString> meshByNorm;
+    for (const QString& mesh : meshTargetNames) {
+        const QString norm = normalizedName(mesh);
+        if (!meshByNorm.contains(norm))
+            meshByNorm.insert(norm, mesh);
+    }
+
+    QSet<QString> usedMeshTargets;
+    for (int i = 0; i < FaceCap::kBlendshapeCount; ++i) {
+        const QString canonical = QString::fromLatin1(FaceCap::kBlendshapeNames[i]);
+        if (canonical == QLatin1String("_neutral"))
+            continue;  // rest weight; no mesh equivalent by design
+        if (ignore.contains(canonical)) {
+            mapping.ignored << canonical;
+            continue;
+        }
+        QString meshName;
+        if (overrideMap.contains(canonical)) {
+            const QString target = overrideMap.value(canonical);
+            if (meshTargetNames.contains(target)) {
+                meshName = target;
+            } else {
+                mapping.error = mapping.error.isEmpty()
+                    ? QStringLiteral("override target '%1' (for %2) not on mesh")
+                          .arg(target, canonical)
+                    : mapping.error;
+            }
+        }
+        if (meshName.isEmpty()) {
+            const QString norm = normalizedName(canonical);
+            meshName = meshByNorm.value(norm);
+        }
+        if (meshName.isEmpty()) {
+            // alias table: some mesh naming convention that normalizes to a
+            // different string but means this canonical channel
+            const QString canonNorm = normalizedName(canonical);
+            for (auto it = meshByNorm.begin(); it != meshByNorm.end(); ++it) {
+                if (aliasTable().value(it.key()) == canonNorm) {
+                    meshName = it.value();
+                    break;
+                }
+            }
+        }
+        if (meshName.isEmpty()) {
+            mapping.unmatchedCanonical << canonical;
+        } else {
+            mapping.channels.append({i, meshName});
+            usedMeshTargets.insert(meshName);
+        }
+    }
+
+    for (const QString& mesh : meshTargetNames)
+        if (!usedMeshTargets.contains(mesh))
+            mapping.unmatchedMesh << mesh;
+
+    return mapping;
+}
+
+}  // namespace FaceCapMapper
diff --git a/src/Mocap/FaceCapMapper.h b/src/Mocap/FaceCapMapper.h
new file mode 100644
index 000000000..9bd8d93b5
--- /dev/null
+++ b/src/Mocap/FaceCapMapper.h
@@ -0,0 +1,53 @@
+#ifndef FACECAPMAPPER_H
+#define FACECAPMAPPER_H
+
+// Maps the 52 canonical MediaPipe/ARKit blendshape names onto the target
+// mesh's actual morph-target names (epic #869, Slice C #872). Pure data —
+// QtCore only — headless-tested.
+//
+// Matching, in priority order per canonical channel:
+//   1. explicit override from the JSON sidecar ("map"),
+//   2. normalized name equality: lowercase, separators ('_', '-', '.', ' ')
+//      stripped, with trailing side tokens expanded first so "Mouth_Smile_L",
+//      "mouthSmile.R" and "MouthSmileLeft" all normalize the same way,
+//   3. alias table for common third-party conventions.
+//
+// Override JSON sidecar format:
+//   {
+//     "map":    { "jawOpen": "MyJawTarget", ... },   // canonical -> mesh name
+//     "ignore": [ "tongueOut", ... ]                 // canonical names to skip
+//   }
+//
+// Unmatched channels are REPORTED (unmatchedCanonical / unmatchedMesh),
+// never silently dropped. "_neutral" (index 0) is a rest-weight channel with
+// no mesh equivalent — it is excluded from mapping and reporting.
+
+#include <QString>
+#include <QStringList>
+
+namespace FaceCapMapper {
+
+struct Channel {
+    int canonicalIndex = -1;   // into FaceCap::kBlendshapeNames
+    QString meshTargetName;    // exact morph-target name on the mesh
+};
+
+struct Mapping {
+    QList<Channel> channels;
+    QStringList unmatchedCanonical;  // canonical names with no mesh target
+    QStringList unmatchedMesh;       // mesh targets no channel drives
+    QStringList ignored;             // canonical names ignored via override
+    QString error;                   // override-file problem (mapping still built)
+
+    bool isEmpty() const { return channels.isEmpty(); }
+};
+
+Mapping build(const QStringList& meshTargetNames,
+              const QString& overrideJsonPath = {});
+
+// exposed for tests: "Mouth_Smile_L" -> "mouthsmileleft"
+QString normalizedName(const QString& name);
+
+}  // namespace FaceCapMapper
+
+#endif  // FACECAPMAPPER_H
diff --git a/src/Mocap/FaceCapMapper_test.cpp b/src/Mocap/FaceCapMapper_test.cpp
new file mode 100644
index 000000000..2f69590e0
--- /dev/null
+++ b/src/Mocap/FaceCapMapper_test.cpp
@@ -0,0 +1,125 @@
+#ifdef ENABLE_MOCAP
+
+#include <gtest/gtest.h>
+
+#include <QJsonArray>
+#include <QJsonDocument>
+#include <QJsonObject>
+#include <QTemporaryDir>
+#include <QFile>
+
+#include "Mocap/FaceCapCanonicalData.h"
+#include "Mocap/FaceCapMapper.h"
+
+namespace {
+
+QString findMesh(const FaceCapMapper::Mapping& m, const QString& canonical)
+{
+    for (const auto& ch : m.channels) {
+        if (QString::fromLatin1(FaceCap::kBlendshapeNames[ch.canonicalIndex])
+            == canonical)
+            return ch.meshTargetName;
+    }
+    return {};
+}
+
+}  // namespace
+
+TEST(FaceCapMapper, ExactArkitNamesAllMatch)
+{
+    QStringList mesh;
+    for (int i = 1; i < FaceCap::kBlendshapeCount; ++i)  // skip _neutral
+        mesh << QString::fromLatin1(FaceCap::kBlendshapeNames[i]);
+    const auto m = FaceCapMapper::build(mesh);
+    EXPECT_EQ(m.channels.size(), FaceCap::kBlendshapeCount - 1);
+    EXPECT_TRUE(m.unmatchedCanonical.isEmpty())
+        << m.unmatchedCanonical.join(", ").toStdString();
+    EXPECT_TRUE(m.unmatchedMesh.isEmpty());
+}
+
+TEST(FaceCapMapper, NormalizedMatchingHandlesSeparatorsAndSides)
+{
+    const QStringList mesh{
+        QStringLiteral("Jaw_Open"),          // CC style
+        QStringLiteral("mouth_smile_l"),     // snake + side letter
+        QStringLiteral("MouthSmile.R"),      // dot side
+        QStringLiteral("eye-blink-left"),    // kebab
+        QStringLiteral("EyeBlink_R"),
+    };
+    const auto m = FaceCapMapper::build(mesh);
+    EXPECT_EQ(findMesh(m, QStringLiteral("jawOpen")), QStringLiteral("Jaw_Open"));
+    EXPECT_EQ(findMesh(m, QStringLiteral("mouthSmileLeft")),
+              QStringLiteral("mouth_smile_l"));
+    EXPECT_EQ(findMesh(m, QStringLiteral("mouthSmileRight")),
+              QStringLiteral("MouthSmile.R"));
+    EXPECT_EQ(findMesh(m, QStringLiteral("eyeBlinkLeft")),
+              QStringLiteral("eye-blink-left"));
+    EXPECT_EQ(findMesh(m, QStringLiteral("eyeBlinkRight")),
+              QStringLiteral("EyeBlink_R"));
+    EXPECT_TRUE(m.unmatchedMesh.isEmpty());
+}
+
+TEST(FaceCapMapper, AliasTableResolvesCommonConventions)
+{
+    const QStringList mesh{QStringLiteral("Blink_L"), QStringLiteral("MouthOpen")};
+    const auto m = FaceCapMapper::build(mesh);
+    EXPECT_EQ(findMesh(m, QStringLiteral("eyeBlinkLeft")), QStringLiteral("Blink_L"));
+    EXPECT_EQ(findMesh(m, QStringLiteral("jawOpen")), QStringLiteral("MouthOpen"));
+}
+
+TEST(FaceCapMapper, UnmatchedAreReportedNeverDropped)
+{
+    const QStringList mesh{QStringLiteral("jawOpen"), QStringLiteral("SomeCustomTarget")};
+    const auto m = FaceCapMapper::build(mesh);
+    EXPECT_EQ(m.channels.size(), 1);
+    // 50 canonical channels unmatched (52 - _neutral - jawOpen)
+    EXPECT_EQ(m.unmatchedCanonical.size(), FaceCap::kBlendshapeCount - 2);
+    ASSERT_EQ(m.unmatchedMesh.size(), 1);
+    EXPECT_EQ(m.unmatchedMesh.first(), QStringLiteral("SomeCustomTarget"));
+    // _neutral is by-design absent from both lists
+    EXPECT_FALSE(m.unmatchedCanonical.contains(QStringLiteral("_neutral")));
+}
+
+TEST(FaceCapMapper, OverrideMapAndIgnore)
+{
+    QTemporaryDir tmp;
+    ASSERT_TRUE(tmp.isValid());
+    const QString overridePath = tmp.path() + QStringLiteral("/map.json");
+    {
+        QJsonObject map;
+        map.insert(QStringLiteral("jawOpen"), QStringLiteral("WeirdJaw"));
+        QJsonObject root;
+        root.insert(QStringLiteral("map"), map);
+        root.insert(QStringLiteral("ignore"),
+                    QJsonArray{QStringLiteral("cheekPuff")});
+        QFile f(overridePath);
+        ASSERT_TRUE(f.open(QIODevice::WriteOnly));
+        f.write(QJsonDocument(root).toJson());
+    }
+    const QStringList mesh{QStringLiteral("WeirdJaw"), QStringLiteral("cheekPuff")};
+    const auto m = FaceCapMapper::build(mesh, overridePath);
+    EXPECT_EQ(findMesh(m, QStringLiteral("jawOpen")), QStringLiteral("WeirdJaw"));
+    // ignored channel is not mapped even though the mesh name would match
+    EXPECT_TRUE(findMesh(m, QStringLiteral("cheekPuff")).isEmpty());
+    EXPECT_TRUE(m.ignored.contains(QStringLiteral("cheekPuff")));
+    EXPECT_FALSE(m.unmatchedCanonical.contains(QStringLiteral("cheekPuff")));
+    EXPECT_TRUE(m.error.isEmpty()) << m.error.toStdString();
+}
+
+TEST(FaceCapMapper, BadOverridePathReportsErrorButStillMaps)
+{
+    const QStringList mesh{QStringLiteral("jawOpen")};
+    const auto m =
+        FaceCapMapper::build(mesh, QStringLiteral("/nonexistent/map.json"));
+    EXPECT_FALSE(m.error.isEmpty());
+    EXPECT_EQ(m.channels.size(), 1);
+}
+
+TEST(FaceCapMapper, EmptyMeshTargetList)
+{
+    const auto m = FaceCapMapper::build({});
+    EXPECT_TRUE(m.channels.isEmpty());
+    EXPECT_EQ(m.unmatchedCanonical.size(), FaceCap::kBlendshapeCount - 1);
+}
+
+#endif  // ENABLE_MOCAP
diff --git a/src/Mocap/FaceCapPose.cpp b/src/Mocap/FaceCapPose.cpp
new file mode 100644
index 000000000..951423eb3
--- /dev/null
+++ b/src/Mocap/FaceCapPose.cpp
@@ -0,0 +1,186 @@
+#include "FaceCapPose.h"
+
+#include "FaceCapCanonicalData.h"
+
+#include <cmath>
+
+namespace FaceCapPose {
+
+namespace {
+
+// Largest-eigenvalue eigenvector of a symmetric 4x4 matrix via cyclic Jacobi.
+// Deterministic, ~1e-12 accurate after a handful of sweeps.
+std::array<double, 4> maxEigenvector4(double m[4][4])
+{
+    double v[4][4] = {{1, 0, 0, 0}, {0, 1, 0, 0}, {0, 0, 1, 0}, {0, 0, 0, 1}};
+    for (int sweep = 0; sweep < 32; ++sweep) {
+        double off = 0.0;
+        for (int p = 0; p < 4; ++p)
+            for (int q = p + 1; q < 4; ++q)
+                off += m[p][q] * m[p][q];
+        if (off < 1e-24)
+            break;
+        for (int p = 0; p < 4; ++p) {
+            for (int q = p + 1; q < 4; ++q) {
+                if (std::abs(m[p][q]) < 1e-30)
+                    continue;
+                const double theta = (m[q][q] - m[p][p]) / (2.0 * m[p][q]);
+                const double t = (theta >= 0 ? 1.0 : -1.0)
+                                 / (std::abs(theta) + std::sqrt(theta * theta + 1.0));
+                const double c = 1.0 / std::sqrt(t * t + 1.0);
+                const double s = t * c;
+                for (int k = 0; k < 4; ++k) {
+                    const double mkp = m[k][p], mkq = m[k][q];
+                    m[k][p] = c * mkp - s * mkq;
+                    m[k][q] = s * mkp + c * mkq;
+                }
+                for (int k = 0; k < 4; ++k) {
+                    const double mpk = m[p][k], mqk = m[q][k];
+                    m[p][k] = c * mpk - s * mqk;
+                    m[q][k] = s * mpk + c * mqk;
+                }
+                for (int k = 0; k < 4; ++k) {
+                    const double vkp = v[k][p], vkq = v[k][q];
+                    v[k][p] = c * vkp - s * vkq;
+                    v[k][q] = s * vkp + c * vkq;
+                }
+            }
+        }
+    }
+    int best = 0;
+    for (int i = 1; i < 4; ++i)
+        if (m[i][i] > m[best][best])
+            best = i;
+    return {v[0][best], v[1][best], v[2][best], v[3][best]};
+}
+
+void rotate(const std::array<float, 4>& q, const double in[3], double out[3])
+{
+    // (x,y,z,w) quaternion rotation of a vector
+    const double x = q[0], y = q[1], z = q[2], w = q[3];
+    const double tx = 2.0 * (y * in[2] - z * in[1]);
+    const double ty = 2.0 * (z * in[0] - x * in[2]);
+    const double tz = 2.0 * (x * in[1] - y * in[0]);
+    out[0] = in[0] + w * tx + (y * tz - z * ty);
+    out[1] = in[1] + w * ty + (z * tx - x * tz);
+    out[2] = in[2] + w * tz + (x * ty - y * tx);
+}
+
+}  // namespace
+
+Result solve(const float* src, const float* dst, const float* weights, int count)
+{
+    Result r;
+    if (count < 3)
+        return r;
+
+    double wSum = 0.0;
+    double muS[3] = {0, 0, 0}, muD[3] = {0, 0, 0};
+    for (int i = 0; i < count; ++i) {
+        const double w = weights ? weights[i] : 1.0;
+        if (w <= 0.0)
+            continue;
+        wSum += w;
+        for (int k = 0; k < 3; ++k) {
+            muS[k] += w * src[i * 3 + k];
+            muD[k] += w * dst[i * 3 + k];
+        }
+    }
+    if (wSum <= 0.0)
+        return r;
+    for (int k = 0; k < 3; ++k) {
+        muS[k] /= wSum;
+        muD[k] /= wSum;
+    }
+
+    // weighted covariance src x dst (Horn's S = sum s.d^T) + source variance
+    // for the scale. Order matters: S[a][b] = s[a]*d[b] yields the rotation
+    // taking SRC into DST; the transpose yields its inverse.
+    double cov[3][3] = {{0}};
+    double varS = 0.0;
+    for (int i = 0; i < count; ++i) {
+        const double w = weights ? weights[i] : 1.0;
+        if (w <= 0.0)
+            continue;
+        double s[3], d[3];
+        for (int k = 0; k < 3; ++k) {
+            s[k] = src[i * 3 + k] - muS[k];
+            d[k] = dst[i * 3 + k] - muD[k];
+        }
+        for (int a = 0; a < 3; ++a)
+            for (int b = 0; b < 3; ++b)
+                cov[a][b] += w * s[a] * d[b];
+        varS += w * (s[0] * s[0] + s[1] * s[1] + s[2] * s[2]);
+    }
+    if (varS <= 0.0)
+        return r;
+
+    // Horn's method: max eigenvector of the 4x4 built from the covariance
+    const double sxx = cov[0][0], sxy = cov[0][1], sxz = cov[0][2];
+    const double syx = cov[1][0], syy = cov[1][1], syz = cov[1][2];
+    const double szx = cov[2][0], szy = cov[2][1], szz = cov[2][2];
+    double n[4][4] = {
+        {sxx + syy + szz, syz - szy, szx - sxz, sxy - syx},
+        {syz - szy, sxx - syy - szz, sxy + syx, szx + sxz},
+        {szx - sxz, sxy + syx, -sxx + syy - szz, syz + szy},
+        {sxy - syx, szx + sxz, syz + szy, -sxx - syy + szz},
+    };
+    const std::array<double, 4> e = maxEigenvector4(n);  // (w, x, y, z)
+    double norm = std::sqrt(e[0] * e[0] + e[1] * e[1] + e[2] * e[2] + e[3] * e[3]);
+    if (norm <= 0.0)
+        return r;
+    // store as (x,y,z,w), w kept positive for a canonical representation
+    const double sign = e[0] >= 0.0 ? 1.0 : -1.0;
+    r.rotation = {static_cast<float>(sign * e[1] / norm),
+                  static_cast<float>(sign * e[2] / norm),
+                  static_cast<float>(sign * e[3] / norm),
+                  static_cast<float>(sign * e[0] / norm)};
+
+    // scale = sum(w * d . (R s)) / sum(w * |s|^2)
+    double dot = 0.0;
+    for (int i = 0; i < count; ++i) {
+        const double w = weights ? weights[i] : 1.0;
+        if (w <= 0.0)
+            continue;
+        double s[3], rs[3], d[3];
+        for (int k = 0; k < 3; ++k) {
+            s[k] = src[i * 3 + k] - muS[k];
+            d[k] = dst[i * 3 + k] - muD[k];
+        }
+        rotate(r.rotation, s, rs);
+        dot += w * (d[0] * rs[0] + d[1] * rs[1] + d[2] * rs[2]);
+    }
+    r.scale = static_cast<float>(dot / varS);
+
+    // t = muD - scale * R * muS  (scale participates: the fit is a similarity;
+    // the caller treats rotation as the pose and translation as informational)
+    double rMu[3];
+    rotate(r.rotation, muS, rMu);
+    for (int k = 0; k < 3; ++k)
+        r.translation[k] = static_cast<float>(muD[k] - r.scale * rMu[k]);
+    r.ok = true;
+    return r;
+}
+
+Result solveHeadPose(const float* landmarksXyz, int landmarkCount)
+{
+    if (landmarkCount < FaceCap::kCanonicalVertexCount)
+        return {};
+    // gather the weighted Procrustes basis subset in both frames
+    float src[FaceCap::kProcrustesBasisCount * 3];
+    float dst[FaceCap::kProcrustesBasisCount * 3];
+    float wgt[FaceCap::kProcrustesBasisCount];
+    for (int i = 0; i < FaceCap::kProcrustesBasisCount; ++i) {
+        const int id = FaceCap::kProcrustesLandmarkIds[i];
+        for (int k = 0; k < 3; ++k)
+            src[i * 3 + k] = FaceCap::kCanonicalFaceModel[id * 3 + k];
+        // image frame -> pose frame: +X right stays, y and z flip
+        dst[i * 3 + 0] = landmarksXyz[id * 3 + 0];
+        dst[i * 3 + 1] = -landmarksXyz[id * 3 + 1];
+        dst[i * 3 + 2] = -landmarksXyz[id * 3 + 2];
+        wgt[i] = FaceCap::kProcrustesWeights[i];
+    }
+    return solve(src, dst, wgt, FaceCap::kProcrustesBasisCount);
+}
+
+}  // namespace FaceCapPose
diff --git a/src/Mocap/FaceCapPose.h b/src/Mocap/FaceCapPose.h
new file mode 100644
index 000000000..279d1607c
--- /dev/null
+++ b/src/Mocap/FaceCapPose.h
@@ -0,0 +1,46 @@
+#ifndef FACECAPPOSE_H
+#define FACECAPPOSE_H
+
+// Head-pose solve for face capture (epic #869, Slice C #872). Pure data —
+// no Qt/Ogre/ONNX — headless-tested.
+//
+// Weighted rigid fit (Horn's closed-form quaternion method — the weighted
+// Kabsch/Umeyama equivalent, solved with a 4x4 Jacobi eigensolver so no
+// linear-algebra dependency is needed) of the MediaPipe canonical face model
+// onto the detected 3D screen landmarks. Scale is solved and DISCARDED for
+// the pose; translation is returned in the destination units.
+//
+// Convention (documented contract): the destination frame is +X right,
+// +Y up, camera looking down -Z; identity rotation = the face looking
+// straight at the camera. Callers build destination points from screen
+// landmarks as (x_px, -y_px, -z_px) — image y grows downward and the
+// landmark z grows away from the camera, so both flip. This intentionally
+// replaces MediaPipe's perspective geometry pipeline (delta vs its facial
+// transformation matrix measured at 4-9 degrees, systematic; the recorder
+// neutral-calibrates the first confident frame anyway). See docs/MOCAP_SPIKE.md.
+
+#include <array>
+
+namespace FaceCapPose {
+
+struct Result {
+    std::array<float, 4> rotation{0.f, 0.f, 0.f, 1.f};  // (x,y,z,w), src -> dst
+    std::array<float, 3> translation{0.f, 0.f, 0.f};    // dst units
+    float scale = 1.f;                                   // solved, informational
+    bool ok = false;
+};
+
+// General weighted rigid fit: dst ~= scale * R * src + t.
+// src/dst are count x 3 (xyz interleaved); weights length count (>= 0, at
+// least 3 non-zero non-collinear points required).
+Result solve(const float* src, const float* dst, const float* weights, int count);
+
+// Face-capture convenience: fits the embedded canonical face model
+// (FaceCapCanonicalData.h, MediaPipe Procrustes basis weights) onto 478 (or
+// 468) screen landmarks given as xyz triples in PIXELS (image coords, y down,
+// z from the landmark model). Applies the (x, -y, -z) frame flip internally.
+Result solveHeadPose(const float* landmarksXyz, int landmarkCount);
+
+}  // namespace FaceCapPose
+
+#endif  // FACECAPPOSE_H
diff --git a/src/Mocap/FaceCapPose_test.cpp b/src/Mocap/FaceCapPose_test.cpp
new file mode 100644
index 000000000..6d6b7e267
--- /dev/null
+++ b/src/Mocap/FaceCapPose_test.cpp
@@ -0,0 +1,165 @@
+#ifdef ENABLE_MOCAP
+
+#include <gtest/gtest.h>
+
+#include <array>
+#include <cmath>
+#include <vector>
+
+#include "Mocap/FaceCapCanonicalData.h"
+#include "Mocap/FaceCapPose.h"
+
+namespace {
+
+using Quat = std::array<float, 4>;  // (x,y,z,w)
+
+Quat axisAngle(float ax, float ay, float az, float rad)
+{
+    const float n = std::sqrt(ax * ax + ay * ay + az * az);
+    const float s = std::sin(rad / 2) / n;
+    return {ax * s, ay * s, az * s, std::cos(rad / 2)};
+}
+
+void rotate(const Quat& q, const float in[3], float out[3])
+{
+    const float x = q[0], y = q[1], z = q[2], w = q[3];
+    const float tx = 2 * (y * in[2] - z * in[1]);
+    const float ty = 2 * (z * in[0] - x * in[2]);
+    const float tz = 2 * (x * in[1] - y * in[0]);
+    out[0] = in[0] + w * tx + (y * tz - z * ty);
+    out[1] = in[1] + w * ty + (z * tx - x * tz);
+    out[2] = in[2] + w * tz + (x * ty - y * tx);
+}
+
+double quatAngle(const Quat& a, const Quat& b)
+{
+    double dot = 0;
+    for (int i = 0; i < 4; ++i)
+        dot += a[i] * b[i];
+    return 2.0 * std::acos(std::fmin(1.0, std::fabs(dot)));
+}
+
+// asymmetric, non-coplanar point cloud
+std::vector<float> makeCloud()
+{
+    return {0, 0, 0, 1, 0, 0, 0, 2, 0, 0, 0, 3, 1, 1, 0.5f, -2, 0.5f, 1};
+}
+
+}  // namespace
+
+TEST(FaceCapPose, RecoversSyntheticRigidTransform)
+{
+    const std::vector<float> src = makeCloud();
+    const int n = static_cast<int>(src.size() / 3);
+    const Quat q = axisAngle(0.3f, 1.f, 0.2f, 0.7f);
+    const float t[3] = {5.f, -3.f, 2.f};
+
+    std::vector<float> dst(src.size());
+    for (int i = 0; i < n; ++i) {
+        float r[3];
+        rotate(q, &src[i * 3], r);
+        for (int k = 0; k < 3; ++k)
+            dst[i * 3 + k] = r[k] + t[k];
+    }
+    const auto res = FaceCapPose::solve(src.data(), dst.data(), nullptr, n);
+    ASSERT_TRUE(res.ok);
+    EXPECT_LT(quatAngle(res.rotation, q), 1e-3);
+    EXPECT_NEAR(res.scale, 1.f, 1e-4);
+    for (int k = 0; k < 3; ++k)
+        EXPECT_NEAR(res.translation[k], t[k], 1e-3);
+}
+
+TEST(FaceCapPose, RecoversScaleAndDiscardsItFromRotation)
+{
+    const std::vector<float> src = makeCloud();
+    const int n = static_cast<int>(src.size() / 3);
+    const Quat q = axisAngle(0.f, 1.f, 0.f, -0.4f);
+
+    std::vector<float> dst(src.size());
+    for (int i = 0; i < n; ++i) {
+        float r[3];
+        rotate(q, &src[i * 3], r);
+        for (int k = 0; k < 3; ++k)
+            dst[i * 3 + k] = 2.5f * r[k] + 1.f;
+    }
+    const auto res = FaceCapPose::solve(src.data(), dst.data(), nullptr, n);
+    ASSERT_TRUE(res.ok);
+    EXPECT_LT(quatAngle(res.rotation, q), 1e-3);
+    EXPECT_NEAR(res.scale, 2.5f, 1e-3);
+}
+
+TEST(FaceCapPose, WeightsFocusTheFit)
+{
+    const std::vector<float> src = makeCloud();
+    const int n = static_cast<int>(src.size() / 3);
+    const Quat q = axisAngle(0.f, 0.f, 1.f, 0.5f);
+
+    std::vector<float> dst(src.size());
+    for (int i = 0; i < n; ++i) {
+        float r[3];
+        rotate(q, &src[i * 3], r);
+        for (int k = 0; k < 3; ++k)
+            dst[i * 3 + k] = r[k];
+    }
+    // corrupt the last point badly, but give it zero weight
+    dst[(n - 1) * 3 + 0] += 100.f;
+    std::vector<float> w(n, 1.f);
+    w[n - 1] = 0.f;
+    const auto res = FaceCapPose::solve(src.data(), dst.data(), w.data(), n);
+    ASSERT_TRUE(res.ok);
+    EXPECT_LT(quatAngle(res.rotation, q), 1e-3);
+}
+
+TEST(FaceCapPose, DegenerateInputsReturnNotOk)
+{
+    const std::vector<float> src = makeCloud();
+    EXPECT_FALSE(FaceCapPose::solve(src.data(), src.data(), nullptr, 2).ok);
+    // all-zero weights
+    std::vector<float> w(src.size() / 3, 0.f);
+    EXPECT_FALSE(
+        FaceCapPose::solve(src.data(), src.data(), w.data(),
+                           static_cast<int>(src.size() / 3)).ok);
+    // coincident points (zero variance)
+    std::vector<float> same(src.size(), 1.f);
+    EXPECT_FALSE(FaceCapPose::solve(same.data(), same.data(), nullptr,
+                                    static_cast<int>(same.size() / 3)).ok);
+}
+
+TEST(FaceCapPose, HeadPoseIdentityForCanonicalLandmarks)
+{
+    // feed the canonical model itself as "screen landmarks" with the
+    // documented (x, -y, -z) flip already inverted: identity comes back
+    std::vector<float> landmarks(FaceCap::kCanonicalVertexCount * 3);
+    for (int i = 0; i < FaceCap::kCanonicalVertexCount; ++i) {
+        landmarks[i * 3 + 0] = FaceCap::kCanonicalFaceModel[i * 3 + 0];
+        landmarks[i * 3 + 1] = -FaceCap::kCanonicalFaceModel[i * 3 + 1];
+        landmarks[i * 3 + 2] = -FaceCap::kCanonicalFaceModel[i * 3 + 2];
+    }
+    const auto res = FaceCapPose::solveHeadPose(
+        landmarks.data(), FaceCap::kCanonicalVertexCount);
+    ASSERT_TRUE(res.ok);
+    const Quat identity{0.f, 0.f, 0.f, 1.f};
+    EXPECT_LT(quatAngle(res.rotation, identity), 1e-3);
+    EXPECT_NEAR(res.scale, 1.f, 1e-4);
+}
+
+TEST(FaceCapPose, HeadPoseRecoversYaw)
+{
+    // rotate the canonical model 30 degrees about +Y (turn left), project to
+    // the image frame (y,z flip), expect the same rotation back
+    const Quat q = axisAngle(0.f, 1.f, 0.f, static_cast<float>(M_PI) / 6.f);
+    std::vector<float> landmarks(FaceCap::kCanonicalVertexCount * 3);
+    for (int i = 0; i < FaceCap::kCanonicalVertexCount; ++i) {
+        float r[3];
+        rotate(q, &FaceCap::kCanonicalFaceModel[i * 3], r);
+        landmarks[i * 3 + 0] = r[0];
+        landmarks[i * 3 + 1] = -r[1];
+        landmarks[i * 3 + 2] = -r[2];
+    }
+    const auto res = FaceCapPose::solveHeadPose(
+        landmarks.data(), FaceCap::kCanonicalVertexCount);
+    ASSERT_TRUE(res.ok);
+    EXPECT_LT(quatAngle(res.rotation, q), 1e-3);
+}
+
+#endif  // ENABLE_MOCAP
diff --git a/src/Mocap/FaceCapPredictor.cpp b/src/Mocap/FaceCapPredictor.cpp
new file mode 100644
index 000000000..0d93790d9
--- /dev/null
+++ b/src/Mocap/FaceCapPredictor.cpp
@@ -0,0 +1,438 @@
+#ifdef ENABLE_MOCAP
+
+#include "FaceCapPredictor.h"
+
+#include "FaceCapCanonicalData.h"
+#include "FaceCapGeom.h"
+#include "FaceCapPose.h"
+#include "../ModelDownloader.h"
+
+#include <QDir>
+#include <QEventLoop>
+#include <QFileInfo>
+#include <QSettings>
+#include <QStandardPaths>
+#include <QTimer>
+
+#include <algorithm>
+#include <cmath>
+#include <vector>
+
+#ifdef ENABLE_ONNX
+#include <onnxruntime_cxx_api.h>
+#endif
+
+namespace {
+
+constexpr const char* kDetectorFile = "face_detector.onnx";
+constexpr const char* kLandmarksFile = "face_landmarks.onnx";
+constexpr const char* kBlendshapesFile = "face_blendshapes.onnx";
+// base URL points at the mocap ROOT; the face/pose subdir is appended so ONE
+// override serves both bundles.
+constexpr const char* kDefaultModelBaseUrl =
+    "https://huggingface.co/fernandotonon/QtMeshEditor-models/resolve/main/mocap/";
+constexpr const char* kBaseUrlSettingsKey = "ai/mocapModelBaseUrl";
+
+constexpr float kPresenceThreshold = 0.5f;
+
+}  // namespace
+
+// ---------------------------------------------------------------------------
+// static model management
+// ---------------------------------------------------------------------------
+
+QString FaceCapPredictor::modelDir()
+{
+    const QString dataPath =
+        QStandardPaths::writableLocation(QStandardPaths::AppDataLocation);
+    return QDir(dataPath).filePath(QStringLiteral("ai_models/mocap/face"));
+}
+
+bool FaceCapPredictor::modelsPresent()
+{
+    const QDir dir(modelDir());
+    return QFileInfo::exists(dir.filePath(QLatin1String(kDetectorFile)))
+           && QFileInfo::exists(dir.filePath(QLatin1String(kLandmarksFile)))
+           && QFileInfo::exists(dir.filePath(QLatin1String(kBlendshapesFile)));
+}
+
+QString FaceCapPredictor::ensureModelsBlocking()
+{
+#ifndef ENABLE_ONNX
+    return {};
+#else
+    if (modelsPresent())
+        return modelDir();
+    if (!qEnvironmentVariableIsEmpty("QTMESH_MOCAP_NO_DOWNLOAD"))
+        return {};
+
+    QString base;
+    {
+        QSettings s;
+        base = s.value(QString::fromLatin1(kBaseUrlSettingsKey)).toString();
+        if (base.isEmpty()) {
+            const QByteArray env = qgetenv("QTMESH_MOCAP_MODEL_BASE_URL");
+            base = env.isEmpty() ? QString::fromLatin1(kDefaultModelBaseUrl)
+                                 : QString::fromUtf8(env);
+        }
+    }
+    if (base.isEmpty())
+        return {};
+    if (!base.endsWith('/'))
+        base += '/';
+
+    auto* dl = ModelDownloader::instance();
+    if (!dl)
+        return {};
+
+    const QDir dir(modelDir());
+    auto downloadOne = [&](const char* fileName) -> bool {
+        const QString dest = dir.filePath(QLatin1String(fileName));
+        if (QFileInfo::exists(dest))
+            return true;
+        QDir().mkpath(QFileInfo(dest).absolutePath());
+        const QString label =
+            QStringLiteral("Face capture model (%1)").arg(QLatin1String(fileName));
+        QEventLoop loop;
+        bool ok = false, timedOut = false;
+        auto onDone = QObject::connect(
+            dl, &ModelDownloader::downloadCompleted, &loop,
+            [&](const QString& name, const QString&) {
+                if (name == label) { ok = true; loop.quit(); }
+            });
+        auto onErr = QObject::connect(
+            dl, &ModelDownloader::downloadError, &loop,
+            [&](const QString& name, const QString&) {
+                if (name == label) { ok = false; loop.quit(); }
+            });
+        QTimer timeout;
+        timeout.setSingleShot(true);
+        QObject::connect(&timeout, &QTimer::timeout, &loop,
+                         [&]() { timedOut = true; loop.quit(); });
+        timeout.start(300000);  // 5 min — the three graphs total ~6.4 MB
+        dl->startDownload(base + QLatin1String("face/") + QLatin1String(fileName), dest, label);
+        loop.exec();
+        QObject::disconnect(onDone);
+        QObject::disconnect(onErr);
+        if (timedOut && dl)
+            dl->cancelDownload();
+        return ok && !timedOut && QFileInfo::exists(dest);
+    };
+
+    if (!downloadOne(kDetectorFile) || !downloadOne(kLandmarksFile)
+        || !downloadOne(kBlendshapesFile))
+        return {};
+    return modelDir();
+#endif
+}
+
+// ---------------------------------------------------------------------------
+// non-ONNX stub (ENABLE_MOCAP requires ENABLE_ONNX in CMake, but keep the
+// TU compilable standalone)
+// ---------------------------------------------------------------------------
+
+#ifndef ENABLE_ONNX
+
+struct FaceCapPredictor::Impl {
+    QString error = QStringLiteral(
+        "face capture predictor unavailable (built without ENABLE_ONNX)");
+};
+
+FaceCapPredictor::FaceCapPredictor() : d(new Impl) {}
+FaceCapPredictor::~FaceCapPredictor() = default;
+bool FaceCapPredictor::load(const QString&) { return false; }
+bool FaceCapPredictor::isAvailable() const { return false; }
+QString FaceCapPredictor::lastError() const { return d->error; }
+FaceSample FaceCapPredictor::predict(const QImage&, double timeSec)
+{
+    FaceSample s;
+    s.timeSec = timeSec;
+    return s;
+}
+void FaceCapPredictor::resetTracking() {}
+int FaceCapPredictor::detectorRuns() const { return 0; }
+
+#else  // ENABLE_ONNX
+
+struct FaceCapPredictor::Impl {
+    Ort::Env env{ORT_LOGGING_LEVEL_WARNING, "qtmesh_facecap"};
+    std::unique_ptr<Ort::Session> detector;
+    std::unique_ptr<Ort::Session> landmarks;
+    std::unique_ptr<Ort::Session> blendshapes;
+    std::vector<std::array<float, 2>> anchors;
+    int detectorSize = 128;
+    int landmarksSize = 256;
+    QString error;
+    bool available = false;
+
+    // detector-skip tracking state
+    bool tracking = false;
+    FaceCapGeom::RotatedRect trackedRect;
+    int detectorRuns = 0;
+
+    // scratch buffers (avoid per-frame allocation in live mode)
+    std::vector<float> detInput;
+    std::vector<float> lmkInput;
+
+    std::unique_ptr<Ort::Session> openSession(const QString& path)
+    {
+        Ort::SessionOptions so;
+        so.SetIntraOpNumThreads(2);
+#ifdef Q_OS_MACOS
+        // CoreML EP where it helps; CPU fallback is always registered.
+        try {
+            std::unordered_map<std::string, std::string> opts;
+            so.AppendExecutionProvider("CoreML", opts);
+        } catch (const Ort::Exception&) {}
+#endif
+#ifdef Q_OS_WIN
+        const std::wstring wpath = path.toStdWString();
+        return std::make_unique<Ort::Session>(env, wpath.c_str(), so);
+#else
+        const QByteArray p = path.toUtf8();
+        return std::make_unique<Ort::Session>(env, p.constData(), so);
+#endif
+    }
+};
+
+FaceCapPredictor::FaceCapPredictor() : d(new Impl) {}
+FaceCapPredictor::~FaceCapPredictor() = default;
+
+bool FaceCapPredictor::load(const QString& dirIn)
+{
+    const QDir dir(dirIn.isEmpty() ? modelDir() : dirIn);
+    const QString det = dir.filePath(QLatin1String(kDetectorFile));
+    const QString lmk = dir.filePath(QLatin1String(kLandmarksFile));
+    const QString bs = dir.filePath(QLatin1String(kBlendshapesFile));
+    if (!QFileInfo::exists(det) || !QFileInfo::exists(lmk)
+        || !QFileInfo::exists(bs)) {
+        // Clear availability from any prior successful load() — a later load()
+        // pointed at a missing/invalid dir must report unavailable, not leave
+        // isAvailable() lying about the previous session's models.
+        d->available = false;
+        d->error = QStringLiteral(
+            "face capture models not found in %1 — they download on first "
+            "use, or set QTMESH_MOCAP_MODEL_BASE_URL").arg(dir.absolutePath());
+        return false;
+    }
+    try {
+        d->detector = d->openSession(det);
+        d->landmarks = d->openSession(lmk);
+        d->blendshapes = d->openSession(bs);
+
+        // runtime shape discovery — never hardcode graph tensor names
+        {
+            const auto info = d->detector->GetInputTypeInfo(0);
+            const auto shape = info.GetTensorTypeAndShapeInfo().GetShape();
+            if (shape.size() == 4 && shape[1] > 0)
+                d->detectorSize = static_cast<int>(shape[1]);
+        }
+        {
+            const auto info = d->landmarks->GetInputTypeInfo(0);
+            const auto shape = info.GetTensorTypeAndShapeInfo().GetShape();
+            if (shape.size() == 4 && shape[1] > 0)
+                d->landmarksSize = static_cast<int>(shape[1]);
+        }
+        d->anchors = FaceCapGeom::genSsdAnchors(d->detectorSize, {8, 16, 16, 16});
+        {
+            const auto info = d->detector->GetOutputTypeInfo(0);
+            const auto shape = info.GetTensorTypeAndShapeInfo().GetShape();
+            if (shape.size() == 3
+                && shape[1] != static_cast<int64_t>(d->anchors.size())) {
+                d->error = QStringLiteral(
+                    "face detector anchor count mismatch (model %1, ours %2)")
+                               .arg(shape[1]).arg(d->anchors.size());
+                d->available = false;
+                return false;
+            }
+        }
+        d->detInput.resize(static_cast<size_t>(d->detectorSize)
+                           * d->detectorSize * 3);
+        d->lmkInput.resize(static_cast<size_t>(d->landmarksSize)
+                           * d->landmarksSize * 3);
+        d->available = true;
+        d->error.clear();
+        return true;
+    } catch (const Ort::Exception& e) {
+        d->error = QStringLiteral("failed to load face capture models: %1")
+                       .arg(QString::fromUtf8(e.what()));
+        d->available = false;
+        return false;
+    }
+}
+
+bool FaceCapPredictor::isAvailable() const { return d->available; }
+QString FaceCapPredictor::lastError() const { return d->error; }
+void FaceCapPredictor::resetTracking() { d->tracking = false; }
+int FaceCapPredictor::detectorRuns() const { return d->detectorRuns; }
+
+FaceSample FaceCapPredictor::predict(const QImage& image, double timeSec)
+{
+    FaceSample sample;
+    sample.timeSec = timeSec;
+    if (!d->available) {
+        if (d->error.isEmpty())
+            d->error = QStringLiteral("predictor not loaded — call load()");
+        return sample;
+    }
+    QImage rgb = image.format() == QImage::Format_RGB888
+                     ? image
+                     : image.convertToFormat(QImage::Format_RGB888);
+    const int W = rgb.width();
+    const int H = rgb.height();
+    if (W <= 0 || H <= 0)
+        return sample;
+
+    try {
+        Ort::MemoryInfo mem =
+            Ort::MemoryInfo::CreateCpu(OrtArenaAllocator, OrtMemTypeDefault);
+        Ort::AllocatorWithDefaultOptions alloc;
+
+        auto runSession = [&](Ort::Session* session, Ort::Value input)
+            -> std::vector<Ort::Value> {
+            const Ort::AllocatedStringPtr inName =
+                session->GetInputNameAllocated(0, alloc);
+            std::vector<Ort::AllocatedStringPtr> outHolders;
+            std::vector<const char*> outNames;
+            const size_t n = session->GetOutputCount();
+            outHolders.reserve(n);
+            for (size_t i = 0; i < n; ++i) {
+                outHolders.push_back(session->GetOutputNameAllocated(i, alloc));
+                outNames.push_back(outHolders.back().get());
+            }
+            const char* in = inName.get();
+            return session->Run(Ort::RunOptions{nullptr}, &in, &input, 1,
+                                outNames.data(), outNames.size());
+        };
+
+        // --- stage 1: face ROI (tracked, or detector)
+        FaceCapGeom::RotatedRect rect;
+        if (d->tracking) {
+            rect = d->trackedRect;
+        } else {
+            const int ds = d->detectorSize;
+            FaceCapGeom::Letterbox lb = FaceCapGeom::letterboxToTensor(
+                rgb, ds, -1.f, 1.f, d->detInput.data());
+            const std::array<int64_t, 4> shape{1, ds, ds, 3};
+            Ort::Value input = Ort::Value::CreateTensor<float>(
+                mem, d->detInput.data(), d->detInput.size(), shape.data(),
+                shape.size());
+            auto outs = runSession(d->detector.get(), std::move(input));
+            ++d->detectorRuns;
+
+            // identify regressors vs scores by the last dimension
+            const float* rawBoxes = nullptr;
+            const float* rawScores = nullptr;
+            for (auto& o : outs) {
+                const auto s = o.GetTensorTypeAndShapeInfo().GetShape();
+                if (s.size() == 3 && s[2] > 1)
+                    rawBoxes = o.GetTensorData<float>();
+                else if (s.size() == 3 && s[2] == 1)
+                    rawScores = o.GetTensorData<float>();
+            }
+            if (!rawBoxes || !rawScores) {
+                d->error = QStringLiteral("unexpected face detector outputs");
+                return sample;
+            }
+            auto dets = FaceCapGeom::decodeDetections(
+                rawBoxes, rawScores, d->anchors, ds, /*numKeypoints=*/6);
+            if (dets.empty())
+                return sample;  // confidence 0 — no face this frame
+            FaceCapGeom::Detection& best = dets.front();
+            FaceCapGeom::unletterbox(lb, best.box[0], best.box[1]);
+            // box w/h scale by the content fraction
+            best.box[2] /= lb.fracX;
+            best.box[3] /= lb.fracY;
+            for (auto& kp : best.keypoints)
+                FaceCapGeom::unletterbox(lb, kp[0], kp[1]);
+            rect = FaceCapGeom::rectFromFaceDetection(best, W, H);
+        }
+
+        // --- stage 2: landmarks
+        const int ls = d->landmarksSize;
+        FaceCapGeom::cropRotatedRectToTensor(rgb, rect, ls, 0.f, 1.f,
+                                             d->lmkInput.data());
+        const std::array<int64_t, 4> lshape{1, ls, ls, 3};
+        Ort::Value linput = Ort::Value::CreateTensor<float>(
+            mem, d->lmkInput.data(), d->lmkInput.size(), lshape.data(),
+            lshape.size());
+        auto louts = runSession(d->landmarks.get(), std::move(linput));
+
+        const float* rawLandmarks = nullptr;
+        size_t landmarkFloats = 0;
+        float presenceLogit = 0.f;
+        bool presenceFound = false;
+        for (auto& o : louts) {
+            const auto info = o.GetTensorTypeAndShapeInfo();
+            const size_t count = info.GetElementCount();
+            if (count >= 468 * 3) {
+                rawLandmarks = o.GetTensorData<float>();
+                landmarkFloats = count;
+            } else if (count == 1 && !presenceFound
+                       && info.GetShape().size() == 4) {
+                presenceLogit = o.GetTensorData<float>()[0];
+                presenceFound = true;
+            }
+        }
+        if (!rawLandmarks) {
+            d->error = QStringLiteral("unexpected face landmark outputs");
+            return sample;
+        }
+        const float presence =
+            1.f / (1.f + std::exp(-std::clamp(presenceLogit, -50.f, 50.f)));
+        if (presence < kPresenceThreshold) {
+            // lost the face: fall back to the detector next frame
+            if (d->tracking) {
+                d->tracking = false;
+                return predict(image, timeSec);
+            }
+            return sample;
+        }
+
+        const int landmarkCount = static_cast<int>(landmarkFloats / 3);
+        std::vector<float> pts(rawLandmarks, rawLandmarks + landmarkFloats);
+        for (auto& v : pts)
+            v /= ls;  // 256-space px -> normalized crop coords (z: /256 then *w)
+        FaceCapGeom::projectLandmarks(pts.data(), landmarkCount, 3, rect);
+
+        // --- stage 3: blendshapes (146-subset pixel coords)
+        std::vector<float> bsInput(FaceCap::kBlendshapeInputLandmarks * 2);
+        for (int i = 0; i < FaceCap::kBlendshapeInputLandmarks; ++i) {
+            const int id = FaceCap::kBlendshapeLandmarkSubset[i];
+            bsInput[i * 2 + 0] = pts[id * 3 + 0];
+            bsInput[i * 2 + 1] = pts[id * 3 + 1];
+        }
+        const std::array<int64_t, 3> bshape{1, FaceCap::kBlendshapeInputLandmarks, 2};
+        Ort::Value binput = Ort::Value::CreateTensor<float>(
+            mem, bsInput.data(), bsInput.size(), bshape.data(), bshape.size());
+        auto bouts = runSession(d->blendshapes.get(), std::move(binput));
+        const float* scores = bouts.front().GetTensorData<float>();
+        const size_t scoreCount =
+            bouts.front().GetTensorTypeAndShapeInfo().GetElementCount();
+        for (size_t i = 0; i < sample.weights.size() && i < scoreCount; ++i)
+            sample.weights[i] = scores[i];
+
+        // --- head pose (weighted Kabsch vs the canonical face model)
+        const FaceCapPose::Result pose =
+            FaceCapPose::solveHeadPose(pts.data(), landmarkCount);
+        if (pose.ok) {
+            sample.headRotation = pose.rotation;
+            sample.headTranslation = pose.translation;
+        }
+        sample.confidence = presence;
+
+        // --- next-frame ROI from these landmarks (detector-skip)
+        d->trackedRect =
+            FaceCapGeom::rectFromFaceLandmarks(pts.data(), landmarkCount, W, H);
+        d->tracking = d->trackedRect.w > 4.f && d->trackedRect.h > 4.f;
+        return sample;
+    } catch (const Ort::Exception& e) {
+        d->error = QStringLiteral("face capture inference failed: %1")
+                       .arg(QString::fromUtf8(e.what()));
+        d->tracking = false;
+        return sample;
+    }
+}
+
+#endif  // ENABLE_ONNX
+#endif  // ENABLE_MOCAP
diff --git a/src/Mocap/FaceCapPredictor.h b/src/Mocap/FaceCapPredictor.h
new file mode 100644
index 000000000..7ec9317e5
--- /dev/null
+++ b/src/Mocap/FaceCapPredictor.h
@@ -0,0 +1,72 @@
+#ifndef FACECAPPREDICTOR_H
+#define FACECAPPREDICTOR_H
+
+// Face capture predictor (epic #869, Slice C #872) — ONNX consumer #9.
+// One RGB888 frame in -> 52 blendshape weights + head pose + confidence out,
+// via the three MediaPipe graphs converted by scripts/export-facecap-onnx.py
+// (Apache-2.0; contract in docs/MOCAP_SPIKE.md):
+//   face_detector.onnx     BlazeFace short-range (letterboxed 128, [-1,1])
+//   face_landmarks.onnx    Face Mesh V2 (rotated 256 crop, [0,1] -> 478 xyz)
+//   face_blendshapes.onnx  MLP-Mixer (146-landmark subset px -> 52 scores)
+//
+// Detector-skip tracking: once a face is tracked, the next frame's ROI comes
+// from the previous frame's landmarks and the detector is skipped until the
+// landmark presence drops below threshold (MediaPipe's own strategy).
+//
+// Models download on first use to AppData/ai_models/mocap/face/ (base URL
+// override: QSettings ai/mocapModelBaseUrl or QTMESH_MOCAP_MODEL_BASE_URL;
+// offline guard: QTMESH_MOCAP_NO_DOWNLOAD). Without ENABLE_ONNX (implied by
+// ENABLE_MOCAP) or without models, isAvailable() stays false and predict()
+// returns confidence 0 with lastError() explaining why — never crashes.
+
+#ifdef ENABLE_MOCAP
+
+#include <QImage>
+#include <QMetaType>
+#include <QString>
+
+#include <array>
+#include <memory>
+
+// One predicted sample. Pure data; shared vocabulary with the mapper,
+// recorder and GUI is FaceCap::kBlendshapeNames (FaceCapCanonicalData.h).
+struct FaceSample {
+    double timeSec = 0.0;
+    std::array<float, 52> weights{};                     // [0,1] each
+    std::array<float, 4> headRotation{0.f, 0.f, 0.f, 1.f};  // (x,y,z,w);
+        // +X right, +Y up, camera looks -Z; identity = facing the camera
+    std::array<float, 3> headTranslation{0.f, 0.f, 0.f};    // px units
+    float confidence = 0.f;                              // 0 = no face
+};
+Q_DECLARE_METATYPE(FaceSample)
+
+class FaceCapPredictor {
+public:
+    FaceCapPredictor();
+    ~FaceCapPredictor();
+
+    static QString modelDir();       // AppData/ai_models/mocap/face
+    static bool modelsPresent();
+    // Blocking first-use download of the three graphs (~6.4 MB total).
+    // Returns the model dir, or empty on failure/offline-guard/non-ONNX.
+    static QString ensureModelsBlocking();
+
+    // Create the ONNX sessions from dir (default: modelDir()).
+    bool load(const QString& dir = {});
+    bool isAvailable() const;
+    QString lastError() const;
+
+    // rgb888: any QImage (converted internally if needed).
+    FaceSample predict(const QImage& image, double timeSec);
+
+    void resetTracking();
+    // diagnostics: how many frames actually ran the detector (tracking test)
+    int detectorRuns() const;
+
+private:
+    struct Impl;
+    std::unique_ptr<Impl> d;
+};
+
+#endif  // ENABLE_MOCAP
+#endif  // FACECAPPREDICTOR_H
diff --git a/src/Mocap/FaceCapPredictor_test.cpp b/src/Mocap/FaceCapPredictor_test.cpp
new file mode 100644
index 000000000..d1098c6e1
--- /dev/null
+++ b/src/Mocap/FaceCapPredictor_test.cpp
@@ -0,0 +1,90 @@
+#ifdef ENABLE_MOCAP
+
+#include <gtest/gtest.h>
+
+#include <QDir>
+#include <QImage>
+
+#include "Mocap/FaceCapCanonicalData.h"
+#include "Mocap/FaceCapPredictor.h"
+
+// Without models on disk the predictor must degrade gracefully (the
+// UniRig/MeshSegmenter pattern): load() false, isAvailable() false, a clear
+// lastError, and predict() returning confidence 0 without crashing.
+TEST(FaceCapPredictor, GracefulWithoutModels)
+{
+    FaceCapPredictor p;
+    EXPECT_FALSE(p.isAvailable());
+    const bool loaded = p.load(QStringLiteral("/nonexistent/model/dir"));
+    EXPECT_FALSE(loaded);
+    EXPECT_FALSE(p.isAvailable());
+    EXPECT_FALSE(p.lastError().isEmpty());
+
+    QImage img(64, 64, QImage::Format_RGB888);
+    img.fill(Qt::gray);
+    const FaceSample s = p.predict(img, 1.5);
+    EXPECT_DOUBLE_EQ(s.timeSec, 1.5);
+    EXPECT_FLOAT_EQ(s.confidence, 0.f);
+}
+
+TEST(FaceCapPredictor, BlendshapeVocabularyIsStable)
+{
+    // the shared vocabulary contract: 52 names, _neutral first, jawOpen at 25
+    EXPECT_EQ(FaceCap::kBlendshapeCount, 52);
+    EXPECT_STREQ(FaceCap::kBlendshapeNames[0], "_neutral");
+    EXPECT_STREQ(FaceCap::kBlendshapeNames[25], "jawOpen");
+    EXPECT_STREQ(FaceCap::kBlendshapeNames[9], "eyeBlinkLeft");
+    EXPECT_STREQ(FaceCap::kBlendshapeNames[44], "mouthSmileLeft");
+    EXPECT_EQ(static_cast<int>(FaceCap::kBlendshapeLandmarkSubset.size()), 146);
+}
+
+// Real-inference test, env-gated (models are not in CI): set
+// QTMESH_MOCAP_MODELS_DIR to a dir containing the three face graphs and
+// QTMESH_MOCAP_TEST_IMAGE to a clear frontal-face photo.
+TEST(FaceCapPredictor, EnvGatedRealInference)
+{
+    const QByteArray dir = qgetenv("QTMESH_MOCAP_MODELS_DIR");
+    const QByteArray imagePath = qgetenv("QTMESH_MOCAP_TEST_IMAGE");
+    if (dir.isEmpty() || imagePath.isEmpty()) {
+        // Pass as a no-op — the CI harness counts ANY skipped test as a suite
+        // failure (same convention as the SkinEvaluate / ArkitTemplate env-
+        // gated tests). Set QTMESH_MOCAP_MODELS_DIR + QTMESH_MOCAP_TEST_IMAGE
+        // to exercise real inference.
+        SUCCEED() << "env not set — real inference not exercised";
+        return;
+    }
+
+    FaceCapPredictor p;
+    ASSERT_TRUE(p.load(QString::fromUtf8(dir))) << p.lastError().toStdString();
+    ASSERT_TRUE(p.isAvailable());
+
+    QImage img(QString::fromUtf8(imagePath));
+    ASSERT_FALSE(img.isNull());
+
+    const FaceSample s = p.predict(img, 0.0);
+    EXPECT_GT(s.confidence, 0.9f);
+    for (float w : s.weights) {
+        EXPECT_GE(w, 0.f);
+        EXPECT_LE(w, 1.f);
+    }
+    // a unit quaternion came back
+    const auto& q = s.headRotation;
+    EXPECT_NEAR(q[0] * q[0] + q[1] * q[1] + q[2] * q[2] + q[3] * q[3], 1.f, 1e-3);
+
+    // detector-skip: a second predict on the same frame must NOT re-run the
+    // detector (tracking ROI from the first frame's landmarks)
+    const int runsAfterFirst = p.detectorRuns();
+    const FaceSample s2 = p.predict(img, 1.0 / 30.0);
+    EXPECT_GT(s2.confidence, 0.9f);
+    EXPECT_EQ(p.detectorRuns(), runsAfterFirst);
+
+    // spot-check values against docs/MOCAP_SPIKE.md's parity run
+    for (int i : {9, 25, 44, 45}) {
+        printf("  %s = %.4f (first) / %.4f (tracked)\n",
+               FaceCap::kBlendshapeNames[i], s.weights[i], s2.weights[i]);
+    }
+    printf("  headRotation = (%.3f, %.3f, %.3f, %.3f) confidence=%.3f\n",
+           q[0], q[1], q[2], q[3], s.confidence);
+}
+
+#endif  // ENABLE_MOCAP
diff --git a/src/Mocap/MocapCLI.cpp b/src/Mocap/MocapCLI.cpp
new file mode 100644
index 000000000..39a333562
--- /dev/null
+++ b/src/Mocap/MocapCLI.cpp
@@ -0,0 +1,628 @@
+#include "MocapCLI.h"
+
+#include "../CLIPipeline.h"
+
+#include <QString>
+
+#ifndef ENABLE_MOCAP
+
+namespace MocapCLI {
+
+int run(int, char*[])
+{
+    CLIPipeline::writeCliError(QStringLiteral(
+        "Error: this build has no performance-capture support — rebuild with "
+        "-DENABLE_MOCAP=ON -DENABLE_ONNX=ON.\n"));
+    return 1;
+}
+
+}  // namespace MocapCLI
+
+#else  // ENABLE_MOCAP
+
+#include "FaceCapCanonicalData.h"
+#include "FaceCapMapper.h"
+#include "FaceCapPredictor.h"
+#include "MocapRecorder.h"
+#include "OneEuroFilter.h"
+#include "PoseCapPredictor.h"
+#include "PoseIKSolver.h"
+#include "VideoFrameSource.h"
+
+#include "../GamificationManager.h"
+#include "../Manager.h"
+#include "../MeshImporterExporter.h"
+#include "../MorphAnimationManager.h"
+#include "../SentryReporter.h"
+
+#include <OgreEntity.h>
+#include <OgreSceneNode.h>
+
+#include <QDir>
+#include <QEventLoop>
+#include <QFileInfo>
+#include <QJsonArray>
+#include <QJsonDocument>
+#include <QJsonObject>
+
+#include <array>
+#include <vector>
+
+namespace MocapCLI {
+
+namespace {
+
+const char* kUsage =
+    "Usage: qtmesh mocap <video> [--face] [--body] --mesh <meshfile> [-o out.glb]\n"
+    "              [--clip-name NAME] [--fps 30] [--smooth-cutoff HZ]\n"
+    "              [--no-smooth] [--map overrides.json] [--no-head]\n"
+    "              [--algo sam3dbody|pose-ik] [--no-model]\n"
+    "              [--frames-dir DIR] [--json]\n"
+    "\n"
+    "  --face: facial performance from a video (or an image sequence via\n"
+    "  --frames-dir) onto the mesh's ARKit-style morph targets as a weight\n"
+    "  clip, plus head rotation on the Head bone (skinned) or node (static).\n"
+    "  --body: full-body pose onto the mesh's humanoid skeleton as a skeletal\n"
+    "  clip (root locked; --algo pose-ik or --no-model force the analytic\n"
+    "  fallback backend). Both can run in one pass over the same video.\n";
+
+QJsonObject reportToJson(const MocapRecorder::FaceRecordReport& r)
+{
+    QJsonObject o;
+    o.insert(QLatin1String("clipName"), r.clipName);
+    o.insert(QLatin1String("framesProcessed"), r.framesProcessed);
+    o.insert(QLatin1String("framesNoFace"), r.framesNoFace);
+    o.insert(QLatin1String("keyframesWritten"), r.keyframesWritten);
+    o.insert(QLatin1String("headKeyframesWritten"), r.headKeyframesWritten);
+    o.insert(QLatin1String("headTarget"), r.headTarget);
+    o.insert(QLatin1String("clipLength"), r.clipLength);
+    o.insert(QLatin1String("matchedChannels"),
+             QJsonArray::fromStringList(r.matchedChannels));
+    o.insert(QLatin1String("unmatchedCanonical"),
+             QJsonArray::fromStringList(r.unmatchedCanonical));
+    o.insert(QLatin1String("unmatchedMesh"),
+             QJsonArray::fromStringList(r.unmatchedMesh));
+    if (!r.error.isEmpty())
+        o.insert(QLatin1String("error"), r.error);
+    if (!r.headError.isEmpty())
+        o.insert(QLatin1String("headError"), r.headError);
+    return o;
+}
+
+QJsonObject bodyReportToJson(const MocapRecorder::BodyRecordReport& r)
+{
+    QJsonObject o;
+    o.insert(QLatin1String("clipName"), r.clipName);
+    o.insert(QLatin1String("algorithmUsed"), r.algorithmUsed);
+    if (!r.fallbackReason.isEmpty())
+        o.insert(QLatin1String("fallbackReason"), r.fallbackReason);
+    o.insert(QLatin1String("framesProcessed"), r.framesProcessed);
+    o.insert(QLatin1String("rolesResolved"), r.rolesResolved);
+    o.insert(QLatin1String("tracksWritten"), r.tracksWritten);
+    o.insert(QLatin1String("clipLength"), r.clipLength);
+    if (!r.error.isEmpty())
+        o.insert(QLatin1String("error"), r.error);
+    return o;
+}
+
+}  // namespace
+
+int run(int argc, char* argv[])
+{
+    QString videoPath, meshPath, outputPath, mapPath, framesDir;
+    QString clipName;
+    QString algo = QStringLiteral("sam3dbody");
+    double fps = 30.0;
+    double smoothCutoff = 1.0;
+    bool smooth = true;
+    bool face = false;
+    bool body = false;
+    bool noModel = false;
+    bool head = true;
+    bool jsonOutput = false;
+
+    for (int i = 1; i < argc; ++i) {
+        const QString arg = QString::fromLocal8Bit(argv[i]);
+        if (arg == QLatin1String("mocap") || arg == QLatin1String("--cli"))
+            continue;
+        if (arg == QLatin1String("--face")) { face = true; continue; }
+        if (arg == QLatin1String("--body")) { body = true; continue; }
+        if (arg == QLatin1String("--no-model")) { noModel = true; continue; }
+        if (arg == QLatin1String("--root-motion")) {
+            CLIPipeline::writeCliError(QStringLiteral(
+                "Error: --root-motion is not available on the pose-ik backend "
+                "(its world landmarks are hip-centred, so they carry no root "
+                "translation) — the root stays locked to the standing pose. "
+                "Tracked for the SAM 3D Body backend in #874.\n"));
+            return 2;
+        }
+        if (arg == QLatin1String("--algo")) {
+            if (i + 1 >= argc) {
+                CLIPipeline::writeCliError(
+                    QStringLiteral("Error: --algo requires a value.\n"));
+                return 2;
+            }
+            algo = QString::fromLocal8Bit(argv[++i]).toLower();
+            if (algo != QLatin1String("sam3dbody")
+                && algo != QLatin1String("pose-ik")) {
+                CLIPipeline::writeCliError(QStringLiteral(
+                    "Error: --algo must be sam3dbody or pose-ik.\n"));
+                return 2;
+            }
+            continue;
+        }
+        if (arg == QLatin1String("--json")) { jsonOutput = true; continue; }
+        if (arg == QLatin1String("--no-head")) { head = false; continue; }
+        if (arg == QLatin1String("--no-smooth")) { smooth = false; continue; }
+        auto value = [&](const char* flag) -> QString {
+            if (i + 1 >= argc) {
+                CLIPipeline::writeCliError(
+                    QStringLiteral("Error: %1 requires a value.\n")
+                        .arg(QLatin1String(flag)));
+                return {};
+            }
+            return QString::fromLocal8Bit(argv[++i]);
+        };
+        if (arg == QLatin1String("--mesh")) {
+            meshPath = value("--mesh");
+            if (meshPath.isEmpty()) return 2;
+            continue;
+        }
+        if (arg == QLatin1String("-o") || arg == QLatin1String("--output")) {
+            outputPath = value("-o");
+            if (outputPath.isEmpty()) return 2;
+            continue;
+        }
+        if (arg == QLatin1String("--clip-name")) {
+            clipName = value("--clip-name");
+            if (clipName.isEmpty()) return 2;
+            continue;
+        }
+        if (arg == QLatin1String("--map")) {
+            mapPath = value("--map");
+            if (mapPath.isEmpty()) return 2;
+            continue;
+        }
+        if (arg == QLatin1String("--frames-dir")) {
+            framesDir = value("--frames-dir");
+            if (framesDir.isEmpty()) return 2;
+            continue;
+        }
+        if (arg == QLatin1String("--fps")) {
+            const QString v = value("--fps");
+            if (v.isEmpty()) return 2;
+            fps = v.toDouble();
+            if (fps <= 0 || fps > 240) {
+                CLIPipeline::writeCliError(
+                    QStringLiteral("Error: --fps out of range (1..240).\n"));
+                return 2;
+            }
+            continue;
+        }
+        if (arg == QLatin1String("--smooth-cutoff")) {
+            const QString v = value("--smooth-cutoff");
+            if (v.isEmpty()) return 2;
+            smoothCutoff = v.toDouble();
+            if (smoothCutoff <= 0) {
+                CLIPipeline::writeCliError(
+                    QStringLiteral("Error: --smooth-cutoff must be > 0 Hz.\n"));
+                return 2;
+            }
+            continue;
+        }
+        if (!arg.startsWith(QLatin1Char('-')) && videoPath.isEmpty()) {
+            videoPath = arg;
+            continue;
+        }
+        CLIPipeline::writeCliError(
+            QStringLiteral("Error: unknown option '%1'.\n%2")
+                .arg(arg, QLatin1String(kUsage)));
+        return 2;
+    }
+
+    if (!face && !body) {
+        CLIPipeline::writeCliError(
+            QStringLiteral("Error: nothing to capture — pass --face and/or "
+                           "--body.\n%1").arg(QLatin1String(kUsage)));
+        return 2;
+    }
+    if (clipName.isEmpty())
+        clipName = face ? QStringLiteral("FaceCap") : QStringLiteral("BodyCap");
+    if (meshPath.isEmpty()) {
+        CLIPipeline::writeCliError(
+            QStringLiteral("Error: --mesh <meshfile> is required.\n%1")
+                .arg(QLatin1String(kUsage)));
+        return 2;
+    }
+    if (videoPath.isEmpty() && framesDir.isEmpty()) {
+        CLIPipeline::writeCliError(
+            QStringLiteral("Error: no input video (or --frames-dir).\n%1")
+                .arg(QLatin1String(kUsage)));
+        return 2;
+    }
+    const QFileInfo meshFi(meshPath);
+    if (!meshFi.exists()) {
+        CLIPipeline::writeCliError(
+            QStringLiteral("Error: mesh not found: %1\n").arg(meshPath));
+        return 1;
+    }
+    if (!framesDir.isEmpty() && !QFileInfo(framesDir).isDir()) {
+        CLIPipeline::writeCliError(
+            QStringLiteral("Error: --frames-dir is not a directory: %1\n")
+                .arg(framesDir));
+        return 1;
+    }
+    if (framesDir.isEmpty() && !QFileInfo::exists(videoPath)) {
+        CLIPipeline::writeCliError(
+            QStringLiteral("Error: video not found: %1\n").arg(videoPath));
+        return 1;
+    }
+
+    if (!CLIPipeline::initOgreHeadless())
+        return 1;
+
+    SentryReporter::addBreadcrumb(
+        QStringLiteral("ai.assist.mocap_face"),
+        QStringLiteral("cli mocap --face mesh=.%1 source=%2")
+            .arg(meshFi.suffix(),
+                 framesDir.isEmpty() ? QStringLiteral("video")
+                                     : QStringLiteral("frames-dir")));
+
+    // --- load the mesh + enumerate morph targets -----------------------------
+    MeshImporterExporter::importer({meshFi.absoluteFilePath()});
+    Ogre::Entity* entity = nullptr;
+    for (Ogre::Entity* e : Manager::getSingleton()->getEntities()) {
+        if (e && e->getMovableType() == "Entity") { entity = e; break; }
+    }
+    if (!entity) {
+        CLIPipeline::writeCliError(
+            QStringLiteral("Error: failed to load %1\n").arg(meshPath));
+        return 1;
+    }
+
+    const QStringList targets =
+        face ? MorphAnimationManager::instance()->morphTargetsFor(entity)
+             : QStringList();
+    if (face && targets.isEmpty() && !head) {
+        CLIPipeline::writeCliError(QStringLiteral(
+            "Error: %1 has NO morph targets and --no-head was given — nothing "
+            "to record.\nFace capture drives ARKit-style blendshape targets "
+            "(jawOpen, mouthSmileLeft, ...). Ready Player Me avatars and\n"
+            "CC/iClone heads ship with them; the Edit-Mode 'Vertex Morph "
+            "Animation' section authors them manually.\n").arg(meshPath));
+        return 1;
+    }
+
+    const FaceCapMapper::Mapping mapping =
+        face ? FaceCapMapper::build(targets, mapPath) : FaceCapMapper::Mapping{};
+    if (!mapping.error.isEmpty()) {
+        CLIPipeline::writeCliError(
+            QStringLiteral("Error: %1\n").arg(mapping.error));
+        return 1;
+    }
+    if (face && !jsonOutput) {
+        QString table = QStringLiteral("Channel mapping (%1 matched):\n")
+                            .arg(mapping.channels.size());
+        for (const auto& ch : mapping.channels)
+            table += QStringLiteral("  %1 -> %2\n")
+                         .arg(QLatin1String(
+                                  FaceCap::kBlendshapeNames[ch.canonicalIndex]),
+                              ch.meshTargetName);
+        if (!mapping.unmatchedCanonical.isEmpty())
+            table += QStringLiteral("  unmatched capture channels: %1\n")
+                         .arg(mapping.unmatchedCanonical.join(
+                             QStringLiteral(", ")));
+        if (!mapping.unmatchedMesh.isEmpty())
+            table += QStringLiteral("  unmatched mesh targets: %1\n")
+                         .arg(mapping.unmatchedMesh.join(QStringLiteral(", ")));
+        CLIPipeline::writeOutput(table);
+    }
+    if (face && mapping.channels.isEmpty() && !targets.isEmpty() && !head) {
+        CLIPipeline::writeCliError(QStringLiteral(
+            "Error: none of the %1 mesh morph targets matched a capture "
+            "channel — see the table above; a --map overrides.json can bind "
+            "custom names.\n").arg(targets.size()));
+        return 1;
+    }
+    if (body && !entity->hasSkeleton()) {
+        CLIPipeline::writeCliError(QStringLiteral(
+            "Error: %1 is not skinned — body capture retargets onto a "
+            "humanoid skeleton (rig one first: qtmesh rig --skeleton humanoid "
+            "--skin).\n").arg(meshPath));
+        return 1;
+    }
+
+    // --- predictors -------------------------------------------------------------
+    FaceCapPredictor predictor;
+    if (face) {
+        if (!FaceCapPredictor::modelsPresent()
+            && FaceCapPredictor::ensureModelsBlocking().isEmpty()) {
+            CLIPipeline::writeCliError(QStringLiteral(
+                "Error: face capture models are not available (download failed, "
+                "offline guard set, or not hosted yet).\nSet "
+                "QTMESH_MOCAP_MODEL_BASE_URL or place the three graphs in %1.\n")
+                .arg(FaceCapPredictor::modelDir()));
+            return 1;
+        }
+        if (!predictor.load()) {
+            CLIPipeline::writeCliError(
+                QStringLiteral("Error: %1\n").arg(predictor.lastError()));
+            return 1;
+        }
+    }
+
+    // Body backend dispatch: sam3dbody is the quality path, but its
+    // checkpoints are gated (see THIRD_PARTY_AI_MODELS.md) — until the export
+    // is hosted, every request falls back to pose-ik with a clear reason.
+    QString bodyAlgoUsed, bodyFallbackReason;
+    PoseCapPredictor posePredictor;
+    if (body) {
+        bodyAlgoUsed = QStringLiteral("pose-ik");
+        if (algo == QLatin1String("sam3dbody") && !noModel)
+            bodyFallbackReason = QStringLiteral(
+                "sam3dbody model not available (checkpoint access pending — "
+                "see THIRD_PARTY_AI_MODELS.md); used pose-ik");
+        else if (noModel)
+            bodyFallbackReason = QStringLiteral("--no-model forced pose-ik");
+        if (!PoseCapPredictor::modelsPresent()
+            && PoseCapPredictor::ensureModelsBlocking().isEmpty()) {
+            CLIPipeline::writeCliError(QStringLiteral(
+                "Error: pose capture models are not available (download "
+                "failed, offline guard set, or not hosted yet).\nSet "
+                "QTMESH_MOCAP_MODEL_BASE_URL or place the two graphs in %1.\n")
+                .arg(PoseCapPredictor::modelDir()));
+            return 1;
+        }
+        if (!posePredictor.load()) {
+            CLIPipeline::writeCliError(
+                QStringLiteral("Error: %1\n").arg(posePredictor.lastError()));
+            return 1;
+        }
+    }
+
+    // --- frame source -> samples ----------------------------------------------
+    std::unique_ptr<VideoFrameSource> source;
+    if (!framesDir.isEmpty()) {
+        QDir dir(framesDir);
+        QStringList images = dir.entryList(
+            {QStringLiteral("*.png"), QStringLiteral("*.jpg"),
+             QStringLiteral("*.jpeg"), QStringLiteral("*.bmp")},
+            QDir::Files, QDir::Name);
+        for (QString& f : images)
+            f = dir.filePath(f);
+        source = std::make_unique<ImageSequenceFrameSource>(images, fps);
+    } else {
+        source = std::make_unique<FileFrameSource>(videoPath, fps);
+    }
+    QString openError;
+    if (!source->open(&openError)) {
+        CLIPipeline::writeCliError(
+            QStringLiteral("Error: %1\n").arg(openError));
+        return 1;
+    }
+
+    std::vector<FaceSample> samples;
+    std::vector<PoseSample> poseSamples;
+    std::array<OneEuroFilter, 52> weightFilters;
+    OneEuroQuatFilter headFilter;
+    if (smooth) {
+        OneEuroFilter::Params params;
+        params.minCutoff = smoothCutoff;
+        for (auto& f : weightFilters)
+            f = OneEuroFilter(params);
+        headFilter = OneEuroQuatFilter(params);
+    }
+
+    QEventLoop loop;
+    bool finished = false;
+    QString streamError;
+    QObject::connect(source.get(), &VideoFrameSource::frameReady,
+                     [&](const MocapFrame& frame) {
+                         if (face) {
+                             FaceSample s = predictor.predict(frame.image,
+                                                              frame.timeSec);
+                             if (smooth && s.confidence > 0.f) {
+                                 for (int c = 0; c < 52; ++c)
+                                     s.weights[c] = static_cast<float>(
+                                         weightFilters[c].filter(s.weights[c],
+                                                                 s.timeSec));
+                                 s.headRotation = headFilter.filter(
+                                     s.headRotation, s.timeSec);
+                             }
+                             samples.push_back(s);
+                         }
+                         if (body) {
+                             poseSamples.push_back(posePredictor.predict(
+                                 frame.image, frame.timeSec));
+                         }
+                     });
+    QObject::connect(source.get(), &VideoFrameSource::finished, [&] {
+        finished = true;
+        loop.quit();
+    });
+    QObject::connect(source.get(), &VideoFrameSource::errorOccurred,
+                     [&](const QString& message) {
+                         streamError = message;
+                         finished = true;
+                         loop.quit();
+                     });
+    source->start();
+    if (!finished)
+        loop.exec();
+    if (!streamError.isEmpty()) {
+        CLIPipeline::writeCliError(
+            QStringLiteral("Error: %1\n").arg(streamError));
+        return 1;
+    }
+    if (samples.empty() && poseSamples.empty()) {
+        CLIPipeline::writeCliError(
+            QStringLiteral("Error: the source produced no frames.\n"));
+        return 1;
+    }
+
+    // --- record: face ------------------------------------------------------------
+    // In combined --face --body mode a failed stream (e.g. the face is too
+    // small to track in full-body footage) reports its error but doesn't
+    // abort the other stream; the exit code is 0 if at least one recorded.
+    MocapRecorder::FaceRecordReport report;
+    if (face) {
+        MocapRecorder::FaceRecordOptions options;
+        options.clipName = clipName;
+        options.head = head;
+        report = MocapRecorder::recordFace(entity, samples, mapping, options);
+        if (!report.ok()) {
+            CLIPipeline::writeCliError(
+                QStringLiteral("Error: %1\n").arg(report.error));
+            if (!body)
+                return 1;
+        }
+    }
+
+    // --- record: body ------------------------------------------------------------
+    MocapRecorder::BodyRecordReport bodyReport;
+    if (body) {
+        std::vector<std::vector<std::array<float, 4>>> clipQuats;
+        std::array<OneEuroQuatFilter, PoseIK::kCanonicalRoles> roleFilters;
+        if (smooth) {
+            OneEuroFilter::Params params;
+            params.minCutoff = smoothCutoff;
+            for (auto& f : roleFilters)
+                f = OneEuroQuatFilter(params);
+        }
+        PoseIK::Solver solver;
+        int noPose = 0;
+        for (const PoseSample& s : poseSamples) {
+            if (s.confidence <= 0.f) {
+                ++noPose;
+                continue;  // dropped frame; the take compresses across gaps
+            }
+            PoseIK::FrameResult fr =
+                solver.solveFrame(s.world.data(), s.visibility.data());
+            if (smooth)
+                for (int r = 0; r < PoseIK::kCanonicalRoles; ++r)
+                    fr.quats[r] = roleFilters[r].filter(fr.quats[r], s.timeSec);
+            clipQuats.push_back(std::vector<std::array<float, 4>>(
+                fr.quats.begin(), fr.quats.end()));
+        }
+        if (clipQuats.size() < 2) {
+            CLIPipeline::writeCliError(QStringLiteral(
+                "Error: no person tracked in the source (%1 of %2 frames had "
+                "no pose).\n").arg(noPose).arg(poseSamples.size()));
+            // Face succeeded → keep its take, but SKIP body recording entirely
+            // (recordBody would reject <2 frames anyway; falling through fed it
+            // the empty clip and overwrote this error). Fail only if face
+            // wasn't recorded either.
+            if (!face || !report.ok())
+                return 1;
+            bodyReport.error = QStringLiteral("no person tracked");
+        } else {
+            MocapRecorder::BodyRecordOptions bodyOptions;
+            bodyOptions.clipName = face ? clipName + QStringLiteral("_Body")
+                                        : clipName;
+            bodyOptions.algorithmUsed = bodyAlgoUsed;
+            bodyOptions.fallbackReason = bodyFallbackReason;
+            bodyReport = MocapRecorder::recordBody(
+                entity, clipQuats, static_cast<int>(fps), bodyOptions);
+            bodyReport.framesProcessed = static_cast<int>(poseSamples.size());
+            if (!bodyReport.ok()) {
+                CLIPipeline::writeCliError(
+                    QStringLiteral("Error: %1\n").arg(bodyReport.error));
+                if (!face || !report.ok())
+                    return 1;
+            }
+        }
+    }
+    if (face && body && !report.ok() && !bodyReport.ok())
+        return 1;
+
+    // --- export -------------------------------------------------------------------
+    if (!outputPath.isEmpty()) {
+        Ogre::SceneNode* node = entity->getParentSceneNode();
+        const QString fmt = CLIPipeline::formatForExtension(outputPath);
+        if (!node
+            || MeshImporterExporter::exporter(
+                   node, QFileInfo(outputPath).absoluteFilePath(), fmt) != 0) {
+            CLIPipeline::writeCliError(
+                QStringLiteral("Error: export to %1 failed.\n").arg(outputPath));
+            return 1;
+        }
+    }
+
+    if (jsonOutput) {
+        // Face-only output keeps its ORIGINAL top-level shape (clipName,
+        // framesProcessed, error, … at the root) so pre-body-capture scripts
+        // don't break. Only nest under "face"/"body" when body capture is
+        // actually part of the run (the two-report case that needs
+        // disambiguation).
+        QJsonObject root;
+        if (face && !body) {
+            root = reportToJson(report);
+        } else {
+            if (face)
+                root.insert(QLatin1String("face"), reportToJson(report));
+            if (body)
+                root.insert(QLatin1String("body"), bodyReportToJson(bodyReport));
+        }
+        CLIPipeline::writeOutput(QString::fromUtf8(
+            QJsonDocument(root).toJson(QJsonDocument::Indented)));
+    } else {
+        QString text;
+        // Only print the face SUCCESS line when face recording actually
+        // succeeded — in a --face --body run where face failed but body
+        // succeeded, the error was already written to stderr above; don't
+        // also claim a face take was recorded.
+        if (face && report.ok())
+            text += QStringLiteral(
+                        "Recorded '%1': %2 frames (%3 without a face), "
+                        "%4 weight keys on %5 channels, %6 head keys (%7), "
+                        "clip length %8s\n")
+                        .arg(report.clipName)
+                        .arg(report.framesProcessed)
+                        .arg(report.framesNoFace)
+                        .arg(report.keyframesWritten)
+                        .arg(report.matchedChannels.size())
+                        .arg(report.headKeyframesWritten)
+                        .arg(report.headTarget)
+                        .arg(report.clipLength, 0, 'f', 2);
+        if (face && report.ok() && !report.headError.isEmpty())
+            text += QStringLiteral("  warning: %1\n").arg(report.headError);
+        if (body) {
+            text += QStringLiteral(
+                        "Recorded '%1' via %2: %3 frames, %4 canonical roles, "
+                        "%5 bone tracks, clip length %6s\n")
+                        .arg(bodyReport.clipName, bodyReport.algorithmUsed)
+                        .arg(bodyReport.framesProcessed)
+                        .arg(bodyReport.rolesResolved)
+                        .arg(bodyReport.tracksWritten)
+                        .arg(bodyReport.clipLength, 0, 'f', 2);
+            if (!bodyReport.fallbackReason.isEmpty())
+                text += QStringLiteral("  (%1)\n").arg(bodyReport.fallbackReason);
+        }
+        if (!outputPath.isEmpty())
+            text += QStringLiteral("Exported -> %1\n").arg(outputPath);
+        CLIPipeline::writeOutput(text);
+    }
+
+    if (face)
+        GamificationManager::noteOperation(
+            QStringLiteral("mocap_face"),
+            {{QStringLiteral("frames"),
+              static_cast<qint64>(report.framesProcessed)},
+             {QStringLiteral("keyframes"),
+              static_cast<qint64>(report.keyframesWritten
+                                  + report.headKeyframesWritten)}},
+            GamificationManager::Surface::Cli);
+    if (body)
+        GamificationManager::noteOperation(
+            QStringLiteral("mocap_body"),
+            {{QStringLiteral("frames"),
+              static_cast<qint64>(bodyReport.framesProcessed)},
+             {QStringLiteral("tracks"),
+              static_cast<qint64>(bodyReport.tracksWritten)}},
+            GamificationManager::Surface::Cli);
+    return 0;
+}
+
+}  // namespace MocapCLI
+
+#endif  // ENABLE_MOCAP
diff --git a/src/Mocap/MocapCLI.h b/src/Mocap/MocapCLI.h
new file mode 100644
index 000000000..0f15e223f
--- /dev/null
+++ b/src/Mocap/MocapCLI.h
@@ -0,0 +1,25 @@
+#ifndef MOCAPCLI_H
+#define MOCAPCLI_H
+
+// Headless `qtmesh mocap` subcommand (epic #869, Slice D #873):
+//
+//   qtmesh mocap <video> --face --mesh <meshfile> [-o out.glb]
+//          [--clip-name NAME] [--fps 30] [--smooth-cutoff HZ] [--no-smooth]
+//          [--map overrides.json] [--no-head] [--frames-dir DIR] [--json]
+//
+// video file -> FaceCapPredictor -> One-Euro smoothing -> MocapRecorder ->
+// morph-weight clip (+ head clip) on the mesh -> optional re-export.
+// `--frames-dir` replaces the video with an image sequence
+// (ImageSequenceFrameSource) — the headless-CI/debug path that needs no
+// Qt Multimedia decode.
+//
+// Always compiled; a non-ENABLE_MOCAP build prints the standard
+// "rebuild with -DENABLE_MOCAP" message (the Alembic pattern).
+
+namespace MocapCLI {
+
+int run(int argc, char* argv[]);
+
+}  // namespace MocapCLI
+
+#endif  // MOCAPCLI_H
diff --git a/src/Mocap/MocapController.cpp b/src/Mocap/MocapController.cpp
new file mode 100644
index 000000000..10415975a
--- /dev/null
+++ b/src/Mocap/MocapController.cpp
@@ -0,0 +1,1067 @@
+#include "MocapController.h"
+
+#ifdef ENABLE_MOCAP
+#include "MocapRecorder.h"
+#include "OneEuroFilter.h"
+#include "PoseCapPredictor.h"
+#include "PoseIKSolver.h"
+#include "VideoFrameSource.h"
+#include "../AnimationMerger.h"
+#include "../MotionInbetween.h"
+#include "../Manager.h"
+#include "../MorphAnimationManager.h"
+#include "../SelectionSet.h"
+#include "../SentryReporter.h"
+#include "../UndoManager.h"
+#include "../GamificationManager.h"
+#include "../commands/RecordMocapClipCommand.h"
+
+#include <OgreAnimationState.h>
+#include <OgreBone.h>
+#include <OgreEntity.h>
+#include <OgreMesh.h>
+#include <OgreSkeletonInstance.h>
+
+#include <QBuffer>
+#include <QElapsedTimer>
+#include <QThread>
+#endif
+
+#include <QApplication>
+#include <QCoreApplication>
+#include <QDir>
+#include <QFileDialog>
+#include <QGuiApplication>
+#include <QPermissions>
+#include <QWidget>
+
+namespace {
+MocapController* s_instance = nullptr;
+}
+
+MocapController* MocapController::instance()
+{
+    if (!s_instance)
+        s_instance = new MocapController();
+    return s_instance;
+}
+
+MocapController* MocapController::qmlInstance(QQmlEngine* engine, QJSEngine*)
+{
+    Q_UNUSED(engine);
+    MocapController* inst = instance();
+    QQmlEngine::setObjectOwnership(inst, QQmlEngine::CppOwnership);
+    return inst;
+}
+
+void MocapController::kill()
+{
+    delete s_instance;
+    s_instance = nullptr;
+}
+
+#ifndef ENABLE_MOCAP
+
+// -----------------------------------------------------------------------------
+// Non-mocap build: the section shows a disabled label with the reason.
+// -----------------------------------------------------------------------------
+
+struct MocapController::Impl {};
+
+MocapController::MocapController(QObject* parent) : QObject(parent) {}
+MocapController::~MocapController() = default;
+bool MocapController::available() const { return false; }
+QString MocapController::unavailableReason() const
+{
+    return tr("This build has no performance-capture support — rebuild with "
+              "-DENABLE_MOCAP=ON -DENABLE_ONNX=ON.");
+}
+int MocapController::state() const { return Idle; }
+QVariantList MocapController::availableDevices() const { return {}; }
+bool MocapController::faceDetected() const { return false; }
+double MocapController::liveFps() const { return 0; }
+double MocapController::recordingSeconds() const { return 0; }
+int MocapController::sampleCount() const { return 0; }
+QString MocapController::previewDataUrl() const { return {}; }
+QString MocapController::statusMessage() const { return {}; }
+int MocapController::matchedChannelCount() const { return 0; }
+QStringList MocapController::unmatchedChannels() const { return {}; }
+bool MocapController::headAvailable() const { return false; }
+bool MocapController::bodyAvailable() const { return false; }
+bool MocapController::bodyDetected() const { return false; }
+bool MocapController::faceEnabled() const { return false; }
+void MocapController::setFaceEnabled(bool) {}
+bool MocapController::headEnabled() const { return false; }
+void MocapController::setHeadEnabled(bool) {}
+bool MocapController::bodyEnabled() const { return false; }
+void MocapController::setBodyEnabled(bool) {}
+QString MocapController::clipName() const { return QStringLiteral("FaceCap"); }
+void MocapController::setClipName(const QString&) {}
+double MocapController::smoothingCutoff() const { return 1.0; }
+void MocapController::setSmoothingCutoff(double) {}
+void MocapController::refreshDevices() {}
+bool MocapController::startPreview(const QString&) { return false; }
+bool MocapController::startPreviewFromVideo(const QString&) { return false; }
+QString MocapController::openVideoDialog() { return {}; }
+void MocapController::stopPreview() {}
+bool MocapController::startRecording() { return false; }
+void MocapController::stopRecording() {}
+void MocapController::calibrateNeutral() {}
+
+#else  // ENABLE_MOCAP
+
+// -----------------------------------------------------------------------------
+// Worker: drains the camera mailbox through the predictor off the main thread.
+// -----------------------------------------------------------------------------
+
+// One canonical-role world-quat frame from the pose solver, marshalled to the
+// main thread alongside the face sample (avoids a second queued signal type).
+struct BodyLiveFrame {
+    bool valid = false;
+    std::array<std::array<float, 4>, PoseIK::kCanonicalRoles> quats;
+    uint32_t resolvedMask = 0;
+};
+Q_DECLARE_METATYPE(BodyLiveFrame)
+
+// queued sampleReady(FaceSample, BodyLiveFrame, QImage) across the worker
+// thread boundary needs both payload types registered.
+namespace {
+struct MocapMetaTypeRegistrar {
+    MocapMetaTypeRegistrar()
+    {
+        qRegisterMetaType<FaceSample>("FaceSample");
+        qRegisterMetaType<BodyLiveFrame>("BodyLiveFrame");
+    }
+};
+const MocapMetaTypeRegistrar mocapMetaTypeRegistrar;
+}  // namespace
+
+class MocapInferenceWorker : public QObject
+{
+    Q_OBJECT
+public:
+    FrameMailbox* mailbox = nullptr;
+    FaceCapPredictor predictor;
+    std::array<OneEuroFilter, 52> weightFilters;
+    OneEuroQuatFilter headFilter;
+    bool smooth = true;
+
+    // body (optional; created only when the Body channel is enabled)
+    bool bodyEnabled = false;
+    std::shared_ptr<PoseCapPredictor> posePredictor;
+    PoseIK::Solver poseSolver;
+    std::array<OneEuroQuatFilter, PoseIK::kCanonicalRoles> roleFilters;
+
+public slots:
+    void processPending()
+    {
+        if (!mailbox)
+            return;
+        MocapFrame frame;
+        while (mailbox->take(&frame)) {
+            FaceSample s = predictor.predict(frame.image, frame.timeSec);
+            if (smooth && s.confidence > 0.f) {
+                for (int c = 0; c < 52; ++c)
+                    s.weights[c] = static_cast<float>(
+                        weightFilters[c].filter(s.weights[c], s.timeSec));
+                s.headRotation = headFilter.filter(s.headRotation, s.timeSec);
+            }
+
+            BodyLiveFrame body;
+            if (bodyEnabled && posePredictor) {
+                const PoseSample ps =
+                    posePredictor->predict(frame.image, frame.timeSec);
+                if (ps.confidence > 0.f) {
+                    PoseIK::FrameResult fr = poseSolver.solveFrame(
+                        ps.world.data(), ps.visibility.data());
+                    if (smooth)
+                        for (int r = 0; r < PoseIK::kCanonicalRoles; ++r)
+                            fr.quats[r] =
+                                roleFilters[r].filter(fr.quats[r], frame.timeSec);
+                    body.valid = true;
+                    body.quats = fr.quats;
+                    body.resolvedMask = fr.resolvedMask;
+                }
+            }
+
+            // downscale sparsely for the HUD preview (payload stays small)
+            QImage preview;
+            if (frame.frameIndex % 3 == 0)
+                preview = frame.image.scaledToWidth(240, Qt::FastTransformation);
+            emit sampleReady(s, body, preview);
+        }
+    }
+
+signals:
+    void sampleReady(const FaceSample& sample, const BodyLiveFrame& body,
+                     const QImage& preview);
+};
+
+struct MocapController::Impl {
+    State state = Idle;
+    QString status;
+    QString clipName = QStringLiteral("FaceCap");
+    double smoothingCutoff = 1.0;
+
+    // The live source feeding the worker: a CameraFrameSource (webcam) OR a
+    // FileFrameSource (video-file preview, the macOS-camera-blocked path).
+    // Both feed the same mailbox() via the base class.
+    std::unique_ptr<VideoFrameSource> camera;
+    VideoFrameSource* injectedSource = nullptr;  // test seam, not owned
+    QThread workerThread;
+    MocapInferenceWorker* worker = nullptr;  // owned by workerThread
+
+    // capture-session state (all main-thread)
+    std::string entityName;
+    FaceCapMapper::Mapping mapping;
+    QString headBone;
+    bool calibrated = false;
+    Ogre::Quaternion neutral = Ogre::Quaternion::IDENTITY;
+    Ogre::Quaternion headBindWorld = Ogre::Quaternion::IDENTITY;
+    Ogre::Quaternion headBindLocal = Ogre::Quaternion::IDENTITY;
+    bool headWasManuallyControlled = false;
+    QHash<QString, float> savedWeights;          // mesh target -> weight
+    QStringList savedEnabledAnimations;
+
+    // channel enables (persist across sessions; body gated on a humanoid rig)
+    bool faceEnabled = true;
+    bool headEnabled = true;
+    bool bodyEnabled = false;
+    bool bodyRigOk = false;   // selection resolved >= half the canonical roles
+
+    // body live-drive state: one canonical role -> the rig bone it drives, plus
+    // that bone's bind orientations (for the same world-delta math recordBody
+    // uses) and its pre-preview manual-control flag (restore contract).
+    struct BodyBone {
+        int role = -1;
+        std::string boneName;
+        Ogre::Quaternion bindLocal = Ogre::Quaternion::IDENTITY;
+        Ogre::Quaternion bindWorld = Ogre::Quaternion::IDENTITY;
+        // The PARENT bone's bind-pose world orientation. A world-space rotation
+        // delta must be transported through the PARENT's frame (not the bone's
+        // own) to become a valid parent-relative local, matching the offline
+        // applyMotionClip retarget. Using the bone's own bindWorld is only
+        // correct when the local bind is identity (~head); it mis-rotates
+        // bones with a non-trivial local bind (arms/shoulders).
+        Ogre::Quaternion parentBindWorld = Ogre::Quaternion::IDENTITY;
+        bool wasManuallyControlled = false;
+    };
+    std::vector<BodyBone> bodyBones;
+    bool bodyCalibrated = false;
+    std::array<Ogre::Quaternion, PoseIK::kCanonicalRoles> bodyNeutral;
+    // Shared per-frame retargeter (same math as the recorded clip); built once
+    // at preview start for the driven entity.
+    std::shared_ptr<BodyRetargeter> bodyRetargeter;
+    bool bodyDetected = false;
+
+    // recording
+    bool recordPending = false;
+    std::vector<FaceSample> take;
+    std::vector<BodyLiveFrame> bodyTake;   // parallel to `take`, when body on
+    double takeStart = 0.0;
+    double lastSampleTime = 0.0;
+
+    // HUD
+    bool faceDetected = false;
+    double liveFps = 0.0;
+    double lastArrival = -1.0;
+    QElapsedTimer clock;
+    QString previewDataUrl;
+    int sampleCount = 0;
+
+    Ogre::Entity* entity() const
+    {
+        auto* mgr = Manager::getSingletonPtr();
+        if (!mgr || !mgr->getSceneMgr() || entityName.empty())
+            return nullptr;
+        auto* scene = mgr->getSceneMgr();
+        return scene->hasEntity(entityName) ? scene->getEntity(entityName)
+                                            : nullptr;
+    }
+};
+
+MocapController::MocapController(QObject* parent)
+    : QObject(parent), d(new Impl)
+{
+    // Keep the channel availability (Face/Head/Body checkboxes) in sync with
+    // whatever is selected, WITHOUT running a preview — otherwise the boxes
+    // stay disabled until the first Preview builds the mapping, and never
+    // update when the user picks a different mesh.
+    if (auto* sel = SelectionSet::getSingleton())
+        connect(sel, &SelectionSet::selectionChanged, this,
+                [this]() { refreshMappingForSelection(); });
+    refreshMappingForSelection();
+}
+
+MocapController::~MocapController()
+{
+    // stopPreview() touches Ogre (snapshot/restore of bone + morph state) and
+    // could throw; an exception escaping a destructor calls std::terminate.
+    // Swallow it — we're tearing down anyway.
+    try {
+        stopPreview();
+    } catch (...) {
+    }
+}
+
+bool MocapController::available() const { return true; }
+QString MocapController::unavailableReason() const { return {}; }
+int MocapController::state() const { return d->state; }
+
+QVariantList MocapController::availableDevices() const
+{
+    QVariantList out;
+    for (const auto& dev : CameraFrameSource::availableDevices()) {
+        QVariantMap m;
+        m.insert(QStringLiteral("id"), dev.id);
+        m.insert(QStringLiteral("description"), dev.description);
+        out.append(m);
+    }
+    return out;
+}
+
+bool MocapController::faceDetected() const { return d->faceDetected; }
+double MocapController::liveFps() const { return d->liveFps; }
+double MocapController::recordingSeconds() const
+{
+    return d->state == Recording ? d->lastSampleTime - d->takeStart : 0.0;
+}
+int MocapController::sampleCount() const { return d->sampleCount; }
+QString MocapController::previewDataUrl() const { return d->previewDataUrl; }
+QString MocapController::statusMessage() const { return d->status; }
+int MocapController::matchedChannelCount() const
+{
+    return d->mapping.channels.size();
+}
+QStringList MocapController::unmatchedChannels() const
+{
+    return d->mapping.unmatchedCanonical;
+}
+bool MocapController::headAvailable() const { return !d->headBone.isEmpty(); }
+bool MocapController::bodyAvailable() const { return d->bodyRigOk; }
+bool MocapController::bodyDetected() const { return d->bodyDetected; }
+bool MocapController::faceEnabled() const { return d->faceEnabled; }
+void MocapController::setFaceEnabled(bool on)
+{
+    if (on == d->faceEnabled) return;
+    d->faceEnabled = on;
+    emit channelsChanged();
+}
+bool MocapController::headEnabled() const { return d->headEnabled; }
+void MocapController::setHeadEnabled(bool on)
+{
+    if (on == d->headEnabled) return;
+    d->headEnabled = on;
+    emit channelsChanged();
+}
+bool MocapController::bodyEnabled() const { return d->bodyEnabled; }
+void MocapController::setBodyEnabled(bool on)
+{
+    if (on == d->bodyEnabled) return;
+    d->bodyEnabled = on;
+    emit channelsChanged();
+}
+QString MocapController::clipName() const { return d->clipName; }
+void MocapController::setClipName(const QString& name)
+{
+    if (name == d->clipName || name.isEmpty())
+        return;
+    d->clipName = name;
+    emit clipNameChanged();
+}
+double MocapController::smoothingCutoff() const { return d->smoothingCutoff; }
+void MocapController::setSmoothingCutoff(double hz)
+{
+    if (hz <= 0 || hz == d->smoothingCutoff)
+        return;
+    d->smoothingCutoff = hz;
+    emit smoothingChanged();
+}
+
+void MocapController::refreshDevices() { emit devicesChanged(); }
+
+void MocapController::setStatusMessage(const QString& message)
+{
+    d->status = message;
+    emit statusChanged();
+}
+
+bool MocapController::startPreview(const QString& deviceId)
+{
+    if (d->state != Idle)
+        return false;
+
+    // A drive target must exist before we bother the user with a camera
+    // permission prompt.
+    auto* sel = SelectionSet::getSingleton();
+    bool haveEntity = false;
+    if (sel && !sel->getResolvedEntities().isEmpty())
+        haveEntity = sel->getResolvedEntities().first() != nullptr;
+    if (!haveEntity) {
+        setStatusMessage(tr("Select an entity to drive first."));
+        emit errorOccurred(d->status);
+        return false;
+    }
+
+    // Camera permission (Qt 6.6+). QCamera::start() delivers NO frames on
+    // macOS until the user has granted access — without this request the
+    // preview would sit at "Starting camera…" forever (there is no error, the
+    // sink is simply silent). requestPermission is async; we continue in
+    // beginPreview() once granted. checkPermission() short-circuits the prompt
+    // on repeat runs.
+    QCameraPermission camPerm;
+    if (qApp->checkPermission(camPerm) == Qt::PermissionStatus::Granted)
+        return beginPreview(deviceId);
+
+    // Not granted yet — ALWAYS go through requestPermission(). It is the only
+    // call that shows the OS dialog (checkPermission never prompts); on the
+    // first run macOS presents it, and if the user previously denied it the
+    // request returns Denied without a dialog, which we turn into the
+    // open-Settings hint. We do NOT short-circuit on a pre-checked Denied,
+    // so clicking Preview always makes a real attempt at the prompt.
+    setStatusMessage(tr("Requesting camera access…"));
+    qApp->requestPermission(camPerm, this,
+        [this, deviceId](const QPermission& result) {
+            if (result.status() == Qt::PermissionStatus::Granted) {
+                beginPreview(deviceId);
+            } else {
+                setStatusMessage(
+                    tr("Camera access was not granted. If no prompt appeared, "
+                       "enable it for QtMeshEditor in System Settings → "
+                       "Privacy & Security → Camera, then click Preview again."));
+                emit errorOccurred(d->status);
+            }
+        });
+    return true;  // async; the callback finishes the job
+}
+
+void MocapController::refreshMappingForSelection()
+{
+    // Never disturb a running session — the mapping is fixed once preview starts.
+    if (d->state != Idle)
+        return;
+
+    auto* sel = SelectionSet::getSingleton();
+    Ogre::Entity* entity = nullptr;
+    if (sel) {
+        const auto ents = sel->getResolvedEntities();
+        if (!ents.isEmpty())
+            entity = ents.first();
+    }
+    if (!entity) {
+        // Nothing selected: clear so the channel checkboxes disable.
+        d->entityName.clear();
+        d->mapping = FaceCapMapper::Mapping{};
+        d->headBone.clear();
+        d->bodyBones.clear();
+        d->bodyRigOk = false;
+        emit mappingChanged();
+        return;
+    }
+
+    d->entityName = entity->getName();
+    d->mapping = FaceCapMapper::build(
+        MorphAnimationManager::instance()->morphTargetsFor(entity));
+    d->headBone = MocapRecorder::resolveHeadBone(entity);
+
+    // body rig mapping: canonical role -> the rig bone that plays it (the same
+    // MotionInbetween::canonicalIndexForBone the retarget uses). Requires a
+    // skinned mesh resolving >= half of the 22 roles (the humanoid gate).
+    d->bodyBones.clear();
+    d->bodyRigOk = false;
+    if (entity->hasSkeleton()) {
+        Ogre::SkeletonInstance* skel = entity->getSkeleton();
+        std::array<bool, PoseIK::kCanonicalRoles> roleSeen{};
+        for (unsigned short i = 0; i < skel->getNumBones(); ++i) {
+            Ogre::Bone* bone = skel->getBone(i);
+            const int role = MotionInbetween::canonicalIndexForBone(
+                QString::fromStdString(bone->getName()));
+            if (role < 0 || role >= PoseIK::kCanonicalRoles || roleSeen[role])
+                continue;
+            roleSeen[role] = true;
+            Impl::BodyBone bb;
+            bb.role = role;
+            bb.boneName = bone->getName();
+            d->bodyBones.push_back(bb);
+        }
+        int resolved = 0;
+        for (bool s : roleSeen) resolved += s ? 1 : 0;
+        d->bodyRigOk = resolved * 2 >= PoseIK::kCanonicalRoles;  // >= half
+        if (!d->bodyRigOk)
+            d->bodyBones.clear();
+    }
+    if (!d->bodyRigOk)
+        d->bodyEnabled = false;  // can't drive body on a non-humanoid rig
+
+    emit mappingChanged();
+}
+
+bool MocapController::beginPreview(const QString& deviceId)
+{
+    // Webcam path: build the camera source and run the shared preview.
+    return beginPreviewWithLiveSource(
+        std::make_unique<CameraFrameSource>(deviceId),
+        tr("Starting camera…"));
+}
+
+bool MocapController::startPreviewFromVideo(const QString& filePath)
+{
+    if (d->state != Idle)
+        return false;
+    if (filePath.isEmpty()) {
+        setStatusMessage(tr("No video file selected."));
+        emit errorOccurred(d->status);
+        return false;
+    }
+    // Video-file path: no camera permission needed (the macOS-blocked-camera
+    // fallback). FileFrameSource plays at real time and drops frames
+    // latest-wins into the mailbox, same as the webcam preview.
+    return beginPreviewWithLiveSource(
+        std::make_unique<FileFrameSource>(filePath),
+        tr("Playing video…"));
+}
+
+QString MocapController::openVideoDialog()
+{
+    // Non-native dialog (matches the codebase convention — avoids the macOS
+    // native panel stealing focus from the Ogre window).
+    if (QWidget* activeWin = QApplication::activeWindow()) {
+        activeWin->raise();
+        activeWin->activateWindow();
+    }
+    QApplication::processEvents();
+    const QString file = QFileDialog::getOpenFileName(
+        QApplication::activeWindow(),
+        tr("Select a video file"),
+        QDir::currentPath(),
+        tr("Video files (*.mp4 *.mov *.m4v *.avi *.mkv *.webm);;All files (*)"),
+        nullptr,
+        QFileDialog::DontUseNativeDialog);
+    return file;
+}
+
+bool MocapController::beginPreviewWithLiveSource(
+    std::unique_ptr<VideoFrameSource> source, const QString& startingMessage)
+{
+    if (d->state != Idle)
+        return false;
+
+    auto* sel = SelectionSet::getSingleton();
+    Ogre::Entity* entity = nullptr;
+    if (sel) {
+        const auto ents = sel->getResolvedEntities();
+        if (!ents.isEmpty())
+            entity = ents.first();
+    }
+    if (!entity) {
+        setStatusMessage(tr("Select an entity to drive first."));
+        emit errorOccurred(d->status);
+        return false;
+    }
+    d->camera = std::move(source);
+
+    // Determine what the selection can be driven with BEFORE downloading any
+    // models — a ~30 MB face-model fetch is wasted if the mesh has no ARKit
+    // morph targets and no head bone (field-reported: clicking Preview on a
+    // plain mesh triggered the download, then failed the drivability check).
+    // (Also keeps the channel checkboxes honest — see refreshMappingForSelection.)
+    refreshMappingForSelection();
+
+    const bool faceDrivable = d->faceEnabled && !d->mapping.channels.isEmpty();
+    const bool headDrivable = d->headEnabled && !d->headBone.isEmpty();
+    const bool bodyDrivable = d->bodyEnabled && d->bodyRigOk;
+    if (!faceDrivable && !headDrivable && !bodyDrivable) {
+        setStatusMessage(
+                  tr("Nothing to drive: enable a channel the selection "
+                     "supports (morph targets for Face, a Head bone, or a "
+                     "humanoid rig for Body)."));
+        emit errorOccurred(d->status);
+        return false;
+    }
+
+    // NOW that we know there is something to drive, fetch the models (blocking
+    // download with a visible status). Face models feed both face + head drive
+    // (the head rotation comes from the face graph); the pose models are
+    // fetched lazily in the worker only when body drive is active.
+    if (!FaceCapPredictor::modelsPresent()) {
+        setStatusMessage(tr("Downloading face capture models…"));
+        QCoreApplication::processEvents();
+        if (FaceCapPredictor::ensureModelsBlocking().isEmpty()) {
+            setStatusMessage(
+                      tr("Face capture models are not available (offline, or "
+                         "not hosted yet)."));
+            emit errorOccurred(d->status);
+            return false;
+        }
+    }
+
+    // snapshot live state (the restore contract)
+    d->savedWeights.clear();
+    auto* morphMgr = MorphAnimationManager::instance();
+    for (const auto& ch : d->mapping.channels)
+        d->savedWeights.insert(ch.meshTargetName,
+                               morphMgr->weight(entity, ch.meshTargetName));
+    d->savedEnabledAnimations.clear();
+    if (auto* states = entity->getAllAnimationStates()) {
+        for (const auto& [name, st] : states->getAnimationStates()) {
+            if (st->getEnabled()) {
+                d->savedEnabledAnimations << QString::fromStdString(name);
+                st->setEnabled(false);
+            }
+        }
+    }
+    // Head-bone drive is used only when body is NOT driving (body owns the
+    // whole skeleton incl. the head when enabled, so they never fight).
+    const bool headBoneDrive =
+        d->headEnabled && !d->headBone.isEmpty() && !bodyDrivable;
+    if (headBoneDrive && entity->hasSkeleton()) {
+        Ogre::SkeletonInstance* skel = entity->getSkeleton();
+        Ogre::Bone* bone = skel->getBone(d->headBone.toStdString());
+        d->headWasManuallyControlled = bone->isManuallyControlled();
+        d->headBindLocal = bone->getOrientation();
+        d->headBindWorld = bone->_getDerivedOrientation();
+        bone->setManuallyControlled(true);
+    } else {
+        d->headBone.clear();  // signals onSample to skip the head-bone path
+    }
+
+    // body drive setup: build the SHARED retargeter (same math as the recorded
+    // clip) from the rig's bind pose, and put the driven bones under manual
+    // control so we can write their orientations each frame.
+    d->bodyRetargeter.reset();
+    if (bodyDrivable && entity->hasSkeleton()) {
+        Ogre::SkeletonInstance* skel = entity->getSkeleton();
+        // The retargeter reads the bind frame off the skeleton, so capture it
+        // BEFORE any bone goes manual (reset() gives the bind pose).
+        d->bodyRetargeter =
+            std::make_shared<BodyRetargeter>(entity->getMesh()->getSkeleton().get());
+        for (auto& bb : d->bodyBones) {
+            Ogre::Bone* bone = skel->getBone(bb.boneName);
+            bb.wasManuallyControlled = bone->isManuallyControlled();
+            bb.bindLocal = bone->getOrientation();  // for restore-on-stop
+            bone->setManuallyControlled(true);
+        }
+        if (!d->bodyRetargeter->valid())
+            d->bodyRetargeter.reset();  // non-humanoid — skip body drive
+    } else {
+        d->bodyBones.clear();  // not driving this session
+    }
+
+    d->calibrated = false;
+    d->bodyCalibrated = false;
+    d->bodyDetected = false;
+    d->faceDetected = false;
+    d->liveFps = 0;
+    d->lastArrival = -1;
+    d->sampleCount = 0;
+    d->clock.start();
+
+    // camera + worker
+    QString error;
+    if (!d->camera->open(&error)) {
+        d->camera.reset();
+        restoreEntityState();
+        setStatusMessage(error);
+        emit errorOccurred(error);
+        return false;
+    }
+    d->worker = new MocapInferenceWorker();
+    d->worker->mailbox = &d->camera->mailbox();
+    OneEuroFilter::Params params;
+    params.minCutoff = d->smoothingCutoff;
+    for (auto& f : d->worker->weightFilters)
+        f = OneEuroFilter(params);
+    d->worker->headFilter = OneEuroQuatFilter(params);
+    for (auto& f : d->worker->roleFilters)
+        f = OneEuroQuatFilter(params);
+    if (!d->worker->predictor.load()) {
+        const QString msg = d->worker->predictor.lastError();
+        delete d->worker;
+        d->worker = nullptr;
+        d->camera.reset();
+        restoreEntityState();
+        setStatusMessage(msg);
+        emit errorOccurred(msg);
+        return false;
+    }
+    // body predictor (only when driving body this session — the mesh is skinned
+    // + humanoid and the Body channel is on)
+    if (!d->bodyBones.empty()) {
+        if (!PoseCapPredictor::modelsPresent()) {
+            setStatusMessage(tr("Downloading pose capture models…"));
+            QCoreApplication::processEvents();
+            PoseCapPredictor::ensureModelsBlocking();
+        }
+        auto pose = std::make_shared<PoseCapPredictor>();
+        if (pose->load()) {
+            d->worker->posePredictor = pose;
+            d->worker->bodyEnabled = true;
+        } else {
+            // body models unavailable: keep face/head live, drop body cleanly
+            setStatusMessage(tr("Body capture unavailable (%1) — driving "
+                                "face/head only.").arg(pose->lastError()));
+            for (auto& bb : d->bodyBones)
+                if (auto* skel = entity->getSkeleton())
+                    skel->getBone(bb.boneName)->setManuallyControlled(
+                        bb.wasManuallyControlled);
+            d->bodyBones.clear();
+        }
+    }
+    d->worker->moveToThread(&d->workerThread);
+    connect(&d->workerThread, &QThread::finished, d->worker,
+            &QObject::deleteLater);
+    connect(d->camera.get(), &VideoFrameSource::frameReady, d->worker,
+            [w = d->worker](const MocapFrame&) { w->processPending(); },
+            Qt::QueuedConnection);
+    connect(d->camera.get(), &VideoFrameSource::errorOccurred, this,
+            [this](const QString& message) {
+                setStatusMessage(message);
+                emit errorOccurred(message);
+                stopPreview();
+            });
+    connect(d->worker, &MocapInferenceWorker::sampleReady, this,
+            [this](const FaceSample& s, const BodyLiveFrame& b,
+                   const QImage& p) { onSample(s, b, p); },
+            Qt::QueuedConnection);
+    d->workerThread.start();
+
+    d->state = CameraStarting;
+    emit stateChanged();
+    setStatusMessage(startingMessage);
+    d->camera->start();
+
+    SentryReporter::addBreadcrumb("ai.assist.mocap_live", "preview start");
+    GamificationManager::noteFeature(QStringLiteral("mocap"),
+                                     GamificationManager::Surface::Gui);
+    return true;
+}
+
+bool MocapController::startPreviewWithSource(VideoFrameSource* source)
+{
+    // Test seam: synchronous drive, no camera/worker thread. Samples are fed
+    // manually through onSample on THIS thread; source may be null.
+    if (d->state != Idle)
+        return false;
+    auto* sel = SelectionSet::getSingleton();
+    Ogre::Entity* entity = nullptr;
+    if (sel) {
+        const auto ents = sel->getResolvedEntities();
+        if (!ents.isEmpty())
+            entity = ents.first();
+    }
+    if (!entity)
+        return false;
+    d->entityName = entity->getName();
+    d->mapping = FaceCapMapper::build(
+        MorphAnimationManager::instance()->morphTargetsFor(entity));
+    d->headBone = MocapRecorder::resolveHeadBone(entity);
+    emit mappingChanged();
+
+    d->savedWeights.clear();
+    auto* morphMgr = MorphAnimationManager::instance();
+    for (const auto& ch : d->mapping.channels)
+        d->savedWeights.insert(ch.meshTargetName,
+                               morphMgr->weight(entity, ch.meshTargetName));
+    d->savedEnabledAnimations.clear();
+    if (auto* states = entity->getAllAnimationStates()) {
+        for (const auto& [name, st] : states->getAnimationStates()) {
+            if (st->getEnabled()) {
+                d->savedEnabledAnimations << QString::fromStdString(name);
+                st->setEnabled(false);
+            }
+        }
+    }
+    if (!d->headBone.isEmpty() && entity->hasSkeleton()) {
+        Ogre::Bone* bone =
+            entity->getSkeleton()->getBone(d->headBone.toStdString());
+        d->headWasManuallyControlled = bone->isManuallyControlled();
+        d->headBindLocal = bone->getOrientation();
+        d->headBindWorld = bone->_getDerivedOrientation();
+        bone->setManuallyControlled(true);
+    }
+    d->calibrated = false;
+    d->sampleCount = 0;
+    d->clock.start();
+    d->injectedSource = source;
+    d->state = Previewing;
+    emit stateChanged();
+    return true;
+}
+
+// Test seam companion: feed a sample as if it came from the worker.
+void MocapController::onSample(const FaceSample& sample, const QImage& preview)
+{
+    onSample(sample, BodyLiveFrame{}, preview);
+}
+
+void MocapController::onSample(const FaceSample& sample,
+                               const BodyLiveFrame& body, const QImage& preview)
+{
+    if (d->state == Idle)
+        return;
+    if (d->state == CameraStarting) {
+        d->state = Previewing;
+        emit stateChanged();
+        setStatusMessage(tr("Live — driving the selection."));
+    }
+
+    // HUD
+    d->faceDetected = sample.confidence > 0.f;
+    d->bodyDetected = body.valid;
+    if (d->lastArrival >= 0.0) {
+        const double dt = sample.timeSec - d->lastArrival;
+        if (dt > 0)
+            d->liveFps = 0.8 * d->liveFps + 0.2 * (1.0 / dt);
+    }
+    d->lastArrival = sample.timeSec;
+    ++d->sampleCount;
+    emit liveStatsChanged();
+    if (!preview.isNull()) {
+        QByteArray png;
+        QBuffer buffer(&png);
+        buffer.open(QIODevice::WriteOnly);
+        preview.save(&buffer, "PNG");
+        d->previewDataUrl =
+            QStringLiteral("data:image/png;base64,") + png.toBase64();
+        emit previewChanged();
+    }
+
+    Ogre::Entity* entity = d->entity();
+    if (!entity || sample.confidence <= 0.f)
+        return;
+
+    // live drive — morphs
+    auto* morphMgr = MorphAnimationManager::instance();
+    for (const auto& ch : d->mapping.channels)
+        morphMgr->setWeight(entity, ch.meshTargetName,
+                            sample.weights[ch.canonicalIndex]);
+
+    // live drive — head (skipped when body owns the skeleton: the body
+    // retargeter already drives the Head bone from the pose landmarks, and
+    // letting both write the same bone makes them fight frame-to-frame).
+    const bool bodyOwnsSkeleton =
+        body.valid && d->bodyRetargeter && d->bodyRetargeter->valid();
+    if (!d->headBone.isEmpty() && entity->hasSkeleton() && !bodyOwnsSkeleton) {
+        if (!d->calibrated) {
+            d->neutral = Ogre::Quaternion(
+                sample.headRotation[3], sample.headRotation[0],
+                sample.headRotation[1], sample.headRotation[2]);
+            d->calibrated = true;
+        }
+        const Ogre::Quaternion current(
+            sample.headRotation[3], sample.headRotation[0],
+            sample.headRotation[1], sample.headRotation[2]);
+        const Ogre::Quaternion delta = current * d->neutral.Inverse();
+        const Ogre::Quaternion local =
+            d->headBindWorld.Inverse() * delta * d->headBindWorld;
+        Ogre::SkeletonInstance* skel = entity->getSkeleton();
+        Ogre::Bone* bone = skel->getBone(d->headBone.toStdString());
+        bone->setOrientation(d->headBindLocal * local);
+        skel->_notifyManualBonesDirty();
+    }
+
+    // live drive — body. Uses the SHARED BodyRetargeter, i.e. the EXACT same
+    // legacy-transport math applyMotionClip bakes into the recorded clip, so
+    // live Preview and Record can't diverge: each joint's parent-relative
+    // articulation delta (vs the first frame) composed onto the rig's harvested
+    // standing pose. setOrientation takes the absolute local the retargeter
+    // returns (Ogre node keys are absolute, not deltas).
+    if (body.valid && d->bodyRetargeter && d->bodyRetargeter->valid()
+        && entity->hasSkeleton()) {
+        const auto locals =
+            d->bodyRetargeter->evaluateFrame(body.quats, body.resolvedMask);
+        Ogre::SkeletonInstance* skel = entity->getSkeleton();
+        for (const auto& [handle, local] : locals)
+            skel->getBone(handle)->setOrientation(local);
+        skel->_notifyManualBonesDirty();
+    }
+
+    if (d->state == Recording) {
+        d->take.push_back(sample);
+        if (!d->bodyBones.empty())
+            d->bodyTake.push_back(body);
+        d->lastSampleTime = sample.timeSec;
+    }
+}
+
+void MocapController::calibrateNeutral()
+{
+    d->calibrated = false;  // the next confident sample becomes neutral
+    setStatusMessage(tr("Hold a neutral face…"));
+}
+
+bool MocapController::startRecording()
+{
+    if (d->state != Previewing)
+        return false;
+    d->take.clear();
+    d->bodyTake.clear();
+    d->takeStart = d->lastArrival;
+    d->lastSampleTime = d->takeStart;
+    d->state = Recording;
+    emit stateChanged();
+    setStatusMessage(tr("Recording…"));
+    SentryReporter::addBreadcrumb("ai.assist.mocap_live", "record start");
+    return true;
+}
+
+void MocapController::stopRecording()
+{
+    if (d->state != Recording)
+        return;
+    d->state = Previewing;
+    emit stateChanged();
+
+    if (d->take.size() < 2) {
+        setStatusMessage(tr("Nothing recorded (no confident frames)."));
+        return;
+    }
+
+    QStringList summary;
+    int faceKeys = 0, bodyTracks = 0;
+    double clipLen = 0.0;
+
+    // face + head clip (only when a face/head channel actually drove)
+    if (!d->mapping.channels.isEmpty() || !d->headBone.isEmpty()) {
+        MocapRecorder::FaceRecordOptions options;
+        options.clipName = d->clipName;
+        options.head = !d->headBone.isEmpty();
+        auto* cmd = new RecordMocapClipCommand(d->entityName, d->take,
+                                               d->mapping, options);
+        UndoManager::getSingleton()->push(cmd);
+        const auto& report = cmd->report();
+        if (report.ok()) {
+            faceKeys = report.keyframesWritten + report.headKeyframesWritten;
+            clipLen = report.clipLength;
+            summary << tr("'%1' (%2 keys)").arg(report.clipName).arg(faceKeys);
+        } else {
+            setStatusMessage(report.error);
+        }
+        GamificationManager::noteOperation(
+            QStringLiteral("mocap_face"),
+            {{QStringLiteral("frames"),
+              static_cast<qint64>(report.framesProcessed)},
+             {QStringLiteral("keyframes"), static_cast<qint64>(faceKeys)}},
+            GamificationManager::Surface::Gui);
+    }
+
+    // body clip: convert the buffered live frames to the [frame][22] world-quat
+    // stream recordBody expects (identity for roles unresolved that frame), and
+    // push a SEPARATE undo command so face + body each undo cleanly.
+    if (!d->bodyBones.empty() && d->bodyTake.size() >= 2) {
+        std::vector<std::vector<std::array<float, 4>>> clipQuats;
+        clipQuats.reserve(d->bodyTake.size());
+        for (const auto& bf : d->bodyTake) {
+            if (!bf.valid)
+                continue;
+            clipQuats.emplace_back(bf.quats.begin(), bf.quats.end());
+        }
+        if (clipQuats.size() >= 2) {
+            MocapRecorder::BodyRecordOptions bopts;
+            bopts.clipName = d->clipName + QStringLiteral("_Body");
+            bopts.algorithmUsed = QStringLiteral("pose-ik");
+            const int fps = 30;
+            auto* bcmd = new RecordBodyClipCommand(d->entityName, clipQuats,
+                                                   fps, bopts);
+            UndoManager::getSingleton()->push(bcmd);
+            const auto& br = bcmd->report();
+            if (br.ok()) {
+                bodyTracks = br.tracksWritten;
+                clipLen = std::max(clipLen, br.clipLength);
+                summary << tr("'%1' (%2 tracks)")
+                               .arg(br.clipName).arg(bodyTracks);
+            }
+            GamificationManager::noteOperation(
+                QStringLiteral("mocap_body"),
+                {{QStringLiteral("frames"),
+                  static_cast<qint64>(br.framesProcessed)},
+                 {QStringLiteral("tracks"), static_cast<qint64>(bodyTracks)}},
+                GamificationManager::Surface::Gui);
+        }
+    }
+
+    if (!summary.isEmpty())
+        setStatusMessage(tr("Recorded %1s → %2 — Ctrl+Z to discard.")
+                             .arg(clipLen, 0, 'f', 1)
+                             .arg(summary.join(QStringLiteral(" + "))));
+}
+
+void MocapController::restoreEntityState()
+{
+    Ogre::Entity* entity = d->entity();
+    if (!entity)
+        return;
+    auto* morphMgr = MorphAnimationManager::instance();
+    for (auto it = d->savedWeights.begin(); it != d->savedWeights.end(); ++it)
+        morphMgr->setWeight(entity, it.key(), it.value());
+    if (entity->hasSkeleton()) {
+        Ogre::SkeletonInstance* skel = entity->getSkeleton();
+        if (!d->headBone.isEmpty()) {
+            Ogre::Bone* bone = skel->getBone(d->headBone.toStdString());
+            bone->setOrientation(d->headBindLocal);
+            bone->setManuallyControlled(d->headWasManuallyControlled);
+        }
+        // restore every body-driven bone to its pre-preview state exactly
+        for (const auto& bb : d->bodyBones) {
+            Ogre::Bone* bone = skel->getBone(bb.boneName);
+            bone->setOrientation(bb.bindLocal);
+            bone->setManuallyControlled(bb.wasManuallyControlled);
+        }
+        skel->_notifyManualBonesDirty();
+    }
+    if (auto* states = entity->getAllAnimationStates()) {
+        for (const QString& name : d->savedEnabledAnimations) {
+            const std::string n = name.toStdString();
+            if (states->hasAnimationState(n))
+                states->getAnimationState(n)->setEnabled(true);
+        }
+    }
+}
+
+void MocapController::stopPreview()
+{
+    if (d->state == Idle)
+        return;
+    if (d->state == Recording)
+        stopRecording();  // commit the take rather than dropping it
+
+    if (d->camera)
+        d->camera->stop();
+    if (d->workerThread.isRunning()) {
+        d->workerThread.quit();
+        // Block until the worker thread has actually exited before we free
+        // anything it touches — the worker drains d->camera->mailbox() inside
+        // processPending(), so releasing the camera (and its mailbox) while
+        // the thread is still running is a use-after-free. A single wait(2000)
+        // could time out mid-inference and fall through; keep waiting (a long
+        // ONNX step is finite) and log if it's pathologically slow.
+        int waited = 0;
+        while (!d->workerThread.wait(2000)) {
+            waited += 2000;
+            SentryReporter::addBreadcrumb("ai.assist.mocap_live",
+                QStringLiteral("preview stop: worker still running after %1ms")
+                    .arg(waited));
+        }
+    }
+    d->worker = nullptr;  // deleted via QThread::finished
+    d->camera.reset();
+    d->injectedSource = nullptr;
+    d->bodyRetargeter.reset();
+
+    restoreEntityState();
+
+    d->state = Idle;
+    d->faceDetected = false;
+    d->liveFps = 0;
+    d->previewDataUrl.clear();
+    emit stateChanged();
+    emit liveStatsChanged();
+    emit previewChanged();
+    if (d->status.isEmpty() || d->status.startsWith(tr("Live")))
+        setStatusMessage(tr("Preview stopped."));
+    SentryReporter::addBreadcrumb("ai.assist.mocap_live", "preview stop");
+}
+
+#include "MocapController.moc"
+
+#endif  // ENABLE_MOCAP
diff --git a/src/Mocap/MocapController.h b/src/Mocap/MocapController.h
new file mode 100644
index 000000000..a93dbdaab
--- /dev/null
+++ b/src/Mocap/MocapController.h
@@ -0,0 +1,185 @@
+#ifndef MOCAPCONTROLLER_H
+#define MOCAPCONTROLLER_H
+
+// Live performance-capture controller (epic #869, Slice F #875) — the
+// QML_SINGLETON behind the Animation-Mode "Performance Capture" Inspector
+// section: camera preview, live drive of the selected entity's morph weights
+// + Head bone, and Record writing an ordinary undoable clip.
+//
+// Threading (the MeshGenController pattern): CameraFrameSource lives on the
+// main thread (Qt Multimedia), frames land in its latest-wins FrameMailbox;
+// a dedicated worker thread drains the mailbox through FaceCapPredictor and
+// emits FaceSamples QUEUED back to the main thread, where ALL Ogre mutation
+// happens. Never BlockingQueuedConnection (the MCP rule applies everywhere).
+//
+// Live drive is preview-only state: entering preview snapshots the mapped
+// morph weights and the Head bone's {manuallyControlled, orientation} plus
+// which AnimationStates were enabled (they are disabled during preview so
+// they don't fight the manual bone); leaving preview restores everything
+// exactly — the UvUnwrap GUI-safe-restore discipline.
+//
+// Recording buffers samples in memory; stopRecording() runs the take through
+// MocapRecorder via ONE RecordMocapClipCommand (Ctrl+Z discards the take).
+// Face-only live drive in this slice; body capture stays offline (CLI/MCP).
+
+#include <QObject>
+#include <QQmlEngine>
+#include <QStringList>
+#include <QVariantList>
+
+#ifdef ENABLE_MOCAP
+#include "FaceCapMapper.h"
+#include "FaceCapPredictor.h"
+#include <vector>
+#endif
+
+#include <memory>
+
+class QJSEngine;
+
+class MocapController : public QObject
+{
+    Q_OBJECT
+    QML_ELEMENT
+    QML_SINGLETON
+
+    Q_PROPERTY(bool available READ available CONSTANT)
+    Q_PROPERTY(QString unavailableReason READ unavailableReason CONSTANT)
+    Q_PROPERTY(int state READ state NOTIFY stateChanged)
+    Q_PROPERTY(QVariantList availableDevices READ availableDevices
+               NOTIFY devicesChanged)
+    Q_PROPERTY(bool faceDetected READ faceDetected NOTIFY liveStatsChanged)
+    Q_PROPERTY(double liveFps READ liveFps NOTIFY liveStatsChanged)
+    Q_PROPERTY(double recordingSeconds READ recordingSeconds NOTIFY liveStatsChanged)
+    Q_PROPERTY(int sampleCount READ sampleCount NOTIFY liveStatsChanged)
+    Q_PROPERTY(QString previewDataUrl READ previewDataUrl NOTIFY previewChanged)
+    Q_PROPERTY(QString statusMessage READ statusMessage NOTIFY statusChanged)
+    Q_PROPERTY(int matchedChannelCount READ matchedChannelCount
+               NOTIFY mappingChanged)
+    Q_PROPERTY(QStringList unmatchedChannels READ unmatchedChannels
+               NOTIFY mappingChanged)
+    Q_PROPERTY(bool headAvailable READ headAvailable NOTIFY mappingChanged)
+    // body: only offerable when the selection is a humanoid rig
+    Q_PROPERTY(bool bodyAvailable READ bodyAvailable NOTIFY mappingChanged)
+    Q_PROPERTY(bool bodyDetected READ bodyDetected NOTIFY liveStatsChanged)
+    // channel enables (writable from the QML Face/Head/Body checkboxes)
+    Q_PROPERTY(bool faceEnabled READ faceEnabled WRITE setFaceEnabled
+               NOTIFY channelsChanged)
+    Q_PROPERTY(bool headEnabled READ headEnabled WRITE setHeadEnabled
+               NOTIFY channelsChanged)
+    Q_PROPERTY(bool bodyEnabled READ bodyEnabled WRITE setBodyEnabled
+               NOTIFY channelsChanged)
+    Q_PROPERTY(QString clipName READ clipName WRITE setClipName
+               NOTIFY clipNameChanged)
+    Q_PROPERTY(double smoothingCutoff READ smoothingCutoff
+               WRITE setSmoothingCutoff NOTIFY smoothingChanged)
+
+public:
+    enum State { Idle = 0, CameraStarting, Previewing, Recording };
+    Q_ENUM(State)
+
+    static MocapController* instance();
+    static MocapController* qmlInstance(QQmlEngine* engine, QJSEngine* scriptEngine);
+    static void kill();
+
+    bool available() const;
+    QString unavailableReason() const;
+    int state() const;
+    QVariantList availableDevices() const;   // [{id, description}]
+    bool faceDetected() const;
+    double liveFps() const;
+    double recordingSeconds() const;
+    int sampleCount() const;
+    QString previewDataUrl() const;
+    QString statusMessage() const;
+    int matchedChannelCount() const;
+    QStringList unmatchedChannels() const;
+    bool headAvailable() const;
+    bool bodyAvailable() const;
+    bool bodyDetected() const;
+    bool faceEnabled() const;
+    void setFaceEnabled(bool on);
+    bool headEnabled() const;
+    void setHeadEnabled(bool on);
+    bool bodyEnabled() const;
+    void setBodyEnabled(bool on);
+    QString clipName() const;
+    void setClipName(const QString& name);
+    double smoothingCutoff() const;
+    void setSmoothingCutoff(double hz);
+
+    Q_INVOKABLE void refreshDevices();
+    // Start the camera + live drive of the SELECTED entity. Empty deviceId =
+    // default camera.
+    Q_INVOKABLE bool startPreview(const QString& deviceId = {});
+    // Start live drive from a VIDEO FILE instead of the camera — the path for
+    // macOS where camera access is blocked/unavailable. No permission prompt;
+    // playback-driven at real time (frames dropped latest-wins, same as the
+    // webcam preview — recording re-runs the full clip). filePath is a local
+    // file path (not a URL).
+    Q_INVOKABLE bool startPreviewFromVideo(const QString& filePath);
+    // Native open-file dialog filtered to video files; returns the chosen
+    // local path or "" if cancelled. Convenience for the GUI "Load Video…"
+    // button (the codebase's C++-side dialog convention).
+    Q_INVOKABLE QString openVideoDialog();
+    Q_INVOKABLE void stopPreview();
+    Q_INVOKABLE bool startRecording();
+    Q_INVOKABLE void stopRecording();
+    // Re-base the head-pose neutral on the current sample ("hold a neutral
+    // face"). Auto-applied on the first confident sample of a preview.
+    Q_INVOKABLE void calibrateNeutral();
+
+#ifdef ENABLE_MOCAP
+    // Test seam: enter Previewing without a camera/worker (no camera in CI).
+    // Ownership stays with the caller; feed samples through onSample().
+    bool startPreviewWithSource(class VideoFrameSource* source);
+    // Receives one predicted sample on the MAIN thread (queued from the
+    // inference worker in live mode; called directly by tests). The
+    // face-only overload forwards with no body frame.
+    void onSample(const FaceSample& sample, const QImage& preview);
+    void onSample(const FaceSample& sample, const struct BodyLiveFrame& body,
+                  const QImage& preview);
+#endif
+
+signals:
+    void stateChanged();
+    void devicesChanged();
+    void liveStatsChanged();
+    void previewChanged();
+    void statusChanged();
+    void mappingChanged();
+    void channelsChanged();
+    void clipNameChanged();
+    void smoothingChanged();
+    void errorOccurred(const QString& message);
+
+private:
+    explicit MocapController(QObject* parent = nullptr);
+    ~MocapController() override;
+
+#ifdef ENABLE_MOCAP
+    // startPreview() gates on camera permission (async on first run), then
+    // hands off here once granted.
+    bool beginPreview(const QString& deviceId);
+    // Shared live-preview runner: drivability check, model download, worker
+    // thread + connections, all driven by `source` (a webcam or a video file).
+    // Takes ownership of `source`. `startingMessage` is the status shown while
+    // the source spins up. Returns false (and restores state) on any failure.
+    bool beginPreviewWithLiveSource(std::unique_ptr<class VideoFrameSource> source,
+                                    const QString& startingMessage);
+    // Inspect the currently-selected entity and (re)build the face mapping,
+    // head bone, and body-rig role set — so matchedChannelCount / headAvailable
+    // / bodyAvailable reflect the selection BEFORE a preview runs (the channel
+    // checkboxes gate on them). Called on selectionChanged and at construction;
+    // beginPreviewWithLiveSource also calls it. No-op / clears when nothing
+    // suitable is selected. Never touches live-session state.
+    void refreshMappingForSelection();
+    void restoreEntityState();
+    void setStatusMessage(const QString& message);
+#endif
+
+    struct Impl;
+    std::unique_ptr<Impl> d;
+};
+
+#endif  // MOCAPCONTROLLER_H
diff --git a/src/Mocap/MocapController_test.cpp b/src/Mocap/MocapController_test.cpp
new file mode 100644
index 000000000..0846d99b9
--- /dev/null
+++ b/src/Mocap/MocapController_test.cpp
@@ -0,0 +1,176 @@
+#ifdef ENABLE_MOCAP
+
+#include <gtest/gtest.h>
+
+#include "Manager.h"
+#include "MorphAnimationManager.h"
+#include "SelectionSet.h"
+#include "TestHelpers.h"
+#include "UndoManager.h"
+
+#include "Mocap/MocapController.h"
+#include "Mocap/MocapRecorder.h"
+
+#include <OgreAnimation.h>
+#include <OgreEntity.h>
+#include <OgreHardwareBufferManager.h>
+#include <OgreMesh.h>
+#include <OgreMeshManager.h>
+#include <OgrePose.h>
+#include <OgreSceneManager.h>
+#include <OgreSceneNode.h>
+#include <OgreSubMesh.h>
+
+namespace {
+
+// same recipe as MocapRecorder_test — a tiny mesh with two ARKit targets
+Ogre::MeshPtr createFaceTestMesh(const std::string& name)
+{
+    auto mesh = Ogre::MeshManager::getSingleton().createManual(
+        name, Ogre::ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME);
+    auto* sub = mesh->createSubMesh();
+    sub->useSharedVertices = false;
+    sub->vertexData = new Ogre::VertexData();
+    sub->vertexData->vertexDeclaration->addElement(0, 0, Ogre::VET_FLOAT3,
+                                                   Ogre::VES_POSITION);
+    auto vbuf = Ogre::HardwareBufferManager::getSingleton().createVertexBuffer(
+        sub->vertexData->vertexDeclaration->getVertexSize(0), 3,
+        Ogre::HardwareBuffer::HBU_STATIC_WRITE_ONLY);
+    float verts[] = {0, 0, 0, 1, 0, 0, 0, 1, 0};
+    vbuf->writeData(0, sizeof(verts), verts);
+    sub->vertexData->vertexBufferBinding->setBinding(0, vbuf);
+    sub->vertexData->vertexCount = 3;
+    auto ibuf = Ogre::HardwareBufferManager::getSingleton().createIndexBuffer(
+        Ogre::HardwareIndexBuffer::IT_16BIT, 3,
+        Ogre::HardwareBuffer::HBU_STATIC_WRITE_ONLY);
+    uint16_t idx[] = {0, 1, 2};
+    ibuf->writeData(0, sizeof(idx), idx);
+    sub->indexData->indexBuffer = ibuf;
+    sub->indexData->indexCount = 3;
+    mesh->_setBounds(Ogre::AxisAlignedBox(-1, -1, -1, 2, 2, 2));
+    mesh->_setBoundingSphereRadius(2.0f);
+    mesh->load();
+    {
+        Ogre::Pose* p = mesh->createPose(1, "jawOpen");
+        p->addVertex(0, Ogre::Vector3(0, -0.1f, 0));
+    }
+    {
+        Ogre::Pose* p = mesh->createPose(1, "mouthSmileLeft");
+        p->addVertex(1, Ogre::Vector3(0.05f, 0.02f, 0));
+    }
+    const auto& poses = mesh->getPoseList();
+    for (unsigned short pi = 0; pi < poses.size(); ++pi) {
+        Ogre::Animation* a = mesh->createAnimation(poses[pi]->getName(), 0.0f);
+        auto* track = a->createVertexTrack(poses[pi]->getTarget(), Ogre::VAT_POSE);
+        track->createVertexPoseKeyFrame(0.0f)->addPoseReference(pi, 1.0f);
+    }
+    return mesh;
+}
+
+FaceSample sample(double t, float jaw, float conf = 1.f)
+{
+    FaceSample s;
+    s.timeSec = t;
+    s.confidence = conf;
+    s.weights[25] = jaw;  // jawOpen
+    return s;
+}
+
+class MocapControllerTest : public ::testing::Test
+{
+protected:
+    void SetUp() override
+    {
+        ASSERT_TRUE(tryInitOgre()) << "Ogre init failed (Xvfb/GL required in CI)";
+        static int counter = 0;
+        m_meshName = "mocap_ctrl_test_" + std::to_string(counter++);
+        m_mesh = createFaceTestMesh(m_meshName);
+        auto* scene = Manager::getSingleton()->getSceneMgr();
+        m_entity = scene->createEntity(m_meshName + "_ent", m_meshName);
+        m_node = scene->getRootSceneNode()->createChildSceneNode();
+        m_node->attachObject(m_entity);
+        SelectionSet::getSingleton()->clearList();
+        SelectionSet::getSingleton()->append(m_entity);
+    }
+
+    void TearDown() override
+    {
+        MocapController::instance()->stopPreview();
+        SelectionSet::getSingleton()->clearList();
+        if (m_entity) {
+            m_node->detachObject(m_entity);
+            Manager::getSingleton()->getSceneMgr()->destroyEntity(m_entity);
+        }
+        Ogre::MeshManager::getSingleton().remove(
+            m_meshName, Ogre::ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME);
+    }
+
+    std::string m_meshName;
+    Ogre::MeshPtr m_mesh;
+    Ogre::Entity* m_entity = nullptr;
+    Ogre::SceneNode* m_node = nullptr;
+};
+
+}  // namespace
+
+TEST_F(MocapControllerTest, PreviewDrivesWeightsAndRestoresOnStop)
+{
+    auto* c = MocapController::instance();
+    auto* morph = MorphAnimationManager::instance();
+    morph->setWeight(m_entity, QStringLiteral("jawOpen"), 0.33f);
+
+    ASSERT_TRUE(c->startPreviewWithSource(nullptr));  // any non-null seam token
+    EXPECT_EQ(c->state(), MocapController::Previewing);
+    EXPECT_EQ(c->matchedChannelCount(), 2);
+
+    c->onSample(sample(0.0, 0.9f), QImage());
+    EXPECT_NEAR(morph->weight(m_entity, QStringLiteral("jawOpen")), 0.9f, 1e-4);
+
+    c->stopPreview();
+    EXPECT_EQ(c->state(), MocapController::Idle);
+    // the pre-preview weight came back exactly
+    EXPECT_NEAR(morph->weight(m_entity, QStringLiteral("jawOpen")), 0.33f, 1e-4);
+}
+
+TEST_F(MocapControllerTest, RecordProducesUndoableClip)
+{
+    auto* c = MocapController::instance();
+    ASSERT_TRUE(c->startPreviewWithSource(nullptr));
+    c->onSample(sample(0.0, 0.1f), QImage());
+
+    ASSERT_TRUE(c->startRecording());
+    EXPECT_EQ(c->state(), MocapController::Recording);
+    c->onSample(sample(0.1, 0.2f), QImage());
+    c->onSample(sample(0.2, 0.8f), QImage());
+    c->onSample(sample(0.3, 0.4f), QImage());
+    c->stopRecording();
+    EXPECT_EQ(c->state(), MocapController::Previewing);
+    c->stopPreview();
+
+    EXPECT_TRUE(m_mesh->hasAnimation("FaceCap"));
+    UndoManager::getSingleton()->undo();  // ONE undo removes the whole take
+    EXPECT_FALSE(m_mesh->hasAnimation("FaceCap"));
+}
+
+TEST_F(MocapControllerTest, StopDuringRecordingCommitsTheTake)
+{
+    auto* c = MocapController::instance();
+    ASSERT_TRUE(c->startPreviewWithSource(nullptr));
+    ASSERT_TRUE(c->startRecording());
+    c->onSample(sample(0.0, 0.2f), QImage());
+    c->onSample(sample(0.2, 0.7f), QImage());
+    c->stopPreview();  // stop while recording
+    EXPECT_EQ(c->state(), MocapController::Idle);
+    EXPECT_TRUE(m_mesh->hasAnimation("FaceCap"));
+    UndoManager::getSingleton()->undo();
+}
+
+TEST_F(MocapControllerTest, NoSelectionRefusesPreview)
+{
+    SelectionSet::getSingleton()->clearList();
+    auto* c = MocapController::instance();
+    EXPECT_FALSE(c->startPreviewWithSource(nullptr));
+    EXPECT_EQ(c->state(), MocapController::Idle);
+}
+
+#endif  // ENABLE_MOCAP
diff --git a/src/Mocap/MocapRecorder.cpp b/src/Mocap/MocapRecorder.cpp
new file mode 100644
index 000000000..cc7387f4f
--- /dev/null
+++ b/src/Mocap/MocapRecorder.cpp
@@ -0,0 +1,418 @@
+#ifdef ENABLE_MOCAP
+
+#include "MocapRecorder.h"
+
+#include "FaceCapCanonicalData.h"
+#include "../AnimationMerger.h"
+#include "PoseIKSolver.h"
+#include "../Manager.h"
+#include "../MorphAnimationManager.h"
+#include "../MotionInbetween.h"
+#include "../NodeAnimationManager.h"
+#include "../SentryReporter.h"
+
+#include <OgreAnimation.h>
+#include <OgreBone.h>
+#include <OgreEntity.h>
+#include <OgreKeyFrame.h>
+#include <OgreMesh.h>
+#include <OgreSceneNode.h>
+#include <OgreSkeletonInstance.h>
+
+#include <algorithm>
+#include <map>
+#include <cmath>
+
+namespace MocapRecorder {
+
+namespace {
+
+constexpr int kHeadCanonicalRole = 5;  // MotionInbetween's canonical Head
+
+Ogre::Quaternion toOgre(const std::array<float, 4>& q)  // (x,y,z,w)
+{
+    return Ogre::Quaternion(q[3], q[0], q[1], q[2]);
+}
+
+double quatAngle(const Ogre::Quaternion& a, const Ogre::Quaternion& b)
+{
+    const double dot = std::abs(a.Dot(b));
+    return 2.0 * std::acos(std::min(1.0, dot));
+}
+
+// Key-time selection with epsilon run-length suppression + gap holds, shared
+// by the weight channels and the head track. `values` is any channel the
+// caller can measure a distance on (via `distance(i, j)` between samples).
+template <typename DistanceFn>
+std::vector<int> selectKeyIndices(const std::vector<int>& confident,
+                                  const std::vector<double>& times,
+                                  double gapHoldSeconds, double epsilon,
+                                  DistanceFn distance)
+{
+    std::vector<int> keys;
+    if (confident.empty())
+        return keys;
+    int lastWritten = confident.front();
+    keys.push_back(lastWritten);
+    for (size_t k = 1; k < confident.size(); ++k) {
+        const int i = confident[k];
+        const int prev = confident[k - 1];
+        const bool isLast = (k == confident.size() - 1);
+        // gap edges: hold the old value up to the gap, land the new value at
+        // its end, regardless of epsilon
+        const bool gapEdge =
+            (times[i] - times[prev]) > gapHoldSeconds;
+        if (gapEdge && keys.back() != prev)
+            keys.push_back(prev);
+        const bool moved = distance(i, lastWritten) >= epsilon;
+        // anchor the frame BEFORE a jump so interpolation doesn't start early
+        const bool nextJumps =
+            !isLast && distance(confident[k + 1], i) >= epsilon;
+        if (moved || nextJumps || isLast || gapEdge) {
+            keys.push_back(i);
+            lastWritten = i;
+        }
+    }
+    return keys;
+}
+
+}  // namespace
+
+QString resolveHeadBone(Ogre::Entity* entity)
+{
+    if (!entity || !entity->hasSkeleton())
+        return {};
+    Ogre::SkeletonInstance* skel = entity->getSkeleton();
+    for (unsigned short i = 0; i < skel->getNumBones(); ++i) {
+        Ogre::Bone* bone = skel->getBone(i);
+        if (MotionInbetween::canonicalIndexForBone(
+                QString::fromStdString(bone->getName())) == kHeadCanonicalRole)
+            return QString::fromStdString(bone->getName());
+    }
+    return {};
+}
+
+FaceRecordReport recordFace(Ogre::Entity* entity,
+                            const std::vector<FaceSample>& samples,
+                            const FaceCapMapper::Mapping& mapping,
+                            const FaceRecordOptions& options)
+{
+    FaceRecordReport report;
+    report.clipName = options.clipName;
+    report.unmatchedCanonical = mapping.unmatchedCanonical;
+    report.unmatchedMesh = mapping.unmatchedMesh;
+    for (const auto& ch : mapping.channels)
+        report.matchedChannels
+            << QString::fromLatin1(FaceCap::kBlendshapeNames[ch.canonicalIndex]);
+
+    if (!entity) {
+        report.error = QStringLiteral("no entity");
+        return report;
+    }
+    if (options.clipName.isEmpty()) {
+        report.error = QStringLiteral("empty clip name");
+        return report;
+    }
+    if (mapping.channels.isEmpty() && !options.head) {
+        report.error = QStringLiteral("nothing to record: no mapped morph "
+                                      "channels and head recording disabled");
+        return report;
+    }
+
+    report.framesProcessed = static_cast<int>(samples.size());
+    std::vector<int> confident;
+    confident.reserve(samples.size());
+    for (size_t i = 0; i < samples.size(); ++i) {
+        if (samples[i].confidence > 0.f)
+            confident.push_back(static_cast<int>(i));
+    }
+    report.framesNoFace = report.framesProcessed
+                          - static_cast<int>(confident.size());
+    if (confident.empty()) {
+        report.error = QStringLiteral("no confident face frame in the take");
+        return report;
+    }
+
+    const double t0 = samples[confident.front()].timeSec;
+    std::vector<double> times(samples.size(), 0.0);
+    for (size_t i = 0; i < samples.size(); ++i)
+        times[i] = samples[i].timeSec - t0;
+
+    Ogre::MeshPtr mesh = entity->getMesh();
+
+    // --- morph weight channels ------------------------------------------------
+    if (!mapping.channels.isEmpty() && mesh) {
+        if (options.replaceExisting
+            && mesh->hasAnimation(options.clipName.toStdString()))
+            mesh->removeAnimation(options.clipName.toStdString());
+
+        const std::string clip = options.clipName.toStdString();
+        for (const auto& ch : mapping.channels) {
+            const int ci = ch.canonicalIndex;
+            auto weightAt = [&](int i) {
+                return static_cast<double>(samples[i].weights[ci]);
+            };
+            const std::vector<int> keys = selectKeyIndices(
+                confident, times, options.gapHoldSeconds, options.weightEpsilon,
+                [&](int i, int j) { return std::abs(weightAt(i) - weightAt(j)); });
+            const std::string target = ch.meshTargetName.toStdString();
+            for (int i : keys) {
+                if (MorphAnimationManager::writeWeightKeyOn(
+                        entity, clip, target, static_cast<float>(times[i]),
+                        static_cast<float>(weightAt(i))))
+                    ++report.keyframesWritten;
+            }
+        }
+        if (mesh->hasAnimation(clip))
+            report.clipLength = mesh->getAnimation(clip)->getLength();
+        entity->refreshAvailableAnimationState();
+    }
+
+    // --- head pose --------------------------------------------------------------
+    report.headTarget = QStringLiteral("none");
+    if (options.head) {
+        // calibration: the first confident frame is neutral
+        const Ogre::Quaternion neutral =
+            toOgre(samples[confident.front()].headRotation);
+        auto deltaAt = [&](int i) {
+            // rotation that takes the neutral pose to this frame's pose
+            return toOgre(samples[i].headRotation) * neutral.Inverse();
+        };
+        const std::vector<int> keys = selectKeyIndices(
+            confident, times, options.gapHoldSeconds, options.headEpsilonRad,
+            [&](int i, int j) { return quatAngle(deltaAt(i), deltaAt(j)); });
+        const double length = times[confident.back()];
+
+        const QString headBone = resolveHeadBone(entity);
+        if (!headBone.isEmpty()) {
+            // author on the MESH skeleton (shared, exported); the entity's
+            // SkeletonInstance only mirrors it for playback
+            Ogre::SkeletonPtr skel = entity->getMesh()->getSkeleton();
+            Ogre::Bone* bone = skel->getBone(headBone.toStdString());
+            const std::string clip = (options.clipName
+                                      + QStringLiteral("_Head")).toStdString();
+            const bool exists = skel->hasAnimation(clip);
+            if (exists && options.replaceExisting)
+                skel->removeAnimation(clip);
+            if (!exists || options.replaceExisting) {
+                // Express the camera-frame delta on the bone's local axes:
+                // rel = boneWorldBind^-1 . delta . boneWorldBind, keyed as the
+                // offset Ogre applies onto the binding orientation.
+                const Ogre::Quaternion boneWorld = bone->_getDerivedOrientation();
+                Ogre::Animation* anim = skel->createAnimation(
+                    clip, static_cast<Ogre::Real>(length));
+                Ogre::NodeAnimationTrack* track =
+                    anim->createNodeTrack(bone->getHandle(), bone);
+                for (int i : keys) {
+                    auto* kf = track->createNodeKeyFrame(
+                        static_cast<Ogre::Real>(times[i]));
+                    kf->setRotation(boneWorld.Inverse() * deltaAt(i) * boneWorld);
+                }
+                entity->refreshAvailableAnimationState();
+                report.headKeyframesWritten = static_cast<int>(keys.size());
+                report.headTarget = QStringLiteral("bone:") + headBone;
+            }
+        } else if (entity->getParentSceneNode()
+                   && !entity->getParentSceneNode()->getName().empty()) {
+            // The node-TRS head clip re-finds the node BY NAME through
+            // NodeAnimationManager::addKeyframe, so an anonymous parent node
+            // (empty getName()) can't be driven. Editor-loaded entities always
+            // sit under a named node (Manager::addSceneNode), so this only
+            // guards synthetic/anonymous setups — skip cleanly, leaving
+            // headTarget "none", rather than authoring an orphan clip.
+            Ogre::SceneNode* node = entity->getParentSceneNode();
+            auto* nam = NodeAnimationManager::instance();
+            const QString clip = options.clipName + QStringLiteral("_Head");
+            if (nam) {
+                // Scene-level node clips are NOT snapshotted by
+                // RecordMocapClipCommand's undo (unlike the mesh/skeleton
+                // clips). When NOT replacing, a pre-existing clip of this name
+                // must not be clobbered — undoing would lose it permanently;
+                // reject with a clear headError. When replaceExisting is set
+                // (the recorder's default contract, same as the mesh/skeleton
+                // clips above), overwrite our own <clip>_Head — the GUI undo
+                // path (RecordMocapClipCommand) owns delete-on-undo for the
+                // clip it created.
+                const bool collides = nam->listClips().contains(clip);
+                if (collides && !options.replaceExisting) {
+                    report.headError = QStringLiteral(
+                        "a node animation named '%1' already exists; head "
+                        "capture will not overwrite it — record under a "
+                        "different clip name, or pass replace").arg(clip);
+                    nam = nullptr;  // skip the write below
+                }
+                if (collides && options.replaceExisting)
+                    nam->deleteClip(clip);
+                // Clip length padded strictly beyond the last key time:
+                // NodeAnimationManager::addKeyframe rejects `time > getLength()`
+                // (MorphAnimationManager auto-extends instead), so a key sitting
+                // at exactly `length` can be dropped by the double→float
+                // round-trip. Harmless (clip is fractionally longer).
+                const double clipLen = std::max(length, 0.001) + 1e-3;
+                const bool created = nam && nam->createClip(clip, clipLen);
+                if (created) {
+                    const QString nodeName = QString::fromStdString(node->getName());
+                    int written = 0;
+                    for (int i : keys) {
+                        if (nam->addKeyframe(clip, nodeName, times[i],
+                                             Ogre::Vector3::ZERO, deltaAt(i),
+                                             Ogre::Vector3::UNIT_SCALE))
+                            ++written;
+                    }
+                    report.headKeyframesWritten = written;
+                    // Only claim the node target if keys actually landed, so the
+                    // report never says "node" with an empty clip.
+                    if (written > 0)
+                        report.headTarget = QStringLiteral("node");
+                    else if (report.headError.isEmpty())
+                        report.headError = QStringLiteral(
+                            "node head clip '%1' created but 0/%2 keyframes "
+                            "written (node '%3' addKeyframe rejected)")
+                            .arg(clip).arg(static_cast<int>(keys.size()))
+                            .arg(QString::fromStdString(node->getName()));
+                } else if (nam && report.headError.isEmpty()) {
+                    report.headError = QStringLiteral(
+                        "node head clip '%1' createClip failed (scene animation "
+                        "of that name already exists?)").arg(clip);
+                }
+            }
+        }
+    }
+    if (report.clipLength <= 0.0)
+        report.clipLength = times[confident.back()];
+
+    SentryReporter::addBreadcrumb(
+        "ai.assist.mocap_face",
+        QStringLiteral("recorded '%1': %2 frames (%3 no-face), %4 weight keys, "
+                       "%5 head keys (%6)")
+            .arg(options.clipName)
+            .arg(report.framesProcessed)
+            .arg(report.framesNoFace)
+            .arg(report.keyframesWritten)
+            .arg(report.headKeyframesWritten)
+            .arg(report.headTarget));
+    return report;
+}
+
+BodyRecordReport recordBody(
+    Ogre::Entity* entity,
+    const std::vector<std::vector<std::array<float, 4>>>& clipQuats, int fps,
+    const BodyRecordOptions& options)
+{
+    BodyRecordReport report;
+    report.clipName = options.clipName;
+    report.algorithmUsed = options.algorithmUsed;
+    report.fallbackReason = options.fallbackReason;
+    report.framesProcessed = static_cast<int>(clipQuats.size());
+
+    if (!entity) {
+        report.error = QStringLiteral("no entity");
+        return report;
+    }
+    if (!entity->hasSkeleton() || !entity->getMesh()
+        || !entity->getMesh()->getSkeleton()) {
+        report.error = QStringLiteral(
+            "the mesh is not skinned — body capture retargets onto a humanoid "
+            "skeleton (rig one first: qtmesh rig --skeleton humanoid --skin)");
+        return report;
+    }
+    if (clipQuats.size() < 2 || fps <= 0) {
+        report.error = QStringLiteral("need at least 2 pose frames");
+        return report;
+    }
+
+    Ogre::SkeletonPtr skel = entity->getMesh()->getSkeleton();
+    const std::string clip = options.clipName.toStdString();
+    if (skel->hasAnimation(clip) && !options.replaceExisting) {
+        report.error = QStringLiteral(
+            "animation '%1' already exists (pass replace)").arg(options.clipName);
+        return report;
+    }
+    // NOTE: do NOT removeAnimation(clip) here. applyMotionClip below replaces
+    // the clip on SUCCESS but returns early (clip untouched) when the skeleton
+    // can't be retargeted — removing it up front would destroy the user's
+    // existing clip on a retarget failure. The replace is deferred to the
+    // moment the take is known good.
+
+    // VALIDATION HARNESS (QTMESH_MOCAP_USE_RETARGETER=1): bake the clip with
+    // the SHARED BodyRetargeter — the EXACT math the LIVE preview runs — so a
+    // rendered clip validates the live path headlessly (the live drive can't
+    // be render-captured directly). Default path stays applyMotionClip.
+    if (qEnvironmentVariableIntValue("QTMESH_MOCAP_USE_RETARGETER")) {
+        BodyRetargeter rt(skel.get());
+        if (!rt.valid()) {
+            report.error = QStringLiteral("retargeter: not a humanoid rig");
+            return report;
+        }
+        if (skel->hasAnimation(clip)) skel->removeAnimation(clip);
+        skel->reset(true);  // bind pose
+        std::map<unsigned short, Ogre::Quaternion> bindLocal;
+        for (unsigned short i = 0; i < skel->getNumBones(); ++i)
+            bindLocal[i] = skel->getBone(i)->getOrientation();
+        const double dt = 1.0 / static_cast<double>(fps);
+        Ogre::Animation* anim = skel->createAnimation(
+            clip, static_cast<Ogre::Real>(dt * (clipQuats.size() - 1)));
+        anim->setRotationInterpolationMode(Ogre::Animation::RIM_LINEAR);
+        std::map<unsigned short, Ogre::NodeAnimationTrack*> tracks;
+        for (size_t f = 0; f < clipQuats.size(); ++f) {
+            std::array<std::array<float, 4>, 22> q{};
+            for (int r = 0; r < 22 && r < PoseIK::kCanonicalRoles; ++r) q[r] = clipQuats[f][r];
+            const auto locals = rt.evaluateFrame(q, 0xFFFFFFFFu);
+            for (const auto& [handle, local] : locals) {
+                auto it = tracks.find(handle);
+                if (it == tracks.end())
+                    it = tracks.emplace(handle,
+                        anim->createNodeTrack(handle, skel->getBone(handle))).first;
+                auto* kf = it->second->createNodeKeyFrame(
+                    static_cast<Ogre::Real>(dt * f));
+                // NodeAnimationTrack::applyToNode ACCUMULATES the keyframe onto
+                // the reset/bind pose (node->rotate(kf)), so a keyframe is a
+                // RELATIVE rotation. evaluateFrame returns the ABSOLUTE local
+                // the live setOrientation() path wants, so convert to relative
+                // for the baked clip: kf = bindLocal⁻¹ · absoluteLocal. This
+                // makes the baked render reproduce EXACTLY what the live drive
+                // shows (both end at the same final local orientation).
+                kf->setRotation(bindLocal[handle].Inverse() * local);
+            }
+        }
+        report.tracksWritten = static_cast<int>(tracks.size());
+        report.rolesResolved = static_cast<int>(tracks.size());
+        report.clipLength = anim->getLength();
+        entity->refreshAvailableAnimationState();
+        SentryReporter::addBreadcrumb("ai.assist.mocap_body",
+            QStringLiteral("recorded via BodyRetargeter (validation)"));
+        return report;
+    }
+
+    // The world-frame retarget: delta vs frame 0 (the calibration frame)
+    // transported into each bone's parent-world frame; rotation-only keys;
+    // root locked (the #411 machinery — not a new retargeter).
+    const bool yaw180 = AnimationMerger::detectBackwardFacing(entity);
+    const auto res = AnimationMerger::applyMotionClip(
+        skel.get(), clip, clipQuats, fps,
+        /*worldFrame=*/true, /*cmuRestWorld=*/{},
+        /*refineWithModel=*/false, /*refineStride=*/8, yaw180);
+    if (!res.ok) {
+        report.error = res.error.isEmpty()
+                           ? QStringLiteral("retarget failed")
+                           : res.error;
+        return report;
+    }
+    report.rolesResolved = res.canonicalJoints;
+    report.tracksWritten = res.tracksWritten;
+    report.clipLength = res.length;
+    entity->refreshAvailableAnimationState();
+
+    SentryReporter::addBreadcrumb(
+        "ai.assist.mocap_body",
+        QStringLiteral("recorded '%1' via %2: %3 frames, %4 roles, %5 tracks")
+            .arg(options.clipName, options.algorithmUsed)
+            .arg(report.framesProcessed)
+            .arg(report.rolesResolved)
+            .arg(report.tracksWritten));
+    return report;
+}
+
+}  // namespace MocapRecorder
+
+#endif  // ENABLE_MOCAP
diff --git a/src/Mocap/MocapRecorder.h b/src/Mocap/MocapRecorder.h
new file mode 100644
index 000000000..eaf6664d4
--- /dev/null
+++ b/src/Mocap/MocapRecorder.h
@@ -0,0 +1,116 @@
+#ifndef MOCAPRECORDER_H
+#define MOCAPRECORDER_H
+
+// Turns a FaceSample stream into ordinary animation clips (epic #869,
+// Slice D #873) — the only Ogre-touching mocap piece so far.
+//
+//  - Morph weights land as weight keyframes on a named mesh VAT_POSE clip via
+//    MorphAnimationManager::writeWeightKeyOn (the #519 pipeline: dope sheet,
+//    timeline playback and glTF morph-weight export all work downstream).
+//    Epsilon run-length suppression keeps near-constant channels from writing
+//    30 keys/sec; first/last confident samples always key; frames with
+//    confidence 0 write nothing, and gaps > 0.5 s get hold keys at both edges
+//    so interpolation doesn't sweep through them.
+//  - Head pose (camera-relative) is re-based on the take's FIRST confident
+//    sample (the calibration frame: looking at the camera at start == rig
+//    neutral) and keyed as rotation deltas on the Head bone (skinned mesh,
+//    resolved via MotionInbetween::canonicalIndexForBone) in a skeletal clip
+//    named "<clipName>_Head", or as node-TRS deltas via NodeAnimationManager
+//    for a static mesh.
+//
+// Smoothing is the CALLER's job (One-Euro over the stream before recording);
+// the recorder stores what it is given. GUI/MCP wrap a take in ONE
+// RecordMocapClipCommand (src/commands/) so Ctrl+Z removes the whole take.
+
+#ifdef ENABLE_MOCAP
+
+#include "FaceCapMapper.h"
+#include "FaceCapPredictor.h"
+
+#include <QString>
+#include <QStringList>
+
+#include <vector>
+
+namespace Ogre {
+class Entity;
+}
+
+namespace MocapRecorder {
+
+struct FaceRecordOptions {
+    QString clipName = QStringLiteral("FaceCap");  // morph weight clip name
+    bool head = true;                // also record head pose
+    bool replaceExisting = true;     // clip with the same name is replaced
+    double weightEpsilon = 0.01;     // suppress keys that don't change
+    double headEpsilonRad = 0.006;   // ~0.35 deg — head key suppression
+    double gapHoldSeconds = 0.5;     // face-lost gap that forces hold keys
+};
+
+struct FaceRecordReport {
+    int framesProcessed = 0;
+    int framesNoFace = 0;
+    int keyframesWritten = 0;        // morph weight keys
+    int headKeyframesWritten = 0;
+    QStringList matchedChannels;
+    QStringList unmatchedCanonical;
+    QStringList unmatchedMesh;
+    QString headTarget;              // "bone:<name>" | "node" | "none"
+    QString clipName;
+    double clipLength = 0.0;         // seconds
+    QString error;                   // non-empty = nothing was written
+    QString headError;               // non-empty = head clip skipped (e.g. a
+                                     // pre-existing node clip we won't clobber);
+                                     // weight keys still written — not fatal
+
+    bool ok() const { return error.isEmpty(); }
+};
+
+// Writes the take onto `entity`. Samples must be time-ascending; times are
+// re-based so the first confident sample is t=0. Main thread only.
+FaceRecordReport recordFace(Ogre::Entity* entity,
+                            const std::vector<FaceSample>& samples,
+                            const FaceCapMapper::Mapping& mapping,
+                            const FaceRecordOptions& options = {});
+
+// ---- body capture (Slice E #874) -------------------------------------------
+
+struct BodyRecordOptions {
+    QString clipName = QStringLiteral("BodyCap");
+    bool replaceExisting = true;
+    QString algorithmUsed = QStringLiteral("pose-ik");  // for the report
+    QString fallbackReason;                             // why not sam3dbody
+};
+
+struct BodyRecordReport {
+    QString clipName;
+    QString algorithmUsed;
+    QString fallbackReason;
+    int framesProcessed = 0;
+    int rolesResolved = 0;     // distinct canonical roles that landed on bones
+    int tracksWritten = 0;     // skeleton bones keyed
+    double clipLength = 0.0;
+    QString error;
+
+    bool ok() const { return error.isEmpty(); }
+};
+
+// clipQuats: [frame][22 canonical roles] WORLD quats (x,y,z,w) — the
+// PoseIKSolver / SAM3DBody output stream, uniformly sampled at `fps`. Runs
+// AnimationMerger::applyMotionClip's world-frame retarget (delta vs frame 0 =
+// the calibration frame; rotation-only keys; root locked). Requires a skinned
+// entity resolving >= half the canonical roles (the humanoid gate).
+BodyRecordReport recordBody(
+    Ogre::Entity* entity,
+    const std::vector<std::vector<std::array<float, 4>>>& clipQuats, int fps,
+    const BodyRecordOptions& options = {});
+
+// Head-bone resolution (exposed for the GUI gate + tests): the first bone of
+// the entity's skeleton whose name resolves to the canonical Head role, or
+// empty when the entity is not skinned / has no such bone.
+QString resolveHeadBone(Ogre::Entity* entity);
+
+}  // namespace MocapRecorder
+
+#endif  // ENABLE_MOCAP
+#endif  // MOCAPRECORDER_H
diff --git a/src/Mocap/MocapRecorder_test.cpp b/src/Mocap/MocapRecorder_test.cpp
new file mode 100644
index 000000000..c950982f4
--- /dev/null
+++ b/src/Mocap/MocapRecorder_test.cpp
@@ -0,0 +1,314 @@
+#ifdef ENABLE_MOCAP
+
+#include <gtest/gtest.h>
+
+#include "Manager.h"
+#include "TestHelpers.h"
+#include "UndoManager.h"
+#include "commands/RecordMocapClipCommand.h"
+
+#include "Mocap/FaceCapCanonicalData.h"
+#include "Mocap/FaceCapMapper.h"
+#include "Mocap/MocapRecorder.h"
+
+#include <OgreAnimation.h>
+#include <OgreAnimationTrack.h>
+#include <OgreEntity.h>
+#include <OgreHardwareBufferManager.h>
+#include <OgreKeyFrame.h>
+#include <OgreMesh.h>
+#include <OgreMeshManager.h>
+#include <OgrePose.h>
+#include <OgreSceneManager.h>
+#include <OgreSceneNode.h>
+#include <OgreSubMesh.h>
+
+#include <vector>
+
+namespace {
+
+// Tiny mesh with two ARKit-named morph targets (the MorphAnimationManager
+// fixture recipe).
+Ogre::MeshPtr createFaceTestMesh(const std::string& name)
+{
+    auto mesh = Ogre::MeshManager::getSingleton().createManual(
+        name, Ogre::ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME);
+
+    auto* sub = mesh->createSubMesh();
+    sub->useSharedVertices = false;
+    sub->vertexData = new Ogre::VertexData();
+    auto* decl = sub->vertexData->vertexDeclaration;
+    decl->addElement(0, 0, Ogre::VET_FLOAT3, Ogre::VES_POSITION);
+
+    auto vbuf = Ogre::HardwareBufferManager::getSingleton().createVertexBuffer(
+        decl->getVertexSize(0), 3, Ogre::HardwareBuffer::HBU_STATIC_WRITE_ONLY);
+    float verts[] = {0, 0, 0, 1, 0, 0, 0, 1, 0};
+    vbuf->writeData(0, sizeof(verts), verts);
+    sub->vertexData->vertexBufferBinding->setBinding(0, vbuf);
+    sub->vertexData->vertexCount = 3;
+
+    auto ibuf = Ogre::HardwareBufferManager::getSingleton().createIndexBuffer(
+        Ogre::HardwareIndexBuffer::IT_16BIT, 3,
+        Ogre::HardwareBuffer::HBU_STATIC_WRITE_ONLY);
+    uint16_t idx[] = {0, 1, 2};
+    ibuf->writeData(0, sizeof(idx), idx);
+    sub->indexData->indexBuffer = ibuf;
+    sub->indexData->indexCount = 3;
+
+    mesh->_setBounds(Ogre::AxisAlignedBox(-1, -1, -1, 2, 2, 2));
+    mesh->_setBoundingSphereRadius(2.0f);
+    mesh->load();
+
+    {
+        Ogre::Pose* p = mesh->createPose(1, "jawOpen");
+        p->addVertex(0, Ogre::Vector3(0, -0.1f, 0));
+    }
+    {
+        Ogre::Pose* p = mesh->createPose(1, "mouthSmileLeft");
+        p->addVertex(1, Ogre::Vector3(0.05f, 0.02f, 0));
+    }
+    const auto& poses = mesh->getPoseList();
+    for (unsigned short pi = 0; pi < poses.size(); ++pi) {
+        Ogre::Animation* a = mesh->createAnimation(poses[pi]->getName(), 0.0f);
+        auto* track = a->createVertexTrack(poses[pi]->getTarget(), Ogre::VAT_POSE);
+        auto* kf = track->createVertexPoseKeyFrame(0.0f);
+        kf->addPoseReference(pi, 1.0f);
+    }
+    return mesh;
+}
+
+FaceSample makeSample(double t, float jawOpen, float smile,
+                      float confidence = 1.f)
+{
+    FaceSample s;
+    s.timeSec = t;
+    s.confidence = confidence;
+    s.weights[25] = jawOpen;         // jawOpen canonical index
+    s.weights[44] = smile;           // mouthSmileLeft canonical index
+    return s;
+}
+
+// weight of `poseName` at (approx) time t on the recorded clip; -1 if unkeyed
+float weightAt(Ogre::MeshPtr mesh, const std::string& clip,
+               const std::string& poseName, float t)
+{
+    if (!mesh->hasAnimation(clip))
+        return -1.f;
+    int poseIndex = -1;
+    const auto& poses = mesh->getPoseList();
+    for (unsigned short i = 0; i < poses.size(); ++i)
+        if (poses[i]->getName() == poseName) poseIndex = i;
+    if (poseIndex < 0)
+        return -1.f;
+    Ogre::Animation* anim = mesh->getAnimation(clip);
+    for (const auto& [handle, track] : anim->_getVertexTrackList()) {
+        for (unsigned short i = 0; i < track->getNumKeyFrames(); ++i) {
+            auto* kf = static_cast<Ogre::VertexPoseKeyFrame*>(track->getKeyFrame(i));
+            if (std::abs(kf->getTime() - t) > 1e-3f)
+                continue;
+            for (const auto& ref : kf->getPoseReferences())
+                if (ref.poseIndex == poseIndex)
+                    return ref.influence;
+        }
+    }
+    return -1.f;
+}
+
+int keyCountFor(Ogre::MeshPtr mesh, const std::string& clip,
+                const std::string& poseName)
+{
+    if (!mesh->hasAnimation(clip))
+        return 0;
+    int poseIndex = -1;
+    const auto& poses = mesh->getPoseList();
+    for (unsigned short i = 0; i < poses.size(); ++i)
+        if (poses[i]->getName() == poseName) poseIndex = i;
+    int count = 0;
+    Ogre::Animation* anim = mesh->getAnimation(clip);
+    for (const auto& [handle, track] : anim->_getVertexTrackList()) {
+        for (unsigned short i = 0; i < track->getNumKeyFrames(); ++i) {
+            auto* kf = static_cast<Ogre::VertexPoseKeyFrame*>(track->getKeyFrame(i));
+            for (const auto& ref : kf->getPoseReferences())
+                if (ref.poseIndex == poseIndex)
+                    ++count;
+        }
+    }
+    return count;
+}
+
+class MocapRecorderTest : public ::testing::Test
+{
+protected:
+    void SetUp() override
+    {
+        ASSERT_TRUE(tryInitOgre()) << "Ogre init failed (Xvfb/GL required in CI)";
+        static int counter = 0;
+        m_meshName = "mocap_rec_test_" + std::to_string(counter++);
+        m_mesh = createFaceTestMesh(m_meshName);
+        auto* scene = Manager::getSingleton()->getSceneMgr();
+        m_entity = scene->createEntity(m_meshName + "_ent", m_meshName);
+        // Name the node: the editor's Manager::addSceneNode always names its
+        // scene nodes, and the node-TRS head clip re-finds the node BY NAME
+        // through NodeAnimationManager. An anonymous node (empty getName())
+        // can't be re-found, so mirror production and give it a unique name.
+        m_node = scene->getRootSceneNode()->createChildSceneNode(
+            m_meshName + "_node");
+        m_node->attachObject(m_entity);
+        m_mapping = FaceCapMapper::build(
+            {QStringLiteral("jawOpen"), QStringLiteral("mouthSmileLeft")});
+        ASSERT_EQ(m_mapping.channels.size(), 2);
+    }
+
+    void TearDown() override
+    {
+        if (m_entity) {
+            m_node->detachObject(m_entity);
+            Manager::getSingleton()->getSceneMgr()->destroyEntity(m_entity);
+        }
+        Ogre::MeshManager::getSingleton().remove(
+            m_meshName, Ogre::ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME);
+    }
+
+    std::string m_meshName;
+    Ogre::MeshPtr m_mesh;
+    Ogre::Entity* m_entity = nullptr;
+    Ogre::SceneNode* m_node = nullptr;
+    FaceCapMapper::Mapping m_mapping;
+};
+
+}  // namespace
+
+TEST_F(MocapRecorderTest, KeyframesLandAtTimesAndValues)
+{
+    std::vector<FaceSample> samples = {
+        makeSample(10.0, 0.1f, 0.9f),   // times re-base to 0
+        makeSample(10.5, 0.5f, 0.9f),
+        makeSample(11.0, 0.9f, 0.9f),
+    };
+    MocapRecorder::FaceRecordOptions options;
+    options.head = false;
+    const auto report =
+        MocapRecorder::recordFace(m_entity, samples, m_mapping, options);
+    ASSERT_TRUE(report.ok()) << report.error.toStdString();
+    EXPECT_EQ(report.framesProcessed, 3);
+    EXPECT_EQ(report.framesNoFace, 0);
+
+    const std::string clip = "FaceCap";
+    EXPECT_FLOAT_EQ(weightAt(m_mesh, clip, "jawOpen", 0.0f), 0.1f);
+    EXPECT_FLOAT_EQ(weightAt(m_mesh, clip, "jawOpen", 0.5f), 0.5f);
+    EXPECT_FLOAT_EQ(weightAt(m_mesh, clip, "jawOpen", 1.0f), 0.9f);
+    EXPECT_NEAR(report.clipLength, 1.0, 1e-4);
+    // the entity can play it
+    EXPECT_TRUE(m_entity->getAnimationState("FaceCap") != nullptr);
+}
+
+TEST_F(MocapRecorderTest, EpsilonSuppressionKeepsConstantChannelsSparse)
+{
+    std::vector<FaceSample> samples;
+    for (int i = 0; i < 60; ++i)
+        samples.push_back(makeSample(i / 30.0, 0.5f, 0.5f));  // constant
+    MocapRecorder::FaceRecordOptions options;
+    options.head = false;
+    const auto report =
+        MocapRecorder::recordFace(m_entity, samples, m_mapping, options);
+    ASSERT_TRUE(report.ok());
+    EXPECT_LE(keyCountFor(m_mesh, "FaceCap", "jawOpen"), 2);   // first + last
+    EXPECT_LE(report.keyframesWritten, 4);
+}
+
+TEST_F(MocapRecorderTest, GapGetsHoldKeysAtEdges)
+{
+    std::vector<FaceSample> samples;
+    samples.push_back(makeSample(0.0, 0.2f, 0.0f));
+    samples.push_back(makeSample(0.1, 0.2f, 0.0f));
+    // face lost for 1.5 s
+    samples.push_back(makeSample(0.2, 0.0f, 0.0f, /*confidence=*/0.f));
+    samples.push_back(makeSample(1.6, 0.8f, 0.0f));
+    samples.push_back(makeSample(1.7, 0.8f, 0.0f));
+    MocapRecorder::FaceRecordOptions options;
+    options.head = false;
+    const auto report =
+        MocapRecorder::recordFace(m_entity, samples, m_mapping, options);
+    ASSERT_TRUE(report.ok());
+    EXPECT_EQ(report.framesNoFace, 1);
+    // hold key at the gap's leading edge (t=0.1) and landing key at t=1.6
+    EXPECT_FLOAT_EQ(weightAt(m_mesh, "FaceCap", "jawOpen", 0.1f), 0.2f);
+    EXPECT_FLOAT_EQ(weightAt(m_mesh, "FaceCap", "jawOpen", 1.6f), 0.8f);
+}
+
+TEST_F(MocapRecorderTest, NoConfidentFramesFailsCleanly)
+{
+    std::vector<FaceSample> samples = {makeSample(0.0, 0.f, 0.f, 0.f)};
+    const auto report =
+        MocapRecorder::recordFace(m_entity, samples, m_mapping, {});
+    EXPECT_FALSE(report.ok());
+    EXPECT_EQ(m_mesh->hasAnimation("FaceCap"), false);
+}
+
+TEST_F(MocapRecorderTest, UnmatchedChannelsAreReported)
+{
+    const auto mapping =
+        FaceCapMapper::build({QStringLiteral("jawOpen"),
+                              QStringLiteral("SomethingCustom")});
+    std::vector<FaceSample> samples = {makeSample(0.0, 0.3f, 0.f),
+                                       makeSample(1.0, 0.6f, 0.f)};
+    MocapRecorder::FaceRecordOptions options;
+    options.head = false;
+    const auto report =
+        MocapRecorder::recordFace(m_entity, samples, mapping, options);
+    ASSERT_TRUE(report.ok());
+    EXPECT_EQ(report.matchedChannels, QStringList{QStringLiteral("jawOpen")});
+    EXPECT_TRUE(report.unmatchedCanonical.contains(QStringLiteral("mouthSmileLeft")));
+    EXPECT_EQ(report.unmatchedMesh,
+              QStringList{QStringLiteral("SomethingCustom")});
+}
+
+TEST_F(MocapRecorderTest, HeadTargetIsNoneForStaticMeshWithoutNode)
+{
+    // static (skeleton-less) entity: head lands on the node path
+    std::vector<FaceSample> samples = {makeSample(0.0, 0.1f, 0.f),
+                                       makeSample(1.0, 0.9f, 0.f)};
+    samples[1].headRotation = {0.f, 0.2588f, 0.f, 0.9659f};  // 30 deg yaw
+    const auto report =
+        MocapRecorder::recordFace(m_entity, samples, m_mapping, {});
+    ASSERT_TRUE(report.ok());
+    // skeleton-less mesh + a parent node exists -> node-TRS head clip
+    EXPECT_EQ(report.headTarget, QStringLiteral("node"))
+        << "headError=" << report.headError.toStdString()
+        << " parentNode=" << (m_entity->getParentSceneNode()
+               ? m_entity->getParentSceneNode()->getName() : std::string("<null>"));
+    EXPECT_GT(report.headKeyframesWritten, 0)
+        << "headError=" << report.headError.toStdString();
+    EXPECT_TRUE(MocapRecorder::resolveHeadBone(m_entity).isEmpty());
+}
+
+TEST_F(MocapRecorderTest, RecordCommandIsSingleUndoStep)
+{
+    std::vector<FaceSample> take1 = {makeSample(0.0, 0.1f, 0.1f),
+                                     makeSample(1.0, 0.9f, 0.9f)};
+    MocapRecorder::FaceRecordOptions options;
+    options.head = false;
+
+    // pre-existing clip state to restore: record take 0 directly
+    std::vector<FaceSample> take0 = {makeSample(0.0, 0.4f, 0.4f),
+                                     makeSample(0.5, 0.6f, 0.6f)};
+    ASSERT_TRUE(MocapRecorder::recordFace(m_entity, take0, m_mapping, options).ok());
+    ASSERT_FLOAT_EQ(weightAt(m_mesh, "FaceCap", "jawOpen", 0.5f), 0.6f);
+
+    auto* cmd = new RecordMocapClipCommand(m_entity->getName(), take1,
+                                           m_mapping, options);
+    UndoManager::getSingleton()->push(cmd);  // runs redo()
+    ASSERT_TRUE(cmd->report().ok()) << cmd->report().error.toStdString();
+    EXPECT_FLOAT_EQ(weightAt(m_mesh, "FaceCap", "jawOpen", 1.0f), 0.9f);
+    EXPECT_FLOAT_EQ(weightAt(m_mesh, "FaceCap", "jawOpen", 0.5f), -1.f);  // replaced
+
+    UndoManager::getSingleton()->undo();
+    // take 0 is back, take 1 is gone
+    EXPECT_FLOAT_EQ(weightAt(m_mesh, "FaceCap", "jawOpen", 0.5f), 0.6f);
+    EXPECT_FLOAT_EQ(weightAt(m_mesh, "FaceCap", "jawOpen", 1.0f), -1.f);
+
+    UndoManager::getSingleton()->redo();
+    EXPECT_FLOAT_EQ(weightAt(m_mesh, "FaceCap", "jawOpen", 1.0f), 0.9f);
+}
+
+#endif  // ENABLE_MOCAP
diff --git a/src/Mocap/OneEuroFilter.cpp b/src/Mocap/OneEuroFilter.cpp
new file mode 100644
index 000000000..a3e4c0555
--- /dev/null
+++ b/src/Mocap/OneEuroFilter.cpp
@@ -0,0 +1,95 @@
+#include "OneEuroFilter.h"
+
+#include <cmath>
+
+namespace {
+
+double smoothingAlpha(double cutoffHz, double dt)
+{
+    const double tau = 1.0 / (2.0 * M_PI * cutoffHz);
+    return 1.0 / (1.0 + tau / dt);
+}
+
+}  // namespace
+
+double OneEuroFilter::filter(double value, double timeSec)
+{
+    if (!m_initialized) {
+        m_initialized = true;
+        m_lastTime = timeSec;
+        m_lastValue = value;
+        m_lastDerivative = 0.0;
+        return value;
+    }
+    double dt = timeSec - m_lastTime;
+    if (dt <= 0.0)
+        return m_lastValue;
+    m_lastTime = timeSec;
+
+    const double rawDerivative = (value - m_lastValue) / dt;
+    const double aD = smoothingAlpha(m_params.dCutoff, dt);
+    m_lastDerivative = aD * rawDerivative + (1.0 - aD) * m_lastDerivative;
+
+    const double cutoff = m_params.minCutoff
+                          + m_params.beta * std::abs(m_lastDerivative);
+    const double a = smoothingAlpha(cutoff, dt);
+    m_lastValue = a * value + (1.0 - a) * m_lastValue;
+    return m_lastValue;
+}
+
+std::array<float, 4> OneEuroQuatFilter::filter(const std::array<float, 4>& quat,
+                                               double timeSec)
+{
+    // hemisphere alignment: q and -q are the same rotation; keep the
+    // representation continuous against the previous OUTPUT.
+    std::array<float, 4> q = quat;
+    if (m_initialized) {
+        const double dot = q[0] * m_lastQuat[0] + q[1] * m_lastQuat[1]
+                           + q[2] * m_lastQuat[2] + q[3] * m_lastQuat[3];
+        if (dot < 0.0)
+            for (auto& c : q) c = -c;
+    }
+
+    if (!m_initialized) {
+        m_initialized = true;
+        m_lastTime = timeSec;
+        m_lastSpeed = 0.0;
+        m_lastQuat = q;
+        return q;
+    }
+    double dt = timeSec - m_lastTime;
+    if (dt <= 0.0)
+        return m_lastQuat;
+    m_lastTime = timeSec;
+
+    // angular distance previous-output -> sample
+    double dot = q[0] * m_lastQuat[0] + q[1] * m_lastQuat[1]
+                 + q[2] * m_lastQuat[2] + q[3] * m_lastQuat[3];
+    dot = std::fmin(1.0, std::fmax(-1.0, dot));
+    const double angle = 2.0 * std::acos(std::abs(dot));
+
+    const double aD = smoothingAlpha(m_params.dCutoff, dt);
+    m_lastSpeed = aD * (angle / dt) + (1.0 - aD) * m_lastSpeed;
+
+    const double cutoff = m_params.minCutoff + m_params.beta * m_lastSpeed;
+    const double a = smoothingAlpha(cutoff, dt);
+
+    // slerp(m_lastQuat, q, a)
+    std::array<float, 4> out;
+    if (angle < 1e-6) {
+        out = q;
+    } else {
+        const double theta = std::acos(std::abs(dot));
+        const double s = std::sin(theta);
+        const double w0 = std::sin((1.0 - a) * theta) / s;
+        const double w1 = std::sin(a * theta) / s;
+        for (int i = 0; i < 4; ++i)
+            out[i] = static_cast<float>(w0 * m_lastQuat[i] + w1 * q[i]);
+        double n = std::sqrt(out[0] * out[0] + out[1] * out[1]
+                             + out[2] * out[2] + out[3] * out[3]);
+        if (n > 0.0)
+            for (auto& c : out) c = static_cast<float>(c / n);
+    }
+    m_lastQuat = out;
+    return out;
+}
diff --git a/src/Mocap/OneEuroFilter.h b/src/Mocap/OneEuroFilter.h
new file mode 100644
index 000000000..74121d322
--- /dev/null
+++ b/src/Mocap/OneEuroFilter.h
@@ -0,0 +1,61 @@
+#ifndef ONEEUROFILTER_H
+#define ONEEUROFILTER_H
+
+// One-Euro filter (Casiez, Roussel & Vogel, CHI 2012) for mocap channel
+// smoothing (epic #869, Slice C #872). Pure data — no Qt/Ogre/ONNX — so the
+// recorder, the live controller and the tests all share it headless.
+//
+// Defaults are tuned for 30 fps face capture: minCutoff 1.0 Hz keeps slow
+// drift smooth, beta 0.05 lets fast expressions track without lag.
+
+#include <array>
+
+class OneEuroFilter {
+public:
+    struct Params {
+        double minCutoff = 1.0;  // Hz — smoothing at rest (lower = smoother)
+        double beta = 0.05;      // speed coefficient (higher = faster tracking)
+        double dCutoff = 1.0;    // Hz — derivative smoothing
+    };
+
+    OneEuroFilter() : m_params() {}
+    explicit OneEuroFilter(const Params& params) : m_params(params) {}
+
+    // value at timeSec (monotonically increasing). The first sample passes
+    // through unchanged.
+    double filter(double value, double timeSec);
+
+    void reset() { m_initialized = false; }
+    const Params& params() const { return m_params; }
+
+private:
+    Params m_params;
+    bool m_initialized = false;
+    double m_lastTime = 0.0;
+    double m_lastValue = 0.0;
+    double m_lastDerivative = 0.0;
+};
+
+// Quaternion variant: hemisphere-aligns each sample against the previous
+// output (dot >= 0) and slerps toward the new sample with a One-Euro-derived
+// alpha where "speed" is the angular velocity between consecutive samples.
+// Quaternions are (x, y, z, w), unit length.
+class OneEuroQuatFilter {
+public:
+    OneEuroQuatFilter() : m_params() {}
+    explicit OneEuroQuatFilter(const OneEuroFilter::Params& params)
+        : m_params(params) {}
+
+    std::array<float, 4> filter(const std::array<float, 4>& quat, double timeSec);
+
+    void reset() { m_initialized = false; }
+
+private:
+    OneEuroFilter::Params m_params;
+    bool m_initialized = false;
+    double m_lastTime = 0.0;
+    double m_lastSpeed = 0.0;  // rad/s, low-passed with dCutoff
+    std::array<float, 4> m_lastQuat{0.f, 0.f, 0.f, 1.f};
+};
+
+#endif // ONEEUROFILTER_H
diff --git a/src/Mocap/OneEuroFilter_test.cpp b/src/Mocap/OneEuroFilter_test.cpp
new file mode 100644
index 000000000..1c057b71d
--- /dev/null
+++ b/src/Mocap/OneEuroFilter_test.cpp
@@ -0,0 +1,122 @@
+#ifdef ENABLE_MOCAP
+
+#include <gtest/gtest.h>
+
+#include <cmath>
+
+#include "Mocap/OneEuroFilter.h"
+
+TEST(OneEuroFilter, FirstSamplePassesThrough)
+{
+    OneEuroFilter f;
+    EXPECT_DOUBLE_EQ(f.filter(0.7, 0.0), 0.7);
+}
+
+TEST(OneEuroFilter, StepResponseSmooths)
+{
+    OneEuroFilter f(OneEuroFilter::Params{1.0, 0.0, 1.0});  // beta 0: pure low-pass
+    f.filter(0.0, 0.0);
+    const double stepped = f.filter(1.0, 1.0 / 30.0);
+    EXPECT_GT(stepped, 0.0);
+    EXPECT_LT(stepped, 0.6);  // strongly smoothed at 30 fps with 1 Hz cutoff
+
+    // converges toward the target
+    double v = stepped;
+    for (int i = 2; i < 90; ++i)
+        v = f.filter(1.0, i / 30.0);
+    EXPECT_GT(v, 0.95);
+}
+
+TEST(OneEuroFilter, BetaLetsFastMotionTrack)
+{
+    OneEuroFilter slow(OneEuroFilter::Params{1.0, 0.0, 1.0});
+    OneEuroFilter fast(OneEuroFilter::Params{1.0, 5.0, 1.0});
+    slow.filter(0.0, 0.0);
+    fast.filter(0.0, 0.0);
+    double vSlow = 0.0, vFast = 0.0;
+    for (int i = 1; i <= 10; ++i) {
+        const double target = i * 0.5;  // fast ramp
+        vSlow = slow.filter(target, i / 30.0);
+        vFast = fast.filter(target, i / 30.0);
+    }
+    EXPECT_GT(vFast, vSlow);  // high beta tracks the ramp closer
+}
+
+TEST(OneEuroFilter, NonMonotonicTimeIsIgnored)
+{
+    OneEuroFilter f;
+    f.filter(1.0, 1.0);
+    EXPECT_DOUBLE_EQ(f.filter(99.0, 1.0), f.filter(99.0, 0.5));
+}
+
+namespace {
+
+std::array<float, 4> quatAboutZ(double rad)
+{
+    return {0.f, 0.f, static_cast<float>(std::sin(rad / 2)),
+            static_cast<float>(std::cos(rad / 2))};
+}
+
+double quatAngle(const std::array<float, 4>& a, const std::array<float, 4>& b)
+{
+    double dot = 0;
+    for (int i = 0; i < 4; ++i)
+        dot += a[i] * b[i];
+    return 2.0 * std::acos(std::fmin(1.0, std::fabs(dot)));
+}
+
+}  // namespace
+
+TEST(OneEuroQuatFilter, FirstSamplePassesThrough)
+{
+    OneEuroQuatFilter f;
+    const auto q = quatAboutZ(0.3);
+    const auto out = f.filter(q, 0.0);
+    // float storage: acos near 1.0 amplifies rounding, so ~1e-3 rad is exact
+    EXPECT_NEAR(quatAngle(out, q), 0.0, 1e-3);
+}
+
+TEST(OneEuroQuatFilter, SmoothsTowardSample)
+{
+    OneEuroQuatFilter f(OneEuroFilter::Params{1.0, 0.0, 1.0});
+    f.filter(quatAboutZ(0.0), 0.0);
+    const auto target = quatAboutZ(1.0);
+    const auto out = f.filter(target, 1.0 / 30.0);
+    const double remaining = quatAngle(out, target);
+    EXPECT_GT(remaining, 0.3);  // did not jump straight to the target
+    EXPECT_LT(remaining, 1.0);  // but moved toward it
+}
+
+TEST(OneEuroQuatFilter, HemisphereConsistency)
+{
+    OneEuroQuatFilter f;
+    auto q = quatAboutZ(0.2);
+    const auto first = f.filter(q, 0.0);
+    // feed the SAME rotation with flipped sign: output must stay in the
+    // previous output's hemisphere (dot >= 0), no 360-degree pop
+    for (auto& c : q)
+        c = -c;
+    const auto out = f.filter(q, 1.0 / 30.0);
+    double dot = 0;
+    for (int i = 0; i < 4; ++i)
+        dot += out[i] * first[i];
+    EXPECT_GE(dot, 0.0);
+    EXPECT_NEAR(quatAngle(out, first), 0.0, 1e-4);
+}
+
+TEST(OneEuroQuatFilter, ContinuousUnderIncrementalRotation)
+{
+    OneEuroQuatFilter f(OneEuroFilter::Params{1.5, 0.5, 1.0});
+    auto prev = f.filter(quatAboutZ(0.0), 0.0);
+    for (int i = 1; i <= 60; ++i) {
+        const auto out = f.filter(quatAboutZ(i * 0.05), i / 30.0);
+        EXPECT_LT(quatAngle(out, prev), 0.2);  // no jumps between frames
+        double n = 0;
+        for (int k = 0; k < 4; ++k)
+            n += out[k] * out[k];
+        EXPECT_NEAR(n, 1.0, 1e-4);  // stays unit length
+        prev = out;
+    }
+}
+
+#endif  // ENABLE_MOCAP
diff --git a/src/Mocap/PoseCapPredictor.cpp b/src/Mocap/PoseCapPredictor.cpp
new file mode 100644
index 000000000..ea24e8730
--- /dev/null
+++ b/src/Mocap/PoseCapPredictor.cpp
@@ -0,0 +1,396 @@
+#ifdef ENABLE_MOCAP
+
+#include "PoseCapPredictor.h"
+
+#include "FaceCapGeom.h"
+#include "../ModelDownloader.h"
+
+#include <QDir>
+#include <QEventLoop>
+#include <QFileInfo>
+#include <QSettings>
+#include <QStandardPaths>
+#include <QTimer>
+
+#include <algorithm>
+#include <cmath>
+#include <vector>
+
+#ifdef ENABLE_ONNX
+#include <onnxruntime_cxx_api.h>
+#endif
+
+namespace {
+
+constexpr const char* kDetectorFile = "pose_detector.onnx";
+constexpr const char* kLandmarksFile = "pose_landmarks.onnx";
+// base URL points at the mocap ROOT (shared with FaceCapPredictor); the
+// pose/ subdir is appended so ONE override serves both bundles.
+constexpr const char* kDefaultModelBaseUrl =
+    "https://huggingface.co/fernandotonon/QtMeshEditor-models/resolve/main/mocap/";
+constexpr const char* kBaseUrlSettingsKey = "ai/mocapModelBaseUrl";
+
+constexpr float kPresenceThreshold = 0.5f;
+
+float stableSigmoid(float x)
+{
+    x = std::clamp(x, -50.f, 50.f);
+    return x >= 0.f ? 1.f / (1.f + std::exp(-x))
+                    : std::exp(x) / (1.f + std::exp(x));
+}
+
+}  // namespace
+
+QString PoseCapPredictor::modelDir()
+{
+    const QString dataPath =
+        QStandardPaths::writableLocation(QStandardPaths::AppDataLocation);
+    return QDir(dataPath).filePath(QStringLiteral("ai_models/mocap/pose"));
+}
+
+bool PoseCapPredictor::modelsPresent()
+{
+    const QDir dir(modelDir());
+    return QFileInfo::exists(dir.filePath(QLatin1String(kDetectorFile)))
+           && QFileInfo::exists(dir.filePath(QLatin1String(kLandmarksFile)));
+}
+
+QString PoseCapPredictor::ensureModelsBlocking()
+{
+#ifndef ENABLE_ONNX
+    return {};
+#else
+    if (modelsPresent())
+        return modelDir();
+    if (!qEnvironmentVariableIsEmpty("QTMESH_MOCAP_NO_DOWNLOAD"))
+        return {};
+
+    QString base;
+    {
+        QSettings s;
+        base = s.value(QString::fromLatin1(kBaseUrlSettingsKey)).toString();
+        if (base.isEmpty()) {
+            const QByteArray env = qgetenv("QTMESH_MOCAP_MODEL_BASE_URL");
+            base = env.isEmpty() ? QString::fromLatin1(kDefaultModelBaseUrl)
+                                 : QString::fromUtf8(env);
+        }
+    }
+    if (base.isEmpty())
+        return {};
+    if (!base.endsWith('/'))
+        base += '/';
+
+    auto* dl = ModelDownloader::instance();
+    if (!dl)
+        return {};
+
+    const QDir dir(modelDir());
+    auto downloadOne = [&](const char* fileName) -> bool {
+        const QString dest = dir.filePath(QLatin1String(fileName));
+        if (QFileInfo::exists(dest))
+            return true;
+        QDir().mkpath(QFileInfo(dest).absolutePath());
+        const QString label =
+            QStringLiteral("Pose capture model (%1)").arg(QLatin1String(fileName));
+        QEventLoop loop;
+        bool ok = false, timedOut = false;
+        auto onDone = QObject::connect(
+            dl, &ModelDownloader::downloadCompleted, &loop,
+            [&](const QString& name, const QString&) {
+                if (name == label) { ok = true; loop.quit(); }
+            });
+        auto onErr = QObject::connect(
+            dl, &ModelDownloader::downloadError, &loop,
+            [&](const QString& name, const QString&) {
+                if (name == label) { ok = false; loop.quit(); }
+            });
+        QTimer timeout;
+        timeout.setSingleShot(true);
+        QObject::connect(&timeout, &QTimer::timeout, &loop,
+                         [&]() { timedOut = true; loop.quit(); });
+        timeout.start(300000);  // 5 min — ~25 MB total
+        dl->startDownload(base + QLatin1String("pose/") + QLatin1String(fileName), dest, label);
+        loop.exec();
+        QObject::disconnect(onDone);
+        QObject::disconnect(onErr);
+        if (timedOut && dl)
+            dl->cancelDownload();
+        return ok && !timedOut && QFileInfo::exists(dest);
+    };
+
+    if (!downloadOne(kDetectorFile) || !downloadOne(kLandmarksFile))
+        return {};
+    return modelDir();
+#endif
+}
+
+#ifndef ENABLE_ONNX
+
+struct PoseCapPredictor::Impl {
+    QString error = QStringLiteral(
+        "pose capture predictor unavailable (built without ENABLE_ONNX)");
+};
+
+PoseCapPredictor::PoseCapPredictor() : d(new Impl) {}
+PoseCapPredictor::~PoseCapPredictor() = default;
+bool PoseCapPredictor::load(const QString&) { return false; }
+bool PoseCapPredictor::isAvailable() const { return false; }
+QString PoseCapPredictor::lastError() const { return d->error; }
+PoseSample PoseCapPredictor::predict(const QImage&, double timeSec)
+{
+    PoseSample s;
+    s.timeSec = timeSec;
+    return s;
+}
+void PoseCapPredictor::resetTracking() {}
+int PoseCapPredictor::detectorRuns() const { return 0; }
+
+#else  // ENABLE_ONNX
+
+struct PoseCapPredictor::Impl {
+    Ort::Env env{ORT_LOGGING_LEVEL_WARNING, "qtmesh_posecap"};
+    std::unique_ptr<Ort::Session> detector;
+    std::unique_ptr<Ort::Session> landmarks;
+    std::vector<std::array<float, 2>> anchors;
+    int detectorSize = 224;
+    int landmarksSize = 256;
+    QString error;
+    bool available = false;
+
+    bool tracking = false;
+    FaceCapGeom::RotatedRect trackedRect;
+    int detectorRuns = 0;
+
+    std::vector<float> detInput;
+    std::vector<float> lmkInput;
+
+    std::unique_ptr<Ort::Session> openSession(const QString& path)
+    {
+        Ort::SessionOptions so;
+        so.SetIntraOpNumThreads(2);
+#ifdef Q_OS_MACOS
+        try {
+            std::unordered_map<std::string, std::string> opts;
+            so.AppendExecutionProvider("CoreML", opts);
+        } catch (const Ort::Exception&) {}
+#endif
+#ifdef Q_OS_WIN
+        const std::wstring wpath = path.toStdWString();
+        return std::make_unique<Ort::Session>(env, wpath.c_str(), so);
+#else
+        const QByteArray p = path.toUtf8();
+        return std::make_unique<Ort::Session>(env, p.constData(), so);
+#endif
+    }
+};
+
+PoseCapPredictor::PoseCapPredictor() : d(new Impl) {}
+PoseCapPredictor::~PoseCapPredictor() = default;
+
+bool PoseCapPredictor::load(const QString& dirIn)
+{
+    const QDir dir(dirIn.isEmpty() ? modelDir() : dirIn);
+    const QString det = dir.filePath(QLatin1String(kDetectorFile));
+    const QString lmk = dir.filePath(QLatin1String(kLandmarksFile));
+    if (!QFileInfo::exists(det) || !QFileInfo::exists(lmk)) {
+        d->error = QStringLiteral(
+            "pose capture models not found in %1 — they download on first "
+            "use, or set QTMESH_MOCAP_MODEL_BASE_URL").arg(dir.absolutePath());
+        return false;
+    }
+    try {
+        d->detector = d->openSession(det);
+        d->landmarks = d->openSession(lmk);
+        {
+            const auto info = d->detector->GetInputTypeInfo(0);
+            const auto shape = info.GetTensorTypeAndShapeInfo().GetShape();
+            if (shape.size() == 4 && shape[1] > 0)
+                d->detectorSize = static_cast<int>(shape[1]);
+        }
+        {
+            const auto info = d->landmarks->GetInputTypeInfo(0);
+            const auto shape = info.GetTensorTypeAndShapeInfo().GetShape();
+            if (shape.size() == 4 && shape[1] > 0)
+                d->landmarksSize = static_cast<int>(shape[1]);
+        }
+        d->anchors =
+            FaceCapGeom::genSsdAnchors(d->detectorSize, {8, 16, 32, 32, 32});
+        {
+            const auto info = d->detector->GetOutputTypeInfo(0);
+            const auto shape = info.GetTensorTypeAndShapeInfo().GetShape();
+            if (shape.size() == 3
+                && shape[1] != static_cast<int64_t>(d->anchors.size())) {
+                d->error = QStringLiteral(
+                    "pose detector anchor count mismatch (model %1, ours %2)")
+                               .arg(shape[1]).arg(d->anchors.size());
+                return false;
+            }
+        }
+        d->detInput.resize(static_cast<size_t>(d->detectorSize)
+                           * d->detectorSize * 3);
+        d->lmkInput.resize(static_cast<size_t>(d->landmarksSize)
+                           * d->landmarksSize * 3);
+        d->available = true;
+        d->error.clear();
+        return true;
+    } catch (const Ort::Exception& e) {
+        d->error = QStringLiteral("failed to load pose capture models: %1")
+                       .arg(QString::fromUtf8(e.what()));
+        d->available = false;
+        return false;
+    }
+}
+
+bool PoseCapPredictor::isAvailable() const { return d->available; }
+QString PoseCapPredictor::lastError() const { return d->error; }
+void PoseCapPredictor::resetTracking() { d->tracking = false; }
+int PoseCapPredictor::detectorRuns() const { return d->detectorRuns; }
+
+PoseSample PoseCapPredictor::predict(const QImage& image, double timeSec)
+{
+    PoseSample sample;
+    sample.timeSec = timeSec;
+    if (!d->available) {
+        if (d->error.isEmpty())
+            d->error = QStringLiteral("predictor not loaded — call load()");
+        return sample;
+    }
+    QImage rgb = image.format() == QImage::Format_RGB888
+                     ? image
+                     : image.convertToFormat(QImage::Format_RGB888);
+    const int W = rgb.width();
+    const int H = rgb.height();
+    if (W <= 0 || H <= 0)
+        return sample;
+
+    try {
+        Ort::MemoryInfo mem =
+            Ort::MemoryInfo::CreateCpu(OrtArenaAllocator, OrtMemTypeDefault);
+        Ort::AllocatorWithDefaultOptions alloc;
+
+        auto runSession = [&](Ort::Session* session, Ort::Value input)
+            -> std::vector<Ort::Value> {
+            const Ort::AllocatedStringPtr inName =
+                session->GetInputNameAllocated(0, alloc);
+            std::vector<Ort::AllocatedStringPtr> outHolders;
+            std::vector<const char*> outNames;
+            const size_t n = session->GetOutputCount();
+            for (size_t i = 0; i < n; ++i) {
+                outHolders.push_back(session->GetOutputNameAllocated(i, alloc));
+                outNames.push_back(outHolders.back().get());
+            }
+            const char* in = inName.get();
+            return session->Run(Ort::RunOptions{nullptr}, &in, &input, 1,
+                                outNames.data(), outNames.size());
+        };
+
+        FaceCapGeom::RotatedRect rect;
+        if (d->tracking) {
+            rect = d->trackedRect;
+        } else {
+            const int ds = d->detectorSize;
+            FaceCapGeom::Letterbox lb = FaceCapGeom::letterboxToTensor(
+                rgb, ds, -1.f, 1.f, d->detInput.data());
+            const std::array<int64_t, 4> shape{1, ds, ds, 3};
+            Ort::Value input = Ort::Value::CreateTensor<float>(
+                mem, d->detInput.data(), d->detInput.size(), shape.data(),
+                shape.size());
+            auto outs = runSession(d->detector.get(), std::move(input));
+            ++d->detectorRuns;
+
+            const float* rawBoxes = nullptr;
+            const float* rawScores = nullptr;
+            for (auto& o : outs) {
+                const auto s = o.GetTensorTypeAndShapeInfo().GetShape();
+                if (s.size() == 3 && s[2] > 1)
+                    rawBoxes = o.GetTensorData<float>();
+                else if (s.size() == 3 && s[2] == 1)
+                    rawScores = o.GetTensorData<float>();
+            }
+            if (!rawBoxes || !rawScores) {
+                d->error = QStringLiteral("unexpected pose detector outputs");
+                return sample;
+            }
+            auto dets = FaceCapGeom::decodeDetections(
+                rawBoxes, rawScores, d->anchors, ds, /*numKeypoints=*/4);
+            if (dets.empty())
+                return sample;
+            FaceCapGeom::Detection& best = dets.front();
+            for (auto& kp : best.keypoints)
+                FaceCapGeom::unletterbox(lb, kp[0], kp[1]);
+            rect = FaceCapGeom::rectFromPoseDetection(best, W, H);
+        }
+
+        const int ls = d->landmarksSize;
+        FaceCapGeom::cropRotatedRectToTensor(rgb, rect, ls, 0.f, 1.f,
+                                             d->lmkInput.data());
+        const std::array<int64_t, 4> lshape{1, ls, ls, 3};
+        Ort::Value linput = Ort::Value::CreateTensor<float>(
+            mem, d->lmkInput.data(), d->lmkInput.size(), lshape.data(),
+            lshape.size());
+        auto louts = runSession(d->landmarks.get(), std::move(linput));
+
+        // identify outputs by element count: 195 = 39x5 screen landmarks,
+        // 117 = 39x3 world landmarks, 1 = presence PROBABILITY (not a logit)
+        const float* rawScreen = nullptr;
+        const float* rawWorld = nullptr;
+        float presence = 0.f;
+        for (auto& o : louts) {
+            const size_t count = o.GetTensorTypeAndShapeInfo().GetElementCount();
+            if (count == 39 * 5)
+                rawScreen = o.GetTensorData<float>();
+            else if (count == 39 * 3)
+                rawWorld = o.GetTensorData<float>();
+            else if (count == 1)
+                presence = o.GetTensorData<float>()[0];
+        }
+        if (!rawScreen || !rawWorld) {
+            d->error = QStringLiteral("unexpected pose landmark outputs");
+            return sample;
+        }
+        if (presence < kPresenceThreshold) {
+            if (d->tracking) {
+                d->tracking = false;
+                return predict(image, timeSec);  // retry with the detector
+            }
+            return sample;
+        }
+
+        // world landmarks: rotate x,y by the ROI rotation only
+        const float ca = std::cos(rect.angle);
+        const float sa = std::sin(rect.angle);
+        for (int i = 0; i < 33; ++i) {
+            const float wx = rawWorld[i * 3 + 0];
+            const float wy = rawWorld[i * 3 + 1];
+            sample.world[i * 3 + 0] = wx * ca - wy * sa;
+            sample.world[i * 3 + 1] = wx * sa + wy * ca;
+            sample.world[i * 3 + 2] = rawWorld[i * 3 + 2];
+            sample.visibility[i] = stableSigmoid(rawScreen[i * 5 + 3]);
+        }
+        sample.confidence = presence;
+
+        // next-frame ROI from the auxiliary alignment landmarks (raw 33/34):
+        // centre + scale point in crop space -> image px -> alignment rect
+        {
+            float aux[2 * 3] = {
+                rawScreen[33 * 5 + 0] / ls, rawScreen[33 * 5 + 1] / ls, 0.f,
+                rawScreen[34 * 5 + 0] / ls, rawScreen[34 * 5 + 1] / ls, 0.f,
+            };
+            FaceCapGeom::projectLandmarks(aux, 2, 3, rect);
+            FaceCapGeom::Detection synth;
+            synth.keypoints = {{aux[0] / W, aux[1] / H},
+                               {aux[3] / W, aux[4] / H}};
+            d->trackedRect = FaceCapGeom::rectFromPoseDetection(synth, W, H);
+            d->tracking = d->trackedRect.w > 8.f && d->trackedRect.h > 8.f;
+        }
+        return sample;
+    } catch (const Ort::Exception& e) {
+        d->error = QStringLiteral("pose capture inference failed: %1")
+                       .arg(QString::fromUtf8(e.what()));
+        d->tracking = false;
+        return sample;
+    }
+}
+
+#endif  // ENABLE_ONNX
+#endif  // ENABLE_MOCAP
diff --git a/src/Mocap/PoseCapPredictor.h b/src/Mocap/PoseCapPredictor.h
new file mode 100644
index 000000000..713968796
--- /dev/null
+++ b/src/Mocap/PoseCapPredictor.h
@@ -0,0 +1,58 @@
+#ifndef POSECAPPREDICTOR_H
+#define POSECAPPREDICTOR_H
+
+// Body-pose predictor (epic #869, Slice E #874) — ONNX consumer #10.
+// One RGB888 frame in -> 33 MediaPipe world landmarks (metres, hip-centred)
+// + visibility + confidence out, via the two graphs converted by
+// scripts/export-facecap-onnx.py --pose (Apache-2.0; contract in
+// docs/MOCAP_SPIKE.md): pose_detector.onnx (letterboxed 224, [-1,1], 2254
+// anchors) and pose_landmarks.onnx (rotated 256 crop, [0,1] -> 39x5 screen
+// landmarks + world landmarks + presence).
+//
+// Detector-skip tracking mirrors FaceCapPredictor: the next frame's ROI comes
+// from this frame's auxiliary alignment landmarks (raw landmarks 33/34 — the
+// mid-hip centre + scale point BlazePose emits exactly for this purpose).
+//
+// Models download on first use to AppData/ai_models/mocap/pose/ (same env /
+// QSettings overrides as the face models: QTMESH_MOCAP_MODEL_BASE_URL /
+// ai/mocapModelBaseUrl / QTMESH_MOCAP_NO_DOWNLOAD).
+
+#ifdef ENABLE_MOCAP
+
+#include <QImage>
+#include <QString>
+
+#include <array>
+#include <memory>
+
+struct PoseSample {
+    double timeSec = 0.0;
+    std::array<float, 33 * 3> world{};      // xyz metres, MediaPipe world frame
+    std::array<float, 33> visibility{};     // sigmoided per-landmark visibility
+    float confidence = 0.f;                 // pose presence; 0 = none found
+};
+
+class PoseCapPredictor {
+public:
+    PoseCapPredictor();
+    ~PoseCapPredictor();
+
+    static QString modelDir();  // AppData/ai_models/mocap/pose
+    static bool modelsPresent();
+    static QString ensureModelsBlocking();
+
+    bool load(const QString& dir = {});
+    bool isAvailable() const;
+    QString lastError() const;
+
+    PoseSample predict(const QImage& image, double timeSec);
+    void resetTracking();
+    int detectorRuns() const;
+
+private:
+    struct Impl;
+    std::unique_ptr<Impl> d;
+};
+
+#endif  // ENABLE_MOCAP
+#endif  // POSECAPPREDICTOR_H
diff --git a/src/Mocap/PoseIKSolver.cpp b/src/Mocap/PoseIKSolver.cpp
new file mode 100644
index 000000000..68bc7a9f4
--- /dev/null
+++ b/src/Mocap/PoseIKSolver.cpp
@@ -0,0 +1,262 @@
+#include "PoseIKSolver.h"
+
+#include <cmath>
+
+namespace PoseIK {
+
+namespace {
+
+// MediaPipe pose landmark indices
+enum Lm : int {
+    Nose = 0, LEar = 7, REar = 8,
+    LShoulderLm = 11, RShoulderLm = 12, LElbowLm = 13, RElbowLm = 14,
+    LWrist = 15, RWrist = 16,
+    LHipLm = 23, RHipLm = 24, LKneeLm = 25, RKneeLm = 26,
+    LAnkle = 27, RAnkle = 28, LFootIndex = 31, RFootIndex = 32,
+};
+
+using Vec3 = std::array<float, 3>;
+using Quat = std::array<float, 4>;
+
+constexpr Quat kIdentity{0.f, 0.f, 0.f, 1.f};
+
+Vec3 sub(const Vec3& a, const Vec3& b) { return {a[0]-b[0], a[1]-b[1], a[2]-b[2]}; }
+Vec3 add(const Vec3& a, const Vec3& b) { return {a[0]+b[0], a[1]+b[1], a[2]+b[2]}; }
+Vec3 mul(const Vec3& a, float s) { return {a[0]*s, a[1]*s, a[2]*s}; }
+float dot(const Vec3& a, const Vec3& b) { return a[0]*b[0]+a[1]*b[1]+a[2]*b[2]; }
+Vec3 cross(const Vec3& a, const Vec3& b)
+{
+    return {a[1]*b[2]-a[2]*b[1], a[2]*b[0]-a[0]*b[2], a[0]*b[1]-a[1]*b[0]};
+}
+float length(const Vec3& a) { return std::sqrt(dot(a, a)); }
+bool normalize(Vec3& a)
+{
+    const float n = length(a);
+    if (n < 1e-6f) return false;
+    a = mul(a, 1.f / n);
+    return true;
+}
+
+// column-major orthonormal basis (x, y, z) -> quaternion (x,y,z,w)
+Quat quatFromBasis(const Vec3& x, const Vec3& y, const Vec3& z)
+{
+    const float m00 = x[0], m01 = y[0], m02 = z[0];
+    const float m10 = x[1], m11 = y[1], m12 = z[1];
+    const float m20 = x[2], m21 = y[2], m22 = z[2];
+    const float trace = m00 + m11 + m22;
+    Quat q;
+    if (trace > 0.f) {
+        const float s = std::sqrt(trace + 1.f) * 2.f;
+        q = {(m21 - m12) / s, (m02 - m20) / s, (m10 - m01) / s, s / 4.f};
+    } else if (m00 > m11 && m00 > m22) {
+        const float s = std::sqrt(1.f + m00 - m11 - m22) * 2.f;
+        q = {s / 4.f, (m01 + m10) / s, (m02 + m20) / s, (m21 - m12) / s};
+    } else if (m11 > m22) {
+        const float s = std::sqrt(1.f + m11 - m00 - m22) * 2.f;
+        q = {(m01 + m10) / s, s / 4.f, (m12 + m21) / s, (m02 - m20) / s};
+    } else {
+        const float s = std::sqrt(1.f + m22 - m00 - m11) * 2.f;
+        q = {(m02 + m20) / s, (m12 + m21) / s, s / 4.f, (m10 - m01) / s};
+    }
+    float n = std::sqrt(q[0]*q[0] + q[1]*q[1] + q[2]*q[2] + q[3]*q[3]);
+    if (n > 0.f)
+        for (auto& c : q) c /= n;
+    return q;
+}
+
+Quat nlerp(const Quat& a, const Quat& b, float t)
+{
+    float dotq = a[0]*b[0] + a[1]*b[1] + a[2]*b[2] + a[3]*b[3];
+    const float sign = dotq >= 0.f ? 1.f : -1.f;
+    Quat out;
+    for (int i = 0; i < 4; ++i)
+        out[i] = a[i] * (1.f - t) + sign * b[i] * t;
+    float n = std::sqrt(out[0]*out[0] + out[1]*out[1] + out[2]*out[2] + out[3]*out[3]);
+    if (n < 1e-6f) return a;
+    for (auto& c : out) c /= n;
+    return out;
+}
+
+// primary axis y + rough secondary -> full basis quat; false when degenerate
+bool basisFromPrimary(Vec3 y, Vec3 secondary, Quat& out, Vec3* usedSecondary)
+{
+    if (!normalize(y))
+        return false;
+    Vec3 x = sub(secondary, mul(y, dot(secondary, y)));
+    if (!normalize(x))
+        return false;
+    const Vec3 z = cross(x, y);
+    out = quatFromBasis(x, y, z);
+    if (usedSecondary)
+        *usedSecondary = x;
+    return true;
+}
+
+}  // namespace
+
+void Solver::reset()
+{
+    m_hasPrev = false;
+}
+
+FrameResult Solver::solveFrame(const float* world, const float* visibility,
+                               float minVisibility)
+{
+    FrameResult result;
+    result.quats.fill(kIdentity);
+    if (m_hasPrev)
+        result.quats = m_prevQuats;  // unresolved roles hold their last pose
+
+    // Canonicalize MediaPipe's frame (x = subject-left, y = down, z = toward
+    // camera) into the canonical rig frame: y-UP, subject FACING +Z, right-
+    // handed. The subject faces the camera (MediaPipe -z), but canonical rigs
+    // face +Z, so we must flip the facing: map (x,y,z) -> (-x, -y, +z). This
+    // is a 180° yaw that cancels the constant (0,-1,0,0) hip offset the old
+    // (x,-y,-z) mapping produced (which left the whole body driven backwards).
+    Vec3 p[kLandmarkCount];
+    for (int i = 0; i < kLandmarkCount; ++i)
+        p[i] = {-world[i * 3 + 0], -world[i * 3 + 1], world[i * 3 + 2]};
+
+    auto visible = [&](int lm) {
+        return !visibility || visibility[lm] >= minVisibility;
+    };
+    auto mid = [&](int a, int b) { return mul(add(p[a], p[b]), 0.5f); };
+
+    std::array<Vec3, kCanonicalRoles> secondaryUsed = m_prevSecondary;
+
+    // ---- torso ---------------------------------------------------------------
+    const bool torsoVisible = visible(LShoulderLm) && visible(RShoulderLm)
+                              && visible(LHipLm) && visible(RHipLm);
+    Quat hipQ = kIdentity, chestQ = kIdentity;
+    bool torsoOk = false;
+    Vec3 torsoUp{0.f, 1.f, 0.f}, torsoRight{1.f, 0.f, 0.f};
+    if (torsoVisible) {
+        const Vec3 hipMid = mid(LHipLm, RHipLm);
+        const Vec3 shoulderMid = mid(LShoulderLm, RShoulderLm);
+        Vec3 up = sub(shoulderMid, hipMid);
+        Vec3 hipLine = sub(p[RHipLm], p[LHipLm]);
+        const Vec3 shoulderLine = sub(p[RShoulderLm], p[LShoulderLm]);
+        // Stabilize the hip's horizontal reference. On a seated / partially-
+        // occluded subject the hip landmarks are noisy and hipLine can FLIP
+        // sign between frames, whipping the whole torso 180° about Y (observed:
+        // Hip quat identity → (0,-1,0,0) mid-clip). The SHOULDER line is far
+        // more reliable, so:
+        //  (a) if the hip line is short/degenerate or points opposite the
+        //      shoulder line, fall back to the shoulder line for the hip frame;
+        //  (b) keep the hip line temporally continuous (no sudden sign flip).
+        if (length(hipLine) < 0.05f * length(shoulderLine)
+            || dot(hipLine, shoulderLine) < 0.f)
+            hipLine = shoulderLine;
+        const Vec3 prevHip{m_prevHipLine[0], m_prevHipLine[1], m_prevHipLine[2]};
+        if (m_hasPrev && dot(hipLine, prevHip) < 0.f)
+            hipLine = mul(hipLine, -1.f);   // preserve orientation continuity
+        m_prevHipLine = {hipLine[0], hipLine[1], hipLine[2]};
+        Quat q1, q2;
+        const bool ok1 = basisFromPrimary(up, hipLine, q1, nullptr);
+        const bool ok2 = basisFromPrimary(up, shoulderLine, q2, nullptr);
+        if (ok1 && ok2) {
+            torsoOk = true;
+            hipQ = q1;
+            chestQ = q2;
+            torsoUp = up;
+            normalize(torsoUp);
+            torsoRight = hipLine;
+            normalize(torsoRight);
+            result.quats[Hip] = q1;
+            result.quats[Abdomen] = nlerp(q1, q2, 0.5f);
+            result.quats[Chest] = q2;
+            result.quats[Neck] = q2;
+            result.quats[Neck1] = q2;
+            result.resolvedMask |= (1u << Hip) | (1u << Abdomen) | (1u << Chest)
+                                   | (1u << Neck) | (1u << Neck1);
+        }
+    }
+
+    // ---- head ------------------------------------------------------------------
+    if (visible(Nose) && visible(LEar) && visible(REar)) {
+        const Vec3 earMid = mid(LEar, REar);
+        Vec3 x = sub(p[REar], p[LEar]);          // ear line
+        Vec3 fwd = sub(p[Nose], earMid);         // facing direction
+        // y (head-up) completes the frame: up = fwd x earline is unstable when
+        // looking straight down, so orthonormalize fwd against x and derive y.
+        if (normalize(x)) {
+            Vec3 z = sub(fwd, mul(x, dot(fwd, x)));
+            if (normalize(z)) {
+                const Vec3 y = cross(z, x);
+                result.quats[Head] = quatFromBasis(x, y, z);
+                result.resolvedMask |= (1u << Head);
+            }
+        }
+    }
+
+    // ---- limbs -----------------------------------------------------------------
+    struct Segment {
+        Role role;
+        int from, to;
+    };
+    const Segment segments[] = {
+        {RShoulder, RShoulderLm, RElbowLm}, {RElbow, RElbowLm, RWrist},
+        {LShoulder, LShoulderLm, LElbowLm}, {LElbow, LElbowLm, LWrist},
+        {RHip, RHipLm, RKneeLm}, {RKnee, RKneeLm, RAnkle},
+        {RFoot, RAnkle, RFootIndex},
+        {LHip, LHipLm, LKneeLm}, {LKnee, LKneeLm, LAnkle},
+        {LFoot, LAnkle, LFootIndex},
+    };
+    const Vec3 torsoFwd = cross(torsoRight, torsoUp);
+    for (const Segment& seg : segments) {
+        if (!visible(seg.from) || !visible(seg.to))
+            continue;
+        Vec3 dir = sub(p[seg.to], p[seg.from]);
+        Vec3 y = dir;
+        if (!normalize(y))
+            continue;
+
+        // Twist reference. Tracked roles get TRUE parallel transport: the
+        // previous secondary axis rotated by the shortest arc between the
+        // previous and current segment directions — well-defined even when
+        // the segment swings straight into the old axis, and it adds zero
+        // twist by construction. First frame (or a lost track / antiparallel
+        // flip) seeds from the most orthogonal torso axis.
+        Vec3 secondary{0.f, 0.f, 0.f};
+        if (m_hasPrev && length(m_prevSecondary[seg.role]) > 0.5f) {
+            const Vec3 prevY = m_prevPrimary[seg.role];
+            const float c = dot(prevY, y);
+            if (c > -0.999f) {
+                // rotate prevSecondary by shortest-arc(prevY -> y):
+                // Rodrigues with axis = prevY x y, sin = |axis|
+                const Vec3 axis = cross(prevY, y);
+                const Vec3 v = m_prevSecondary[seg.role];
+                const Vec3 t = cross(axis, v);
+                const Vec3 tt = cross(axis, t);
+                // R v = v + t + tt/(1+c)   (unit-free Rodrigues form)
+                secondary = add(add(v, t), mul(tt, 1.f / (1.f + c)));
+            }
+        }
+        if (length(secondary) < 0.5f) {
+            secondary = std::abs(dot(y, torsoRight)) < std::abs(dot(y, torsoFwd))
+                            ? torsoRight
+                            : torsoFwd;
+            if (std::abs(dot(y, secondary)) > 0.99f)
+                secondary = std::abs(y[0]) < 0.9f ? Vec3{1.f, 0.f, 0.f}
+                                                  : Vec3{0.f, 0.f, 1.f};
+        }
+        Quat q;
+        Vec3 used;
+        if (basisFromPrimary(dir, secondary, q, &used)) {
+            result.quats[seg.role] = q;
+            result.resolvedMask |= (1u << seg.role);
+            secondaryUsed[seg.role] = used;
+            m_prevPrimary[seg.role] = y;
+        }
+    }
+    (void)torsoOk;
+    (void)hipQ;
+    (void)chestQ;
+
+    m_prevSecondary = secondaryUsed;
+    m_prevQuats = result.quats;
+    m_hasPrev = true;
+    return result;
+}
+
+}  // namespace PoseIK
diff --git a/src/Mocap/PoseIKSolver.h b/src/Mocap/PoseIKSolver.h
new file mode 100644
index 000000000..833376014
--- /dev/null
+++ b/src/Mocap/PoseIKSolver.h
@@ -0,0 +1,82 @@
+#ifndef POSEIKSOLVER_H
+#define POSEIKSOLVER_H
+
+// Analytic body-pose solver (epic #869, Slice E #874) — the always-available
+// permissive fallback backend. Pure data: no Qt/Ogre/ONNX.
+//
+// Input: MediaPipe pose WORLD landmarks per frame (33 x xyz, metres,
+// hip-centred, MediaPipe's frame: +x subject's-left, +y DOWN, +z toward the
+// camera). Output: WORLD orientation quaternions (x,y,z,w) for the 22
+// canonical CMU roles MotionInbetween/AnimationMerger retarget with
+// (`applyMotionClip(..., worldFrame=true)` takes the delta vs frame 0 and
+// transports it onto the rig, so only CONSISTENCY over time matters, not the
+// absolute basis).
+//
+// Per role the solver builds an orthonormal frame from landmark geometry:
+//   - hips / spine / chest: hip line (or shoulder line) + the hips->shoulders
+//     spine direction — a full 3-axis torso basis, so torso roll is captured;
+//     abdomen blends the two.
+//   - head: ear line + nose direction.
+//   - limbs (upper/lower arm+leg): the segment direction is the primary axis;
+//     the secondary (twist reference) axis is PARALLEL-TRANSPORTED from the
+//     previous frame (projected perpendicular to the new segment), which
+//     zeroes relative twist by construction and stays continuous even when
+//     the segment sweeps past a torso axis. The first frame seeds from the
+//     most orthogonal torso axis. This is the "zero the twist" hinge
+//     treatment the slice spec asks for — no candy-wrapping.
+//   - collar/buttock/neck twist roles stay identity (their delta is identity,
+//     so the rig keeps its standing pose there).
+//
+// The solver is stateful (the transported axes): one Solver per take,
+// frames fed in order; reset() between takes.
+
+#include <array>
+#include <cstdint>
+
+namespace PoseIK {
+
+constexpr int kLandmarkCount = 33;
+constexpr int kCanonicalRoles = 22;
+
+// canonical role indices (MotionInbetween's kCanonJoints order)
+enum Role : int {
+    Hip = 0, Abdomen = 1, Chest = 2, Neck = 3, Neck1 = 4, Head = 5,
+    RCollar = 6, RShoulder = 7, RElbow = 8, RHand = 9,
+    LCollar = 10, LShoulder = 11, LElbow = 12, LHand = 13,
+    RButtock = 14, RHip = 15, RKnee = 16, RFoot = 17,
+    LButtock = 18, LHip = 19, LKnee = 20, LFoot = 21,
+};
+
+struct FrameResult {
+    // world orientation per canonical role, (x,y,z,w); identity if unresolved
+    std::array<std::array<float, 4>, kCanonicalRoles> quats;
+    uint32_t resolvedMask = 0;  // bit i set = role i solved this frame
+
+    bool resolved(int role) const { return resolvedMask & (1u << role); }
+};
+
+class Solver {
+public:
+    // world: 33 x 3 floats (MediaPipe world landmarks). visibility: optional
+    // 33 sigmoided visibilities; landmarks below minVisibility invalidate the
+    // roles they feed (those roles hold their previous orientation if any,
+    // else identity, and are not marked resolved).
+    FrameResult solveFrame(const float* world, const float* visibility = nullptr,
+                           float minVisibility = 0.3f);
+
+    void reset();
+
+private:
+    bool m_hasPrev = false;
+    // previous secondary (twist-reference) + primary axes per role, world frame
+    std::array<std::array<float, 3>, kCanonicalRoles> m_prevSecondary{};
+    std::array<std::array<float, 3>, kCanonicalRoles> m_prevPrimary{};
+    std::array<std::array<float, 4>, kCanonicalRoles> m_prevQuats{};
+    // previous hip horizontal line (world frame) — keeps the torso frame
+    // from flipping 180° on a noisy/occluded seated subject.
+    std::array<float, 3> m_prevHipLine{0.f, 0.f, 0.f};
+};
+
+}  // namespace PoseIK
+
+#endif  // POSEIKSOLVER_H
diff --git a/src/Mocap/PoseIKSolver_test.cpp b/src/Mocap/PoseIKSolver_test.cpp
new file mode 100644
index 000000000..8620fda01
--- /dev/null
+++ b/src/Mocap/PoseIKSolver_test.cpp
@@ -0,0 +1,174 @@
+#ifdef ENABLE_MOCAP
+
+#include <gtest/gtest.h>
+
+#include <array>
+#include <cmath>
+#include <vector>
+
+#include "Mocap/PoseIKSolver.h"
+
+namespace {
+
+using Landmarks = std::array<float, PoseIK::kLandmarkCount * 3>;
+
+void set(Landmarks& l, int lm, float x, float y, float z)
+{
+    l[lm * 3 + 0] = x;
+    l[lm * 3 + 1] = y;
+    l[lm * 3 + 2] = z;
+}
+
+// A rough T-pose in the MediaPipe world frame (x subject-left, y DOWN,
+// z toward camera), metres, hip-centred.
+Landmarks tPose()
+{
+    Landmarks l{};
+    set(l, 0, 0.f, -0.65f, -0.10f);     // nose
+    set(l, 7, 0.08f, -0.62f, 0.02f);    // left ear
+    set(l, 8, -0.08f, -0.62f, 0.02f);   // right ear
+    set(l, 11, 0.18f, -0.45f, 0.f);     // left shoulder
+    set(l, 12, -0.18f, -0.45f, 0.f);    // right shoulder
+    set(l, 13, 0.45f, -0.45f, 0.f);     // left elbow (arm out)
+    set(l, 14, -0.45f, -0.45f, 0.f);    // right elbow
+    set(l, 15, 0.70f, -0.45f, 0.f);     // left wrist
+    set(l, 16, -0.70f, -0.45f, 0.f);    // right wrist
+    set(l, 23, 0.10f, 0.f, 0.f);        // left hip
+    set(l, 24, -0.10f, 0.f, 0.f);       // right hip
+    set(l, 25, 0.10f, 0.40f, 0.f);      // left knee
+    set(l, 26, -0.10f, 0.40f, 0.f);     // right knee
+    set(l, 27, 0.10f, 0.80f, 0.f);      // left ankle
+    set(l, 28, -0.10f, 0.80f, 0.f);     // right ankle
+    set(l, 31, 0.10f, 0.85f, -0.15f);   // left foot index (toes forward)
+    set(l, 32, -0.10f, 0.85f, -0.15f);  // right foot index
+    return l;
+}
+
+double quatAngle(const std::array<float, 4>& a, const std::array<float, 4>& b)
+{
+    double dot = 0;
+    for (int i = 0; i < 4; ++i)
+        dot += static_cast<double>(a[i]) * b[i];
+    return 2.0 * std::acos(std::fmin(1.0, std::fabs(dot)));
+}
+
+}  // namespace
+
+TEST(PoseIKSolver, StaticPoseGivesIdenticalFrames)
+{
+    PoseIK::Solver solver;
+    const Landmarks pose = tPose();
+    const auto f1 = solver.solveFrame(pose.data());
+    const auto f2 = solver.solveFrame(pose.data());
+    for (int r = 0; r < PoseIK::kCanonicalRoles; ++r) {
+        if (!f1.resolved(r))
+            continue;
+        EXPECT_TRUE(f2.resolved(r)) << "role " << r;
+        EXPECT_LT(quatAngle(f1.quats[r], f2.quats[r]), 1e-4)
+            << "role " << r << " drifted between identical frames";
+    }
+    // core roles resolve on a full-visibility T-pose
+    for (int r : {PoseIK::Hip, PoseIK::Chest, PoseIK::Head, PoseIK::RShoulder,
+                  PoseIK::RElbow, PoseIK::LShoulder, PoseIK::LElbow,
+                  PoseIK::RHip, PoseIK::RKnee, PoseIK::LHip, PoseIK::LKnee})
+        EXPECT_TRUE(f1.resolved(r)) << "role " << r;
+}
+
+TEST(PoseIKSolver, ElbowBendRecoversNinetyDegrees)
+{
+    PoseIK::Solver solver;
+    Landmarks pose = tPose();
+    const auto f1 = solver.solveFrame(pose.data());
+
+    // bend the left forearm 90 degrees at the elbow: wrist moves from
+    // straight-out (+x) to straight-forward (toward the camera, +z in
+    // MediaPipe's frame is BEHIND, so forward = -z... use -z)
+    set(pose, 15, 0.45f, -0.45f, -0.25f);
+    const auto f2 = solver.solveFrame(pose.data());
+
+    ASSERT_TRUE(f1.resolved(PoseIK::LElbow));
+    ASSERT_TRUE(f2.resolved(PoseIK::LElbow));
+    const double bend = quatAngle(f1.quats[PoseIK::LElbow],
+                                  f2.quats[PoseIK::LElbow]);
+    EXPECT_NEAR(bend, M_PI / 2.0, 0.05);
+    // the upper arm did not move
+    EXPECT_LT(quatAngle(f1.quats[PoseIK::LShoulder],
+                        f2.quats[PoseIK::LShoulder]), 1e-3);
+}
+
+TEST(PoseIKSolver, TorsoTwistShowsOnChestNotHips)
+{
+    PoseIK::Solver solver;
+    Landmarks pose = tPose();
+    const auto f1 = solver.solveFrame(pose.data());
+
+    // rotate the shoulder line ~30 degrees about the vertical axis
+    const float c = std::cos(0.5236f), s = std::sin(0.5236f);
+    auto yaw = [&](int lm) {
+        const float x = pose[lm * 3 + 0];
+        const float z = pose[lm * 3 + 2];
+        pose[lm * 3 + 0] = c * x - s * z;
+        pose[lm * 3 + 2] = s * x + c * z;
+    };
+    yaw(11);
+    yaw(12);
+    const auto f2 = solver.solveFrame(pose.data());
+
+    const double chestDelta = quatAngle(f1.quats[PoseIK::Chest],
+                                        f2.quats[PoseIK::Chest]);
+    const double hipDelta = quatAngle(f1.quats[PoseIK::Hip],
+                                      f2.quats[PoseIK::Hip]);
+    EXPECT_NEAR(chestDelta, 0.5236, 0.06);
+    EXPECT_LT(hipDelta, 0.01);  // hips stayed put
+}
+
+TEST(PoseIKSolver, ContinuityWhileArmSweeps)
+{
+    // sweep the left arm from T-pose down to the side in small steps; the
+    // parallel-transported twist reference must keep consecutive frames close
+    PoseIK::Solver solver;
+    Landmarks pose = tPose();
+    auto prev = solver.solveFrame(pose.data());
+    for (int step = 1; step <= 20; ++step) {
+        const float a = step * (static_cast<float>(M_PI) / 2.f) / 20.f;
+        // elbow + wrist rotate about the shoulder in the frontal plane
+        set(pose, 13, 0.18f + 0.27f * std::cos(a), -0.45f + 0.27f * std::sin(a), 0.f);
+        set(pose, 15, 0.18f + 0.52f * std::cos(a), -0.45f + 0.52f * std::sin(a), 0.f);
+        const auto cur = solver.solveFrame(pose.data());
+        EXPECT_LT(quatAngle(prev.quats[PoseIK::LShoulder],
+                            cur.quats[PoseIK::LShoulder]), 0.25)
+            << "jump at step " << step;
+        prev = cur;
+    }
+    // total travel is ~90 degrees
+    PoseIK::Solver fresh;
+    Landmarks tp = tPose();
+    const auto f0 = fresh.solveFrame(tp.data());
+    EXPECT_NEAR(quatAngle(f0.quats[PoseIK::LShoulder],
+                          prev.quats[PoseIK::LShoulder]), M_PI / 2.0, 0.1);
+}
+
+TEST(PoseIKSolver, DegenerateInputDoesNotNaN)
+{
+    PoseIK::Solver solver;
+    Landmarks zeros{};
+    const auto f = solver.solveFrame(zeros.data());
+    EXPECT_EQ(f.resolvedMask, 0u);  // nothing resolvable
+    for (const auto& q : f.quats)
+        for (float c : q)
+            EXPECT_TRUE(std::isfinite(c));
+}
+
+TEST(PoseIKSolver, LowVisibilityInvalidatesRoles)
+{
+    PoseIK::Solver solver;
+    const Landmarks pose = tPose();
+    std::array<float, PoseIK::kLandmarkCount> vis;
+    vis.fill(1.f);
+    vis[15] = 0.05f;  // left wrist invisible
+    const auto f = solver.solveFrame(pose.data(), vis.data());
+    EXPECT_FALSE(f.resolved(PoseIK::LElbow));   // needs the wrist
+    EXPECT_TRUE(f.resolved(PoseIK::LShoulder)); // shoulder->elbow unaffected
+}
+
+#endif  // ENABLE_MOCAP
diff --git a/src/Mocap/VideoFrameSource.cpp b/src/Mocap/VideoFrameSource.cpp
new file mode 100644
index 000000000..6fcfb8eef
--- /dev/null
+++ b/src/Mocap/VideoFrameSource.cpp
@@ -0,0 +1,300 @@
+#ifdef ENABLE_MOCAP
+
+#include "VideoFrameSource.h"
+
+#include <QCamera>
+#include <QCameraDevice>
+#include <QElapsedTimer>
+#include <QFileInfo>
+#include <QMediaCaptureSession>
+#include <QMediaDevices>
+#include <QMediaMetaData>
+#include <QMediaPlayer>
+#include <QUrl>
+#include <QVideoFrame>
+#include <QVideoSink>
+
+namespace {
+// Queued frameReady connections (capture thread -> worker) need the metatype.
+struct MocapMetaTypeRegistrar {
+    MocapMetaTypeRegistrar() { qRegisterMetaType<MocapFrame>("MocapFrame"); }
+};
+const MocapMetaTypeRegistrar registrar;
+}  // namespace
+
+QImage mocapFrameToRgb888(const QImage& image)
+{
+    if (image.format() == QImage::Format_RGB888)
+        return image;
+    return image.convertToFormat(QImage::Format_RGB888);
+}
+
+// ---------------------------------------------------------------------------
+// ImageSequenceFrameSource
+// ---------------------------------------------------------------------------
+
+ImageSequenceFrameSource::ImageSequenceFrameSource(const QStringList& imagePaths,
+                                                   double fps, double targetFps,
+                                                   QObject* parent)
+    : VideoFrameSource(parent),
+      m_paths(imagePaths),
+      m_fps(fps > 0.0 ? fps : 30.0),
+      m_decimator(targetFps)
+{
+}
+
+bool ImageSequenceFrameSource::open(QString* error)
+{
+    if (m_paths.isEmpty()) {
+        if (error) *error = tr("image sequence is empty");
+        return false;
+    }
+    for (const QString& p : m_paths) {
+        if (!QFileInfo::exists(p)) {
+            if (error) *error = tr("image not found: %1").arg(p);
+            return false;
+        }
+    }
+    return true;
+}
+
+void ImageSequenceFrameSource::start()
+{
+    m_stopped = false;
+    m_decimator.reset();
+    for (qint64 i = 0; i < m_paths.size() && !m_stopped; ++i) {
+        const double t = static_cast<double>(i) / m_fps;
+        if (!m_decimator.shouldEmit(t))
+            continue;
+        QImage img(m_paths.at(i));
+        if (img.isNull()) {
+            emit errorOccurred(tr("failed to load image: %1").arg(m_paths.at(i)));
+            return;
+        }
+        MocapFrame frame;
+        frame.image = mocapFrameToRgb888(img);
+        frame.timeSec = t;
+        frame.frameIndex = i;
+        emit frameReady(frame);
+    }
+    if (!m_stopped)
+        emit finished();
+}
+
+void ImageSequenceFrameSource::stop()
+{
+    m_stopped = true;
+}
+
+// ---------------------------------------------------------------------------
+// FileFrameSource
+// ---------------------------------------------------------------------------
+
+FileFrameSource::FileFrameSource(const QString& filePath, double targetFps,
+                                 QObject* parent)
+    : VideoFrameSource(parent), m_path(filePath), m_decimator(targetFps)
+{
+}
+
+FileFrameSource::~FileFrameSource()
+{
+    stop();
+    // Tear down in dependency order: the player holds the sink pointer via
+    // setVideoSink(), so it must die (or be unbound) BEFORE the sink. Member
+    // destruction runs in reverse declaration order (m_sink before m_player),
+    // which would leave the player briefly pointing at a freed sink — reset
+    // the player first here.
+    if (m_player) {
+        m_player->setVideoSink(nullptr);
+        m_player.reset();
+    }
+    m_sink.reset();
+}
+
+bool FileFrameSource::open(QString* error)
+{
+    if (!QFileInfo::exists(m_path)) {
+        if (error) *error = tr("video file not found: %1").arg(m_path);
+        return false;
+    }
+    m_player = std::make_unique<QMediaPlayer>();
+    m_sink = std::make_unique<QVideoSink>();
+    m_player->setVideoSink(m_sink.get());
+
+    connect(m_sink.get(), &QVideoSink::videoFrameChanged, this,
+            &FileFrameSource::handleVideoFrame);
+    connect(m_player.get(), &QMediaPlayer::mediaStatusChanged, this,
+            [this](QMediaPlayer::MediaStatus status) {
+                if (status == QMediaPlayer::EndOfMedia && !m_finishedEmitted) {
+                    m_finishedEmitted = true;
+                    emit finished();
+                }
+                if (status == QMediaPlayer::LoadedMedia) {
+                    const auto rate = m_player->metaData()
+                                          .value(QMediaMetaData::VideoFrameRate);
+                    if (rate.isValid())
+                        m_nativeFps = rate.toDouble();
+                }
+            });
+    connect(m_player.get(), &QMediaPlayer::errorOccurred, this,
+            [this](QMediaPlayer::Error, const QString& message) {
+                emit errorOccurred(tr("video decode error: %1").arg(message));
+            });
+
+    m_player->setSource(QUrl::fromLocalFile(m_path));
+    return true;
+}
+
+void FileFrameSource::start()
+{
+    if (!m_player) {
+        emit errorOccurred(tr("start() before open()"));
+        return;
+    }
+    m_decimator.reset();
+    m_frameIndex = 0;
+    m_finishedEmitted = false;
+    m_player->play();
+}
+
+void FileFrameSource::stop()
+{
+    if (m_player)
+        m_player->stop();
+}
+
+void FileFrameSource::handleVideoFrame()
+{
+    const QVideoFrame vf = m_sink->videoFrame();
+    if (!vf.isValid())
+        return;
+    const qint64 index = m_frameIndex++;
+    // Prefer the frame's own timestamp; fall back to the player clock.
+    double t = vf.startTime() >= 0
+                   ? vf.startTime() / 1e6
+                   : (m_player ? m_player->position() / 1e3 : 0.0);
+    if (!m_decimator.shouldEmit(t))
+        return;
+    MocapFrame frame;
+    frame.image = mocapFrameToRgb888(vf.toImage());
+    frame.timeSec = t;
+    frame.frameIndex = index;
+    if (!frame.image.isNull())
+        emitFrame(frame);   // -> frameReady() + mailbox (worker-thread preview)
+}
+
+// ---------------------------------------------------------------------------
+// CameraFrameSource
+// ---------------------------------------------------------------------------
+
+QList<CameraFrameSource::DeviceInfo> CameraFrameSource::availableDevices()
+{
+    QList<DeviceInfo> out;
+    const auto devices = QMediaDevices::videoInputs();
+    for (const QCameraDevice& d : devices)
+        out.append({QString::fromUtf8(d.id()), d.description()});
+    return out;
+}
+
+CameraFrameSource::CameraFrameSource(const QString& deviceId, QObject* parent)
+    : VideoFrameSource(parent), m_deviceId(deviceId)
+{
+}
+
+CameraFrameSource::~CameraFrameSource()
+{
+    stop();
+    // The capture session references the sink via setVideoSink(); detach and
+    // destroy the session (and camera) BEFORE the sink. Member destruction
+    // runs in reverse declaration order (m_sink before m_session), so do it
+    // explicitly here.
+    if (m_session)
+        m_session->setVideoSink(nullptr);
+    m_camera.reset();
+    m_session.reset();
+    m_sink.reset();
+}
+
+bool CameraFrameSource::open(QString* error)
+{
+    QCameraDevice device;
+    const auto devices = QMediaDevices::videoInputs();
+    if (m_deviceId.isEmpty()) {
+        device = QMediaDevices::defaultVideoInput();
+    } else {
+        for (const QCameraDevice& d : devices) {
+            if (QString::fromUtf8(d.id()) == m_deviceId) {
+                device = d;
+                break;
+            }
+        }
+    }
+    if (device.isNull()) {
+        if (error)
+            *error = devices.isEmpty()
+                         ? tr("no camera available")
+                         : tr("camera not found: %1").arg(m_deviceId);
+        return false;
+    }
+
+    m_camera = std::make_unique<QCamera>(device);
+    m_session = std::make_unique<QMediaCaptureSession>();
+    m_sink = std::make_unique<QVideoSink>();
+    m_session->setCamera(m_camera.get());
+    m_session->setVideoSink(m_sink.get());
+    m_clock = std::make_unique<QElapsedTimer>();
+
+    const auto formats = device.videoFormats();
+    if (!formats.isEmpty())
+        m_nativeFps = formats.first().maxFrameRate();
+
+    connect(m_sink.get(), &QVideoSink::videoFrameChanged, this,
+            &CameraFrameSource::handleVideoFrame);
+    connect(m_camera.get(), &QCamera::errorOccurred, this,
+            [this](QCamera::Error err, const QString& message) {
+                if (err == QCamera::CameraError && message.contains(
+                        QStringLiteral("permission"), Qt::CaseInsensitive)) {
+                    emit errorOccurred(tr("camera permission denied — allow "
+                                          "camera access for QtMeshEditor in "
+                                          "the system settings"));
+                } else {
+                    emit errorOccurred(tr("camera error: %1").arg(message));
+                }
+            });
+    return true;
+}
+
+void CameraFrameSource::start()
+{
+    if (!m_camera) {
+        emit errorOccurred(tr("start() before open()"));
+        return;
+    }
+    m_frameIndex = 0;
+    m_clock->start();
+    m_camera->start();
+}
+
+void CameraFrameSource::stop()
+{
+    if (m_camera)
+        m_camera->stop();
+}
+
+void CameraFrameSource::handleVideoFrame()
+{
+    const QVideoFrame vf = m_sink->videoFrame();
+    if (!vf.isValid())
+        return;
+    MocapFrame frame;
+    frame.image = mocapFrameToRgb888(vf.toImage());
+    if (frame.image.isNull())
+        return;
+    frame.timeSec = m_clock->isValid() ? m_clock->elapsed() / 1e3 : 0.0;
+    frame.frameIndex = m_frameIndex++;
+    // Latest-wins for the inference consumer; the signal serves lightweight
+    // observers (preview HUD) that keep up with the camera.
+    emitFrame(frame);
+}
+
+#endif  // ENABLE_MOCAP
diff --git a/src/Mocap/VideoFrameSource.h b/src/Mocap/VideoFrameSource.h
new file mode 100644
index 000000000..fd7f8f023
--- /dev/null
+++ b/src/Mocap/VideoFrameSource.h
@@ -0,0 +1,231 @@
+#ifndef VIDEOFRAMESOURCE_H
+#define VIDEOFRAMESOURCE_H
+
+// Performance capture frame sources (epic #869, Slice B #871).
+//
+// One abstraction delivers timestamped RGB888 frames from (a) a video file,
+// (b) a live camera, (c) an image sequence (the headless test double / the
+// CLI --frames-dir debug path) — so the predictors and controllers never
+// touch Qt Multimedia directly. Everything in this header is compiled only
+// under ENABLE_MOCAP (src/CMakeLists.txt adds the .cpp behind the flag).
+
+#ifdef ENABLE_MOCAP
+
+#include <QImage>
+#include <QMetaType>
+#include <QObject>
+#include <QStringList>
+
+#include <memory>
+#include <mutex>
+
+class QCamera;
+class QElapsedTimer;
+class QMediaCaptureSession;
+class QMediaPlayer;
+class QVideoSink;
+
+// One decoded frame. image is guaranteed Format_RGB888.
+struct MocapFrame {
+    QImage image;
+    double timeSec = 0.0;   // media timestamp (file/sequence) or wall-clock since start (camera)
+    qint64 frameIndex = 0;  // source frame counter (pre-decimation)
+};
+Q_DECLARE_METATYPE(MocapFrame)
+
+// Drops frames so a source delivering at native fps emits ~targetFps.
+// Pure data — unit-tested headless. targetFps <= 0 disables decimation.
+class FrameDecimator {
+public:
+    explicit FrameDecimator(double targetFps = 0.0) : m_targetFps(targetFps) {}
+
+    // Called with each frame's timestamp (monotonically increasing); returns
+    // true when the frame should be emitted. The first frame always passes.
+    // Tolerates timestamps landing half a source-frame early so 60 -> 30 fps
+    // emits exactly every other frame instead of every third.
+    bool shouldEmit(double timeSec)
+    {
+        if (m_targetFps <= 0.0)
+            return true;
+        const double interval = 1.0 / m_targetFps;
+        if (m_hasEmitted && timeSec - m_lastEmitted < interval * 0.75)
+            return false;
+        m_hasEmitted = true;
+        m_lastEmitted = timeSec;
+        return true;
+    }
+
+    void reset() { m_hasEmitted = false; m_lastEmitted = 0.0; }
+
+private:
+    double m_targetFps;
+    double m_lastEmitted = 0.0;
+    bool m_hasEmitted = false;
+};
+
+// Latest-wins single-slot mailbox between the capture thread and a (slower)
+// inference consumer: a new frame REPLACES any undelivered pending frame, so
+// live inference never falls behind the camera. Thread-safe; unit-tested.
+class FrameMailbox {
+public:
+    void put(const MocapFrame& frame)
+    {
+        std::lock_guard<std::mutex> lock(m_mutex);
+        if (m_hasPending)
+            ++m_dropped;
+        m_pending = frame;
+        m_hasPending = true;
+    }
+
+    // Takes the newest pending frame, if any. Returns false when empty.
+    bool take(MocapFrame* out)
+    {
+        std::lock_guard<std::mutex> lock(m_mutex);
+        if (!m_hasPending)
+            return false;
+        *out = m_pending;
+        m_pending = MocapFrame{};  // release the QImage
+        m_hasPending = false;
+        return true;
+    }
+
+    // Frames overwritten before a consumer took them (diagnostics/HUD).
+    qint64 droppedCount() const
+    {
+        std::lock_guard<std::mutex> lock(m_mutex);
+        return m_dropped;
+    }
+
+private:
+    mutable std::mutex m_mutex;
+    MocapFrame m_pending;
+    bool m_hasPending = false;
+    qint64 m_dropped = 0;
+};
+
+// Guarantees Format_RGB888 (the input contract of every mocap predictor).
+QImage mocapFrameToRgb888(const QImage& image);
+
+class VideoFrameSource : public QObject {
+    Q_OBJECT
+public:
+    explicit VideoFrameSource(QObject* parent = nullptr) : QObject(parent) {}
+    ~VideoFrameSource() override = default;
+
+    // Prepare the source. Returns false and fills *error on failure.
+    virtual bool open(QString* error) = 0;
+    virtual void start() = 0;
+    virtual void stop() = 0;
+    virtual bool isLive() const = 0;
+    virtual double nativeFps() const = 0;  // 0 if unknown
+
+    // Latest-wins mailbox for the (slower) inference consumer running on a
+    // worker thread. Live camera AND file playback both feed it — the live
+    // GUI preview drops intermediate frames either way (real-time). Sources
+    // that emit frames write via emitFrame() below, which both signals
+    // frameReady() and posts to this mailbox.
+    FrameMailbox& mailbox() { return m_mailbox; }
+
+signals:
+    void frameReady(const MocapFrame& frame);
+    void finished();                      // file/sequence sources: end of media
+    void errorOccurred(const QString& message);
+
+protected:
+    // Emit a frame to BOTH the frameReady() signal (synchronous consumers /
+    // tests) and the mailbox (worker-thread live preview).
+    void emitFrame(const MocapFrame& frame)
+    {
+        m_mailbox.put(frame);
+        emit frameReady(frame);
+    }
+
+    FrameMailbox m_mailbox;
+};
+
+// (c) Image sequence — synchronous test double. Emits every image on start()
+// with timestamps i/fps, honouring targetFps decimation, then finished().
+class ImageSequenceFrameSource : public VideoFrameSource {
+    Q_OBJECT
+public:
+    ImageSequenceFrameSource(const QStringList& imagePaths, double fps,
+                             double targetFps = 0.0, QObject* parent = nullptr);
+
+    bool open(QString* error) override;
+    void start() override;
+    void stop() override;
+    bool isLive() const override { return false; }
+    double nativeFps() const override { return m_fps; }
+
+private:
+    QStringList m_paths;
+    double m_fps;
+    FrameDecimator m_decimator;
+    bool m_stopped = false;
+};
+
+// (a) Video file — QMediaPlayer + QVideoSink. Playback-driven (real-time;
+// faster-than-realtime decode is a known follow-up, QVideoSink is fed by the
+// player clock). targetFps decimates delivery for offline capture.
+class FileFrameSource : public VideoFrameSource {
+    Q_OBJECT
+public:
+    explicit FileFrameSource(const QString& filePath, double targetFps = 0.0,
+                             QObject* parent = nullptr);
+    ~FileFrameSource() override;
+
+    bool open(QString* error) override;
+    void start() override;
+    void stop() override;
+    bool isLive() const override { return false; }
+    double nativeFps() const override { return m_nativeFps; }
+
+private:
+    void handleVideoFrame();
+
+    QString m_path;
+    FrameDecimator m_decimator;
+    std::unique_ptr<QMediaPlayer> m_player;
+    std::unique_ptr<QVideoSink> m_sink;
+    double m_nativeFps = 0.0;
+    qint64 m_frameIndex = 0;
+    bool m_finishedEmitted = false;
+};
+
+// (b) Live camera — QCamera + QMediaCaptureSession + QVideoSink. Frames are
+// emitted as frameReady AND written into mailbox() (latest-wins) for a
+// slower inference consumer. deviceId empty = default camera.
+class CameraFrameSource : public VideoFrameSource {
+    Q_OBJECT
+public:
+    struct DeviceInfo {
+        QString id;
+        QString description;
+    };
+    // Enumerates video inputs (feeds the GUI picker + MCP list_capture_devices).
+    static QList<DeviceInfo> availableDevices();
+
+    explicit CameraFrameSource(const QString& deviceId = {},
+                               QObject* parent = nullptr);
+    ~CameraFrameSource() override;
+
+    bool open(QString* error) override;
+    void start() override;
+    void stop() override;
+    bool isLive() const override { return true; }
+    double nativeFps() const override { return m_nativeFps; }
+
+private:
+    void handleVideoFrame();
+
+    QString m_deviceId;
+    std::unique_ptr<QCamera> m_camera;
+    std::unique_ptr<QMediaCaptureSession> m_session;
+    std::unique_ptr<QVideoSink> m_sink;
+    std::unique_ptr<QElapsedTimer> m_clock;
+    double m_nativeFps = 0.0;
+    qint64 m_frameIndex = 0;
+};
+
+#endif // ENABLE_MOCAP
+#endif // VIDEOFRAMESOURCE_H
diff --git a/src/Mocap/VideoFrameSource_test.cpp b/src/Mocap/VideoFrameSource_test.cpp
new file mode 100644
index 000000000..e8161599c
--- /dev/null
+++ b/src/Mocap/VideoFrameSource_test.cpp
@@ -0,0 +1,200 @@
+#ifdef ENABLE_MOCAP
+
+#include <gtest/gtest.h>
+
+#include <QDir>
+#include <QImage>
+#include <QSignalSpy>
+#include <QTemporaryDir>
+
+#include <thread>
+#include <vector>
+
+#include "Mocap/VideoFrameSource.h"
+
+namespace {
+
+QStringList writeTestImages(const QString& dir, int count, int size = 8)
+{
+    QStringList paths;
+    for (int i = 0; i < count; ++i) {
+        QImage img(size, size, QImage::Format_ARGB32);
+        img.fill(QColor(i * 10 % 255, 0, 0));
+        const QString p = dir + QStringLiteral("/frame_%1.png").arg(i, 3, 10, QChar('0'));
+        img.save(p);
+        paths << p;
+    }
+    return paths;
+}
+
+}  // namespace
+
+TEST(FrameDecimator, PassesEverythingWhenDisabled)
+{
+    FrameDecimator d(0.0);
+    for (int i = 0; i < 10; ++i)
+        EXPECT_TRUE(d.shouldEmit(i / 60.0));
+}
+
+TEST(FrameDecimator, HalvesSixtyToThirty)
+{
+    FrameDecimator d(30.0);
+    int emitted = 0;
+    for (int i = 0; i < 60; ++i)
+        if (d.shouldEmit(i / 60.0))
+            ++emitted;
+    EXPECT_GE(emitted, 28);
+    EXPECT_LE(emitted, 32);
+}
+
+TEST(FrameDecimator, FirstFrameAlwaysPasses)
+{
+    FrameDecimator d(1.0);
+    EXPECT_TRUE(d.shouldEmit(0.0));
+    EXPECT_FALSE(d.shouldEmit(0.1));
+    d.reset();
+    EXPECT_TRUE(d.shouldEmit(0.1));
+}
+
+TEST(FrameMailbox, LatestWinsDropsIntermediates)
+{
+    FrameMailbox box;
+    for (int i = 0; i < 3; ++i) {
+        MocapFrame f;
+        f.frameIndex = i;
+        box.put(f);
+    }
+    MocapFrame out;
+    ASSERT_TRUE(box.take(&out));
+    EXPECT_EQ(out.frameIndex, 2);       // only the newest survives
+    EXPECT_FALSE(box.take(&out));       // and only once
+    EXPECT_EQ(box.droppedCount(), 2);   // the two overwritten frames
+}
+
+TEST(FrameMailbox, ThreadSafePutTake)
+{
+    FrameMailbox box;
+    std::thread producer([&box] {
+        for (int i = 0; i < 1000; ++i) {
+            MocapFrame f;
+            f.frameIndex = i;
+            box.put(f);
+        }
+    });
+    qint64 last = -1;
+    for (int i = 0; i < 2000; ++i) {
+        MocapFrame out;
+        if (box.take(&out)) {
+            EXPECT_GT(out.frameIndex, last);  // monotone: never re-deliver older
+            last = out.frameIndex;
+        }
+    }
+    producer.join();
+    MocapFrame out;
+    while (box.take(&out))
+        last = out.frameIndex;
+    EXPECT_EQ(last, 999);  // the final frame is never lost
+}
+
+TEST(ImageSequenceFrameSource, EmitsAllFramesInOrderWithTimestamps)
+{
+    QTemporaryDir tmp;
+    ASSERT_TRUE(tmp.isValid());
+    const QStringList paths = writeTestImages(tmp.path(), 5);
+
+    ImageSequenceFrameSource src(paths, 10.0);
+    QString error;
+    ASSERT_TRUE(src.open(&error)) << error.toStdString();
+
+    std::vector<MocapFrame> frames;
+    bool done = false;
+    QObject::connect(&src, &VideoFrameSource::frameReady,
+                     [&frames](const MocapFrame& f) { frames.push_back(f); });
+    QObject::connect(&src, &VideoFrameSource::finished, [&done] { done = true; });
+    src.start();
+
+    ASSERT_TRUE(done);
+    ASSERT_EQ(frames.size(), 5u);
+    for (size_t i = 0; i < frames.size(); ++i) {
+        EXPECT_EQ(frames[i].frameIndex, static_cast<qint64>(i));
+        EXPECT_DOUBLE_EQ(frames[i].timeSec, i / 10.0);
+        EXPECT_EQ(frames[i].image.format(), QImage::Format_RGB888);
+        EXPECT_FALSE(frames[i].image.isNull());
+    }
+}
+
+TEST(ImageSequenceFrameSource, DecimatesToTargetFps)
+{
+    QTemporaryDir tmp;
+    ASSERT_TRUE(tmp.isValid());
+    const QStringList paths = writeTestImages(tmp.path(), 60);
+
+    ImageSequenceFrameSource src(paths, 60.0, /*targetFps=*/30.0);
+    QString error;
+    ASSERT_TRUE(src.open(&error)) << error.toStdString();
+
+    int emitted = 0;
+    QObject::connect(&src, &VideoFrameSource::frameReady,
+                     [&emitted](const MocapFrame&) { ++emitted; });
+    src.start();
+    EXPECT_GE(emitted, 28);
+    EXPECT_LE(emitted, 32);
+}
+
+TEST(ImageSequenceFrameSource, OpenFailsOnMissingFile)
+{
+    ImageSequenceFrameSource src({QStringLiteral("/nonexistent/frame.png")}, 30.0);
+    QString error;
+    EXPECT_FALSE(src.open(&error));
+    EXPECT_FALSE(error.isEmpty());
+}
+
+TEST(ImageSequenceFrameSource, OpenFailsOnEmptyList)
+{
+    ImageSequenceFrameSource src({}, 30.0);
+    QString error;
+    EXPECT_FALSE(src.open(&error));
+    EXPECT_FALSE(error.isEmpty());
+}
+
+TEST(FileFrameSource, OpenFailsOnMissingFile)
+{
+    FileFrameSource src(QStringLiteral("/nonexistent/video.mp4"));
+    QString error;
+    EXPECT_FALSE(src.open(&error));
+    EXPECT_FALSE(error.isEmpty());
+}
+
+// Real camera tests are impossible in CI; enumeration must not crash headless.
+TEST(CameraFrameSource, AvailableDevicesDoesNotCrash)
+{
+    const auto devices = CameraFrameSource::availableDevices();
+    for (const auto& d : devices) {
+        EXPECT_FALSE(d.id.isEmpty());
+    }
+}
+
+TEST(CameraFrameSource, OpenFailsOnBogusDeviceId)
+{
+    if (!qEnvironmentVariableIsSet("QTMESH_MOCAP_CAMERA_TESTS")
+        && CameraFrameSource::availableDevices().isEmpty()) {
+        // headless CI: also exercises the no-camera error path
+    }
+    CameraFrameSource src(QStringLiteral("definitely-not-a-camera-id"));
+    QString error;
+    EXPECT_FALSE(src.open(&error));
+    EXPECT_FALSE(error.isEmpty());
+}
+
+TEST(MocapFrameToRgb888, ConvertsAndPassesThrough)
+{
+    QImage argb(4, 4, QImage::Format_ARGB32);
+    argb.fill(Qt::green);
+    const QImage converted = mocapFrameToRgb888(argb);
+    EXPECT_EQ(converted.format(), QImage::Format_RGB888);
+
+    const QImage same = mocapFrameToRgb888(converted);
+    EXPECT_EQ(same.format(), QImage::Format_RGB888);
+}
+
+#endif  // ENABLE_MOCAP
diff --git a/src/MorphAnimationManager.cpp b/src/MorphAnimationManager.cpp
index 2bf38b5a8..e52af4110 100644
--- a/src/MorphAnimationManager.cpp
+++ b/src/MorphAnimationManager.cpp
@@ -243,29 +243,23 @@ bool isPoseShapeClip(Ogre::Mesh* mesh, const std::string& animName)
 
 } // namespace
 
-bool MorphAnimationManager::setMorphWeightKeyframe(const QString& name,
-                                                   double time, double weight)
+bool MorphAnimationManager::writeWeightKeyOn(Ogre::Entity* entity,
+                                             const std::string& clip,
+                                             const std::string& targetName,
+                                             float time, float weight)
 {
-    assertMainThread();
-    if (name.isEmpty() || time < 0.0) return false;
-
-    auto* sel = SelectionSet::getSingleton();
-    if (!sel) return false;
-    auto ents = sel->getResolvedEntities();
-    if (ents.isEmpty() || !ents.first()) return false;
-    Ogre::Entity* entity = ents.first();
+    if (!entity || targetName.empty() || time < 0.0f) return false;
     Ogre::MeshPtr mesh = entity->getMesh();
     if (!mesh) return false;
 
-    const std::string clip = m_activeMorphClip.toStdString();
-    const int pi = poseIndexForName(mesh.get(), name.toStdString());
+    const int pi = poseIndexForName(mesh.get(), targetName);
     if (pi < 0) return false;
     Ogre::VertexAnimationTrack* track =
-        weightTrackFor(mesh.get(), name.toStdString(), clip, true);
+        weightTrackFor(mesh.get(), targetName, clip, true);
     if (!track) return false;
 
-    const float t = static_cast<float>(time);
-    const float w = std::clamp(static_cast<float>(weight), 0.0f, 1.0f);
+    const float t = time;
+    const float w = std::clamp(weight, 0.0f, 1.0f);
 
     // Update in place if a keyframe already exists at ~t, else create one.
     Ogre::VertexPoseKeyFrame* kf = nullptr;
@@ -286,6 +280,26 @@ bool MorphAnimationManager::setMorphWeightKeyframe(const QString& name,
     Ogre::Animation* anim = mesh->getAnimation(clip);
     if (anim && t > anim->getLength())
         anim->setLength(t);
+    return true;
+}
+
+bool MorphAnimationManager::setMorphWeightKeyframe(const QString& name,
+                                                   double time, double weight)
+{
+    assertMainThread();
+    if (name.isEmpty() || time < 0.0) return false;
+
+    auto* sel = SelectionSet::getSingleton();
+    if (!sel) return false;
+    auto ents = sel->getResolvedEntities();
+    if (ents.isEmpty() || !ents.first()) return false;
+    Ogre::Entity* entity = ents.first();
+
+    const float t = static_cast<float>(time);
+    const float w = std::clamp(static_cast<float>(weight), 0.0f, 1.0f);
+    if (!writeWeightKeyOn(entity, m_activeMorphClip.toStdString(),
+                          name.toStdString(), t, w))
+        return false;
 
     // Refresh the entity's animation-state mirror so the new clip is playable.
     entity->refreshAvailableAnimationState();
diff --git a/src/MorphAnimationManager.h b/src/MorphAnimationManager.h
index b557df797..d843b6d4e 100644
--- a/src/MorphAnimationManager.h
+++ b/src/MorphAnimationManager.h
@@ -125,6 +125,18 @@ class MorphAnimationManager : public QObject
     /// first clip created). Also the glTF export fallback name.
     static const char* kWeightClipName;
 
+    /// Entity-explicit weight-keyframe writer — the core of
+    /// setMorphWeightKeyframe without the SelectionSet/active-clip coupling,
+    /// for batch writers (mocap recording #873) that target a specific entity
+    /// and clip. Handles the shared-track subtlety (targets on the same
+    /// submesh share one VAT_POSE track; only THIS pose's reference at `time`
+    /// is added/updated) and extends the clip length. Does NOT emit signals
+    /// or refresh animation states — callers batch-refresh once via
+    /// `entity->refreshAvailableAnimationState()` after the last key.
+    static bool writeWeightKeyOn(Ogre::Entity* entity, const std::string& clip,
+                                 const std::string& targetName, float time,
+                                 float weight);
+
     /// Make the ACTIVE morph clip the playable animation on the selected entity:
     /// select it in the Animation Control panel + enable its AnimationState so
     /// the timeline scrubs/plays the keyed weights. No-op if it doesn't exist.
diff --git a/src/commands/RecordMocapClipCommand.cpp b/src/commands/RecordMocapClipCommand.cpp
new file mode 100644
index 000000000..9635be02e
--- /dev/null
+++ b/src/commands/RecordMocapClipCommand.cpp
@@ -0,0 +1,270 @@
+#ifdef ENABLE_MOCAP
+
+#include "RecordMocapClipCommand.h"
+
+#include "../Manager.h"
+#include "../NodeAnimationManager.h"
+
+#include <OgreAnimation.h>
+#include <OgreAnimationTrack.h>
+#include <OgreBone.h>
+#include <OgreEntity.h>
+#include <OgreKeyFrame.h>
+#include <OgreMesh.h>
+#include <OgreSceneManager.h>
+#include <OgreSkeletonInstance.h>
+
+#include <QObject>
+
+#include <map>
+#include <utility>
+
+namespace {
+
+Ogre::Entity* findEntity(const std::string& name)
+{
+    auto* mgr = Manager::getSingletonPtr();
+    if (!mgr || !mgr->getSceneMgr())
+        return nullptr;
+    auto* scene = mgr->getSceneMgr();
+    return scene->hasEntity(name) ? scene->getEntity(name) : nullptr;
+}
+
+// serialized VAT_POSE clip: per track handle, keyframes with pose references
+struct VertexClipSnapshot {
+    float length = 0.f;
+    struct Key {
+        float time;
+        std::vector<std::pair<unsigned short, float>> poseRefs;
+    };
+    std::map<unsigned short, std::vector<Key>> tracks;
+};
+
+// serialized bone rotation clip: per bone handle, (time, rotation) keys
+struct BoneClipSnapshot {
+    float length = 0.f;
+    struct Key {
+        float time;
+        Ogre::Quaternion rotation;
+        Ogre::Vector3 translate;
+        Ogre::Vector3 scale;
+    };
+    std::map<unsigned short, std::vector<Key>> tracks;
+};
+
+}  // namespace
+
+struct RecordMocapClipCommand::Snapshots {
+    bool hadWeightClip = false;
+    VertexClipSnapshot weightClip;
+    bool hadHeadBoneClip = false;
+    BoneClipSnapshot headBoneClip;
+};
+
+RecordMocapClipCommand::RecordMocapClipCommand(
+    std::string entityName, std::vector<FaceSample> samples,
+    FaceCapMapper::Mapping mapping, MocapRecorder::FaceRecordOptions options,
+    QUndoCommand* parent)
+    : QUndoCommand(parent),
+      m_entityName(std::move(entityName)),
+      m_samples(std::move(samples)),
+      m_mapping(std::move(mapping)),
+      m_options(options)
+{
+    setText(QObject::tr("Record performance capture '%1'")
+                .arg(options.clipName));
+}
+
+RecordMocapClipCommand::~RecordMocapClipCommand() = default;
+
+void RecordMocapClipCommand::redo()
+{
+    Ogre::Entity* entity = findEntity(m_entityName);
+    if (!entity)
+        return;
+
+    if (!m_snapshotTaken) {
+        m_before = std::make_unique<Snapshots>();
+        Ogre::MeshPtr mesh = entity->getMesh();
+        const std::string clip = m_options.clipName.toStdString();
+        if (mesh && mesh->hasAnimation(clip)) {
+            m_before->hadWeightClip = true;
+            Ogre::Animation* anim = mesh->getAnimation(clip);
+            m_before->weightClip.length = anim->getLength();
+            for (const auto& [handle, track] : anim->_getVertexTrackList()) {
+                auto& keys = m_before->weightClip.tracks[handle];
+                for (unsigned short i = 0; i < track->getNumKeyFrames(); ++i) {
+                    auto* kf = static_cast<Ogre::VertexPoseKeyFrame*>(
+                        track->getKeyFrame(i));
+                    VertexClipSnapshot::Key key;
+                    key.time = kf->getTime();
+                    for (const auto& ref : kf->getPoseReferences())
+                        key.poseRefs.push_back({ref.poseIndex, ref.influence});
+                    keys.push_back(std::move(key));
+                }
+            }
+        }
+        const std::string headClip =
+            (m_options.clipName + QStringLiteral("_Head")).toStdString();
+        if (entity->hasSkeleton()
+            && entity->getMesh()->getSkeleton()->hasAnimation(headClip)) {
+            m_before->hadHeadBoneClip = true;
+            Ogre::Animation* anim =
+                entity->getMesh()->getSkeleton()->getAnimation(headClip);
+            m_before->headBoneClip.length = anim->getLength();
+            for (const auto& [handle, track] : anim->_getNodeTrackList()) {
+                auto& keys = m_before->headBoneClip.tracks[handle];
+                for (unsigned short i = 0; i < track->getNumKeyFrames(); ++i) {
+                    auto* kf = static_cast<Ogre::TransformKeyFrame*>(
+                        track->getKeyFrame(i));
+                    keys.push_back({kf->getTime(), kf->getRotation(),
+                                    kf->getTranslate(), kf->getScale()});
+                }
+            }
+        }
+        m_snapshotTaken = true;
+    }
+
+    m_report = MocapRecorder::recordFace(entity, m_samples, m_mapping, m_options);
+}
+
+void RecordMocapClipCommand::undo()
+{
+    Ogre::Entity* entity = findEntity(m_entityName);
+    if (!entity || !m_before)
+        return;
+
+    Ogre::MeshPtr mesh = entity->getMesh();
+    const std::string clip = m_options.clipName.toStdString();
+    if (mesh && mesh->hasAnimation(clip))
+        mesh->removeAnimation(clip);
+    if (mesh && m_before->hadWeightClip) {
+        Ogre::Animation* anim =
+            mesh->createAnimation(clip, m_before->weightClip.length);
+        for (const auto& [handle, keys] : m_before->weightClip.tracks) {
+            auto* track = anim->createVertexTrack(handle, Ogre::VAT_POSE);
+            for (const auto& key : keys) {
+                auto* kf = track->createVertexPoseKeyFrame(key.time);
+                for (const auto& [poseIndex, influence] : key.poseRefs)
+                    kf->addPoseReference(poseIndex, influence);
+            }
+        }
+    }
+
+    const std::string headClip =
+        (m_options.clipName + QStringLiteral("_Head")).toStdString();
+    if (entity->hasSkeleton()) {
+        Ogre::SkeletonPtr skel = entity->getMesh()->getSkeleton();
+        if (skel->hasAnimation(headClip))
+            skel->removeAnimation(headClip);
+        if (m_before->hadHeadBoneClip) {
+            Ogre::Animation* anim =
+                skel->createAnimation(headClip, m_before->headBoneClip.length);
+            for (const auto& [handle, keys] : m_before->headBoneClip.tracks) {
+                auto* track =
+                    anim->createNodeTrack(handle, skel->getBone(handle));
+                for (const auto& key : keys) {
+                    auto* kf = track->createNodeKeyFrame(key.time);
+                    kf->setRotation(key.rotation);
+                    kf->setTranslate(key.translate);
+                    kf->setScale(key.scale);
+                }
+            }
+        }
+    }
+    // node-TRS head clip (static meshes): scene-level, owned by
+    // NodeAnimationManager — a recorded node clip is simply deleted. This is
+    // safe because recordFace REJECTS a name collision with a pre-existing
+    // node clip (report.headError set, headTarget != "node") rather than
+    // overwriting it, so a "node" headTarget always means we created it fresh
+    // this record — there is nothing of the user's to restore.
+    if (m_report.headTarget == QLatin1String("node")) {
+        if (auto* nam = NodeAnimationManager::instance())
+            nam->deleteClip(m_options.clipName + QStringLiteral("_Head"));
+    }
+
+    entity->refreshAvailableAnimationState();
+}
+
+// ---------------------------------------------------------------------------
+// RecordBodyClipCommand (Slice E #874)
+// ---------------------------------------------------------------------------
+
+struct RecordBodyClipCommand::Snapshot {
+    bool hadClip = false;
+    BoneClipSnapshot clip;
+};
+
+RecordBodyClipCommand::RecordBodyClipCommand(
+    std::string entityName,
+    std::vector<std::vector<std::array<float, 4>>> clipQuats, int fps,
+    MocapRecorder::BodyRecordOptions options, QUndoCommand* parent)
+    : QUndoCommand(parent),
+      m_entityName(std::move(entityName)),
+      m_clipQuats(std::move(clipQuats)),
+      m_fps(fps),
+      m_options(std::move(options))
+{
+    setText(QObject::tr("Record body capture '%1'").arg(m_options.clipName));
+}
+
+RecordBodyClipCommand::~RecordBodyClipCommand() = default;
+
+void RecordBodyClipCommand::redo()
+{
+    Ogre::Entity* entity = findEntity(m_entityName);
+    if (!entity)
+        return;
+
+    if (!m_snapshotTaken) {
+        m_before = std::make_unique<Snapshot>();
+        const std::string clip = m_options.clipName.toStdString();
+        if (entity->hasSkeleton()
+            && entity->getMesh()->getSkeleton()->hasAnimation(clip)) {
+            m_before->hadClip = true;
+            Ogre::Animation* anim =
+                entity->getMesh()->getSkeleton()->getAnimation(clip);
+            m_before->clip.length = anim->getLength();
+            for (const auto& [handle, track] : anim->_getNodeTrackList()) {
+                auto& keys = m_before->clip.tracks[handle];
+                for (unsigned short i = 0; i < track->getNumKeyFrames(); ++i) {
+                    auto* kf = static_cast<Ogre::TransformKeyFrame*>(
+                        track->getKeyFrame(i));
+                    keys.push_back({kf->getTime(), kf->getRotation(),
+                                    kf->getTranslate(), kf->getScale()});
+                }
+            }
+        }
+        m_snapshotTaken = true;
+    }
+
+    m_report = MocapRecorder::recordBody(entity, m_clipQuats, m_fps, m_options);
+}
+
+void RecordBodyClipCommand::undo()
+{
+    Ogre::Entity* entity = findEntity(m_entityName);
+    if (!entity || !m_before || !entity->hasSkeleton())
+        return;
+
+    Ogre::SkeletonPtr skel = entity->getMesh()->getSkeleton();
+    const std::string clip = m_options.clipName.toStdString();
+    if (skel->hasAnimation(clip))
+        skel->removeAnimation(clip);
+    if (m_before->hadClip) {
+        Ogre::Animation* anim =
+            skel->createAnimation(clip, m_before->clip.length);
+        for (const auto& [handle, keys] : m_before->clip.tracks) {
+            auto* track = anim->createNodeTrack(handle, skel->getBone(handle));
+            for (const auto& key : keys) {
+                auto* kf = track->createNodeKeyFrame(key.time);
+                kf->setRotation(key.rotation);
+                kf->setTranslate(key.translate);
+                kf->setScale(key.scale);
+            }
+        }
+    }
+    entity->refreshAvailableAnimationState();
+}
+
+#endif  // ENABLE_MOCAP
diff --git a/src/commands/RecordMocapClipCommand.h b/src/commands/RecordMocapClipCommand.h
new file mode 100644
index 000000000..b734dd38b
--- /dev/null
+++ b/src/commands/RecordMocapClipCommand.h
@@ -0,0 +1,83 @@
+#ifndef RECORD_MOCAP_CLIP_COMMAND_H
+#define RECORD_MOCAP_CLIP_COMMAND_H
+
+// Undoable wrapper around MocapRecorder::recordFace (epic #869, Slice D
+// #873): a recorded take — potentially thousands of weight keyframes plus a
+// head clip — is ONE undo step.
+//
+// First redo() snapshots the pre-existing clips (the mesh VAT_POSE weight
+// clip, the "<clip>_Head" skeletal clip, and the scene-level node clip, each
+// of which may or may not exist) and runs the recorder with the samples the
+// command owns. undo() removes the recorded clips and restores the snapshots
+// keyframe-for-keyframe. Subsequent redo()s re-run the recorder on the same
+// inputs (deterministic).
+//
+// Only compiled under ENABLE_MOCAP (the recorder doesn't exist otherwise).
+
+#ifdef ENABLE_MOCAP
+
+#include <QUndoCommand>
+
+#include "../Mocap/FaceCapMapper.h"
+#include "../Mocap/MocapRecorder.h"
+
+#include <string>
+#include <vector>
+
+class RecordMocapClipCommand : public QUndoCommand
+{
+public:
+    RecordMocapClipCommand(std::string entityName,
+                           std::vector<FaceSample> samples,
+                           FaceCapMapper::Mapping mapping,
+                           MocapRecorder::FaceRecordOptions options,
+                           QUndoCommand* parent = nullptr);
+    ~RecordMocapClipCommand() override;
+
+    void undo() override;
+    void redo() override;
+
+    const MocapRecorder::FaceRecordReport& report() const { return m_report; }
+
+private:
+    struct Snapshots;
+
+    std::string m_entityName;
+    std::vector<FaceSample> m_samples;
+    FaceCapMapper::Mapping m_mapping;
+    MocapRecorder::FaceRecordOptions m_options;
+    MocapRecorder::FaceRecordReport m_report;
+    std::unique_ptr<Snapshots> m_before;
+    bool m_snapshotTaken = false;
+};
+
+// Body-take variant (Slice E #874): one undo step around
+// MocapRecorder::recordBody. Snapshots the pre-existing skeletal clip.
+class RecordBodyClipCommand : public QUndoCommand
+{
+public:
+    RecordBodyClipCommand(std::string entityName,
+                          std::vector<std::vector<std::array<float, 4>>> clipQuats,
+                          int fps, MocapRecorder::BodyRecordOptions options,
+                          QUndoCommand* parent = nullptr);
+    ~RecordBodyClipCommand() override;
+
+    void undo() override;
+    void redo() override;
+
+    const MocapRecorder::BodyRecordReport& report() const { return m_report; }
+
+private:
+    struct Snapshot;
+
+    std::string m_entityName;
+    std::vector<std::vector<std::array<float, 4>>> m_clipQuats;
+    int m_fps;
+    MocapRecorder::BodyRecordOptions m_options;
+    MocapRecorder::BodyRecordReport m_report;
+    std::unique_ptr<Snapshot> m_before;
+    bool m_snapshotTaken = false;
+};
+
+#endif  // ENABLE_MOCAP
+#endif  // RECORD_MOCAP_CLIP_COMMAND_H
diff --git a/src/mainwindow.cpp b/src/mainwindow.cpp
index d6e068f6d..3f2fa4782 100755
--- a/src/mainwindow.cpp
+++ b/src/mainwindow.cpp
@@ -140,6 +140,7 @@
 #include "ThemeManager.h"
 #include "IsometricSpritesController.h"
 #include "ImageTo3D/MeshGenController.h"
+#include "Mocap/MocapController.h"
 #include "MorphAnimationManager.h"
 #include "VertexAnimationManager.h"
 #include "EditorModeController.h"
@@ -583,6 +584,7 @@ MainWindow::~MainWindow()
         ViewportLightSoloController::kill();
         IsometricSpritesController::kill();
         MeshGenController::kill();
+        MocapController::kill();
         MeshDepthRenderer::shutdown();
         MeshValidator::kill();
         MaterialPresetLibrary::kill();
@@ -769,6 +771,11 @@ void MainWindow::initToolBar()
             [](QQmlEngine* engine, QJSEngine*) -> QObject* {
                 return SkinWeightsController::qmlInstance(engine, nullptr);
             });
+        qmlRegisterSingletonType<MocapController>(
+            "PropertiesPanel", 1, 0, "MocapController",
+            [](QQmlEngine* engine, QJSEngine*) -> QObject* {
+                return MocapController::qmlInstance(engine, nullptr);
+            });
         qmlRegisterSingletonType<FaceRigController>(
             "PropertiesPanel", 1, 0, "FaceRigController",
             [](QQmlEngine* engine, QJSEngine*) -> QObject* {
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index 49fb59587..d147d0c16 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -89,6 +89,22 @@ if(BUILD_TESTS)
         ${CMAKE_CURRENT_SOURCE_DIR}/../src/FaceRig/FaceRigAttach.cpp
         ${CMAKE_CURRENT_SOURCE_DIR}/../src/FaceRig/FaceLandmarkDetector.cpp
         ${CMAKE_CURRENT_SOURCE_DIR}/../src/FaceRig/FaceRigLandmarks.cpp
+        # Performance capture (#869): MCPServer/CLIPipeline/mainwindow
+        # reference these too. The .cpp files self-guard with #ifdef
+        # ENABLE_MOCAP (empty TU when off), so listing them unconditionally is
+        # safe and keeps the per-suite test executables linking either way.
+        ${CMAKE_CURRENT_SOURCE_DIR}/../src/Mocap/VideoFrameSource.cpp
+        ${CMAKE_CURRENT_SOURCE_DIR}/../src/Mocap/OneEuroFilter.cpp
+        ${CMAKE_CURRENT_SOURCE_DIR}/../src/Mocap/FaceCapMapper.cpp
+        ${CMAKE_CURRENT_SOURCE_DIR}/../src/Mocap/FaceCapPose.cpp
+        ${CMAKE_CURRENT_SOURCE_DIR}/../src/Mocap/FaceCapGeom.cpp
+        ${CMAKE_CURRENT_SOURCE_DIR}/../src/Mocap/FaceCapPredictor.cpp
+        ${CMAKE_CURRENT_SOURCE_DIR}/../src/Mocap/MocapRecorder.cpp
+        ${CMAKE_CURRENT_SOURCE_DIR}/../src/Mocap/PoseCapPredictor.cpp
+        ${CMAKE_CURRENT_SOURCE_DIR}/../src/Mocap/PoseIKSolver.cpp
+        ${CMAKE_CURRENT_SOURCE_DIR}/../src/Mocap/MocapCLI.cpp
+        ${CMAKE_CURRENT_SOURCE_DIR}/../src/Mocap/MocapController.cpp
+        ${CMAKE_CURRENT_SOURCE_DIR}/../src/commands/RecordMocapClipCommand.cpp
         ${CMAKE_CURRENT_SOURCE_DIR}/../src/MCPServer.cpp
         ${CMAKE_CURRENT_SOURCE_DIR}/../src/MCPSettingsDialog.cpp
         ${CMAKE_CURRENT_SOURCE_DIR}/../src/MeshInfoOverlay.cpp
@@ -599,6 +615,15 @@ ${CMAKE_CURRENT_SOURCE_DIR}/../src/PS1/runtime/MeshReconstructorTexKeys.cpp
         target_link_libraries(qtmesh_test_common PUBLIC advapi32)
     endif()
 
+    # Performance capture (#869): the Mocap frame sources include Qt
+    # Multimedia headers (QCamera/QMediaPlayer/QVideoSink). The main build
+    # links Qt6::Multimedia into UnitTests under ENABLE_MOCAP; do the same for
+    # the per-suite test library so MCPServer/mainwindow (which reference the
+    # Mocap layer) both compile and link.
+    if(ENABLE_MOCAP)
+        target_link_libraries(qtmesh_test_common PUBLIC Qt6::Multimedia)
+    endif()
+
     if(ENABLE_PS1_RIP)
         add_dependencies(qtmesh_test_common qtmesh_ps1core_stub)
         if(TARGET qtmesh_ps1core_libretro)