DfttTimecode API#

class DfttTimecode[source]#

Bases: object

High-precision timecode class for film and television production.

DfttTimecode provides frame-accurate timecode representation with support for multiple professional formats, high frame rates (0.01-999.99 fps), drop-frame compensation, and comprehensive arithmetic operations.

The class uses fractions.Fraction internally for precise timestamp calculations, ensuring accuracy even with complex operations and format conversions.

Parameters:

  • timecode_value – The timecode value in various supported formats: - str: Timecode string (e.g., ‘01:00:00:00’, ‘01:00:00,000’) - int: Frame count (with timecode_type=’frame’) or seconds (with timecode_type=’time’) - float: Timestamp in seconds - Fraction: Precise timestamp as rational number - tuple/list: Two-element [numerator, denominator] for rational time - DfttTimecode: Returns the same instance (no copy)

  • timecode_type – Format type of the timecode value. Use ‘auto’ for automatic detection. See TimecodeType for available formats. Defaults to ‘auto’.

  • fps – Frame rate in frames per second. Supports 0.01-999.99 fps. Defaults to 24.0.

  • drop_frame – Enable drop-frame compensation for NTSC-compatible frame rates (29.97, 59.94, 119.88 fps and their multiples). Defaults to False.

  • strict – Enable 24-hour wraparound mode. When True, timecodes automatically cycle within 0-24 hour range (e.g., 25:00:00:00 becomes 01:00:00:00). Defaults to True.

type#

Current timecode format type

Type:

str

fps#

Frame rate in frames per second

Type:

float

is_drop_frame#

Whether drop-frame compensation is enabled

Type:

bool

is_strict#

Whether 24-hour strict mode is enabled

Type:

bool

framecount#

Total frame count from zero

Type:

int

timestamp#

Total seconds from zero

Type:

float

precise_timestamp#

High-precision timestamp as Fraction

Type:

Fraction

Raises:

Examples

Create from SMPTE timecode string:

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

Create with automatic format detection:

>>> tc = DfttTimecode('01:00:00,000', 'auto', fps=25)
>>> print(tc.type)
srt

Create from frame count:

>>> tc = DfttTimecode(1000, 'frame', fps=24)
>>> print(tc.timecode_output('smpte'))
00:00:41:16

Create with drop-frame compensation:

>>> tc = DfttTimecode('01:00:00;00', fps=29.97, drop_frame=True)
>>> print(tc.is_drop_frame)
True

Arithmetic operations:

>>> tc1 = DfttTimecode('01:00:00:00', fps=24)
>>> tc2 = tc1 + 100  # Add 100 frames
>>> print(tc2)
01:00:04:04
>>> tc3 = tc1 + 3.5  # Add 3.5 seconds
>>> print(tc3)
01:00:03:12

Format conversion:

>>> tc = DfttTimecode('01:00:00:00', fps=24)
>>> print(tc.timecode_output('srt'))
01:00:00,000
>>> print(tc.timecode_output('ffmpeg'))
01:00:00.00

Note

  • Timecode objects are immutable. All operations return new instances.

  • The internal timestamp uses fractions.Fraction for maximum precision.

  • Drop-frame compensation is automatically validated against frame rate.

  • Negative timecodes are supported with a leading minus sign.

See also

  • DfttTimeRange: For working with time intervals

  • dftt_timecode.pattern: Regex patterns for format validation

  • dftt_timecode.error: Custom exception classes

static __new__(cls, timecode_value=0, timecode_type='auto', fps=24.0, drop_frame=False, strict=True)[source]#
__init__(timecode_value, timecode_type, fps, drop_frame, strict)[source]#
__init__(timecode_value, timecode_type='auto', fps=24.0, drop_frame=None, strict=True)
__init__(timecode_value, timecode_type='time', fps=24.0, drop_frame=False, strict=True)
__init__(timecode_value, timecode_type='frame', fps=24.0, drop_frame=False, strict=True)
__init__(timecode_value, timecode_type='time', fps=24.0, drop_frame=False, strict=True)
__init__(timecode_value, timecode_type='time', fps=24.0, drop_frame=False, strict=True)
__init__(timecode_value, timecode_type='time', fps=24.0, drop_frame=False, strict=True)
property type: str#

