TiliaJsonLoader

loader.alignment.tilia.TiliaJsonLoader(media_unit=TimeUnit.seconds, **kwargs)

Loader for TiLiA JSON annotation exports.

Parses a TiLiA .tla or .json file and produces one ContinuousPhysicalTimeline (seconds) per annotated timeline in the file. The primary output is a timetoalign.timelines.groups.TimelineGroup containing all timelines, accessible via create_group().

Internally, the "timelines" array is parsed so that each element (which has its own "kind" and "components") becomes a separate pa.Table keyed by its source identifier. The underlying JsonLoader machinery is used for normalising each timeline’s components into a flat table.

The .store property returns a TiliaDictStore with helper properties for each TiLiA timeline type::

loader.store.hierarchy  # all hierarchy tables concatenated
loader.store.marker     # all marker tables concatenated
loader.store.beat       # all beat tables concatenated

Two-phase usage:

  1. loader.load("Bruckner5_Scherzo.json")
  2. group = loader.create_group()
    1. tl = loader.create_timeline("BEAT_TIMELINE_3")
  3. bundle = loader.create_bundle()

Parameters

Name Type Description Default
media_unit TimeUnit The TimeUnit for all timelines. Default TimeUnit.seconds (TiLiA annotations are time-based). TimeUnit.seconds

Examples

>>> loader = TiliaJsonLoader()
>>> loader.load("Bruckner5_Scherzo.json")
>>> group = loader.create_group()
>>> group.n_timelines
7
>>> loader.create_timeline("BEAT_TIMELINE_3").n_events
1146
>>> loader.store.hierarchy._table.num_rows
33

See Also

timetoalign.loader.format.json.JsonLoader timetoalign.timelines.groups.TimelineGroup TiliaDictStore

Attributes

Name Description
media_length Media length in seconds (from media_metadata.media length).
store The TiliaDictStore containing all normalised timeline tables.
timeline_ids Type-based identifiers for all parsed timelines.
timeline_specs Metadata dicts for each parsed timeline.

Methods

Name Description
clear Clear all loaded data, including timeline specs and cache.
create_bundle Create an AlignmentBundle wrapping all timelines in one group.
create_group Create a TimelineGroup containing all (or selected) timelines.
create_timeline Create a single ContinuousPhysicalTimeline by uid.
create_timelines Create multiple timelines.

clear

loader.alignment.tilia.TiliaJsonLoader.clear()

Clear all loaded data, including timeline specs and cache.

create_bundle

loader.alignment.tilia.TiliaJsonLoader.create_bundle()

Create an AlignmentBundle wrapping all timelines in one group.

This is a convenience method. The bundle contains a single TimelineGroup with no cross-group MatchClaim objects.

Returns

Name Type Description
'AlignmentBundle' An AlignmentBundle with one group and no claims.

Raises

Name Type Description
RuntimeError If load() has not been called.

create_group

loader.alignment.tilia.TiliaJsonLoader.create_group(uids=None)

Create a TimelineGroup containing all (or selected) timelines.

This is the primary output method for TiliaJsonLoader. The group is built with all member timelines mapped to the same physical time axis (seconds).

Parameters

Name Type Description Default
uids list[str] | None Timeline identifiers to include. None (default) means all. None

Returns

Name Type Description
'TimelineGroup' A TimelineGroup with one member per timeline.

Raises

Name Type Description
RuntimeError If load() has not been called.

create_timeline

loader.alignment.tilia.TiliaJsonLoader.create_timeline(uid)

Create a single ContinuousPhysicalTimeline by uid.

The uid may be a type-based ID from timeline_ids (for example, "cpt4"), the original TiLiA source ID/title, or an integer index.

Parameters

Name Type Description Default
uid str | int Timeline identifier or integer index. required

Returns

Name Type Description
'Timeline' A ContinuousPhysicalTimeline with events from the
'Timeline' timeline’s components.

Raises

Name Type Description
KeyError If no timeline with uid exists.
RuntimeError If load() has not been called.

create_timelines

loader.alignment.tilia.TiliaJsonLoader.create_timelines(uids=None)

Create multiple timelines.

Parameters

Name Type Description Default
uids list[str] | None List of timeline identifiers to create. If None (the default), all timelines are created. None

Returns

Name Type Description
list['Timeline'] List of ContinuousPhysicalTimeline objects.