# Motion Desk

> Convert one animation between five runtimes and see what does not survive. The same
> animation is not the same animation in two of them: the iteration count is off by one,
> the unit differs by a factor of a thousand, the end state depends on a default that
> snaps back, and the easing does not map. Free browser-side converter, five paid lanes.

Live at https://motion-desk.skillsafe.ai/ · API at https://motion-desk.skillsafe.ai/api.html

Derived from five runtime-adapter skills in `heygen-com/hyperframes`
(https://github.com/heygen-com/hyperframes): `waapi`, `css-animations`, `animejs`,
`lottie` and `gsap`. Not affiliated with or endorsed by HeyGen.

## The one thing to know

**The iteration count is off by one.** WAAPI, CSS and Lottie count PLAYS; GSAP's
`repeat` and anime.js's `loop` count ADDITIONAL cycles. Three plays is `iterations: 3`
in one and `repeat: 2` in the other, and copying the 3 across gives 4 plays and
+300 ms at 300 ms a play - always exactly one cycle, always the same direction.

**The unit is not the same unit.** CSS, WAAPI and anime.js are milliseconds; GSAP is
SECONDS; Lottie is FRAMES. And a Lottie duration is QUANTISED: 250 ms is 7.5 frames at 30 fps,
so it becomes 8 frames and plays for 266.7 ms, +16.7 ms. 200 ms is 6 frames exactly and survives.

**The end state differs, and the default is the one that snaps back.** WAAPI's `fill`
and CSS's `animation-fill-mode` both default to `none`, so the element reverts the
instant the animation finishes; GSAP and anime.js leave the value applied; Lottie holds
its last frame.

**And the easing does not map.** An easing curve is a FUNCTION, so the nearest
equivalent has a measurable error, sampled at 101 points:

```text
ease-out     -> GSAP   sine.out   2.4% of the travel, 9.6 px over 400px
power2.out   -> CSS    cubic-bezier(0.33, 1, 0.68, 1)   0.3%
bounce.out   -> CSS    cubic-bezier(0.33, 1, 0.68, 1)   24.4%
elastic.out  -> CSS    cubic-bezier(0.16, 1, 0.3, 1)   79%  —  not a substitution
steps(4)     -> Lottie ease-in   23.3%  —  a staircase is not a curve
spring       -> CSS    cubic-bezier(0.34, 1.56, 0.64, 1)   19.9%  —  and it is not a duration either
```

## What each runtime spells

| Runtime | Duration in | Iteration field | It counts | `fill` default | Ends holding? | Curves it spells |
| --- | --- | --- | --- | --- | --- | --- |
| Web Animations API | **ms** | `iterations` | **plays** | `none` | **no** | cubic-bezier, steps() |
| CSS animation | **ms** | `animation-iteration-count` | **plays** | `none` | **no** | cubic-bezier, steps() |
| GSAP | **s** | `repeat` | **extra cycles** | `forwards` | **yes** | steps(), power, sine, expo, circ, back, elastic, bounce, none |
| anime.js | **ms** | `loop` | **extra cycles** | `forwards` | **yes** | cubic-bezier, steps(), spring(), power, sine, expo, circ, back, elastic, bounce, none |
| Lottie | **frames** | `loop` | **plays** | `forwards` | **yes** | cubic-bezier |

Read the third and fourth columns together: **`iterations` counts PLAYS and `repeat`/`loop` count EXTRA cycles**, so the same intent is a different number. Read the fifth and sixth together: **two of the five default to reverting**, so an animation that is supposed to leave something moved needs a fill written down. And the second column is why no duration number ports as written.

## The off-by-one

| Plays wanted | `iterations` (WAAPI, CSS, Lottie) | `repeat`/`loop` (GSAP, anime.js) | Correct total | Copying the number gives | Out by |
| --- | --- | --- | --- | --- | --- |
| 1 | `1` | **`0`** | 300 ms | 2 plays = 600 ms | **+300 ms** |
| 2 | `2` | **`1`** | 600 ms | 3 plays = 900 ms | **+300 ms** |
| 3 | `3` | **`2`** | 900 ms | 4 plays = 1200 ms | **+300 ms** |
| 5 | `5` | **`4`** | 1500 ms | 6 plays = 1800 ms | **+300 ms** |
| 10 | `10` | **`9`** | 3000 ms | 11 plays = 3300 ms | **+300 ms** |

At 300 ms a play. The error is **always exactly one cycle** and always in the same direction, whatever the count - which is why it survives review: nothing about it looks like an off-by-one. `repeat: 0` is one play and `repeat: -1` is forever, so the field has no way to say "none".

## The frame grid

| Duration | In frames | Lottie plays | Which is | Out by | On the grid? |
| --- | --- | --- | --- | --- | --- |
| 120 ms | 3.6 frames | 4 frames | 133.3 ms | **+13.3 ms** | no |
| 150 ms | 4.5 frames | 5 frames | 166.7 ms | **+16.7 ms** | no |
| 200 ms | 6 frames | 6 frames | 200 ms | — | **yes** |
| 250 ms | 7.5 frames | 8 frames | 266.7 ms | **+16.7 ms** | no |
| 300 ms | 9 frames | 9 frames | 300 ms | — | **yes** |
| 400 ms | 12 frames | 12 frames | 400 ms | — | **yes** |
| 500 ms | 15 frames | 15 frames | 500 ms | — | **yes** |
| 1000 ms | 30 frames | 30 frames | 1000 ms | — | **yes** |

At 30 fps, where one frame is 33.3 ms. A Lottie duration is a whole number of frames, so anything that is not a multiple of a frame is rounded and **the rounded value is what plays**. Raising the rate shrinks the error and never removes it, so the fix is to choose durations on the grid: at 30 that means multiples of 33.3 ms.

## The curve cost

| Curve | waapi | css | gsap | animejs | lottie |
| --- | --- | --- | --- | --- | --- |
| `ease-out` | exact | exact | 2.4% / 9.6 px | exact | exact |
| `power2.out` | 0.3% / 1.1 px | 0.3% / 1.1 px | exact | exact | 0.3% / 1.1 px |
| `expo.out` | 1.2% / 4.8 px | 1.2% / 4.8 px | exact | exact | 1.2% / 4.8 px |
| `back.out` | 0.5% / 2 px | 0.5% / 2 px | exact | exact | 0.5% / 2 px |
| `elastic.out` | **79% / 316.1 px** | **79% / 316.1 px** | exact | exact | **79% / 316.1 px** |
| `bounce.out` | **24.4% / 97.8 px** | **24.4% / 97.8 px** | exact | exact | **24.4% / 97.8 px** |
| `steps(4)` | exact | exact | exact | exact | **23.3% / 93.2 px** |
| `spring(1, 100, 10, 0)` | **19.9% / 79.6 px** | **19.9% / 79.6 px** | **19.9% / 79.7 px** | exact | **19.9% / 79.6 px** |

Percent of the travel at the worst moment, and what that is over 400px. **Bold is past 8%**, which is not a substitution - it is a different movement. `elastic` oscillates and `bounce` is four parabolas; a cubic-bezier has one hump, so neither has a CSS equivalent at any price. `steps()` has no gradient at all, so Lottie has to be authored with held keyframes instead - a different edit rather than a different number.

## Constants and thresholds

| Constant | Value | What it decides |
| --- | --- | --- |
| `SAMPLES` | 101 | the grid every curve deviation is measured on |
| `DEVIATION` | 2% | a curve substitution worth naming |
| `BIG_DEVIATION` | 8% | one that is not a substitution at all |
| `QUANTISE_MS` | 4 ms | a frame-grid rounding worth naming |
| `PIXELS` | 8 px | a curve deviation worth naming, in pixels |
| `LONG_MS` | 1000 ms | an animation worth calling long |
| `DEFAULT_DURATION_MS` | 300 ms | assumed when a duration cannot be read |
| `DEFAULT_EASE` | `ease` | assumed when none is declared — CSS's own default, and not GSAP's |
| `DEFAULT_FPS` | 30 | assumed for the Lottie target |
| `DEFAULT_DISTANCE_PX` | 400px | assumed when turning a curve deviation into pixels |
| `DEFAULT_DECLARED_IN` | `waapi` | assumed when the sheet does not say which runtime it is written in |

Only the units, the iteration semantics and the fill defaults are the runtimes'; everything else is this page's threshold for when a difference is worth saying. The deviation figures are measurements and not preferences.

## Sheet grammar

A sheet is a header of `KEY: value` lines and an `ANIMATIONS:` block.

```text
JOB: what this is                 (optional, echoed back)
DECLARED IN: waapi                (which runtime the numbers are written in;
                                   one of waapi, css, gsap, animejs, lottie; assumed `waapi`)
FPS: 30                           (for the Lottie target; assumed 30)
DISTANCE: 400                     (px, for turning a curve deviation into pixels)

ANIMATIONS:
  <name>  dur=<time> ease=<easing> iterations=<n>|repeat=<n>|loop=<n>
          delay=<time> fill=none|forwards|backwards|both
          alternate  on=<target>  props=<comma list>
```

**A time is `300ms`, `1.2s`, `9f` for frames, or a bare number — which is read as
MILLISECONDS**, because three of the four unit-bearing runtimes are.

**THE ITERATION FIELD NAME DECIDES WHAT THE NUMBER MEANS.** `iterations=3` is three
plays; `repeat=3` and `loop=3` are four. Write the field you mean and the answer will
say which it read. `infinite`, `forever` and `-1` all mean forever.

An easing may be a CSS keyword (`ease`, `ease-in`, `ease-out`, `ease-in-out`),
`cubic-bezier(x1,y1,x2,y2)`, `steps(n)` or `steps(n, start|end)`, GSAP's
`family.direction` (`power2.out`, `sine.inOut`, `elastic.out`, …), anime.js's
`easeOutQuad` spelling, or `spring(mass, stiffness, damping, velocity)`. A bare family
name is read as `.out`, which is what almost everybody means, and the answer says so.

Anything the reader cannot place is listed as a problem rather than skipped. A sheet
whose animation lines were quietly swallowed would read as an empty sheet, and every
figure on the page would be a confident answer about nothing.

## Lanes

| Lane | What it produces |
| --- | --- |
| `plan` | Turn a motion brief into a portable animation sheet |
| `port` (primary) | What this animation becomes in each runtime, and what does not survive |
| `time` | The timing question: units, iteration counts and the frame grid |
| `curve` | The easing question: what the nearest curve costs |
| `deliver` | Decide what changes: the number, the fill, or the runtime |

## A worked sheet

```text
JOB: card reveal, authored in WAAPI and needed in Lottie and GSAP
DECLARED IN: waapi
FPS: 30
DISTANCE: 400

ANIMATIONS:
  card    dur=300ms  ease=ease-out                     iterations=1  props=opacity,transform
  chips   dur=250ms  ease=cubic-bezier(0.2,0.8,0.2,1)  iterations=3  delay=100ms  props=transform
  label   dur=180ms  ease=power2.out                   iterations=1  props=opacity
  glow    dur=600ms  ease=sine.inOut                   iterations=2  alternate  props=opacity
```

| Animation | Declared | waapi | css | gsap | animejs | lottie |
| --- | --- | --- | --- | --- | --- | --- |
| `card` | 300 ms `ease-out` x1 | 300ms `iterations: 1` **reverts** | 300ms `count: 1` **reverts** | 0.3s `repeat: 0` 2.4% | 300ms `loop: 0` | 9 frames `loop: 1` |
| `chips` | 250 ms `cubic-bezier(0.2,0.8,0.2,1)` x3 | 250ms `iterations: 3` **reverts** | 250ms `count: 3` **reverts** | 0.25s `repeat: 2` 2.4% | 250ms `loop: 2` | 8 frames `loop: 3` **+16.7 ms** |
| `label` | 180 ms `power2.out` x1 | 180ms `iterations: 1` 0.3% **reverts** | 180ms `count: 1` 0.3% **reverts** | 0.18s `repeat: 0` | 180ms `loop: 0` | 5 frames `loop: 1` 0.3% **-13.3 ms** |
| `glow` | 600 ms `sine.inOut` x2 | 600ms `iterations: 2` 1.9% **reverts** | 600ms `count: 2` 1.9% **reverts** | 0.6s `repeat: 1` | 600ms `loop: 1` | 18 frames `loop: 2` 1.9% |

The sheet in the worked example. 4 animations declared in waapi, across 5 runtimes, 4 with an iteration count that is off by one, 2 quantised by the frame grid, 4 that end in a different state, 2 with a visible curve substitution, worst duration spread 50 ms. Each cell is the duration in that runtime's unit, the iteration field it needs, what the curve substitution costs where there is one, whether it reverts, and what the frame grid did. Bold is a figure past a threshold.

## Findings

| Finding | Severity | Why it matters |
| --- | --- | --- |
| `NOTHING-TO-CONVERT` | error | The sheet declares no animation |
| `THE-EASING-CANNOT-BE-EXPRESSED-AT-ALL` | error | A runtime has nothing of the right shape |
| `THE-ITERATION-COUNT-IS-OFF-BY-ONE` | note | Copying the iteration number across adds a whole cycle |
| `COPYING-THE-DURATION-ACROSS-IS-WRONG-BY-A-FACTOR` | note | The bare number in another runtime is wrong by a thousand |
| `THE-ITERATION-FIELD-IS-NOT-THE-DECLARED-RUNTIMES` | warning | The sheet spells an iteration field the declared runtime does not have |
| `THE-EASING-HAS-NO-USABLE-EQUIVALENT` | warning | The nearest curve is not a substitution |
| `THE-UNIT-IS-NOT-THE-SAME-UNIT` | note | The duration has to be converted, not copied |
| `THE-FRAME-GRID-CHANGES-THE-DURATION` | warning | Lottie quantises the duration and it cannot be undone |
| `THE-END-STATE-DISAGREES-BETWEEN-RUNTIMES` | warning | The same animation ends in a different state |
| `A-FILL-IS-NEEDED-AND-NOT-DECLARED` | warning | A runtime will revert unless a fill is declared |
| `THE-EASING-SUBSTITUTION-IS-VISIBLE` | warning | The nearest curve a runtime has is visibly different |
| `AN-OVERSHOOTING-CURVE-LEAVES-THE-UNIT-SQUARE` | warning | The curve goes past its destination and comes back |
| `A-DURATION-WAS-NOT-READABLE` | warning | A duration could not be read |
| `AN-EASING-WAS-NOT-DECLARED` | note | An animation declares no easing |
| `AN-EASING-WAS-NOT-READABLE` | warning | An easing could not be read |
| `THE-SHEET-HAS-LINES-THIS-PAGE-COULD-NOT-READ` | warning | Some lines were not readable |
| `AN-INFINITE-ANIMATION-HAS-NO-TOTAL` | note | An animation that repeats forever has no duration to convert |
| `THE-EASING-PORTS-EXACTLY` | note | A runtime has this exact curve |
| `THE-EASING-SUBSTITUTION-IS-CLOSE-ENOUGH` | note | The nearest curve is within a couple of percent |
| `THE-TOTAL-DURATION-AGREES-EVERYWHERE` | note | Every runtime plays it for the same length of time |
| `THE-TOTAL-DURATION-DISAGREES` | note | The runtimes do not play it for the same length of time |
| `AN-ITERATION-FIELD-WAS-SPELLED` | note | The sheet says which iteration field it used |
| `A-DELAY-IS-ADDED-TO-EVERY-TOTAL` | note | The delay is part of the total in every runtime |
| `ALTERNATE-DOES-NOT-CHANGE-THE-DURATION` | note | Alternating changes the direction and not the length |
| `STEPS-IS-NOT-A-CURVE` | note | A stepped easing is a staircase, not a curve |
| `A-SPRING-IS-NOT-A-DURATION` | note | A spring's length comes from its physics |
| `THE-DECLARED-RUNTIME-IS-THE-BASELINE` | note | Everything is measured against the runtime it was declared in |
| `A-LONG-ANIMATION` | note | An animation runs for a long time |
| `THE-PROPERTIES-ARE-DECLARED` | note | The sheet says which properties animate |
| `AN-EASING-DIRECTION-WAS-ASSUMED` | note | A bare family name was read as `.out` |

30 findings: 2 errors, 10 warnings, 18 notes. Nothing that fires on every usable sheet is a warning: the units always differ and the off-by-one is always available, so those are notes.

## What this page cannot do

This page reads a description of an animation, not your code. It never runs an
animation, touches the DOM or renders anything, so:

- **It converts timing and easing, and nothing else.** What is animated, from what to
  what, in what units of what property — none of that changes the conversion, so none
  of it is modelled. `props=` is carried through so a conflict is visible; it is not read.
- **The five runtimes are the ones the source skills cover.** Framer Motion, Motion One,
  Rive and the rest have their own semantics and are not here; where a sheet names one,
  it says so rather than guessing.
- **The curve substitutions come from a LIBRARY, not an optimiser.** The candidates are
  the cubic-beziers people actually write plus each runtime's own named families, so a
  substitution offered here is one somebody could paste. A four-dimensional fit would
  be closer and would not be a curve anybody recognises.
- **A deviation is measured on the value, not on how it looks.** 8% of the travel is
  the threshold for "not a substitution" because it is where the shape changes, not
  because a study says so. On a 20px move, a big percentage is a small number of pixels;
  the pixel column is there for exactly that reason.
- **`stagger`, keyframe offsets and per-keyframe easings are outside it.** An animation
  here is one duration, one curve and one iteration count. A multi-keyframe animation
  has one curve per segment, and each segment is its own row.
- **Nothing here says whether the animation is any good.** It says whether the animation
  you described is the animation each runtime will play.

## API

`POST https://api.skillsafe.ai/v1/app-api/run` with an app session token. The body
IS the input object — never wrapped in an `input` key. Fields: `task` (one of `plan`, `port`, `time`, `curve`, `deliver`), `rules`, `prescan`, plus the lane's own fields.

`POST .../estimate` with the same body returns `hold_credits` and costs nothing.

## Provenance

Every table and every figure above is generated from `motion.js` by `build-skill.js`.
Nothing is typed twice, so nothing can drift.