Get the current timecode format type.

Returns:

The timecode format type (e.g., ‘smpte’, ‘srt’, ‘ffmpeg’)

Return type:

str

Example

>>> tc = DfttTimecode('01:00:00:00', fps=24)
>>> tc.type
'smpte'
property fps: float#

Get the frame rate in frames per second.

Returns:

The frame rate

Return type:

float

Example

>>> tc = DfttTimecode('01:00:00:00', fps=29.97)
>>> tc.fps
29.97
property is_drop_frame: bool#

Check if drop-frame compensation is enabled.

Returns:

True if drop-frame mode is enabled, False otherwise

Return type:

bool

Note

Drop-frame is automatically enabled for NTSC-compatible frame rates (29.97, 59.94, 119.88 and their multiples) when drop_frame=True.

Example

>>> tc = DfttTimecode('01:00:00;00', fps=29.97, drop_frame=True)
>>> tc.is_drop_frame
True
property is_strict: bool#

Check if 24-hour strict mode is enabled.

Returns:

True if strict mode is enabled, False otherwise

Return type:

bool

Note

In strict mode, timecodes automatically wrap around at 24 hours.

Example

>>> tc = DfttTimecode('25:00:00:00', fps=24, strict=True)
>>> print(tc)
01:00:00:00
property framecount: int#

Get the total frame count from zero.

Returns:

The frame number (zero-indexed)

Return type:

int

Example

>>> tc = DfttTimecode('00:00:01:00', fps=24)
>>> tc.framecount
24
property timestamp: float#

Get the timestamp in seconds from zero.

Returns:

The timestamp in seconds (rounded to 5 decimal places)

Return type:

float

Example

>>> tc = DfttTimecode('00:00:01:00', fps=24)
>>> tc.timestamp
1.0
property precise_timestamp: Fraction#

Get the high-precision timestamp as a Fraction.

Returns:

The precise timestamp for exact calculations

Return type:

Fraction

Note

This is the internal representation used for all calculations to maintain maximum precision.

Example

>>> tc = DfttTimecode('00:00:01:00', fps=24)
>>> tc.precise_timestamp
Fraction(1, 1)
timecode_output(dest_type='auto', output_part=0)[source]#

Convert timecode to specified format and return as string.

Parameters:

  • dest_type (Literal['smpte', 'srt', 'dlp', 'ffmpeg', 'fcpx', 'frame', 'time', 'auto']) – Target timecode format. Use ‘auto’ to output in current format. Available formats: ‘smpte’, ‘srt’, ‘dlp’, ‘ffmpeg’, ‘fcpx’, ‘frame’, ‘time’. Defaults to ‘auto’.

  • output_part (int) – For multi-part formats (SMPTE, SRT, DLP, FFMPEG), specify which part to return. 0 returns the complete timecode string, 1-4 return individual parts (hours, minutes, seconds, frames/subseconds). Defaults to 0.

Returns:

The formatted timecode string

Return type:

str

Raises:

AttributeError – If dest_type is not a valid timecode format

Examples

>>> tc = DfttTimecode('01:00:00:00', fps=24)
>>> tc.timecode_output('srt')
'01:00:00,000'
>>> tc.timecode_output('ffmpeg')
'01:00:00.00'
>>> tc.timecode_output('frame')
'86400'
>>> tc.timecode_output('smpte', output_part=1)  # Get hours only
'01'

Note

  • For ‘auto’, outputs in the current timecode type

  • Falls back to SMPTE format if dest_type is invalid

set_fps(dest_fps, rounding=True)[source]#

Change the frame rate of the timecode.

