init: animation pipeline hub — Mac↔PC bridge for converting and implementing animations

Skills (.claude/skills/): animation-creation, iclone-video-mocap,
pose-estimation (MediaPipe models via LFS), retarget-animations (deprecated).
Tools: cc/mixamo/kevin/mocap retargeters + composite baker.
Plans: animation-gen-pipeline + skills-adoption.
exchange/: incoming-fbx, converted-glb, reference-video (LFS for fbx/glb/mp4).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.claude/skills/iclone-video-mocap/references/ariki-integration.md

@@ -0,0 +1,75 @@
+# ariki-game — Integrating iClone Animation Exports
+
+How motion authored in iClone 8 (incl. Video Mocap output) lands on ariki-game's shared Quaternius skeleton. Mapped 2026-07-15 from the repo.
+
+**Headline: the retargeter already exists — `tools/cc_retarget.py` (created 2026-07-14) handles `CC_Base_*` (Reallusion CC/iClone) FBX → Quaternius GLB.** The pipeline is: iClone FBX export → `cc_retarget.py` → mesh-stripped GLB in an auto-discovered pack dir → referenceable as `<pack>/<ClipName>` in dances/showcase.
+
+## 1. The shared Quaternius skeleton (retarget target)
+
+- **Canonical rig:** `assets/quaternius/base-characters/Universal Base Characters[Standard]/Base Characters/Godot - UE/Superhero_Male_FullBody.gltf` — all retargeters default to it (`--target` overrides). `kevin_retarget.py:26` is the exception (hardcoded absolute path, non-portable).
+- **65 bones, UE-style names, T-pose rest.** Spine: `root, pelvis, spine_01..03, neck_01, Head` (capital H). Per side: `clavicle_, upperarm_, lowerarm_, hand_, thigh_, calf_, foot_, ball_, ball_leaf_` + fingers `thumb/index/middle/ring/pinky_01..03_` with `_04_leaf_` tips.
+
+## 2. ClipCatalog discovery (`src/Testing/Dance/ClipCatalog.cs`)
+
+- Hardcoded packs (lines 20-25): UAL1, UAL2, Run_Punch.
+- Auto-discovered dirs (lines 37-45): `res://assets/quaternius/kevin`, `res://assets/quaternius/mixamo`, `res://assets/quaternius/dancegen` — drop a GLB in one and it's live; **pack name = GLB basename**.
+- Clip ref format: `"<pack>/<ClipName>"` (e.g. `dancegen/HakaFull`).
+- Lazy extraction (lines 80-118): first `AnimationPlayer` in GLB scene, skips `RESET`, forces `LoopMode.Linear`, caches. Name fallback: `exact → +"_Loop" → -"_Loop"`.
+- Gotcha baked into the code (lines 63-64): `DirAccess.GetNext()` returns `""` at end, not null — null check pegs CPU.
+
+## 3. `tools/cc_retarget.py` — the iClone/CC ingestion tool
+
+Blender 5 headless, same world-rotation-delta method as `mixamo_retarget.py`:
+
+```bash
+/Applications/Blender.app/Contents/MacOS/Blender --background \
+  --python tools/cc_retarget.py -- \
+  --src "<dir-or-fbx>[,<more>...]" --out assets/quaternius/dancegen/<pack>.glb \
+  [--name <ClipName>] [--target <gltf>]
+```
+
+- **BONE_MAP (lines 25-48):** `CC_Base_Hip→pelvis`, `CC_Base_Waist→spine_01`, `CC_Base_Spine01→spine_02`, `CC_Base_Spine02→spine_03`, `CC_Base_NeckTwist01→neck_01`, `CC_Base_Head→Head`; limbs `CC_Base_L_Clavicle/Upperarm/Forearm/Hand/Thigh/Calf/Foot/ToeBase → clavicle_l/upperarm_l/lowerarm_l/hand_l/thigh_l/calf_l/foot_l/ball_l`. **Thumbs 3-seg, other fingers 1-seg** (`CC_Base_L_Index1→index_01_l` etc. — game-optimized CC rigs have one segment per finger). Twist helpers (`UpperarmTwist01…`) unmapped → ride parent rigidly.
+- **Char-frame conjugation:** `q_delta = C @ (q_src·q_src_rest⁻¹) @ C⁻¹` with `C = char_frame(target) @ char_frame(source)⁻¹`; source frame from `CC_Base_Hip`/`CC_Base_Head`/`CC_Base_L_Upperarm` (lines 128-129).
+- **Units/scale:** `unit = src_arm.scale.x` captured BEFORE `transform_apply` (importer's cm→m 0.01); pelvis = world-space delta `× tscale × unit` (lines 176-177). Handles iClone's cm natively.
+- **fps 60** (only tool at 60 — "iClone exports at 60; glTF export resamples fine").
+- **Motion-presence guard** (`pick_action`, lines 89-105): picks the longest action whose fcurves reference `CC_Base_` bones; **rejects `TempMotion` <5-frame placeholders** with error "FBX exported WITHOUT motion — Re-export with Include Motion".
+- Export tail (shared with all retargeters): drop MESH objects, one NLA track per action (track name = clip name = glTF animation name), `export_scene.gltf(export_animation_mode="NLA_TRACKS", export_force_sampling=True, export_optimize_animation_size=False)`.
+
+### ⚠ Open validation item: A-pose
+The tool's comments claim "CC rigs rest in T-pose, verified on ActorBuild exports", but iClone/CC3+ characters bind in **A-pose**. The char-frame delta math measures off actual rest and should self-cancel — but the left-arm char-frame axis (`CC_Base_L_Upperarm` bone-Y) points down-and-out in A-pose, not straight +X. **QA the first A-pose export**: if arms bake rotated, fix the char-frame or add a per-arm rest-alignment quaternion. This is the one genuine divergence vs the proven Mixamo (T-pose) path. Alternatively force T-pose on the iClone side: FBX Advanced Settings > **Use T-Pose As Bind Pose**.
+
+## 4. Recommended iClone export settings for this pipeline
+
+- iClone: `File > Export > Export Fbx...`, Target Tool Preset **Blender** (or Unity 3D), Export Range **All**/**Range**, FPS `Project(60)` fine (tool handles it). Advanced: **Preserve Bone Names (CC Base)** ON (default — the bone map depends on it), consider **Use T-Pose As Bind Pose** (see §3 caveat), **Reset Bone Scale** ON.
+- Run **Menu > Animation > Flatten All Motion with Constraint** first if the take uses Reach/Link/Look At/Path — those keys don't survive FBX.
+- iClone 8 always exports mesh+animation (no motion-only mode); `cc_retarget.py` strips the mesh anyway, so don't fight it — but uncheck Embed Textures / set Max Texture Size low to keep the FBX small.
+- Animation-only alternative: export via CC4 (`FBX Options: Motion`) — the retargeter still needs a rest pose, and Blender only gets bind pose from a weighted mesh, so prefer the iClone mesh+motion export.
+- Store-content license wall: Reallusion marketplace motions/characters need a per-pack **Export License** to leave via FBX; your own Video Mocap recordings and characters are unrestricted.
+
+## 5. Runtime consumers
+
+- **AnimationShowcase** (`src/Testing/AnimationShowcase.cs`, `scenes/animation_showcase.tscn`): pages all clips. `SCENE=animation_showcase bash tools/game.sh spawn` (game.sh:926). ASK Jeremy before launching the game.
+- **Dance test bed** (`scenes/dance_test_bed.tscn`, `src/Testing/Dance/DanceTestBed.cs:118-124`): hot-reload dances via `DanceLibrary.Poll`; in-scene `VideoRecorder` → `~/Downloads/*.mp4` at 30fps. `SCENE=dance_test_bed bash tools/game.sh spawn` (game.sh:927).
+- **Dance JSON** (`assets/dances/*.json`): `{ "name", "bpm", "moves": [...] }`; move = `{ "clip": "pack/Clip", "loops": N }` or composite `{ "layers": [{"mask":"upper","clip":...},{"mask":"lower","clip":...}], "duration": s }`. Transitions quantize to the BPM beat clock. Examples: `haka_mocap.json` (uses `haka_mocap/HakaFull`), `clap_stomp.json` (110), `war_challenge.json` (120).
+- **CompositeClipBaker.cs**: lower mask = `root|pelvis|thigh*|calf*|foot*|ball*` (always owns hip pos+rot — prevents hip-fight/foot-slide); upper = rest; first-writer-wins per track. Cache keyed by definition → JSON edits need no invalidation.
+- **Hard rules:** skeleton path remap mandatory for raw GLB clips (GLB tracks target `Armature/Skeleton3D:bone`; derive real prefix from an already-remapped clip — `PlayerController.LoadUalLibrary` is canonical). **Never use `*RM`/`*RootMotion` clip variants** — everything is in-place.
+
+## 6. Godot import conventions
+
+- `.import` sidecars: `importer="scene"`, **`animation/fps=30`** (even 60fps cc output resamples to 30 at import), `animation/remove_immutable_tracks=true`, `animation/import_rest_as_RESET=false`, `meshes/generate_lods=false`. `.uid` files auto-generate — never hand-author.
+- Commit GLB + let Godot import → immediately referenceable as `<pack>/<ClipName>`.
+
+## 7. Precedents
+
+- **Kevin Iglesias**: 199 Unity FBX (`B-*` rig) → 12 packs in `assets/quaternius/kevin/` via `kevin_retarget.py` batch — the batch-directory template.
+- **Video-to-mocap (free, local)**: `extract_pose.py` (MediaPipe) → `mocap_retarget.py` (rotation-solving, no source armature) → `dancegen/haka_mocap.glb` / `HakaFull`. iClone Video Mocap is the paid, higher-quality alternative feeding the same `cc_retarget.py` path.
+- Four bone-map dicts exist: `kevin_retarget.py:29`, `mixamo_retarget.py:26`, `cc_retarget.py:25`, `mocap_retarget.py` AIM_BONES.
+
+## 8. End-to-end recipe (iClone Video Mocap → in-game dance)
+
+1. Film per the Video Mocap guidelines (eye-level static camera, full body, single actor, textured clothing; stack takes with 2s gaps into one ≤60s region).
+2. Generate in the plugin (Full Body [+ Includes Fingers]), apply to a CC character, clean up in iClone (Motion Correction for feet, Curve Editor smooth/Butterworth for jitter — see the other references).
+3. Export FBX per §4.
+4. `cc_retarget.py --src <fbx> --out assets/quaternius/dancegen/<pack>.glb --name <ClipName>`.
+5. Verify: open in animation_showcase or reference `<pack>/<ClipName>` from a dance JSON in `assets/dances/` (hot-reloads in the dance test bed).
+6. First A-pose export: eyeball arm orientation (§3 caveat) before batching.

.claude/skills/iclone-video-mocap/references/export-pipeline-to-blender-godot.md

@@ -0,0 +1,108 @@
+# iClone 8 / CC4 → Blender → Godot Animation Export Pipeline Reference
+
+Compiled 2026-07-15 from Reallusion manuals, soupday docs, Godot docs, Reallusion forum. Claims not confirmed against a primary source are marked [UNVERIFIED].
+
+## 1. iClone 8 FBX Export
+
+**Menu path:** `Menu > File > Export > Export Fbx...` (select one or more avatars/props/accessories/cameras first). iClone 8 ships as a single edition — no separate "Pipeline" SKU and no 3DXchange needed; FBX/OBJ export is built in.
+
+**Export dialog options (exact names, iClone 8 manual):**
+- **Target Tool Preset** — dropdown, auto-configures Advanced Settings per DCC. Supported-tools list is rendered as an image in the manual page (not text-extractable); known presets include 3ds Max, Blender, Cinema 4D, Maya, MotionBuilder, Unity, Unreal [UNVERIFIED exact/full list].
+- **Export Range**: `T-Pose` | `Current Frame` | `All` | `Range` — this is the mesh-vs-animation control. `T-Pose`/`Current Frame` = static export; `All`/`Range` = baked animation.
+- **Export Animation FPS** — free field / dropdown to resample export frame rate.
+- **Embed Textures** — embed in FBX vs. export as separate files.
+- **Max Image Size** — cap texture resolution (default: original size).
+- **Convert Image Format to** — force texture format (default JPG).
+- **Delete Hidden Face** — strips occluded mesh.
+- **Use Smooth Mesh** — export subdivided/smoothed surface.
+- **Merge Face Hair to One Object**, **Tear Ducts UV Adjustment** — face-mesh consolidation options.
+- **Embed Timeline Timecode**.
+- **Convert Skinned Expressions to Morphs** — bakes skinned (bone-driven) facial expressions into morph targets so faces survive in non-Reallusion tools. Important for facial anim in Godot.
+- **Delete Unused Morphs** — drops unkeyed blendshapes (smaller files; disable if you need the full ARKit/viseme set at runtime).
+- **Advanced Settings** panel — per-tool fixups; for the Blender template this includes **Rename Duplicated Nodes** and **Reset Bone Offset** (needed so bones behave in Blender Object/Pose/Edit modes).
+
+**Animation-only export:** iClone 8 has **no** "export animation only" FBX mode — mesh/materials always come along (confirmed by forum threads and Feedback Tracker "IClone 8 has limited FBX export options compared to CC4"). Workarounds: export via CC4 (which has `FBX Options: Motion`), or import the full FBX in Blender/soupday tools and discard meshes. For constraint-based animation (Link/Look At/Attach/Path/Reach), run `Menu > Animation > Flatten All Motion with Constraint` before export or those keys are lost.
+
+**Not exportable as FBX:** iLight, iEffect, iParticle, iTree, iGrass, heightmap iTerrain, iWater, iSky, aml, iTalk, iPath.
+
+**Export License gating:** The *software* does not gate FBX export; the *content* does. Reallusion marketplace/Content Store items require a purchased **Export License** per pack to leave the ecosystem; without it you get "You must first purchase the content licenses in order to export FBX and USD files." Your own characters and content flagged export-ready export freely. The Content EULA restricts exporting iContent to FBX/OBJ etc. without that license.
+
+Sources: https://manual.reallusion.com/iClone-8/Content/ENU/8.0/83-FBX/FBX_UI_Intro.htm , https://manual.reallusion.com/iClone-8/Content/ENU/8.0/83-FBX/Exporting_FBX_from_iClone.htm , https://forum.reallusion.com/516723/export-animation-only-to-fbx-with-iclone-8/Forum445.aspx , https://www.reallusion.com/license/content.html , https://forum.reallusion.com/556427/
+
+## 2. CC4 FBX Export (the better animation exit door)
+
+**Menu path:** `File > Export > FBX (Clothed Character)`.
+
+**Dialog options:**
+- **Target Tool Preset** dropdown (auto-sets Advanced Settings): Blender, Unity, Unreal, Maya, 3ds Max, etc.
+- **FBX Options**: `Mesh` | `Motion` | `Mesh and Motion` — `Motion` is the true animation-only export (armature + animation, no character mesh). Separate checkbox **Export Mesh and Motion Individually** writes mesh FBX + one FBX per motion.
+- **Include Motion**: `Calibration` (T-pose calibration motion) | `Current Pose` | `Custom` (queue .iMotion/.iMotionPlus clips; MotionPlus carries facial + body). Disabled when Export Type = Mesh only.
+- **Frame rate**: dedicated page "Setting Frame Rate for Exporting FBX" — resample dropdown/manual entry.
+- **First Frame in Bind-Pose** — inserts bind pose (T-pose for CC1/CC3 Base, **A-pose for CC3+ characters**) one frame ahead of the motion. Critical for retargeting tools that read frame 0 as rest pose.
+- Texture size/format, embed toggle; **Delete Hidden Mesh**; **Merge Beard and Brows into one object**; **Bake diffuse and specular maps from Digital Human Hair Shader**; **Bake diffuse maps from skin color**; **Use Subdivided Mesh**; InstaLOD/Remesher/Merge Material for game LODs.
+
+Sources: https://manual.reallusion.com/Character-Creator-4/Content/ENU/4.1/17-Export/Export-FBX.htm , https://manual.reallusion.com/Character-Creator-4/Content/ENU/4.0/17_Export/Exporting_Mesh_and_Motion_Individually.htm , https://manual.reallusion.com/Character-Creator-4/Content/ENU/4.0/17_Export/Setting_Frame_Rate_for_FBX.htm , https://manual.reallusion.com/Character-Creator-4/Content/ENU/4.0/17_Export/Using-First-Fram-in-Bind-Pose-Feature.htm
+
+## 3. BVH Export
+
+- **CC4 4.4+ has native BVH export**: `File > Export > BVH`. Options: Prefix/Suffix; bone selection with designated **motion root** (map to Hips); **Target Tool Preset**; **Rename Duplicated Nodes** + **Reset Bone Offset** (Blender compat); **Frame Rate** (sampling); Include Motion: `Calibration` | `Current Pose` | `Current Animation` | `Custom` (batch via Load Perform/Open File). Supports .iMotion/.iMotionPlus/.rlMotion/.rlPose. Known failures exporting motions retargeted onto non-standard (e.g. Daz G8) skeletons.
+- **iClone 8:** no BVH exporter documented in the iClone 8 manual [UNVERIFIED — historical `File > Export to Other 3D Format > Export BVH` docs are 3DXchange5-era]. Practical path: send motion to CC4 and BVH-export there, or export FBX and convert in Blender.
+- Both tools **import** BVH (Convert External Motions → iMotion).
+
+Sources: https://manual.reallusion.com/Character-Creator-4/Content/ENU/4.4/17-Export/Exporting-Motions-to-BVH.htm , https://discussions.reallusion.com/t/bvh-export-fails-from-cc4/13056 , https://manual.reallusion.com/iClone-8/Content/ENU/8.4/50-Animation/Import-External-Motions/Convert-External-Motions.htm
+
+## 4. USD / glTF
+
+- **USD:** via the free **Omniverse Connector plugin** (iClone must be 8.3+). After install, `Plugins > Omniverse` exposes **Export USD** plus Live Sync (one-click whole-project or per-item two-way transfer). CC4 has an equivalent USD/Omniverse export [UNVERIFIED exact CC4 menu]. USD export of store content is also Export-License-gated.
+- **glTF/GLB:** **no native glTF export** in iClone 8 or CC4 [UNVERIFIED as absolute, but no manual page exists]. Standard route: FBX → Blender → glTF exporter, or FBX → FBX2glTF/ufbx inside Godot. Community tutorials (Freedom Arts "CC4 Export to GLB and GLTF with Blender") all route through Blender.
+
+Sources: https://manual.reallusion.com/Omniverse-Plug-in/Content/ENU/iC-8.3/01-Installation/For-IC-Users.htm , https://docs.omniverse.nvidia.com/connect/iclone.html , https://www.classcentral.com/course/youtube-character-creator-4-export-to-glb-gltf-with-blender-cc4-pipeline-tutorial-blender-310648
+
+## 5. soupday CC/iC Blender Tools (cc_blender_tools)
+
+Add-on (a.k.a. "CC/iC Pipeline") for importing/auto-setup of CC3/CC4 + iClone 7/8 exports into Blender. Docs explicitly warn: **"Do Not use the standard blender FBX importer"** for CC/iC characters.
+
+**Recommended export settings** — CC4: preset `Blender`, `FBX (Clothed Character)`, FBX Options `Mesh and Motion`, Include Motion `Current Pose`, check `Delete Hidden Faces`, textures NOT embedded. iClone: `File > Export > Export FBX`, target `Blender`, range `All`, check `Embed Textures` + `Delete Hidden Faces`.
+
+**Features:**
+- **Import Character** button: auto-builds full material setup (from the sidecar `.json`), optional toggles for Lighting, Physics, Wrinkles, Rigify; `Import Animation` checkbox brings motions in as Blender Actions.
+- **Import Animations** button (Retargeting section): imports armature + actions **including shape-key actions** from extra FBX files, discarding meshes/materials.
+- **Rigify** button (Rigging and Animation panel): one-click Rigify control rig, optional **Full Face Rig**; original CC skeleton is kept (hidden) as deform rig.
+- **Retargeting**: sources supported — Character Creator, ActorCore, GameBase, iClone, **Mixamo (X/Y Bots)**, "General Humans". Workflow: pick Source Armature + action → **Preview Retarget** (live tweak arm spread, leg spacing, heel/toe angle, root height) → **Bake Retarget** (new action named `RigifiedChar | <Type> | ClipName`) → **Retarget Shape Keys** copies facial/viseme shape-key animation onto every mesh with matching shape keys. iClone facial performances arrive as "iCTM" temp-motion actions. NLA editor recommended for stacking body + shape-key actions.
+- **Round-trip:** `Export to CC3/4` button requires the **FbxKey** from the original CC export; writes back JSON material params/textures for lossless re-import into CC. **Export to Unity** (.fbx or .blend); after Rigify, three export modes: mesh-only, armature+animation-only, or both.
+
+Sources: https://github.com/soupday/cc_blender_tools , https://soupday.github.io/cc_blender_tools/usage.html , https://soupday.github.io/cc_blender_tools/animation.html , https://soupday.github.io/cc_blender_tools/adv-animation.html , https://soupday.github.io/cc_blender_tools/pipeline.html
+
+## 6. CC Skeleton & Retargeting to Other Rigs
+
+- **Naming convention:** every bone prefixed `CC_Base_` — e.g. `CC_Base_BoneRoot`, `CC_Base_Hip`, `CC_Base_Waist`, `CC_Base_Spine01/02`, `CC_Base_NeckTwist01/02`, `CC_Base_Head`, `CC_Base_L_Clavicle/L_Upperarm/L_Forearm/L_Hand`, `CC_Base_L_Thigh/L_Calf/L_Foot/L_ToeBase`, plus twist chains (`CC_Base_L_UpperarmTwist01/02`, `ForearmTwist`, `ThighTwist`, `CalfTwist`) and full finger chains [names verified via CC4 Bone List/Bone Manager docs and community presets; exact full hierarchy: see CC4 Bone List F3 panel]. GameBase conversion produces a simplified skeleton with different names (breaks soupday Rigify — see issue #60).
+- **Not Mixamo-named** (`mixamorig:` ≠ `CC_Base_`); retargeting is by humanoid mapping, not name matching. soupday retarget handles Mixamo→CC-Rigify directly.
+- **Blender retarget options:** (a) soupday Rigify retarget (best for CC targets); (b) **Auto-Rig Pro** Remap — community bone-list preset "Character Creator 4 to Auto-Rig Pro IK" exists (gist by muratagawa); ARP is the commonly recommended robust option; (c) **Rokoko Studio Live** addon Retargeting tab — select source/target armature → **Build Bone List** → fix mappings → retarget; a ready-made CC3 bone-list JSON is sold/shared on Gumroad; addon has Blender-version lag issues.
+- **To a Quaternius-style simple rig:** map only the ~20 core humanoid bones (Hips←CC_Base_Hip, Spine←Spine01/02 collapsed, Head, UpperArm/LowerArm/Hand, UpperLeg/LowerLeg/Foot); ignore twist bones and finger chains, or bake twist rotation into parent limb bones before transfer. Rest-pose difference (CC A-pose vs Quaternius T-pose) must be corrected with a rest-pose alignment step (ARP "Redefine Rest Pose" / Rokoko auto rest-pose matching) or shoulders will bake ~45° off.
+
+Sources: https://manual.reallusion.com/Character-Creator-4/Content/ENU/4.0/04_Introducing_the_User_Interface/Bone-List.htm , https://gist.github.com/muratagawa/ed07632bdd07bdec442fa194821b92b9 , https://github.com/Rokoko/rokoko-studio-live-blender , https://support.rokoko.com/hc/en-us/articles/4410463481489 , https://github.com/soupday/cc_blender_tools/issues/60
+
+## 7. FBX → GLB → Godot
+
+**Blender leg:**
+- CC FBX is authored in **centimeters**; Blender's FBX importer compensates with **armature object scale 0.01** (and Edit Mode shows 0.01 scaling). Fix: use soupday importer, or apply transforms (select armature+meshes → `Object > Apply > All Transforms`) before doing anything else; the classic manual fix is scale ×100 → Apply Scale → ×0.01 dance when round-tripping to engines.
+- Standard importer bone options: `Automatic Bone Orientation` + `Force Connect Children` make bones viewable but **alter bone rolls/joint rotations** — avoid if you will export animation back out; CC bones have zero-length/leaf-bone issues that iClone's "Reset Bone Offset" advanced option mitigates.
+- **GLB export (File > Export > glTF 2.0):** glTF is Godot's recommended format. Key settings: `Data > Armature > Export Deformation Bones Only` = ON (required when meshes have shape keys, prevents shading errors; also strips Rigify control bones), Include `Shape Keys` + `Shape Key Animations` [UNVERIFIED exact checkbox names per Blender version], Animation mode `Actions` or push actions to **NLA tracks** so every clip exports as a named animation; `+Y Up` handled automatically; enable Backface Culling on materials. If exporting a Rigify character, bake action to the deform (CC_Base_) bones first or export with "Export Deformation Bones Only".
+
+**Godot leg:**
+- **Godot 4.3+ imports .fbx natively via ufbx** — no external converter; handles unit conversion (cm→m applied to mesh data, not node scale), no extraneous RootNode. Pre-4.3 / legacy files use **FBX2glTF** (requires downloaded binary; per-file importer switch in Import dock; switching importers changes node hierarchy, rest poses, surface order). Direct iClone-FBX → Godot-ufbx works but skips Blender-side cleanup (material rebuild, morph naming) [UNVERIFIED quality for CC characters specifically].
+- GLB path is still the most predictable: animations arrive in an `AnimationPlayer`, blendshapes as mesh blend-shape tracks. Import dock: set `Animation > FPS` (default 30 — raise to 60 for iClone-sourced clips to avoid resampling loss [Godot 4 samples at import]), loop suffixes (`-loop`/`-cycle` name suffix or import options), and use **Root Motion** by assigning the hip/root bone as `root_motion_track` in AnimationTree.
+
+Sources: https://godotengine.org/article/introducing-the-improved-ufbx-importer-in-godot-4-3/ , https://docs.godotengine.org/en/stable/tutorials/assets_pipeline/importing_3d_scenes/available_formats.html , https://docs.godotengine.org/en/stable/classes/class_editorsceneformatimporterfbx2gltf.html , https://blenderartists.org/t/bringing-armature-into-edit-mode-scales-it-to-0-01-no-matter-what-i-do/1485346
+
+## 8. Common Pitfalls Checklist
+
+1. **60 fps:** iClone's realtime engine/timeline runs at 60 fps [UNVERIFIED whether iClone 8 allows changing project fps]; set **Export Animation FPS** deliberately and match Godot's import bake FPS, or clips get resampled twice.
+2. **cm units / 0.01 scale:** CC/iClone FBX = centimeters. Blender import → 0.01-scaled armature; apply transforms before retarget/export or child meshes, physics, and GLB scale drift. Godot ufbx converts units into mesh data automatically.
+3. **A-pose vs T-pose:** CC3+ (CC4 default) characters' **bind pose is A-pose**; CC1/CC3 Base is T-pose. The Export dialog's T-pose option only *prepends a T-pose frame* — the skin bind pose stays A-pose (Feedback Tracker: "Exported FBX character stays in A pose when I select T pose"). Use **First Frame in Bind-Pose** so retargeters can read frame 0; align rest poses before baking onto T-pose target rigs.
+4. **Bind pose only appears with animation:** importing CC FBX into Blender *without* animation shows bind pose, not the current pose you saw in iClone. Conversely, Blender's FBX exporter writes bind poses only when a weighted mesh is exported — armature-only motion FBX loses bind pose.
+5. **Twist bones:** CC twist chains (`...Twist01/02`) carry real rotation; dropping them without baking their rotation into parent bones causes candy-wrapper forearms/thighs on simple rigs.
+6. **Facial blendshapes:** enable **Convert Skinned Expressions to Morphs** (iClone) and don't over-prune with **Delete Unused Morphs**; in Blender keep shape keys + use `Export Deformation Bones Only` in glTF export; shape-key actions need **Retarget Shape Keys** (soupday) to follow a retarget; verify blend-shape tracks in Godot's imported AnimationPlayer.
+7. **Root motion:** iClone motions move `CC_Base_BoneRoot`/Hip in world space; decide in-place vs root-motion before export (flatten constraints first), then configure Godot AnimationTree root-motion track; Rigify retarget offers root-height adjustment at preview time.
+8. **Store-content license wall:** FBX/USD export silently blocked per-asset without Export License — audit content packs before building a pipeline around them.
+9. **GameBase/non-standard skeletons:** break both soupday Rigify and CC4 BVH export; keep characters on the standard CC_Base_ skeleton until final export.

.claude/skills/iclone-video-mocap/references/iclone8-core-animation.md

@@ -0,0 +1,170 @@
+# iClone 8 Core Animation System — Technical Reference
+
+Compiled 2026-07-15 from manual.reallusion.com (iClone 8 Online Manual, sections 8.0–8.5), Reallusion KB, and Reallusion forums. Excludes the Video Mocap plugin (see video-mocap-plugin.md). `[UNVERIFIED]` marks low-confidence items.
+
+## 1. Character Animation Architecture
+
+### 1.1 Core model: Motion Clips + Layer Keys
+- "A **Motion** or **Animation** is the combination of the **Motion Clip** and the **Layer Keys**." Since iClone 1.x-era redesign, **layer keys are encased inside motion/animation clips**: dragging a clip drags its layer keys; a clip's layer key **cannot be moved outside the range of the clip**.
+- Motion track has sub-tracks: **Motion Layer** keys (per body part: e.g. `R Arm`, `LFingers`, `RFingers`) and **gesture layer clips** for both hands (LHand/RHand). Gesture data can be **Sampled** (extracted into LFingers/RFingers Motion Layer tracks) or **Flattened** (merged back into the motion clip).
+- **Relative Motion Layer Keys** blend an offset into the underlying motion. Old "absolute" motion layer keys were removed — the equivalent is removing the motion and posing via Edit Motion Layer.
+- A motion layer key's effect **persists to end of clip until another key is set**; transitions between consecutive layer keys are auto-generated.
+
+### 1.2 Edit Motion Layer panel (Modify > Animation tab > Edit Motion Layer; menu Animation > Edit Motion Layer; hotkey **N**)
+Engine is **HumanIK** ("automatic floor contact while the intuitive real-time IK motion control keeps the body balanced"). Panel sections:
+1. **Set as Default / Reset to Default** (base pose retrieval; Default button adds a layer key standing the character straight in default pose).
+2. Mode tabs: **IK / Mask / Detail**.
+3. **Body pictogram** with effector-point states: Selected / Free / Move-locked / Rotate-locked / fully Locked / blend-weight-activated joints; quick lock toggle.
+4. **Pin presets**: lock joint translation, joint rotation, Both Feet, Both Hands, Hands+Feet, Both Toes, Unlock All.
+5. **Mirror controls**: edit bilateral bones simultaneously, copy bone status to opposite side, mirror entire pose.
+6. Selection modes: **Full Body** (torso may drag along when an effector moves; Ctrl+Click multi-select; keys inserted on ALL Motion Layer sub-tracks except fingers) vs **Body Part** (limbs/head only; key lands only in the relevant sub-track, e.g. R Arm).
+7. **Set Key** and **Reset Pose** buttons.
+8. **Viewport Controller** (colored on-screen bone pickers), **Bone Display Mode** (bones/bounding boxes), Bone Settings (Size, Affect all Bones, Color, Opacity).
+9. Palm pictogram for **hand gestures**.
+10. **Effector Blend Weight** activate/deactivate.
+11. Three **Mirror Pose** buttons (incl. Pose Mirror Right to Left, Full Body Pose Mirror).
+12. **Vertical Pose Alignment** toggle — includes Z-axis values (normally only X and Y are aligned → confirms Z = vertical axis in iClone).
+13. **Properties** dropdown for numeric translate/rotate entry.
+14. **Copy Pose / Paste Pose**.
+- IK posing: pick an effector (e.g. hand), use Move tool (W) and drag in viewport — 2D mouse motion drives the limb; manual says "make sure your target body parts face the camera" for precise 2D→3D control. Rotate tool (E) = FK-style joint angle edits. **Foot Contact / Hand Contact** checkboxes prevent ground penetration. Recommended: deactivate sub-joint blend weights and pin (lock) bones you don't want dragged before editing.
+- **Pose Mixer / Mask Mode** (inside Edit Motion Layer): pick body parts on pictogram (Select All / Select None / Invert Selection), then apply `*.rlPose` files from Content Manager — only masked parts take the pose; repeat with other pose files to compose partial poses; masked mirroring via Pose Mirror buttons. Custom poses saved via Add/save to library (`.rlPose`; iClone 8.4 added save-custom-poses page).
+- **Edit Pose vs motion layer keys**: "Edit Pose" panel is the Character Creator 4 equivalent (CC manual: "Using the Edit Pose Panel", same Body Key Editor); inside iClone all posing goes through Edit Motion Layer and always lands as **Motion Layer keys** relative to the current clip (or on an empty motion as pose-to-pose keyframing).
+- Layering workflow onto existing motion: apply clip → Edit Motion Layer → go to frame → adjust effectors → key auto-added to Motion Layer track and blended into the Motion-track pose.
+
+### 1.3 Animation Layer panel (F11; iClone 8.x, distinct from the single Motion Layer track)
+- Stores pose keys in stackable named layers to "set their weight together". Toolbar: **Add New Layer, Duplicate Layer, Delete Layer, Rename Layer, Merge** (merge as **optimized keys** or **sampled key per frame**), reorder up/down, **Lock**, layer **Color**, **activation toggle** (mute), **Weight slider** with **weight keyframing** over time. Supports per-body-part layering (manual: "Animation Layers for Body Parts").
+
+### 1.4 Reach Target (Modify > Animation tab > Reach Target; menu Animation > Reach Target)
+Panel: (1) **Bone Edit Mode** checkbox (show bones); (2) **Bone Settings** (Bone Size / Affect to all bones / Color / Opacity); (3) **Pictogram** effector states: Selected / Free / **Reaching** (contacts target) / Motion-compelling (keeps original motion); (4) **Reach Target** section incl. **Select Target and Keep Current Pose** button (reach-key effect without snapping to the target); (5) **Reach Mode** — **Position** checkbox (hand snaps/aligns to target pivot) and **Rotation** checkbox (also follows target orientation); (6) **Reach Offset** (position and angle offsets from the target); (7) **Lock to Origin** (pin effector to original position); (8) **Release** (sets a release key on the timeline).
+- **Lock to Original workflow** (protecting existing pose while one part reaches): lock affected effectors **one at a time** (multi-selection not allowed for locking); secondary drift may require additional locks; verify by playback.
+- Reach keys/constraints are **not** exported directly to FBX — use **Menu > Animation > Flatten All Motion with Constraint** to bake Link / Look At / Attach / Path / Reach keys into motion clips first.
+- Effector **dummy props** can be used as reach targets to fix motions ("Fixing Motions with Effector" page); Look At / Reach / Path control also via dummy props (Set > Prop > Using Dummy Props).
+
+Sources: manual pages `50-Animation/Motion-Layer/Introducing_the_Edit_Motion_Layer_Panel.htm`, `Using_Body_Key_Editor.htm`, `How_to_Use_IK.htm`, `Layering_Motion_Layer_Keys_to_Exising_Motions.htm`, `Using-Mask-Mode.htm`, `50-Animation/Animation-Layer/Introducing-the-Animation-Layer-Panel.htm`, `50-Animation/Reach_Target/*.htm`, `51-Animation-Timeline-Editing/Clips_and_Keys.htm`.
+
+## 2. Timeline (F3; Shift+F3 focuses it)
+
+### 2.1 Tracks
+Per-object track stack includes: **Transform**, **Motion** (with Motion Layer + gesture sub-tracks), **Facial layer tracks**, **Viseme** (expand triangle → **Voice** and **Lips** sub-tracks), Expression tracks (see §5), **Visible**, Effect/HDR/IBL property tracks, **Audio/Sound + Lips** sync tracks, **Part tracks** (bone-skinned objects) and **Bone tracks** (individual bones + IK effectors), **Collect Clip** track, and the **Project track** (flags/markers). Track show/hide hotkeys: O, Q, T, M, R, Z, E, L, V, S, D, I.
+
+### 2.2 Clip operations (toolbar / right-click / hotkeys)
+- **Add Key** `A`; **Break** `Ctrl+B` (non-destructive split, hidden data preserved); **Break Flatten** (destructive split, discards data beyond boundaries); **Auto Extend** (expands clip when keys fall outside; also Menu > Animation > **Clip Auto Extend**); **Loop** `1` (drag right clip edge); **Speed** `2` (drag edge; shown as % on clip title bar); **Resize Clip** `3`; **Motion Direction Control** `4`; **Motion Modifier** `5`; Cut/Copy/Paste `Ctrl+X/C/V`; duplicate = `Ctrl+LMB drag`; Delete key. Prev/Next key: `Ctrl+Left / Ctrl+Right` (toolbar also lists Tab/Shift+Tab). Playback range on/off: `'` / `;`. Zoom `+`/`-`, Fit `Ctrl+*`, **Actual Size** `Ctrl+/` (1 cell = 1 frame at 60fps). Insert/Delete frames for project or single object; Mark In/Out; flags on Project track.
+- **Reversing Clips**: right-click clip > Reverse (page `Reversing_Clips.htm`).
+- **Time Warp** (right-click motion clip > Time Warp): default = **Linear**; presets **Ease In / Ease In & Out / Ease Out / Ease Out & In**; **Custom** panel = curve-type dropdown + variation slider (left ≈ linear, right = more dramatic). Changes speed *within* the clip.
+- **Transitions between clips**: transition range sits ahead of the latter clip; each clip has 4 draggable triangles: **Fade In Start** (weight 0) / **Fade In End** (100) / **Fade Out Start** (100) / **Fade Out End** (0); blend progression between lower triangles is always **linear**. Weights do nothing if only one clip is on the track.
+- **Transition Curves between two keys** (Transform and other key tracks): set 2 keys, right-click the **later** key > **Transition Curve** > pick from **16 curves + Default** (Ease In, Ease Out, Ease In & Out, Pause and Move, Gain momentum before Move, Damping, Gain momentum and Damp, Stutter Start, End in a Bounce, Stuttering Start and End, Elastic Start and Sudden End, Sudden Start with Elastic end, Elastic Start and End, Step, Linear, Default). 4 basic presets have a **Strength** slider; **Default** curve comes from **Preference panel > Default Key Tangent**. Live viewport preview when hovering choices.
+- **Hollow vs solid keys**: hollow = partially keyed frame (not all axes keyed — common after Sampling due to optimization); solid = all axes keyed. Editing hollow keys in detail requires the **Curve Editor**.
+
+### 2.3 Sampling & Flattening (right-click on motion/animation clip)
+- **Sample Motion Clip to New Layer** >> **Sample All Parts - Optimized** | **Sample All Parts - Per Frame** | **Sample Selected Parts** — exposes clip contents as **Layer Keys** (standard CC characters). Props/accessories: **Sample Animation Clip**.
+- **Flatten Motion Clip** >> **Flatten All Layers** | **Flatten And Keep All Keys** — merges Layer Keys into the clip. For clips with Speed/Time Warp applied, keys are **recalculated and optimized** rather than merged, and cells re-match timeline units (standard characters only). Menu names differ for standard vs non-standard characters vs props.
+- **Menu > Animation > Flatten All Motion with Constraint** bakes constraint keys (Link, Look At, Attach, Path, Reach) — required before FBX export of constrained animation.
+
+### 2.4 Collect Clip track
+- Open Collect Clip track → click-drag a range covering the desired clips/keys → right-click: **Add Motion to Library** (actors; merges/compacts Transform + Motion + Hands + Motion Layer tracks into one motion, save to Custom library), **Add Gesture to Library** (hand motions), **Add to Perform List** (iProps: Transform + Animation tracks), **Add to Perform** (props: Transform track). Re-import via right-click Motion track > **Import**, or the Perform menu. This is the standard way to consolidate a mocap-plus-layer-edit result into a reusable `.iMotion`/MotionPlus asset.
+
+### 2.5 Motion Direction Control (hotkey 4)
+Fixes the "transform keys fight motion clips" problem: select clip > Motion Direction Control button → leading line(s) show clip travel direction; **Rotate** fields (exact degrees), **Translate** fields (initialize clip start position), or use Object Rotate tool visually. With multiple clips, adjust the second clip while keeping adjacent motions aligned/connected. Related: **Menu > Animation > Auto Motion Alignment** >> **No Alignment / Align Position Only / Align Position and Direction**.
+
+Sources: `51-Animation-Timeline-Editing/Timeline-Operation-Basic.htm`, `Clips_and_Keys.htm`, `Sampling_and_Flattening.htm`, `Transition_Methods_in_Tracks.htm`, `Creating-Transition-between-Clips.htm`, `Time_Warp_for_Motion_Clips.htm`, `Collect_Clip_Track.htm`, `Using-Motion-Direction-Control.htm`, `90_Keyboard_Shortcuts/Timeline_Shortcuts.htm`, `02-Main-Menu/Menu_Animation.htm`.
+
+## 3. Curve Editor (built-in plugin; F12, Shift+F12 focuses; separate manual section 58-Curve-Editor)
+
+- Purpose: classic-animation curve control over iClone keys ("time and space adjustment", ease in/out, arcs, smooth/linear camera moves). Select motion keys in Timeline, edit their curves.
+- UI: **Menu bar** (Key, Tangent, Navigation, Zoom, Optimize/Filter, Curve menus); **Toolbar** areas: Outliner Display Options, **Tangent Tools**, **Handle Tools**, **Key Editing Tools**, Navigation Tools; **Search bar**; **Outliner** (structure nodes + curve nodes of selected object); **Edit mode** dropdown: **Layer Keys** | **Transformation**; **Time mode**: **Project Time** | **Clip Time**; Current Frame field; **Graph view**; **FK Mode** button (launches motion-layer editing for bone selection); Status bar with Frame/Value numeric fields.
+- Key Editing Tools: **Move Key** (Shift+Drag = single-axis constraint), **Offset Key** (shifts entire sequence before/after to preserve surrounding animation), **Add Keyframe** (directly on curve; toggle "Add Keyframes for All Curves"), **Remove Keys**, **Scale Keys** (bounding-box: horizontal = speed, vertical = magnitude).
+- Filter menu: **Optimize** (Threshold 0–1 curve-fitting; higher = smoother/fewer keys; options: Optimize Selected Keys only / Selected Curves only / Selected Keys on Selected Curves; Preview shows before/after key counts — for densely keyed mocap curves), **Smooth** (Smooth Factor strength, **Falloff** to avoid cliffs at range edges, **Keep Custom Tangent**, Preview), **Butterworth** smoothing (**Cut-off (Hz)**, **Sample Rate (fps)**, Falloff, **Align to frames** = float keys → integer frames, Preview). These are the primary **mocap jitter cleanup** tools — sample the imported mocap clip to layer keys first, then filter.
+- Tangent menu/tools include standard tangent types (Auto/Linear/Step/Ease etc.) `[UNVERIFIED — exact list not confirmed]`. Dedicated Curve Editor keyboard shortcut page exists (`58-Curve-Editor/Keyboard_Shortcuts.htm`).
+- Gotcha: to curve-edit inside a motion clip you must expose keys (Sample) — clip contents themselves aren't directly curve-editable; hollow keys are adjusted here.
+
+Sources: `58-Curve-Editor/Welcome_to_Curve_Editor.htm`, `UI_Intro_for_Curve_Editor.htm`, `UI_Intro_for_Curve_Editor_Key_Editing_Tools.htm`, `UI_Intro_for_Curve_Editor_Menu_Optimize.htm`.
+
+## 4. Motion Correction / Cleanup Tools
+
+### 4.1 Motion Correction (foot/hand sliding fix)
+- Right-click motion clip > **Motion Correction**. Derived from Reach: calculates ground-contact times, auto-creates **hand/foot prints**, sets Reach keys to feet/hands so they stick to prints.
+- Panel: **Presets** (pre-optimized body part sets), **Body Parts** (manual per-part activation), **Parts Settings**: **Threshold** (higher = severe sliding, lower = minor sliding — the main dial), **Transition** (frames for Reach/Release key transition), **Reach Offset** / **Release Offset** (shift Reach/Release keys left/right), **Reach Mode** checkboxes (touch prints / align to print directions), **Sync Threshold with all Parts** checkbox. Click **Correct**.
+- Iteration gotcha: after each Correct, run **Flatten Motion Clip > Flatten All Layers**, deactivate the already-fixed parts, then correct remaining parts; repeat.
+- This is the primary post-import cleanup pass for external/video mocap clips.
+
+### 4.2 Motion Modifier (Timeline button, hotkey 5)
+- Slider-based whole-clip body-part adjustment ("fix posture issues or alter overall look"). **Base Pose** options: **Default Pose** (motions that don't change much), **Auto Generate** (averages pose for highly varying clips), **Load** (use first pose of a loaded iMotion). **Part Modify** section with **Stand Mode** / **Move Mode**. Converts entire clip into an altered one. Not recommended for dramatic motions (big turns/heavy transforms).
+
+### 4.3 Motion Director (iClone 8 flagship; replaces MixMoves conceptually)
+- Behavior files (**iMD**) drive characters: each character can have multiple **Behaviors**; each behavior has **Modes** (currently **Casual** and **Athletic**); modes contain speeds ('Stroll', 'Walk', 'Jog'); each speed has perform-motions and **Mix-motions** ('Main Mixer' + sub-mixers).
+- Control: keyboard/gamepad (WASD-style; **Ctrl+R** start/stop playback-record; Shift = accelerate a level, Ctrl = decelerate; customizable via **Hotkey Manager**, Edit > Hotkey Manager, Ctrl+`); waypoints via **Alt+left-click** (queue) and **Alt+right-click** (absolute, cancels others). Cameras: **MD Camera** (system), **Free Camera**, **Follow Camera** (8 presets + 5 customizable) on MD Triggers panel. **Snap to Surface** for terrain-following characters (8.1). **Menu > Animation > Create iMD Cache** pre-retargets actors for MD performance. MD Props with **Reach Effect** settings exist (8.5).
+- Recording writes normal motion clips to the timeline, editable with everything in §1–§3.
+
+### 4.4 MixMoves — REMOVED in iClone 8
+- The iClone 7 MixMoves system (automatic motion-graph transitions) is **not in iClone 8**; legacy MixMoves animations still usable as regular motions (Reallusion forum confirmation). Motion Director is the successor.
+
+### 4.5 Motion Puppet / Direct Puppet / Prop Puppet / Morph Animation (Menu > Animation)
+- **Motion Puppet**: record motions from puppet templates onto the selected character (mask body parts, mouse-driven). **Direct Puppet**: simultaneously move+record body to generate motions. **Prop Puppet**: puppet-record prop animation. **Morph Animation**: Morph Animator panel — keyed morphing sliders (also how morph-based prop/character shape animation is keyed). **Edit Animation Layer**: layer keys on existing prop animations.
+
+### 4.6 Smoothing
+- Body: Curve Editor **Smooth / Butterworth** filters (§3), Optimize for key reduction.
+- HumanIK foot floor contact: automatic in Edit Motion Layer (Foot/Hand Contact checkboxes). Character-level contact geometry comes from CC's **Floor Contact Planes** (soles/palms; toes/fingers bend to avoid penetration) — set in Character Creator, honored by iClone terrain snapping.
+
+Sources: `51-Animation-Timeline-Editing/Motion-Correction-for-Sliding-Issues.htm`, `Modifying_and_Fixing_Motions.htm`, `50-Animation/Motion-Director/Basic-Concepts.htm`, `Setting-Hotkeys-with-Hotkey-Manager.htm`, `Snap-to-Surface.htm` (8.1), `02-Main-Menu/Menu_Animation.htm`, forum.reallusion.com/519260 (MixMoves), CC manual `06_Body/Setting_the_Floor_Contact_Planes.htm`.
+
+## 5. Face Animation
+
+### 5.1 Track structure
+- **Viseme track** → sub-tracks **Voice** (audio clip) and **Lips** (auto-generated viseme keys). **Expression** timeline = 4 tracks: **Muscle** (morph data), **Eye Blink**, **Eyeball**, **Head** (orient/tilt). **Facial Layer** tracks hold Face Key output. Face clips support Auto-Extend, Loop, Speed; layer keys copy/paste only within their originating clip. **Sample/Flatten** available to convert expression clips ↔ three-track layer keys. **Menu > Animation > Expression Clip Auto Crop** trims overlapping expression clips.
+
+### 5.2 AccuLips
+- Open: **Modify > Animation tab > Motion section > Facial group > Create Script**, or **Menu > Animation > Create Script > AccuLips** (other Create Script options: Record Voice, Text-To-Speech, Wave File).
+- Works only for **CC G1–G3+ Standard and CC Gamebase** characters. Audio: wav, mp3, m4a, aac, wma.
+- Workflow: Open Audio File / Record Voice → **Generate Text** (speech-to-text; fix red-highlighted words) → **Align** (word-by-word sync; or **Update Selected** for a range) → adjust word durations → **Apply** → visemes generated on Lips track. Optional: load a TXT/SRT script with identical filename to skip transcription; custom viseme-word pairs saveable to **dictionary**. TTS input auto-aligns. Old iTalk scripts convertible.
+
+### 5.3 Viseme editing & strength (3 levels)
+1. **Project/character level**: Modify > Animation tab > **Facial Animation Settings > Viseme Strength** slider. 2. **Clip level**: right-click voice clip on Viseme track > **Talking Style Editor** (hotkey 6) — per-clip viseme strength sliders. 3. **Individual key**: double-click viseme key (or empty cell to add) → **Lips Editor** (hotkey 7) — phoneme choice (e.g. "Phoneme: Oh") + **Expressiveness** slider (result visible after slider release).
+- **Smoothing mouth**: right-click Lips/Lip Options track range > **Lip Sync Options** → radio **Full Mouth** (+Smooth checkbox + smooth value) or **Parts** (independent lips / tongue / jaw sliders).
+
+### 5.4 Face Key panel (Menu > Animation > Face Key, or Modify > Animation tab)
+- Tabs: **Expression** (preset expression style sets via dropdown), **Modify** (detail morph sliders grouped: **Brow, Eye, Nose, Cheek, Mouth, Custom**), **Morph** (**Expressiveness** slider + **Revert**). **Muscle** editing: click highlighted face regions and drag in viewport to sculpt an expression; **Muscle Symmetrical Selection** for mirrored edits; **Reset to Zero** button. Keys land on **Facial Layer** tracks; blend sequential keys by placing the playhead between them. Muscle vs Detail distinction: Muscle = region-drag posing, Detail = per-morph sliders.
+
+### 5.5 Face Puppet (Menu > Animation > Face Puppet)
+- Real-time mouse-driven expression recording. Profiles: **Male, Female, Stylized** ("00_"-prefixed enhanced versions), **Universal** (mouth shut + six mouth expressions). **Facial Profile Strength** slider exaggerates/smooths. **Solo Feature Profile** states: None / Active / Selected. During Preview/Record: **left-click = blink**, hotkeys **Q W E R T Y** trigger Full Face Control Profile commands. **Profile Details** (Edit Property) table: 60 standard + 24 custom morphs. Preference > Control > "Confine Face Puppet area to 3D view-port". Attribute tab **Auto-Blink** toggle (disable during puppeteering).
+
+Sources: `50-Animation/Facial-Animation/Creating-Voice-Script-with-Accurate-Lipsync.htm`, `Three-Levels-of-Setting-Strength-for-Visemes.htm`, `50-Animation/Pro_Facial_Animation/Face_Puppet.htm`, `Face_Key_Editing.htm`, `Facial_Timeline.htm`, `51-Animation-Timeline-Editing/Adding_or_Modifying_Lip_Synching_Keys.htm`, `Smoothing_Mouth_Movements.htm`.
+
+## 6. Characters & Characterization
+
+- **CC4 Standard characters** (CC3+/CC Gamebase etc.): full feature support — Edit Motion Layer/HumanIK, facial system (AccuLips requires CC G1–G3+ Standard/Gamebase), Motion Director, sampling with "All Parts - Optimized". Created/edited in Character Creator 4; CC4's **Characterization panel** data (bone-mapping, bone-rotation, floor contact, **HIK property data**) is what iClone uses for retargeting.
+- **ActorCore characters/motions**: Reallusion's store rigs (AccuRig-rigged); load directly in iClone and accept iClone/ActorCore motions; AccuRig converts arbitrary humanoid meshes → compatible rigs.
+- **Non-standard/Humanoid characters**: custom FBX rigs are converted via CC4's **Convert to Non-Standard / Humanoid** (Characterization mode: map custom bones to standard iClone bones, adjust to **T-pose** — all `.iMotion` are T-pose-based; skipping T-pose causes body-part offsets when motions apply). 3DXchange's old conversion role now lives in CC4/AccuRig. Feature availability in iClone differs (e.g. sampling menu items differ for non-standard characters; AccuLips unsupported).
+- **Imported mocap interaction (core side)**: **File > Import > Import External Motion** (iClone 8.4+) accepts **FBX or BVH** motion for standard/humanoid characters. Options: **Motion Profile** (from CC Characterization data), optional **T-pose** file from the same source, **Sample Per Second** (higher = more detail), **Root Bone** dropdown (choose source root node), **Auto-generate to Perform List**; **Convert All** → clips stored under custom **Motion > External Motion** library. Once converted, mocap clips are ordinary motion clips: trim/loop/speed/time-warp, Motion Correction, sample-to-layer + Curve Editor filtering, Edit Motion Layer layering, Reach Target locking.
+- **Props/Accessories**: animate via **Transform track** keys, **Prop Puppet**, **Edit Animation Layer**, Morph Animator; clip form = Animation clips ("Sample/Flatten Animation Clip"); collect via Collect Clip > Add to Perform (List). Constraint animation via Link/Attach/Path/Look At dummy workflows, flattened before export.
+
+Sources: `8.4/50-Animation/Import-External-Motions/Import-External-Motions.htm`, CC4 manual `09-Import-Humanoid/*`, 3DXchange 6 legacy `Converting_Models_to_Non_Standard_Characters.htm`, actorcore.reallusion.com learn-and-support.
+
+## 7. Import / Export
+
+- **Menu paths**: `File > Export > Export FBX...` | `Export Alembic...` | `USD (Omniverse)`. `File > Import > Import External Motion` (mocap in). 3DXchange is **discontinued**; all conversion/export features merged into iClone 8 / CC4 (kb.reallusion.com/Product/53036) — iClone 8 ships pipeline-capable (FBX/OBJ export built in, no separate Pipeline SKU).
+- **Export FBX dialog** (verbatim, from manual screenshots): **Target Tool Preset**: Maya, 3ds Max, Unity 3D, Unreal (UE4 Skeleton), Unreal (UE5 Skeleton), Motion Builder, Blender, Cinema 4D, **Maya (Motion Pipeline)**, **Motion Builder (Motion Pipeline)**, Marmoset Toolbag. Preset changes downstream settings incl. axis conversion (no manual Y-up/Z-up radio in iClone 8; legacy 3DXchange had explicit Y-Up/Z-Up choice). **FPS** dropdown (default `Project(60)`). **Export Range**: T-Pose (no animation, avatar moved to origin (0,0,0)) / Current Frame / All / Range (From/To). Checkboxes: **Embed Textures**, **Embed Timeline Timecode**, **Max Texture Size** (default on, 2048), **Convert Image Format to** (default Bmp shown; JPG if unset), **Delete Hidden Face**, **Use Smooth Mesh**, **Convert Skinned Expressions to Morphs**, **Merge Face Hair to One Object**, **Delete Unused Morphs**, **Tear Ducts UV Adjustment** (character can't round-trip to CC if on).
+- **Export FBX Advanced Settings** (gear icon): **Merge Opacity to Diffuse Texture**, **Preserve Bone Names (CC Base)** (default on), **Mouth Open as Morph**, **Epic Skeleton** (UE4 Skeleton / UE5 Skeleton radio), **Epic Skeleton Hand and Foot IK**, **Reset Motion Root**, **Export Weight-map to Vertex Color** (default on), **Use T-Pose As Bind Pose**, **Reset Bone Scale** (default on), **Add Reference Pose** (default on) with radio: T-Pose for Unity / A-Pose for UE4 Skeleton / A-Pose for UE5 Skeleton / A-Pose for UEFN. Also **Export JSON for Auto Material Setup** (default on, for Auto Setup plugins) `[per Auto Setup manual]`.
+- **Root motion**: **Reset Motion Root** — since 7.6, for Unity/Unreal game-engine presets the root node **follows the hip** instead of staying at origin; needed for root-motion scripting/blending in engines. Constraint animation must be flattened first (**Animation > Flatten All Motion with Constraint**). Motion-only export: use the **(Motion Pipeline)** presets.
+- **Batch export**: select multiple objects; with Target Tool Preset = **Unreal** or **Unity 3D** each object exports to a **separate FBX** named after the iClone object; any non-game-engine preset merges all picked objects into **one** FBX.
+- **Non-exportable types**: iLight, iEffect, iParticle, iTree, iGrass, iTerrain, iWater, iSky, aml, iTalk, iPath.
+- **USD**: via free **Omniverse connector plugin** — Menu > Plugin > Omniverse > Export USD, File > Export, or toolbar. Options: Export All/Selected; Material Render Mode (RTX Real-Time = OV PBR shader; RTX Interactive Path Tracing = SSS MDL for digital humans); Export Range > **Motion FPS: 60/30/24**; Send to Server (Nucleus). Outputs main USD + light/material/motion dependency folders.
+- **BVH**: **import** supported (Import External Motion); **BVH export is NOT available from iClone 8** — legacy BVH export was 3DXchange Pipeline; CC4 4.4+ has BVH export (see export-pipeline-to-blender-godot.md §3).
+- **Blender/Godot**: Blender via Target Tool Preset "Blender" + free **CC/iC Blender Tools** (soupday) importer; Godot has **no preset** — use Unity 3D or Blender preset FBX, or round-trip through Blender→glTF `[workflow inference, not Reallusion-documented]`.
+- **Licensing**: Reallusion content items require an **Export License** to leave the Reallusion ecosystem in FBX/OBJ/USD ("You must first purchase the content licenses in order to export FBX and USD files" error otherwise); iClone-only content (legacy "maroon" items) is blocked without it. Your own imported/created assets are unrestricted. FBX-key/`.fbxkey` applies to CC character mesh round-trips. Export License purchase deducts already-owned iContent cost.
+- **Alembic** export exists for vertex-cache workflows (`Export Alembic...`).
+
+Sources: `83-FBX/FBX_UI_Intro.htm` (+ dialog screenshots), `Exporting_FBX_from_iClone.htm`, `Batch_Exporting_FBX_Files.htm`, `Resetting_Motion_Root.htm`, kb.reallusion.com/Product/53036, reallusion.com/ContentStore/Export_License.pdf, Omniverse plugin manual (iC-8.3), forum.reallusion.com/556427.
+
+## 8. System Fundamentals
+
+- **Frame rate**: Project Settings > **Time Unit** section — FPS dropdown per project; **default project length 1800 frames, maximum 54000**; timeline "Actual Size" = 1 cell : 1 frame **at 60fps** (iClone's native/internal sampling is 60fps; FBX FPS default `Project(60)`; render/export offers 12/24/25/30/60). Time Mode: Realtime vs **By Frame** (physics). Time Unit display: time-based or frame-based.
+- **Units**: **1 iClone unit = 1 cm**; default grid 100×100 units = 1×1 m. CC characters ≈175 units tall. Matches Unreal cm scale directly.
+- **Axes**: iClone is **Z-up** (Reallusion: "iClone and 3DXchange are Z-Up based 3D tools"); corroborated by Edit Motion Layer "Vertical Pose Alignment includes Z-axis values". FBX export axis conversion is handled by the Target Tool Preset (Y-up conversion for Maya/Unity etc.). Character bones do **not** share a common up-vector (spine Z-up, legs point down, feet back) — a known pain point when retargeting exported skeletons. A literal `Z_UpAxis` node/track name: not found in iClone 8 docs `[UNVERIFIED — likely a 3DXchange-era conversion dummy]`.
+- **Key global shortcuts**: Space play/pause; ,/. start/end frame; ←/→ frame step; **F3 Timeline**, **F11 Animation Layer panel**, **F12 Curve Editor** (Shift+ variants focus); **N = Edit Motion Layer**; Q/W/E/R = Select/Move/Rotate/Scale; Ctrl+Z/Ctrl+Y undo/redo; X/Z/C/V camera Pan/Zoom/Orbit/Roll; Home = 45° perspective; F = front view of selection. Timeline-specific keys in §2.2. All remappable: **Edit > Hotkey Manager (Ctrl+`)** — Device: Keyboard, expand item, press new key.
+- **Rotation order**: editable per object via **Menu > Animation > Rotation Order** (Euler order — matters for curve editing and export). **Remove Object Animation** / **Remove Scene Animation** clear animation (scene removal offers frame-position options).
+
+Sources: `03-Introducing-the-User-Interface/Project_Settings_Time_Unit.htm`, `90_Keyboard_Shortcuts/Global_Shortcuts.htm`, `Timeline_Shortcuts.htm`, `Hotkey-Manager.htm`, 3DXchange5 `Y_Up_or_Z_Up.htm`, forum.reallusion.com/109018 & /326528 (cm units), forum.reallusion.com/525257 (bone axes).
+
+---
+
+Key gotchas worth surfacing: layer keys can't leave their clip; flatten-between-iterations for Motion Correction; Flatten All Motion with Constraint before FBX export; MixMoves removed in iC8; AccuLips is CC-Standard-only; game-engine presets (Unreal/Unity) are the only batch/per-file + Reset-Motion-Root paths; 60fps internal / cm / Z-up when planning Godot import.

.claude/skills/iclone-video-mocap/references/video-mocap-plugin.md

@@ -0,0 +1,134 @@
+# Reallusion AI Video Mocap for iClone 8 — Reference (researched 2026-07-15)
+
+## 1. Product Disambiguation (Reallusion mocap ecosystem, mid-2026)
+
+| Product | What it is | Body/Face | Input | Pricing model |
+|---|---|---|---|---|
+| **iClone Video Mocap** (plug-in) | AI body mocap from ordinary video, powered by **QuickMagic** cloud AI. THE "video mocap plugin". Launched **Oct 29–31, 2025** | Body + fingers; **NO face** | Recorded video file | Free plugin; pay-per-use points per generation (cloud) |
+| **AccuFACE** (Motion LIVE gear) | AI **facial** tracker from webcam (live) or video file (offline). Local NVIDIA RTX inference | Face only | Webcam or video file | Perpetual plugin, $499 MSRP (launch promo $250, Nov 2023) |
+| **Motion LIVE** | Hub plugin aggregating real-time mocap hardware/gear (Xsens, Rokoko, Perception Neuron, Leap Motion, iPhone LIVE FACE, Faceware, AccuFACE) into one unified real-time recording panel | Body+face+hands (via gear) | Live hardware streams | Hub + per-gear profile purchases |
+| **Motion Director** | Gameplay-style interactive character locomotion/control system inside iClone (WASD-style driving, not video mocap) | Body locomotion | Keyboard/gamepad | Built into iClone 8 |
+
+Video Mocap deliberately does NOT do faces — official workflow layers AccuFACE (or iPhone LIVE FACE) on top for talking animations.
+Sources: https://www.cgchannel.com/2025/10/reallusion-launches-ai-motion-capture-service-video-mocap/ , https://www.reallusion.com/iclone/motion-capture/default.html
+
+## 2. Video Mocap — Identity, Versions, Requirements
+
+- Exact name: **"iClone Video Mocap"** / **"Video Mocap Plug-in for iClone"**. Tagline: "Precise AI Mocap from Any Video".
+- Technology partner: **QuickMagic** (AI mocap provider); processing is **cloud/online** (upload video → AI conversion on QuickMagic cloud → download motion). Not local; no GPU requirement for generation itself.
+- Requirements: **iClone 8.63 or above**, **Windows 10 & 11 only**. Plugin itself is a **free download**, installed/updated via **Reallusion Hub**.
+- Version history: launch ~v1.0 (Oct 2025, alongside iClone 8.63); **v1.02 (announced 2026-02-26)** — urgent fix for task-status-refresh bug that caused re-submission and **redundant point charges** after closing the app; also added diagnostic logs and auto-recovery of task statuses from local video/motion files. Users on iClone 8.71 + plugin 1.02 reported in forum (Mar 2026+). Manual page shows revision date June 8, 2026.
+- Official manual root: https://manual.reallusion.com/iclone-video-mocap-plug-in/content/welcome.htm (sections: Workflow, Full Body, Upper Body, Import, Edit, Generate (purchase.htm), Apply, Save, Adding Facial Expression (talking-animation.htm), Video Guidelines (rule.htm)).
+
+Sources: https://www.reallusion.com/iclone/video-mocap/download.html , https://discussions.reallusion.com/t/urgent-update-video-mocap-1-02-fixes-task-status-refresh-bug-to-prevent-redundant-charges/16659
+
+## 3. Pricing
+
+- Current metering (product page + manual, mid-2026): **5 points per second of processed video** (AI / Bonus / DA Points), **100 points = US$1.00** → **$0.05/sec, max $3.00 for a 60 s task**. Deduction order: **AI Points → Bonus Points → DA Points**.
+- At launch (Oct 2025) press reported a flat **250 DA Points (US$2.50) per task** up to 60 s; the Apr 2026 beginner article still says "$2.50 per motion". Flat-250 vs 5/sec discrepancy: pricing appears to have moved to per-second metering; treat exact figure as ~$2.50–3.00/generation [UNVERIFIED which applies at any given moment].
+- Points sources: **DA Points** ($10 / $50 / $100 packs, min $10 spend) or **Reallusion AI Cloud subscription** AI Points (FREE $0 = 500 pts; STARTER $11/mo = 1,100; STANDARD $35/mo = 3,500; PRO $95/mo = 9,500; annual −20%). AI Points are universal across AI Studio, Video Mocap, Headshot image gen. DA:AI = 1:1 value.
+- Fully licensed iClone users get complimentary Video Mocap generation coupon(s); one coupon = one task regardless of duration. (Launch promo advertised "100 free AI mocap generations" limited-time; one forum user mentions losing "5 complimentary generations" — exact freebie count varies by promo [UNVERIFIED].)
+- Failed tasks: Reallusion support has refunded points for failed tasks case-by-case (forum evidence). Verify tasks/transactions: https://kb.reallusion.com/Print53250.aspx
+
+Sources: https://manual.reallusion.com/iclone-video-mocap-plug-in/content/purchase.htm , https://ai.reallusion.com/plans.html , https://www.cgchannel.com/2025/10/reallusion-launches-ai-motion-capture-service-video-mocap/
+
+## 4. Workflow (official 5 stages: Import Video | Edit Video | Generate Motion | Apply Motion | Save Motion)
+
+### 4.1 Import Video
+- Open the plugin from iClone's Plugins menu after Hub install [menu path UNVERIFIED, standard for RL plugins].
+- Import via **"+ Add Video"** button or drag-and-drop into the panel.
+- **13 supported formats**: `.avi .flv .m4v .mkv .mov .mp4 .mpeg .ogv .webm .wmv .3gp .asf .dv .mxf`.
+- Source video duration: **1 s – 15 min** accepted; **processing region must be 1–60 s** (longer videos auto-trimmed or must be trimmed). Max file size **400 MB** (else reduce bitrate/rescale/compress/trim). Resolution: **≥720p recommended; 4K accepted but may hurt performance**. FPS not specified.
+- Task queue: up to **100 videos**; batch generation: up to **10 tasks at once**. Statuses: Unprocessed → Trimmed → (processing) → Applicable / Error.
+
+### 4.2 Edit Video panel
+- Drag playhead to preview; drag **Start Time** / **End Time** handles to set the processing region (timecode MM:SS:FF); drag the whole region to shift it with fixed duration; **Reset Range** restores full span; **Apply Settings** confirms → status "Trimmed".
+- **Detect Actors** button: when multiple people are in frame, click it and pick the single target actor in a frame where they are clearly visible. **One actor per task**; for group scenes, duplicate the task per performer and select a different detection each time.
+- Trim out segments where no person appears (hurts AI quality).
+
+### 4.3 Generate Motion
+- Choose tracking mode: **Full Body** (default) or **Upper Body**; optional **"Includes Fingers"** checkbox in both modes for finger capture.
+- Full Body: whole body must be clearly visible throughout. Upper Body: designed for framing cut off below the pelvis (sign language, instrument playing, speech); everything below the hip is ignored/not generated.
+- Submit → upload → cloud processing, typically **5–8 minutes per task**; progress monitored in the task list. Insufficient points → "Add Funds" / "Cancel" dialog.
+
+### 4.4 Apply Motion
+- Select completed task → **Apply Motion** button (bottom-right), or double-click the task, or right-click → **Apply Motion**.
+- Motion is saved as **rlMotion** to a preset folder and applied to the **currently selected character**; if none selected, **a dummy character is auto-loaded**. Auto-retargeting adapts the motion to any iClone/CC4/AccuRIG standard character body type.
+- **"Apply reference video"** checkbox: loads the source video as a 2D background object in the viewport behind the character for frame-by-frame comparison during cleanup.
+
+### 4.5 Save Motion
+- Auto-saved to Content Manager **Animation > Motion > VideoMocap**; default disk path `C:\Users\Public\Documents\Reallusion\Reallusion Custom\Animation\Motion\VideoMocap`. Folder button changes path; Reset restores default. Right-click task → **Find Motion File**. Thumbnail from Edit Video frame (Quick Thumbnail on) or posed character (off).
+
+Sources: https://manual.reallusion.com/iclone-video-mocap-plug-in/content/video-mocap-workflow.htm , .../import.htm , .../edit.htm , .../purchase.htm , .../video-mocap-full-body.htm , .../video-mocap-upper-body.htm , .../apply.htm , .../save.htm
+
+## 5. Official Video Guidelines (rule.htm) — filming rules
+
+- **Camera angle**: flat/eye-level. Overhead or elevated angles make the result lean forward/backward.
+- **Camera motion**: static camera, single continuous shot, no cuts/switched shots; only minor shake tolerated ("Counteracts camera shakes" is marketing — keep it steady).
+- **Framing**: entire actor (or pelvis-up for Upper Body) visible for the whole clip; "any body part that moves out of the frame will present a problem". Actor not too small in frame; size consistent (no zooms/dollies).
+- **Clothing**: avoid solid colors and colors matching the background; patterns/texture are fine.
+- **Background/lighting**: clean and bright preferred, though the engine tolerates dim light, busy backdrops, patterned clothing.
+- **Motion restrictions**: avoid very fast motion, violent shaking, acrobatic flips, vertical actions (pull-ups, jumps), and ungrounded-feet activity (swimming).
+- **Occlusion**: single person only; avoid limbs intersecting other actors; avoid hand-occluding poses ("running fingers through hair").
+
+Source: https://manual.reallusion.com/iclone-video-mocap-plug-in/content/rule.htm
+
+## 6. Cleanup / Post-Processing in iClone (official recommended tools)
+
+Artifact → tool mapping (from Reallusion Magazine + 80.lv + tutorials):
+- **Foot sliding** → **Motion Correction** tool (Motion Correction for Sliding Issues, iClone 8 manual) + **Reach Target** to lock/release foot positions; also Foot Contact tool + iClone footstep visualization. Official tutorial: "Mocap Motion Fix – Eliminating Foot Sliding | iClone 8 Tutorial" (https://www.youtube.com/watch?v=t8yeA-DJ0ds).
+- **Sudden elevation changes / abrupt vertical pops** → dedicated fix tutorial "Fixing Sudden Elevation Change"; edit hip height in Curve Editor.
+- **Depth misalignment / motion offset** → **Auto Motion Alignment** / Root Alignment.
+- **Jitter/noise** → **Curve Editor** smoothing.
+- **Sudden body twists / rotating limbs** → Motion Layer editing with HumanIK controls.
+- **Hand/gesture errors** → iClone gesture tools / hand pose library.
+- **Missing or garbage frames** → rotoscope against the 2D reference video and bridge with transition curves.
+- The auto-loaded reference-video background is the key rotoscoping aid — compare character to footage in real time.
+- **Gotcha**: if the applied clip has **Loop** enabled, motion-layer edits "spring back" (looped frames reference the source); **Flatten** the motion clip (or disable Loop) before keyframe editing (forum-confirmed staff answer).
+- Tutorial course hub: https://courses.reallusion.com/home/iclone/pipelines/video-mocap-plug-in
+
+Sources: https://magazine.reallusion.com/2025/10/29/iclone-video-mocap-converts-videos-into-editable-3d-motion/ , https://80.lv/articles/getting-ai-mocap-ready-for-production-with-reallusion-s-iclone-8 , https://discussions.reallusion.com/t/cant-adjust-motions-after-applying-from-video-mocap/16711 , https://manual.reallusion.com/iClone-8/Content/ENU/8.0/51-Animation-Timeline-Editing/Motion-Correction-for-Sliding-Issues.htm
+
+## 7. Adding Face (talking animation) — official 7-step layering with AccuFACE
+
+1. Apply Video Mocap body motion + reference video. 2. In **AccuFACE VIDEO mode**, load a speech video framed on the actor's head (RL strongly recommends **separate recordings for body and face**). 3. Connect AccuFACE in **Motion LIVE**, enable **"Audio for Viseme Track"** (auto voice clip). 4. Preview + record facial clips via Motion LIVE. 5. Align viseme/expression clips to the motion clip on the timeline using the reference video. 6. Verify sync in playback. 7. Save to Content Manager custom library.
+Source: https://manual.reallusion.com/iclone-video-mocap-plug-in/content/talking-animation.htm
+
+## 8. AccuFACE (face-from-video) — key facts
+
+- Motion LIVE gear plugin; **iClone 8.6+**, Windows 10/11 64-bit, 8 GB RAM, **NVIDIA RTX only** (20/30/40/50 series + RTX Pro; driver 520.46+ or 572+ for RTX 50) — local GPU inference, no cloud, no AMD/Intel support. $499 MSRP (frequent discounts).
+- Input: live webcam (min 1280×720@30fps; 720p/30 optimal) or video files (**AVI, WMV, MP4, MKV, MOV**). Captures up to 60 fps facial data; single-pass audio + face capture; **AccuLIPS** refines lip/tongue; output framerate-independent (24/30/60 fps).
+- Calibration: guided process (live mode) or pick calibration poses across video frames (video mode). Refinement controls: **Strength Balance** (per-region), **Smooth Filter**, **Denoise**, **Anti-Interference** (cross-region triggering).
+Source: https://www.reallusion.com/iclone/motion-capture/accuface.html
+
+## 9. Known Limitations & Community Issues
+
+- Hard limits: 60 s/task, 1 actor/task, no face capture, cloud-only (needs internet + points), 400 MB file cap, 10-task batch cap.
+- AI-typical artifacts acknowledged by Reallusion itself: foot sliding, depth misalignment, unnatural twists, jitter — cleanup is an expected part of the workflow, not an edge case.
+- Failure modes: subject leaving frame, background-matching clothing, fast/occluded motion, spins with limb occlusion, airborne/ungrounded feet.
+- Forum-reported bugs: (a) pre-1.02 task-status refresh bug → duplicate charges (fixed in 1.02); (b) failed tasks bricking the queue — Error tasks with retry/delete greyed out and Generate Motion disabled for all new videos; support refunded points but the user had to hand-edit plugin task files to recover (https://discussions.reallusion.com/t/video-mocap-problem/17173); (c) Loop-enabled clips blocking motion-layer edits (see §6).
+- Community consensus: results are solid for grounded, single-person, moderate-speed motion; twitchy feet and torso rotation remain the main manual-cleanup costs, consistent with other AI mocap (DeepMotion, Plask).
+
+## 10. Best-Practice Tips (Reallusion Magazine "Video Mocap for Beginners", Apr 2026)
+
+- A mid-range phone (Samsung A54) or 1080p webcam (Logitech C922) on a tripod is fully sufficient; ordinary home lighting worked.
+- Rehearse, then **overact** mundane motions; record multiple takes.
+- **Stack multiple motions in one 60 s clip with ~2 s gaps** between them — one generation fee yields several clips to split in iClone.
+- Pre-trim in an external editor; use real props to anchor hand positions and prevent hand drift.
+- Use Upper Body mode + Includes Fingers for seated/talking/instrument performances.
+Source: https://magazine.reallusion.com/2026/04/13/video-mocap-for-beginners/
+
+## 11. Brief Comparison
+
+- **vs Motion LIVE hardware**: Motion LIVE = real-time, suit/camera hardware ($$$–$$$$), no per-use fee, best fidelity and long takes; Video Mocap = offline, zero hardware, ~$2.50–3/clip, 60 s cap, cleanup required. Reallusion positions them as hybrid-complementary (ActorCore packs + hardware for hero shots, Video Mocap for bulk/reference-driven motion).
+- **vs free/DIY (Rokoko Video free tier, DeepMotion, Plask, open-source VIBE/4DHumans pipelines)**: those export FBX/BVH requiring manual retarget; Video Mocap's differentiator is native rlMotion output, auto-retargeting to CC4/AccuRIG characters, the in-viewport reference-video rotoscope, and direct access to iClone's correction toolset — then FBX/USD export from iClone to Unreal, Unity, Blender, Maya, MotionBuilder.
+
+## 12. Primary Sources
+
+- Product: https://www.reallusion.com/iclone/video-mocap/ | Download: https://www.reallusion.com/iclone/video-mocap/download.html
+- Manual: https://manual.reallusion.com/iclone-video-mocap-plug-in/content/welcome.htm (+ import/edit/purchase/apply/save/rule/talking-animation/video-mocap-full-body/video-mocap-upper-body .htm)
+- Magazine: https://magazine.reallusion.com/2025/10/29/iclone-video-mocap-converts-videos-into-editable-3d-motion/ , https://magazine.reallusion.com/2026/04/13/video-mocap-for-beginners/
+- Press: https://www.cgchannel.com/2025/10/reallusion-launches-ai-motion-capture-service-video-mocap/ , https://beforesandafters.com/2025/11/08/iclone-video-mocap-converts-videos-into-editable-3d-motions/
+- AI plans: https://ai.reallusion.com/plans.html | AccuFACE: https://www.reallusion.com/iclone/motion-capture/accuface.html
+- Forum: https://discussions.reallusion.com/t/urgent-update-video-mocap-1-02-fixes-task-status-refresh-bug-to-prevent-redundant-charges/16659 , /t/video-mocap-problem/17173 , /t/cant-adjust-motions-after-applying-from-video-mocap/16711
+- Courses: https://courses.reallusion.com/home/iclone/pipelines/video-mocap-plug-in | 80.lv: https://80.lv/articles/getting-ai-mocap-ready-for-production-with-reallusion-s-iclone-8