first commit

docs/media/video/video-thumbnails/README.md

@@ -0,0 +1,85 @@
+# @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
+