Skip to content

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.ts
index 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.md
index 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.