Read a video's start time from its GPS clock, and tell whether creation_time marks the start or the end

[caglarpir]

The bug

A community report (Mapillary forum + FB group): a video recorded at 4.91 fps, paired with a GPX
of the same drive, comes out with its frames on the wrong part of the route. The same file + GPX
works in Google Street View.

The reporter described it as the frame rate being misread. It isn't — the container is parsed
correctly (mdhd timescale 15712, stts 3186 × 3200 → exactly 4.91 fps, and
mp4_sample_parser reproduces every composition time to the microsecond). What is wrong is
the video's start time, and since the frames are located along the GPX by their absolute
timestamps, getting that wrong moves all of them together.

Probe.extract_stream_start_time() returned creation_time - duration. For the reported file
(creation_time 2026-08-08T08:47:32Z, duration 648.879837s) that is 08:36:43.120Z, while the
GPX starts at 08:47:32Z — the creation time, to the second. Every sampled frame came out one
full video duration early, and the workflow the README documents fails outright:

$ mapillary_tools video_process VIDEO_DIR --geotag_source gpx \
      --geotag_source_path R0024681.gpx --video_sample_distance -1 --video_sample_interval 20
...
32 image read in total
        32 (81.0 MB) MapillaryOutsideGPXTrackError
MapillaryProcessError: Failed to process 32 files.

The hard failure is the lucky case. When the track does reach back far enough — a GPX covering
a drive that the camera split across several files — the frames from every file after the first
are silently placed one file-length back along the route. On this track that is up to ~1 km,
and the images end up bunched onto road they were not shot on, which is what the report
describes.

Where it came from

The subtraction was introduced in 644701c (Feb 2019). The comment it deleted says what it was
for:

# Blackvue actually reports endtime in the created_at exif field

It was a BlackVue workaround that later got generalised to every video. But neither reading is
right for every camera, and nothing in the file says which one applies. Checked against sample
videos, by comparing the creation time with the camera's own GPS clock or with the neighbouring
clips of the same drive:

• End of the recording: BlackVue, Viofo, Vantrue, AZDome and most other dashcams, the
  Ricoh Theta X and the Labpano PanoX V2.
• Start of the recording: Sony, Insta360, and the reported file. GoPro also writes the
  start, but in local time (Video Timestamping Bugs with GoPro MAX #819).

The fix

Resolve the start time in this order:

1. --video_start_time, if given (unchanged).
2. The video's own GPS clock, which is absolute UTC and so right for both BlackVue and
   GoPro: the median of the first 5 plausible GPS timestamps, each mapped back to the video's
   time 0. Timestamps before 2010 (a GoPro writes 2000-01-01 until its first fix) or more than
   a day in the future are skipped, and the median keeps a stale first fix (seen on the PanoX
   V2, seconds older than the rest) from shifting the result.
3. The container's creation_time, read as the start or the end of the recording by
   looking for evidence:
   • a camera known to stamp the end: BlackVue, detected by the free/gps and free/cprt
     boxes it writes whether or not it ever got a fix, and the Theta X and PanoX V2, by their
     make and model tags;
   • otherwise a date and time in the file name (20230106_150558_00422F.MP4,
     2023_0725_141524_103.MP4, …) that matches only one of creation_time and
     creation_time - duration, allowing for a whole UTC offset because cameras name files in
     local time;
   • otherwise the start, with a warning that prints the --video_start_time value to pass if
     the camera stamps the end.

A start-time source that fails (telemetry that does not parse, a malformed creation_time)
now falls through to the next one with a warning instead of failing the video.

Behaviour changes

• Start-stamping cameras without telemetry (the reported case, Sony, Insta360): frames are
  timestamped one duration later than before, which is when they were shot.
• End-stamping cameras without telemetry: unchanged when the camera model or the file name
  identifies them. The others now get the start reading, with the warning, where every camera
  used to get the end reading silently.
• GoPro / CAMM with interval sampling: frames are timestamped from the GPS clock. For the
  hero8.mp4 fixture that moves the first sample from 2019_11_18_15_41_12_354 (the camera's
  local RTC, minus the duration, labelled UTC) to 2019_11_18_23_42_08_539 (real UTC, matching
  the GPS positions written into the same frames). This is Video Timestamping Bugs with GoPro MAX #819 items 2 and 4.
• BlackVue: GPS point times were measured from the first valid fix instead of from the
  start of the recording. Until the receiver gets a fix the camera logs NMEA lines without
  positions, so every point was late by the time to first fix. They are now measured from the
  first NMEA line, which changes BlackVue point times wherever they are used, not only the
  start time. For most videos the two coincide; on 433 BlackVue sample videos, 7 took more than
  5 s to get a fix, the slowest 60 s.
• Distance-based sampling: frames at GPS points with an absolute timestamp still take their
  time from it. The start time is resolved, in the order above, only for frames without one, so
  a video without a usable creation time no longer fails when it does not need one. That includes
  every frame placed along a GPX, whose points carry their own time: since Honour --geotag_source in distance-based sampling #841 reads the GPX in
  distance sampling, such a video gets as far as the GPX instead of failing before it is read.

On top of #839 and #841

This was rebased once both had landed, rather than having them rebase onto it:

• The start time raises a plain MapillaryVideoError, which Fail the sample instead of silently producing no frames #839's sample summary reports with
  the other sampling errors.
• Fail the sample instead of silently producing no frames #839's test of an unreadable start time patched probe_video_start_time(), which this PR
  removes. It now covers interval sampling through _extract_video_start_time(), and distance
  sampling through a track without a GPS clock, which is the only case in which distance
  sampling looks the start time up.
• Honour --geotag_source in distance-based sampling #841's comment on why only --video_start_time places a GPX on a video without GPS gave
  creation_time - duration as the reason. It now says why that still holds: such a video would
  get its start time from its creation time, which cameras stamp at the start or the end of the
  recording, some in local time.

Verification

• The reported file (make/model RICOH / RICOH THETA Z1, which is not on the
  end-stamping list, and no date in its name) resolves to 08:47:32Z, the GPX start, and gets the
  warning. That is the start time the first revision of this PR used, with which
  video_process --geotag_source gpx --video_sample_distance -1 --video_sample_interval 2
  yielded 289 geotagged frames spanning 08:47:32 → 08:58:18, every one 0.0000 m from the GPX
  position at its true video time. Before: 0 frames, all rejected as outside the track.
• Interval sampling with a GPX, built from the camera's own track where it has one, on
  11 sample videos from 10 cameras:
  • Viofo A129 and AZDome GS63H: 119 and 57 frames geotagged, as on main. Reading every
    creation time as the start had dropped them to 1 and 0.
  • Sony FDR-X3000 with its converted GPX: 0 → 129 frames geotagged.
  • BlackVue DR900M-2CH: frames move from 5.2 s late to on time.
  • The samples whose camera clock is in local time or simply wrong fail the same way before
    and after; --video_start_time is the way out there.
• The full suite (946 passed, 18 skipped, 1 xfailed), ruff check, ruff format --check,
  usort diff and mypy (for Python 3.9, as CI checks) all pass.

Not addressed here

• process --video_geotag_source gpx still places a GPX at video time 0 on a video without GPS,
  so a GPX covering several video files is injected whole into each of them (Honour --geotag_source in distance-based sampling #841 lets
  video_process place it by --video_start_time instead). That is the documented limitation
  under "Limitations of --video_geotag_source" and is a separate change.