DfttTimeRange API#

class DfttTimeRange[源代码]#

基类：object

High-precision timerange class for representing time intervals.

DfttTimeRange represents a time interval with a start point, duration, and direction. It provides comprehensive operations for manipulating time ranges including offset, extend, shorten, reverse, retime, intersection, and union operations.

The class uses fractions.Fraction internally for precise calculations, ensuring frame-accurate operations even with complex interval manipulations.

参数:

  • start_tc -- Start timecode. Can be a DfttTimecode object or any value that can construct a DfttTimecode. Required if not using precise parameters.

  • end_tc -- End timecode. Can be a DfttTimecode object or any value that can construct a DfttTimecode. Required if not using precise parameters.

  • forward -- Direction of the timerange. True for forward (start < end), False for backward (start > end). Defaults to True.

  • fps -- Frame rate in frames per second. Used when constructing timecodes from non-timecode values. Defaults to 24.0.

  • start_precise_time -- Internal construction parameter - precise start time as Fraction. Use with precise_duration for direct construction.

  • precise_duration -- Internal construction parameter - precise duration as Fraction. Use with start_precise_time for direct construction.

  • strict_24h -- Enable 24-hour constraint mode. When True, the timerange duration cannot exceed 24 hours and midnight-crossing ranges are handled specially. Defaults to False.

fps#

Frame rate of the timerange

Type:

float

forward#

Direction of the timerange

Type:

bool

strict_24h#

Whether 24-hour constraint is enabled

Type:

bool

precise_duration#

Duration as high-precision Fraction

Type:

Fraction

start_precise_time#

Start time as high-precision Fraction

Type:

Fraction

end_precise_time#

End time as high-precision Fraction

Type:

Fraction

duration#

Duration in seconds (absolute value)

Type:

float

framecount#

Duration in frames (absolute value)

Type:

int

start#

Start timecode object

Type:

DfttTimecode

end#

End timecode object

Type:

DfttTimecode

抛出:

示例

Create from two timecodes:

>>> tr = DfttTimeRange('01:00:00:00', '02:00:00:00', fps=24)
>>> print(tr.duration)
3600.0
>>> print(tr.framecount)
86400

Create backward timerange:

>>> tr = DfttTimeRange('02:00:00:00', '01:00:00:00', forward=False, fps=24)
>>> print(tr.start)
02:00:00:00
>>> print(tr.end)
01:00:00:00

Operations:

>>> tr = DfttTimeRange('01:00:00:00', '01:10:00:00', fps=24)
>>> tr2 = tr.offset(600)  # Move forward 600 seconds (10 minutes)
>>> print(tr2.start)
01:10:00:00
>>> tr3 = tr.extend(300)  # Add 5 minutes to duration
>>> print(tr3.duration)
900.0

Iteration:

>>> tr = DfttTimeRange('01:00:00:00', '01:00:00:10', fps=24)
>>> for tc in tr:
...     print(tc)
01:00:00:00
01:00:00:01
...
01:00:00:09

Set operations:

>>> tr1 = DfttTimeRange('01:00:00:00', '02:00:00:00', fps=24)
>>> tr2 = DfttTimeRange('01:30:00:00', '02:30:00:00', fps=24)
>>> intersection = tr1 & tr2  # Intersection operator
>>> print(intersection.start)
01:30:00:00
>>> union = tr1 | tr2  # Union operator
>>> print(union.duration)
5400.0

备注

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

  • The internal representation uses fractions.Fraction for precision.

  • Forward and backward timeranges behave differently in some operations.

  • Zero-length timeranges are not allowed.

参见

  • DfttTimecode: For working with individual timecodes

  • dftt_timecode.error: Custom exception classes

TIME_24H_SECONDS = 86400#

Constant representing 24 hours in seconds (86400).

__init__(start_tc=None, end_tc=None, forward=True, fps=24.0, start_precise_time=None, precise_duration=None, strict_24h=False)[源代码]#
参数:
property fps: float#

Frame rate of the timerange

property forward: bool#

Direction of the timerange

