docs/generation-settings.md

# Generation settings

The two settings that most affect motion quality are **denoising steps** and
**clip duration** (plus playback speed). Both were measured on this Space with
controlled, same-seed experiments (June 2026).

## Denoising steps — the dominant quality lever

Kimodo samples with DDIM; **its own default is 100 steps.** This Space's UI
previously defaulted to **20** (fast but mushy) and **now defaults to 60**.

Same seed, "A person throws a sharp straight punch forward with the right fist.":

| Steps | Right-hand peak speed | Feel |
|---|---|---|
| 20 | 1.28 m/s | soft, the foot shuffles instead of a planted strike |
| 60 | **3.86 m/s** | planted, committed punch |
| 100 | **5.05 m/s** | sharp |

Raising 20 → 100 made the punch **~4× snappier** with no jitter penalty; kicks
also lifted higher (foot lift +0.33 m → +0.51 m).

**Recommendation:** use **60** for general use (this Space's default), **80–100**
when you want maximum crispness on strikes. The cost is generation time
(~linear in steps) — still seconds on the a10g GPU.

## Clip duration vs. playback speed

**Don't generate ultra-short (~1 s) clips to get fast motion.** Sub-1.5 s clips
truncate kicks. Same seed, steps = 60:

| Clip | Kick: foot lift | Kick: speed at the END of the clip | Jitter |
|---|---|---|---|
| 1.0 s (30 f) | +0.34 m | **7.0 m/s (foot still flying — cut off mid-air)** | worst |
| 1.5 s (45 f) | +0.39 m | 0.12 m/s (lands & settles) | much lower |
| 2.2 s (66 f) | +0.48 m | 0.04 m/s (settled) | lowest |

At 1.0 s the kick's peak happens ~66% through the clip with **no time to land** —
the clip ends mid-kick, and the *next* chained move then starts from a foot-in-
the-air pose. Punches survive 1 s (they extend fully) but get ~3.5× jitterier.

**~1.5 s is the floor** for a complete, settled strike.

### To make a kata feel fast: play it back faster

Generate at **~1.5–2.5 s** (so the motion completes), then **watch at 1.5×**.
This Space's viewer **defaults playback to 1.5×** — a 1.5 s clip then feels ~1 s,
but the foot still lands and the motion is far cleaner than a native 1 s clip.

> Rule of thumb: control *speed* with the **playback rate**, control *completion*
> with the **generation duration**. Don't conflate them.

Sizing within the 1.5–5 s band: a single snap (jab, wave) ~1.5–2 s; a kick
~2–2.5 s; a step-through technique or short 2–3 beat phrase ~3–5 s. Hard cap is
**10 s / 300 frames** (the model's training limit).

## Guidance (CFG)

Kimodo uses decomposed classifier-free guidance, default **`w_text = 2`,
`w_constr = 2`**. Raise the text weight if a motion ignores the prompt; the
general text-to-motion sweet spot is ~2.5–3.0 (higher = more adherence, less
diversity). (Not currently exposed in this Space's UI — generations use the
model default.)

## Seed

Generation is **diverse** — the same prompt + settings yields different plausible
takes per seed. The UI "Regenerate" uses a fresh random seed each time; keep
generating to find a take you like. (Identical prompt + duration + steps + seed is
cached and returns the same clip.)

## Defaults on this Space (current)

| Setting | Value | Why |
|---|---|---|
| Denoising steps | **60** | crisp strikes without excess time (see above) |
| Playback speed | **1.5×** | fast feel without truncating the generated motion |
| Post-processing | **off** | the `motion_correction` package isn't installed; the frame-0 continuation pin is enforced by the constraint regardless |
| Model | `kimodo-smplx-rp` (SMPL-X 22-joint, 30 fps) | matches the citizen/clothing retargeter |

## Sources

- Kimodo tech report (100 DDIM default, CFG, 10 s / 300 f cap) — https://research.nvidia.com/labs/sil/projects/kimodo/assets/kimodo_tech_report.pdf
- MDM guidance scale ~2.5 — https://ar5iv.labs.arxiv.org/html/2209.14916
- All measured numbers (steps, duration, jitter, foot lift/speed) are from our own same-seed experiments on this Space (June 2026).