Generate previews. Not FFmpeg headaches.

VidPeek is a typed video preview generation package for Node.js and CLI. It turns media files into lightweight animated previews and thumbnails using FFmpeg/FFprobe, with safe temp handling, useful presets, overwrite protection, JSON output, and readable errors for real developer workflows.

• Typed Node.js API and scriptable CLI.
• Animated preview generation for WebP, GIF, and MP4.
• Still thumbnail generation for JPG, JPEG, PNG, and WebP.
• FFprobe metadata API for duration, dimensions, FPS, codecs, and format.
• Dry-run preview planning without writing output files.
• Presets for common preview sizes.
• Safe per-run temp directories.
• No shell command strings; FFmpeg is called with spawn argument arrays.
• Readable FFmpeg/FFprobe errors with stage, command, exit code, and stderr.

• Node.js 18+
• FFmpeg
• FFprobe

Verify FFmpeg and FFprobe:

ffmpeg -version
ffprobe -version

pnpm add vidpeek

npm install vidpeek

Generate an animated preview:

vidpeek input.mp4 --out preview.webp --preset web --overwrite

Generate a thumbnail:

vidpeek thumbnail input.mp4 --out thumb.jpg --at 25% --width 640 --overwrite

Probe video metadata:

vidpeek probe input.mp4 --json

vidpeek input.mp4 \
  --out preview.webp \
  --preset web \
  --strategy evenly-spaced \
  --clips 5 \
  --clip-duration 2 \
  --width 320 \
  --fps 10 \
  --overwrite

Dry-run a preview plan without generating files:

vidpeek input.mp4 --out preview.webp --preset web --dry-run --json

Create a thumbnail from a percentage timestamp:

vidpeek thumbnail input.mp4 --out thumb.png --at 10% --height 360 --overwrite

Print readable metadata:

vidpeek probe input.mp4

import { generatePreview } from "vidpeek";

const result = await generatePreview({
  input: "video.mp4",
  output: "preview.webp",
  preset: "web",
  strategy: "evenly-spaced",
  clips: {
    count: 5,
    duration: 2,
  },
  width: 320,
  fps: 10,
  overwrite: true,
});

console.log(result.sizeBytes);

import { generateThumbnail } from "vidpeek";

await generateThumbnail({
  input: "video.mp4",
  output: "thumb.jpg",
  at: "25%",
  width: 640,
  overwrite: true,
});

import { probeVideo } from "vidpeek";

const metadata = await probeVideo("video.mp4");

console.log(metadata.duration);
console.log(metadata.width, metadata.height);
console.log(metadata.videoCodec);

import { dryRunPreview } from "vidpeek";

const plan = await dryRunPreview({
  input: "video.mp4",
  output: "preview.webp",
  preset: "web",
});

console.log(plan.segments);

Preview JSON:

{
  "output": "preview.webp",
  "format": "webp",
  "duration": 128.4,
  "segments": [{ "index": 0, "start": 6.42, "duration": 2 }],
  "elapsedMs": 1842,
  "sizeBytes": 384920
}

Thumbnail JSON:

{
  "output": "thumb.jpg",
  "at": 32.1,
  "elapsedMs": 312,
  "sizeBytes": 42188
}

Probe JSON:

{
  "duration": 128.4,
  "width": 1920,
  "height": 1080,
  "fps": 29.97,
  "videoCodec": "h264",
  "audioCodec": "aac",
  "format": "mov,mp4,m4a,3gp,3g2,mj2"
}

VidPeek does not replace existing output files unless you explicitly ask it to.

vidpeek input.mp4 --out preview.webp

If preview.webp already exists, this fails with a readable error. Use --overwrite to replace it:

vidpeek input.mp4 --out preview.webp --overwrite

The same behavior applies to thumbnails.

Place a sample video at benchmarks/fixtures/sample.mp4, then run:

pnpm bench

The benchmark generates tiny, web, and high-quality previews and prints elapsed time plus output file size.

Install FFmpeg and FFprobe, then verify both commands work:

ffmpeg -version
ffprobe -version

If they are not on PATH, pass custom binary paths:

vidpeek input.mp4 --out preview.webp --ffmpeg-path /path/to/ffmpeg --ffprobe-path /path/to/ffprobe

VidPeek expects a local file path. Use vidpeek probe input.mp4 --json first if you need to inspect metadata before preview generation.

Pass --overwrite when replacing files intentionally. Without it, VidPeek refuses to overwrite output.

Paths with spaces are supported because VidPeek calls FFmpeg with argument arrays:

vidpeek "benchmarks\fixtures\sample video.mp4" --out "output preview.webp" --preset web --overwrite

Parent output directories are created automatically:

vidpeek input.mp4 --out previews/preview.webp --overwrite

VidPeek outputs standard media files you can embed anywhere your app, README, dashboard, or pipeline already displays images and video. For a quick local demo, generate a WebP preview and a thumbnail:

vidpeek input.mp4 --out preview.webp --preset web --overwrite
vidpeek thumbnail input.mp4 --out thumb.jpg --at 25% --width 640 --overwrite

• Typed API for Node apps.
• CLI and library from the same core pipeline.
• Safe temp dirs.
• No shell command strings.
• Readable FFmpeg/FFprobe errors.
• Useful presets.
• JSON output for automation.

• Scene-change strategy.
• Contact sheets.
• Sprites.
• AVIF previews.
• Worker and concurrency options.

MIT