86 lines
5.4 KiB
Markdown
86 lines
5.4 KiB
Markdown
# @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
|
||
|