[timecode] Use fractions for internal framerate representation

Author: Breakthrough

scenedetect/common.py

@@ -92,8 +92,8 @@
 TimecodePair = ty.Tuple["FrameTimecode", "FrameTimecode"]
 """Named type for pairs of timecodes, which typically represents the start/end of a scene."""
 
-MAX_FPS_DELTA: float = 1.0 / 100000
-"""Maximum amount two framerates can differ by for equality testing."""
+MAX_FPS_DELTA: float = 1.0 / 1000000000.0
+"""Maximum amount two framerates can differ by for equality testing. Currently 1 frame/nanosec."""
 
 _SECONDS_PER_MINUTE = 60.0
 _SECONDS_PER_HOUR = 60.0 * _SECONDS_PER_MINUTE
@@ -160,13 +160,14 @@ class FrameTimecode:
     def __init__(
         self,
         timecode: ty.Union[int, float, str, Timecode, "FrameTimecode"] = None,
-        fps: ty.Union[int, float, str, "FrameTimecode"] = None,
+        fps: ty.Union[float, "FrameTimecode", Fraction] = None,
     ):
         """
         Arguments:
             timecode: A frame number (`int`), number of seconds (`float`), timecode string in
                 the form `'HH:MM:SS'` or `'HH:MM:SS.nnn'`, or a `Timecode`.
-            fps: The framerate or FrameTimecode to use as a time base for all arithmetic.
+            fps: The framerate to use for distance between frames and to calculate frame numbers.
+                For a VFR video, this may just be the average framerate.
         Raises:
             TypeError: Thrown if either `timecode` or `fps` are unsupported types.
             ValueError: Thrown when specifying a negative timecode or framerate.
@@ -175,7 +176,7 @@ def __init__(
         # in a frame-specific manner.  Note that once the framerate is set,
         # the value should never be modified (only read if required).
         # TODO(v1.0): Make these actual @properties.
-        self._framerate = fps
+        self._framerate: Fraction = None
         self._frame_num = None
         self._timecode: ty.Optional[Timecode] = None
         self._seconds: ty.Optional[float] = None
@@ -188,25 +189,31 @@ def __init__(
             self._seconds = timecode._seconds
             return
 
-        # Timecode.
-        if isinstance(timecode, Timecode):
-            self._timecode = timecode
-            return
+        if not isinstance(fps, (float, Fraction, FrameTimecode)):
+            raise TypeError("fps must be of type float, Fraction, or FrameTimecode.")
 
         # Ensure args are consistent with API.
         if fps is None:
-            raise TypeError("Framerate (fps) is a required argument.")
+            raise TypeError("fps is a required argument.")
         if isinstance(fps, FrameTimecode):
-            fps = fps._framerate
-
-        # Process the given framerate, if it was not already set.
-        if not isinstance(fps, (int, float)):
-            raise TypeError("Framerate must be of type int/float.")
-        if (isinstance(fps, int) and not fps > 0) or (
-            isinstance(fps, float) and not fps >= MAX_FPS_DELTA
-        ):
-            raise ValueError("Framerate must be positive and greater than zero.")
-        self._framerate = float(fps)
+            self._framerate = fps._framerate
+        elif isinstance(fps, float):
+            if fps <= MAX_FPS_DELTA:
+                raise ValueError("Framerate must be positive and greater than zero.")
+            self._framerate = Fraction.from_float(fps)
+        elif isinstance(fps, Fraction):
+            if float(fps) <= MAX_FPS_DELTA:
+                raise ValueError("Framerate must be positive and greater than zero.")
+            self._framerate = fps
+        else:
+            raise TypeError(
+                f"Wrong type for fps: {type(fps)} - expected float, Fraction, or FrameTimecode"
+            )
+
+        # Timecode with a time base.
+        if isinstance(timecode, Timecode):
+            self._timecode = timecode
+            return
         # Process the timecode value, storing it as an exact number of frames only if required.
         if isinstance(timecode, str) and timecode.isdigit():
             timecode = int(timecode)
@@ -243,7 +250,7 @@ def frame_num(self) -> ty.Optional[int]:
 
     @property
     def framerate(self) -> ty.Optional[float]:
-        return self._framerate
+        return float(self._framerate)
 
     def get_frames(self) -> int:
         """[DEPRECATED] Get the current time/position in number of frames.

