[SteveYu000]

Preserve source clocks and VFR range-end coverage

This is the source-clock/VFR part split from #10, independently based on
v0.8.39. Related independent changes: SAR #11 and AV1/MP4 #12.

The original combined patch made a kept picture at 37.996 s last only 4 ms
before OUT at 38 s. This change retains the existing coded-length floor at
the end of a normal range, while using measured coverage at seams inside
the range. On the reviewer's exact default-mode command, the first range's
last picture now lasts 41.708333 ms in MP4 and 42 ms in MKV. All displayed
timestamps are checked, not just successful decoding.

Changes

• Refine only progressive non-TS sources that vary, or whose nominal frame
  period is not an integer number of source ticks. Leave ordinary CFR grids
  and their original timescales unchanged, including avoiding unnecessary
  fraction reduction. Keep the existing integer/time-step bounds.
• Detect repeated 40/40/80 ms holds against typical positive gaps as well as
  the average. For unclassified progressive B-frame sources averaging over
  1% below their declared rate, decline the decode-time-only container index
  so default auto scans presentation timestamps. This adds a sequential
  read for those sources; ordinary CFR still uses the table.
• Distinguish an internal segment seam from the end of a keep-range.
  Preserve existing coded_length_unbounded behavior for genuine holds.
  Account for the CFR planner's coarse-clock selection margin using measured
  next-picture coverage, including copy coverage from the terminating point.
• Keep the latest displayed picture writable at the final tail on a refined
  clock. The new tests found another short tail: three B pictures followed
  a copied H.264 P picture although has_b_frames was two, so the P picture
  had already been written when its final hold was known. The output ended
  about 27 ms early. This path uses the existing 256 MiB buffer limit and
  reports an error if it is exceeded.
• Bump seek-cache version 18 to 19 so previous CFR classifications are not
  reused. Add an 80-case real-media suite and a technical description.

There are no SAR, AV1 configuration-policy, M2TS arrival-clock, dependency or
audio/subtitle strategy changes. Japanese documentation is left to you as
offered in the review.

Validation actually run

Windows x64 / MSVC / Rust 1.98 / FFmpeg 7.1.1 shared SDK. Both the unmodified
v0.8.39 baseline and this CLI were compiled locally.

• New fixed-input suite: 45/80 baseline → 80/80 here, using identical
  input SHA-256 values and the same final test script. It covers AVC, HEVC,
  AV1, MP4/MKV, repeated holds, CFR, single/multiple ranges, aligned copies,
  one-picture cuts, whole inputs, and ranges ending/lying inside long holds.
• The reviewer's unchanged 90 s / 1280×720 generator and both --keep
  arguments were run. The old Preserve source clocks, AV1 descriptions and M2TS arrival timestamps #10 executable reproduces 4 ms in both
  containers; this change gives 41.708333 / 42 ms, with 794 pictures.
  Single-range versions were checked too.
• Checks include normal strict decoding, picture counts, every display PTS,
  DTS ordering, movie/video-track duration, copied VCL bytes and pixels.
  Repeated parameter-set NAL units are recorded separately from VCL changes.
• 20 ordinary CFR MP4 outputs are byte-identical to the newly built
  baseline. Another 10 CFR MKV controls retain packet timing, payload and
  configuration (their generated SegmentUIDs are not compared as file identity).
• Historical fixed-input matrix: 140/235 → 165/235, 25 improvements,
  no newly failing cases. All 35 TS and 35 M2TS files are byte-identical
  to v0.8.39. The remaining failures include the other split changes and the
  existing TS/M2TS final-display-duration limitation.
• Existing VFR suite: 8/8. Rust workspace: 574 passed, 4 filtered;
  the four are the already reproduced Windows-specific baseline failures
  listed below. Clippy exits 0 with existing warnings only.
• A real v18 cache made by the baseline is rebuilt as v19; reopening v19
  produces the same output file as the rebuilding run.

