Method get_timecode

scenedetect/common.py:407–450

Get a formatted timecode string of the form HH:MM:SS[.nnn]. Args: precision: The number of decimal places to include in the output ``[.nnn]``. use_rounding: Rounds the output to the desired precision. If False, the value will be truncated to the speci

(
        self, precision: int = 3, use_rounding: bool = True, nearest_frame: bool = True
    )

    # We may also just need to clamp end time to the one specified by the user, this may not be
    # happening in the code.
    def get_timecode(
        self, precision: int = 3, use_rounding: bool = True, nearest_frame: bool = True
    ) -> str:
        """Get a formatted timecode string of the form HH:MM:SS[.nnn].

        Args:
            precision: The number of decimal places to include in the output ``[.nnn]``.
            use_rounding: Rounds the output to the desired precision. If False, the value
                will be truncated to the specified precision.
            nearest_frame: Ensures that the timecode is moved to the nearest frame boundary if this
                object has a defined framerate, otherwise has no effect.

        Returns:
            str: The current time in the form ``"HH:MM:SS[.nnn]"``.
        """
        # Compute hours and minutes based off of seconds, and update seconds.
        # For PTS-backed timecodes, the PTS already represents an exact frame boundary, so we use
        # `seconds` directly. For non-PTS timecodes, `nearest_frame` snaps to the nearest frame
        # boundary using frame_num, which avoids floating point drift in CFR video display.
        if nearest_frame and self.frame_rate and not isinstance(self._time, Timecode):
            secs = self.frame_num / float(self.frame_rate)
        else:
            secs = self.seconds
        hrs = int(secs / _SECONDS_PER_HOUR)
        secs -= hrs * _SECONDS_PER_HOUR
        mins = int(secs / _SECONDS_PER_MINUTE)
        secs = max(0.0, secs - (mins * _SECONDS_PER_MINUTE))
        if use_rounding:
            secs = round(secs, precision)
        secs = min(_SECONDS_PER_MINUTE, secs)
        # Guard against emitting timecodes with 60 seconds after rounding/floating point errors.
        if int(secs) == _SECONDS_PER_MINUTE:
            secs = 0.0
            mins += 1
            if mins >= _MINUTES_PER_HOUR:
                mins = 0
                hrs += 1
        # We have to extend the precision by 1 here, since `format` will round up.
        msec = format(secs, f".{precision + 1}f") if precision else ""
        # Need to include decimal place in `msec_str`.
        msec_str = msec[-(2 + precision) : -1]
        secs_str = f"{int(secs):02d}{msec_str}"
        # Return hours, minutes, and seconds as a formatted timecode string.
        return f"{hrs:02d}:{mins:02d}:{secs_str}"

    @staticmethod
    def _ensure_fractional(fps: "FrameRate | FrameTimecode") -> Fraction: