The vtc module contains types for working with SMPTE and arbitrary timecode.

Timecode

class Timecode(src, *, rate)[source]

Timecode represents the frame at a particular time in a video.

Parameters

  • src (Union[str, int, float, Fraction, Decimal, PremiereTicks, Timecode]) –

    The source value to parse. The values type determines how it is interpreted:

    • vtc.Timecode: used the vtc.Timecode.rational seconds value to construct a new timecode.

    • string: etiher a timecode, runtime, or feet+frames string. Runtime strings must have a fractal seconds place, i.e. ‘01:00:00.0’.

    • int: frame count.

    • decimal.Decimal: seconds.

    • float: seconds.

    • fractions.Fraction: seconds.

    • vtc.PremiereTicks: Adobe Premiere Pro ticks value.

  • rate (Union[Framerate, str, Tuple[int, int], Fraction, float, None]) – The framerate to use for this timecode. May be any value which can be passed to the constructor of Framerate or a Framerate. May only be None if src is a Framerate instance.

Returns

A newly constructed Timecode value.

Raises

  • ValueError – If a string value passed to the constructor is not a valid timecode, runtime, or feet+frames, or no rate value can be found.

  • TypeError – If passed an unsupported type.

rebase(new_rate)[source]

rebase re-calculates the timecode at a new frame rate based on the frame-count value of the current timecode.

Parameters

new_rate (Union[Framerate, str, Tuple[int, int], Fraction, float]) – the new rate to rebase at.

Return type

Timecode

Returns

The new, rebased timecode.

runtime(precision=9)[source]

Runtime returns the true runtime of the timecode in HH:MM:SS.FFFFFFFFF format.

Parameters

precision (Optional[int]) – how many places to print for fractional seconds. None=no rounding.

Runtime will always be returned with at least one decimal place in order to distinguish it from timecode without an hours value. A runtime of exactly one hour will be returned as ‘01:00:00.0’

Note: The true runtime will often diverge from the hours, minutes, and seconds

value of the timecode representation when dealing with non-whole-frame framerates. Even drop-frame timecode does not continuously adhere 1:1 to the actual runtime. For instance, [01:00:00;00 @ 29.97 DF] has a true runtime of ‘00:59:59.9964’, and [01:00:00:00 @ 23.98 NTSC] has a true runtime of ‘01:00:03.6’

Return type

str

property feet_and_frames: str

returns the number of feet and frames this timecode represents if it were shot on 35mm 4-perf film (16 frames per foot). ex: ‘5400+13’.

feet and frames is most commonly used as a reference in the sound mixing world.

Return type

str

property frames: int

frames returns the frame number of this timecode (how many frames would have played starting at 0 between 00:00:00:00 and the tc this value represents.).

Return type

int

property premiere_ticks: vtc._premiere_ticks.PremiereTicks

premiere_ticks returns the number of elapsed ticks this timecode represents in Adobe Premiere Pro.

Premiere uses ticks internally to track elapsed time. A second contains 254016000000 ticks, regardless of framerate.

These ticks are present in Premiere FCP7XML cutlists, and can sometimes be used for more precise calculations during respeeds.

Ticks are also used for scripting in Premiere Panels.

Return type

PremiereTicks

property rate: vtc._framerate.Framerate

rate is the framerate at which this timecode is being interpreted

Return type

Framerate

property rational: fractions.Fraction

frac is a rational (fraction) representation of number of seconds this timecode represents.

Return type

Fraction

property seconds: decimal.Decimal

seconds returns the number of seconds that would have elapsed between 00:00:00:00 and the timecode this value represents.

This value is a decimal.Decimal value to avoid floating-point shenanigans.

Return type

Decimal

property sections: vtc._timecode_sections.TimecodeSections

sections returns the sections of a timecode as ints for callers to format/work on as desired.

Return type

TimecodeSections

property timecode: str

timecode returns the formatted SMPTE timecode: (ex: 01:00:00:00).

Return type

str

Framerate

class Framerate(src, *, ntsc=None, dropframe=False)[source]

