The VS Code of video editing, built for agents.
TypeScript
Update keyframe documentation to clarify source-local time semantics
konstantin-paulusf2728f616be3
diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.tsindex 9cff2dfd..43f1fa60 100644--- a/packages/jsx/src/types.ts+++ b/packages/jsx/src/types.ts@@ -611,7 +611,11 @@ export type KeyframeTrackProps = {/** `<keyframe>` — one keyframe of the `<keyframeTrack>` holding it. */export type KeyframeProps = {- /** Node-local time: 0 is where the clip begins (its `start`). Any `Time` format. */+ /**+ * Source-local time, any `Time` format: 0 is the source's first frame, so a+ * head-trimmed clip (`sourceIn`) starts at time `sourceIn`, not 0. Keyframes+ * stay pinned to the same content when the clip is moved or trimmed.+ */time: Time;/** The value at `time`: a number, or any CSS color on a `color` track. */value: number | string;diff --git a/reference/jsx/keyframes.md b/reference/jsx/keyframes.mdindex 8508b89e..03f05bcb 100644--- a/reference/jsx/keyframes.md+++ b/reference/jsx/keyframes.md@@ -18,13 +18,26 @@ A `<keyframeTrack>` animates one prop of the element holding it over the node's| Element | Props | Meaning || ------- | ----- | ------- || `<keyframeTrack>` | `property` (**required**) | The prop of the holding element it drives, by name. One track per prop. |-| `<keyframe>` | `time` (**required**), `value` (**required**), `easing` | One keyframe: node-local time in any [time format](./timing.md#time-formats), the value at that time (a number, or any CSS color on a `color` track), and the easing into the next keyframe. |+| `<keyframe>` | `time` (**required**), `value` (**required**), `easing` | One keyframe: source-local time in any [time format](./timing.md#time-formats), the value at that time (a number, or any CSS color on a `color` track), and the easing into the next keyframe. |Animatable props (`property`): `x`, `y`, `offsetX`, `offsetY`, `width`, `height`, `rotation`, `scale`, `scaleX`, `scaleY`, `opacity`, `cornerRadius`, `cornerRadiusTopLeft`, `cornerRadiusTopRight`, `cornerRadiusBottomRight`, `cornerRadiusBottomLeft`, `volume`, `color`, `offset`, `blur`, `value`. Whose prop is the track's holder's: a track under a [paint or color stop](./paints.md) animates the paint (`color`, `opacity`, `offset`), and one under a [`<stroke>`, `<shadow>` or `<effect>`](./styles.md) that style's own — `width` is a stroke's line width, `blur`/`offsetX`/`offsetY` a shadow's, `value` an effect's amount. For preset in/out effects (fade, slides, text reveals, ...) use [`<animation>`](./animations.md) instead.## Semantics-- `time` is **node-local**: `0` is where the clip begins (its `start`). Timing props are parent-relative; keyframe times are not, so animation moves with the clip.+- `time` is **source-local**: `0` is the first frame of the node's **source**, not where the clip sits on the timeline. A keyframe fires when playback reaches that moment of the content, so animation moves with the clip and stays pinned to the same footage when the head is trimmed. On a clip with [`sourceIn`](./timing.md), a keyframe at `time={t}` therefore plays at clip-relative moment `t - sourceIn`; anything meant relative to the clip's first visible frame must be authored at `sourceIn + t`. For an untrimmed clip (and any node without a source) `0` coincides with the clip's start.++ ```tsx+ {/* sourceIn trims 2s off the head, so the clip's first visible frame is source time 2.+ The fade over its first half second is authored at 2–2.5, not 0–0.5. */}+ <video src="footage/clip.mp4" start={0} sourceIn={2} sourceOut={7}>+ <keyframeTrack property="opacity">+ <keyframe time={2} value={0} />+ <keyframe time={2.5} value={1} />+ </keyframeTrack>+ </video>+ ```++- At a [`playbackRate`](./timing.md#playback-rate) other than `1`, keyframe times stay on the source clock: a keyframe lands on the same content frame at any speed, and the animation speeds up or slows down with the footage.- Keyframes may be written in any order; they sort by `time`. Outside the keyframed range the value holds at the first/last keyframe.- `easing` shapes the segment from its keyframe to the next; the last keyframe's easing is ignored. Default `"linear"`.- The prop's static value (`x={10}` on the element) is what holds when the track has no keyframes; while it has any, the track wins.