Interchange

Module wabcut_interchange (pure C++23, no Qt) imports timelines from Premiere Pro, DaVinci Resolve, Final Cut Pro and anything that writes OpenTimelineIO or CMX3600 EDLs, and (X.1) exports them back in the same formats ("Export" below). Owner: Interchange (follow-ups since C.4: Core engine).

#include <wabcut/interchange/Import.h>

interchange::ImportOptions options;
options.mediaSearchRoots = {"D:/Footage"};
auto result = interchange::ImportRouter::importFile("Main Edit.xml", options);
if (!result) { /* result.error(): NotFound / IoError / Unsupported / ParseError */ }
// result->project: a valid ProjectState; result->report: carried / approximated / dropped;
// result->unresolvedMedia: files that were not found.

wabcut-cli import <file> [--search <dir>]... [--json] [--carried] [--edl-rate 24000/1001] [--experimental-prproj]

How it works#

file ──ImportRouter::detect──► parser (FCP7 / FCPXML / OTIO / EDL / prproj) ──► IR ──TimelineBuilder──► ProjectState
                                                    │                                   │
                                                    └──────────── ImportReport ◄────────┘     MediaRelinker

• Detection reads at most 64 KiB and goes by content first (XML root element, gzip magic, OTIO_SCHEMA, CMX3600 event lines), extension second. .fcpxmld and .otiod bundles are folders read through their Info.fcpxml / content.otio.
• Parsers turn each format into a format-neutral intermediate representation (src/Ir.h) in exact Ticks, and report what they cannot represent. Times are converted with a 128-bit mulDiv and explicit rounding (src/TimeMath.h); NTSC rates stay exact (24000/1001, 30000/1001, ...).
• TimelineBuilder builds the project only through the model's own operations (addBin, addMedia, addSequence, placeClips, setSpeed, frameHold, setTimeRemap, addTitle, setClipAttributes, linkClipGroups, addTransition, addMarker, markIn/markOut, setSequenceDuration, setTrackState), so the result is valid by construction; validate(Strict) runs at the end anyway.
  • X.1 bulk build: a track's media clips go in with one edit::placeClips (the model's bulk placement: each clip checked like an overwrite edit, the track copied once) and every link group with one edit::linkClipGroups; titles and nested clips are placed one by one between the batches.
  • A retimed clip is placed at 100% and then given its speed with SpeedChange::keepDuration. This is Premiere's Speed/Duration with speed and duration unlinked: the clip keeps its position, length and media In, and plays length × speed of media. A freeze frame becomes a frame hold of its source In.
  • Variable speed becomes a time remap (C.6, edit::setTimeRemap): the clip is placed at 100% and given the source's curve, keys at curve time (the clip's own output time) holding media positions. Straight segments between the keys are exact; smooth (curved) keys are imported as straight segments and reported.
  • Transitions keep the alignment their sides describe (center within a frame, startAtCut, endAtCut, otherwise custom), stored on the transition.
  • Transitions are added last, on the clips that end and start at the transition's edit point. When only one side has a clip, the transition becomes a one-sided fade inside that clip (reported). When the media lacks the handles, it is shortened to the media there is (HandleFit::UseAvailable, reported). When no clip meets the cut, it is reported as a cut.
  • Titles are made with addTitle: a title media item in the import bin, a clip and its style effect. Imported media and sequences go into a new bin named after the file, in bins below it that mirror the source's (X.1: FCP7 <bin>s, FCPXML events and keyword collections; at most 16 levels). With ImportOptions::targetProject they are added to an existing project.
