Skip to content

Commit 6e8b6eb

Browse files
miguel-heygenmiguel-heygen
committed
feat(studio): keyframe integration wiring + docs
Wire App.tsx recording orchestration, TimelineToolbar K/R buttons, PropertyPanel per-property diamonds, shortcuts panel, toast notifications, and keyframes guide documentation. All gated on STUDIO_KEYFRAMES_ENABLED (default false).
1 parent 20ca775 commit 6e8b6eb

29 files changed

Lines changed: 705 additions & 287 deletions

‎docs/docs.json‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,6 @@
7474
{
7575
"group": "Guides",
7676
"pages": [
77-
"guides/mcp",
7877
"guides/pipeline",
7978
"guides/html-in-canvas",
8079
"guides/website-to-video",
@@ -85,6 +84,7 @@
8584
"guides/prompting",
8685
"guides/hyperframes-vs-remotion",
8786
"guides/gsap-animation",
87+
"guides/keyframes",
8888
"guides/rendering",
8989
"guides/remove-background",
9090
"guides/hdr",
@@ -227,7 +227,6 @@
227227
"pages": [
228228
"catalog/components/grain-overlay",
229229
"catalog/components/grid-pixelate-wipe",
230-
"catalog/components/motion-blur",
231230
"catalog/components/parallax-unzoom",
232231
"catalog/components/parallax-zoom",
233232
"catalog/components/shimmer-sweep",

‎docs/guides/keyframes.mdx‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
title: Keyframes & Arc Motion
3+
description: "Edit GSAP keyframes visually in Studio — timeline diamonds, arc motion paths, and gesture recording."
4+
---
5+
6+
Studio gives you visual tools to create and edit GSAP keyframes without writing code. You can adjust animation properties in the Design Panel, convert straight-line motion into curved arcs, and record gesture-based motion by dragging elements in the preview.
7+
8+
## Timeline Keyframe Diamonds
9+
10+
When you open a composition in Studio, the timeline shows **diamond markers** on clips that have GSAP animations. Each diamond represents a keyframe — a point in time where a property value is set.
11+
12+
- **Start diamond** — where the tween begins (e.g., `x: 0`)
13+
- **End diamond** — where the tween ends (e.g., `x: 1000`)
14+
- Elements with multiple tweens show multiple diamond pairs
15+
16+
<Note>
17+
Keyframe diamonds are synthesized from your GSAP tweens automatically. Every `.to()`, `.from()`, and `.fromTo()` call produces start and end markers on the timeline.
18+
</Note>
19+
20+
## Editing Animation Properties
21+
22+
Select any animated element in the preview or timeline to open the Design Panel. The **Animation** section shows:
23+
24+
- **Method badge** — `Animate`, `Animate In`, or `Animate Out` (maps to `.to()`, `.from()`, `.fromTo()`)
25+
- **Timing** — Length (duration) and Starts at (position on timeline)
26+
- **Speed** — The GSAP ease (e.g., `power2.inOut`, `back.out(3)`)
27+
- **Speed curve** — Visual preview of the easing function
28+
- **Properties** — Each animated property (Move X, Move Y, Scale, Opacity, etc.) with its target value
29+
30+
<Steps>
31+
<Step title="Select an element">
32+
Click an animated element in the preview or its clip in the timeline. The Design Panel opens on the right.
33+
</Step>
34+
<Step title="Edit property values">
35+
Change any property value directly — for example, set Move X to `500` to make the element travel 500px. Changes apply immediately via soft reload.
36+
</Step>
37+
<Step title="Change the ease">
38+
Click the ease dropdown (e.g., "Smooth ease") to pick a different easing function. The speed curve preview updates live.
39+
</Step>
40+
<Step title="Verify in Code tab">
41+
Switch to the Code tab to see the generated GSAP code. Every Design Panel edit writes valid GSAP that renders identically in preview and headless export.
42+
</Step>
43+
</Steps>
44+
45+
## Arc Motion
46+
47+
Arc Motion converts a straight-line x/y animation into a curved path using GSAP's MotionPathPlugin. Instead of moving in a straight diagonal, the element follows a smooth arc — like tossing an object into a basket.
48+
49+
### When to Use It
50+
51+
Use Arc Motion when an element has both `x` and `y` properties in a single tween. Common examples:
52+
- Add-to-cart animations (item arcs from product to cart icon)
53+
- Throw/toss effects
54+
- Any motion that should feel physical rather than robotic
55+
56+
### Step-by-Step
57+
58+
<Steps>
59+
<Step title="Select an element with x/y motion">
60+
The element must have a `.to()` tween with both Move X and Move Y properties. Select it in the preview or timeline.
61+
</Step>
62+
<Step title="Toggle Arc Motion ON">
63+
In the Animation section of the Design Panel, find the **Arc Motion** toggle below the property list. Switch it ON.
64+
</Step>
65+
<Step title="Adjust Curviness">
66+
The **Curviness** slider controls how exaggerated the arc is:
67+
- `0` — straight line (no curve)
68+
- `1` — gentle natural arc
69+
- `1.5–2.0` — smooth throw feel (recommended)
70+
- `3.0` — extreme loop
71+
72+
Scrub the timeline to preview the arc in real time.
73+
</Step>
74+
<Step title="Toggle Auto-Rotate (optional)">
75+
Enable **Auto-Rotate** to make the element rotate to face the direction of travel along the arc. This adds a "thrown" feel vs. a "floating" feel.
76+
</Step>
77+
<Step title="Verify the generated code">
78+
Switch to the Code tab. You'll see:
79+
80+
```javascript
81+
tl.to("#element", {
82+
scale: 0.4,
83+
opacity: 0,
84+
duration: 1.0,
85+
ease: "power2.inOut",
86+
motionPath: {
87+
path: [{x: 0, y: 0}, {x: 1400, y: -280}],
88+
curviness: 1.5,
89+
autoRotate: true
90+
}
91+
}, 1.0);
92+
```
93+
94+
The MotionPathPlugin CDN script is added automatically.
95+
</Step>
96+
<Step title="Disable to restore straight motion">
97+
Toggle Arc Motion OFF to restore the original `x` and `y` properties as flat tween values.
98+
</Step>
99+
</Steps>
100+
101+
<Note>
102+
Arc Motion works for flat `.to()` tweens with x/y properties. It synthesizes waypoints from `{x: 0, y: 0}` (start) to `{x: targetX, y: targetY}` (end). For more complex paths with intermediate waypoints, edit the `motionPath.path` array directly in the Code tab.
103+
</Note>
104+
105+
## Gesture Recording
106+
107+
Record motion by physically dragging an element in the preview while the timeline plays. The pointer path is simplified and converted into GSAP keyframes automatically.
108+
109+
<Steps>
110+
<Step title="Select an element">
111+
Click the element you want to animate in the preview.
112+
</Step>
113+
<Step title="Click Record or press R">
114+
In the Animation section of the Design Panel, click **Record gesture (R)** or press the R key. The timeline starts playing.
115+
</Step>
116+
<Step title="Drag the element">
117+
Move the element in the preview by dragging it. Your pointer motion is sampled at ~60fps. A trail overlay shows the path you're drawing.
118+
</Step>
119+
<Step title="Stop recording">
120+
Press R again or wait for the timeline to reach the end. Recording stops, the motion is simplified (reducing ~180 raw samples to 5–15 clean keyframes), and the keyframes are written to the GSAP script immediately.
121+
</Step>
122+
<Step title="Review or undo">
123+
The timeline seeks back to the recording start so you can scrub through the result. If you don't like it, press **Cmd+Z** to undo and try again.
124+
</Step>
125+
</Steps>
126+
127+
## Clipboard Context
128+
129+
The **clipboard icon** next to the element name in the Design Panel copies structured element context to your clipboard:
130+
131+
```
132+
Element: Title (#title)
133+
File: index.html:15
134+
Position: x=100, y=40
135+
Size: 264×43
136+
Tag: <div>
137+
Animation: from() 0.5s at 0s, ease: power2.out
138+
Properties: x: -40, opacity: 0
139+
```
140+
141+
Paste this into any AI agent prompt to give it spatial context about the element — its position, size, animation, and source location.

0 commit comments

Comments
 (0)