Quick Start#

This guide will help you get started with dftt_timecode quickly.

Importing the Library#

from dftt_timecode import DfttTimecode

Creating Timecode Objects#

There are multiple ways to create timecode objects:

SMPTE Format#

# Non-drop-frame
tc = DfttTimecode('01:00:00:00', 'auto', fps=24, drop_frame=False, strict=True)

# Drop-frame (uses semicolon separator)
tc_df = DfttTimecode('01:00:00;00', 'auto', fps=29.97, drop_frame=True)

Frame Count#

# Using frame count with 'f' suffix
tc = DfttTimecode('1000f', 'auto', fps=24)

# Using integer (automatically treated as frame count)
tc = DfttTimecode(1000, 'auto', fps=119.88, drop_frame=True)

Timestamp#

# Using timestamp with 's' suffix
tc = DfttTimecode('3600.0s', 'auto', fps=24)

# Using float (automatically treated as timestamp)
tc = DfttTimecode(3600.0, 'auto', fps=23.976)

# Using Fraction for precise frame rates
from fractions import Fraction
tc = DfttTimecode(3600.0, 'auto', fps=Fraction(60000, 1001))

Other Formats#

# SRT format
tc = DfttTimecode('01:00:00,000', 'auto', fps=24)

# FFMPEG format
tc = DfttTimecode('01:00:00.00', 'auto', fps=24)

# FCPX format
tc = DfttTimecode('1/24s', 'auto', fps=24)

Accessing Timecode Properties#

tc = DfttTimecode('01:00:00:00', 'auto', fps=24)

print(tc.type)         # 'smpte'
print(tc.fps)          # 24
print(tc.framecount)   # 86400
print(tc.timestamp)    # 3600.0
print(tc.is_drop_frame)  # False
print(tc.is_strict)    # True

Converting Between Formats#

tc = DfttTimecode('01:00:00:00', 'auto', fps=24)

# Convert to different formats
print(tc.timecode_output('smpte'))   # '01:00:00:00'
print(tc.timecode_output('srt'))     # '01:00:00,000'
print(tc.timecode_output('ffmpeg'))  # '01:00:00.00'
print(tc.timecode_output('fcpx'))    # '86400/24s'

# Get specific parts (1=hours, 2=minutes, 3=seconds, 4=frames/ms)
print(tc.timecode_output('smpte', output_part=1))  # '01'
print(tc.timecode_output('smpte', output_part=4))  # '00'

Arithmetic Operations#

Adding Timecodes#

tc1 = DfttTimecode('01:00:00:00', 'auto', fps=24)
tc2 = DfttTimecode('00:30:00:00', 'auto', fps=24)

result = tc1 + tc2
print(result.timecode_output('smpte'))  # '01:30:00:00'

# Add frames
result = tc1 + 100
print(result.timecode_output('smpte'))  # '01:00:04:04'

# Add seconds
result = tc1 + 60.0
print(result.timecode_output('smpte'))  # '01:01:00:00'

Subtracting Timecodes#

tc1 = DfttTimecode('01:00:00:00', 'auto', fps=24)
tc2 = DfttTimecode('00:30:00:00', 'auto', fps=24)

result = tc1 - tc2
print(result.timecode_output('smpte'))  # '00:30:00:00'

Multiplying and Dividing#

tc = DfttTimecode('01:00:00:00', 'auto', fps=24)

# Multiply
result = tc * 2
print(result.timecode_output('smpte'))  # '02:00:00:00'

# Divide
result = tc / 2
print(result.timecode_output('smpte'))  # '00:30:00:00'

Comparison Operations#

tc1 = DfttTimecode('01:00:00:00', 'auto', fps=24)
tc2 = DfttTimecode('00:30:00:00', 'auto', fps=24)

print(tc1 == tc2)  # False
print(tc1 != tc2)  # True
print(tc1 > tc2)   # True
print(tc1 >= tc2)  # True
print(tc1 < tc2)   # False
print(tc1 <= tc2)  # False

Changing Timecode Properties#

Changing Frame Rate#

tc = DfttTimecode('01:00:00:101', 'auto', fps=120)

# Change FPS with rounding
tc.set_fps(24, rounding=True)
print(tc.timecode_output('smpte'))  # Frame-aligned result

# Change FPS without rounding (preserves timestamp)
tc.set_fps(24, rounding=False)
print(tc.timecode_output('smpte'))  # Exact timestamp conversion

Changing Strict Mode#

tc = DfttTimecode('25:01:02:05', 'auto', fps=24, strict=False)
print(tc.timecode_output('smpte'))  # '25:01:02:05'

tc.set_strict(True)
print(tc.timecode_output('smpte'))  # '01:01:02:05' (wrapped to 24 hours)

Changing Timecode Type#

tc = DfttTimecode('01:00:00,123', 'auto', fps=24)
print(tc.type)  # 'srt'

tc.set_type('smpte', rounding=True)
print(tc.type)  # 'smpte'
print(tc.timecode_output('smpte'))  # Frame-aligned SMPTE timecode

Strict Mode#

Strict mode ensures timecodes stay within a 24-hour range:

# With strict mode enabled (default)
tc = DfttTimecode('25:00:00:00', 'auto', fps=24, strict=True)
print(tc.timecode_output('smpte'))  # '01:00:00:00'

# With strict mode disabled
tc = DfttTimecode('25:00:00:00', 'auto', fps=24, strict=False)
print(tc.timecode_output('smpte'))  # '25:00:00:00'

# Negative values
tc = DfttTimecode('-01:00:00:00', 'auto', fps=24, strict=True)
print(tc.timecode_output('smpte'))  # '23:00:00:00'