• Each media item gets a MediaLocator: the absolute path (the file found, or the original path when it is offline), the path relative to the project file (ImportOptions::projectFile, by default a project saved next to the imported file) and offline when it was not found. The fingerprint stays unknown at import (computing it reads every file); the media probe fills it in.
• Clips that overlap on one track (possible in OTIO/EDL/hand-edited XML, or FCPXML lanes from different parents) are never lost or overwritten: they move to an extra track and the move is reported.
• Malformed input returns ErrorCode::ParseError; it never crashes. Inputs are capped (256 MB file, 512 MB decompressed .prproj), recursion is bounded (nesting depth 32) and parsing is iterative. Every parser is fuzzed (tests/fuzz, C.10).
• Text encoding. Imported text is always UTF-8 (C.10).
  • EDLs carry no encoding, and Avid and older tools write Windows-1252. An EDL that is not valid UTF-8 is read as Windows-1252: valid UTF-8 sequences stay, the other bytes are converted.
  • In XML, pugixml honours a BOM or a Latin-1 declaration. Text and attribute values that are still not UTF-8 after parsing are converted the same way. This covers undeclared Windows-1252 and numeric references to lone surrogates.
  • Before C.10, such bytes went into names unchanged, and the imported project could not be saved. As a last guard, an import whose project would not serialise is refused with ParseError.

The import report#

Every element read is listed once as Carried (exactly as in the source), Approximated (in the timeline but changed; the reason says how) or Dropped (not in the timeline; the reason says why), with a category — clip, gap, transition, speed, effect, marker, track, sequence-setting, audio-mapping, media, graphic (Lottie, below) — and a source location: file, element path (XML path such as /xmeml/sequence/media/video/track[1]/transitionitem[1], JSON pointer such as /tracks/children/0/children/3, or event 012 for EDLs) and line (0 for JSON). reason is user-facing English (unlike Error::message).

Support matrix#

C = carried exactly, A = approximated (reported), D = dropped (reported), — = the format has no such thing.

Timing semantics worth knowing, per format:

