# Design — enterprise-video-thumbnails

> Non-normative. Architecture, file layout, rationale.

## Architecture

The package is split into four feature modules under `src/`:

```text
packages/media/video/video-thumbnails/src/
  index.ts                          # package root barrel (named re-exports)
  error-codes/
    index.ts
    error-codes.ts                  # defineCodes("VIDEO_THUMBNAILS", [...])
    error-codes.md
  errors/
    index.ts
    video-thumbnails-error.ts       # VideoThumbnailsError extends SuaveplanError
    video-thumbnails-error.md
  schemas/
    index.ts
    schemas.ts                      # Zod schemas for every option type
    schemas.md
    schemas.types.ts                # inferred TS types
  telemetry/
    index.ts
    telemetry.ts                    # meter + counters/histograms factory
    telemetry.md
  runner/
    index.ts
    runner.ts                       # FfmpegRunner interface + helpers
    runner.md
    runner.types.ts
    fluent-ffmpeg-runner.ts         # default impl using fluent-ffmpeg + @ffmpeg-installer
    fluent-ffmpeg-runner.md
  thumbnail-generator/
    index.ts
    thumbnail-generator.ts          # ThumbnailGenerator class
    thumbnail-generator.md
    thumbnail-generator.types.ts
  sprite-sheet/
    index.ts
    sprite-sheet.ts                 # SpriteSheetGenerator class
    sprite-sheet.md
    sprite-sheet.types.ts
```

## Key types

```ts
interface FfmpegRunner {
  isAvailable(signal?: AbortSignal): Promise<boolean>;
  extract(input: ExtractInput, signal?: AbortSignal): Promise<void>;
  tile(input: TileInput, signal?: AbortSignal): Promise<void>;
  probe(inputPath: string, signal?: AbortSignal): Promise<ProbeResult>;
}

class ThumbnailGenerator {
  constructor(config: ThumbnailGeneratorConfig, runner?: FfmpegRunner);
  generate(input, options?, signal?): Promise<ThumbnailResult>;
  generateMultiple(input, timestamps, signal?): Promise<ThumbnailResult[]>;
  extractSlidingWindow(input, count, durationSeconds, signal?): Promise<ThumbnailResult[]>;
  getMetadata(input, signal?): Promise<VideoMetadata>;
  isAvailable(signal?): Promise<boolean>;
}

class SpriteSheetGenerator {
  constructor(config?: SpriteSheetConfig, runner?: FfmpegRunner);
  generate(input, outputPath, duration?, signal?): Promise<SpriteSheetResult>;
}
```

## Default runner

`FluentFfmpegRunner` wraps `fluent-ffmpeg`, pinning the binary to `require("@ffmpeg-installer/ffmpeg").path` so consumers do not need ffmpeg on PATH. `extract`, `tile`, `probe` translate the typed call into a fluent-ffmpeg chain and resolve when the command emits `end`/`error`. The runner registers an `abort` listener on the supplied `AbortSignal` and calls `command.kill("SIGKILL")` on trigger, rejecting with `VIDEO_THUMBNAILS.ABORTED`.

## Error model

All public methods throw `VideoThumbnailsError` (extends `SuaveplanError<VideoThumbnailsCode>`). Codes:

| Code | When raised |
|---|---|
| `VIDEO_THUMBNAILS.EXTRACT_FAILED` | ffmpeg exited non-zero on a single-frame extract or sprite render. |
| `VIDEO_THUMBNAILS.PROBE_FAILED` | ffprobe failed or produced unparseable JSON. |
| `VIDEO_THUMBNAILS.VIDEO_INVALID` | Probe succeeded but found no video stream or duration ≤ 0. |
| `VIDEO_THUMBNAILS.INVALID_TIMESTAMP` | Caller supplied a timestamp string that does not match `HH:MM:SS(.mmm)?`. |
| `VIDEO_THUMBNAILS.INVALID_DIMENSIONS` | Width or height ≤ 0, or `count` for sliding-window ≤ 0. |
| `VIDEO_THUMBNAILS.INVALID_OPTIONS` | Zod boundary validation failed for `ThumbnailConfig`/`ThumbnailOptions`/`SpriteSheetConfig`. |
| `VIDEO_THUMBNAILS.FORMAT_UNSUPPORTED` | Output format not in the supported set. |
| `VIDEO_THUMBNAILS.RUNNER_UNAVAILABLE` | `runner.isAvailable()` returned `false` and a guard was requested. |
| `VIDEO_THUMBNAILS.ABORTED` | `AbortSignal` triggered mid-operation. |

## Observability

A package-scoped meter (`@suaveplan/video-thumbnails`) emits:

- `video_thumbnails.extract.duration_ms` (histogram, attrs `{format, fit, outcome}`)
- `video_thumbnails.extract.total` (counter, attrs `{outcome, format}`)
- `video_thumbnails.sprite_sheet.duration_ms` (histogram, attrs `{outcome, format}`)
- `video_thumbnails.sprite_sheet.frames` (histogram, attrs `{format}`)

The meter is lazily fetched per call via `metrics.getMeter` so the package retains `sideEffects: false` and tree-shakes when callers do not import the generator entry.

## Testing strategy

A `tests/setup/fixtures.ts` helper synthesises a 5-second 320×240 colour-gradient MP4 once per worker using ffmpeg's `lavfi` source (`-f lavfi -i color=c=red:size=320x240:rate=10:duration=5`). The path is cached and reused across tests. Tests cover:

- Real single-frame extraction at 0s, mid, near-end for each format.
- `generateMultiple` over three timestamps.
- `extractSlidingWindow` returns exactly N evenly-spaced frames.
- `getMetadata` returns duration ≈ 5s, width 320, height 240, codec `h264`.
- Sprite sheet 3×3 generation against the same fixture.
- `AbortSignal` cancels mid-extract → `ABORTED`.
- Zod boundary rejects invalid options.
- Every error code is reachable from a real call site.

No mocks. ffmpeg binary is sourced from `@ffmpeg-installer/ffmpeg`.

## File layout vs. AGENTS rules

- All feature modules live under `src/<feature>/` (no flat `src/`-root impl files).
- Every `.ts` (except `index.ts`, `*.types.ts`, `*.test.ts`) has a sibling `.md`.
- Barrels are explicit named re-exports.
- Test files import from `@suaveplan/testing/runner`.
- No `biome-ignore`, no `export *`, no direct `vitest`/`bun:test` imports.