Clips

Clips are the fundamental building blocks of video compositions — video, audio, image, text, and caption (word-timed karaoke text — see Rendering · Captions) elements positioned on the timeline. Custom kinds can be registered with registerClipKind (payload under props, validated by your schema).

All clip operations are performed through commands: deterministic, undoable operations that can be batched, synced, and logged.

Anatomy of a clip

Every clip has:

• Timeline placement — startUs, durationUs: where and how long the clip appears on the timeline.
• Source trimming — trimStartUs (video/audio): where in the source asset the clip starts playing; the out point follows from durationUs. Media beyond the visible range is headroom — what transitions draw from.
• Transform — position, scale, rotation, opacity (normalized composition coordinates).
• Animations — optional per-property keyframes (keyframe/set) on x/y/scale/rotation/opacity/volume — see Rendering · Animation.
• Effects — an ordered stack of GPU effects (effect/add): colorAdjust, blur, chromaKey — see Rendering · Effects.
• Type-specific properties — e.g. text content and font for text clips, volume for audio, word timing and style for captions.

Operations

project.dispatch({
  type: "clip/split",
  payload: { clipId: "clip-1", atUs: 2_000_000 },
});