[common] Calculate framerate as Fraction rather than using lookup table

Author: Breakthrough

scenedetect/common.py

@@ -91,37 +91,34 @@
 MAX_FPS_DELTA: float = 1.0 / 1000000000.0
 """Maximum amount two framerates can differ by for equality testing. Currently 1 frame/nanosec."""
 
+# `datetime.timedelta` does not expose seconds per minute/hour as constants, so we define our own.
 _SECONDS_PER_MINUTE = 60.0
 _SECONDS_PER_HOUR = 60.0 * _SECONDS_PER_MINUTE
 _MINUTES_PER_HOUR = 60.0
 
-# Common framerates mapped from their float representation to exact rational values.
-_COMMON_FRAMERATES: dict[Fraction, Fraction] = {
-    Fraction(24000, 1001): Fraction(24000, 1001),  # 23.976...
-    Fraction(30000, 1001): Fraction(30000, 1001),  # 29.97...
-    Fraction(60000, 1001): Fraction(60000, 1001),  # 59.94...
-    Fraction(120000, 1001): Fraction(120000, 1001),  # 119.88...
-}
+# Tolerance for snapping a float value's framerate to an NTSC-derived rational (N * 1000/1001).
+# e.g. 23.976 should be detected as 24000/1001, 29.97 should be detected as 30000/1001, etc.
+_NTSC_DETECTION_TOLERANCE: float = 1e-3
 
 
 def framerate_to_fraction(fps: float) -> Fraction:
     """Convert a float framerate to an exact rational Fraction.
 
-    Recognizes common NTSC framerates (23.976, 29.97, 59.94, 119.88) and maps them to their
-    exact rational representation (e.g. 24000/1001). For other values, uses limit_denominator
-    to find a clean rational approximation, or returns the exact integer fraction for whole
-    number framerates.
+    Detects NTSC-derived framerates of the form ``N * 1000/1001`` (e.g. 23.976 -> 24000/1001,
+    29.97 -> 30000/1001, 47.952 -> 48000/1001) for any positive integer ``N`` and returns
+    their exact rational representation. Whole-number framerates are returned as
+    ``Fraction(N, 1)``. Other values fall back to ``limit_denominator(10000)`` for a clean
+    rational approximation.
     """
     if fps <= MAX_FPS_DELTA:
         raise ValueError("Framerate must be positive and greater than zero.")
-    # Integer framerates are exact.
     if fps == int(fps):
         return Fraction(int(fps), 1)
-    # Check against known common framerates using limit_denominator to find the closest match.
-    candidate = Fraction(fps).limit_denominator(10000)
-    if candidate in _COMMON_FRAMERATES:
-        return _COMMON_FRAMERATES[candidate]
-    return candidate
+    # Invert fps = N * 1000/1001 to recover N, then verify within tolerance.
+    base = round(fps * 1001 / 1000)
+    if base > 0 and abs(base * 1000 / 1001 - fps) < _NTSC_DETECTION_TOLERANCE:
+        return Fraction(base * 1000, 1001)
+    return Fraction(fps).limit_denominator(10000)
 
 
 class Interpolation(Enum):

tests/test_timecode.py

@@ -316,12 +316,34 @@ def test_ntsc_framerate_detection():
     assert framerate_to_fraction(23.976023976023978) == Fraction(24000, 1001)
     assert framerate_to_fraction(29.97002997002997) == Fraction(30000, 1001)
     assert framerate_to_fraction(59.94005994005994) == Fraction(60000, 1001)
+    assert framerate_to_fraction(119.88011988011988) == Fraction(120000, 1001)
     assert framerate_to_fraction(24.0) == Fraction(24, 1)
     assert framerate_to_fraction(30.0) == Fraction(30, 1)
     assert framerate_to_fraction(60.0) == Fraction(60, 1)
     assert framerate_to_fraction(25.0) == Fraction(25, 1)
 
 
+def test_ntsc_framerate_detection_arbitrary_base():
+    """NTSC detection should work for any base rate, not a hardcoded list (e.g. 48000/1001
+    for HFR cinema)."""
+    assert framerate_to_fraction(47.952047952047955) == Fraction(48000, 1001)
+    assert framerate_to_fraction(239.76023976023975) == Fraction(240000, 1001)
+
+
+def test_ntsc_framerate_detection_low_precision():
+    """Low-precision float reports (e.g. truncated to 3 decimals) should still snap to the
+    NTSC rational."""
+    assert framerate_to_fraction(23.976) == Fraction(24000, 1001)
+    assert framerate_to_fraction(29.97) == Fraction(30000, 1001)
+
+
+def test_framerate_to_fraction_non_ntsc_fallback():
+    """Non-NTSC, non-integer framerates should fall back to limit_denominator and not be
+    misclassified as NTSC."""
+    # 24.5 is not near any N*1000/1001 within tolerance, so the limit_denominator path runs.
+    assert framerate_to_fraction(24.5) == Fraction(49, 2)
+
+
 def test_timecode_arithmetic_mixed_time_base():
     """Arithmetic with FrameTimecodes using different time_bases should work."""
     fps = Fraction(24000, 1001)