Skip to content

fix(preview): run VDecimate in the IVTC / Soft Telecine preview, in the encode's phase (task #46) - #206

Merged
StuartCameronCode merged 2 commits into
mainfrom
stuart/46-ivtc-soft-telecine-preview-shows-a-frame
Nov 16, 2026
Merged

StuartCameronCode merged 2 commits into
mainfrom
stuart/46-ivtc-soft-telecine-preview-shows-a-frame

Conversation

@StuartCameronCode

Copy link
Copy Markdown
Owner

Problem

With Deinterlace set to IVTC, or to Soft Telecine at 29.97/30 fps, the preview ran VFM but skipped VDecimate. ProcessingPipeline::preview_output still picked its frame as though the clip had been decimated, so the preview showed the film frame of source frame target - ceil(radius/5):

  • 1 frame early at radius 5, 3 frames early at radius 12;
  • only 22 of 135 previews showed the right frame;
  • with IVTC followed by a 59.94 Frame Rate pass, the preview converted the undecimated 29.97 clip, so it used the wrong ratio as well.

Fix

The preview now runs VDecimate itself, on a clip arranged the way the encode's clip is:

  • The window's frames before the in-point are dropped. For IVTC this happens before VFM.
  • Copies of the first frame go in front, e0 mod cycle of them, so VDecimate's cycles fall in the encode's phase.
  • The clip ends where the encode's clip ends. The preview job now carries endFrame; without it the worker takes totalFrames. For Soft Telecine the last cycle is filled the way pipe_frames fills it.

Which frame of the target's cycle VDecimate drops depends on the picture, so the worker computes the output index for both cases (DecimatePreview::after_drop). The script tags each frame with its index, reads the tag at the target's position, picks the matching index, and prints PREVIEW_DECIMATE:corr=N. The worker then reports the frame actually shown on PREVIEW_INFO.

Other changes:

  • FrameMap::Decimate now declares radius cycle + 1.
  • Stabilize's pitch lookup offset is now first + skip - pad.
  • The encode script is unchanged.

Report

docs/reports/issue-46-ivtc-preview/ holds:

  • the measurements before and after: 147 of 147 previews now show the encode's frame, with a mean absolute difference (MAD) of 0.00 on 8-bit sources;
  • a probe of VDecimate's rules in the bundled vivtc;
  • the scripts that produced every number.

It is linked from ENGINEERING_NOTES and the reports index. CLAUDE.md is updated ("Previewing every output frame", "One script template").

Testing

  • Rust unit tests:

    • a VDecimate model checks that the preview shows the frame the encode keeps, across cycles 4/5/6, Soft Telecine, in-points 0..7 and several end points;
    • a retime after decimation;
    • the radius;
    • the Stabilize offset;
    • the preview's end point.

    cargo test --lib: 591 passed.

  • Rust script-generation test: test_250 covers both methods. test_161, test_240 and test_248 are updated. filter_integration_test: 232 passed.

  • Heavy suite: the new integration_ivtc_preview_test.dart checks previews against a lossless encode and against independently regenerated film frames. It covers hard_telecine_test.avi, the 10-bit ProRes telecine clip, soft_telecine_test.mkv, several radii, trims, and IVTC followed by 59.94. The run also included frame mapping, source grid, seek alignment and high-bit-depth: 134 tests, all passing.

  • Limitation: everything was measured on Apple Silicon only, with synthetic 3:2 pulldown fixtures.

🤖 Generated with Claude Code

StuartCameronCode and others added 2 commits November 16, 2026 16:24
…he encode's phase (task #46)

The preview ran VFM without VDecimate while preview_output picked its frame
as if decimated (local * 4/5 of an undecimated window), so it showed the
film frame of source frame target - ceil(radius/5): one early at radius 5,
three at 12; 22 of 135 previews were the encode's frame. IVTC then a frame
rate conversion converted the undecimated 29.97 at the wrong ratio.

The preview now runs VDecimate on a clip arranged as the encode's: window
frames before the in-point dropped (before VFM for IVTC), copies of the
first frame putting the cycles in the encode's phase, and the clip ended
where the encode's ends (the app sends endFrame with a preview job; Soft
Telecine's last cycle filled as pipe_frames does). FrameMap::Decimate
declares radius cycle + 1. Each frame is tagged with its index; the script
reads which frame of the target's cycle was dropped and picks between the
two outputs preview_output_in computed. Stabilize's preview pitch lookup
follows the padded clip. 147 of 147 previews are now the encode's frame
(MAD 0.00 on 8-bit). Report: docs/reports/issue-46-ivtc-preview.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
#46)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@StuartCameronCode
StuartCameronCode force-pushed the stuart/46-ivtc-soft-telecine-preview-shows-a-frame branch from dc07b01 to d721207 Compare November 16, 2026 05:26
@StuartCameronCode
StuartCameronCode merged commit 27ece09 into main Nov 16, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant