Hi. I'm close to completing a Python scripting framework for FCP XML export files, but cannot seem to get closure on the semantics of the time and timecode-related entities after much studying of the FCP XML spec and many sample exports. I'm hoping someone on the list here can shed some light.
The framework is basically a set of Python classes that load an XML file and wrap the XML DOM in a more tractable Python object-model that tries to better match the FCP user-interface abstractions. Here's a small sample script that scans for all the Text generators in the first 10 minutes of the V2 track of the sequence named 'main' and sets title details and text from a python dictionary indexed by clip name:
for c in sequences['main'].v2.clipItems.startBetween('1:0:0;0', '1:10:0;0'): if c.isGenerator and c.effect.name == 'Text' and c.name in titles: c.effect.font = 'Helvetica' c.effect.size = 36 c.text = titles[c.name]
As you can see, it abstracts away a lot of the complex structure in the XML DOM and provides useful tools, such as time-based searching and so on.
As I mentioned, the main issue for me now is fully understanding the time & timecode elements in the XML DOM, particularly for Browser-resident clips. The time-related elements, like <duration>, <in>, <out>, <start> and <end>, are all given in relative frames with respect to a playback framerate and a timecode reference. To help when scripting these fields, I want to be able to display and take real time and timecodes, not just relative frames, so determining the correct reference 'context' for these values is necessary.
It turns outs that the playback framerate is always well-defined, coming from a local or inherited <rate> element. The timecode reference, encoded in <timecode> elements and giving timecode display format, timecode timebase and starting timecode, is not so well-defined. Firstly, the spec says they are not inheritable, but they are not directly present in most of the places you'd need them. As a first guess, it seems that <in>/<out> should be relative to a <timecode> in the contained <file>, and <start>/<end>/<duration> relative to the owning-sequence's <timecode>, and the FCP UI seems to confirm this, at least for Sequence-resident items.
The trouble is, clipitems inside Browser-resident clips have no containing <sequence>, so it can't be used as a reference for the <start>/<end>/<duration> elements in contained clipitems. Perhaps the contained <file> should be used. It's actually unclear what the difference is between clipitem <in>/<out> and <start>/<end> in this case, since there's no containing timecode reference. Further, <clip>s contain their own <in>/<out> and there's no description of how these relate to contained clipitem <in>/<out> nor which <timecode> reference they relate to. If this should be a contained file, ambiguity sets in when you have L-cuts or merged clipitems from different files.
In fact, the presence of an L-cut in a Browser-resident clip seems to generate quite odd XML exports. Firstly, the offset of the video clipitem is defined in the clip's <in>, not the video clipitem, whose <in> always appears to be 0. Next, the audio clipitem offsets are defined by <in> children of the <audio> element, which otherwise never seems to have <in>/<out> elements, and the audio clipitem's <in> is again always 0. There's actually a bug (in FCP 6.0 anyway); if you have an L-cut that offsets the in-points of each audio track differently, this is lost in the export, it seems to always use the offset of the first audio track for the <in> element in the clip's <audio> element and all audio tracks will re-import with the same in-point.
Anyway, there are other oddities, but I've rambled enough. Does anyone have definitive specs on the semantics of time and timecode elements in FCP XML files?
Thanks, John
|