Why does self.frames = int(seconds * self._int_framerate) ?

[cheng-chi]

Hi Erkan,
Thank you so much for maintaining this convenient timecode package on pip! I'm a Robotics PhD student at Columbia university. My current project requires syncing multiple GoPros using their timecode with a global clock.
After my discucsion with GoPro Lab's maintainer, and my experiments, I believe that the conversion of Timecode from and to float seconds is incorrect.
Let's take 29.97Hz video for example, each frame takes 1/29.97 seconds. Therefore, to convert seconds into frames, we should:

self.frames = int(seconds * float(self.framerate))

Same goes to converting number of frames into seconds:

float(self.frames) / float(self.framerate)

The symptom of this error is that the 29.97Hz drop frame timecode is lexically faster than 30Hz timecode, while in reality, the drop frame operations should make the two timecodes roughly align:

t = 5000
tc = Timecode(framerate='29.97', start_seconds=t)
print(tc, ' 29.97Hz')
# 01:23:24;29  29.97Hz

tc = Timecode(framerate='29.97', frames=round(t*29.97))
print(tc, ' 29.97Hz')
# 01:23:19;29  29.97Hz

tc = Timecode(framerate='30', frames=round(t*30))
print(tc, ' 30Hz')
# 01:23:19:29  30Hz

[eoyilmaz]

Hi @cheng-chi

Whenever somebody disputes about the calculation that I do in this library, I like to use DaVinci Resolve as a calculator to see if I'm doing it correctly , so here are my tests results:

1- I put a 5000 seconds clip (Solid Color) in a 29.97 FPS Drop Frame timeline that starts at 00:00:00;00, the clip ends at 01:23:24;29
2- I put a 5000 seconds clip (Solid Color) in a 30 FPS None Drop Frame timeline that starts at 00:00:00:00, the clip ends at 01:23:19:29
3- I then used Timecode library to see if it is doing it correctly:

>>> from timecode import Timecode
>>> tc1 = Timecode("29.97", start_seconds=5000)
>>> tc2 = Timecode(30, start_seconds=5000)
>>> tc1
01:23:24;29
>>> tc2
01:23:19:29

Exactly matching the DaVinci Resolve result.

Here you can try yourself: Timelines.zip

Coming to your example where you are setting the number of frames in two different timelines with two different frame rates and drop frame schema to two different numbers (149850 and 150000 respectively) to get the same timecode, I'm not sure what is the best way to explain this difference, and I understand your intuation, requsting the same duration in two different timelines should always return the same timecode even if the frame numbers are different, but I guess it is not working in this way when drop frames are getting involved in to the mix...

[eoyilmaz]

Here is a nice explanation why the same requested duration in 29.97 FPS and 30 FPS result in two different "wall-clock" times: https://en.wikipedia.org/wiki/SMPTE_timecode

The altered frame rate meant that an "hour of timecode" at a nominal frame rate of 29.97 frame/s was longer than an hour of wall-clock time by 3.6 seconds (for 29.97 non-drop timecode of 01:00:00:00 drop-frame timecode is 01:00:03;18 and for non-drop 00:59:56:12 drop-frame is 01:00:00;00), leading to an error of almost a minute and a half over a day.[2]

[eoyilmaz]

Maybe your assumption here:

Let's take 29.97Hz video for example, each frame takes 1/29.97 seconds

is the cullprit, as the frames are actually 1/30 seconds but over a certain time or every now and then we drop some frames to have a mean value of close to 1/29.97 seconds per frame duration... This is explained in the aformentioned wikipedia page:

Drop-frame timecode drops 18 of 18,000 frame numbers, equivalent to 1/1000, achieving 30 × 0.999 = 29.97 frame/s.

[mlaurendeau]

Hi @eoyilmaz,

I ran the calculations available at https://pub.smpte.org/pub/eg40/eg0040-2016.pdf, section 6.5.5 "29.97... frames/sec drop frame", and got drop frame timecode 01:23:20:00 for time = 5000 seconds. The tool at https://robwomack.com/timecode-calculator/ provides the same result.

Not sure why I am not getting the same result using this library. Any hint?

[eoyilmaz]

Your calculations is wrong... It is 4995.033 seconds and my Timecode beautifully shows it that way:

from timecode import Timecode
tc = Timecode(framerate="29.97", start_timecode="01:23:20:00")
print(tc.float)  # prints 4995.033333333334
print(tc.frames)  # prints 149851

In many questions like this I use Davinci Resolve as the calculator to see if Timecode is calculating correctly:

And Davinci Resolve beautifully shows that a clip with 149851 frames ends at 01:23:20;00 (01:23:20;01 is the current playhead and the clip ends 1 frame before).