Filtered existing Windows tests: input::tests::a_file_url_is_the_file_it_names,
udfw::tests::an_image_being_written_by_another_run_is_left_to_it,
udfw::tests::an_image_inside_its_own_folder_is_refused, and
vobsub::tests::names_follow_the_whole_cut_name.

Limits and test details

The review regression is tested with its original default auto indexing.
The synthetic input also contains duplicate timestamps and very short gaps.
With a separately forced --index scan, both v0.8.39 and this branch retain
the existing unbounded-hold behavior: 796 pictures rather than the default
794, and an approximately 4 ms range boundary. This pre-existing variant is
not claimed fixed here. The change avoids reinterpreting that hold policy
as part of the source-clock fix.

The FFmpeg 7.1 synthetic B-frame VFR generator can write an edit list ending
at the final generated PTS. Only the reference pixel decoder uses
ignore_editlist=1 to read all generated packets; outputs must decode normally
and meet their independent count/end checks. Matroska stores no DTS; equal
inferred DTS on the millisecond clock are recorded, while backwards ones
fail. MP4 DTS must strictly increase.

The suite checks timing/copying, not AV1 container-configuration compliance.
No Linux CI, GUI or hardware-player result is claimed. Extreme clocks that
cannot fit the existing 32-bit bounds retain the old bounded grid.

cargo build --release --locked --manifest-path rust/Cargo.toml -p smartcut-cli
bash tests/run_source_clock_tests.sh
bash tests/run_vfr_tests.sh

The new suite writes complete commands, input/binary/script hashes and results
to a fresh directory. Pass --fixtures <previous-run>/fixtures to compare
another executable against exactly the same input bytes.

[DeepRegular]

Thank you for splitting this out and for fixing the 4 ms case. I built c3afb99 on Linux (Debian 13, FFmpeg 7.1) and compared it with v0.8.39.

Confirmed

• My reproducer: the picture before the seam now lasts 41–42 ms in both MP4 and MKV, as in v0.8.39, and every picture is identical (792 of 792). There are no steps under 10 ms anywhere in the output.
• tests/source_clock_tests.py: v0.8.39 45/80, this branch 80/80 on the same fixtures. run_vfr_tests.sh 8/8, workspace unit tests and clippy pass (same warnings as main).
• The web-distributed 23.976 H.264 MP4 where I first saw the 4 ms gap: the source steps are 41/42 ms, and this branch's output contains only 41/42 ms steps, while v0.8.39 had 40.40/41.06/42.36 ms. That is a real improvement.
• Byte-identical to v0.8.39: broadcast .ts, .m2ts and --bdav output, VC-1 .m2ts, CFR H.264 MP4, and four phone VFR recordings (two H.264, two HEVC).
• It merges onto current main (with Preserve container sample aspect ratio through smart rendering #11) with one trivial conflict in tests/ci.sh; I checked the combined build and both fixes still hold.

One request: please leave constant-rate sources on their nominal grid

needs_source_clock also refines a constant-rate source whose frame period is not a whole number of ticks. A common case is a 29.97 VP9 .mkv on a 1 ms clock cut to .mp4. v0.8.39 writes exact 1001/30000 steps (avg_frame_rate=30000/1001). This branch copies the 33/34 ms rounding of the source clock instead, so the output reports avg_frame_rate=339625/11332 and some tools then treat it as variable-rate. For a CFR source those milliseconds are rounding, not timing, so I think its output should stay CFR. Could the refinement be limited to sources classified as variable rate? As far as I can see, all of the cases this PR fixes (the review file, the 40/40/80 holds and the web 23.976 file) are classified as variable, so it should not affect them.

Two smaller points

• Writer::queue: when the held pictures exceed HELD_AT_MOST, the whole cut now fails. I'd rather fall back to emit_one() as before (and the shorter hold) than refuse the cut.
• ContainerIndex now declines the seek table for B-frame sources more than 1% below their declared rate, which means a full packet scan when such a file is opened. That is fine with me, but please mention it in source-clock.md so the extra time on a large file is not a surprise.

I'll write the Japanese counterpart of source-clock.md myself once this is in.