tests/test_timecode.py

@@ -25,6 +25,7 @@
 
 # Standard Library Imports
 from scenedetect.common import MAX_FPS_DELTA, FrameTimecode
+from fractions import Fraction
 
 
 def test_framerate():
@@ -38,11 +39,11 @@ def test_framerate():
         FrameTimecode(timecode=None, fps=FrameTimecode(timecode=0, fps=None))
     # Test zero FPS/negative.
     with pytest.raises(ValueError):
-        FrameTimecode(timecode=0, fps=0)
+        FrameTimecode(timecode=0, fps=0.0)
     with pytest.raises(ValueError):
-        FrameTimecode(timecode=0, fps=-1)
+        FrameTimecode(timecode=0, fps=-1.0)
     with pytest.raises(ValueError):
-        FrameTimecode(timecode=0, fps=-100)
+        FrameTimecode(timecode=0, fps=-100.0)
     with pytest.raises(ValueError):
         FrameTimecode(timecode=0, fps=0.0)
     with pytest.raises(ValueError):
@@ -52,26 +53,28 @@ def test_framerate():
     with pytest.raises(ValueError):
         FrameTimecode(timecode=0, fps=MAX_FPS_DELTA / 2)
     # Test positive framerates.
-    assert FrameTimecode(timecode=0, fps=1).frame_num == 0
-    assert FrameTimecode(timecode=0, fps=MAX_FPS_DELTA).frame_num == 0
-    assert FrameTimecode(timecode=0, fps=10).frame_num == 0
+    assert FrameTimecode(timecode=0, fps=1.0).frame_num == 0
+    assert FrameTimecode(timecode=0, fps=10.0).frame_num == 0
     assert FrameTimecode(timecode=0, fps=MAX_FPS_DELTA * 2).frame_num == 0
-    assert FrameTimecode(timecode=0, fps=1000).frame_num == 0
     assert FrameTimecode(timecode=0, fps=1000.0).frame_num == 0
+    assert FrameTimecode(timecode=0, fps=1000.0).frame_num == 0
+    # Reject framerates too small for equality testing or potential divide by zero situations.
+    with pytest.raises(ValueError):
+        assert FrameTimecode(timecode=0, fps=MAX_FPS_DELTA).frame_num == 0
 
 
 def test_timecode_numeric():
     """Test FrameTimecode constructor argument "timecode" with numeric arguments."""
     with pytest.raises(ValueError):
-        FrameTimecode(timecode=-1, fps=1)
+        FrameTimecode(timecode=-1, fps=1.0)
     with pytest.raises(ValueError):
         FrameTimecode(timecode=-1.0, fps=1.0)
     with pytest.raises(ValueError):
         FrameTimecode(timecode=-0.1, fps=1.0)
     with pytest.raises(ValueError):
         FrameTimecode(timecode=-1.0 / 1000, fps=1.0)
-    assert FrameTimecode(timecode=0, fps=1).frame_num == 0
-    assert FrameTimecode(timecode=1, fps=1).frame_num == 1
+    assert FrameTimecode(timecode=0, fps=1.0).frame_num == 0
+    assert FrameTimecode(timecode=1, fps=1.0).frame_num == 1
     assert FrameTimecode(timecode=0.0, fps=1.0).frame_num == 0
     assert FrameTimecode(timecode=1.0, fps=1.0).frame_num == 1
 
@@ -80,13 +83,13 @@ def test_timecode_string():
     """Test FrameTimecode constructor argument "timecode" with string arguments."""
     # Invalid strings:
     with pytest.raises(ValueError):
-        FrameTimecode(timecode="-1", fps=1)
+        FrameTimecode(timecode="-1", fps=1.0)
     with pytest.raises(ValueError):
         FrameTimecode(timecode="-1.0", fps=1.0)
     with pytest.raises(ValueError):
         FrameTimecode(timecode="-0.1", fps=1.0)
     with pytest.raises(ValueError):
