russellaugust/vtc-py

A SMTPE video timecode library for Python

vtc-py

A SMPTE Timecode Library for Python

Overview

vtc-py is inspired by years of scripting workflow solutions in a Hollywood cutting room. It is designed to support both quick, one-off scripts and higher level production code.

vtc aims to capture all the ways in which timecode is used throughout the industry so users can spend more time on their workflow logic, and less time handling the corner-cases of parsing and calculating timecode.

Features

• SMPTE Conventions:
  • NTSC
  • Drop-Frame
  • Interlaced timecode (not implemented)
• Timecode Representations:
  • Timecode | '01:00:00:00'
  • Frames | 86400
  • Seconds | 3600.0
  • Runtime | '01:00:00.0'
  • Rational | 18018/5
  • Feet+Frames | '5400+00'
    • 35mm, 4-perf
    • 35mm, 3-perf
    • 35mm, 2-perf
    • 16mm
  • Premiere Ticks | 15240960000000
• Operations:
  • Comparisons (==, <, <=, >, >=)
  • Add
  • Subtract
  • Scale (multiply and divide)
  • Divmod
  • Modulo
  • Negative
  • Absolute
  • Rebase (recalculate frame count at new framerate)
• Flexible Parsing:
  • Partial timecodes | '1:12'
  • Partial runtimes | '1.5'
  • Negative string values | '-1:12', '-3+00'
  • Poorly formatted tc | '1:13:4'
• Type inference for fast scripting (add a tc string to a Timecode value).
• Built-in consts for common framerates.
• Range type for working with and comparing frame ranges.
• Modern Python Typehints for static analysis.

Demo

Let's take a quick high-level look at what you can do with this library:

>>> import vtc

# It's easy to make a new 23.98 NTSC timecode.
>>> tc = vtc.Timecode("17:23:13:02", rate=23.98)

# We can get all sorts of ways to represent the timecode.
>>> tc.timecode
'17:23:13:02'

>>> tc.frames
1502234

>>> tc.seconds
Decimal('62655.67641666666666666666667')

>>> tc.rational
Fraction(751868117, 12000)

>>> tc.runtime(precision=3)
'17:24:15.676'

>>> tc.premiere_ticks
15915544300656000

>>> tc.feet_and_frames
'93889+10'

# We can inspect the framerate.
>>> tc.rate.playback
Fraction(24000, 1001)

>>> tc.rate.timebase
Fraction(24, 1)

>>> tc.rate.ntsc
True

>>> tc.rate.dropframe
False

# Parsing is flexible
# Partial timecode
>>> vtc.Timecode("3:12", rate=23.98)
[00:00:03:12 @ [23.98 NTSC]]

# Frame count (ints)
>>> vtc.Timecode(24, rate=23.98)
[00:00:01:00 @ [23.98 NTSC]]

# Seconds (floats, decimals, or fractions)
>>> vtc.Timecode(1.5, rate=23.98)
[00:00:01:12 @ [23.98 NTSC]]

# Premiere ticks
>>> vtc.Timecode(vtc.PremiereTicks(254016000000), rate=23.98)
[00:00:01:00 @ [23.98 NTSC]]

# Feet + Frames
>>> vtc.Timecode("1+08", rate=23.98)
[00:00:01:00 @ [23.98 NTSC]]

# We can add two timecodes
>>> tc += vtc.Timecode("01:00:00:00", rate=23.98)
>>> tc
[18:23:13:02 @ [23.98 NTSC]]

# But if we want to do something quickly, we just use a timecode string instead.
>>> tc += "00:10:00:00"
>>> tc.timecode
'18:33:13:02'

# Adding ints means adding frames.
>>> tc += 2
>>> tc.timecode
'18:33:13:04'

# Adding floats, decimals, or fractions means adding seconds.
>>> tc += 1.5
>>> tc.timecode
'18:33:14:16'

# We can subtract too.
>>> tc -= "01:00:00:00"
>>> tc.timecode
'17:33:14:16'

# It's easy to compare two timecodes
>>> tc > vtc.Timecode("02:00:00:00", rate=vtc.RATE.F23_98)
True

# Just like adding, we can use a shortcut and compare directly against a string
>>> "02:00:00:00" < tc
True

# Or against an int to check the frame count.
>>> vtc.Timecode("01:00:00:00", rate=vtc.RATE.F23_98) == 86400
True

# It's easy to sort timecodes.
>>> sorted([tc, vtc.Timecode("03:00:00:00", rate=23.98)])
[[03:00:00:00 @ [23.98 NTSC]], [17:33:14:16 @ [23.98 NTSC]]]

# We can multiply
>>> tc *= 2
>>> tc.timecode
'35:06:29:08'

# ... divide ...
>>> tc /= 2
>>> tc.timecode
'17:33:14:16'

# ... and even get the remainder while dividing!
>>> dividend, remainder = divmod(tc, 3)
>>> dividend.timecode
'05:51:04:21'
>>> remainder.timecode
'00:00:00:01'

# Maybe just the remainder!
>>> remainder = tc % 3
>>> remainder.timecode
'00:00:00:01'

# We can make a timecode negative.
>>> tc = -tc
>>> tc.timecode
'-17:33:14:16'

# Or get it's absolute value.
>>> tc = abs(tc)
>>> tc.timecode
'17:33:14:16'

# We can make dropframe timecode for 29.97 or 59.94 using one of the pre-set
# framerates. We can use an int to parse 15000 frames.
>>> vtc.Timecode(15000, rate=vtc.RATE.F29_97_DF)
[00:08:20;18 @ [29.97 NTSC DF]]

# We can make new timecodes with arbitrary framerates if we want:
>>> vtc.Timecode("01:00:00:00", rate=240)
[01:00:00:00 @ [240]]

# Using a non-whole number indicates this is an NTSC timecode.
>>> vtc.Timecode("01:00:00:00", rate=239.76)
[01:00:00:00 @ [239.76 NTSC]]

# We can signal that we want a whole-frame timebase to be converted to an
# NTSC framerate.
>>> tc = vtc.Timecode("01:00:00:00", rate=vtc.Framerate(48, ntsc=True))
>>> tc
[01:00:00:00 @ [47.95 NTSC]]

# We can also rebase the frames using a new framerate!
>>> tc.rebase(vtc.RATE.F23_98)
[02:00:00:00 @ [23.98 NTSC]]

Goals

• Parse and fetch all Timecode representations.
• A clean, Pythonic API.
• Support all operations that make sense for timecode.
• Sane shortcuts for scripting.

Non-Goals

• Real-time timecode generators.

Installation

pip install vtc

Getting Started

For full documentation: read the docs.

For library development guide, read the docs.

Authors

• Billy Peake - Initial work

Attributions

Drop-frame calculations adapted from David Heidelberger's blog.

Logo made by Freepik from www.flaticon.com