Timecode

Timecode

class edl.Timecode(timecode_string, fps=24, drop_frame=None)[source]

Bases: object

A Timecode object.

Instantiate a Timecode object from a timecode or frame number as a string.

Note

The following sites were referenced for determining the best way to formulate the calculations in this module and are provided as a reference:

Parameters:

  • timecode_string – A timecode as a string (formatted as hh:mm:ss:ff for non-drop frame or hh:mm:ss;ff for drop frame) or a frame number as a string.

  • fps – Frames per second setting as an int or float. Default is 24.

  • drop_frame – Boolean indicating whether to use drop frame or not. None if the timecode string should determine this value. Default is None.

Raises:

ValueError if timecode_string cannot be transformed into a Timecode object.

classmethod str_is_drop_frame(timecode_str)[source]

Determine whether the timecode string uses drop frame notation or not.

Drop frame timecodes are typically delimited by a ; or , while non-drop frame timecodes are delimited by : or .

Parameters:

timecode_str – String representation of the timecode to parse.

Returns:

Boolean True if timecode is using drop frame notation, False if not.

Raises:

ValueError if timecode_str is not a valid hh:mm:ss:ff format and cannot be parsed correctly.

classmethod parse_timecode(timecode_str)[source]

Parse a timecode string to valid hour, minute, second, and frame values.

Splits the timecode string by any non-alphanumeric character. This ensures that that we can support various formats of delimiting timecode strings. For example:

00:12:34:21 # NON-DROP FRAME variation 1
00:12:34.21 # NON-DROP FRAME variation 2
00:12:34;21 # DROP FRAME variation 1
00:12:34,21 # DROP FRAME variation 2
00;12;34;56 # DROP FRAME variation 3
Parameters:

timecode_str – A timecode string (eg. hh:mm:ss:ff for non-drop frame or hh:mm:ss;ff for drop frame).

Returns:

Tuple of (hours, minutes, seconds, frames) where all values are ints.

Raises:

ValueError if string cannot be parsed.

classmethod from_frame(frame, fps=24, drop_frame=False)[source]

Return a new Timecode for the given frame, at the given fps.

Parameters:

  • frame – A frame number, as an int.

  • fps – Number of frames per second, as an int or float. Defaults to 24.

  • drop_frame – Boolean indicating whether to use drop frame or not. Default is False.

Returns:

A Timecode instance.

to_frame()[source]

Return the frame number corresponding to this Timecode instance.

Returns:

A frame number, as an int.

to_seconds()[source]

Convert this Timecode to seconds, using its frame rate.

Note

We use the decimal module here in order to ensure our math is accurate and not subject to rounding errors. The reason we use it here and not when doing frame/timecode calculations is because time is an exact calculation whereas frames is not (since there is no such thing as a fractional frame).

When using a float frame rate (fps) calculations of frames and timecode are not technically exact, and will cause time drift away from “wall clock” time. But this is still correct. Drop frame was created to help mitigate this and it attempts to correct the drift by skipping frame numbers at certain intervals. However, it’s still technically not exact and will usually be a fraction of time off. But it’s exact enough for the editorial world.

See also

https://docs.python.org/2/tutorial/floatingpoint.html#tut-fp-issues

Returns:

Number of seconds as a Decimal.

edl.frame_from_timecode(timecode, fps=24, drop_frame=None)[source]

Return the frame number for the given timecode.

Parameters:

  • timecode – A timecode as a string (formatted as hh:mm:ss:ff for non-drop frame or hh:mm:ss;ff for drop frame) or as a (hours, minutes, seconds, frames) tuple.

  • fps – Number of frames per second as an int or float. Default is 24.

  • drop_frame – Boolean determining whether timecode should use drop frame or not. None if this value should be determined by the timecode’s delimiter notation. Default is None.

Returns:

Corresponding frame number, as an int.

Raises:

NotImplementedError if drop_frame is True and the fps value is unsupported for drop frame.

edl.timecode_from_frame(frame_number, fps=24, drop_frame=False)[source]

Return the timecode corresponding to the given frame.

Note

We don’t need to use the decimal module here because frame/timecode calculations are not exact (there is no such thing as a fractional frame).

When using a float frame rate (fps) calculations of frames and timecode are not technically exact, and will cause time drift away from “wall clock” time. But this is still correct. Drop frame was created to help mitigate this and it attempts to correct the drift by skipping frame numbers at certain intervals. However, it’s still technically not exact and will usually be a fraction of time off. But it’s exact enough for the editorial world (and is therefore “correct”).

Parameters:

  • frame_number – A frame number, as an int.

  • fps – Number of frames per seconds, as an int or float. Default is 24.

  • drop_frame – Boolean determining whether timecode should use drop frame or not. Default is False.

Returns:

Timecode as string, e.g. 01:02:12:32 (non-drop frame) or 01:02:12;32 (drop frame).

Raises:

NotImplementedError if drop_frame is True and the fps value is unsupported for drop frame.