Thumbnail output

Generate immutable local JPEG previews from verified H.264 IDR pictures on local SRT push and managed source-pull streams. Cascade input, cascade serving, outbound target-push and closed VOD do not start this branch. The interval is a target on the normalized 90 kHz media timeline: the first eligible IDR after it becomes due is selected.

"thumbnails": {
  "enabled": true,
  "interval": "10s",
  "resize": {
    "width": 400,
    "height": 225
  },
  "sessionMaxBytes": 1073741824,
  "sessionMaxArtifacts": 10000,
  "retention": "0s",
  "ffmpegPath": "ffmpeg",
  "maxWorkers": 4
}

Omit resize to preserve the SPS display dimensions exactly. When resize is present, both positive dimensions are required and the JPEG is exactly that width and height. There is no implicit aspect-ratio preservation, crop policy or prohibition on scaling up or down. Input and output dimensions must fit within 1920 by 1080 and 2,073,600 pixels.

The feature can run while HLS and recording are disabled. It still requires output.root and the viewer-facing output.http.listener. Producing thumbnails requires local push or managed pull input. A cascade-only node accepts output.thumbnails.enabled: true with publication disabled, but builds no thumbnail runtime and performs no thumbnail FFmpeg probe. Each eligible stream instance reserves an independent output.root/thumbnails/YYYY/MM/DD/{encoded-streamId}/{HHmmssSSS}[~NNN]/ session. JPEG names use {ordinal12}-{pts20}.jpg; thumbnail sessions do not share identity or ownership with vod/ recording sessions.

The defaults allow 1 GiB and 10,000 committed JPEGs per session. Configurable limits are 4 MiB through 1 TiB and 1 through 10,000,000 artifacts. Decoder admission is process-wide, defaults to four workers and has no waiting queue. A candidate is dropped when no worker or storage budget is immediately available, so this branch cannot build a frame backlog or block the media path.

Each JPEG becomes visible only after bounded write, file sync, close and atomic rename; the parent directory is then synced for crash durability. Startup recovery scans only the canonical thumbnails/ tree, removes process-owned incomplete temporary state, rebuilds committed byte and artifact accounting and conservatively closes a session left open by a crash. It does not use recording metadata.

retention defaults to 0s, which disables deletion. A positive duration can remove only a durably closed thumbnail session as one whole-root tombstone operation. With publication enabled, the session must also satisfy its own publication closure. It never targets vod/.

Stream close freezes selector and storage admission before finalization. A late decoder result cannot commit after that boundary. A caller deadline may let Close return before an uninterruptible filesystem sync finishes, but Drained is not reached until the inner output, selector and session finalizer have all returned. Session reservation, decoder or persistence failure degrades only that stream's thumbnail branch; local ingest, HLS and recording continue.

The example above is local-only. Set output.thumbnails.publish to true and configure the shared output.s3 destination to publish committed JPEGs. Public thumbnail metrics and status fields are not shipped yet; they remain issue #579 scope.

Use the shared output settings with this module. The complete field reference covers every accepted option; the maximal composition shows how modules fit together.