The timecode is processed along with the frames. If the source contains the timecode, the SDK works with the data. If the source doesn't have timecode data it is generated from 0.
Get timecode information
The start timecode of a file is kept in the "file::start_timecode" property for an MFile object and in the "start_timecode" object for an MFReader object. The resulting value indicates the type of drop- and non-drop-frame timecode. For example, "01:02:03:04" means non-drop-frame timecode, and "01:02:03;04" means drop-frame timecode.
The current frame timecode
The timecode information is kept in the M_TIME structure. You can get the time information with the FrameTimeGet method (MPlatform SDK) and with the MFTimeGet method (MFormats SDK). Both methods return you the M_TIME structure. The timecode information is in the tcFrame field which is a M_TIMECODE structure. The structure contains the eTCFlags field that has one or multiple eMTimecodeFlags flags that indicate the timecode type.
Seeking by timecode
You can set a playback position for a file with the FilePosSetTC method with the desired timecode specified. You can cue the file playback by setting the in- and out- points by timecode with the FileInOutSetTC method.
To set the target timecode position, use the "tc_pos" property:
Once the property is set, the seeking is processed with the next requested frame. So the next SourceFrameGet (or -ConvertedGet) method returns you a frame with the specified timecode. If the timecode is incorrect it returns you the 1st frame.
If the source frames contain the timecode data the data is encoded for the containers that support the timecode track (MOV, MXF, for instance). To specify a custom timecode, you can use the "start_timecode" attribute in the encoding configuration. The possible values are:
- auto (default) - it uses the original timecode from the source
- disabled - the timecode is disabled for encoding
- local_time - aligns the start timecode with the local system time
- custom string like "10:00:00:00" - use the specific value as the start timecode.
High frame rates and timecode
Based on the SMPTE 12M Timecode standard, the maximal value for the frame number in the timecode is 30:
"Section 12 has been added to document time code implementations for video formats with frame per second rates greater than 30 fps."
"12.1 Time Address of a Frame Pair in 50 and 60 Frames-Per-Second Progressive Systems
Since the frame rate of 50 and 60 frames-per-second progressive systems exceeds the frame count capacity of the time address, the count shall be constrained to increment only every other frame (as shown in Figure 9). This results in an edit resolution of two frames"
If the source frame rate is greater than 30, the timecode value is split into two parts that are marked with the eMTCF_Progressive_Odd_Frame and the eMTCF_Progressive_Even_Frame flags. The even frame has both flags, the odd frame has the ...Even_Frame flag only.
Here are some examples for the timecode calculations for a 50p file:
00:06:35:15.0 = 00:06:35:(15 * 2 + 0) = 00:06:35:30
00:06:35:15.1 = 00:06:35:(15 * 2 + 1) = 00:06:35:31
00:06:35:16.0 = 00:06:35:(16 * 2 + 0) = 00:06:35:32
00:06:35:16.1 = 00:06:35:(16 * 2 + 1) = 00:06:35:33
00:06:35:17.0 = 00:06:35:(17 * 2 + 0) = 00:06:35:34
00:06:35:17.1 = 00:06:35:(17 * 2 + 1) = 00:06:35:35
In the SDK, the even frames are marked with ".0" suffix, the odd frames are marked with the ".1".