renderSceneToVideoFrames

Encodes a frame sequence into video via VideoCreator.createVideo with createFromFrames. The composed scene PNG can be prepended to your frame list.

Requirements: FFmpeg on PATH. video.options.createFromFrames is mandatory (throws if missing).

#Pipeline (summary)

1. composedPng = await sceneCreator.render(scene, video.sceneRender) — optional SceneRenderOptions (same as renderScene second argument).
2. body = expandSceneVideoFrames(framesWithRepeats) or [...createFromFrames.frames]
3. frames = prepend [composedPng, ...body] unless prependComposedToFrames === false
4. merged = { ...video.options, source: video.options.source ?? composedPng, createFromFrames: { ...cf, frames } }
5. videoCreator.createVideo(merged)

SceneVideoFrameSlot: string | Buffer | { source: string | Buffer; repeat?: number } · Optional video.sceneRender forwards SceneRenderOptions to that inner scene render step.

#Variant: intro card + only composed frame

1import { ApexPainter } from "apexify.js";2 3const painter = new ApexPainter();4 5const scene = {6  width: 1920,7  height: 1080,8  background: { colorBg: "#020617" },9  layers: [10    { type: "text", texts: [{ text: "Intro", x: 120, y: 420, fontSize: 96, color: "#f8fafc" }] },11  ],12};13 14await painter.renderSceneToVideoFrames(scene, {15  options: {16    createFromFrames: {17      frames: [],18      outputPath: "./out/intro-only.mp4",19      fps: 30,20      format: "mp4",21      quality: "high",22    },23    prependComposedToFrames: true,24  },25  sceneRender: { maxSurfaceDepth: 24 },26});

With empty frames and default prepend, the list is [composedPng] — a very short clip (one image at fps).

#Variant: composed + file paths / buffers

1await painter.renderSceneToVideoFrames(scene, {2  options: {3    createFromFrames: {4      frames: ["./frames/a.png", "./frames/b.png"],5      outputPath: "./out/slideshow.mp4",6      fps: 12,7      format: "mp4",8      quality: "medium",9    },10    prependComposedToFrames: true,11  },12});

Final order: [composedPng, a.png, b.png].

#Variant: framesWithRepeats (holds / timelapse feel)

1await painter.renderSceneToVideoFrames(scene, {2  options: {3    createFromFrames: {4      frames: [],5      outputPath: "./out/with-holds.mp4",6      fps: 24,7      format: "mp4",8      quality: "high",9    },10    prependComposedToFrames: true,11    framesWithRepeats: [12      { source: "./segment1.png", repeat: 48 },13      { source: "./segment2.png", repeat: 24 },14      someBuffer,15    ],16  },17});

expandSceneVideoFrames flattens repeat into consecutive identical frames for FFmpeg.

#Variant: no composed — only explicit frames

1await painter.renderSceneToVideoFrames(scene, {2  options: {3    createFromFrames: {4      frames: ["./only/001.png", "./only/002.png"],5      outputPath: "./out/no-prepend.mp4",6      fps: 30,7      format: "mp4",8    },9    prependComposedToFrames: false,10  },11});

Must have non-empty frames or framesWithRepeats after expansion, or you get “no frames after expansion” (composed is not added).

#Variant: optional source on VideoCreationOptions

If you omit source, it defaults to composedPng so VideoCreationOptions stays valid for branches that read source.

1options: {2  // source omitted on purpose3  createFromFrames: { /* … */ },4},

#Variant: extra VideoCreationOptions keys

The merge does { ...opt, source, createFromFrames }. VideoCreator.createVideo typically follows one operation branch — extra keys are usually ignored unless they collide with detection order. Keep createFromFrames as the primary operation for this path.

#Troubleshooting

#See also

• Video overview — createVideo one-op router
• Video pipeline (advanced) — trim, splice, captions, SFX after scene export
• createAudio (advanced) — procedural SFX to mux with mixAudio or pipeline .audio()
• Video (advanced) hub