FrameTimecode¶
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/test_timecode.py.
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)
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 seconds/timecode.
A timecode is valid only if it complies with one of the following three types/formats:
Timecode as str in the form ‘HH:MM:SS[.nnn]’ (‘01:23:45’ or ‘01:23:45.678’)
Number of seconds as float, or str in form ‘Ss’ or ‘S.SSSs’ (‘2s’ or ‘2.3456s’)
Exact number of frames as int, or str in form NNNNN (123 or ‘123’)
- Parameters
timecode (Union[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 (Union[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
Constants¶
- scenedetect.frame_timecode.MAX_FPS_DELTA = 1e-05¶
Maximum amount two framerates can differ by for equality testing.