@kieransimkin/dance-rudiments 0.2.4 → 0.4.0

package/docs/rig-motion.md

@@ -0,0 +1,285 @@
+# Rigify character motion on the DanceRudiments clock
+
+This extension binds the existing native **N-dimensional Recording** to a
+versioned Blender Rigify control profile. Each model has a semantic type URL;
+each physical parameter has a fixed, one-based channel number. A compiled motion
+retains the profile, source timing, provenance and normalized samples together.
+
+The core authoring code is standard-library Python. Live playback still uses
+C++ `SampledRecording` at **64 integer pips per quarter-note beat**. Blender is
+the optional environment for importing, evaluating and driving a rigged mesh.
+Existing XYZ patterns, the 1,731-pattern catalogue and their looping semantics
+are unchanged. Rig motions are **non-looping** and reject out-of-range pips.
+
+## Models and types
+
+The checked-in inventory was generated using the actual **Blender 5.2.2 LTS**
+Rigify implementation. It covers eight metarigs and 28 component types. The
+[Rigify catalogue guide](rigify-catalogue.md) records the exact build, source
+hashes, channel counts, component contexts and regeneration command.
+
+| Rigify preset | Motion type |
+| --- | --- |
+| Human | `syn://type/danceflow/motion/rigify/metarig/human` |
+| Basic human | `syn://type/danceflow/motion/rigify/metarig/basic/basic_human` |
+| Basic quadruped | `syn://type/danceflow/motion/rigify/metarig/basic/basic_quadruped` |
+| Bird | `syn://type/danceflow/motion/rigify/metarig/animals/bird` |
+| Cat | `syn://type/danceflow/motion/rigify/metarig/animals/cat` |
+| Horse | `syn://type/danceflow/motion/rigify/metarig/animals/horse` |
+| Shark | `syn://type/danceflow/motion/rigify/metarig/animals/shark` |
+| Wolf | `syn://type/danceflow/motion/rigify/metarig/animals/wolf` |
+
+Component types have a parallel hierarchy, for example
+`syn://type/danceflow/motion/rigify/component/limbs/arm` and
+`syn://type/danceflow/motion/rigify/component/spines/super_spine`.
+`synny://` URLs resolve to the **same identity** as their `syn://` equivalents.
+The tree is an interchange convention; it does not add a Potbot dependency or
+modify another repository's type registry.
+
+Rigify's presets are configurable. A rig with edited proportions, extra bones,
+different generation settings or another Blender build needs its **own exported
+profile**. The model type can remain the same while its profile fingerprint
+changes. Neither bone count nor matching names establishes rig compatibility.
+
+## Numbered channel contract
+
+A `dancerudiments.rig-profile` document declares:
+
+| Field | Meaning |
+| --- | --- |
+| `type_uri`, `model`, `version` | Semantic model identity and explicit profile version |
+| `channels[].number` | Persistent one-based parameter number; column index is `number - 1` |
+| `name` | Unique Recording dimension name |
+| `bone`, `data_path`, `array_index` | Exact Blender control and component to drive |
+| `unit` | Blender units, radians, unitless values or other explicitly declared units |
+| `minimum`, `maximum`, `neutral` | Physical range and neutral value |
+| `value_type`, `interpolation` | Float, integer or Boolean; linear, quaternion or step behavior |
+| `enum_items` | Valid numeric choices and labels for discrete enum controls, when present |
+| `rotation_mode` | The actual generated control's Euler order, quaternion or axis-angle mode |
+| `source` | Blender/Rigify identity, rest matrices, parents, locks and scene-unit metadata |
+
+The initial export enumerates actual controls deterministically. When extending
+an exported profile, `--previous` preserves the old channel numbers and appends
+new parameters. Removed or changed parameter definitions fail rather than
+silently reusing an old number. The explicit version and SHA-256 fingerprint
+accompany every capture and motion. A fingerprint detects mismatched data; it is
+not a digital signature or a guarantee that a source is trustworthy.
+
+The generated manifests cover writable **animator control transforms and numeric
+custom properties**, including IK/FK blends and parent selectors where present.
+Rigify's internal `ORG-`, `DEF-`, `MCH-` and `VIS-` bones are excluded from direct
+control. The existing rig evaluates its constraints and drives the bound mesh.
+Static metarig-generation parameters are inventoried separately: segment counts,
+widget choices and similar settings are not time-varying motion channels.
+
+Local transforms remain in Blender's coordinate convention. Exported presets use
+explicit bounds: location ±10 Blender units, Euler angles ±4π radians, scale
+0..4, quaternion components −1..1, and custom properties' declared ranges.
+These are encoding limits, not anatomical joint limits. Set suitable bounds when
+exporting a real character, especially one with large root translation. Values
+outside the chosen range fail; they are never silently clamped or independently
+renormalized per clip.
+
+Physical values encode into the existing bipolar Recording contract:
+
+```text
+normalized = 2 * (physical - minimum) / (maximum - minimum) - 1
+physical = minimum + (normalized + 1) * (maximum - minimum) / 2
+```
+
+Every stored scalar remains finite float64 within `[-1,1]`, rounded to twelve
+decimals. Quaternions are complete `w,x,y,z` groups and must have unit magnitude.
+Boolean/integer selectors use held values, never fractional intermediate choices.
+Quaternion interpolation uses shortest-path SLERP during compilation. Existing
+Euler controls keep their actual rotation order and sampled winding; unwrap
+source discontinuities before capture. The profile does not force Euler-based
+Rigify controls into quaternion mode.
+
+## Inspect or export the mappings
+
+From a source checkout, the CLI works without installing a native extension for
+inspection and authoring:
+
+```sh
+python tools/rig_motion.py catalogue
+python tools/rig_motion.py profile human --output generated/human.profile.json
+python tools/rig_motion.py channels generated/human.profile.json --output generated/human.channels.csv
+python tools/rig_motion.py profile limbs.arm --kind component --output generated/arm.profile.json
+python tools/rig_motion.py sources
+```
+
+After installing this source revision, `dancerudiments-rig` is the same command.
+The catalogue JSON and all profile JSON files are shipped inside the Python
+package. The CSV includes every numbered parameter; no XYZ truncation occurs.
+Existing outputs are preserved unless `--overwrite` is explicit. Conversion
+commands refuse output paths that are also their inputs.
+
+## Import and capture real animation
+
+The Blender bridge is available as the packaged
+`dancerudiments_authoring.blender_bridge` module and through
+`tools/blender_rigify_bridge.py`. The latter wrapper is useful with Blender's
+`--python` command. Playback requires the native DanceRudiments extension for
+the **Python ABI used by that Blender**. Authoring-only import/profile/capture
+operations do not require the native extension.
+
+First import a local file using Blender's supported interchange importers:
+
+```sh
+blender --background --python tools/blender_rigify_bridge.py -- import-source dance.bvh --save imported-source.blend
+```
+
+FBX and glTF/GLB are also accepted. This imports the recording's skeleton and
+animation. Use an explicit retargeting workflow in Blender to map it onto the
+chosen generated Rigify rig, correct the rest-pose/bone bases and root scale,
+choose the appropriate FK/IK controls, and **bake the control animation**. Save
+that result as, for example, `dancer-retargeted.blend`.
+
+Export the exact character profile and capture its controls:
+
+```sh
+blender --background dancer-retargeted.blend --python tools/blender_rigify_bridge.py -- export-profile --armature rig --model my_dancer --output generated/dancer.profile.json
+blender --background dancer-retargeted.blend --python tools/blender_rigify_bridge.py -- capture-action --armature rig --profile generated/dancer.profile.json --frame-start 1 --frame-end 121 --output generated/dance.capture.json
+```
+
+`--model` is your rig instance's stable descriptive identifier. `--kind metarig`
+with the original model identifier is appropriate when preserving a preset's
+model type. `--location-range`, `--rotation-range` and `--scale-max` choose the
+export contract; modifying these later requires a new capture/profile identity.
+
+Capture times are in seconds relative to the first selected Blender frame. The
+source musical beat-zero offset must use **that same origin**. FPS and captured
+frame range are retained in provenance. The bridge restores the previous scene
+frame after capture. BVH import preserves its source FPS. Fractional frame bounds
+allow precise imported endpoints; see `capture-action --help` for frame-step and
+sample-rate controls.
+
+The bridge reads baked control values. It does not infer a foreign skeleton's
+mapping, embed arbitrary Python in motion JSON, or replace Rigify's constraints.
+Object placement, mesh shape keys and third-party feature-set controls require
+an explicit appropriate rig/profile integration; they are not silently inferred
+from humanoid motion.
+
+## Beat matching and compilation
+
+A `dancerudiments.rig-capture` stores physical frame values and timestamps without
+binding them to music yet. A source `BeatMap` supplies strictly increasing
+`(seconds, beat)` anchors, or a constant BPM plus a separately supplied beat-zero
+time. There is no automatic tempo estimate or first-beat guess.
+
+```sh
+python tools/rig_motion.py compile generated/dance.capture.json generated/dance.motion.json --name dance_phrase --source-bpm 100 --source-beat-zero 0.18 --bpm 124 --samples 512
+```
+
+That example creates an eight-beat grid (512 pip rows). It requires sufficient
+source motion after its 0.18-second beat origin. At every absolute output pip `p`:
+
+```text
+source_beat = source_beat_offset + motion_rate * p / 64
+source_seconds = source_beat_map.inverse(source_beat)
+```
+
+`--source-beat-offset` selects a source excerpt. `--motion-rate 1/2` uses half a
+source beat per playback beat; `2` uses two. `--start-pip` is an absolute output
+beat position, including negative pickups; it is not an independent clip-local
+offset. For a desired source beat `s` at start pip `p0`, use
+`source_beat_offset = s - motion_rate * p0 / 64`.
+
+For drifting tempo or manually marked motion accents, use
+`--source-beat-map beats.json` instead of `--source-bpm`/`--source-beat-zero`.
+Anchors interpolate linearly in accumulated beat position; the inverse maps back
+to source time. A measured map is bounded unless extrapolation is explicitly
+enabled. Source frame bounds are always enforced. There is no automatic looping,
+endpoint extension, foot-plant correction or seam repair.
+
+`--bpm` records the **nominal target tempo** for standard Recording compatibility.
+The compiled samples are indexed by musical position and can subsequently play
+under a different fixed or variable target tempo. The original source tempo map
+is retained separately in provenance; it is not replaced by the target BPM.
+
+## Native playback and Blender baking
+
+```python
+from dancerudiments_authoring import BeatMap, load_rig_motion
+
+motion = load_rig_motion("generated/dance.motion.json")
+player = motion.player()  # actual C++ SampledRecording
+values = player.sample(64)              # physical values in channel order
+numbered = player.by_channel(64)        # {one_based_channel_number: value}
+target = BeatMap.from_bpm(124, beat_zero_seconds=0, source="song tempo")
+values_at_time = player.sample_time(0.5, target)
+```
+
+The target transport determines each pip from **absolute** audio time. A variable
+tempo map integrates successive beat intervals instead of multiplying all
+elapsed time by the latest BPM. Repeated seeks do not leave an accumulated phase.
+`pip_at()` uses floor for negative positions. There is no Python playback fallback
+when the native extension is missing.
+
+To apply a native sample or bake the whole motion into a new Blender Action:
+
+```sh
+blender --background dancer-retargeted.blend --python tools/blender_rigify_bridge.py -- apply --armature rig --motion generated/dance.motion.json --pip 64 --save posed.blend
+blender --background dancer-retargeted.blend --python tools/blender_rigify_bridge.py -- bake --armature rig --motion generated/dance.motion.json --action-name DanceRudimentsDance --save danced.blend
+```
+
+`bake --target-beat-map beats.json` supplies a variable target tempo. The output
+frame start anchors the recording's first pip; subsequent pip times use the
+target map's inverse. Without a target map, the recording's nominal fixed tempo
+sets spacing. This places a clip at `--frame-start`, including for negative or
+nonzero starting pips, rather than preserving the original transport's absolute
+beat-zero time. Baked keyframes use constant interpolation to retain the exact
+integer-pip contract. Any smoother rendering is an explicit consumer choice.
+`apply` creates a one-pose Action so the requested pose survives reopening the
+saved scene. Both output operations use full-influence replacement and disable
+NLA evaluation for that armature; previous Actions and NLA data are retained.
+Output `.blend` files must be new paths. Rig/profile mismatches fail before
+applying values.
+
+## Interchange and existing consumers
+
+`dancerudiments.rig-motion`, schema 1, contains `type_uri`, `profile_sha256`,
+`profile` and an unchanged `dancerudiments.recording` schema-1 document. Loaders
+reject unknown fields, duplicate JSON keys, non-finite values, invalid discrete
+controls/quaternions and mismatched columns or profile hashes.
+
+```sh
+python tools/rig_motion.py inspect generated/dance.motion.json
+python tools/rig_motion.py recording generated/dance.motion.json generated/dance.recording.json
+```
+
+The extracted recording works with the existing native C++/Python N-dimensional
+sampler and shared recording harness. Its bar view can inspect all normalized
+channels. It is not a mesh viewer. The typed Python layer performs physical-unit
+decoding and target-profile checking. Existing C#/TypeScript XYZ wrappers remain
+unchanged; this update does not claim new typed mesh renderers in DanceMoves or
+FrameRudiments.
+
+The existing recording bounds apply: at most **8,388,608 scalar values** and
+**64 MiB JSON** per document. Long full-body recordings may require explicit
+excerpts. No channel is discarded to make a file fit. Native sampling can run
+without Blender; evaluating a full Rigify constraint rig requires Blender or a
+separately implemented consumer capable of the same rig semantics.
+
+## Examples, tests and next imports
+
+The [synthetic quickstart](../examples/rig-motion/README.md) produces a capture,
+source beat map and typed motion, then optionally samples it through C++ under a
+variable tempo. It contains no third-party choreography or music.
+
+```sh
+python -m pip install .
+python -m unittest discover -s tests/python -p 'test_motion*.py' -v
+python -m unittest discover -s tests/python -p 'test_rig*.py' -v
+python examples/rig-motion/quickstart.py --output generated/rig-example --native
+```
+
+The dedicated Rigify workflow installs the pinned official `bpy` runtime and
+checks an actual generated armature, native sampling, skin deformation and
+save/reopen persistence. Its synthetic BVH, FBX and GLB importer fixtures also
+verify source timing, fractional capture endpoints and retained skin bindings.
+See [motion-source research](motion-sources.md) for 100STYLE, CMU, Mixamo,
+Rokoko, AIST++, AMASS, LaFAN1, Motorica and animal-motion candidates, with separate
+format/access/licence notes. Dataset-specific SMPL conversion, general automatic
+retargeting, automatic beat inference, contacts and loop/transition repair remain
+future adapters rather than implied capabilities of this first implementation.

