handler/STORYTELLING.md

# Staging product storytelling experiment

Production stays on its existing Git and Hugging Face revisions. Changes reach
handler mode selection, its strict request contract, model-cache provenance,
selftest, staging endpoint revision and contract tests. No Django caller changes.

`motion` and `union` use the pinned native ICLoraPipeline, one full-resolution
stage, eight distilled steps and the respective official ref0.5 LoRA. Reference
scale comes from the adapter metadata. They accept `video_url` containing a
prepared sparse-motion or depth/canny/pose guide, plus optional `image_url` or
`images` identity anchors. `conditioning_strength` defaults to 1, range [0,1].
Guide frame count and FPS must equal the requested output; aspect ratio must be
preserved. A normal RGB clip is not a motion-track or union guide. Guidance,
negative prompts and arbitrary step counts are refused rather than ignored.

A storyboard is orchestration: approve product references for each shot, render
short continuous shots, then assemble explicit cuts and a continuous soundtrack.
Multi-keyframe conditioning is already supported by `i2v` / `keyframe`; it does
not automatically create or validate a storyboard. Never ask the model to
complete hidden product lettering. Judge source markings, both shoe count and
silhouette across the actual output, including cut boundaries.

Refine Details already exists as `refine` and uses tiled native diffusion with
50 percent tile overlap. Native blending differs from the official ComfyUI
recipe; GPU comparisons must precede enabling it for customers. A 4K output
size is not evidence that low-resolution source lettering became accurate.

Official references:
- https://docs.ltx.io/open-source-model/feature-guides/structural-control/motion-control
- https://docs.ltx.io/open-source-model/feature-guides/structural-control/union-control
- https://ltx.io/blog/how-to-storyboard
- https://huggingface.co/Lightricks/LTX-2.5-22b-IC-LoRA-Refine-Details

Checks: `LTX_SOURCE=/path/to/pinned/LTX-2 python3 -m unittest discover -s tests`.
Real render receipts and quality conclusions belong in the application research
report; callable controls alone are not evidence of improved product fidelity.