Skip to main content

Motion

Motion is a distinct artifact type: animated slides authored as HTML + CSS and rendered to MP4.

It is motion graphics — code, not generated footage. That distinction is the whole point: change one number or retime a scene and the rest is untouched. Compare that with a diffusion video render, where a new take means a new roll and often a different result.

MotionVideo
AuthoringHTML + CSS you can editA prompt
DeterminismFrame-exact, repeatableVaries per roll
RetimingChange a numberRe-render and hope
FootageGraphicsReal or invented footage
RendererLocal Chromium + ffmpegToothFairyAI backend

Use motion when the user will want to tweak the result — explainers, animated charts, kinetic type, brand-first presentations. Use Video when they want invented footage.

The render contract​

A composition declares everything the renderer needs on <html>:

<html lang="en" data-od-duration="6" data-od-fps="30" data-od-aspect="16:9">
AttributeMeaningRange
data-od-durationTotal length in seconds0–120 (120 is the ceiling)
data-od-fpsFrames per second1–120; the UI offers 24 / 30 / 60
data-od-aspectOutput ratio16:9 (1920×1080) · 9:16 (1080×1920) · 1:1 (1080×1080) · 4:3 (1440×1080)

Duration may also be derived from the latest data-od-end on any timeline element, so a composition that forgets the attribute still renders something sane instead of failing.

The seek mechanism​

This is the load-bearing idea. A CSS animation normally runs on wall-clock time, which a frame-capture renderer cannot control. CSS offers exactly one primitive for seeking: a negative animation-delay starts an animation partway through its cycle.

:root { --od-t: 0s; } /* the playhead */

.my-thing {
animation: rise 0.8s var(--od-ease) forwards;
animation-delay: calc(-1 * var(--od-t) + 0.4s); /* playhead + stagger */
animation-play-state: paused;
}

Writing --od-t re-evaluates every delay at once, so a single custom-property write moves every animation on the page to time t.

Verified behaviour: a 2s linear translateX(0→300px) animation screenshotted at --od-t = 0 / 0.5 / 1 / 1.5 lands at x = 8 / 83 / 158 / 233 — exactly linear.

Consequences:

  • Compositions contain zero animation JavaScript.
  • The renderer gets frame-exact, repeatable output.
  • What you scrub in the preview is exactly what the render captures, because they share the same mechanism.

The shim that exposes window.odMotion (ready, duration, fps, seek, play, pause, current) is injected by the renderer and embedded in the preview harness. Agents never write it and never hand-edit it.

Scenes​

A composition is a sequence of scenes with contiguous time windows:

<section class="od-scene" data-od-start="0" data-od-end="2" style="--od-bg:#0b0d10">
...
</section>
<section class="od-scene" data-od-start="2" data-od-end="4" style="--od-bg:#161a20">
...
</section>
RuleDetail
Windows contiguousNo gaps, no overlaps
UnitsSeconds, decimals fine (2.5)
ElementsAdd class="od-anim" and style="--od-in: <seconds>" to stagger in

Media layers​

Video, audio, and full-bleed images are composited by ffmpeg, not the browser. They declare their placement as data attributes so the preview and the render read the same values:

<video data-od-src="clip.mp4"
data-od-start="2.0" data-od-end="6.5"
data-od-rect="0,0,1920,1080"
data-od-fit="cover"
muted></video>
AttributeMeaning
data-od-srcProject-relative media path
data-od-start / data-od-endVisibility window in seconds
data-od-rectx,y,width,height in stage pixels
data-od-fitcover | contain
data-od-volumeOpt a video layer's own audio into the mix

Layout images that are part of a scene may be ordinary <img> elements — they are captured with the DOM and need no attributes.

Two things this prevents:

  • Positioning a media layer with transform alone — the preview would follow it and the export would not.
  • Referencing anything remote — the render must work offline from the project folder.

Layer paths are validated: a layer resolving outside the project directory, or pointing at a missing file, fails the render with a clear message rather than producing a blank frame.

What the agent must not do​

NeverWhy
requestAnimationFrame, setInterval for anything that must appear in the exportWall-clock animation is invisible to a seeking renderer — it renders as one frozen frame
transition for exported motionSame reason
Make the stage responsive / use viewport unitsThe renderer captures at exact stage dimensions
Emit an <artifact> wrapper around the pageThe file is the artifact
Inline the seek shimThe renderer injects it
Load CDN scripts, network fonts, or remote imagesThe render must resolve everything from the project folder
Exceed 120 secondsThe ceiling; split into separate compositions

Rendering​

Requirements​

DependencyPurpose
Chromium (Playwright)Frame capture
ffmpegEncoding + media-layer compositing
ffprobeProbing media layers for audio streams

The daemon reports readiness rather than letting a render fail late:

GET /api/media/motion/models

returns the renderer registry plus a runtime block:

{
"renderers": [{ "id": "motion-html", "label": "Motion (HTML + CSS)", "provider": "local",
"caps": ["html2mp4", "audio-mix", "video-layer"],
"maxDurationSec": 120, "aspects": ["16:9","9:16","1:1","4:3"], "fps": [24,30,60] }],
"runtime": { "chromium": true, "ffmpeg": true, "ready": true }
}

When runtime.ready is false, the message names which dependency is missing. Chromium discovery is cached; packaged builds ship browsers under the app resource root, dev machines use the Playwright cache.

Over MCP​

ToolPurpose
list_motion_modelsRenderer, fps/aspect options, and whether this machine can render
generate_motionSubmit { entry } → { taskId } immediately
wait_motionLong-poll to completion

generate_motion accepts entry, output, fps, aspect, and duration. Defaults come from the composition's own declaration, so a correctly-authored file needs only entry.

Over HTTP​

EndpointMethodDescription
/api/media/motion/modelsGETRenderer registry + runtime readiness
/api/projects/:id/media/motion/generatePOST{ entry, output?, fps?, aspect?, duration? } → 202 { taskId }
/api/media/tasks/:id/waitPOSTLong-poll any media task, motion included

The render preflights the runtime before queueing: a missing browser or ffmpeg is a 503 you can act on, not a task that fails a minute later.

Render pipeline​

composition HTML ──► validate entry + layers
──► launch Chromium at stage dimensions
──► seek --od-t per frame, screenshot
──► ffmpeg: frames → video (+ composite video/audio layers)
──► write <output>.mp4 into the project

A 120s composition at 60fps is 7200 frames, which is why the capture budget is 20 minutes rather than the MCP default 30 seconds.

Viewing​

Motion artifacts get their own viewer in the app:

ControlAction
Compose / RenderedEdit-time preview vs the rendered MP4
Play / pauseDrive the playhead
ScrubSeek continuously
Frame stepOne frame at a time
RenderStart the MP4 render from the viewer

CLI​

There is no tfdesign motion subcommand. Terminal users render through the HTTP route or over MCP; in practice motion is driven by an agent, because the composition has to be authored first.

curl -s -X POST "http://127.0.0.1:7456/api/projects/$OD_PROJECT_ID/media/motion/generate" \
-H 'content-type: application/json' \
-d '{"entry":"explainer.html","fps":30,"aspect":"16:9"}'

See also​

  • Video — diffusion footage, sequences, and the HyperFrames path
  • Audio — narration you can attach as an audio layer
  • Modes — where motion sits among the project surfaces
  • Preview & Comments — the transport UI