Time Utils

Utility functions for time intersection algorithms.

auto_detect_timestamp_to_seconds(t, *, video_duration=None, reference_time=None)

Convert a raw timestamp to absolute seconds using contextual heuristics.

Applies decode_timestamp_to_seconds only when duration, sequence order, or batch overflow suggests the value is flat MMS rather than absolute seconds.

Parameters:

Name	Type	Description	Default
t	float	Raw timestamp from transcript output.	required
video_duration	float | None	Total video length in seconds.	None
reference_time	float | None	Previous timestamp in the same sequence.	None

Returns:

Name	Type	Description
float	float	Best-effort absolute seconds.

calculate_time_iob(span_start, span_end, reference_start, reference_end)

Calculate the Intersection over Box (IoB) of a time span relative to a reference span.

This calculates the ratio of intersection length to the span's length.

Parameters:

Name	Type	Description	Default
span_start	float	Start time of the span being measured.	required
span_end	float	End time of the span being measured.	required
reference_start	float	Start time of the reference span (the "box").	required
reference_end	float	End time of the reference span (the "box").	required

Returns:

Name	Type	Description
float	float	A value between 0.0 and 1.0 representing the proportion of the span that overlaps with the reference span.

convert_mmss_to_seconds(value)

Convert a single timestamp from MM.SS format to seconds.

Video-caption models often emit times as minutes.seconds without a separator, e.g. 1.55 means 1 minute 55 seconds (115s), not 1.55 seconds.

Parameters:

Name	Type	Description	Default
value	float | None	Time in MM.SS format.	required

Returns:

Type	Description
float | None	float | None: Time in seconds, or None when the input is None.

decode_timestamp_to_seconds(t)

Decode a structurally valid flat MMS timestamp to absolute seconds.

Flat MMS encodes M:SS as M * 100 + SS where 0 <= SS < 60. Values below 100 or with an invalid seconds slot are returned unchanged.

This function is intentionally agnostic: it always applies the structural decode and does not consider video duration or transcript order.

Parameters:

Name	Type	Description	Default
t	float	Raw timestamp value.	required

Returns:

Name	Type	Description
float	float	Absolute seconds when t is valid flat MMS, otherwise t.

normalize_transcript_timestamps(transcripts, *, video_duration=None)

Normalize transcript start_time / end_time values to absolute seconds.

Parameters:

Name	Type	Description	Default
transcripts	list[AudioTranscript]	Transcript objects to normalize.	required
video_duration	float | None	Total video length in seconds.	None

Returns:

Type	Description
list[AudioTranscript]	list[AudioTranscript]: Transcripts with decoded absolute-second timestamps.