Software Documentation

Software Documentation


Last updated: November 14, 2023

8 The “Analyze timecode in soundtrack file…” function for SMPTE and FSK

The analyze timecode dialog and its timecode log file show you a summary and the actual timecode frames that are in a song file or that have been received as timecode input from an external source.  For song files, the summary is convenient for many everyday uses since a human can’t tell from looking at the waveform or listening to the timecode channel of an audio file what the timecode range of the song is.  For song files and for timecode input, the log file is useful for debugging, answering such questions as whether the timecode signal has any jumps or glitches, how long it should take a device to lock onto the timecode, is its frame rate consistent, when does it start or end, etc.

The “File > Tools > Analyze timecode in soundtrack file…” function works for all firing system versions of FSK (see FSK) and for all the common variations of SMPTE (see SMPTE).  The function examines the file, testing whether it contains valid timecode in any of the timecode formats.


Alignment on the timeline

The timecode information dialog looks like the dialog of Figure 1.  If you use the function, “File > Tools > Analyze timecode in soundtrack file…”, you’ll get a dialog that looks like this for any song file you choose, WAV for MP3.  The dialog confirms that the song file actually does contain a timecode signal, and tells you what channel it is on.


Figure 1 – The best alignment for the song is usually — but not always — the same as its first frame time.


The dialog tells you the best alignment for the song on the timeline.  Usually, the best alignment for the song on the timeline is the time of the first frame in the timecode signal, but depending on how the song file was created, that may not be the case.

The timecode signal in the file may not start at exactly the beginning of the file, and may not start with a valid frame.   If the timecode channel was cropped to a timecode range and copy / pasted into the song in an audio editor, there’s a good chance that the first frame may be partially clipped and thus invalid.  There’s also a chance that a copy / pasted timecode signal might not be pasted at the exact beginning of the song.  In all these scenarios, the first valid frame of the timecode might not correspond to the beginning of the file.

Imagine that the first frame of the timecode is 04:00:00:00 but that the timecode channel happened to be pasted at an offset 1 minute into the song.  Then the proper alignment of the song based on its timecode would be 4 hours minus 1 minute, or 03:59:00:00.  Importing the song at that position on the timeline causes its 04:00:00:00 frame to align with exactly 4 hours on the timeline.


Alignment of FSK

The firing system versions of FSK follow de facto alignment conventions specific to each firing system.  As described in FSK, the conventions do not match up the data packets to the times they represent exactly to the millisecond.  They are a little bit off.  Depending on the firing system, the data packets in the FSK end anywhere from 0 ms to 100 ms earlier than the times the data packets are meant to represent.

The analyze timecode dialog and its log file show the actual alignment of the data packets in the examined file, but the “Best alignment on timeline” shown in the dialog and used to align songs when importing them is adapted to keep consistent with the firing system reference FSK files:  If the calculated data packet alignment is less than or equal to 100 ms, the “Best alignment on timeline” is taken to be simply, “Beginning of timeline” rather than the actual delta necessary to align the data packets to the times they represent.   That’s what you want, so that’s “best.”


Frame rate and drop frame

SMPTE timecode doesn’t contain the frame rate in its encoded data explicitly, but it does contain a flag indicating whether the encoded frames are counted using the drop frame system (DF) nor non-drop frame (NDF), as explained in Timecode frame rates and drop frame.  The frame rate of SMPTE timecode is implicitly the frequency of the frames in the encoded signal.  The dialog of Figure 1 displays the frame rate and DF/NDF for song files based on this information.

For timecode input from an external source that comes into the computer as MIDI MTC timecode, Finale 3D displays the same information but it comes from a different calculation.  A MIDI MTC signal does contain an explicit frame rate in its encoded data, which Finale 3D uses, but it does not contain an explicit drop frame flag.  Finale 3D determines the drop frame system of MIDI MTC timecode input based on the frame rate (inferring that any frame rate other than 29.97 fps is NDF) and based on the presence or absence of the frame numbers that don’t exist in the drop frame counting system.


Bad frames, jumps, and pauses

Since timecode can be added to a song file using an audio editor, there’s no guarantee that the timecode signal starts at the beginning, or is contiguous.  A sound track can be constructed in an audio editor that has different sections with different timecode ranges in them and gaps in between.  The timecode ranges may not even be in chronological order.

When Finale 3D reads the timecode of a song file, it keeps track of the number of gaps in the timecode frame sequence, and of discontinuous jumps.  Finale 3D also keeps track of the number of bad frames, which are frames that are corrupted or whose encoded times are clearly not part of any progressing sequence of frames.  It is not uncommon to see frames with times of 30:00:00:00 or 00:00:00:00 in the middle of a timecode sequence that is nowhere near 30 hours or the beginning of the show, depending on the quality of the encoded timecode signal.

