RepoVizzLoader

loader.RepoVizzLoader()

Load RepoVizz XML manifests or single CSV files for creating physical timelines.

RepoVizzLoader supports two modes:

XML Manifest Mode (when loading a .xml file): Parses the RepoVizz XML manifest and builds a catalogue of all data files in the recording directory. Provides lazy access to: - Audio recordings (ambient + pickup) - Essentia audio descriptors - Bowing gesture descriptors - MoCap position data - Score alignment files (.notes)

Legacy CSV Mode (when loading a .csv file): Reads the 2-line RepoVizz CSV format for a single sensor signal. This preserves backwards compatibility with existing code.

Both modes create :class:DiscretePhysicalTimeline instances with the samples unit and an attached SamplesToSeconds conversion map.

Examples

XML manifest mode::

>>> loader = RepoVizzLoader.from_file("StringQuartetEEP_I_Normal.xml")
>>> loader.groups
['audio', 'descriptors', 'mocap', 'score']
>>> loader.timeline_ids[:5]
['ROOT0_Audi1_Audi0_Ambi0', 'ROOT0_Audi1_Audi0_Ambi1', ...]

>>> tl = loader.create_timeline("ROOT0_Audi1_Audi0_Ambi0")
>>> tl.length
Coordinate(11753638, samples)

Legacy CSV mode::

>>> loader = RepoVizzLoader.from_file("vln1_bb_angle.csv")
>>> loader.n_samples
63965
>>> loader.frame_rate
240

Attributes

Name	Description
catalogue	The full catalogue of entries (XML mode only).
duration_seconds	Duration in seconds (legacy CSV mode only).
frame_rate	Sampling rate in Hz (legacy CSV mode only).
groups	List of all group names present (XML mode only).
info	Return parsed RepoVizz metadata (legacy CSV mode only).
is_xml_mode	True if loader is in XML manifest mode, False for legacy CSV.
n_samples	Number of data samples (legacy CSV mode only).
store	The `RepovizzDictStore` containing catalogue and cached data.
timeline_ids	Identifiers for all loadable timelines (XML mode only).
timeline_specs	Metadata dicts for each loadable timeline (XML mode only).

Methods

Name	Description
clear	Clear all loaded data.
create_group	Create a TimelineGroup containing timelines.
create_timeline	Create a DiscretePhysicalTimeline from a catalogue entry.
create_timelines	Create multiple timelines.
find_audio	Find an audio entry by source name.
find_audio_descriptor	Find an audio descriptor entry (Essentia features).
find_descriptor	Find a descriptor entry by name.
find_signal	Find a signal entry by name pattern.
get_entry	Get a catalogue entry by ID.
get_sample_rate_for_descriptor_type	Get the sample rate for a descriptor type.
load	Load one or more source files.

clear

loader.RepoVizzLoader.clear()

Clear all loaded data.

create_group

loader.RepoVizzLoader.create_group(
    category=None,
    entries=None,
    *,
    id=None,
    name=None,
    with_notes=False,
)

Create a TimelineGroup containing timelines.

Parameters

Name	Type	Description	Default
category	`str` \| None	Filter to a specific category (“audio”, “mocap”, etc.).	`None`
entries	`list`[`str`] \| None	Specific catalogue entries to include.	`None`
id	`str` \| None	Custom ID for the TimelineGroup. Defaults to `"repovizz:{category or 'all'}"`.	`None`
name	`str` \| None	Custom name for the TimelineGroup. Defaults to the source filename stem.	`None`
with_notes	`bool`	If True, add notes as a child of the first audio timeline using `use_conversion_map=True`. This enables automatic coordinate transfer from seconds (notes) to samples (audio). Default: False.	`False`

Returns: A TimelineGroup containing the specified timelines.

Raises

Name	Type	Description
	`ValueError`	If category is invalid.
	`RuntimeError`	If no XML manifest loaded.

Examples

Load an EEP recording with all timelines and notes:

>>> loader = RepoVizzLoader.from_file("recording.xml")
>>> group = loader.create_group(id="normal", name="Normal Recording", with_notes=True)

create_timeline

loader.RepoVizzLoader.create_timeline(entry=None, *, uid=None, **kwargs)

Create a DiscretePhysicalTimeline from a catalogue entry.

In XML mode: looks up the entry and creates a timeline with its metadata. In legacy CSV mode: creates timeline from the loaded CSV.

Parameters

Name	Type	Description	Default
entry	`str` \| None	Entry lookup key. In XML mode, supports: - Audio shorthand: “mono”, “binaural”, “pickup_vln1” - Descriptor pattern: “tonal.ChordsStrength.mono” - Exact xml_id or name In legacy CSV mode, this is an optional timeline ID.	`None`
**kwargs	`Any`	Additional arguments: - name: Override the timeline’s name (defaults to entry’s name). - attach_cmap: If True (default), attach a SamplesToSeconds C-map.	`{}`
uid	`str` \| None	Override the timeline’s ID (defaults to entry’s xml_id).	`None`

