Keyframe Clip

Overview

A timeline node for creating motion with keyframes. Waveform nodes describe motion mathematically; this node directly specifies a shape at a given frame. Register and record poses for path or image transformations in the dedicated editor, then play or export them as an AnimationClip.

Usage tips

• Choose by motion: periodic or mechanical motion → motion node; acted motion such as wind up → hold → swing down → this node.
• Basic flow: connect path or image → move through the frames in the editor and set keys in pose mode → check with play → send the result downstream through the matching Path / Image outputs. Those carry the current-frame result, so you can stack more filters or motion nodes after them and finish with animation_render to play everything. Use the spritesheet output when you want the sheet directly.
• Clip duration and key positions are frame-based. New clips take their duration and fps from the project animation defaults (canvas bar).
• Supplying progress (0–1) externally lets the graph control clip evaluation time, including integration with time_source or progress-based effect branching.
• The value_float output is a plain Float: the clip's first numeric (Scalar) track evaluated at the current clip time. Use it to keyframe a single numeric parameter — the Inspector's 🎞️ animation button ("Keyframe" flavor) wires this output to the target parameter automatically. Outside the key range the value clamps to the edge keys, interpolation follows the track's setting (the shared easing vocabulary of ease_in_out), and clips without a Scalar track output 0.0.
• The source node itself is never rewritten. The original shape remains intact.

Common pitfalls

• A key was added, but nothing moves: one key cannot be interpolated. You need at least two keys, a start and an end.
• The editor and output look different: the editor displays source + applied clip. The Path/Image outputs carry that same current-frame result downstream; clip/value are the animation data itself and spritesheet is the full sheet, so check which output you are using.

Interactive editor

Keyframe Clip has an interactive editor with an embedded source.

The editor supports:

• source switching
  • Choose whether to edit Path or Image.
• pose mode
  • Save the shape at the current time as one key pose.
• record mode
  • Record a drag path across the start/end range.
• play / stop / loop
  • Play the editor preview directly.
• key list
  • Review saved keys and jump to one.
• export
  • Sprite-sheet PNG sampling frames t=0..D-1 of the D-frame duration (the last frame stops just before the loop restarts)
  • Batch export of key PNG files at actual key frames only
  • Current-frame PNG export

Important:

• The source node itself is not rewritten.
• The editor displays the source with the clip applied.
• Switching keys displays that key pose directly.
• For an image source, the current editor handles translation / rotation / scale transforms.
  • Rotation uses zone dragging: move the pointer near the outside edge until ↺ appears.
• For a path source, move points / handles directly to create a pose.

Technical details

AnimationClip is the user-facing animation type introduced in P07.
Internally it contains explicit tracks / keyframes and bridges to and from RecordedLayer when needed.

When the layer input is connected:

• Convert the layer input into a base clip
• Overlay clip_data as a local clip
• Expose the same clip as both AnimationClip and RecordedLayer at the output

The path / image inputs are also editor sources and are intended to be used with downstream ClipApplyPath / ClipApplyImage.

Examples

Key-editing a Path

1. Create BezierPath.
2. Connect it to KeyframeClip.path.
3. Open the KeyframeClip editor.
4. At frame 0, move a point / handle to create the first pose.
5. Create another pose at the last frame.
6. Connect KeyframeClip.clip to ClipApplyPath.clip.
7. Connect BezierPath.path to ClipApplyPath.path, then drive progress (0–1) with Float Input or Time Source to play it.

Key-editing an Image

1. Create an image source such as PixelCanvas.image.
2. Connect it to KeyframeClip.image.
3. Open the KeyframeClip editor.
4. Drag the image to move it, drag a corner to scale it, and rotate it in the ↺ zone near the outer edge.
5. Connect KeyframeClip.clip to ClipApplyImage.clip.
6. Connect the source image to ClipApplyImage.image, then change progress to play it.

Exporting from the clip editor

1. Open the KeyframeClip editor.
2. Set Duration (frames) (defaults to the project's default frame count).
3. Set Columns (0=Auto) if needed.
4. Export every frame with Spritesheet PNG.
5. Export only actual keys as separate PNG files with Export Key PNGs.

Additional notes:

• A spritesheet from an Image source samples frames t=0..D-1 of the D-frame duration.
• With Columns = 0, automatic layout chooses a roughly square arrangement rather than a single horizontal row.
• Choose placement order from Row (row_major) or Column (column_major).
• Node output follows the P07A SpriteSheet contract:
  • spritesheet is the dedicated type.
  • frame_count / fps / columns / rows / frame_width / frame_height / fill_order are helper metadata outputs returned with the same export settings.
• The columns / rows / frame_width / frame_height / fill_order outputs make downstream frame splitting easier.
• Exporting a Path source produces a transparent-background PNG of the line preview shown in the editor.
• For the final rendered appearance, use ClipApplyPath -> PathStroke -> AnimationRender.

Related nodes

• clip_apply_path / clip_apply_image — apply the clip to a path or image downstream
• animation_render — create a sprite sheet of the final appearance
• clip_mixer / clip_loop_fit — mix clips or adjust a loop
• Waveforms such as motion — when mathematical motion is sufficient

Time, multiple tracks, and data safety

• The only time input is progress (normalized 0–1); it evaluates progress * duration (frames). With nothing connected, graph evaluation time is treated as normalized progress. The legacy absolute-seconds time pin has been removed; old projects with time connections are rewired to progress on load.
• Connect the 0–1 output of Time Source to progress.
• Clip duration and key positions are frame-based (v2). Legacy v1 (seconds-based) clip_data is converted on load using the fps derived from the old Seconds / Frame setting (or the legacy default 10fps when missing).
• With multiple image Transform tracks, preview and export apply every track in order. Canvas operations and key add/move/delete affect only the selected track.
• Shortening duration does not destroy out-of-range keys. Evaluation time is clamped to 0–duration. Use the explicit Trim command to delete them or Scale to fit all keys proportionally into the duration.
• Invalid non-empty clip_data is not silently treated as empty. The editor preserves the original text, pauses saving, and offers copy or a confirmed reset.
• Per-track interpolation shares the same easing vocabulary and curves as the ease_in_out node (Linear / Ease In / … / Bounce Out / Step).