| Thanks very much Helena. It sounds like the heuristics I'd guessed at were generally right. You mention the start timecode defaults in the absence of an obvious <timecode> element, presumably the owning-element's frameRate & NTSC flag are used and I guess the TC display would default to drop-frame for NTSC and non-drop-frame for all others?
I had noticed the multiple-<timecode> element issue and I'm providing a way to use the default or select an alternate (aux1, aux2, etc.) when working with timecode-based times. Thanks for the info about <primarytimecode>, hadn't seen that yet.
The only thing I'm still a little unclear on is the relationships of the various <in>/<out> children in the browser-resident <clip>s. It looks like the <clip> has <in>/<out>, but so do the contained <audio> and <clipitem> elements. How do they relate? It looks like the <clip>.<in>/<out> defines the video clipitem in-point, and <audio>.<in>/<out> define the audio clipitem in-points, and <video> has no <in>/<out> and all the <clipitem>.<in>/<out> always span the media of the enclosed <file>. This is not how the exact same clip in a sequence looks - the video and audio <clipitem>.<in>/<out>s are definitive, I guess as I would expect. Is this difference between clip and sequence-resident timing info how it's supposed to be?
Anyway, thanks again for all the info. I'll post details of the scripting kit as it gets closer to completion.
Cheers, John.
On Jun 25, 2007, at 4:42 PM, Helena Ju wrote: Hi John,The document you're asking for really doesn't exist, but let me try to answer your questions. Sounds like you've already discovered most of these, but hopefully this will help.
On Jun 25, 2007, at 2:28 PM, John Wainwright wrote: 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.
Yes. I absolutely agree that it is very confusing. Here are the basic rules: start/end indicate when in the sequence this particular item starts and ends. These are in the timebase of the containing sequence. Converting them to timecode values, one should use timecode in the containing <sequence> or for browser clips on the <file> of the containing <clip>.
in/out indicate at what point in the media the item begins and ends. These are in the timebase of the item. One can use the starting <timecode> of the file within the item if there is one. Times start from 00:00:00:00 on media without timecodes and 01:00:00:00 on sequences by default, though users can change this.
As you noticed, for basic clips there aren't actually any differences from the in/out keys start/end keys on the clip. In this case the data you're looking for is on the containing <clip>'s <file>. (as you noted above).
As to the starting timecode that is used.... if there is only one defined on the <file> then that is easy, use that. If there is more than one (like source, aux1, aux2) look for: <clipitem> ... <primarytimecode>aux1</primarytimecode> if it is NOT there, the default is always source, so FCP is using the <timecode> with <source>source</source> on it.
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.
Ah, good point. I've written that one up. Here is a reference number for the bug 5293721. 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
Cheers, Helena |