Framerate is the rate at which a video file frames are played back.

Framerate is measured in frames-per-second (24/1 = 24 frames-per-second).

Parameters

  • src (Union[Framerate, str, Tuple[int, int], Fraction, float]) –

    the source value to parse to a Framerate. src must conform to one of the following value types:

    • Framerate: Another timebase value.

    • str: Strings may be of a fractional value (‘24/1’), whole numbers representing the fps (‘24’) OR decimal numbers like (‘23.9876’) or 23.98. Such values will be converted to their actual meaning (24000/1001).

    • Tuple[int, int]: Numerator and denominator of a fraction.

    • fractions.Fraction value.

    • float value – only allowed if ntsc=true.

    Note

    if a value like 1/24 is passed in (where the numerator is less than the denominator), the value will be converted to 24/1 after being parsed.

  • ntsc (Optional[bool]) –

    Whether timecode should be calculated via NTSC convention.

    For NTSC, playback speed is 23.976, the TIMECODE is still calculated as if it were at 24fps, which affects how a timecode() value will be rendered.

    When None, non-whole number floats like 23.98 and fractional values with a denominator of 1001 will be assumed to be ntsc, but whole-numbers will be left as-is.

    When this option is True, the framerate will be rounded to the nearest whole number before the timecode() representation is calculated.

  • dropframe (bool) – Whether this is a drop-frame style timecode (only available for frame rates divisible by 30000/1001 like 29.97 and 59.94).

property dropframe: bool

Whether this Framerate is drop-frame.

Return type

bool

property ntsc: bool

Whether this is an NTSC-style time base (aka 23.98, 24000/1001, etc).

Return type

bool

property playback: fractions.Fraction

The rational representation of the real-world video playback speed in frames-per-second as a fraction.

example: 24000/1001.

Note

playback() and timebase() only differ in NTSC framerates. All non-NTSC framerates will have identical values for both properties.

Return type

Fraction

property timebase: fractions.Fraction

The rational representation of the timecode display speed in frames-per-second as a fraction.

example: 24/1

Note

playback() and timebase() only differ in NTSC framerates. All non-NTSC framerates will have identical values for both properties.

Return type

Fraction

RATE

RATE

Rate contains a number of pre-defined, common framerates for ease-of-use

Attribute

Framerate

NTSC

DROP FRAME

F23_98

24000/1001

True

False

F24

24/1

False

False

F29_97_NDF

30000/1001

True

False

F29_97_DF

30000/1001

True

True

F30

30/1

False

False

F47_95

40000/1001

True

False

F48

48/1

False

False

F59_94_NDF

60000/1001

True

False

F59_94_DF

60000/1001

True

True

F60

60/1

False

True

PremiereTicks

class PremiereTicks[source]

PremiereTicks signals than an int value represents an Adobe Premier Pro ticks value and can be used to wrap ints for parsing tc and doing mathematical operations.

Range

class Range(tc1, tc2)[source]

Represents the range between two timecodes. A timecode Range is exclusive. Timecode ranges cannot be negative in length, the absolute value between the two timecodes is used.

Parameters

  • tc1 (Timecode) – The in point of the range.

  • tc2 (Timecode) – The out point of the range. This timecode is not actually in the range itself, but marks the delimiter where the range ends.

Raises

ValueError – when the framerates of the two timecodes do not match.

Note

If tc1 is less than tc2, the values will be flipped, and tc2 will be used as the in point, while tc1 is used as the out point.

intersection(other)[source]

Returns None if the two ranges do not intersect, otherwise returns the Range of the intersection of the two Ranges.

Parameters

other (Range) –

Return type

Optional[Range]

separation(other)[source]

Returns None if the two ranges intersect, otherwise returns the timecode range between the two ranges.

Parameters

other (Range) –

Return type

Optional[Range]

property tc_in: vtc._timecode.Timecode

The in point of the range.

Return type

Timecode

property tc_out: vtc._timecode.Timecode

The out point of the range.

Return type

Timecode