Class FrameTimecode

scenedetect/common.py:191–774

Object for frame-based timecodes, using the video framerate to compute back and forth between frame number and seconds/timecode. A timecode is valid only if it complies with one of the following three types/formats: 1. Timecode as `str` in the form "HH:MM:SS[.nnn]" (`"01:23:45"` or

class FrameTimecode:
    """Object for frame-based timecodes, using the video framerate to compute back and
    forth between frame number and seconds/timecode.

    A timecode is valid only if it complies with one of the following three types/formats:
        1. Timecode as `str` in the form "HH:MM:SS[.nnn]" (`"01:23:45"` or `"01:23:45.678"`)
        2. Number of seconds as `float`, or `str` in form  "SSSS.nnnn" (`"45.678"`)
        3. Exact number of frames as `int`, or `str` in form NNNNN (`456` or `"456"`)

    Rate-related properties:
        * :attr:`framerate` is a ``float`` (legacy / deprecated alias).
        * :attr:`frame_rate` is a ``Fraction`` and is the canonical form. Both represent
          the same rate.
        * :attr:`time_base` equals ``1 / frame_rate`` for CFR sources. For VFR
          (:class:`Timecode`-backed) instances, ``time_base`` is authoritative and
          ``frame_rate`` is an approximation.
    """

    def __init__(
        self,
        timecode: "TimecodeLike",
        fps: "float | FrameTimecode | Fraction | None" = 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 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.
        """
        self._time: _FrameNumber | _Seconds | Timecode
        """Internal time representation."""
        self._rate: Fraction | None = None
        """Rate at which time passes between frames, measured in frames/sec."""

        # Copy constructor.
        if isinstance(timecode, FrameTimecode):
            self._time = timecode._time
            self._rate = timecode._rate if fps is None else self._ensure_fractional(fps)
            return

        # Ensure args are consistent with API.
        if fps is None:
            raise TypeError("fps is a required argument.")
        self._rate = self._ensure_fractional(fps)

        # Timecode with a time base.
        if isinstance(timecode, Timecode):
            self._time = 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)