Skip to main content

SMPTE Time Code Manipulation Library

Project description

Python Module for manipulating SMPTE timecode. Supports 23.98, 24, 25, 29.97, 30, 50, 59.94, 60 frame rates and milliseconds (1000 fps).

This library is a fork of the original PyTimeCode python library. You should not use the two library together (PyTimeCode is not maintained and has known bugs).

The math behind the drop frame calculation is based on the blog post of David Heidelberger .

Simple math operations like, addition, subtraction, multiplication or division with an integer value or with a timecode is possible. Math operations between timecodes with different frame rates are supported. So:

from timecode import Timecode

tc1 = Timecode('29.97', '00:00:00:00')
tc2 = Timecode('24', '00:00:00:10')
tc3 = tc1 + tc2
assert tc3.framerate == '29.97'
assert tc3.frames == 12
assert tc3 == '00:00:00:11'

Creating a Timecode instance with a start timecode of ‘00:00:00:00’ will result a timecode object where the total number of frames is 1. So:

tc4 = Timecode('24', '00:00:00:00')
assert tc4.frames == 1

Use the frame_number attribute if you want to get a 0 based frame number:

assert tc4.frame_number == 0

Frame rates 29.97 and 59.94 are always drop frame, and all the others are non drop frame.

The SMPTE standard limits the timecode with 24 hours. Even though, Timecode instance will show the current timecode inline with the SMPTE standard, it will keep counting the total frames without clipping it.

Please report any bugs to the GitHub page.

Copyright 2014 Joshua Banton and PyTimeCode developers.



  • New: Frame delimiter is now set to “:” for Non Drop Frame, “;” for Drop Frame and “.” for millisecond based time codes. If Timecode.__init__() start_timecode is passed a string with the wrong delimiter it will be converted automatically.

  • Update: All tests involving Drop Frame and millisecond time codes are now set to use the new delimiter.

  • New: Timecode.tc_to_string() method added to present the correctly formatted time code.

  • New: Timecode.ms_frame boolean attribute added.

  • New: Timecode.__init__() now supports strings, ints and floats for the framerate argument.


  • New: Renamed the library to timecode.


  • New: Rewritten the whole library from scratch.

  • New: Most important change is the licencing. There was now license defined in the previous implementation. The library is now licensed under MIT license.

  • Update: Timecode.__init__() arguments has been changed, removed the unnecessary drop_frame, iter_returns arguments.

    Drop frame can be interpreted from the framerate argument and iter_returns is unnecessary cause any iteration on the object will return another Timecode instance.

    If you want to get a string representation use Timecode.__str__() or str(Timecode) or Timecode.__repr__() or \`Timecode\` or '%s' % Timecode any other thing that will convert it to a string.

    If you want to get an integer use Timecode.frames or Timecode.frame_count depending on what you want to get out of it.

    So setting the iter_returns to something and nailing the output was unnecessary.

  • Update: Updated the drop frame calculation to a much better one, which is based on to the blog post of David Heidelberger at

  • New: Added Timecode.__eq__() so it is now possible to check the equality of two timecode instances or a timecode and a string or a timecode and an integer (which will check the total frame count).

  • Update: Timecode.tc_to_frames() now needs a timecode as a string and will return an integer value which is the number of frames in that timecode.

  • Update: Timecode.frames_to_tc() now needs an integer frame count and returns 4 integers for hours, minutes, seconds and frames.

  • Update: Timecode.hrs, Timecode.mins, Timecode.secs and Timecode.frs attributes are now properties. Because it was so rare to check the individual hours, minutes, seconds or frame values, their values are calculated with Timecode.frames_to_tc() method. But in future they can still be converted to attributes and their value will be updated each time the Timecode.frames attribute is changed (so add a _frames attribute and make frames a property with a getter and setter, and update the hrs, mins, secs and frs in setter etc.).

  • Update: Removed Timecode.calc_drop_frame() method. The drop frame calculation is neatly done inside Timecode.frames_to_tc() and Timecode.tc_to_frames() methods.

  • Update: Updated Timecode.parse_timecode() method to a much simpler algorithm.

  • Update: Removed Timecode.__return_item__() method. It is not necessary to return an item in that way anymore.

  • Update: Removed Timecode.make_timecode() method. It was another unnecessary method, so it is removed. Now using simple python string templates for string representations.

  • New: Added timecode.__version__ string, and set the value to “0.2.0”.

  • Update: Removed Timecode.set_int_framerate() method. Setting the framerate will automatically set the Timecode.int_framerate attribute.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

timecode-0.4.0.tar.gz (13.5 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page