GetTimeCode
GetTimeCode(srcClip, timeCode, frameRate, dropFrame)
Additional Notes
This function has a problem with timecode when used on clip1 (I hope this isn't a feature). As of FCP 3.02, clip1 always returns the framerate of the current timeline regardless of the clip's native framerate. A PAL clip dragged into the timeline reports 30fps(29.97), while the same clip dragged into a clip input well reports 25fps. Since GetTimeCode is supposed to be reporting on the fundamental, independent attributes of a clip, this seems like a bug. Also, this behavior is not able to be reproduced in FXBuilder when testing scripts.
After further research, I don't think it's a bug, but rather a fundamental way in which FCP understands clips. When a clip is placed into a timeline, it's framerate is interpreted up or down to the timeline framerate. The duration in seconds remains fixed, but the number of frames used to represent that timing is modified. Any FXScript Clip Functions called for clip1 (the clip the effect is applied to) will be based on the interpreted values rather than the clip's native values.
Clips dragged onto FXScript Input wells will retain their native framerates.
The result of GetTimeCode will drift over time for interlaced timelines. To workaround that, subtract half of frame. Better still, divide by fieldProcessing+1 and skip worrying about if/else conditional statements. The following works:
float clipTC, clipFR, clipDF ;
GetTimecode(clip1, clipTC, clipFR, clipDF);
clipTC -= frame/(fieldProcessing+1);
The resulting value, when formatted with k30fps correctly aligns to NTSC timecode information.
GetTimeCode returns three values based on the timecode of the source clip. All three values are floating point values.
Timecode is the framecount of the clip. When this is formatted to match the source frame rate the current frame's timecode is displayed.
FrameRate is the playback fps of the source clip. This value is one of the few places in FCP where NTSC's 29.97 frame rate is reported without modification. It's also one of the only places where values round up. When changed to an integer, frameRate will round up to 30.
DropFrame is a boolean value indicating whether the source clip uses drop frame timecode or not. A value of 1 (true) indicates that the timecode value is drop frame. FCP recognizes 30fps and 60fps drop frame values. See formatting constants for other possible formats.
As of FCP 3, GetTimeCode only appeared in the Timecode Print video filter. I used this for reporting the current frame's timecode values in Joe's Time Bender.