overlay-animation

Files (7)

• SKILL.md
• overlay_animation_plan.py · scripts/
• overlay_animation_plan_test.py · scripts/
• overlay_asset_verify.py · scripts/
• overlay_asset_verify_test.py · scripts/
• overlay_preview_evidence.py · scripts/
• overlay_preview_evidence_test.py · scripts/

SKILL.md (first lines)

# Overlay Animation

Use this when the edit needs a generated motion graphic, callout,
animated stat card, visual explainer, lower-third treatment, or other
bespoke overlay asset.

Before generating an overlay asset, call `plan_visual_support` for the
visual need and read its `needs`, `intents`, `primary_lane`,
`supporting_lanes`, and `plan_steps`. If it returns `motion_scene`,
prefer `plan_motion_scene` and its `Set Motion Scene` EDL for native,
previewable/renderable layered motion. MotionScene supports multi-layer
text, rectangle/solid panels, callout rectangles, and project-relative
still image layers, with shared transforms and layer-local animations
for opacity, position, scale, and rotation; keep actual footage in
B-roll/PiP. Pass transcript-backed on-screen content to
`plan_motion_scene`: `headline` or `evidence_text`, plus exact
`step_labels` for step/process scenes. Do not call it with only the
freeform visual request. Use the generated asset workflow below only when the scene
needs custom motion beyond that subset, subject-aware compositing, video
media inside the graphic, or a renderer path that MotionScene does not
yet provide.

## Principle

Generated animation is an asset workflow, not a custom render path. Each
animation slot produces a project file under `generated/overlays/<slug>/`
and then enters the timeline with normal Montage overlay operations.

Prefer existing graph-native titles, captions, transitions, and
broadcast overlays when they solve the job. Use generated overlays only
when the graphic itself needs custom motion or visual design.

## Slot Planning

Create a slots JSON file with:

```json
{
  "slots": [
    {
      "name": "Launch Callout",
      "anchor": "clip_uuid=clip-a",
      "start_s": 2.0,
      "duration_s": 1.8,
      "engine": "canvas",
      "mode": "full_frame",
      "prompt": "Animated product callout synced to the word launch",
      "subject_aware": false,
      "text_layers": [
        {
          "text": "LAUNCH",
          "font_family": "Inter",
          "font_size": 120,
          "font_color": "#FFFFFF",
          "opacity": 1.0,
          "rotation": 0,
          "x": 0.5,
          "y": 0.42,
          "weight": "black"
        }
      ]
    }
  ]
}
```

Then generate a manifest:

```bash
python3 <skill-root>/scripts/overlay_animation_plan.py \
  --slots-json overlay-slots.json \
  --output-root generated/overlays
```

For each returned slot:

- Write or generate the asset at `asset_path`.
- Use the generated `brief` as the exact production contract.
- Insert the asset with the provided `edl_hint`, adjusting anchor,
  corner, scale, or margin only if the timeline needs it.
- Render and verify the slot in context.

Before insertion, verify generated assets:

```bash
python3 <skill-root>/scripts/overlay_asset_verify.py \
  --manifest overlay-manifest.json \
  --project-root .
```

The verifier must return `status: "ready"`. A `blocked` report means
the generated overlay, duration contract, project-relative paths, or
subject matte/cutout artifacts are not ready for timeline insertion.

For text-behind-subject preview evidence, generate a deterministic
before/after preview scorecard:

```bash
python3 <skill-root>/scripts/overlay_preview_evidence.py \
  --manifest overlay-manifest.json \
  --fixture-json overlay-preview-fixture.json \
  --output-root generated/previews \
  --project-root .
```

The fixture supplies frame dimensions and the subject bounds for each
subject-aware slot. The report writes an ordinary overlay preview, a
subject-safe preview, and a scorecard. Treat the scorecard as ready only
when ordinary overlay pixels intersect the subject and the subject-safe
preview has zero overlay pixels inside the subject bounds.

The same evidence helper can validate background treatment slots when a
slot includes `background_treatment`. Supported deterministic evidence
modes are `color` and `transparent`; heavier blur, image, or video
replacement belongs in a renderer or sidecar artifact with separate
render evidence.

For text-behind-subject or subject-aware overlay work, set
`subject_aware: true`, provide `subject_prompt`, and provide or generate

From explicit09/montage, Apache-2.0.

More from explicit09/montage