I also created 5 x 1000 second clips (couldn't remember how to enter 5000 seconds clip at once in Davinci Resolve) and it ends at 01:23:24;29:

exactly 4 seconds 29 frames later than the first clip:

Which is also approved by my Timecode library:

>>> tc2 = Timecode(start_seconds=5000, framerate="29.97")
>>> tc2
01:23:24;29

[mlaurendeau]

Please let me know the flaw:

Python 3.11.2 (main, Nov 30 2024, 21:22:50) [GCC 12.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> time = 5000
>>> frame_count = int(time * 30000 / 1001)
>>> frame_count
149850
>>> h = int(frame_count / 107892)
>>> h
1
>>> hours = h % 24
>>> hours
1
>>> minutes = int((frame_count + 2 * int((frame_count - (107892 * h)) / 1800) - 2 * int((frame_count - (107892 * h)) / 18000) - 107892 * h) / 1800)
>>> minutes
23
>>> seconds = int((frame_count - 1798 * minutes - 2 * int (minutes / 10) - 107892 * h) / 30)
>>> seconds
20
>>> frames = frame_count - 30 * seconds - 1798 * minutes - 2 * int(minutes / 10) - 107892 * h
>>> frames
0

The calculations are almost copy-pasted from https://pub.smpte.org/pub/eg40/eg0040-2016.pdf, section 6.5.5 "29.97... frames/sec drop frame", except small adaptations that make them compatible with both python and c++.

[eoyilmaz]

What you are mistaken here is that 29.97 drop frame is not calculated through an approximation of int(time * 30000 / 1001). You see, the drop frame timecode, skips 1 frame (to be correct, it skips 1 timecode) every 1000 frames, and when you calculate the duration through your float division you essentially drop more (or less, my brain is not braining right now) than you actually need to do...

So, if you don't trust Timecode library's calculatiion is correct, trust Davinci Resolve's... which shows the same result...

[mlaurendeau]

int(5000 * 30000 / 1001) counts the number of frames in 5000 seconds. Drop frames do not matter here, they are taken care of in the rest of the calculation.

[mlaurendeau]

The following test:

from timecode import Timecode

prev_hours = -1
prev_minutes = -1
prev_seconds = -1
prev_frames = -1

for frame in range(1, 17984):
    start_seconds = frame * 1001 / 30000
    timecode = Timecode('29.97', start_seconds=start_seconds)
    print(f"{frame} {start_seconds:.3f} {timecode}")
    hours = timecode.hrs
    minutes = timecode.mins
    seconds = timecode.secs
    frames = timecode.frs

    if seconds == 0 and prev_frames == 29:
        if minutes % 10 == 0:
            assert frames == 0
        else:
            assert frames == 2
    elif prev_frames == 29:
        assert frames == 0
    else:
        assert frames == prev_frames + 1

    prev_hours = hours
    prev_minutes = minutes
    prev_seconds = seconds
    prev_frames = frames

fails pretty quickly:

[...]
991 33.066 00:00:33;00
992 33.100 00:00:33;01
993 33.133 00:00:33;02
994 33.166 00:00:33;03
995 33.200 00:00:33;04
996 33.233 00:00:33;05
997 33.267 00:00:33;06
998 33.300 00:00:33;07
999 33.333 00:00:33;08
1000 33.367 00:00:33;10
Traceback (most recent call last):
  File "/home/mlaurendeau/Ateme/venv/timecode/./tc.py", line 25, in <module>
    assert frames == prev_frames + 1
           ^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError

'00:00:33;09' is unexpectedly skipped. I get 1 frame offset when converting this timecode to frames and then back to timecode:

Python 3.11.2 (main, Nov 30 2024, 21:22:50) [GCC 12.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> from timecode import Timecode
>>> tc1 = Timecode('29.97', '00:00:33;09')
>>> tc1.frames
1000
>>> tc2 = Timecode('29.97', start_seconds=1000 * 1001 / 30000)
>>> tc2.frames
1001
>>> tc2
00:00:33;10
>>> 

[mlaurendeau]

Also it looks strange that start_seconds=0 is not allowed, it should yield 00:00:00;00.

[eoyilmaz]

'00:00:33;09' is unexpectedly skipped. I get 1 frame offset when converting this timecode to frames and then back to timecode:

I think you don't understand the concept of drop frame... 00:00:33;09 is skipped (and 1 every other 1000 frames in this case) because this is a 29.97 fps dropframe Timecode. The reason behind using drop frames is to match the Timecode (which is a unique label given to each frame) of a 30 fps timeline and 29.97 fps timeline at every 24h, to eliminate the inherint offset created by the difference in the fps... There are many sources you can read about this in detail...

Also it looks strange that start_seconds=0 is not allowed, it should yield 00:00:00;00.

Again, another misconception here... I updated the Readme to explain this in more detail:

Note

A common misconception is that 00:00:00:00 should have 0 frames. This is wrong
because Timecode is a label given for each frame in a media, and it happens to be
using numbers which are seemingly incremented one after another. So, for a Timecode to
exist there should be a frame. and 00:00:00:00 is generally the label given to the
first frame.

I'm keeping this issue ticket open as a courtesy, otherwise I don't see any issues to be solved here...

[matlo]

Quote from the wikipedia page you linked earlier, right after the paragraph you mentioned:

To correct this, drop-frame SMPTE timecode was invented. In spite of what the name implies, no video frames are dropped or skipped when using drop-frame timecode. Rather, some of the timecodes are dropped. In order to make an hour of timecode match an hour on the clock, drop-frame timecode skips frame numbers 0 and 1 of the first second of every minute, except when the number of minutes is divisible by ten.[a] This causes timecode to skip 18 frames each ten minutes (18,000 frames @ 30 frame/s) and almost perfectly compensates for the difference in rate (but still accumulates 1 frame every 9 hours 15 minutes).[b][3]

(the same guy commenting with non-professional account)

[matlo]

Also it looks strange that start_seconds=0 is not allowed, it should yield 00:00:00;00.

Again, another misconception here... I updated the Readme to explain this in more detail:

No misconception here. It is usual to start numbering frames at 0, and to place first frame at time = 0 seconds on a timeline. First frame starts at time = 0 seconds, second frame at (1 / frequency) seconds, third frame at (2 / frequency) seconds, and so on. The name "start_seconds" is misleading if a number of frames as seconds is expected, 'start' usually refers to a point in time, not to a duration (a number of frames is a duration).

Let's summarise my previous observations:

• your implementation does not give the same results as the calculation provided by the engineering guideline of the SMPTE itself
• your implementation drops timecodes that are not expected to be dropped

Moreover your implementation does not give the same result as the code by David Heidelberger linked in the readme. And the code by David Heidelberger gives the same results as the SMPTE engineering guideline:

• frame number (numbering starts at 0) 149850 yields timecode 1:23:20:0: https://onlinegdb.com/NqRwIJfuG
• timecode 1:23:20:0 yields frame number 149850: https://onlinegdb.com/70bNv0rTY

[cubicibo]

No misconception here. It is usual to start numbering frames at 0, and to place first frame at time = 0 seconds on a timeline. First frame starts at time = 0 seconds, second frame at (1 / frequency) seconds, third frame at (2 / frequency) seconds, and so on. The name "start_seconds" is misleading if a number of frames as seconds is expected, 'start' usually refers to a point in time, not to a duration (a number of frames is a duration).

Not really. A reference display device requires $fps^{-1}$ to display a frame. The normative SMPTE 12M-1 document does not state what is the right reference timestamp. It could be when the system starts to draw the frame, or when the system displays the frame. Furthermore, a camera captures incoming light for $fps^{-1}$ seconds to produce a frame, some may argue the time of the first frame shall not be zero, as it is physically incorrect.

'00:00:33;09' is unexpectedly skipped. I get 1 frame offset when converting this timecode to frames and then back to timecode

It's silly, the problem is simply the value being rounded up! If you truncate your float to avoid rounding at the N-th decimal, then everything works out.

>>> def truncate(f, n): return math.floor(f * 10 ** n) / 10 ** n
>>>
>>> tc2 = Timecode('29.97', start_seconds=truncate(1000 * 1001 / 30000, 5))
>>> tc2 
00:00:33;09

[cubicibo]

SMPTE EG40 is absolutely not safe from rounding errors either. I get discrepancies if I parrot §6.5.5 and test with time=1.001 or frame_count=30.

>>> hf = lambda fr, h : int(1/1800 * (fr+2*int((fr - 107892*h)/1800) - 2*int((fr - 107892*h)/1800) - 107892*h))
>>> sf = lambda fr, h, m : int((1/30)*(fr - 1798*m - 2*int(m/10)-107892*h))
>>> ff = lambda fr, s, m, h : fr - 30*s - 1798*m - 2*int(m/10) - 107892*h
>>>
>>> def smpte_eg40_30df_frame(frame_count: int) -> str:
    """
    Convert a frame count to the corresponding Timecode (29.97 DF)
    """
     h = int(frame_count/(30*60*60-108)); m = hf(frame_count, h)
     s = sf(frame_count, h, m);           f = ff(frame_count, h, m, s)
     return f"{(h % 24):02}:{m:02}:{s:02};{f:02}"

>>> def smpte_eg40_30df(time: float) -> str:
     """
     Convert the wall clock time to a Timecode by first converting to a frame count  (29.97 DF)
     """
     frame_count = int(30*1000/1001*time)
     return smpte_eg40_30df_frame(frame_count)

>>> smpte_eg40_30df(time=1.001) # 30 frames fully elapse in one NTSC second @ 29.97
00:00:00;29
>>> smpte_eg40_30df_frame(frame_count=30) # frame_count is the count of fully elapsed frames
00:00:01;00 
>>> smpte_eg40_30df(time=1.001 + 1e-10) # ...
00:00:01;00