FrameTimecode — PySceneDetect 0.6.5-dev1 documentation

# FrameTimecode

`scenedetect.frame_timecode` Module

This module implements `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.

See the following examples, or the `FrameTimecode constructor`.

## Usage Examples

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(timecode = 29, fps = 29.97)
    seconds_float = FrameTimecode(timecode = 10.0, fps = 10.0)
    timecode_str = FrameTimecode(timecode = "00:00:10.000", fps = 10.0)

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

    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")
    # 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.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 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”)

  Parameters:

    - timecode (int | float | str | FrameTimecode) – A frame number (int), number of seconds (float), or timecode (str in the form ‘HH:MM:SS’ or ‘HH:MM:SS.nnn’).

    - fps (int | float | str | FrameTimecode) – The framerate or FrameTimecode to use as a time base for all arithmetic.

  Raises:

    - TypeError – Thrown if either timecode or fps are unsupported types.

    - ValueError – Thrown when specifying a negative timecode or framerate.

  equal_framerate(fps)

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

    Parameters:

      fps – Framerate to compare against within the precision constant defined in this module (see `MAX_FPS_DELTA`).

    Returns:

      True if passed fps matches the FrameTimecode object’s framerate, False otherwise.

    Return type:

      bool

  get_framerate()

    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_frames()

    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_seconds()

    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].

    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.

    Returns:

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

    Return type:

      str

  previous_frame()

    Return a new FrameTimecode for the previous frame (or 0 if on frame 0).

    Return type:

      FrameTimecode

scenedetect.frame_timecode.MAX_FPS_DELTA: float = 1e-05

  Maximum amount two framerates can differ by for equality testing.