scenedetect.frame_timecode Module

This module contains the FrameTimecode object, which is used as a way for PySceneDetect to store frame-accurate timestamps of each cut. This is done by also specifying the video framerate with the timecode, allowing a frame number to be converted to/from a floating-point number of seconds, or string in the form “HH:MM:SS[.nnn]” where the [.nnn] part is optional.

See the following examples, or the FrameTimecode constructor.

Unit tests for the FrameTimecode object can be found in tests/

Usage Examples

A FrameTimecode can be created by specifying the frame number as an integer, along with the framerate:

x = FrameTimecode(timecode = 0, fps = 29.97)

It can also be created from a floating-point number of seconds. Note that calling x.get_frames() will return 200 in this case (10.0 seconds at 20.0 frames/sec):

x = FrameTimecode(timecode = 10.0, fps = 20.0)

timecode can also be specified as a string in “HH:MM:SS[.nnn]” format. Note that calling x.get_frames() will return 600 in this case (1 minute, or 60 seconds, at 10 frames/sec):

x = FrameTimecode(timecode = "00:01:00.000", fps = 10.0)

FrameTimecode objects can be added and subtracted. Note, however, that a negative timecode is not representable by a FrameTimecode, and subtractions towards/past zero will wrap at zero.


Be careful when subtracting FrameTimecode objects. In the example below, c will be at frame 0 since b > a, but d will be at frame 5:

a = FrameTimecode(5, 10.0)
b = FrameTimecode(10, 10.0)
c = a - b   # b > a, so c == 0
d = b - a

When performing arithmetic/comparison operations with FrameTimecode objects, the other operand can be a FrameTimecode, an int number of frames, a float number of seconds, or a str of the form “HH:MM:SS[.nnn]”. For example:

x = FrameTimecode(timecode = "00:01:00.000", fps = 10.0)
# Can add int (frames), float (seconds), or str (timecode).
print(x + 10)
print(x + 10.0)
print(x + "00:10:00")
# The same goes for comparison.
print((x + 10.0) == "00:01:10.000")

FrameTimecode Class

class scenedetect.frame_timecode.FrameTimecode(timecode=None, fps=None)

Object for frame-based timecodes, using the video framerate to compute back and forth between frame number and second/timecode formats.

The timecode argument is valid only if it complies with one of the following three types/formats:

  1. string: standard timecode HH:MM:SS[.nnn]:
    str in form ‘HH:MM:SS’ or ‘HH:MM:SS.nnn’, or list/tuple in form [HH, MM, SS] or [HH, MM, SS.nnn]
  2. float: number of seconds S[.SSS], where S >= 0.0:
    float in form S.SSS, or str in form ‘Ss’ or ‘S.SSSs’ (e.g. ‘5s’, ‘1.234s’)
  3. int: Exact number of frames N, where N >= 0:
    int in form N, or str in form ‘N’
  • timecode (str, float, int, or FrameTimecode) – A timecode or frame number, given in any of the above valid formats/types. This argument is always required.
  • fps (float, or FrameTimecode, conditionally required) – The framerate to base all frame to time arithmetic on (if FrameTimecode, copied from the passed framerate), to allow frame-accurate arithmetic. The framerate must be the same when combining FrameTimecode objects in operations. This argument is always required, unless timecode is a FrameTimecode.
  • TypeError – Thrown if timecode is wrong type/format, or if fps is None or a type other than int or float.
  • ValueError – Thrown when specifying a negative timecode or framerate.

Equal Framerate: Determines if the passed framerate is equal to that of the FrameTimecode object.

Parameters:fps – Framerate (float) to compare against within the precision constant MINIMUM_FRAMES_PER_SECOND_DELTA_FLOAT defined in this module.
Returns:True if passed fps matches the FrameTimecode object’s framerate, False otherwise.
Return type:bool

Get Framerate: Returns the framerate used by the FrameTimecode object.

Returns:Framerate of the current FrameTimecode object, in frames per second.
Return type:float

Get the current time/position in number of frames. This is the equivalent of accessing the self.frame_num property (which, along with the specified framerate, forms the base for all of the other time measurement calculations, e.g. the get_seconds() method).

If using to compare a FrameTimecode with a frame number, you can do so directly against the object (e.g. FrameTimecode(10, 10.0) <= 10).

Returns:The current time in frames (the current frame number).
Return type:int

Get the frame’s position in number of seconds.

If using to compare a FrameTimecode with a frame number, you can do so directly against the object (e.g. FrameTimecode(10, 10.0) <= 1.0).

Returns:The current time/position in seconds.
Return type:float
get_timecode(precision=3, use_rounding=True)

Get a formatted timecode string of the form HH:MM:SS[.nnn].

  • precision – The number of decimal places to include in the output [.nnn].
  • use_rounding – True (default) to round the output to the desired precision.

The current time in the form "HH:MM:SS[.nnn]".

Return type:



Returns a new FrameTimecode for the frame before this one. :return: New FrameTimeCode object, one frame earlier