# Repository guidance

## Video analysis

When diagnosing render motion, transitions, timing, or visual artifacts, use
`scripts/analyze_video_frames.sh` instead of manually seeking through the video.

```bash
scripts/analyze_video_frames.sh VIDEO [OUTPUT_DIR] \
  --window START:DURATION [--window START:DURATION ...]
```

The script creates:

- timestamped overview contact sheets sampled at 2 fps;
- scene-change frames and a `scene-timestamps.txt` index;
- optional dense 10-fps contact sheets for specified transition windows.

Inspect the overview first, then request dense windows around transitions or artifacts. Sampling and
scene sensitivity can be adjusted with `OVERVIEW_FPS`, `WINDOW_FPS`, and `SCENE_THRESHOLD`.

The generated files are analysis artifacts and belong in `/tmp` or another requested output directory;
do not commit them to the repository.