Parameters:

  • dest_fps (float) – Target frame rate in frames per second (0.01-999.99)

  • rounding (bool) – If True, rounds the internal timestamp to the nearest frame at the new frame rate. If False, preserves exact timestamp. Defaults to True.

Returns:

Self reference for method chaining

Return type:

DfttTimecode

Examples

>>> tc = DfttTimecode('01:00:00:00', fps=24)
>>> tc.set_fps(30)
>>> print(tc.fps)
30.0
>>> print(tc)  # Same time, different frame count
01:00:00:00

Note

This method modifies the object in place and returns self for chaining.

set_type(dest_type='smpte', rounding=True)[source]#

Change the internal timecode format type.

Parameters:

  • dest_type (Literal['smpte', 'srt', 'dlp', 'ffmpeg', 'fcpx', 'frame', 'time', 'auto']) – Target timecode format type. Available formats: ‘smpte’, ‘srt’, ‘dlp’, ‘ffmpeg’, ‘fcpx’, ‘frame’, ‘time’. Defaults to ‘smpte’.

  • rounding (bool) – If True, rounds the timestamp to match the precision of the new format. If False, preserves exact timestamp. Defaults to True.

Returns:

Self reference for method chaining

Return type:

DfttTimecode

Examples

>>> tc = DfttTimecode('01:00:00:00', fps=24)
>>> tc.set_type('srt')
>>> print(tc.type)
'srt'
>>> print(tc)
01:00:00,000

Note

  • This changes the internal type, affecting __str__() output

  • Rounding adjusts precision to match format (e.g., SRT has millisecond precision)

  • Invalid types are ignored with a warning

set_strict(strict=True)[source]#

Change the 24-hour strict mode setting.

Parameters:

strict (bool) – If True, enables 24-hour wraparound (timecodes cycle within 0-24 hours). If False, allows timecodes beyond 24 hours. Defaults to True.

Returns:

Self reference for method chaining

Return type:

DfttTimecode

Examples

>>> tc = DfttTimecode('25:00:00:00', fps=24, strict=False)
>>> print(tc)
25:00:00:00
>>> tc.set_strict(True)
>>> print(tc)
01:00:00:00

Note

Changing strict mode recalculates the internal timestamp with the new mode.

get_audio_sample_count(sample_rate)[source]#

Calculate the number of audio samples at the given sample rate.

Converts the timecode to audio sample count for audio synchronization. Uses high-precision rational arithmetic to avoid rounding errors.

Parameters:

sample_rate (int) – Audio sample rate in Hz (e.g., 44100, 48000, 96000)

Returns:

The number of audio samples (floored to nearest integer)

Return type:

int

Examples

>>> tc = DfttTimecode('00:00:01:00', fps=24)
>>> tc.get_audio_sample_count(48000)
48000
>>> tc = DfttTimecode('00:00:00:01', fps=24)
>>> tc.get_audio_sample_count(48000)  # 1 frame at 24fps
2000

Note

Uses floor division to ensure sample count doesn’t exceed the timecode position.

__repr__()[source]#

Return detailed string representation of the timecode object.

Returns:

Detailed representation including timecode, type, fps, and mode flags

Return type:

str

Example

>>> tc = DfttTimecode('01:00:00:00', fps=24, drop_frame=False)
>>> repr(tc)
'<DfttTimecode>(Timecode:01:00:00:00, Type:smpte,FPS:24.00 NDF, Strict)'
__str__()[source]#

Return timecode as formatted string in current type.

Returns:

Timecode string in the current format type

Return type:

str

Example

>>> tc = DfttTimecode('01:00:00:00', fps=24)
>>> str(tc)
'01:00:00:00'
__add__(other)[source]#

Add timecode with another timecode, frame count, or timestamp.

Parameters:

other (DfttTimecode | int | float | Fraction) – Value to add. Can be: - DfttTimecode: Adds timestamps (must have same fps and drop_frame) - int: Treats as frame count to add - float: Treats as seconds to add - Fraction: Treats as precise seconds to add

Returns:

New timecode object with the sum

Return type:

DfttTimecode

Raises:

DFTTTimecodeOperatorError – If fps or drop_frame don’t match between timecodes, or if other is an unsupported type

Examples

>>> tc = DfttTimecode('01:00:00:00', fps=24)
>>> result = tc + 100  # Add 100 frames
>>> print(result)
01:00:04:04
>>> result = tc + 3.5  # Add 3.5 seconds
>>> print(result)
01:00:03:12
>>> tc2 = DfttTimecode('00:10:00:00', fps=24)
>>> result = tc + tc2
>>> print(result)
01:10:00:00

Note

  • Result inherits the format type of the left operand

  • If either operand has strict=True, result will have strict=True

__radd__(other)[source]#

Reflected addition (called when left operand doesn’t support +).

Implements commutative property: other + timecode == timecode + other

Parameters:

other (int | float | Fraction) – Value to add (int, float, or Fraction)

Returns:

New timecode object with the sum

Return type:

DfttTimecode

Example

>>> tc = DfttTimecode('01:00:00:00', fps=24)
>>> result = 100 + tc  # Same as tc + 100
>>> print(result)
01:00:04:04
__sub__(other)[source]#

Subtract timecode, frame count, or timestamp from this timecode.

Parameters:

other (DfttTimecode | int | float | Fraction) – Value to subtract. Can be: - DfttTimecode: Subtracts timestamps (must have same fps and drop_frame) - int: Treats as frame count to subtract - float: Treats as seconds to subtract - Fraction: Treats as precise seconds to subtract

Returns:

New timecode object with the difference

Return type:

DfttTimecode

Raises:

DFTTTimecodeOperatorError – If fps or drop_frame don’t match between timecodes, or if other is an unsupported type

Examples

>>> tc = DfttTimecode('01:00:00:00', fps=24)
>>> result = tc - 100  # Subtract 100 frames
>>> print(result)
00:59:55:20
>>> result = tc - 3.5  # Subtract 3.5 seconds
>>> print(result)
00:59:56:12

Note

Result can be negative, which will be displayed with a leading minus sign.

__mul__(other)[source]#

Multiply timecode by a numeric factor.

Parameters:

other (int | float | Fraction) – Multiplication factor (int, float, or Fraction)

Returns:

New timecode with timestamp multiplied by factor

Return type:

DfttTimecode

Raises:

DFTTTimecodeOperatorError – If attempting to multiply two timecodes or if other is an unsupported type

Examples

>>> tc = DfttTimecode('00:00:10:00', fps=24)
>>> result = tc * 2  # Double the timecode
>>> print(result)
00:00:20:00
>>> result = tc * 0.5  # Half the timecode
>>> print(result)
00:00:05:00

Note

Multiplying two timecode objects together is not allowed and will raise an error.

__rmul__(other)[source]#

Reflected multiplication (implements commutative property).

Parameters:

other (int | float | Fraction) – Multiplication factor (int, float, or Fraction)

Returns:

New timecode with timestamp multiplied by factor

Return type:

DfttTimecode

Example

>>> tc = DfttTimecode('00:00:10:00', fps=24)
>>> result = 2 * tc  # Same as tc * 2
>>> print(result)
00:00:20:00
__truediv__(other)[source]#

Divide timecode by a numeric factor.

Parameters:

other (int | float | Fraction) – Division factor (int, float, or Fraction)

Returns:

New timecode with timestamp divided by factor

Return type:

DfttTimecode

Raises:

DFTTTimecodeOperatorError – If attempting to divide timecodes or if other is an unsupported type

Examples

>>> tc = DfttTimecode('00:00:10:00', fps=24)
>>> result = tc / 2  # Half the timecode
>>> print(result)
00:00:05:00

Note

Dividing two timecode objects is not allowed and will raise an error.

__eq__(other)[source]#

Check equality with another timecode or numeric value.

Parameters:

