image_sequence element

Scroll-driven filmstrip of crossfading images.

Fields

Field	Type	Default	Description
image_sequence	list of path (optional)	required	Ordered image paths, relative to the slide source file. Min 2 entries. An empty string ("") reserves a blank slot in the timeline — neighboring frames crossfade out before and in after it. Repeating the same path consecutively extends its visible duration by one slot per repeat.
frame_distance	number	required	Scroll distance between consecutive frames' snap positions (P_i = scroll_offset + i * frame_distance). Must be > 0.
hold_fraction	number	0.2	Fraction of frame_distance each frame stays at full opacity, centered on its snap position. Must be in [0, 1) so the crossfade (frame_distance * (1 - hold_fraction)) stays positive. Default 0.2.
scroll_offset	number	0	Scroll position of frame 0's snap (P_0); frame i snaps at scroll_offset + i * frame_distance.
fade_in	number	0	Scroll distance of the leading fade-in ramp before frame 0's snap. 0 (default) = frame 0 starts at full opacity (hard cut). > 0 = the timeline begins (opacity 0) at scroll_offset - fade_in.
fade_out	number	0	Scroll distance of the trailing fade-out ramp after the last frame's snap. 0 (default) = the last frame stays at full opacity past its snap (hard cut). > 0 = the timeline ends (opacity 0) at last_snap + fade_out.
object_fit	"cover" | "contain" | "fill" (optional)	null	How each image fills its box. Required when both size dimensions are numeric (or animated), forbidden when one is "auto". Same semantics as ImageElement.object_fit.
compositing	"blend" | "overlay" | "incremental"	"blend"	How successive frames composite on top of one another as the sequence advances. "blend" (default): symmetric crossfade — each frame ramps 0→1 in and 1→0 out, leaving a brief mid-transition window where both frames are partially transparent and the slide background may show through. Use for frames that have their own per-pixel transparency and should fully replace each other. "overlay": each frame ramps 0→1 in, then holds at 1 until the next frame has fully faded in, then instantly drops to 0. The next frame fully covers it before it disappears, so the slide background never shows through. Use for opaque image sequences (photos, screenshots). "incremental": each frame ramps 0→1 in, then holds at 1 until the sequence ends — all revealed frames stay layered and the rendered image is the alpha-composite of every frame to date. Use for build-up sequences where each frame adds a new element on a transparent background (a flowchart growing, an equation revealed line by line, a map gaining markers).

Every element also shares the common fields — position, size, anchor, opacity, scale, and angle.

Example

{
  // Scroll-driven filmstrip: three frames crossfading on a scroll grid.
  image_sequence: ["frames/01.png", "frames/02.png", "frames/03.png"],
  frame_distance: 400,
  position: [50, 50],
  anchor: [50, 50],
  width: 70,
}