property strict_24h: bool#

Whether timerange is constrained to 24 hours

property precise_duration: Fraction#

Precise duration as Fraction to avoid calculation errors

property start_precise_time: Fraction#

Start time as precise Fraction

property end_precise_time: Fraction#

End time as precise Fraction

property duration: float#

Duration in seconds

property framecount: int#

Duration in frames

property start: DfttTimecode#

Start timecode

property end: DfttTimecode#

End timecode

offset(offset_value)[源代码]#

Move timerange in time while preserving duration.

Shifts the entire timerange by the specified offset amount without changing the duration. Both start and end points move by the same amount.

参数:

offset_value (float | DfttTimecode | str | int) -- Amount to offset the timerange. Can be: - float: Seconds to shift - int: Frames to shift (converted using current fps) - DfttTimecode: Uses the timecode's timestamp - str: Timecode string to parse

返回:

New timerange with shifted start/end points

返回类型:

DfttTimeRange

抛出:

DFTTTimeRangeMethodError -- If offset_value cannot be parsed

示例

>>> tr = DfttTimeRange('01:00:00:00', '01:10:00:00', fps=24)
>>> tr2 = tr.offset(600)  # Offset by 10 minutes (600 seconds)
>>> print(tr2.start)
01:10:00:00
>>> print(tr2.end)
01:20:00:00

备注

In strict_24h mode, the new start time wraps around at 24 hours.

extend(extend_value)[源代码]#

Extend duration (positive value increases duration).

Extends or shortens the timerange by modifying the end point while keeping the start point fixed. Positive values increase duration, negative values decrease it.

参数:

extend_value (int | float | DfttTimecode | str) -- Amount to extend the duration. Can be: - int or float: Seconds to extend (positive) or shorten (negative) - DfttTimecode: Uses the timecode's timestamp - str: Timecode string to parse

返回:

New timerange with modified duration

返回类型:

DfttTimeRange

抛出:

示例

>>> tr = DfttTimeRange('01:00:00:00', '01:10:00:00', fps=24)
>>> tr2 = tr.extend(300)  # Add 5 minutes
>>> print(tr2.duration)
900.0
>>> tr3 = tr.extend(-300)  # Subtract 5 minutes
>>> print(tr3.duration)
300.0

备注

The direction (forward/backward) affects how extension is applied.

shorten(shorten_value)[源代码]#

Shorten duration (positive value decreases duration).

This is a convenience method that calls extend() with a negated value. Shortens the timerange by modifying the end point while keeping the start fixed.

参数:

shorten_value (int | float | DfttTimecode | str) -- Amount to shorten the duration. Can be: - int or float: Seconds to shorten (positive decreases duration) - DfttTimecode: Uses the timecode's timestamp - str: Timecode string to parse

返回:

New timerange with shortened duration

返回类型:

DfttTimeRange

抛出:

示例

>>> tr = DfttTimeRange('01:00:00:00', '01:10:00:00', fps=24)
>>> tr2 = tr.shorten(300)  # Shorten by 5 minutes
>>> print(tr2.duration)
300.0
>>> print(tr2.end)
01:05:00:00

备注

Internally calls extend(-shorten_value) for numeric values.

reverse()[源代码]#

Reverse direction of timerange.

Creates a new timerange with swapped start/end points and inverted direction. The duration magnitude remains the same, but the direction is flipped.

返回:

New timerange with reversed direction

返回类型:

DfttTimeRange

示例

>>> tr = DfttTimeRange('01:00:00:00', '02:00:00:00', fps=24, forward=True)
>>> print(tr.start, '->', tr.end)
01:00:00:00 -> 02:00:00:00
>>> tr_rev = tr.reverse()
>>> print(tr_rev.start, '->', tr_rev.end)
02:00:00:00 -> 01:00:00:00
>>> print(tr_rev.forward)
False
>>> print(tr.duration == tr_rev.duration)
True

备注

  • The new start becomes the old end

  • The forward flag is flipped

  • Duration magnitude is preserved

  • This is useful for working with timeranges that play backward

