Imperative video helpers (painter.)

Besides createVideo({ ... }), ApexPainter exposes direct probe and frame-extraction methods. These methods use the same central FFmpeg session, validation, runtime limits, remote-network policy, abort/process handling, and isolated temporary workspaces as the rest of the video stack.

Requirements: FFmpeg and ffprobe must be available on PATH, configured through configureApexifyRuntime({ ffmpeg: ... }), or supplied through the documented APEXIFY_FFMPEG_PATH / APEXIFY_FFPROBE_PATH environment variables.

#Method map

The same helpers are available through the grouped painter.video stack where documented by its public type surface.

#getVideoInfo(source, skipFfmpegCheck?)

1const info = await painter.getVideoInfo('./clip.mp4');2console.log(info.width, info.height, info.fps, info.duration);

source may be a local path, an HTTP(S) URL permitted by the central network policy, or a Buffer. Remote/buffer inputs are staged inside the operation's isolated temporary workspace. Do not depend on any internal temporary pathname.

skipFfmpegCheck defaults to false. It exists for already-validated internal/delegated flows; normal application code should leave it omitted.

Probe failures use the structured Apexify process/input error paths rather than a documented null sentinel contract.

#extractFrameAtTime

1const jpeg = await painter.extractFrameAtTime(2  './film.mp4',3  42.5,4  'jpg',5  3,6);

Signature:

1extractFrameAtTime(2  videoSource: string | Buffer,3  timeSeconds: number,4  outputFormat?: 'jpg' | 'png',5  quality?: number,6): Promise<Buffer>

Defaults are outputFormat = 'jpg' and quality = 2. quality must be an integer from 1 through 31. The timestamp must be finite, non-negative, inside the governed video duration, and inside the actual source duration.

#extractFrameByNumber

1const png = await painter.extractFrameByNumber('./take.mp4', 48, 'png');

frameNumber is 1-based. The implementation probes FPS and converts the requested frame to (frameNumber - 1) / fps. The frame number must be a positive integer; format and quality use the same validation as extractFrameAtTime.

#extractMultipleFrames

1const shots = await painter.extractMultipleFrames(2  './interview.mp4',3  [0, 1.25, 3.8, 10],4  'jpg',5  3,6);

This returns an ordered Buffer[]. The timestamp array must be non-empty, each timestamp must be finite and non-negative, and the request is bounded by both collection and maxVideoExtractedFrames limits. Extraction is performed through the shared frame operation/runtime rather than an unbounded Promise.all fan-out.

#extractFrames(source, options)

1const frames = await painter.extractFrames('./motion.mp4', {2  interval: 500,3  outputFormat: 'jpg',4  quality: 3,5  outputDirectory: './sampled-frames',6  frameSelection: { start: 0, end: 19 },7});

interval is required and is expressed in milliseconds; sampling FPS is derived as 1000 / interval. frameSelection.start and .end are zero-based indexes into the generated sampling sequence and must form an increasing range inside that sequence.

Current options include:

The method writes the selected frames to the output directory and returns local descriptors { source, isRemote: false }[]. The operation's temporary input workspace is isolated and cleaned separately; output files intentionally persist because they are caller-visible results.

The number of extracted files is bounded by maxVideoExtractedFrames.

#extractAllFrames(source, options?)

1const frames = await painter.extractAllFrames('./short.mp4', {2  outputDirectory: './cells',3  outputFormat: 'png',4  startTime: 0,5  endTime: 1,6  prefix: 'frame',7});

Defaults:

The prefix must be a simple filename prefix, the time range must be inside the source duration, and the estimated frame count is checked against maxVideoExtractedFrames before FFmpeg runs. Results are { source, frameNumber, time }[] with zero-based frameNumber metadata.

Disk warning: extracting every frame from a long/high-FPS source can produce substantial persistent output. Use an explicit output directory with sufficient quota and prefer interval/timestamp extraction when full-frame dumping is unnecessary.

#Security, cleanup, and cancellation

All direct helpers inherit the Phase 8/13 video runtime controls:

• remote HTTP(S) inputs pass through DNS/SSRF validation, redirect revalidation, transfer-byte limits, and remote concurrency bounds;
• FFmpeg/ffprobe use argv execution with shell: false;
• temporary operation state lives in isolated fs.mkdtemp() workspaces and is cleaned by default;
• custom temp roots come from explicit/session settings, runtime temp.rootDirectory, APEXIFY_TEMP_DIR, then the OS temp directory;
• process timeouts and AbortSignal controls are handled through the shared FFmpeg session where the enclosing API exposes controls;
• caller-visible outputDirectory files from extractFrames / extractAllFrames are outputs, not temporary workspace files, and are not automatically deleted.

See Security & deployment and Runtime validation & resource governance for the complete policy.

#Choosing the surface

Use createVideo() for the typed one-operation router, videoPipeline() for multi-step declarative editing, and these direct helpers when the task is specifically probing or extracting frames.

See also: Frame extraction suite · Metadata & frames · Video pipeline.