Returns

Name	Type	Description
	'DiscretePhysicalTimeline'	A DiscretePhysicalTimeline representing the data.

Raises

Name	Type	Description
	`RuntimeError`	If no file has been loaded.
	`KeyError`	If entry doesn’t match any catalogue entry (XML mode).

create_timelines

loader.RepoVizzLoader.create_timelines(id_pattern=None, *, entries=None)

Create multiple timelines.

Parameters

Name	Type	Description	Default
id_pattern	`str` \| None	Regex pattern to filter timeline IDs.	`None`
entries	`list`[`str`] \| None	List of catalogue entries to create. If None, all are created.	`None`

Returns

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

find_audio

loader.RepoVizzLoader.find_audio(source)

Find an audio entry by source name.

Parameters

Name	Type	Description	Default
source	`str` \| None	Source name (e.g., “mono”, “binaural”, “pickup_vln1”). For pickup sources, can use “vln1” shorthand.	required

Returns

Name	Type	Description
	`str` \| None	The matching entry ID, or None if not found.

find_audio_descriptor

loader.RepoVizzLoader.find_audio_descriptor(
    descriptor_type,
    descriptor_name,
    source,
)

Find an audio descriptor entry (Essentia features).

Audio descriptors are WAV files with feature data extracted from audio by Essentia. They’re organized by type (tonal, lowlevel, rhythm) and named by the feature (ChordsStrength, Dissonance, etc.).

Parameters

Name	Type	Description	Default
descriptor_type	`str`	Type of descriptor (“tonal”, “lowlevel”, “rhythm”).	required
descriptor_name	`str`	Feature name (e.g., “ChordsStrength”, “Dissonance”).	required
source	`str`	Audio source (e.g., “mono”, “binaural”, “pickup_vln1”).	required

Returns

Name	Type	Description
	`str` \| None	The matching entry ID, or None if not found.

find_descriptor

loader.RepoVizzLoader.find_descriptor(descriptor_name, instrument=None)

Find a descriptor entry by name.

Searches both the entry name and filename for matches. The instrument filter is checked against the subgroup first, then the filename as a fallback (bowing gesture descriptors often encode the instrument in the filename, e.g. vln1_bb_angle.csv).

Parameters

Name	Type	Description	Default
descriptor_name	`str`	Descriptor name (e.g., “bb_angle”, “bow_vel”).	required
instrument	`str` \| None	Optional instrument filter (e.g., “vln1”, “cello”).	`None`

Returns

Name	Type	Description
	`str` \| None	The matching entry ID, or None if not found.

find_signal

loader.RepoVizzLoader.find_signal(name_pattern, source=None)

Find a signal entry by name pattern.

Parameters

Name	Type	Description	Default
name_pattern	`str`	Regex pattern to match signal names.	required
source	`str` \| None	Optional source filter (e.g., “mono”, “vln1”).	`None`

Returns

Name	Type	Description
	`str` \| None	The matching entry ID, or None if not found.

get_entry

loader.RepoVizzLoader.get_entry(id)

Get a catalogue entry by ID.

This is the public API for accessing catalogue entries.

Parameters

Name	Type	Description	Default
id	`str`	Entry identifier, name, or partial match.	required

Returns

Name	Type	Description
	`CatalogueEntry`	The CatalogueEntry.

Raises

Name	Type	Description
	`KeyError`	If not found.

get_sample_rate_for_descriptor_type

loader.RepoVizzLoader.get_sample_rate_for_descriptor_type(descriptor_type)

Get the sample rate for a descriptor type.

Parameters

Name	Type	Description	Default
descriptor_type	`str`	Type of descriptor (“tonal”, “lowlevel”, “rhythm”).	required

Returns

Name	Type	Description
	`int`	Sample rate in Hz.

load

loader.RepoVizzLoader.load(*sources)

Load one or more source files.

If the source is an .xml file, uses XML manifest mode. Otherwise, falls back to legacy CSV mode.

Parameters

Name	Type	Description	Default
*sources	`Path` \| `str`	Paths to XML manifest or CSV files.	`()`

Returns

Name	Type	Description
	`Self`	Self, for method chaining.

Raises

Name	Type	Description
	`FileNotFoundError`	If any source doesn’t exist.
	`ValueError`	If any source is invalid.

RepoVizzLoader

Examples

See Also

Attributes

Methods

clear

create_group

Parameters

Raises

Examples

create_timeline

Parameters

Returns

Raises

create_timelines

Parameters

Returns

find_audio

Parameters

Returns

find_audio_descriptor

Parameters

Returns

find_descriptor

Parameters

Returns

find_signal

Parameters

Returns

get_entry

Parameters

Returns

Raises

get_sample_rate_for_descriptor_type

Parameters

Returns

load

Parameters

Returns

Raises