package/docs/rigify-catalogue.md

@@ -0,0 +1,246 @@
+# Rigify model types and numbered control channels
+
+DanceRudiments can describe and drive a generated Blender Rigify armature through
+a versioned `dancerudiments.rig-profile`. A mesh bound to that armature deforms
+through Blender's normal Armature modifier. The profile describes animator
+controls; it does not replace skin weights, rig constraints or inverse kinematics.
+
+The checked-in catalogue was extracted by **running Blender 5.2.2 LTS**, build
+`d13f752e3b9c`, and generating its actual built-in rigs. It contains **8 metarig
+presets and 28 component sample profiles**. Every entry has a hierarchical type
+URL, a concrete numbered channel manifest and a SHA-256 fingerprint. The Blender
+build, normalized Rigify Python-source digest and source URL are retained in each
+profile. No third-party character mesh, motion recording or music is bundled.
+
+## Complete metarig presets
+
+| Blender model | Semantic type suffix after `syn://type/danceflow/motion/rigify/metarig/` | Channels |
+| --- | --- | ---: |
+| `human` | `human` | 1,967 |
+| `Basic.basic_human` | `basic/basic_human` | 653 |
+| `Basic.basic_quadruped` | `basic/basic_quadruped` | 799 |
+| `Animals.bird` | `animals/bird` | 1,327 |
+| `Animals.cat` | `animals/cat` | 2,379 |
+| `Animals.horse` | `animals/horse` | 1,286 |
+| `Animals.shark` | `animals/shark` | 579 |
+| `Animals.wolf` | `animals/wolf` | 2,669 |
+
+There are **11,659 channels across these eight preset manifests**. Numbers are
+local to a profile: channel 265 in one model need not be the same parameter as
+channel 265 in another. The profile type and fingerprint accompany the data.
+`synny://` and `syn://` resolve to the same type identity; serialization uses
+`syn://`. They are not two separate registries.
+
+## Component samples
+
+Rigify constructs complete metarigs from reusable component rig types. The
+component profiles use `syn://type/danceflow/motion/rigify/component/` followed
+by the dotted Blender name expressed as a path, for example `limbs/arm`.
+
+| Component | Channels in the generated sample |
+| --- | ---: |
+| `basic.copy_chain` | 40 |
+| `basic.pivot` | 20 |
+| `basic.raw_copy` | 10 |
+| `basic.super_copy` | 20 |
+| `experimental.super_chain` | 70 |
+| `face.basic_tongue` | 41 |
+| `face.skin_eye` | 84 |
+| `face.skin_jaw` | 132 |
+| `faces.super_face` | 892 |
+| `limbs.arm` | 113 |
+| `limbs.front_paw` | 144 |
+| `limbs.leg` | 146 |
+| `limbs.paw` | 144 |
+| `limbs.rear_paw` | 144 |
+| `limbs.simple_tentacle` | 70 |
+| `limbs.spline_tentacle` | 115 |
+| `limbs.super_finger` | 52 |
+| `limbs.super_limb` | 113 |
+| `limbs.super_palm` | 14 |
+| `skin.anchor` | 20 |
+| `skin.basic_chain` | 38 |
+| `skin.glue` | 20, in the explicitly declared containing-rig fixture |
+| `skin.stretchy_chain` | 38 |
+| `skin.transform.basic` | 20 |
+| `spines.basic_spine` | 108 |
+| `spines.basic_tail` | 69 |
+| `spines.super_head` | 44 |
+| `spines.super_spine` | 195 |
+
+These are concrete upstream sample configurations, including their generated
+root and containing controls. Changing chain length, component settings or the
+metarig composition can change the controls; export a profile from the resulting
+rig instead of assuming a sample's channel layout still applies.
+
+`skin.glue` has **no independent animator control**: it connects to a skin control
+created by another component. Its fixture adds a real `skin.anchor` at the glue
+head, successfully generates both components and records their containing rig's
+root/anchor channels. Both the catalogue and profile explicitly mark this context.
+The channels are not represented as new controls created by glue. Similarly,
+the default `basic.raw_copy` sample exposes its generated root while preserving
+its deformation bone internally.
+
+The catalogue also enumerates each component's **generation settings**—chain
+segments, rotation-axis options and similar configuration. Those settings are
+metadata, not animated control channels. They must be applied before generating
+the rig. The runtime profile covers the generated result.
+
+## Numbering and physical meaning
+
+Each channel defines its stable **one-based number**, safe Recording dimension
+name, exact bone name, Blender property path, array component, unit, minimum,
+maximum, neutral value, value type and interpolation policy. Quaternion channels
+retain Blender's **w, x, y, z** ordering. Euler controls retain the actual Euler
+order chosen by Rigify; the bridge does not change a rig's rotation mode.
+Integer selectors also retain their allowed numeric enum choices and labels.
+
+For example, the shipped `Basic.basic_human` profile assigns:
+
+| Channel | Exact control parameter |
+| ---: | --- |
+| 203–205 | `hand_ik.L.location` X, Y, Z |
+| 206–209 | `hand_ik.L.rotation_quaternion` W, X, Y, Z |
+| 210–212 | `hand_ik.L.scale` X, Y, Z |
+| 265–267 | `root.location` X, Y, Z |
+| 268–271 | `root.rotation_quaternion` W, X, Y, Z |
+| 272–274 | `root.scale` X, Y, Z |
+| 617 | `upper_arm_parent.L["IK_FK"]` |
+| 619 | `upper_arm_parent.L["IK_parent"]` |
+| 621 | `upper_arm_parent.L["pole_vector"]` |
+
+These are exact assignments from the checked-in profile, not a generic humanoid
+bone convention. The complete list is machine readable and can be exported to
+CSV with the motion CLI.
+
+Local location is measured in Blender units; the scene's `scale_length` is part
+of the profile. Angles are radians and scales are dimensionless. Controls use
+local pose/basis space relative to the retained bone rest matrices and hierarchy.
+Armature-object animation is not captured as a bone channel; bake locomotion to
+the rig's root control first when it is part of the motion.
+
+The built-in transform ranges are ±10 Blender units for local translation,
+±4π radians for Euler/axis-angle rotation and 0–4 for scale. Quaternion components
+use −1–1. Numeric custom properties use their declared limits; custom enums use
+the actual allowed choices rather than Blender's generic int32 storage range.
+The exporter accepts explicit range overrides. A capture that exceeds its
+profile's bounds fails visibly; it is never silently clipped.
+
+The encoding into the existing normalized Recording contract is:
+
+```text
+encoded = 2 × (physical − minimum) / (maximum − minimum) − 1
+physical = minimum + (encoded + 1) × (maximum − minimum) / 2
+```
+
+The existing float64/twelve-decimal contract remains in force. Quaternion groups
+must form a unit quaternion, and native output is normalized when applied in
+Blender to remove small numerical drift. Boolean/integer/enum channels use step
+sampling and reject invalid intermediate values; float blends remain continuous.
+Euler curves preserve their sampled winding. Correct discontinuous Euler wraps
+in the source action before capture, or use an appropriate quaternion control.
+
+Initial exports enumerate bones deterministically and their writable transforms
+and numeric custom properties in fixed order. Re-export with `--previous` to
+retain every existing channel number and append new bindings. Removed channels,
+changed ranges or changed parameter semantics require an explicit new profile;
+old recordings are not silently reinterpreted. Rest-pose changes also change the
+fingerprint even when names and numbers remain identical.
+
+## Export and capture a real character
+
+The helper lives in the installable package as
+`dancerudiments_authoring.blender_bridge`; `tools/blender_rigify_bridge.py` is its
+checkout entry point. Capture and profile discovery use Blender plus the Python
+authoring package. Native apply/bake additionally require a DanceRudiments
+extension built for the Python ABI used by that Blender installation.
+
+```sh
+blender --background character.blend --python tools/blender_rigify_bridge.py -- export-profile --armature rig --model my_character --output my-character.profile.json
+blender --background character.blend --python tools/blender_rigify_bridge.py -- capture-action --armature rig --profile my-character.profile.json --frame-start 1 --frame-end 241 --output my-character.capture.json
+```
+
+Use `--location-range`, `--rotation-range` and `--scale-max` on `export-profile`
+when the character needs different explicit transform bounds. Use `--previous`
+with a prior profile to preserve numbering when adding controls. A saved profile
+fingerprints the actual rest matrices, modes, source version and unit scale, but
+does not include the current pose or random Rigify instance ID. Applying to a
+different rig fails with a fingerprint mismatch.
+
+Capture accepts fractional `--frame-start`, `--frame-end` and `--frame-step`
+values. It always retains the explicit last endpoint. `--sample-fps` selects an
+explicit sampling rate instead of `--frame-step`, including subframes. Time zero
+is the first captured frame; source frames, FPS and time origin are recorded in
+provenance. Supply musical beat anchors relative to this origin when compiling
+the capture. Captures are bounded by the existing scalar-count and file-size
+limits; select an excerpt when a long, high-channel-count motion exceeds them.
+
+## Import and retarget motion
+
+```sh
+blender --background --factory-startup --python tools/blender_rigify_bridge.py -- import-source dance.bvh --save dance-source.blend
+```
+
+The bridge delegates `.bvh`, `.fbx`, `.gltf` and `.glb` to Blender's own importers.
+BVH import preserves the source FPS in the scene and updates its duration.
+FBX/glTF may have fractional keyframe endpoints; choose explicit capture bounds
+and sampling rates after retargeting. Imports retain their original skeleton
+until an explicit retargeting/baking step maps them to the generated Rigify
+**controls**. Bone-name copying is not sufficient to compensate for rest-pose
+axes, scale, IK, poles or foot contacts. See [motion sources and tools](motion-sources.md).
+
+After retargeting, export the exact destination rig's profile and use
+`capture-action`; the regular motion compiler maps this capture to 64 pips per
+beat. The adapter does not infer musical tempo or foot-contact events.
+
+## Native playback and saved Blender actions
+
+```sh
+blender --background character.blend --python tools/blender_rigify_bridge.py -- apply --armature rig --motion dance.rig-motion.json --pip 64 --save pose-at-beat-one.blend
+blender --background character.blend --python tools/blender_rigify_bridge.py -- bake --armature rig --motion dance.rig-motion.json --target-beat-map song-beats.json --frame-start 1 --save song-matched-character.blend
+```
+
+Both commands sample the existing native C++ recording engine. `apply` writes a
+new one-pose Action, so the requested pose persists after reopening the file.
+`bake` writes a new Action with a key at every recorded pip and explicitly sets
+constant interpolation, retaining the integer-pip playback contract without
+Bezier overshoot. It anchors the recording's first pip at `--frame-start`.
+With `--target-beat-map`, each following pip uses the map's inverse beat-to-time
+conversion; otherwise it uses the recording's nominal tempo.
+
+The saved output uses the new Action at full replacement influence and disables
+previous NLA evaluation, preventing accidental mixing with existing animation.
+Previous Action and NLA data are retained. A failed operation restores the old
+Action and animation settings. Output `.blend` paths must be new files.
+
+The bridge never animates `DEF-`, `MCH-`, `ORG-` or visual helper bones directly.
+It drives animator controls and lets the generated rig evaluate its constraints,
+drivers and skin deformation. Mesh shape keys, arbitrary external feature-set
+semantics and automatic universal retargeting are outside this profile contract.
+For another Blender/Rigify version or a customized metarig, discover the actual
+rig rather than assuming these pinned manifests remain valid.
+
+## Reproduce the manifests and integration check
+
+```sh
+blender --background --factory-startup --python tools/blender_rigify_bridge.py -- catalogue --output-dir python/dancerudiments_authoring/rig_profiles
+PYTHONPATH=python python -m unittest discover -s tests/python -p test_rigs.py -v
+python tools/test_blender_rigify_bridge.py --output-dir .cache/rigify-smoke
+```
+
+The last command runs in a Python environment with `bpy==5.2.2` and the matching
+compiled DanceRudiments extension. It builds an actual Rigify basic human,
+captures synthetic movement, compiles beat samples, drives a weighted test mesh,
+checks fractional capture and selector handling, bakes variable-tempo native
+motion, reopens saved apply/bake outputs in fresh Blender processes to verify
+their control values and skin deformation, and verifies the contextual glue
+sample. It uses no third-party motion.
+
+## Primary references
+
+- [Pinned Blender 5.2.2 Rigify source](https://github.com/blender/blender/tree/v5.2.2/scripts/addons_core/rigify).
+- [Rigify component model and generation stages](https://developer.blender.org/docs/features/animation/rigify/).
+- [Blender Rigify rig types](https://docs.blender.org/manual/en/latest/addons/rigify/rig_types/index.html).
+- [Blender Rigify metarig construction](https://docs.blender.org/manual/en/latest/addons/rigify/metarigs.html).
+- [Blender PoseBone API](https://docs.blender.org/api/current/bpy.types.PoseBone.html).
+- [Official bpy distribution](https://pypi.org/project/bpy/5.2.2/).

package/examples/motion-packages/inspect_package.py

@@ -0,0 +1,21 @@
+"""Inspect one selected package and sample only the chosen clip natively."""
+import argparse
+from pathlib import Path
+import sys
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / 'python'))
+from dancerudiments_authoring import MotionPackage, load_profile
+
+parser = argparse.ArgumentParser(description=__doc__)
+parser.add_argument('package', type=Path)
+parser.add_argument('--clip')
+parser.add_argument('--profile', type=Path, help='Exact profile saved with the target scene')
+args = parser.parse_args()
+profile = load_profile(args.profile) if args.profile else None
+with MotionPackage(args.package, expected_profile=profile) as package:
+    for clip in package.catalogue():
+        print(clip['id'], clip['start_pip'], clip['sample_count'], clip['byte_length'])
+    if args.clip:
+        motion = package.load(args.clip)
+        player = motion.player()
+        print('type:', motion.profile.type_uri)
+        print('first native pose by numbered channel:', player.by_channel(player.start_pip))