You may have no idea where the timecode signal in a file or from an external source originated — a copy /pasted WAV file?  A file that has been compressed as an MP3?  A hardware device?  A recorded or broadcasted audio signal?  The bad frame count in the timecode information dialog gives you an idea of the quality of the signal.

Since most firing systems and other production hardware devices lock on and track to a timecode signal while using an internal clock to provide smooth playback, the presence of bad frames in the timecode signal is not necessarily alarming.  Look at the count of jumps and pauses.  If those numbers align with your expectations, then the timecode signal is probably fine even if it has hundreds of bad frames.  But the bad frames may be a reason for you to investigate further.


Timecode log file

The timecode log file shows the actual frames encoded in the song file or received as input.  The file may be long, as even 20 minutes of 30 fps is 36000 frames.  An excerpt from a log file is shown in Figure 2.


// Format: [timestamp] (deltas from last msg: timestamp, frame) received msg HH:MM:SS:FF @ received frame rate + timecode input offset -- > interpretation
[0.018] (+0 +0) 00:00:59:28 @ 30 fps NDF + 0ms -- > 00:00:59:28 30 fps NDF < non-tracking >
[0.052] (+34 +94) 00:00:59:29 @ 29.97 fps NDF + 0ms -- > 00:00:59:29 29.97 fps NDF < non-tracking >
[0.085] (+33 +33) 00:01:00:00 @ 29.97 fps NDF + 0ms -- > 00:01:00:00 29.97 fps NDF < non-tracking >
[0.118] (+33 +33) 00:01:00:01 @ 29.97 fps NDF + 0ms -- > 00:01:00:01 29.97 fps NDF < non-tracking >
[0.152] (+34 +34) 00:01:00:02 @ 29.97 fps NDF + 0ms -- > 00:01:00:02 29.97 fps NDF < non-tracking >
[0.185] (+33 +33) 00:01:00:03 @ 29.97 fps NDF + 0ms -- > 00:01:00:03 29.97 fps NDF < non-tracking >
[0.218] (+33 +33) 00:01:00:04 @ 29.97 fps NDF + 0ms -- > 00:01:00:04 29.97 fps NDF < non-tracking >
[0.252] (+34 +34) 00:01:00:05 @ 29.97 fps NDF + 0ms -- > 00:01:00:05 29.97 fps NDF < locking >
[0.285] (+33 +33) 00:01:00:06 @ 29.97 fps NDF + 0ms -- > 00:01:00:06 29.97 fps NDF
[0.318] (+33 +34) 00:01:00:07 @ 29.97 fps NDF + 0ms -- > 00:01:00:07 29.97 fps NDF
[0.352] (+34 +33) 00:01:00:08 @ 29.97 fps NDF + 0ms -- > 00:01:00:08 29.97 fps NDF

Figure 2 – Example log file

The log file lines begin with the time stamp of each received message (frame), followed by the time deltas from the previous message measured in real world time and in the difference between the HH:MM:SS:FF encoded times in the messages.  If those two time deltas are exactly the same, then the encoded timecode frame sequence is progressing in synch with real world time.

In practice, the time deltas aren’t always in synch exactly, for a number of reasons including latency and burstiness in the timecode event processing for timecode input from an external signal.  The second message in Figure 2 is an example in which the deltas between the times represented by the frames are not the same (+34 versus +94 milliseconds).  But if you compare the frames 00:00:59:28 to 00:00:59:29, that would seem to be a single frame difference, or about 33ms.  Where did the +94 come from?

Looking more carefully at the first and second messages, the first message is interpreted to be at 30 fps, whereas the second message at 29.97 fps.  Recall that SMPTE timecode does not contain an explicit frame rate in the encoded signal.  The frame rate is determined based on the frequency of the encoded frames in the signal.  The difference between 29.97 fps and 30 fps isn’t much, so after a single frame, the signal doesn’t yet contain enough precision for the reader to ascertain the frequency exactly.  It happens, in this example, that the reader interprets the first frame as 30 fps, and the second (more accurately) as 29.97 fps.  The real world time of 00:00:59:28 in 30 fps is 59.933 ms.  The real world time of 00:00:59:29 in 29.97 fps is 60.026 ms.  The difference?  94 ms.

To the right of the arrow is the interpretation of the frame, which begins the same as the frame payload itself for song files.  For MIDI MTC timecode input, the interpretation includes the DF/NDF determination that is not present to the left of the arrow (not shown in this example).

The bracketed comment in the interpretation, such as <non-tracking> and <locking> show how the timecode reader interprets the frame in the context of the surrounding sequence of frames.  You can see that it takes a few received frames for the timecode reader to lock onto the sequence.  Other hardware devices may take more or fewer frames to lock on but follow a similar sort of pattern.  Other comments such as <bad> and <jump> and longer comments for timecode input like <pausing because no messages in XXX ms> are also possible.