About
-----
Python Module for manipulating SMPTE timecode. Supports 23.976, 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`_ .
.. _`blog post of David Heidelberger`: http://www.davidheidelberger.com/blog/?p=29
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 timecode library supports rational frame rates passed as a either a string
or tuple::
tc5 = Timecode('30000/1001', '00:00:00;00')
assert tc5.framerate == '29.97'
tc6 = Timecode((30000, 1001), '00:00:00;00')
assert tc6.framerate == '29.97'
You may also pass a big "Binary Coded Decimal" integer as start timecode::
tc7 = Timecode('24', 421729315)
assert repr(tc7) == '19:23:14:23'
This is useful for parsing timecodes stored in OpenEXR's and extracted through
OpenImageIO for instance.
Timecode also supports passing start timecodes formatted like HH:MM:SS.sss where
SS.sss is seconds and fractions of seconds::
tc8 = Timecode(25, '00:00:00.040')
assert tc8.frame_number == 1
You may set any timecode to be represented as fractions of seconds::
tc9 = Timecode(24, '19:23:14:23')
assert repr(tc9) == '19:23:14:23'
tc9.set_fractional(True)
assert repr(tc9) == '19:23:14.958'
Fraction of seconds is useful when working with tools like FFmpeg.
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.
.. _`GitHub`: https://github.com/eoyilmaz/timecode
Copyright 2014 Joshua Banton and PyTimeCode developers.
=======
Changes
=======
1.3.1
=====
* **Fix:** Fixed 23.98, 29.97 DF, 29.97 NDF, 59.94 and 59.94 NDF rollover to ``00:00:00:00`` after 24 hours.
1.3.0
=====
* **Fix:** Fixed a huge bug in 29.97 NDF and 59.97 NDF calculations introduced
in v1.2.3.
* **Fix:** Fixed ``Timecode.framerate`` when it is given as ``23.98``. The
``framerate`` attribute will not be forced to ``24`` and it will stay
``23.98``.
* **Update:** ``Timecode.tc_to_frames()`` method now accepts Timecode instances
with possibly different frame rates then the instance itself.
* **Fix:** Fixed ``Timecode.div_frames()`` method.
* **Update:** Test coverage has been increased to 100% (yay!)
1.2.5
=====
* **Fix:** Fixed an edge case when two Timecodes are subtracted the resultant
Timecode will always have the correct amount of frames. But it is not
possible to have a Timecode with negative or zero frames as this is changed
in 1.2.3.
* **Fix:** Fixed ``Timecode.float`` property for drop frames.
1.2.4
=====
* **Update:** It is now possible to supply a ``Fraction`` instances for the
``framerate`` argument.
1.2.3
=====
* **Update:** Passing ``frames=0`` will now raise a ValueError. This hopefully
will clarify the usage of the TimeCode as a duration. If there is no
duration, hence the ``frames=0``, meaning that the number of frames of the
duration that this TimeCode represents is 0, which is meaningless.
* **Update:** Also added some validation for the ``frames`` property
(oh yes it is a property now).
1.2.2.1
=======
* **Fix:** Fixed the ``CHANGELOG.rst`` and ``setup.py`` to be able to properly
package and upload to PyPI.
1.2.2
=====
* **Fix:** Fixed ``Timecode.parse_timecode`` for int inputs.
* **Update:** ``Timecode`` now accepts a ``fractional`` bool argument that
forces the timecode to be fractional.
* **Update:** ``Timecode`` now accepts a ```force_non_drop_frame`` argument
that forces the timecode to be non-drop frame.
1.2.1
=====
* **Update:** Added support for 23.976 fps which is a common variation of 23.98.
1.2.0
=====
* **NEW:** Support for passing a tuple with numerator and denominator when
passing rational framerate.
* **NEW:** set_fractional method for setting whether or not to represent a
timecode as fractional seconds.
* **Update:** Updated README's with info on new features
* **FIX:** Some merge issues.
1.1.0
=====
* **New:** Support for passing "binary coded decimal" (BCD) integer to
timecode argument as it's stored in certain formats like OpenEXR and DPX.
Useful for parsing timecode from metadata through OpenImageIO for instance.
Example: ``Timecode(24, 421729315) -> 19:23:14:23``
https://en.wikipedia.org/wiki/SMPTE_timecode
1.0.1
=====
* **Update:** To prevent confusion, passing 0 for ``start_seconds`` argument
will raise a ValueError now in ``Timecode.__init__`` method.
1.0.0
=====
* **New:** Added support for passing rational frame rate. 24000/1001 for 23.97
etc.
* **New:** Added tests for new functionality. Fractional seconds and
rational frame rates.
* **New:** added __ge__ and __le__ methods for better comparison between two
timecodes.
* **New:** Added support for fractional seconds in the frame field as used in
ffmpeg's duration for instance.
* **Important:** When passing fractional second style timecode, the
Timecode.frs will return a float representing the fraction of a second. This
is a major change for people expecting int values
0.4.2
=====
* **Update:** Version bump for PyPI.
0.4.1
=====
* **Fix:** Fixed a test that was testing overloaded operators.
0.4.0
=====
* **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.
0.3.0
=====
* **New:** Renamed the library to ``timecode``.
0.2.0
=====
* **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
http://www.davidheidelberger.com/blog/?p=29
* **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.
Raw data
{
"_id": null,
"home_page": "https://github.com/eoyilmaz/timecode",
"name": "timecode",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "video, timecode, smpte",
"author": "Erkan Ozgur Yilmaz",
"author_email": "eoyilmaz@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/71/43/0045d51dc626adc07aeb227c9a13626eff38224287b556828bf59f2d9227/timecode-1.4.1.tar.gz",
"platform": null,
"description": "About\n-----\n\nPython Module for manipulating SMPTE timecode. Supports 23.976, 23.98, 24, 25, \n29.97, 30, 50, 59.94, 60 frame rates and milliseconds (1000 fps).\n\nThis library is a fork of the original PyTimeCode python library. You should\nnot use the two library together (PyTimeCode is not maintained and has known\nbugs).\n\nThe math behind the drop frame calculation is based on the\n`blog post of David Heidelberger`_ .\n\n.. _`blog post of David Heidelberger`: http://www.davidheidelberger.com/blog/?p=29\n\nSimple math operations like, addition, subtraction, multiplication or division\nwith an integer value or with a timecode is possible. Math operations between\ntimecodes with different frame rates are supported. So::\n\n from timecode import Timecode\n\n tc1 = Timecode('29.97', '00:00:00:00')\n tc2 = Timecode('24', '00:00:00:10')\n tc3 = tc1 + tc2\n assert tc3.framerate == '29.97'\n assert tc3.frames == 12\n assert tc3 == '00:00:00:11'\n\nCreating a Timecode instance with a start timecode of '00:00:00:00' will\nresult a timecode object where the total number of frames is 1. So::\n\n tc4 = Timecode('24', '00:00:00:00')\n assert tc4.frames == 1\n\nUse the ``frame_number`` attribute if you want to get a 0 based frame number::\n\n assert tc4.frame_number == 0\n\nFrame rates 29.97 and 59.94 are always drop frame, and all the others are non\ndrop frame.\n\nThe timecode library supports rational frame rates passed as a either a string\n or tuple::\n\n tc5 = Timecode('30000/1001', '00:00:00;00')\n assert tc5.framerate == '29.97'\n\n tc6 = Timecode((30000, 1001), '00:00:00;00')\n assert tc6.framerate == '29.97'\n\nYou may also pass a big \"Binary Coded Decimal\" integer as start timecode::\n\n tc7 = Timecode('24', 421729315)\n assert repr(tc7) == '19:23:14:23'\n\nThis is useful for parsing timecodes stored in OpenEXR's and extracted through\nOpenImageIO for instance.\n\nTimecode also supports passing start timecodes formatted like HH:MM:SS.sss where\nSS.sss is seconds and fractions of seconds::\n\n tc8 = Timecode(25, '00:00:00.040')\n assert tc8.frame_number == 1\n\nYou may set any timecode to be represented as fractions of seconds::\n\n tc9 = Timecode(24, '19:23:14:23')\n assert repr(tc9) == '19:23:14:23'\n\n tc9.set_fractional(True)\n assert repr(tc9) == '19:23:14.958'\n\nFraction of seconds is useful when working with tools like FFmpeg.\n\n\nThe SMPTE standard limits the timecode with 24 hours. Even though, Timecode\ninstance will show the current timecode inline with the SMPTE standard, it will\nkeep counting the total frames without clipping it.\n\nPlease report any bugs to the `GitHub`_ page.\n\n.. _`GitHub`: https://github.com/eoyilmaz/timecode\n\nCopyright 2014 Joshua Banton and PyTimeCode developers.\n\n\n=======\nChanges\n=======\n\n1.3.1\n=====\n\n* **Fix:** Fixed 23.98, 29.97 DF, 29.97 NDF, 59.94 and 59.94 NDF rollover to ``00:00:00:00`` after 24 hours.\n\n1.3.0\n=====\n\n* **Fix:** Fixed a huge bug in 29.97 NDF and 59.97 NDF calculations introduced\n in v1.2.3.\n\n* **Fix:** Fixed ``Timecode.framerate`` when it is given as ``23.98``. The\n ``framerate`` attribute will not be forced to ``24`` and it will stay\n ``23.98``.\n\n* **Update:** ``Timecode.tc_to_frames()`` method now accepts Timecode instances\n with possibly different frame rates then the instance itself.\n\n* **Fix:** Fixed ``Timecode.div_frames()`` method.\n\n* **Update:** Test coverage has been increased to 100% (yay!)\n\n1.2.5\n=====\n\n* **Fix:** Fixed an edge case when two Timecodes are subtracted the resultant\n Timecode will always have the correct amount of frames. But it is not\n possible to have a Timecode with negative or zero frames as this is changed\n in 1.2.3.\n\n* **Fix:** Fixed ``Timecode.float`` property for drop frames.\n\n1.2.4\n=====\n\n* **Update:** It is now possible to supply a ``Fraction`` instances for the\n ``framerate`` argument.\n\n1.2.3\n=====\n* **Update:** Passing ``frames=0`` will now raise a ValueError. This hopefully\n will clarify the usage of the TimeCode as a duration. If there is no\n duration, hence the ``frames=0``, meaning that the number of frames of the\n duration that this TimeCode represents is 0, which is meaningless.\n* **Update:** Also added some validation for the ``frames`` property\n (oh yes it is a property now).\n\n1.2.2.1\n=======\n* **Fix:** Fixed the ``CHANGELOG.rst`` and ``setup.py`` to be able to properly\n package and upload to PyPI.\n\n1.2.2\n=====\n* **Fix:** Fixed ``Timecode.parse_timecode`` for int inputs.\n* **Update:** ``Timecode`` now accepts a ``fractional`` bool argument that\n forces the timecode to be fractional.\n* **Update:** ``Timecode`` now accepts a ```force_non_drop_frame`` argument\n that forces the timecode to be non-drop frame.\n\n1.2.1\n=====\n* **Update:** Added support for 23.976 fps which is a common variation of 23.98.\n\n1.2.0\n=====\n* **NEW:** Support for passing a tuple with numerator and denominator when\n passing rational framerate.\n\n* **NEW:** set_fractional method for setting whether or not to represent a\n timecode as fractional seconds.\n\n* **Update:** Updated README's with info on new features\n\n* **FIX:** Some merge issues.\n\n1.1.0\n=====\n\n* **New:** Support for passing \"binary coded decimal\" (BCD) integer to\n timecode argument as it's stored in certain formats like OpenEXR and DPX.\n Useful for parsing timecode from metadata through OpenImageIO for instance.\n Example: ``Timecode(24, 421729315) -> 19:23:14:23``\n https://en.wikipedia.org/wiki/SMPTE_timecode\n\n1.0.1\n=====\n\n* **Update:** To prevent confusion, passing 0 for ``start_seconds`` argument\n will raise a ValueError now in ``Timecode.__init__`` method.\n\n1.0.0\n=====\n\n* **New:** Added support for passing rational frame rate. 24000/1001 for 23.97\n etc.\n\n* **New:** Added tests for new functionality. Fractional seconds and\n rational frame rates.\n\n* **New:** added __ge__ and __le__ methods for better comparison between two\n timecodes.\n\n* **New:** Added support for fractional seconds in the frame field as used in\n ffmpeg's duration for instance.\n\n* **Important:** When passing fractional second style timecode, the\n Timecode.frs will return a float representing the fraction of a second. This\n is a major change for people expecting int values\n\n0.4.2\n=====\n\n* **Update:** Version bump for PyPI.\n\n0.4.1\n=====\n\n* **Fix:** Fixed a test that was testing overloaded operators.\n\n0.4.0\n=====\n\n* **New:** Frame delimiter is now set to \":\" for Non Drop Frame, \";\" for Drop\n Frame and \".\" for millisecond based time codes.\n If ``Timecode.__init__()`` start_timecode is passed a string with the wrong\n delimiter it will be converted automatically.\n\n* **Update:** All tests involving Drop Frame and millisecond time codes are now\n set to use the new delimiter.\n\n* **New:** ``Timecode.tc_to_string()`` method added to present the correctly\n formatted time code.\n\n* **New:** ``Timecode.ms_frame`` boolean attribute added.\n\n* **New:** ``Timecode.__init__()`` now supports strings, ints and floats for\n the framerate argument.\n\n0.3.0\n=====\n\n* **New:** Renamed the library to ``timecode``.\n\n0.2.0\n=====\n\n* **New:** Rewritten the whole library from scratch.\n\n* **New:** Most important change is the licencing. There was now license\n defined in the previous implementation. The library is now licensed under MIT\n license.\n\n* **Update:** Timecode.__init__() arguments has been changed, removed the\n unnecessary ``drop_frame``, ``iter_returns`` arguments.\n\n Drop frame can be interpreted from the ``framerate`` argument and\n ``iter_returns`` is unnecessary cause any iteration on the object will return\n another ``Timecode`` instance.\n\n If you want to get a string representation use ``Timecode.__str__()`` or\n ``str(Timecode)`` or ``Timecode.__repr__()`` or ``\\`Timecode\\``` or\n ``'%s' % Timecode`` any other thing that will convert it to a string.\n\n If you want to get an integer use ``Timecode.frames`` or\n ``Timecode.frame_count`` depending on what you want to get out of it.\n\n So setting the ``iter_returns`` to something and nailing the output was\n unnecessary.\n\n* **Update:** Updated the drop frame calculation to a much better one, which\n is based on to the blog post of David Heidelberger at\n http://www.davidheidelberger.com/blog/?p=29\n\n* **New:** Added ``Timecode.__eq__()`` so it is now possible to check the\n equality of two timecode instances or a timecode and a string or a timecode\n and an integer (which will check the total frame count).\n\n* **Update:** ``Timecode.tc_to_frames()`` now needs a timecode as a string\n and will return an integer value which is the number of frames in that\n timecode.\n\n* **Update:** ``Timecode.frames_to_tc()`` now needs an integer frame count\n and returns 4 integers for hours, minutes, seconds and frames.\n\n* **Update:** ``Timecode.hrs``, ``Timecode.mins``, ``Timecode.secs`` and\n ``Timecode.frs`` attributes are now properties. Because it was so rare to\n check the individual hours, minutes, seconds or frame values, their values\n are calculated with ``Timecode.frames_to_tc()`` method. But in future they\n can still be converted to attributes and their value will be updated each\n time the ``Timecode.frames`` attribute is changed (so add a ``_frames``\n attribute and make ``frames`` a property with a getter and setter, and update\n the hrs, mins, secs and frs in setter etc.).\n\n* **Update:** Removed ``Timecode.calc_drop_frame()`` method. The drop frame\n calculation is neatly done inside ``Timecode.frames_to_tc()`` and\n ``Timecode.tc_to_frames()`` methods.\n\n* **Update:** Updated ``Timecode.parse_timecode()`` method to a much simpler\n algorithm.\n\n* **Update:** Removed ``Timecode.__return_item__()`` method. It is not\n necessary to return an item in that way anymore.\n\n* **Update:** Removed ``Timecode.make_timecode()`` method. It was another\n unnecessary method, so it is removed. Now using simple python string\n templates for string representations.\n\n* **New:** Added ``timecode.__version__`` string, and set the value to\n \"0.2.0\".\n\n* **Update:** Removed ``Timecode.set_int_framerate()`` method. Setting the\n framerate will automatically set the ``Timecode.int_framerate`` attribute.\n",
"bugtrack_url": null,
"license": null,
"summary": "SMPTE Time Code Manipulation Library",
"version": "1.4.1",
"project_urls": {
"Homepage": "https://github.com/eoyilmaz/timecode"
},
"split_keywords": [
"video",
" timecode",
" smpte"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "71430045d51dc626adc07aeb227c9a13626eff38224287b556828bf59f2d9227",
"md5": "d0852fa5f787dd77a783b47f2e7652d8",
"sha256": "e372acd3fa3b02d62f2db343d7d87ba9b9c5a6ae554d1003d006f81d0f81621c"
},
"downloads": -1,
"filename": "timecode-1.4.1.tar.gz",
"has_sig": false,
"md5_digest": "d0852fa5f787dd77a783b47f2e7652d8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 64651,
"upload_time": "2024-07-08T11:44:58",
"upload_time_iso_8601": "2024-07-08T11:44:58.418266Z",
"url": "https://files.pythonhosted.org/packages/71/43/0045d51dc626adc07aeb227c9a13626eff38224287b556828bf59f2d9227/timecode-1.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-08 11:44:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "eoyilmaz",
"github_project": "timecode",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "timecode"
}
JSON
