DfttTimecode API

class DfttTimecode

基类：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.

参数:

• 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

抛出:

• DFTTTimecodeInitializationError -- When initialization parameters are incompatible

• DFTTTimecodeTypeError -- When timecode type doesn't match the value format

• DFTTTimecodeValueError -- When timecode value is invalid for the given parameters

示例

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

备注

• 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.

参见

• 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)

__init__(timecode_value, timecode_type, fps, drop_frame, strict)

__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.

返回:

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

返回类型:

str

示例

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

property fps: float

Get the frame rate in frames per second.

返回:

The frame rate

返回类型:

float

示例

>>> 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.

返回:

True if drop-frame mode is enabled, False otherwise

返回类型:

bool

备注

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

示例

>>> 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.

返回:

True if strict mode is enabled, False otherwise

返回类型:

bool

备注

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

示例

>>> 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.

返回:

The frame number (zero-indexed)

返回类型:

int

示例

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

property timestamp: float

Get the timestamp in seconds from zero.

返回:

The timestamp in seconds (rounded to 5 decimal places)

返回类型:

float

示例

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

property precise_timestamp: Fraction

Get the high-precision timestamp as a Fraction.

返回:

The precise timestamp for exact calculations

返回类型:

Fraction

备注

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

示例

>>> tc = DfttTimecode('00:00:01:00', fps=24)
>>> tc.precise_timestamp
Fraction(1, 1)

timecode_output(dest_type='auto', output_part=0)

Convert timecode to specified format and return as string.

参数:

• 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.

返回:

The formatted timecode string

返回类型:

str

抛出:

AttributeError -- If dest_type is not a valid timecode format

示例

>>> 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'

备注

• For 'auto', outputs in the current timecode type

• Falls back to SMPTE format if dest_type is invalid

set_fps(dest_fps, rounding=True)

Change the frame rate of the timecode.

参数:

• 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.

返回:

Self reference for method chaining

返回类型:

DfttTimecode

示例

>>> 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

备注

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

set_type(dest_type='smpte', rounding=True)

Change the internal timecode format type.

参数:

• 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.

返回:

Self reference for method chaining

返回类型:

DfttTimecode

示例

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

备注

• 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)

Change the 24-hour strict mode setting.

参数:

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

返回:

Self reference for method chaining

返回类型:

DfttTimecode

示例

>>> 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

备注

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

get_audio_sample_count(sample_rate)

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.

参数:

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

返回:

The number of audio samples (floored to nearest integer)

返回类型:

int

示例

>>> 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

备注

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

__repr__()

Return detailed string representation of the timecode object.

返回:

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

返回类型:

str

示例

>>> 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__()

Return timecode as formatted string in current type.

返回:

Timecode string in the current format type

返回类型:

str

示例

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

__add__(other)

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

参数:

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

返回:

New timecode object with the sum

返回类型:

DfttTimecode

抛出:

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

示例

>>> 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

备注

• Result inherits the format type of the left operand

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

__radd__(other)

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

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

参数:

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

返回:

New timecode object with the sum

返回类型:

DfttTimecode

示例

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

__sub__(other)

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

参数:

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

返回:

New timecode object with the difference

返回类型:

DfttTimecode

抛出:

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

示例

>>> 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

备注

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

__mul__(other)

Multiply timecode by a numeric factor.

参数:

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

返回:

New timecode with timestamp multiplied by factor

返回类型:

DfttTimecode

抛出:

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

示例

>>> 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

备注

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

__rmul__(other)

Reflected multiplication (implements commutative property).

参数:

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

返回:

New timecode with timestamp multiplied by factor

返回类型:

DfttTimecode

示例

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

__truediv__(other)

Divide timecode by a numeric factor.

参数:

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

返回:

New timecode with timestamp divided by factor

返回类型:

DfttTimecode

抛出:

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

示例

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

备注

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

__eq__(other)

Check equality with another timecode or numeric value.

参数:

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

返回:

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

返回类型:

bool

抛出:

• DFTTTimecodeOperatorError -- If comparing timecodes with different fps

• DFTTTimecodeTypeError -- If other is an unsupported type

示例

>>> 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)

Check inequality with another timecode or numeric value.

参数:

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

返回:

True if values are not equal, False otherwise

返回类型:

bool

示例

>>> tc1 = DfttTimecode('01:00:00:00', fps=24)
>>> tc2 = DfttTimecode('01:00:00:01', fps=24)
>>> tc1 != tc2
True

__lt__(other)

Check if this timecode is less than another value.

参数:

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

返回:

True if this timecode is less than other, False otherwise

返回类型:

bool

抛出:

• DFTTTimecodeOperatorError -- If comparing timecodes with different fps

• DFTTTimecodeTypeError -- If other is an unsupported type

示例

>>> tc1 = DfttTimecode('01:00:00:00', fps=24)
>>> tc2 = DfttTimecode('02:00:00:00', fps=24)
>>> tc1 < tc2
True

__le__(other)

Return self<=value.

__gt__(other)

Return self>value.

__ge__(other)

Return self>=value.

__neg__()

Return the negation of this timecode.

返回:

New timecode with negated timestamp

返回类型:

DfttTimecode

备注

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

示例

>>> 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__()

Convert timecode to float (seconds).

返回:

The timestamp in seconds

返回类型:

float

示例

>>> tc = DfttTimecode('00:00:10:00', fps=24)
>>> float(tc)
10.0

__int__()

Convert timecode to integer (frame count).

返回:

The frame count

返回类型:

int

示例

>>> 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'