-        FrameTimecode(timecode="1.9x", fps=1)
+        FrameTimecode(timecode="1.9x", fps=1.0)
     with pytest.raises(ValueError):
         FrameTimecode(timecode="1x", fps=1.0)
     with pytest.raises(ValueError):
@@ -95,56 +98,56 @@ def test_timecode_string():
         FrameTimecode(timecode="1.0-", fps=1.0)
 
     # Frame number integer [int->str] ('%d', integer number as string)
-    assert FrameTimecode(timecode="0", fps=1).frame_num == 0
-    assert FrameTimecode(timecode="1", fps=1).frame_num == 1
+    assert FrameTimecode(timecode="0", fps=1.0).frame_num == 0
+    assert FrameTimecode(timecode="1", fps=1.0).frame_num == 1
     assert FrameTimecode(timecode="10", fps=1.0).frame_num == 10
 
     # Seconds format [float->str] ('%f', number as string)
-    assert FrameTimecode(timecode="0.0", fps=1).frame_num == 0
-    assert FrameTimecode(timecode="1.0", fps=1).frame_num == 1
+    assert FrameTimecode(timecode="0.0", fps=1.0).frame_num == 0
+    assert FrameTimecode(timecode="1.0", fps=1.0).frame_num == 1
     assert FrameTimecode(timecode="10.0", fps=1.0).frame_num == 10
     assert FrameTimecode(timecode="10.0000000000", fps=1.0).frame_num == 10
     assert FrameTimecode(timecode="10.100", fps=1.0).frame_num == 10
     assert FrameTimecode(timecode="1.100", fps=10.0).frame_num == 11
 
     # Seconds format [float->str] ('%fs', number as string followed by 's' for seconds)
-    assert FrameTimecode(timecode="0s", fps=1).frame_num == 0
-    assert FrameTimecode(timecode="1s", fps=1).frame_num == 1
+    assert FrameTimecode(timecode="0s", fps=1.0).frame_num == 0
+    assert FrameTimecode(timecode="1s", fps=1.0).frame_num == 1
     assert FrameTimecode(timecode="10s", fps=1.0).frame_num == 10
     assert FrameTimecode(timecode="10.0s", fps=1.0).frame_num == 10
     assert FrameTimecode(timecode="10.0000000000s", fps=1.0).frame_num == 10
     assert FrameTimecode(timecode="10.100s", fps=1.0).frame_num == 10
     assert FrameTimecode(timecode="1.100s", fps=10.0).frame_num == 11
 
     # Standard timecode format [timecode->str] ('HH:MM:SS[.nnn]', where [.nnn] is optional)
-    assert FrameTimecode(timecode="00:00:01", fps=1).frame_num == 1
-    assert FrameTimecode(timecode="00:00:01.9999", fps=1).frame_num == 2
-    assert FrameTimecode(timecode="00:00:02.0000", fps=1).frame_num == 2
-    assert FrameTimecode(timecode="00:00:02.0001", fps=1).frame_num == 2
+    assert FrameTimecode(timecode="00:00:01", fps=1.0).frame_num == 1
+    assert FrameTimecode(timecode="00:00:01.9999", fps=1.0).frame_num == 2
+    assert FrameTimecode(timecode="00:00:02.0000", fps=1.0).frame_num == 2
+    assert FrameTimecode(timecode="00:00:02.0001", fps=1.0).frame_num == 2
 
     # MM:SS[.nnn] is also allowed
-    assert FrameTimecode(timecode="00:01", fps=1).frame_num == 1
-    assert FrameTimecode(timecode="00:01.9999", fps=1).frame_num == 2
-    assert FrameTimecode(timecode="00:02.0000", fps=1).frame_num == 2
-    assert FrameTimecode(timecode="00:02.0001", fps=1).frame_num == 2
+    assert FrameTimecode(timecode="00:01", fps=1.0).frame_num == 1
+    assert FrameTimecode(timecode="00:01.9999", fps=1.0).frame_num == 2
+    assert FrameTimecode(timecode="00:02.0000", fps=1.0).frame_num == 2
+    assert FrameTimecode(timecode="00:02.0001", fps=1.0).frame_num == 2
 
     # Conversion edge cases