retime(retime_factor)[源代码]#

Change duration by multiplication factor.

Scales the timerange duration by the given factor while keeping the start point fixed. This is useful for time-stretching or speed-change operations.

参数:

retime_factor (int | float | Fraction) -- Multiplication factor for the duration. Can be: - int or float: Factor to multiply duration by - Fraction: Precise rational factor Examples: 2.0 doubles duration, 0.5 halves it, 1.5 extends by 50%

返回:

New timerange with scaled duration

返回类型:

DfttTimeRange

抛出:

示例

>>> tr = DfttTimeRange('01:00:00:00', '01:10:00:00', fps=24)
>>> print(tr.duration)
600.0
>>> tr2 = tr.retime(2.0)  # Double the duration
>>> print(tr2.duration)
1200.0
>>> print(tr2.end)
01:20:00:00
>>> tr3 = tr.retime(0.5)  # Half the duration (speed up)
>>> print(tr3.duration)
300.0
>>> # Can also use * operator
>>> tr4 = tr * 2
>>> print(tr4.duration)
1200.0

备注

  • Start point remains unchanged

  • Commonly used for speed ramping or time-stretching effects

  • Factor > 1 increases duration (slow down)

  • Factor < 1 decreases duration (speed up)

  • Can also use the * operator for the same effect

separate(num_parts)[源代码]#

Separate timerange into multiple equal parts.

Divides the timerange into a specified number of equal-duration sub-ranges. All parts have the same duration and are contiguous (adjacent with no gaps).

参数:

num_parts (int) -- Number of parts to divide the timerange into (must be >= 2)

返回:

List of timerange parts, ordered from start to end

返回类型:

List[DfttTimeRange]

抛出:

DFTTTimeRangeValueError -- If num_parts is less than 2

示例

>>> tr = DfttTimeRange('01:00:00:00', '01:01:00:00', fps=24)
>>> parts = tr.separate(4)  # Split into 4 equal parts
>>> len(parts)
4
>>> for i, part in enumerate(parts):
...     print(f"Part {i+1}: {part.start} - {part.end}, duration={part.duration}")
Part 1: 01:00:00:00 - 01:00:15:00, duration=15.0
Part 2: 01:00:15:00 - 01:00:30:00, duration=15.0
Part 3: 01:00:30:00 - 01:00:45:00, duration=15.0
Part 4: 01:00:45:00 - 01:01:00:00, duration=15.0
>>> # Each part has equal duration
>>> all(part.duration == tr.duration / 4 for part in parts)
True

备注

  • Each part has duration = original_duration / num_parts

  • Parts are contiguous (no gaps or overlaps)

  • All parts inherit the same fps, forward direction, and strict_24h mode

  • For backward timeranges, parts are still ordered from start to end

  • Useful for splitting work into parallel chunks or creating segments

contains(item, strict_forward=False)[源代码]#

Check if timerange contains another timerange or timecode.

参数:

  • item (DfttTimecode | DfttTimeRange | str | int | float) -- Item to check for containment. Can be: - DfttTimecode: Checks if timecode is within range - DfttTimeRange: Checks if entire timerange is contained - str, int, float: Converted to timecode for checking

  • strict_forward (bool) -- If True, requires contained timerange to have same direction. Only applies when item is a DfttTimeRange. Defaults to False.

返回:

True if item is contained within this timerange, False otherwise

返回类型:

bool

抛出:

DFTTTimeRangeTypeError -- If item cannot be converted to timecode

示例

>>> tr = DfttTimeRange('01:00:00:00', '02:00:00:00', fps=24)
>>> tc = DfttTimecode('01:30:00:00', fps=24)
>>> tr.contains(tc)
True
>>> tr.contains('00:30:00:00')
False
>>> tr2 = DfttTimeRange('01:10:00:00', '01:50:00:00', fps=24)
>>> tr.contains(tr2)
True

备注

For backward timeranges, containment is checked accordingly.

intersect(other)[源代码]#

Calculate intersection of two timeranges (AND operation).

