[common] Add operators for Timecode

Author: Breakthrough

scenedetect/common.py

@@ -144,6 +144,81 @@ class Timecode:
     def seconds(self) -> float:
         return float(self.time_base * self.pts)
 
+    def _get_other_as_seconds(self, other: ty.Any) -> float:
+        if isinstance(other, Timecode):
+            return other.seconds
+        if isinstance(other, float):
+            return float(other)
+        raise TypeError(f"Unsupported type for comparison with Timecode: {type(other)}")
+
+    def __add__(self, other: ty.Union[float, "Timecode"]) -> "Timecode":
+        if isinstance(other, Timecode):
+            if self.time_base != other.time_base:
+                raise ValueError("Timecode instances require equal time_base for arithmetic.")
+            return Timecode(self.pts + other.pts, self.time_base)
+        if isinstance(other, float):
+            # Assume other is in seconds. Convert to pts.
+            pts_offset = round(other / self.time_base)
+            return Timecode(self.pts + pts_offset, self.time_base)
+        return NotImplemented
+
+    def __sub__(self, other: ty.Union[float, "Timecode"]) -> "Timecode":
+        if isinstance(other, Timecode):
+            if self.time_base != other.time_base:
+                raise ValueError("Timecode instances require equal time_base for arithmetic.")
+            return Timecode(self.pts - other.pts, self.time_base)
+        if isinstance(other, float):
+            # Assume other is in seconds. Convert to pts.
+            pts_offset = round(other / self.time_base)
+            return Timecode(self.pts - pts_offset, self.time_base)
+        return NotImplemented
+
+    def __eq__(self, other: ty.Any) -> bool:
+        try:
+            return math.isclose(self.seconds, self._get_other_as_seconds(other))
+        except TypeError:
+            return NotImplemented
+
+    def __ne__(self, other: ty.Any) -> bool:
+        eq_result = self.__eq__(other)
+        return not eq_result if eq_result is not NotImplemented else NotImplemented
+
+    def __lt__(self, other: ty.Any) -> bool:
+        try:
+            other_seconds = self._get_other_as_seconds(other)
+            if math.isclose(self.seconds, other_seconds):
+                return False
+            return self.seconds < other_seconds
+        except TypeError:
+            return NotImplemented
+
+    def __le__(self, other: ty.Any) -> bool:
+        try:
+            other_seconds = self._get_other_as_seconds(other)
+            if math.isclose(self.seconds, other_seconds):
+                return True
+            return self.seconds < other_seconds
+        except TypeError:
+            return NotImplemented
+
+    def __gt__(self, other: ty.Any) -> bool:
+        try:
+            other_seconds = self._get_other_as_seconds(other)
+            if math.isclose(self.seconds, other_seconds):
+                return False
+            return self.seconds > other_seconds
+        except TypeError:
+            return NotImplemented
+
+    def __ge__(self, other: ty.Any) -> bool:
+        try:
+            other_seconds = self._get_other_as_seconds(other)
+            if math.isclose(self.seconds, other_seconds):
+                return True
+            return self.seconds > other_seconds
+        except TypeError:
+            return NotImplemented
+
 
 class FrameTimecode:
     """Object for frame-based timecodes, using the video framerate to compute back and

tests/test_timecode.py

@@ -21,10 +21,12 @@
 """
 
 # Third-Party Library Imports
+# Standard Library Imports
+from fractions import Fraction
+
 import pytest
 
-# Standard Library Imports
-from scenedetect.common import MAX_FPS_DELTA, FrameTimecode
+from scenedetect.common import MAX_FPS_DELTA, FrameTimecode, Timecode
 
 
 def test_framerate():
@@ -300,3 +302,54 @@ def test_precision():
     assert FrameTimecode(990, fps).get_timecode(precision=1, use_rounding=False) == "00:00:00.9"
     assert FrameTimecode(990, fps).get_timecode(precision=0, use_rounding=True) == "00:00:01"
     assert FrameTimecode(990, fps).get_timecode(precision=0, use_rounding=False) == "00:00:00"
+
+
+def test_timecode_operators():
+    """Test Timecode operators."""
+    time_base = Fraction(1, 1000)  # 1ms time base
+    t1 = Timecode(pts=1000, time_base=time_base)  # 1 second
+
+    # Addition
+    t2 = t1 + 0.5
+    assert t2.pts == 1500
+    assert t2.seconds == 1.5
+    t3 = t1 + Timecode(pts=500, time_base=time_base)
+    assert t3.pts == 1500
+    assert t3.seconds == 1.5
+
+    # Subtraction
+    t4 = t1 - 0.5
+    assert t4.pts == 500
+    assert t4.seconds == 0.5
+    t5 = t1 - Timecode(pts=200, time_base=time_base)
+    assert t5.pts == 800
+    assert t5.seconds == 0.8
+
+    # Different time_base for arithmetic should fail
+    with pytest.raises(ValueError):
+        t1 + Timecode(pts=1, time_base=Fraction(1, 1))
+    with pytest.raises(ValueError):
+        t1 - Timecode(pts=1, time_base=Fraction(1, 1))
+
+    # Comparisons
+    assert t1 == 1.0
+    assert t1 == Timecode(pts=1000, time_base=time_base)
+    assert t1 != 2.0
+    assert t1 < 2.0
+    assert t1 <= 1.0
+    assert t1 > 0.5
+    assert t1 >= 1.0
+
+    t_other_tb = Timecode(pts=1, time_base=Fraction(1, 1))  # 1 second, different time base
+    assert t1 == t_other_tb
+    assert t1 <= t_other_tb
+    assert t1 >= t_other_tb
+
+    t_other_tb_2 = Timecode(pts=2, time_base=Fraction(1, 1))  # 2 seconds
+    assert t1 < t_other_tb_2
+    assert t1 != t_other_tb_2
+
+    # Test with different types
+    assert t1 != "a"
+    with pytest.raises(TypeError):
+        _ = t1 < "a"