-    assert FrameTimecode(timecode="00:00:01", fps=10).frame_num == 10
-    assert FrameTimecode(timecode="00:00:00.5", fps=10).frame_num == 5
-    assert FrameTimecode(timecode="00:00:00.100", fps=10).frame_num == 1
-    assert FrameTimecode(timecode="00:00:00.001", fps=1000).frame_num == 1
+    assert FrameTimecode(timecode="00:00:01", fps=10.0).frame_num == 10
+    assert FrameTimecode(timecode="00:00:00.5", fps=10.0).frame_num == 5
+    assert FrameTimecode(timecode="00:00:00.100", fps=10.0).frame_num == 1
+    assert FrameTimecode(timecode="00:00:00.001", fps=1000.0).frame_num == 1
 
-    assert FrameTimecode(timecode="00:00:59.999", fps=1).frame_num == 60
-    assert FrameTimecode(timecode="00:01:00.000", fps=1).frame_num == 60
-    assert FrameTimecode(timecode="00:01:00.001", fps=1).frame_num == 60
+    assert FrameTimecode(timecode="00:00:59.999", fps=1.0).frame_num == 60
+    assert FrameTimecode(timecode="00:01:00.000", fps=1.0).frame_num == 60
+    assert FrameTimecode(timecode="00:01:00.001", fps=1.0).frame_num == 60
 
-    assert FrameTimecode(timecode="00:59:59.999", fps=1).frame_num == 3600
-    assert FrameTimecode(timecode="01:00:00.000", fps=1).frame_num == 3600
-    assert FrameTimecode(timecode="01:00:00.001", fps=1).frame_num == 3600
+    assert FrameTimecode(timecode="00:59:59.999", fps=1.0).frame_num == 3600
+    assert FrameTimecode(timecode="01:00:00.000", fps=1.0).frame_num == 3600
+    assert FrameTimecode(timecode="01:00:00.001", fps=1.0).frame_num == 3600
 
     # Check too many ":" characters (https://github.com/Breakthrough/PySceneDetect/issues/476)
     with pytest.raises(ValueError):
-        FrameTimecode(timecode="01:01:00:00.001", fps=1)
+        FrameTimecode(timecode="01:01:00:00.001", fps=1.0)
 
 
 def test_get_frames():
@@ -157,10 +160,10 @@ def test_get_frames():
     assert FrameTimecode(timecode=1000.0, fps=60.0).frame_num == int(1000.0 * 60.0)
     assert FrameTimecode(timecode=1000000000.0, fps=29.97).frame_num == int(1000000000.0 * 29.97)
 
-    assert FrameTimecode(timecode="00:00:02.0000", fps=1).frame_num == 2
-    assert FrameTimecode(timecode="00:00:00.5", fps=10).frame_num == 5
-    assert FrameTimecode(timecode="00:00:01", fps=10).frame_num == 10
-    assert FrameTimecode(timecode="00:01:00.000", fps=1).frame_num == 60
+    assert FrameTimecode(timecode="00:00:02.0000", fps=1.0).frame_num == 2
+    assert FrameTimecode(timecode="00:00:00.5", fps=10.0).frame_num == 5
+    assert FrameTimecode(timecode="00:00:01", fps=10.0).frame_num == 10
+    assert FrameTimecode(timecode="00:01:00.000", fps=1.0).frame_num == 60
 
 
 def test_get_seconds():
@@ -173,10 +176,10 @@ def test_get_seconds():
     assert FrameTimecode(timecode=1000.0, fps=60.0).seconds, pytest.approx(1000.0)
     assert FrameTimecode(timecode=1000000000.0, fps=29.97).seconds, pytest.approx(1000000000.0)
 