Returns the overlapping portion of two timeranges. Both timeranges must have the same direction and frame rate.

参数:

other (DfttTimeRange) -- Another DfttTimeRange to intersect with

返回:

New timerange representing the intersection, or None if no overlap

返回类型:

DfttTimeRange

抛出:

示例

>>> tr1 = DfttTimeRange('01:00:00:00', '02:00:00:00', fps=24)
>>> tr2 = DfttTimeRange('01:30:00:00', '02:30:00:00', fps=24)
>>> intersection = tr1.intersect(tr2)
>>> print(intersection.start)
01:30:00:00
>>> print(intersection.end)
02:00:00:00
>>> # Can also use & operator
>>> intersection = tr1 & tr2

备注

  • Returns None if timeranges don't overlap

  • Strict_24h is True only if both input timeranges have it enabled

union(other)[源代码]#

Calculate union of two timeranges (OR operation).

Combines two overlapping or adjacent timeranges into a single continuous timerange that spans from the earliest start to the latest end. Both timeranges must have the same direction and frame rate, and must either overlap or be adjacent (touching) with no gap between them.

参数:

other (DfttTimeRange) -- Another DfttTimeRange to union with

返回:

New timerange spanning both input ranges

返回类型:

DfttTimeRange

抛出:

示例

Overlapping timeranges:

>>> tr1 = DfttTimeRange('01:00:00:00', '01:30:00:00', fps=24)
>>> tr2 = DfttTimeRange('01:20:00:00', '02:00:00:00', fps=24)
>>> union = tr1.union(tr2)
>>> print(union.start)
01:00:00:00
>>> print(union.end)
02:00:00:00
>>> print(union.duration)
3600.0

Adjacent (touching) timeranges:

>>> tr1 = DfttTimeRange('01:00:00:00', '01:30:00:00', fps=24)
>>> tr2 = DfttTimeRange('01:30:00:00', '02:00:00:00', fps=24)
>>> union = tr1.union(tr2)  # No gap, they touch
>>> print(union.start)
01:00:00:00
>>> print(union.end)
02:00:00:00

Using the | operator:

>>> tr1 = DfttTimeRange('01:00:00:00', '01:30:00:00', fps=24)
>>> tr2 = DfttTimeRange('01:20:00:00', '02:00:00:00', fps=24)
>>> union = tr1 | tr2  # Shorthand for union
>>> print(union.duration)
3600.0

Non-adjacent timeranges (will fail):

>>> tr1 = DfttTimeRange('01:00:00:00', '01:30:00:00', fps=24)
>>> tr2 = DfttTimeRange('02:00:00:00', '02:30:00:00', fps=24)
>>> union = tr1.union(tr2)  # Gap of 30 minutes
DFTTTimeRangeMethodError: Cannot union non-overlapping, non-adjacent timeranges

备注

  • Timeranges must overlap or be adjacent (no gap allowed)

  • The result spans from earliest start to latest end

  • Direction must be the same for both timeranges

  • Strict_24h is True only if both input timeranges have it enabled

  • This is a set operation, different from add() which combines durations

  • Can also use the | operator as a shorthand

  • For checking overlap, use intersect() first

参见

  • intersect(): Get the overlapping portion (AND operation)

  • add(): Add durations (different from union)

add(other)[源代码]#

Add durations of two timeranges (direction-sensitive).

Combines the durations of two timeranges to create a new timerange with extended duration. The behavior depends on whether the timeranges have the same or opposite directions.

参数:

other (DfttTimeRange) -- Another DfttTimeRange to add

返回:

New timerange with combined duration, same start point

and direction as the original

返回类型:

DfttTimeRange

抛出:

示例

>>> tr1 = DfttTimeRange('01:00:00:00', '01:10:00:00', fps=24)  # 10 min
>>> tr2 = DfttTimeRange('01:00:00:00', '01:05:00:00', fps=24)  # 5 min
>>> tr3 = tr1.add(tr2)
>>> print(tr3.duration)  # Same direction: 10 + 5 = 15 min
900.0
>>> tr4 = DfttTimeRange('01:10:00:00', '01:00:00:00', forward=False, fps=24)
>>> tr5 = tr1.add(tr4)
>>> print(tr5.duration)  # Opposite direction: 10 - 10 = 0 (error)
DFTTTimeRangeValueError

