TimeStamp

TimeStamp(
    coordinates,
    source_id,
    source=None,
    row_index=None,
    is_interpolated=False,
    conversion_maps=True,
)

A synchronized instant across a timeline hierarchy.

Lightweight object that computes coordinates on access via InterpolationMaps. Works identically for Timeline (with children) and TimelineGroup (with members).

The TimeStamp represents a cross-section through the timeline structure at a specific axis coordinate. Related coordinates are retrieved through the typed precise getters and dispatcher.

Attributes

Name	Type	Description
axis	IdCoordinate	The root/reference coordinate value.
source	TimeStampSource | None	The Timeline or TimelineGroup this timestamp belongs to.
source_id	str	ID of the source (for serialization).
row_index	int | None	If from a table row, the index. -1 if interpolated and None for a direct query on the source axis.

Examples

>>> ts = timeline.get_timestamp(5.0)
>>> ts.axis  # The root coordinate with identity
IdCoordinate(5.0, seconds, 'audio')
>>> ts.get_coordinate_for("child:1", format="float")
2.5

>>> # Convert to different unit
>>> ts.get_unit(TimeUnit.seconds, format="float")
10.5

Methods

Name	Description
get_conversion_for	Get the raw output of a conversion map addressed by name/selector.
get_unit	Convert one stored coordinate through an eligible unit map.

get_conversion_for

TimeStamp.get_conversion_for(key)

Get the raw output of a conversion map addressed by name/selector.

Searches the source and every descendant/member present at this axis for a C-Map whose name, id, selector, or target-unit name is key, and evaluates it at that timeline’s coordinate.

Parameters

Name	Type	Description	Default
key	str	A conversion-map name, id, selector, or target-unit name.	required

Returns

Name	Type	Description
	object	The C-Map’s output at this instant without projection.

Raises

Name	Type	Description
	KeyError	If no enabled map matches key.

get_unit

TimeStamp.get_unit(
    unit,
    *,
    timeline_id=None,
    format='id_coordinate',
    rounding='round',
)

Convert one stored coordinate through an eligible unit map.

Parameters

Name	Type	Description	Default
unit	TimeUnit	Requested target unit.	required
timeline_id	str | None	Optional stored axis to select explicitly.	None
format	CoordinateFormat	Requested coordinate output format.	'id_coordinate'
rounding	Rounding	Integral projection mode.	'round'

Returns

Name	Type	Description
	CoordinateResult | pd.Series	The converted coordinate projection.

Raises

Name	Type	Description
	KeyError	If the selected timeline is absent or no eligible map exists.