[caglarpir]

Problem

A timelapse packs several seconds of capture into each second of video. Without a GPS clock of its own, nothing in the video tells how many, and its GPX is laid out at 1x, so the frames get only the start of the track. An Insta360 ONE X timelapse stitched by Insta360 Studio (1.8 s of video, 110 s GPX) gives 1 frame with --interpolation_use_gpx_start_time, the option the current error suggests.

Changes

• --video_duration_ratio (real seconds per video second) used to apply to interval sampling only, and was marked deprecated. It now also paces the GPX of a video without a GPS clock in distance sampling, however the GPX is placed: by --video_start_time, by --interpolation_use_gpx_start_time, or by assuming it starts with the video. A video's own GPS clock still wins, and logs a warning when it overrides a given ratio.
• The ratio is required where a track runs on long after the video and nothing else accounts for it:
  • Without a start time, a track more than twice as long as the video was already refused. It is now measured against the time the video spans at the ratio, and the error names the ratio.
  • With --interpolation_use_gpx_start_time, such a track is now refused too (MapillaryGPXVideoStartUnknownError), in interval sampling as well. Interval sampling checks it only for a video that GPX sync reads no GPS clock from: GPS rejected as noise still has one, which the GPX is synced at the pace of. The error suggests the ratio for a timelapse. For a track of less than a day, which may be a GPS logger left running after the video, it prints the start of the track to pass as --video_start_time instead, which places the video the same way. A longer track is a log of several trips, so the error only asks for the time the video started: for a dashcam clip with a 208-day GPX, the start of the track would put it on a drive 9 months earlier.
  • With --video_start_time, nothing is required, so one GPX can serve many videos.
• A ratio that isn't positive is rejected as a bad parameter (it now divides GPS time; 0 used to raise ZeroDivisionError).
• process is unchanged.

Behaviour change

--interpolation_use_gpx_start_time with a GPX more than twice as long as a video without a GPS clock used to be accepted, with the frames along the start of the track. That includes a GPS logger left running after the video. It is now refused, and the error prints the --video_start_time to use instead: for the 5.76 s sample-5s.mp4 with a 60 s GPX, pasting it gives the same 18 frames that main gives. The integration test for the README's example now uses a GPX that ends with the video, and a new one checks the refusal.

Verification

The ONE X timelapse with its GPX:

	main	this PR
distance, --interpolation_use_gpx_start_time	1 frame	refused
same, --video_duration_ratio 60	1 frame	33 frames over 129 m
distance, --video_start_time, --video_duration_ratio 60	1 frame	33 frames over 129 m
interval, --interpolation_use_gpx_start_time	10 frames, 8 duplicates, over 1 m	refused
interval, same, --video_duration_ratio 60	18 frames over 131 m	the same

A 1.24 s GoPro MAX 2 clip whose GPS is rejected as noise, with a 12x GPS clock and a 12 s GPX, sampled by interval with --interpolation_use_gpx_start_time: the same 2 frames as main.

Normal-speed videos (GoPro HERO7 and HERO8, BlackVue, Insta360 Pro) give output identical to main. Unit: 937 passed, 18 skipped, 1 xfailed. Integration: 70 passed. Doctests, mypy, ruff check, ruff format --check and usort diff are clean.

With #851: VideoSyncOption keeps start_time and duration_ratio, and the interval check reads use_gpx_start_time from each GPX source's interpolation, passing it on to GPXVideoExtractor.