Add ImageSequenceReference Support

[camkerr]

Link the Issue(s) this Pull Request is related to.

Fixes Issue #82

Summarize your change.

Support for ImageSequenceReference isn't available in the Swift bindings, this PR adds that support.

Reference associated tests.

testImageSequenceReference.swift has been added with 11 tests to cover this new implementation.

Use of AI / LLM

This code was written using an LLM. The following are the details of that session.

My Original Prompt

This folder is my fork of the OpenTimelineIO-Swift-Bindings repo.  I have added my own CLAUDE.md and SKILLS.md

Right now, ImageSequenceReference.1 is not supported in these Swift Bindings.  I have made a new branch "img-seq-ref" to implement ImageSequenceReference.1

Consult CLAUDE.md and SKILLS.md

Here is the documentation:  https://opentimelineio.readthedocs.io/en/stable/tutorials/otio-serialized-schema.html#imagesequencereference-1

Environment

Claude Code
Model: Opus 4.8
Claude for Mac: Version 1.15962.2
See uploaded CLAUDE.md and SKILLS.md

---

Start of Claude's Response

ImageSequenceReference.1 is now implemented across all three layers, and the build and full test suite (75 tests, 0 failures) are green.

What I did

1. Obj-C++ bridge — Sources/objc/include/opentimelineio.h + Sources/objc/opentimelineio.mm

• Added otio_new_image_sequence_reference() constructor (and #include <opentimelineio/imageSequenceReference.h>).
• Added a // MARK: - ImageSequenceReference section wrapping every C++ member:
  • String props: target_url_base, name_prefix, name_suffix
  • Numeric props: start_frame, frame_step, rate, frame_zero_padding
  • Enum prop: missing_frame_policy (bridged as int, cast back to the C++ MissingFramePolicy)
  • Computed/derived: end_frame, number_of_images_in_sequence, and the three error-returning methods frame_for_time, target_url_for_image_number, presentation_time_for_image_number (using the _AutoErrorHandler aeh(cxxErr) pattern).

2. Swift layer — ImageSequenceReference.swift

• public class ImageSequenceReference : MediaReference with a nested MissingFramePolicy: Int enum (error/hold/black), modeled on Track.NeighborGapPolicy.
• Two convenience inits following the ExternalReference/MediaReference generic-metadata pattern, with C++-matching defaults (startFrame: 1, frameStep: 1, rate: 1, frameZeroPadding: 0, missingFramePolicy: .error).
• Computed properties for all fields; endFrame/numberOfImagesInSequence as get-only; the three error-returning methods as throws functions via OTIOError.returnOrThrow.
• Registered "ImageSequenceReference" in SerializableObject.swift's WrapperCreator.

3. Tests — testImageSequenceReference.swift

• 11 tests covering construction, property round-trips, the enum, endFrame, numberOfImagesInSequence, targetURL(forImageNumber:) (including the missing-slash case), frame(for:) (including out-of-range throwing), presentationTime(forImageNumber:), testNegativeFrameNumbers, and JSON serialize/deserialize round-trip. Expected values are taken from upstream's test_image_sequence_reference.py.

Notes worth flagging

• Submodule wasn't initialized. The OpenTimelineIO/ C++ submodule was empty, so I ran git submodule update --init --recursive to get the headers needed to compile the bridge. (CLAUDE.md describes it as a checked-out reference repo.)
• Test toolchain. swift test failed with no such module 'XCTest' because xcode-select points at CommandLineTools. I ran the suite with DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer swift test (no global change). swift build works either way.
• I left your CLAUDE.md "Coverage status" section untouched — but it now lists ImageSequenceReference.1 as missing, which is no longer true. Want me to move it into the "Bound" list?

One small API-design call I made: the conversion methods are named frame(for:), targetURL(forImageNumber:), and presentationTime(forImageNumber:) since there was no existing peer to copy. Easy to rename if you'd prefer something closer to the C++ frame_for_time / target_url_for_image_number naming.

End of Claude's Response

---

I also used this new implementation to write out a couple of .otio test files containing image sequences. Those imported correctly into: DaVinci Resolve, NukeStudio and RV. I did have some issues with image sequences that have negative frame numbers, but those issues appear to be lack of support for negative frame numbers at the host application level and not my implementation.

Creating this as a Draft PR until we finalize our AI coding policy.

I did create my own CLAUDE.md and SKILLS.md for use with these Swift bindings. I have uploaded them here for reference.
CLAUDE.md
SKILLS.md

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: camkerr / name: Cameron Kerr (e652fbf)