Common

scenedetect.common Module

This module contains common types and functions used throughout PySceneDetect.

This includes FrameTimecode 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.

A FrameTimecode can be created by specifying a timecode (int for number of frames, float for number of seconds, or str in the form “HH:MM:SS” or “HH:MM:SS.nnn”) with a framerate:

frames = FrameTimecode(29, 29.97)
seconds_float = FrameTimecode(10.0, 10.0)
timecode_str = FrameTimecode("00:00:10.000", 10.0)

Arithmetic/comparison operations with FrameTimecode objects is also possible, and the other operand can also be of the above types:

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

FrameTimecode objects can be added and subtracted, however the current implementation disallows negative values, and will clamp negative results to 0.

Warning

Be careful when subtracting FrameTimecode objects or adding negative amounts of frames/seconds. 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
assert(c == 0)
assert(d == 5)
class scenedetect.common.FrameTimecode(timecode, fps=None)

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:

  • framerate is a float (legacy / deprecated alias).

  • frame_rate is a Fraction and is the canonical form. Both represent the same rate.

  • time_base equals 1 / frame_rate for CFR sources. For VFR (Timecode-backed) instances, time_base is authoritative and frame_rate is an approximation.

Parameters:

  • timecode (TimecodeLike) – 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 (float | FrameTimecode | Fraction | None) – 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.

equal_frame_rate(other)

Determine whether the passed frame rate equals this object’s frame rate.

Parameters:

other (float | Fraction | FrameTimecode) – Frame rate to compare against within the precision constant defined in this module (see MAX_FPS_DELTA). May be a float, Fraction, or another FrameTimecode.

Returns:

True if other matches this FrameTimecode’s frame rate within tolerance, False otherwise.

Return type:

bool

equal_framerate(fps)

[DEPRECATED] Use equal_frame_rate() instead.

Return type:

bool

get_timecode(precision=3, use_rounding=True, nearest_frame=True)

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

Parameters:

  • precision (int) – The number of decimal places to include in the output [.nnn].

  • use_rounding (bool) – Rounds the output to the desired precision. If False, the value will be truncated to the specified precision.

  • nearest_frame (bool) – Ensures that the timecode is moved to the nearest frame boundary if this object has a defined framerate, otherwise has no effect.

Returns:

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

Return type:

str

property frame_num: int

The frame number. For VFR video or Timecode-backed objects, this is an approximation based on the average framerate. Prefer using pts and time_base for precise timing.

property frame_rate: Fraction | None

The frame rate as an exact rational fractions.Fraction.

For CFR sources this equals 1 / time_base. For VFR sources the rate may be an approximation (e.g. the average framerate); prefer time_base for exact PTS arithmetic. Returns None for timecodes constructed without an associated rate (i.e. pure Timecode representations).

property framerate: float | None

[DEPRECATED] Use frame_rate instead.

Returns the rate as a float for legacy compatibility. The new frame_rate property returns an exact fractions.Fraction and matches the naming used by scenedetect.video_stream.VideoStream.frame_rate.

property pts: int

The presentation timestamp of the frame in units of time_base.

property seconds: float

The frame’s position in number of seconds.

property time_base: Fraction

The time base in which presentation time is calculated.

class scenedetect.common.Interpolation(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Interpolation method used for image resizing. Based on constants defined in OpenCV.

AREA = 3

Pixel area relation resampling. Provides moire’-free downscaling.

CUBIC = 2

Bicubic interpolation.

LANCZOS4 = 4

Lanczos interpolation over 8x8 neighborhood.

LINEAR = 1

Bilinear interpolation.

NEAREST = 0

Nearest neighbor interpolation.

class scenedetect.common.Timecode(pts, time_base)

Timing information associated with a given frame.

Parameters:

  • pts (int) –

  • time_base (Fraction) –

pts: int

Presentation timestamp of the frame in units of time_base.

time_base: Fraction

The base unit in which pts is measured.

scenedetect.common.framerate_to_fraction(fps)

Convert a framerate value to an exact rational Fraction.

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. Fraction inputs are returned directly without conversion.

Parameters:

fps (float | Fraction) –

Return type:

Fraction

scenedetect.common.CropRegion

Type hint for rectangle of the form X0 Y0 X1 Y1 for cropping frames. Coordinates are relative to source frame without downscaling.

alias of tuple[int, int, int, int]

scenedetect.common.CutList

Type hint for a list of cuts, where each timecode represents the first frame of a new shot.

alias of list[FrameTimecode]

scenedetect.common.FrameRate = float | fractions.Fraction

Type hint for a video frame rate. Fraction is the canonical exact form and should be preferred (e.g. Fraction(30000, 1001)), while float is accepted for convenience. Floats will be converted to rationals at runtime via framerate_to_fraction().

scenedetect.common.MAX_FPS_DELTA: float = 1e-09

Maximum amount two framerates can differ by for equality testing. Currently 1 frame/nanosec.

scenedetect.common.SceneList

Type hint for a list of scenes in the form (start time, end time).

alias of list[tuple[FrameTimecode, FrameTimecode]]

scenedetect.common.TimecodeLike

Type hint for values that can be converted to a FrameTimecode. Accepts a frame number (int), number of seconds (float), timecode string (str of the form HH:MM:SS[.nnn]), a Timecode, or an existing FrameTimecode.

alias of Union[int, float, str, Timecode, FrameTimecode]

scenedetect.common.TimecodePair

Type hint for timecode pairs, typically representing the start/end of a scene.

alias of tuple[FrameTimecode, FrameTimecode]