Animated Video

---
name: animated-video
description: Use when creating animated product launch videos, GSAP timelines, or visual motion assets
---

# Animated video

Create an animated video or motion design piece rendered as an HTML page. Build a timeline-based animation with smooth transitions. Design frame-by-frame sequences with playback controls (play/pause, scrubber). Focus on visual storytelling with the Anthropic brand palette. Export-ready at a fixed aspect ratio (16:9 or 9:16). If you need to know the position of an element (eg to move a cursor or character between elements) use refs to grab the position.

For any standalone animation (one that isn't embedded inside another design or page), ALWAYS build on the `animations_v2.jsx` starter — only skip it if the user explicitly asks you not to. Do NOT load `animations.jsx` alongside it: v2 contains the whole engine (same globals — importing both means last-wins).

START by calling `copy_starter_component` with `kind: "animations_v2.jsx"` — it gives you the full timeline engine (`<Stage>`, `<Sprite start end>`, `useTime()` / `useSprite()` hooks, an `Easing` library, `interpolate()` / `animate()` tweens, `TextSprite` / `ImageSprite` / `RectSprite` primitives) PLUS scene sequencing: `<SceneStage>` plays named scenes in authored order and keeps the exportable duration in sync. Read the file after copying.

ALWAYS structure the piece as a scene sequence — even a single-scene piece is a one-entry scene list. Follow the authoring contract exactly (it's in the file's usage block): declare the scene list as a JSON string literal in a plain inline `<script>` of the MAIN document — `<script>window.OM_SCENES = '[{"name":"Opening","dur":3},…]';</script>` (exact JSON.stringify formatting, no spaces) — NOT in a text/babel script and NOT in a sibling .jsx (only vanilla inline script literals are addressable for the editor's write-back); pass it through untouched as `<SceneStage scenes={window.OM_SCENES}>`, and map scene names to components in the children object. The user can then edit timing by hand on the host timeline: trim one scene at its right edge, reorder blocks — every edit writes back into your literal and reflows live. (The time ruler itself is a seek surface — click or drag to scrub — not an editing handle.)

TIMING IS USER-EDITABLE (time-stretch): when the user changes a scene's length, the engine remaps the scene clock so your full choreography plays faster or slower — never cut off. That only works for motion driven by the scene clock, so inside a scene component ALWAYS animate from useScene()'s `localTime`/`progress` (never your own clock, never useTime directly inside a scene). Scene entries can carry extra fields (`"text"`, palettes, any params) — your scene components receive the whole entry, so user-visible knobs belong in that JSON too.

Give every motion project a tweaks panel (`kind: "tweaks_panel.jsx"`) whose TWEAK_DEFAULTS include `"motionEditor": true` with a `<TweakToggle label="Motion editor">` wired to it. That key is the host timeline editor's visibility gate: the user flips it in the Tweaks panel to hide or show the editor bar, and the animation, its timing data, and export are untouched either way. Declare the TWEAK_DEFAULTS literal in a plain inline `<script>` of the MAIN document (the /*EDITMODE-BEGIN*/ convention), so the flip persists.

Stage renders inside <svg><foreignObject>; if a screenshot of it comes back black, that's a capture artifact — trust the live preview.

Animations are complex code! Make reusable JSX components for each visual element and each scene. Invest in tweaking the timeline iteratively.

Animation tips:
- Storytelling is KEY! Before you create ANYTHING, identify the story arc, key tensions, characters, etc. Align on the message you want to convey. Run it by the user.
- Use good animation principles... anticipation, easing, follow-through, exaggeration, all the Disney animator principles.
- Scenes should have establishing shots setting the scene (use titles or captions if NECESSARY, but prefer to show not tell), followed by heavy zooms on the action. (either hard cuts, or ken-burns-style zooms, or mouse-follows.) Most scenes should exist in a realistic context: they should have a background, or exist in the UI of a computer or phone; etc. Elements should generally not float in the aether.
- In short animations, most 'scenes' are a single shot, or a sequence of shots in the same setting. Scenes may be slides (e.g. text or graphics onscreen, animating or being emphasized (highlighted etc) in an engaging way that calls attention to the key thing). Decide what the shot is going to be. Maybe it's starting zoomed out, then slowly zooming in on the area of focus or action. Maybe it's rapidly cutting back/forth between two people or graphics in tension. Maybe you're following something, like a cursor or a line on a graph, as it flits around. Be creative!
- Except for deliberate dramatic effect (a held beat), SOMETHING should always be in motion. The camera, an element, or a transition — slowly panning, zooming, subtly scaling up, drifting, or building. A truly static frame reads as a bug. Images especially: always slowly zoom in/out, pan, have some 'action', have text or graphics appearing or building, or be rapidly cutting in sequence.
- Whenever you show text or images, remember that you need pauses for it to sink in -- on the order of seconds -- before you can show something else.

If cursor or pointer movement is depicted (eg in a product walkthrough or prototype), you should zoom in on it and follow it with a damped viewport animation, like Screen Studio would. You MUST use HTML refs to locate elements onscreen so the cursor points at the right things.

For clarity when commenting, update the video root's data-screen-label attr with the current timestamp each second, so you can easily comment on a particular timestamp and know that the agent will be told exactly the timestamp.

To make content the user can export as a video (Share → Export → Video):

IF YOU ARE BUILDING ON THE `animations_v2.jsx` STARTER (the normal case): `<SceneStage>` ALREADY SATISFIES THIS ENTIRE CONTRACT — it owns the exportable attribute, the seek listener, the svg/foreignObject wrapper, and font inlining, and it provides a `<VideoSprite>` helper for looped <video> clips. Do NOT add `data-om-exportable-video-with-duration-secs` to any element yourself. Adding it to a wrapper ABOVE the stage creates two nested exportable roots, and the export and timeline transport bind to the wrong (outer) one — playback control and export silently break.

Only for a page built WITHOUT the starter, implement the contract yourself:

- Put `data-om-exportable-video-with-duration-secs="<N>"` on the ONE root element you want exported (N ≤ 300; longer is clamped). Exactly one element in the document may carry this attribute — never nest it.
- That element MUST listen for the custom event `data-om-seek-to-time-frame` (`detail: {time, frame}`): on receipt, pause playback and synchronously render that exact timestamp so every visible child is at that point.
- Nested `<video>` elements that should contribute audio must carry `data-om-exportable-video-play-start`, `data-om-exportable-video-play-end` (seconds into the source), and optionally `data-om-exportable-video-play-speed`; they loop within [start,end] at that speed and their audio is mixed into the export. Keep their visual frame in sync with the timeline yourself (set `video.currentTime` from the seek event / your clock).
- For best results, make the root an `<svg><foreignObject>` wrapper and inline your @font-face rules into it once — the exporter then serializes the svg directly per frame (fast, pixel-perfect). A plain div works too, just slower (full-page snapshot per frame).

A page carrying this contract also gets a live timeline under the preview — the host scrubs and plays it by dispatching the same seek event, so treat every seek as pause-and-hold (don't resume your own clock until seeks stop arriving).