​

render-node contract: preview slice + contact sheet

1. outputSlice hardening (framelane-api task #4) — render a sub-window faithfully.
2. The contactSheet directive (task #10) — render N sampled frames and tile them into one grid PNG.

​

Ground rule: preview == export

​

Where these appear in the payload

"params": {
  "uuid": "render_01J...",
  "renderType": "project",
  "version": "v4",
  "outputWidth": 480,          // already downscaled for a frame/window preview
  "outputHeight": 270,
  "outputDuration": 30.0,      // full timeline length (unchanged)
  "outputFormat": "mp4",
  "exportSettings": { "fps": 30, "fpsLimit": 30, ... },  // previews pin `fps`: engine renders at EXACTLY this

  // preview-only, injected by framelane-api:
  "outputSliceStart": 4.0,     // seconds, absolute timeline (optional)
  "outputSliceEnd":   4.0333,  // seconds, absolute timeline (optional)
  "contactSheet": { ... }      // present only for a contact-sheet preview
}

​

Part A — outputSlice (task #4)

• a single frame: [t, t + 1/fps], with t snapped to the frame grid;
• a window clip: [t0, t1], audio trimmed and muxed as today.

• end > start and start >= 0 are enforced at request-parse time (a schema validator on the window field, before any preview logic runs).
• A window whose start is at/after the timeline is explicitly rejected with a 422 before dispatch (_guard_window in api/routers/preview.py).
• A window’s end (or a single-frame at) that overshoots the timeline is never rejected — it is silently clamped down to outputDuration (window_slice/frame_slice in api/services/preview_service.py). So the slice render-node receives is always well-formed, but may be narrower than what an agent originally asked for.

1. Zero-width guard. Reject end <= start with a clear error instead of a divide-by-zero in the frame counter (per the earlier main review, src/RenderNodeLib/frame_counter.cpp; confirm against current main). A preview must never crash the worker on a degenerate slice.
2. Non-zero start / decode offset. A slice with start > 0 must seek or adjust the source streams so mid-timeline frames decode correctly (IgnoreOrAdjustStreamForSlice path). No production caller exercises start > 0 today, so this needs an explicit e2e test.
3. Fidelity. A frame produced from a slice must be pixel-identical to the same frame of the full render (see “preview == export”).

​

Part A acceptance tests

• Slice [t, t + 1/fps] produces exactly one frame; [t0, t1] produces only that window with audio.
• end <= start is rejected with an error, not a crash.
• A slice with start > 0 decodes the correct frames (not an offset/garbage frame).
• A sliced frame is byte-identical to the same frame extracted from a full render at the same timestamp and resolution.

​

Part B — contactSheet directive (task #10)

"contactSheet": {
  "frames":     [0.0, 2.2333, 4.0, 6.0, 9.9667],  // absolute timeline seconds, ascending, frame-snapped
  "columns":    4,
  "rows":       2,
  "cellWidth":  480,        // even; already downscaled from the canvas, aspect-correct
  "cellHeight": 270,        // even
  "labels":     ["0:00 first_frame", "0:02 uniform", "0:04 element_start", "0:06 element_start", "0:09 last_frame"]
}

• frames is authoritative for which frames appear and in what order. Each is an absolute timeline second, already snapped to the frame grid, so round(t*fps) is exact. Render each faithfully (same engine, “preview == export”).
• columns / rows give the grid. len(frames) <= columns*rows; fill row-major from index 0, leaving trailing cells blank if the last row is short. framelane-api now rounds its cell budget to a count that tiles the grid exactly, so in practice len(frames) == columns*rows — but keep this an inequality: a caller can still pin a columns wider than the tier budget can fill, and that is the one case that leaves a short last row. Blank cells should be painted with the sheet background, not left at the zeroed buffer: an opaque-black slot is indistinguishable from a legitimately black frame.
• cellWidth / cellHeight are the per-cell pixel size (even, aspect-correct vs the canvas). Downscale each rendered frame to exactly this. Note: on a contact-sheet job outputWidth/outputHeight stay the full canvas (unlike a frame/window preview); cellWidth/cellHeight govern each cell, and the final PNG is columns*cellWidth by rows*cellHeight.
• labels is parallel to frames (same length, same order): a short "m:ss reason" caption. Burning it into each cell (small, legible, corner) is recommended so the agent maps a cell to a timeline moment and knows why it was sampled. If you cannot burn text, ignore it (framelane-api also returns the labels in the API response). Inset the caption from the cell edge — today it is flush, and the glyph tops read as clipped (see below).

​

Label inset (defect on current main)

const int scale  = std::max(1, mCellWidth / 240);   // line 103
const int glyphH = 8 * scale;                       // line 105
const int pad    = scale;                           // line 106  <-- too small
const int barH   = std::min(mCellHeight, glyphH + 2 * pad);
// contrast bar is filled from (x0, y0) — the exact cell corner
int       penX   = x0 + pad;                        // line 121
const int penY   = y0 + pad;                        // line 122

​

Output

• The artifact is a single PNG, columns*cellWidth by rows*cellHeight (plus any label gutter you add). Emit it regardless of params.outputFormat; the engine emits mp4/webm today, so the grid PNG is a new still/grid output path.
• Report the completed artifact path (ending .png) through the existing render-events callback exactly like a normal render. framelane-api stores it as the job output and serves it via the signed-download endpoint; no new callback fields are needed. The job is is_preview (framelane-api excludes it from billing and the renders list); render-node treats it like any render.

​

Do not drop or reorder cells (positional sync)

​

Forward-compatibility (important)

​

Part B acceptance tests

• A directive with N frames yields one PNG with N cells laid out columnsxrows, row-major, in frames order, each cellWidthxcellHeight.
• Each cell equals the same-timestamp frame of a full render downscaled to the cell size (preview == export, per cell).
• Labels (if burned) match labels[i] for cell i, and no lit glyph pixel falls within glyphH / 2 of the cell’s top or left edge (8 px at the 480 px default cell) — or the caption sits in a dedicated gutter outside the frame image.
• An absent contactSheet key renders normally; an unknown key does not crash.

​

Delivery + references (confirm against current main)

• The zero-width slice guard (Part A) lives in JSON parsing, not frame_counter.cpp as an earlier draft of this doc said — confirm current location against main before relying on either pointer.
• graph.cpp:149-156 — outputSlice to FrameCounter window (Part A).
• The grid PNG is a new still/grid output path (the engine emits mp4/webm today); it belongs wherever render-node composes and encodes output, not a fixed file cited here.

​

Emit side (framelane-api, already implemented)

​

HTTP surface

• POST /v1/preview — the composition is inline, as render_request in the body.
• POST /v1/projects/{project_id}/preview — no render_request; the composition is the stored project’s current head (ProjectService.head_request, api/services/project_service.py). 404s if the project doesn’t exist in the workspace. Note: this “project” (api/models/project.py, a stored/versioned composition with its own CRUD + patch-ops API, new alongside preview) is an unrelated concept to the payload’s params.renderType == "project" discriminator described at the top of this doc — same word, different thing. The stored-project CRUD surface is otherwise out of scope here.

{
  "render_request": { /* RenderRequest — only on POST /v1/preview */ },
  "at": 2.0,                              // seconds; single-frame preview
  "window": { "from": 4.0, "to": 6.0 },   // OR at, not both
  "contact_sheet": { "detail": "balanced", "columns": 4, "max_cells": 16 }, // OR at
  "width": 480,                           // 16-3840; downscale target, height derives from aspect
  "dry_run": false,                       // true = validate only, no job
  "target_duration_sec": 30.0,
  "target_tolerance_sec": 0.5
}

{
  "kind": "frame",       // "validation" (dry-run) | "frame" | "window" | "contact_sheet"
  "ok": true,             // false iff any error-severity violation
  "violations": [ { "code": "DANGLING_TRANSITION", "message": "...", "severity": "error", "path": "transitions[0]" } ],
  "job": { "id": "render_...", "is_preview": true, "status": "queued", "..." : "..." }, // null on dry_run
  "sheet": { "columns": 4, "rows": 1, "width": 480, "window": { "from": 0, "to": 10 }, "cells": [ { "index": 0, "at": 0.0, "reason": "first_frame" } ] } // present iff contact_sheet requested (including dry_run)
}

​

Validation & error shapes

• Schema-level (window.to <= window.from, at+window both set, a field out of range): {"code": "invalid_request", "message": "Request validation failed.", "details": {"errors": [...]}}.
• Application-level (raise_validation, api/routers/_helpers.py — the window-past-duration guard, unresolved media, a translator/preflight failure): {"code": <ErrorCode>, "message": <specific message>, "details": {...}}.

​

is_preview, billing, and listing

• btree index ix_jobs_is_preview) is the only discriminator between a preview and a billable render — both share kind = RENDER and the render_ id prefix, and run through the identical translate → preflight → CDN-rewrite → queue pipeline (create_preview_render calls the same payload builder as a full render, then narrows it with apply_preview_slice/apply_contact_sheet before publishing). Three places branch on it:

• JobService.list(..., exclude_preview=True) (the default) filters Job.is_preview.is_(False); GET /v1/renders never overrides it, so previews never appear in the list.
• JobService.get() does not filter on is_preview — GET /v1/renders/{id} can still poll a preview job, which is what makes “polls via GET /v1/renders/{id}” below true.
• GET /v1/workspace/usage (api/routers/workspace.py) filters Job.is_preview.is_(False) on both the render_minutes and egress_bytes aggregates, so previews are excluded from billed usage too. output_path is always populated on completion; output_duration/output_size_bytes are only as good as whatever renderData the completion callback carries (see _apply_complete, api/workers/event_drainer.py) — for a video/window preview that should match a real render, but a contact-sheet (PNG) completion likely omits duration (and maybe sizeBytes) if render-node’s metadata probe is video-only; confirm against current main before assuming those fields are set for a contact-sheet job.

​

Contact-sheet sampling (api/services/contact_sheet.py, plan_contact_sheet)

1. Budget — max(1, min(round(window_seconds), tier_cap, max_cells, max_frames_in_window)), floored at MIN_CELLS = 4. Tier caps by detail: overview = 9, balanced = 16 (default), detailed = 36; the request’s max_cells (1–64) can only lower it further. max_frames_in_window is the count of frames in [window_start, last_renderable_frame] — the frames the anchors and the uniform fill actually sample from. The budget is then snapped to a count that tiles a whole grid (see step 5), rounding up when a full count fits under the ceiling and down otherwise.
2. Anchors — always first_frame (window start) and last_frame (last renderable frame in-window); plus every visible element’s start (element_start), each transition’s entering-element boundary (transition), and each caption’s first-word start on a text/countdown element (caption).
3. Dedup — anchors landing on the same frame keep the highest-priority reason: first_frame > {element_start, transition, caption} > last_frame > uniform.
4. Reconciliation — too many anchors → evenly subsampled (always keeps the first and last); too few → uniform-filled (reason: "uniform") up to budget.
5. Grid — columns = request.columns or ceil(sqrt(n)), rows = ceil(n / columns). Because the budget in step 1 was snapped to a count this formula tiles exactly — one of 1, 2, 4, 6, 9, 12, 16, 20, 25, 30, 36, 42, 49, 56, 64, or a multiple of a pinned columns — len(frames) == columns*rows and the sheet has no blank cells. Rounding up is free: ceil(sqrt(n)) and ceil(n/columns) are unchanged by the snap, so the grid shape, the PNG’s pixel size and the sampled span are the same as before; the added cells are uniform samples filling slots the grid already had (a 5s clip yields 6 cells in the same 3x2, not 5 with a hole). The one exception is a pinned columns wider than any count the budget ceiling admits (e.g. columns: 12 with detail: "overview"), which is honoured as asked and leaves a short last row.

​

File map

• api/routers/preview.py — POST /v1/preview; run_preview (shared orchestration: media resolution → _guard_window → dry-run/dispatch branch → contact-sheet planning), _guard_window, _resolve_media, _run_contact_sheet.
• api/routers/projects.py — POST /v1/projects/{project_id}/preview, delegating to the same run_preview.
• api/schemas/preview.py — the wire contract: PreviewRequest, PreviewOptions, PreviewWindow, ContactSheetOptions, ContactSheetPlan, ContactSheetCell, SampleReason, PreviewResponse.
• api/schemas/validation.py — Violation, Severity, ValidationResult.
• api/services/preview_service.py — frame_slice, window_slice, scaled_dims (pure slice/scale math), apply_preview_slice, apply_contact_sheet (payload mutators), PreviewService.validate / build_preview_payload.
• api/services/contact_sheet.py — plan_contact_sheet, the sampling planner.
• api/services/invariants.py — check_invariants, the free linter behind dry_run / violations.
• api/services/job_service.py — create_preview_render; JobService.list’s exclude_preview filter.
• api/models/job.py, alembic/versions/0008_jobs_is_preview.py — Job.is_preview.
• api/routers/workspace.py — usage-endpoint is_preview exclusion.