备注

  • Same direction: durations are added (extend)

  • Opposite direction: durations are subtracted (shorten)

  • Start point remains unchanged

  • This is different from union() which combines overlapping ranges

subtract(other)[源代码]#

Subtract durations of two timeranges (direction-sensitive).

Subtracts the duration of another timerange from this one to create a new timerange with reduced duration. The behavior depends on whether the timeranges have the same or opposite directions.

参数:

other (DfttTimeRange) -- Another DfttTimeRange to subtract

返回:

New timerange with reduced duration, same start point

and direction as the original

返回类型:

DfttTimeRange

抛出:

示例

>>> tr1 = DfttTimeRange('01:00:00:00', '01:10:00:00', fps=24)  # 10 min
>>> tr2 = DfttTimeRange('01:00:00:00', '01:03:00:00', fps=24)  # 3 min
>>> tr3 = tr1.subtract(tr2)
>>> print(tr3.duration)  # Same direction: 10 - 3 = 7 min
420.0
>>> print(tr3.end)
01:07:00:00
>>> # With opposite directions
>>> tr4 = DfttTimeRange('01:10:00:00', '01:08:00:00', forward=False, fps=24)
>>> tr5 = tr1.subtract(tr4)  # 10 - (-2) = 12 min
>>> print(tr5.duration)
720.0

备注

  • Same direction: durations are subtracted (shorten)

  • Opposite direction: durations are added (extend)

  • Start point remains unchanged

  • This is the inverse operation of add()

  • Can result in zero-length error if durations are equal

__str__()[源代码]#

Return str(self).

返回类型:

str

__repr__()[源代码]#

Return repr(self).

返回类型:

str

__contains__(item)[源代码]#
返回类型:

bool

__iter__()[源代码]#

Iterate through timecodes in the range

返回类型:

Iterator[DfttTimecode]

__add__(other)[源代码]#

Add operator for timeranges

返回类型:

DfttTimeRange

__sub__(other)[源代码]#

Subtract operator for timeranges

返回类型:

DfttTimeRange

__mul__(factor)[源代码]#

Multiply duration by factor

返回类型:

DfttTimeRange

__truediv__(factor)[源代码]#

Divide duration by factor

返回类型:

DfttTimeRange

__and__(other)[源代码]#

Intersection operator

返回类型:

DfttTimeRange | None

__or__(other)[源代码]#

Union operator

返回类型:

DfttTimeRange

__eq__(other)[源代码]#

Equality comparison

返回类型:

bool

__ne__(other)[源代码]#

Inequality comparison

返回类型:

bool

__lt__(other)[源代码]#

Less than comparison based on start time

返回类型:

bool

__le__(other)[源代码]#

Less than or equal comparison

返回类型:

bool

__gt__(other)[源代码]#

Greater than comparison

返回类型:

bool

__ge__(other)[源代码]#

Greater than or equal comparison

返回类型:

bool

Core Class#

The DfttTimeRange class represents a time range with start and end points, built on top of DfttTimecode.

Examples#

Basic Usage#

from dftt_timecode import DfttTimecode, DfttTimeRange

# Create time range
start = DfttTimecode('01:00:00:00', 'auto', fps=24)
end = DfttTimecode('02:00:00:00', 'auto', fps=24)
range1 = DfttTimeRange(start, end)

# Get duration
print(range1.duration.timecode_output('smpte'))  # '01:00:00:00'

Checking Containment and Intersection#

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

# Check if timecode is within range
if tc in range1:
    print("Timecode is within range")

# Create another range
range2 = DfttTimeRange(
    DfttTimecode('01:30:00:00', 'auto', fps=24),
    DfttTimecode('02:30:00:00', 'auto', fps=24)
)

# Get intersection of two ranges
intersection = range1.intersect(range2)
print(intersection)