droboticflow/docs/transcoded-pts-pairing.md

31 lines
2.1 KiB
Markdown

# 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.