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.
| Motion | Video | |
|---|---|---|
| Authoring | HTML + CSS you can edit | A prompt |
| Determinism | Frame-exact, repeatable | Varies per roll |
| Retiming | Change a number | Re-render and hope |
| Footage | Graphics | Real or invented footage |
| Renderer | Local Chromium + ffmpeg | ToothFairyAI 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">
| Attribute | Meaning | Range |
|---|---|---|
data-od-duration | Total length in seconds | 0–120 (120 is the ceiling) |
data-od-fps | Frames per second | 1–120; the UI offers 24 / 30 / 60 |
data-od-aspect | Output ratio | 16: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>
| Rule | Detail |
|---|---|
| Windows contiguous | No gaps, no overlaps |
| Units | Seconds, decimals fine (2.5) |
| Elements | Add 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>
| Attribute | Meaning |
|---|---|
data-od-src | Project-relative media path |
data-od-start / data-od-end | Visibility window in seconds |
data-od-rect | x,y,width,height in stage pixels |
data-od-fit | cover | contain |
data-od-volume | Opt 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
transformalone — 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
| Never | Why |
|---|---|
requestAnimationFrame, setInterval for anything that must appear in the export | Wall-clock animation is invisible to a seeking renderer — it renders as one frozen frame |
transition for exported motion | Same reason |
| Make the stage responsive / use viewport units | The renderer captures at exact stage dimensions |
Emit an <artifact> wrapper around the page | The file is the artifact |
| Inline the seek shim | The renderer injects it |
| Load CDN scripts, network fonts, or remote images | The render must resolve everything from the project folder |
| Exceed 120 seconds | The ceiling; split into separate compositions |
Rendering
Requirements
| Dependency | Purpose |
|---|---|
| Chromium (Playwright) | Frame capture |
| ffmpeg | Encoding + media-layer compositing |
| ffprobe | Probing 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
| Tool | Purpose |
|---|---|
list_motion_models | Renderer, fps/aspect options, and whether this machine can render |
generate_motion | Submit { entry } → { taskId } immediately |
wait_motion | Long-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
| Endpoint | Method | Description |
|---|---|---|
/api/media/motion/models | GET | Renderer registry + runtime readiness |
/api/projects/:id/media/motion/generate | POST | { entry, output?, fps?, aspect?, duration? } → 202 { taskId } |
/api/media/tasks/:id/wait | POST | Long-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:
| Control | Action |
|---|---|
| Compose / Rendered | Edit-time preview vs the rendered MP4 |
| Play / pause | Drive the playhead |
| Scrub | Seek continuously |
| Frame step | One frame at a time |
| Render | Start 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