Video & FFmpeg (createVideo) — overview

await painter.createVideo(options[, painterOpts]) is the main entry for FFmpeg/ffprobe work: probe clips, extract frames, transcode, trim, audio mixes, addTextOverlay, compositing, and more.

Multi-step editor workflows (trim → splice → captions → audio in one stack) live under Advanced → Video pipeline — not in this feature guide.

Requirements: ffmpeg and ffprobe on PATH, or configure custom binary paths through the Apexify runtime configuration. Buffer, local-path, and http(s) video sources all enter the same source-resolution policy. Remote video is streamed into an isolated temporary workspace under the configured byte, host, redirect, timeout, retry, and concurrency limits; it is not first accumulated as one full in-memory Buffer. See Video security & runtime configuration.

Low-level stack: painter.video — typed getVideoInfo, frame extract helpers, and videoPipeline() (advanced).

#Signature & asset refs

1await painter.createVideo(options: VideoCreationOptions, painterOpts?: PainterAssetRefsOptions);

When painterOpts.resolveAssetRefs is true, options is passed through maybeResolveRefs ($… placeholders, same pattern as createImage and createGIF on ApexPainter). To resolve refs yourself with the flag off, use prepareForRender.

#Exactly one operation per call

createVideo now validates the whole request before resolving media, probing files, creating workspaces, or starting FFmpeg. A call must contain exactly one video operation key in addition to source and the optional execution controls.

1await painter.createVideo({2  source: './input.mp4',3  trim: { startTime: 5, endTime: 12, outputPath: './clip.mp4' },4  // convert: { ... } // ❌ a second operation is rejected; it is not silently ignored5});

Use videoPipeline() when several edits belong to one project. The options reference card maps every createVideo operation to its guide.

Some operations use their own media lists (for example merge, splitScreen, and batch), but the public VideoCreationOptions contract still includes top-level source.

#Shared execution controls

All FFmpeg-backed operations share the same controls:

1await painter.createVideo({2  source: './input.mp4',3  convert: { outputPath: './out.mp4', format: 'mp4' },4  signal: abortController.signal,5  timeoutMs: 120_000,6  overwrite: false,7  onProgress: ({ percent, time, speed }) => {8    console.log(percent, time, speed);9  },10});

• signal aborts remote resolution and active FFmpeg/ffprobe work where applicable.
• timeoutMs bounds the active FFmpeg operation.
• overwrite defaults to true; false rejects an existing destination before FFmpeg starts and also uses FFmpeg's no-overwrite mode as a race-condition backstop.
• onProgress uses FFmpeg's machine-readable progress channel for FFmpeg-backed jobs. Metadata-only operations do not synthesize progress events.

#Source and process safety model

Phase 8 removes shell-command construction from the video subsystem. FFmpeg and ffprobe are spawned with an executable plus an argv array and shell: false; media paths, filter values, and output paths are validated before execution.

Remote video uses the same centralized network policy as other media. Buffer and remote inputs are materialized only inside isolated temporary workspaces, and workspaces are removed after success, rejection, timeout, or abort unless temporary-file retention is explicitly enabled in runtime configuration.

#Topic tutorials

#Option-by-option manuals (options/)

For every createVideo flag, start at the Video options hub: discovery, frames, transcode, timeline, geometry, audio, visuals, addTextOverlay, compositing, transitions, stabilize, batch, and onProgress.

Editor / multi-step edits: Video pipeline (advanced). Procedural SFX: Advanced → createAudio — pair with mixAudio or pipeline .audio().

#Scenes → video

painter.renderSceneToVideoFrames(scene, video) renders the scene to PNG, merges optional frame slots, and delegates to createVideo. video.options.createFromFrames is required. video.sceneRender.resolveAssetRefs defaults true — scene asset refs use the shared scene resolver unless you opt out.

#Types (package exports)

Import from apexify.js or apexify.js/types.