• Speeds (all formats) — the clip's timeline position and length and its media In come from the file as before; the speed says how much media it plays (length × speed). Speeds are exact rationals: FCPXML timeMap points are rational times; percentages, OTIO time scalars and .prproj speeds are matched to the nearest fraction with a denominator up to 100,000 (exact for decimal percentages; anything else is reported as rounded).
• FCP7 XML — start/end are sequence frames; in/out are frames at the clip's own <rate>. A clip next to a transition has start or end = -1, and its in/out include the transition's handles (Apple's reference, listing 3-17): the edit point comes from the transition — Premiere's cutPointTicks when present, else the alignment (center = middle, rounded down like OTIO; start/start-black = its start; end/end-black = its end) — and an incoming clip's media In moves past the handle. With a speed change in/out count retimed frames, so the media In comes from pproTicksIn (Premiere, exact), else the speedkfin keyframe value, else in × speed. With variable speed the Time Remap graphdict keyframes are the curve: when is a frame of the clip's own in/out space (the clip's curve time starts at in, past any transition handle) and value the media frame. Premiere writes each stereo track as two "exploded" mono tracks (currentExplodedTrackIndex/totalExplodedTrackCount); they become one track.
• FCPXML — sequenceTime(child) = sequenceTime(parent) + (child.offset − parent.start), recursively; top-level spine offsets count from tcStart. A clip without start begins at its asset's first frame. Transitions overlap the cut between back-to-back spine items. Lanes: video lanes in order (below-primary lanes composite under V1's content), audio: primary storyline first, then lanes below, then audio of connected clips above.
• OTIO — rates are doubles: 23.976023976… / 29.97 / 59.94 snap to the exact NTSC rationals. Times at different rates in one file (48 kHz audio ranges) convert exactly. Transitions take no track time (in_offset before the cut, out_offset after).
• EDL — the frame rate is not in the file: ImportOptions::edlFrameRate / --edl-rate, default 29.97 for drop-frame EDLs and 24 otherwise (OTIO's default). Drop-frame comes from FCM: or ; separators; labels that do not exist in drop-frame (e.g. 00:01:00;00) drop the event and say so. Record time is rebased so the starting timecode hour is 0. A dissolve's cut is at the incoming event's record In and runs N frames into it. Source timecodes are absolute: the clip's source In stays the absolute timecode unless ImportOptions::mediaInspector reports the file's start timecode (MediaFacts::startTimecode), in which case it is converted (reported either way).

Export (X.1)#

A sequence goes back out as a timeline file other editors read, with the nested sequences and multicam sources it plays: for the grade in Resolve, the mix elsewhere, or a Premiere Pro editor down the line.

#include <wabcut/interchange/Export.h>

auto result = interchange::exportSequenceToFile(project, sequenceId, interchange::Format::Fcp7Xml, "Main Edit.xml");
// result->report: carried / approximated / dropped, like an import's; result->sequences: what was written.

wabcut-cli export-timeline <project.wabcut> <out> [--format fcp7-xml|fcpxml|otio|edl] [--sequence <name|id>]
                           [--fcpxml-version 1.10|1.11] [--json] [--carried]

The command interchange.export ({"format", "path", "fcpxmlVersion"}) does the same for scripts, the assistant and MCP clients. It names a file, so it is a file command: MCP serves it only with --allow-files / --files-folder, confined to those folders (docs/mcp.md). A dry run reports and writes nothing. For the UI engineer: File > Export > Timeline as FCP XML / FCPXML / OTIO / EDL is the command with a save dialog, then the report in the same panel as the import report.

ProjectState ──describeForExport──► IR (src/Ir.h) ──writer (FCP7 / FCPXML / OTIO / EDL)──► file
                       │                                      │
                       └──────────── export report ◄──────────┘

• Deterministic. The same project gives the same bytes (ids are numbered in document order), so exports can be diffed and checked in. Golden files of each format (tests/interchange/fixtures/export/basic.*) are compared byte for byte; a changed export is written to test-output/export/, and WABCUT_UPDATE_GOLDEN=1 replaces them.
• Read back by Wabcut. Every format's output is imported again in the tests (tests/interchange/test_export.cpp): Wabcut -> format -> Wabcut gives the same timeline for everything the report calls Carried, compared clip by clip (position, length, source In, speed, remap, properties and keyframes, effects, titles, links, transitions, markers, nested and multicam sources). The fixtures of the import suite are exported to each format and imported again too.
• Media are written as absolute file URLs (file://localhost/C%3a/... for FCP7 XML as Premiere writes it, file:///C:/... for FCPXML and OTIO); media with only a project-relative path are resolved against ExportOptions::projectFile.

Export support matrix#

C = carried exactly (comes back the same), A = approximated (written, but changed: the report says how), D = dropped (reported), — = the format has no such thing.

Lottie (motion graphics, C.13)#

importLottie (Lottie.h, src/LottieImporter.cpp) reads Bodymovin JSON into a Graphic (not a timeline): shape, solid, text and precomp layers, parenting, transforms with their easing as Bezier keys, shapes, fills, strokes, gradients, trims, text range selectors and masks. It reports like the timeline importers, category graphic (and effect, media, marker), with JSON pointers into the file. The support matrix and bounds are in graphics.md; lottie.import places the result as a clip or saves it as a template. Fuzzed by fuzz_lottie.

Media relinking (MediaRelinker.h)#

For every media reference, in order: the exact path (when absolute on this platform); project relative — a relative reference against the imported file's folder, then the trailing folders of the original path under that folder and its parent (/Volumes/X/Show/Media/a.mov → <dir>/Media/a.mov, ...); then a file-name search under the search roots (case-insensitive, indexed once per import, capped at 500,000 files and depth 24). Candidates whose size (when the format knows it) or duration (when an inspector is given) differ are rejected; among the rest the one sharing the most trailing folders with the original path wins, and an ambiguous pick is reported. Unfound media stay in the project as offline items with their original path (ImportResult::unresolvedMedia lists them with every path tried). The relinker only lists directories and reads sizes; it never opens, moves or modifies media.

The paths come from the imported file, so they are untrusted. A UNC path (\\host\share\clip.mov) makes Windows contact that host when the path is checked. ImportOptions::fileExists (RelinkOptions::fileExists) replaces the existence check. The fuzz harnesses use it so they never touch the disk or the network. A host that imports files from strangers can use it to refuse network paths it has not seen before.

Network paths: the policy (C.10, decided for I.8). A network path (\\server\share\..., file://server/share/..., //server/share/...) is treated exactly like a local one: it is checked with the same plain existence test, in the same order, and a share that is missing, unreachable or refuses access leaves the media offline with its original path, as a missing local file does - never an import error. Wabcut never mounts a share (no drive letter is mapped, no WNetAddConnection), never shows or follows a credentials prompt (only plain file-system calls are made, which fail rather than ask), and never searches a share it was not given as a search root. What the check cannot avoid on Windows: it contacts the host named, with the signed-in user's single sign-on, as Explorer does when such a path is opened; a host that wants that refused passes its own fileExists. The test is "interchange: relink: a network share is looked up like a local folder" (tests/interchange/test_relinker.cpp).

Detected but not imported#

.prproj research spike — outcome#

Shipped: detection + guidance by default, and an experimental reader behind ImportOptions::experimentalPremiereProject (--experimental-prproj).

What we learned (structure documented at the top of src/PremiereProject.cpp): a .prproj is gzip-compressed UTF-8 XML whose root's direct children are objects addressed by per-save ObjectID/ObjectRef integers or persistent ObjectUID/ObjectURef GUIDs (nested scopes reuse ids, so only the root's children are indexed). Sequences → track groups (typed by GUID) → clip tracks → track items (Start/End, IsMuted = disabled) → sub-clip → clip (InPoint/OutPoint, PlaybackSpeed, PlayBackwards) → media source → Media (ActualMediaFilePath, Title, Infinite for stills). Links, transitions (Alignment = ticks before the cut) and markers (DVAMarker JSON with 0xAABBGGRR colours) hang off the sequence. All times are Premiere ticks, which are Wabcut ticks, so positions transfer losslessly. Recent versions omit default values (Start 0, speed 1, IsMuted false). The element names were stable from Premiere 10.4 (2016) to 26.3 (2026) in the files examined by the research, following the MIT-licensed py-premiere.

Verification: the reader was compared with Premiere's own ExtendScript dump (py-premiere's ground truth) for 24 sample projects saved by Premiere 26.3. In all 24, the sequences, frame rates and sizes, every track, every clip's start, end, name and media In, and the markers matched (one project has no sequence; its media imported). The samples share a small base project (a still, a tone, a nested sequence) and each adds one feature: transitions, disabled clips, track mute/lock, retime, time remap, merged and multicam clips, generators, subclips, razor/slip/roll results, extra tracks, sequence settings. Seven of them and their dumps are test fixtures (tests/interchange/fixtures/prproj, MIT notice included); the tests also check locks, disabled clips, links and marker details.

Why it stays experimental:

• the format is undocumented and changes between versions; only Premiere 26.3 output was checked against ground truth, older layouts (pre-CS6 projects in particular) are untested;
• effects, keyframes, clip properties, time-remap curves, audio track mute (mixer), clip channel routing, bins and proxies are not read;
• merged and multicam clips are internal sequences in the project; they import as sequences of their own, and since X.1 the clips that use them (and nested sequences) play them as nested clips; a multicam clip's angle switches are not read;
• a whole DOM is built: a very large project (hundreds of MB of XML) needs gigabytes of memory.

Recommendation: keep FCP7 XML export as the advertised Premiere path (it carries effects values, speed and audio mapping and is what Adobe calls the robust interchange), and grow the .prproj reader behind the flag with more ground-truth samples (py-premiere has ~80) before turning it on.

Known gaps and next steps#

• Transitions, retiming and titles (C.4) are carried with the model's operations: addTransition, setSpeed with keepDuration, frameHold and addTitle (see "How it works").

  • Variable speed is carried as a time remap (C.6) from FCP7 XML (graphdict) and FCPXML (multi-point timeMap). Still approximated: wipe patterns and other transition types (mapped to the closest built-in transition), reverse playback (the same media range played backwards), smooth speed-ramp keys (X.1: Bezier keys whose tangents are worked out from the neighbouring keys, since neither format keeps handles), .prproj time remapping and OTIO non-linear time effects (100%; OTIO has no schema for them), and title parameters beyond text, font, size, style, alignment, colour and outline.
  • Still dropped: generators other than titles.
  • X.1: keyframes of opacity, motion and volume import as curves (curve time = media time), position and anchor are carried, and FCP7's Gaussian Blur, Crop and Drop Shadow (and Wabcut's own effects written by an export) import as effect stack entries (edit::addEffect). Still dropped: colour, EQ and compressor filters of other editors (their parameters do not map onto Wabcut's), FCPXML filters, OTIO effects other than time warps.

• Premiere's work area and split-edit audio extents need model support before they can be carried (X.1 added the sequence start timecode, and clip markers are carried as markers of the source). (Per-channel audio routing has it since A.9: FCP7 and FCPXML channel selections import as clip channel maps.)

• Media probing during import: the CLI passes no mediaInspector yet, so EDL source timecodes stay absolute and same-name candidates are not compared by duration. Wire media::probe (and start timecode) in the app.

• Bins (X.1): FCP7 bins and FCPXML events and keyword collections become bins below the import bin. Not read: .prproj bins (the project view's tree is not mapped yet), FCPXML keyword collections beyond a media item's first, smart collections. The exporters write no bins.

• Not supported yet: AAF, .otioz, OTIO ImageSequenceReference, OTIO nested Track items, multicam angle switches in Premiere .prproj files, generators other than titles.

• Nested and multicam sequences (C.8) are built before the sequences that use them; ImportResult::sequences keeps the parsers' order: a parent sequence comes before the sequences nested in it (FCP7 right after it, FCPXML after the project that uses them, OTIO after all timelines; each in the order they were met). A clip that would make a sequence contain itself is dropped and reported.

• wabcut-cli takes paths as narrow argv; on Windows non-ASCII paths need a wide wmain (CLI-wide change).

• Performance (X.1, RelWithDebInfo on the shared 32 GB build box, linked picture + sound pairs of tests/model/ScaleProject.h; wabcut_interchange_tests "[perf]", the 50,000-clip case is hidden: run it with "[perf]~[export]"):

  Clips	Format	Export before → after	Import before → after
  3,000	FCP7 XML (4.1 MB)	55 → 57 ms	389 → 120 ms
  3,000	OTIO (12.9 MB)	149 → 169 ms	326 → 255 ms
  50,000	FCP7 XML (68 MB)	797 → 689 ms	212.3 s → 2.8 s
  50,000	OTIO (215 MB)	3.2 → 2.8 s	23.7 → 4.0 s

  Before: one overwriteEdit per clip (each copies the track: O(n²) per track), one linkClips per pair, a findClip per clip for its attributes, and every report location counted the element's siblings (a track of 25,000 clipitems: O(n²) on FCP7 XML alone). After: placeClips / linkClipGroups, one clip index, and sibling positions cached per large parent (XmlLocator). The rest is linear; the OTIO time is mostly JSON parsing of Wabcut's lossless metadata. Clips with a speed, a remap or effects still cost one edit each.

Sources#

• Apple, Final Cut Pro XML Interchange Format (FCP7 xmeml v1–v5), element reference and listings 3-6, 3-14, 3-17 — developer.apple.com/library/archive/documentation/AppleApplications/Reference/FinalCutPro_XML.
• Apple, FCPXML Reference and DTDs 1.8–1.11 (media-rep, .fcpxmld bundles, timing attributes, lanes).
• OpenTimelineIO schema docs and sources (otio-serialized-schema.md, time-ranges.md, track.cpp), and the OTIO FCP7/FCPX/CMX3600 adapters (alignment cut points, exploded stereo tracks, sample files).
• CMX 3600 EDL specification (event/M2 column layout, edit types); Avid/Resolve comment conventions (* FROM CLIP NAME:, * LOC:, AUD).
• py-premiere (MIT) and its ExtendScript ground-truth samples; Adobe Premiere Pro Scripting Guide (Time, TrackItem); OpenNeuro ds004505 (CC0) and other public .prproj files examined during the spike.