# @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`.

<!-- begin:auto-docs -->
## Documentation tree

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

## Install

```bash
bun add @suaveplan/video-thumbnails
```

## Quick start

```ts
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`](./src/error-codes/error-codes.md) — `VIDEO_THUMBNAILS_CODES` registry.
- [`errors/video-thumbnails-error`](./src/errors/video-thumbnails-error.md) — typed error class.
- [`schemas`](./src/schemas/schemas.md) — Zod schemas + format / fit constants.
- [`telemetry`](./src/telemetry/telemetry.md) — OTel counter + histograms.
- [`runner`](./src/runner/runner.md) — `FfmpegRunner` interface + filter helpers.
- [`runner/fluent-ffmpeg-runner`](./src/runner/fluent-ffmpeg-runner.md) — default runner.
- [`thumbnail-generator`](./src/thumbnail-generator/thumbnail-generator.md) — single-frame +
  batch + sliding-window extractor.
- [`sprite-sheet`](./src/sprite-sheet/sprite-sheet.md) — 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