M11.4: document AAF / OMF interchange and the cfb crate

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

README.md

@@ -211,6 +211,8 @@ Move timelines between FilmCraft and every other editor:
 - **FCPXML 1.9–1.11:** the spine, connected clips as lanes, transitions, retiming and compound clips.
 - **OpenTimelineIO:** the open interchange format of the film industry, round-tripping every FilmCraft detail through `metadata.filmcraft`.
 - **CMX 3600 EDL:** the oldest format still in use, with drop-frame timecode, dissolves, wipes, speed changes (`M2`) and one EDL per track.
+- **AAF (Edit Protocol):** for Avid Media Composer and Pro Tools. Video and audio tracks, dissolves and dips, clip volume with keyframes, markers and source timecode; audio embedded or as separate WAV / AIFF files, trimmed with handles, with clip effects rendered in and broken out to mono, plus an optional video mixdown. Import reads AAF back, extracting embedded audio.
+- **OMF 2.0:** the audio-post handoff: the audio tracks with crossfades and gain, sample-accurate, with the audio encapsulated or alongside.
 
 Import merges the document's bins, media and sequences into your project as one undoable step, and links each media file it finds on disk.
 

crates/interchange/README.md

@@ -0,0 +1,56 @@
+# 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`](../cfb/README.md) |
+| 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.
+
+## 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.
+- `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.

docs/architecture.md

@@ -59,7 +59,7 @@ and `filmcraft-cli`.
 | `edit` | L2 | pure edit algebra (insert, overwrite, razor, ripple, roll, slip, slide, rate stretch…; text-based editing: `edit::transcript`) |
 | `speech` | L2 | speech-to-text: `Transcriber` trait, Whisper model catalogue + verified downloader (feature `download`), pure-Rust Whisper inference on candle with word timestamps (feature `whisper`), speaker labelling ([transcripts.md](transcripts.md)) |
 | `codecs` | L2 | container + codec hub: MP4/MOV, MKV, MXF and Ogg sources, GOP-aware seeking, decoder registry, audio decoding |
-| `interchange` | L2 | EDL, FCP7 XML, FCPXML and OTIO import/export (no file I/O) |
+| `interchange` | L2 | EDL, FCP7 XML, FCPXML, OTIO, AAF (on `cfb`) and OMF 2.0 import/export (no file I/O; the engine supplies rendered audio essence) ([README](../crates/interchange/README.md)) |
 | `render` | L3 | sequence evaluation, CPU compositor, video effects (`effects`, `vfx`; effects needing other frames or tracks read them through `vfx::FxEnv`), transitions, audio mix |
 | `gpu` | L3 | wgpu compositor (WGSL) |
 | `golden` | L3 | test-only: golden-image tests of the CPU renderer and GPU-vs-CPU parity; empty library, dev-dependencies only |
@@ -554,9 +554,14 @@ file.exportMedia {path, preset?, settings?, format?, range?, …}     export.qui
 Video encoders implement `export::VideoEncoder`. Codec crates plug in with `register_encoder` and
 `register_audio_encoder`.
 
-Timelines can be exchanged as EDL, FCP7 XML, FCPXML or OTIO. `file.import` detects these formats and
-merges the result into the project as one undoable step, and `file.exportInterchange`,
-`file.exportEdl`, `file.exportFcpxml` and `file.exportOtio` write them.
+Timelines can be exchanged as EDL, FCP7 XML, FCPXML, OTIO, AAF or OMF. `file.import` detects these
+formats and merges the result into the project as one undoable step (AAF / OMF embedded audio is
+written next to the document first), and `file.exportInterchange`, `file.exportEdl`,
+`file.exportFcpxml`, `file.exportOtio`, `file.exportAaf` and `file.exportOmf` write them. For AAF and
+OMF the engine (`engine::aaf_omf`) first prepares the audio the document references: it lists the
+used ranges (`interchange::essence::audio_needs`), decodes or renders them (clip effects through the
+export audio pipeline), embeds them or writes WAV / AIFF files, and optionally renders a video
+mixdown.
 
 ## 7. Automation surfaces