other (DfttTimecode | int | float | Fraction) – Value to compare. Can be: - DfttTimecode: Compares timestamps (must have same fps) - int: Compares as frame count - float: Compares as seconds - Fraction: Compares as precise seconds

Returns:

True if values are equal (within 5 decimal places), False otherwise

Return type:

bool

Raises:

Examples

>>> tc1 = DfttTimecode('01:00:00:00', fps=24)
>>> tc2 = DfttTimecode('01:00:00:00', fps=24)
>>> tc1 == tc2
True
>>> tc1 == 86400  # Compare with frame count
True
>>> tc1 == 3600.0  # Compare with seconds
True
__ne__(other)[source]#

Check inequality with another timecode or numeric value.

Parameters:

other (DfttTimecode | int | float | Fraction) – Value to compare (DfttTimecode, int, float, or Fraction)

Returns:

True if values are not equal, False otherwise

Return type:

bool

Example

>>> tc1 = DfttTimecode('01:00:00:00', fps=24)
>>> tc2 = DfttTimecode('01:00:00:01', fps=24)
>>> tc1 != tc2
True
__lt__(other)[source]#

Check if this timecode is less than another value.

Parameters:

other (DfttTimecode | int | float | Fraction) – Value to compare. Can be: - DfttTimecode: Compares timestamps (must have same fps) - int: Compares as frame count - float: Compares as seconds - Fraction: Compares as precise seconds

Returns:

True if this timecode is less than other, False otherwise

Return type:

bool

Raises:

Example

>>> tc1 = DfttTimecode('01:00:00:00', fps=24)
>>> tc2 = DfttTimecode('02:00:00:00', fps=24)
>>> tc1 < tc2
True
__le__(other)[source]#

Return self<=value.

__gt__(other)[source]#

Return self>value.

__ge__(other)[source]#

Return self>=value.

__neg__()[source]#

Return the negation of this timecode.

Returns:

New timecode with negated timestamp

Return type:

DfttTimecode

Note

In strict mode, negative timecodes wrap around within 24 hours. For example, -01:00:00:00 becomes 23:00:00:00 in strict mode.

Examples

>>> tc = DfttTimecode('01:00:00:00', fps=24, strict=False)
>>> neg_tc = -tc
>>> print(neg_tc)
-01:00:00:00
>>> tc_strict = DfttTimecode('01:00:00:00', fps=24, strict=True)
>>> neg_tc_strict = -tc_strict
>>> print(neg_tc_strict)
23:00:00:00
__float__()[source]#

Convert timecode to float (seconds).

Returns:

The timestamp in seconds

Return type:

float

Example

>>> tc = DfttTimecode('00:00:10:00', fps=24)
>>> float(tc)
10.0
__int__()[source]#

Convert timecode to integer (frame count).

Returns:

The frame count

Return type:

int

Example

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

Core Class#

The DfttTimecode class is the main interface for working with timecodes in various formats.

Supported Timecode Types#

The following timecode types are supported:

  • auto: Automatic detection based on input format

  • smpte: SMPTE timecode format (HH:MM:SS:FF or HH:MM:SS;FF for drop-frame)

  • srt: SubRip subtitle format (HH:MM:SS,mmm)

  • ffmpeg: FFmpeg format (HH:MM:SS.ff)

  • fcpx: Final Cut Pro X format (frames/fps)

  • dlp: DLP Cinema format (HH:MM:SS:FFF)

  • frame: Frame count (integer)

  • time: Timestamp in seconds (float)

Examples#

Basic Usage#

from dftt_timecode import DfttTimecode

# Create a timecode
tc = DfttTimecode('01:00:00:00', 'auto', fps=24, drop_frame=False, strict=True)

# Access properties
print(tc.framecount)  # 86400
print(tc.timestamp)   # 3600.0

Format Conversion#

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

# Convert to different formats
print(tc.timecode_output('srt'))     # '01:00:00,000'
print(tc.timecode_output('ffmpeg'))  # '01:00:00.00'

Arithmetic Operations#

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

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

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