Deterministic video comparison pipeline: frame selection, HDR→SDR tonemapping, overlays/reports, and publishable outputs.

• What it does
• Key ideas
• Requirements
• Install
• Quick start
• Documentation
• Quality & verification
• Releases & versioning
• Contributing
• Security
• License

Frame Compare helps you produce consistent, reviewable comparisons between encodes:

• Selects representative frames deterministically (including seeded randomness where required).
• Renders PNGs with overlays and stable naming.
• Produces machine-readable outputs for automation (reports/metadata) and human-readable outputs for review.
• Supports “offline-first” workflows, with optional publishing integrations.

If you want the spec-driven rebuild plan and workflow, start here:

• docs/OPUS_REBUILD_FRAME_COMPARE/00-executive-summary.md
• docs/OPUS_REBUILD_FRAME_COMPARE/11-agent-workflow.md

Frame Compare is designed so the same inputs produce the same outputs:

• Stable sorting rules and explicit seeds.
• “No guessing” contracts for CLI/config where ambiguity would cause churn.
• Reproducible verification gates.

Canonical truth is stored as YAML/JSON contracts, with generated derived views:

• Canonical: docs/OPUS_REBUILD_FRAME_COMPARE/contracts/
• Derived views generator: scripts/generate_contract_views.py
• Readiness gate SSOT: docs/OPUS_REBUILD_FRAME_COMPARE/contracts/readiness_gates.json

This repo includes an operator-minimal, file-based run system for phased implementation:

• Run artifacts live under .agent-workflow/runs/<RUN_ID>/
• Each artifact ends with a ## NEXT AGENT PROMPT (COPY/PASTE) block for deterministic handoffs

See: docs/OPUS_REBUILD_FRAME_COMPARE/11-agent-workflow.md

• Python 3.13+
• uv (recommended) or pip
• FFmpeg available on PATH (for probing and fallbacks)
• Optional: VapourSynth runtime and plugins (for the primary renderer path)

uv sync --group dev --frozen

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"

This README is a high-level overview. The authoritative runbook and CLI surface are documented in the OPUS rebuild docs.

• Start here: docs/OPUS_REBUILD_FRAME_COMPARE/00-executive-summary.md
• Workflow and gates: docs/OPUS_REBUILD_FRAME_COMPARE/11-agent-workflow.md

./scripts/check-all-gates.sh

Or, to rerun and sync gate timestamps in AI_READINESS_ROADMAP.md:

bash scripts/reverify_ai_readiness.sh --update-roadmap

• Executive overview: docs/OPUS_REBUILD_FRAME_COMPARE/00-executive-summary.md
• Multi-agent workflow (SSOT): docs/OPUS_REBUILD_FRAME_COMPARE/11-agent-workflow.md
• Master checklist: docs/OPUS_REBUILD_FRAME_COMPARE/10-agent-master-checklist.md

• docs/OPUS_REBUILD_FRAME_COMPARE/contracts/README.md
• docs/OPUS_REBUILD_FRAME_COMPARE/contracts/readiness_gates.json

This repo uses two lanes to keep commands deterministic:

1. Repo scripts/validators: uv run --no-sync with workspace cache

UV_CACHE_DIR=./.uv_cache uv run --no-sync python scripts/generate_contract_views.py --check
UV_CACHE_DIR=./.uv_cache uv run --no-sync python scripts/validate_traceability.py --check

2. Tooling: prefer .venv/bin/*

.venv/bin/pyright --warnings
.venv/bin/ruff check .
.venv/bin/pytest -q

UV_CACHE_DIR=./.uv_cache uv run --no-sync python scripts/validate_run_id.py --check-exists <RUN_ID>
UV_CACHE_DIR=./.uv_cache uv run --no-sync python scripts/validate_run_artifacts.py .agent-workflow/runs/<RUN_ID>

• Git tags follow SemVer with a v prefix (for example v0.1.0, v1.0.0).
• During the rebuild, pre-1.0 tags are expected while the public surface stabilizes.

This repo is designed to support:

• Conventional Commits (enforced via PR titles + squash merge).
• Release automation from main (recommended: Release PR model via release-please).

1. Create a branch for your change.
2. Open a PR to main.
3. Use a Conventional Commit-style PR title (this becomes the squash commit message):
   • feat(scope): add ...
   • fix(scope): correct ...
   • docs: clarify ...
   • chore: ...

.venv/bin/pyright --warnings
.venv/bin/ruff check .
.venv/bin/pytest -q

Read: CODEX.md

Security invariants are documented and tested in the scaffold and workflow:

• Path traversal containment
• Subprocess argument hardening
• SSRF policy (where network features exist)

See: docs/OPUS_REBUILD_FRAME_COMPARE/08-quality-standards.md and docs/OPUS_REBUILD_FRAME_COMPARE/scaffold/

See LICENSE (to be added).