@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

5.4 KiB Raw Blame History Unescape Escape