Static Helpers

These are static methods on the SIMPLEFFMPEG class — no project instance required.

SIMPLEFFMPEG.getDuration(clips)

Computes the total visual timeline duration from a clips array. Handles duration shorthand, auto-sequencing, and transition overlap subtraction. Pure function — no file I/O.

const clips = [
  { type: "video", url: "./a.mp4", duration: 5 },
  {
    type: "video",
    url: "./b.mp4",
    duration: 10,
    transition: { type: "fade", duration: 0.5 },
  },
];
 
SIMPLEFFMPEG.getDuration(clips); // 14.5

Useful for computing text overlay timings or background music end times before calling load().

SIMPLEFFMPEG.getTransitionOverlap(clips)

Returns the total seconds consumed by xfade transition overlaps among visual clips. Handles duration shorthand and auto-sequencing. Pure function — no file I/O.

const clips = [
  { type: "video", url: "./a.mp4", duration: 5 },
  {
    type: "video",
    url: "./b.mp4",
    duration: 10,
    transition: { type: "fade", duration: 0.5 },
  },
];
 
SIMPLEFFMPEG.getTransitionOverlap(clips); // 0.5
SIMPLEFFMPEG.getDuration(clips);          // 14.5

Useful for computing how much timeline compression transitions will cause, or for inflating clip durations so the rendered output hits a target length.

SIMPLEFFMPEG.probe(filePath)

Returns ffprobe-derived metadata for video, audio, or image files.

const info = await SIMPLEFFMPEG.probe("./video.mp4");
// {
//   duration: 30.5,         // seconds
//   width: 1920,
//   height: 1080,
//   hasVideo: true,
//   hasAudio: true,
//   rotation: 0,            // mobile rotation metadata
//   videoCodec: "h264",
//   audioCodec: "aac",
//   format: "mov,mp4,m4a,3gp,3g2,mj2",
//   fps: 30,
//   size: 15728640,         // bytes
//   bitrate: 4125000,       // bits/sec
//   sampleRate: 48000,      // Hz
//   channels: 2
// }

Fields that don’t apply to the file type are null (e.g. width/height/fps for audio-only files).

Throws MediaNotFoundError if the file cannot be found or probed.

SIMPLEFFMPEG.snapshot(filePath, options)

Captures a single frame from a video and writes it as an image. Format is determined by the outputPath extension.

await SIMPLEFFMPEG.snapshot("./video.mp4", {
  outputPath: "./frame.png",
  time: 5,
});
 
// JPEG with quality control and resize
await SIMPLEFFMPEG.snapshot("./video.mp4", {
  outputPath: "./thumb.jpg",
  time: 10,
  width: 640,
  quality: 4,
});

Supported formats: .jpg, .jpeg, .png, .webp, .bmp, .tiff.

SIMPLEFFMPEG.extractKeyframes(filePath, options)

Extracts representative frames using scene-change detection or fixed time intervals.

• With outputDir — writes frames to disk and returns string[] file paths
• Without outputDir — returns in-memory Buffer[] (no temp files left behind)

Each call with outputDir creates a unique simpleffmpeg-keyframes-XXXXXX subdirectory inside it, so repeat and concurrent calls against the same outputDir are fully isolated. Always use the returned paths — do not assume frames live directly at ${outputDir}/frame-0001.jpg.

// Scene-change detection — returns Buffer[]
const frames = await SIMPLEFFMPEG.extractKeyframes("./video.mp4", {
  mode: "scene-change",
  sceneThreshold: 0.4,
  maxFrames: 8,
  format: "jpeg",
});
 
// Fixed interval — writes to disk, returns string[]
const paths = await SIMPLEFFMPEG.extractKeyframes("./video.mp4", {
  mode: "interval",
  intervalSeconds: 5,
  outputDir: "./frames/",
  format: "png",
});

Throws FFmpegError if extraction fails.

SIMPLEFFMPEG.validate(clips, options?)

Validates clip descriptors before creating a project. See the Validation guide for full usage.

SIMPLEFFMPEG.getSchema(options?)

Exports a structured text description of all accepted clip types. See the Schema Export guide for full usage.

SIMPLEFFMPEG.getPresets() / SIMPLEFFMPEG.getPresetNames()

Returns available platform preset configurations:

SIMPLEFFMPEG.getPresetNames(); // ['tiktok', 'youtube-short', 'youtube', ...]
SIMPLEFFMPEG.getPresets();     // { tiktok: { width: 1080, height: 1920, fps: 30 }, ... }