punkhopandClaude Opus 5.5
4aa3f79953
Problem: a clip item whose `<file id="...">` reference has no definition anywhere in the document was dropped without a word, so a sequence could come back one clip short with an empty import report. FilmCraft's own export writes titles and adjustment layers this way. Solution: the importer adds a warning that names the clip item: `clip "Title" refers to a file the document does not define; skipped`. Nothing else about the import changes. Test: `fcp7_import_reports_a_clip_item_whose_file_is_not_defined` (FilmCraft's own export, a hand-written document, and a document whose files are all defined). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
filmcraft-interchange
Timeline interchange for FilmCraft: CMX 3600 EDL, Final Cut Pro 7 XML (xmeml), FCPXML, OpenTimelineIO, AAF and OMF import and export, plus Avid ALE. Layer L2: no file I/O; media references are strings and audio essence is supplied by the caller (the engine).
Specifications
Clean-room: written from public specifications only. The AAF SDK, pyaaf2, the OMF Toolkit and other implementations were not consulted.
| Format | Document | Edition | Used for |
|---|---|---|---|
| AAF | AMWA AAF Object Specification | v1.1 (2005) | classes, properties (ids shared with SMPTE ST 377-1 local tags), mob / slot / segment model, sequences and transitions, operation groups, parameters, definitions, descriptors, locators, essence data |
| AAF | AMWA AAF Low-Level Container Specification | v1.0.1 | objects as structured storages, properties streams, stored forms, strong / weak reference collections and their index streams, referenced properties |
| AAF | AMWA AAF Edit Protocol | v1.0 (AMWA AS-01) | top-level composition, mob chains (composition → master → file → physical source), operation definitions (dissolve, fade to black, audio gain / dissolve), usage codes |
| AAF | SMPTE RP 224 / RP 210 registers | — | data definition, class and type labels |
| AAF | Microsoft [MS-CFB] | rev. 10.0 | the container, see filmcraft-cfb |
| OMF | Avid OMF Interchange Specification | Version 2.0 (1997) | classes (HEAD, CMOB, MMOB, SMOB, MSLT, TRKD, SEQU, SCLP, FILL, TRAN, EFFE, ESLT, CVAL, VVAL, TCCP, WAVD, AIFD, WAVE, AIFC, locators), property and type names |
| OMF | Apple Bento Specification | revision 1.0d5 | container label, TOC encoding, objects / properties / types, references |
| WAVE / AIFF | Microsoft RIFF WAVE; Apple AIFF 1.3 | — | embedded and separate audio files |
The other formats' editions are listed in the module docs (edl, fcp7, fcpxml, otio, ale).
AAF and OMF
comp holds a format-neutral mob-style model (compositions of slots whose sequences of fillers,
source clips and overlapping transitions reference media through master and file source mobs).
aaf and omf serialise it; both import back into the same model and from there into FilmCraft
sequences and media. Mapping details (what each FilmCraft feature becomes) are in the aaf and
omf module docs. Times are kept in ticks in the model; compositions use the sequence frame rate
for picture and the sample rate for sound slots, so audio edits are sample-exact.
Embedded / consolidated audio (essence): audio_needs lists the media ranges an export
references (per media item or per clip, with handles); the engine decodes or renders them and
passes AudioEssence (embedded PCM or a written file) back in MediaOptions.
Not represented: speed changes and frame holds (exported at 100 % with a report entry), nested sequences, graphics and synthetic media (gaps), video effects other than transitions, clip markers (written to the master mob, so they come back as media markers), OMF video and markers.
Graphics and adjustment layers
No format here has an equivalent of a FilmCraft graphic (title) clip or an adjustment layer, and
none of the exports brings one back. Each such clip is named in the export Report as a warning
(graphic clip "Title" at frame 48 …, one line per clip), with what was written instead:
| Format | Written as | On import into FilmCraft |
|---|---|---|
| FCP7 XML | a clip item without media (its layers as FilmCraft filter ids) | not read back; the import report names the skipped clip item |
| FCPXML | a clip without media | not read back |
| OTIO | a clip with a MissingReference (effects in the filmcraft metadata) |
offline media |
| EDL | an ordinary event with the reel the reel mode gives | an ordinary clip |
| AAF | a gap | nothing |
OMF carries no video at all.
Tests
tests/aaf_omf.rs: AAF round trips at 25, 29.97 DF, 23.976 and 59.94 DF (clips, gaps, two-sided and one-sided transitions, links, markers, start timecodes, constant and keyframed gain, media markers and timecode); 512-byte sectors; breakout to mono; embedded trimmed audio (sample data and source offsets); separate consolidated files with a video mixdown; OMF round trips with embedded audio, separate AIFF files and breakout; empty sequences; truncation and random corruption never panic.tests/uncarried_clips.rs: every format's export report names each graphic clip and adjustment layer once, as a warning; a sequence without them reports nothing; what a re-import gives back matches the report; the FCP7 XML import names a clip item whose file is not defined.src/aaf/tests.rs: written files checked against the required properties of every class written (Header, Identification, Mobs, slots, components, descriptors), weak references resolving into the dictionary, source clips resolving to mobs and slots, the Edit Protocol transition rules and sequence length arithmetic; every stored form round-trips through the container.src/omf/tests.rs: the Bento label and TOC, the required properties of every OMF class written, reference resolution, embedded WAVE data, sequence lengths in samples.