Add cut_diff example: structural editorial diff between two cuts

[chaoz23]

This adds an examples/cut_diff.py script that answers "what changed between cut A and cut B" — which clips were added, removed, retimed, moved, or shifted — in the spirit of existing examples like conform.py and shot_detect.py. The OTIO docs list "Shots Added or Removed From The Cut" as a first-class use case; this example implements it.

Because both inputs go through adapters, the cuts don't need to share a format — an EDL can be diffed against an FCP XML export of the revision:

$ python cut_diff.py editors_cut.edl finishing.fcpxml
1 retimed, 1 shifted (7 unchanged)
  ~ ZZ100_503A shortened by 12f (28f -> 16f)
  . ZZ100_504C shifted 12f earlier

Design notes:

• Clips are matched by identity (media target_url + source in-point), not timeline position — one insertion shifts every downstream timecode, so positional diffing reports everything as changed.
• "Moved" is detected by relative order (longest increasing subsequence over matched clips), so a gap inserted by a lift-trim doesn't read as every downstream clip moving.
• Ripple slides report as "shifted", separate from "retimed", so one trim doesn't read as N retimes.
• Scope is structural editorial only (clips/timing/order); effects and transitions are intentionally out, per their tool-specific serialization.
• --json output and diff(1) exit codes for scripting.

Validated against sample files from the cmx3600 and fcpx-xml adapter test suites, including hand-modified known-change cases. A packaged version with a test suite and an MCP server lives at chaoz23/otio-diff; this example is self-contained.

🤖 Generated with Claude Code

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: chaoz23 / name: chaoz23 (d92cd00)

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.25%. Comparing base (bc5fe2d) to head (eea4a72).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2030   +/-   ##
=======================================
  Coverage   83.25%   83.25%           
=======================================
  Files         180      180           
  Lines       13479    13479           
  Branches     1253     1253           
=======================================
  Hits        11222    11222           
  Misses       2085     2085           
  Partials      172      172           

Flag	Coverage Δ
py-unittests	83.25% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update bc5fe2d...eea4a72. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jminor]

See also: #1922

[chaoz23]

Thanks — hadn't seen #1922. That's the ambitious integrated-tool path: an otiotool feature with a visual annotated-OTIO output, aimed at #26. From the outside it looks stalled, though — still a draft, no commits since Aug 2025, and currently conflicting with main.

This PR is deliberately narrower and at a different layer: a self-contained examples/cut_diff.py alongside conform.py and shot_detect.py. It touches no core code, CI is green, and it can land independently today. If #1922 revives later as the full integrated tool, this example points readers straight to it — they complement rather than compete. I've added a header note in the example cross-referencing otiotool/#1922 and #26.

Proposal: merge this as an example. If you'd rather hold it, I'll close it — no debate needed.

[chaoz23]

Hi maintainers — following up on this example PR (cut_diff: structural editorial diff between two cuts). All checks are passing (build, docs, DCO, EasyCLA). Happy to make any adjustments if you have feedback. Thanks for taking a look!

[jminor]

Hi @chaoz23 - the OpenTimelineIO Technical Steering Committee is actively debating this project's policy for LLM-assisted code contributions. You'll have to wait until we finalize that policy before moving forward with this PR. Thanks for your patience.

[chaoz23]

Understood, and thanks for the heads-up, I'll wait for the TSC's policy and won't push in the meantime. Whenever it lands, happy to adapt this PR to whatever disclosure/provenance requirements you settle on (the AI-assistance note in the description was intentional on my part, in that spirit). Appreciate the transparency about the process.