droboticflow-new/docs/transcoded-pts-pairing.md

2.1 KiB

Transcoded video / original-named PTS

The normalizer first matches <video-stem>_pts.csv. If absent, it resolves the original name within the same Capture, camera and part. The filename suffix alone is no longer an error.

Before using that fallback, normalization reads the actual files and requires:

  1. Valid strictly increasing positive integer timestamp_us values, at least two rows.
  2. A full ffprobe decode count equal to PTS row count, without decoder errors.
  3. Matching original segment frame count when a Capture meta file exists. There is no manual frame-order declaration gate. TRANSCODE_PRESERVES_FRAME_ORDER is no longer read; old true/false values have no effect.

Original device timestamps are never generated, rescaled or rewritten. Unequal counts, invalid timestamps, decoder errors and inconsistent meta remain blocking errors. Original/exact-name PTS follows the existing downstream validation path. Successful validation records count/timestamp checks only, not a claim that frame order was independently verified.

Deploy the updated normalizer image; no workflow flag is needed. Existing failed Runs are not automatically retried by an image update.

Meta records from multiple recordings

A meta file may contain several records with the same part index from different Captures. Resolve the selected stream record by Capture filename identity, camera side and part number, ignoring the video's transcoding suffix. When both file and pts_file are present, both must agree with that identity. Do not select the first record, sum counts, or borrow another Capture's frame count.

Legacy metadata with only index/count remains supported only when no record for that part provides file identity and exactly one record matches. Missing matches, duplicate matching identities, invalid frame counts and video/PTS/meta count mismatches remain errors. These conditions now have distinct error messages. This change never edits source metadata or timestamps, and does not automatically retry existing failed runs. It requires a normalizer image release; deploying the API/dashboard alone does not update the normalizer used by workflow jobs.