Confused by wall clock vs. timecode

[wzph]

Howdy, and thanks to @orchetect for this library 👍. I'm starting this discussion because I think I must lack some knowledge of timecodes and how they relate to wall-clock time, and I'm hopeful somebody here can set me straight.

Consider the following snippet.

import Foundation
import TimecodeKit

var max = TimecodeFrameRate.allCases.map({ $0.rawValue.count }).max()
guard let max else { exit(1) }

for fps in TimecodeFrameRate.allCases {
    let tc = try Timecode(.realTime(seconds: 1), at: fps)

    let pad = String(repeating: " ", count: max - fps.rawValue.count)
    let fpsString = fps.rawValue
    let tcString = tc.stringValue(format: .showSubFrames)
    print("\(pad)\(fpsString):\t\(tcString)")
}

And its output.

 23.976:	00:00:00:23.97
     24:	00:00:01:00.00
  24.98:	00:00:00:24.97
     25:	00:00:01:00.00
  29.97:	00:00:00:29.97
 29.97d:	00:00:00;29.97
     30:	00:00:01:00.00
    30d:	00:00:01;00.00
 47.952:	00:00:00:47.95
     48:	00:00:01:00.00
     50:	00:00:01:00.00
  59.94:	00:00:00:59.94
 59.94d:	00:00:00;59.94
     60:	00:00:01:00.00
    60d:	00:00:01;00.00
 95.904:	00:00:00:95.90
     96:	00:00:01:00.00
    100:	00:00:01:00.00
 119.88:	00:00:00:119.88
119.88d:	00:00:00;119.88
    120:	00:00:01:000.00
   120d:	00:00:01;000.00

You'll notice that with one second of realTime, the only stringValues that start with 00:00:01 are those for integer TimecodeFrameRates. I assume this is because of the difference between video framerate and timecode framerate, as explained in this project's comments and elsewhere. However, it's unclear to me, when the "ps" in "fps" means "per second," why 1 second wouldn't increment the seconds component for all framerates, integer and non-integer alike.

If this is is too rudimentary or if there's a better place to ask this, please let me know.

Thanks again.

[orchetect]

Thanks for the post - it's a good question. It's explained in the documentation but due to the nuanced nature of timecode it can be a head-scratcher even for the experienced in the field.

Timecode is not time. Timecode seconds are not wall-clock seconds. That is why a conversion is necessary between the two completely different domains.

TimecodeFrameRate is essentially: fps == frames per Timecode second.
VideoFrameRate is essentially: fps == frames per wall-time second.

In a nutshell, for fractional rates and drop-frame rates, the time values themselves will not align because 1 Timecode second will be slightly shorter than 1 actual second of wall time if you were to overlay the two domains. So your code (and log output) is correct.

There are long and very technical reasons for this, and if you want some very dry bedtime reading you can read about SMPTE Timecode and why fractional rates and drop-frame exists.

At certain rates it may appear that hours, minutes, and seconds in both domains correspond. However this is not necessarily true as in many cases there is actual very slight drift between the two domains even if it's seemingly inconsequential. So some are led to use timecode (say, at 30 fps) in place of real time or see them as interchangeable, but it is generally bad practise.

The purpose of this library is to try and make working with timecode and conversions simple (and correct).

And also, if it is not totally clear:

Timecode(.realTime(seconds: 1), at: fps) // converts 1 second of real time to timecode
Timecode(.components(h: 0, m: 0, s: 1, f: 0), at: fps) // 1 explicit second of timecode

[wzph]

Thanks so much for your response. I need to dig into SMPTE and learn more.

Timecode seconds are not wall-clock seconds

But it appears that they are the same for non-fractional rates. I think that's what tripped me up.

[orchetect]

But it appears that they are the same for non-fractional rates. I think that's what tripped me up.

Yes, whole frame rates tend to appear to align with real time. The reason why it's called 'timecode' and not 'timestamp' or 'time' is that timecode is an encoding. It's based on total elapsed frame count. In whole frame rates, the frame count works out to a timecode that is consistent with real time. In fractional rates, it does not.

Consider that all of the following are equal durations of real time. You can see that the longer the time has elapsed, the more that timecode and real time drift apart.

- 20 hours real time
- 20:00:00:00.00 @ 30 fps
- 19:58:48:02.15 @ 29.97 fps