feat: add --sample-frames N preview/sample mode

[shezmic]

Summary

• Adds --sample-frames N flag to run-inference. Picks N evenly-spaced frames across the clip timeline, runs full inference on those only, and writes output to Output/Sample/ — never mingles with a real render.
• _compute_sample_indices(n, total) helper: floating-point step, set deduplication for rounding ties, edge cases for n=1 and n≥total
• Normal sequential VideoCapture path is untouched — caps are only opened in normal mode; sample mode uses read_video_frame_at() for per-frame seeking (already existed in backend/frame_io.py)
• Output filenames use the actual source frame index (00125.exr not 00001.exr) for direct correlation back to the clip timeline
• Comp video stitch skipped in sample mode (non-sequential filenames break ffmpeg's %05d glob pattern); a log message explains this
• 222 tests pass (1 new: --sample-frames passthrough kwarg; 1 extended: help flag assertion)

Why it was needed

Running full inference on a 500-frame clip to validate despill or colorspace settings wastes significant time. --max-frames only covers the first N frames, missing midpoint/end conditions. Sample mode lets users validate settings quickly across the whole clip, then drop the flag for the full render.

How to verify

uv run pytest --tb=short -q
uv run corridorkey run-inference --help   # --sample-frames appears in output

Manual (with clips present):

# Processes frames 0, 125, 250, 375, 499 of a 500-frame clip
uv run corridorkey run-inference --sample-frames 5 --srgb --despill 5 --despeckle --refiner 1.0
# Output appears in ClipFolder/Output/Sample/ — main Output/ unchanged

---

Fix (added post-review)

Stitch guard inconsistency — clip_manager.py line 837

The output-dir redirect (line 652) and index computation (line 669) both guard with sample_frames is not None and sample_frames > 0. The stitch guard used only sample_frames is not None.

With --sample-frames 0 this caused all frames to run into Output/ (not Output/Sample/) while the video stitch was still skipped — silently producing an incomplete render in the main output directory rather than the sample subdirectory.

Fixed by aligning the stitch guard to sample_frames is not None and sample_frames > 0, making all three guards consistent. --sample-frames 0 now behaves identically to omitting the flag entirely (normal mode, stitch runs).

Commit: cc4d906

[nikopueringer]

If the user wants to sample fewer frames, I feel that they should implement that by simply exporting a sequence form their editing program that contains less frames.

Likewise, I don't think using the source file number for the output file number is necessarily a desired action. I'm sure for some power users it would be nice to maintain timecode through file name, but for most users I think they're going to find themselves with messy filenames, as opposed to a clean readable sequence.

I'm in favor of fewer, focused features, and a simpler code base, personally.

[shezmic]

That's a fair point — the NLE export workflow already handles this cleanly, and adding a sampling layer inside CorridorKey duplicates something the artist's editing software does better. The timecode-based filename concern is also valid; a clean sequential output is more predictable for most users.

Closing this one. Happy to keep contributing in areas that align with the simpler codebase direction.