-    assert FrameTimecode(timecode="00:00:02.0000", fps=1).seconds, pytest.approx(2.0)
-    assert FrameTimecode(timecode="00:00:00.5", fps=10).seconds, pytest.approx(0.5)
-    assert FrameTimecode(timecode="00:00:01", fps=10).seconds, pytest.approx(1.0)
-    assert FrameTimecode(timecode="00:01:00.000", fps=1).seconds, pytest.approx(60.0)
+    assert FrameTimecode(timecode="00:00:02.0000", fps=1.0).seconds, pytest.approx(2.0)
+    assert FrameTimecode(timecode="00:00:00.5", fps=10.0).seconds, pytest.approx(0.5)
+    assert FrameTimecode(timecode="00:00:01", fps=10.0).seconds, pytest.approx(1.0)
+    assert FrameTimecode(timecode="00:01:00.000", fps=1.0).seconds, pytest.approx(60.0)
 
 
 def test_get_timecode():
@@ -185,15 +188,15 @@ def test_get_timecode():
     assert FrameTimecode(timecode=60.117, fps=60.0).get_timecode() == "00:01:00.117"
     assert FrameTimecode(timecode=3600.234, fps=29.97).get_timecode() == "01:00:00.234"
 
-    assert FrameTimecode(timecode="00:00:02.0000", fps=1).get_timecode() == "00:00:02.000"
-    assert FrameTimecode(timecode="00:00:00.5", fps=10).get_timecode() == "00:00:00.500"
+    assert FrameTimecode(timecode="00:00:02.0000", fps=1.0).get_timecode() == "00:00:02.000"
+    assert FrameTimecode(timecode="00:00:00.5", fps=10.0).get_timecode() == "00:00:00.500"
     # If a value is provided in seconds, we store that value internally now.
     assert (
-        FrameTimecode(timecode="00:00:01.501", fps=10).get_timecode(nearest_frame=False)
+        FrameTimecode(timecode="00:00:01.501", fps=10.0).get_timecode(nearest_frame=False)
         == "00:00:01.501"
     )
     assert (
-        FrameTimecode(timecode="00:00:01.501", fps=10).get_timecode(nearest_frame=True)
+        FrameTimecode(timecode="00:00:01.501", fps=10.0).get_timecode(nearest_frame=True)
         == "00:00:01.500"
     )
 
@@ -204,8 +207,10 @@ def test_equality():
     assert x == x
     assert x == FrameTimecode(timecode=1.0, fps=10.0)
     assert x == FrameTimecode(timecode=1.0, fps=10.0)
+    assert x == FrameTimecode(timecode=1.0, fps=Fraction(10, 1))
     assert x != FrameTimecode(timecode=10.0, fps=10.0)
     assert x != FrameTimecode(timecode=10.0, fps=10.0)
+    assert x != FrameTimecode(timecode=10.0, fps=Fraction(100, 10))
     assert x == FrameTimecode(x)
     assert x == FrameTimecode(1.0, x)
     assert x == FrameTimecode(10, x)
@@ -231,8 +236,8 @@ def test_equality():
     with pytest.raises(TypeError):
         assert x == {0: 0}
 
-    assert FrameTimecode(timecode="00:00:00.5", fps=10) == "00:00:00.500"
-    assert FrameTimecode(timecode="00:00:01.500", fps=10) == "00:00:01.500"
+    assert FrameTimecode(timecode="00:00:00.5", fps=10.0) == "00:00:00.500"
+    assert FrameTimecode(timecode="00:00:01.500", fps=10.0) == "00:00:01.500"
 
 
 def test_addition():
@@ -261,7 +266,9 @@ def test_subtraction():
     assert FrameTimecode("00:00:00.000", fps=20.0) == x - 10
 
 
-@pytest.mark.parametrize("frame_num,fps", [(1, 1), (61, 14), (29, 25), (126, 24000 / 1001.0)])
+@pytest.mark.parametrize(
+    "frame_num,fps", [(1, 1.0), (61, 14.0), (29, 25.0), (126, Fraction(24000, 1001))]
+)
 def test_identity(frame_num, fps):
     """Test FrameTimecode values, when used in init return the same values"""
     frame_time_code = FrameTimecode(frame_num, fps=fps)