suaveplan/packages/media/video/video-thumbnails/README.md

@suaveplan/video-thumbnails - Video thumbnail extraction and sprite-sheet generation backed by an injectable FfmpegRunner (fluent-ffmpeg + @ffmpeg-installer by default).

Video thumbnail extraction and sprite-sheet generation backed by an injectable FfmpegRunner. The default runner — FluentFfmpegRunner — wraps fluent-ffmpeg and pins ffmpeg/ffprobe to the binaries shipped by @ffmpeg-installer/ffmpeg and @ffprobe-installer/ffprobe, so the package works on any host without requiring those binaries on PATH.

Documentation tree

• error-codes — VIDEO_THUMBNAILS_CODES is the stable, frozen registry of every failure mode raised by @suaveplan/video-thumbnails.…
  • error-codes — VIDEO_THUMBNAILS_CODES is the stable, frozen registry of every failure mode raised by @suaveplan/video-thumbnails.…
• errors — VideoThumbnailsError is the single error class raised by every public surface of @suaveplan/video-thumbnails. It ex…
  • video-thumbnails-error — VideoThumbnailsError is the single error class raised by every public surface of @suaveplan/video-thumbnails. It ex…
• runner — The runner module defines the FfmpegRunner interface plus a handful of pure helpers used by every implementation: `bu…
  • fluent-ffmpeg-runner — Default FfmpegRunner implementation used by ThumbnailGenerator and SpriteSheetGenerator when no other runner is i…
  • runner — The runner module defines the FfmpegRunner interface plus a handful of pure helpers used by every implementation: `bu…
• schemas — Defines every Zod schema and inferred TypeScript type that crosses the public boundary of @suaveplan/video-thumbnails…
  • schemas — Defines every Zod schema and inferred TypeScript type that crosses the public boundary of @suaveplan/video-thumbnails…
• sprite-sheet — SpriteSheetGenerator renders an N×M grid of thumbnails into a single image using ffmpeg's tile filter. A sprite she…
  • sprite-sheet — SpriteSheetGenerator renders an N×M grid of thumbnails into a single image using ffmpeg's tile filter. A sprite she…
• telemetry — Centralises the OpenTelemetry instruments owned by @suaveplan/video-thumbnails. A meter is acquired lazily — only whe…
  • telemetry — Centralises the OpenTelemetry instruments owned by @suaveplan/video-thumbnails. A meter is acquired lazily — only whe…
• thumbnail-generator — ThumbnailGenerator is the primary class consumers reach for to extract still frames from a video file. It accepts a Z…
  • thumbnail-generator — ThumbnailGenerator is the primary class consumers reach for to extract still frames from a video file. It accepts a Z…

Install

bun add @suaveplan/video-thumbnails

Quick start

import {
    ThumbnailGenerator,
    SpriteSheetGenerator,
} from "@suaveplan/video-thumbnails";

const thumb = new ThumbnailGenerator({ outputDir: "/tmp/thumbs" });
const result = await thumb.generate("/data/clip.mp4", { timestamp: "00:00:02" });
console.log(result.outputPath, result.sizeBytes);

const sprite = new SpriteSheetGenerator({ columns: 5, rows: 5, interval: 2 });
const sheet = await sprite.generate("/data/clip.mp4", "/tmp/sprite.jpg");
console.log(sheet.frameCount, sheet.width, sheet.height);

Features

• Single-frame extract, multi-timestamp batch, sliding-window sampling.
• Sprite-sheet generation via ffmpeg's tile filter with auto-duration detection.
• jpeg / png / webp output for thumbnails; jpeg / png for sprite sheets.
• Zod-validated boundaries — INVALID_DIMENSIONS, INVALID_TIMESTAMP, FORMAT_UNSUPPORTED, INVALID_OPTIONS are typed failures.
• AbortSignal propagation kills the underlying ffmpeg child process and raises ABORTED.
• OTel: one counter and three histograms keyed by outcome, format, fit.

Modules

• error-codes — VIDEO_THUMBNAILS_CODES registry.
• errors/video-thumbnails-error — typed error class.
• schemas — Zod schemas + format / fit constants.
• telemetry — OTel counter + histograms.
• runner — FfmpegRunner interface + filter helpers.
• runner/fluent-ffmpeg-runner — default runner.
• thumbnail-generator — single-frame + batch + sliding-window extractor.
• sprite-sheet — N×M sprite-sheet generator.

Error codes

VIDEO_THUMBNAILS.EXTRACT_FAILED, VIDEO_THUMBNAILS.PROBE_FAILED, VIDEO_THUMBNAILS.VIDEO_INVALID, VIDEO_THUMBNAILS.INVALID_TIMESTAMP, VIDEO_THUMBNAILS.INVALID_DIMENSIONS, VIDEO_THUMBNAILS.INVALID_OPTIONS, VIDEO_THUMBNAILS.FORMAT_UNSUPPORTED, VIDEO_THUMBNAILS.RUNNER_UNAVAILABLE, VIDEO_THUMBNAILS.ABORTED.

License

MIT