Skip to content
Apexify.jsDocs
Apexify.js version v5.4.5

Node / Video Ffmpeg · guide

Metadata, frames & discovery

Current Apexify.js 6.0.0 documentation for Metadata, frames & discovery.

apexify.jsRuntime: nodeCURRENTSince 6.0.0

See also: Discovery & metadata · Frame extraction suite (option-by-option explanations + examples) · Imperative painter.* helpers.

getInfo

Returns getVideoInfo payload (duration, width, height, fps, bitrate, format).

Fields (runtime)

FieldMeaning
durationSeconds (float).
width, heightPixel dimensions of primary video stream.
fpsParsed from r_frame_rate (defaults 30 if missing).
bitrateStream or container bitrate when exposed by ffprobe.
formatformat_name string (e.g. mov,mp4,m4a...).

Example

SOURCEtypescript
typescript
Studio
const meta = await painter.createVideo({  source: 'https://example.com/file.mp4',  getInfo: true,});console.log(meta.duration, `${meta.width}x${meta.height}`, meta.fps);

detectFormat

Runs getVideoInfo plus ffprobe codec_name for v:0.

Return shape

FieldNotes
format, containerFrom getVideoInfo.format.
codecVideo codec short name (h264, vp9, …) or unknown.
width, height, fps, bitrate, durationSame as getInfo.

Example

SOURCEtypescript
typescript
Studio
const probe = await painter.createVideo({  source: './movie.mkv',  detectFormat: true,});console.log(probe.codec, probe.container, probe.duration);

extractFrame

Single raster grab at time (seconds) or frame index (0-based in API; implementation forwards to extractVideoFrame).

OptionTypeNotes
timenumberSeconds — overrides frame when set (pass via extractVideoFrame ordering).
framenumberDefault 0.
width, heightnumberScale on canvas after decode (default = native frame size).
outputFormatjpg | pngJPEG vs PNG decode path; return value from createVideo is always a PNG buffer composited on canvas (VideoCreator).
qualitynumberJPEG -q:v style (lower = better, default 2).

Example

SOURCEtypescript
typescript
Studio
const shot = await painter.createVideo({  source: './talk.mp4',  extractFrame: {    time: 45.5,    width: 1280,    height: 720,    outputFormat: 'jpg',    quality: 3,  },});// shot.buffer — PNG// shot.canvas — { width, height }

extractFrames — two modes

A) Explicit timestamps → Buffer[]

Set times: number[] (seconds). Uses extractVideoFrame per entry.

OptionNotes
timesRequired for this mode.
outputFormatjpg / png.
qualityPer-frame quality.
SOURCEtypescript
typescript
Studio
const buffers = await painter.createVideo({  source: './clip.mp4',  extractFrames: {    times: [0, 1.5, 3.0],    outputFormat: 'png',    quality: 2,  },});

B) Interval sampling → file paths

Set interval (milliseconds, must be > 0). Uses ApexPainter.extractFrames internally.

OptionNotes
intervalMs between samples → derived fps = 1000 / interval for FFmpeg -vf fps=.
frameSelection.start, endFrame indices clamped to extracted range.
outputFormatjpg / png.
outputDirectoryDeclared on VideoCreationOptions but interval mode writes under .temp-frames/frames-<timestamp>/ — treat outputDirectory as reserved / unused today.
SOURCEtypescript
typescript
Studio
const frames = await painter.createVideo({  source: './walk.mp4',  extractFrames: {    interval: 500, // every 500 ms → ~2 fps sampling    outputFormat: 'jpg',    frameSelection: { start: 0, end: 40 },  },});// frames: { source: string; isRemote: boolean }[]

extractAllFrames

Delegates to ApexPainter.extractAllFrames — dumps every decoded frame in a window (heavy on long clips).

OptionDefaultNotes
outputFormatpngjpg / png.
outputDirectory./extracted-framesDestination folder (created).
quality2JPEG -q:v.
prefixframeprefix-%06d.ext.
startTime, endTime0 … durationSeconds slice.

Returns { source, frameNumber, time }[] (time increments by 1/fps from metadata).

Example

SOURCEtypescript
typescript
Studio
const list = await painter.createVideo({  source: './short.mp4',  extractAllFrames: {    outputFormat: 'png',    outputDirectory: './dump',    prefix: 'anim',    startTime: 0,    endTime: 2,  },});

generateThumbnail

Montage of count evenly spaced grabs on a single canvas (PNG).

OptionDefaultNotes
count9Timeline stride duration / (count + 1).
grid{ cols: 3, rows: 3 }Tile layout.
width, height per cell320×180Each thumbnail cell size.
outputFormatjpgFeed into extractVideoFrame.
quality2JPEG quality.
SOURCEtypescript
typescript
Studio
const grid = await painter.createVideo({  source: './film.mp4',  generateThumbnail: {    count: 6,    grid: { cols: 3, rows: 2 },    width: 480,    height: 270,  },});// grid.buffer — PNG sheet

generatePreview

Writes count stills under outputDirectory (default ./video-preview).

OptionDefault
count10
outputDirectory./video-preview
outputFormatpng
quality2
SOURCEtypescript
typescript
Studio
const previews = await painter.createVideo({  source: './talk.mp4',  generatePreview: {    count: 12,    outputDirectory: './storyboard',    outputFormat: 'jpg',  },});// [{ source, frameNumber, time }, ...]

detectScenes

Runs FFmpeg select='gt(scene,threshold)' pipeline (shell grep / awk / sed — most reliable on POSIX).

OptionDefaultNotes
threshold0.3Scene detect sensitivity.
outputPath—Optional JSON dump of [{ time, scene }].
SOURCEtypescript
typescript
Studio
const cuts = await painter.createVideo({  source: './interview.mp4',  detectScenes: {    threshold: 0.35,    outputPath: './scenes.json',  },});

On failure / empty parse, implementation returns [].

Next steps

Video — advanced workflowsGuide · node · CURRENT

Current Apexify.js 6.0.0 documentation for Video — advanced workflows.

Video options — deep-dive guidesGuide · node · CURRENT

Current Apexify.js 6.0.0 documentation for Video options — deep-dive guides.

Video & FFmpeg (createVideo) — overviewGuide · node · CURRENT

Current Apexify.js 6.0.0 documentation for Video & FFmpeg (createVideo) — overview.

Discovery & metadata optionsGuide · node · CURRENT

Current Apexify.js 6.0.0 documentation for Discovery & metadata options.