EventStore

EventStore()

Abstract base class for collections of EventData.

Provides a uniform interface for both single-data and multi-data stores, enabling consistent timeline creation across loader types.

All stores must implement the collection protocol (iteration, keys, items, getitem) to allow uniform access to their constituent data.

NOTE: This class was renamed from EventBundle to EventStore in the 2026-01 API refactoring. EventStore holds one or more EventData tables.

Subclasses: - ScoreStore: notes, measures, controls, annotations - MidiStore: notes, controls - SingleStore: generic wrapper for any single EventData

Examples: >>> # Iterate over stores >>> for name, store in bundle.items(): … print(f”{name}: {len(store)} events”)

>>> # Create default timeline with children
>>> timeline = bundle.create_timeline(uid="my_score")

>>> # Create filtered timeline
>>> timeline = bundle.create_timeline(
...     store_filters={"notes": {"event_type": "Note"}},
...     exclude_stores=["annotations"],
... )

Attributes

Name	Description
event_count	Total number of events across all data tables in the store.

Methods

Name	Description
create_timeline	Create a Timeline from this store.
get_cmaps	Get ConversionMaps derivable from store metadata.
items	Iterate over (name, data) pairs in canonical order.
keys	Return data names in canonical order.
summary	Get a summary of the store contents.
values	Iterate over data.

create_timeline

EventStore.create_timeline(
    uid=None,
    store_filters=None,
    include_stores=None,
    exclude_stores=None,
    flatten=False,
)

Create a Timeline from this store.

By default, each data becomes a child timeline embedded at offset 0, maintaining its own 0-based coordinate system. The parent timeline’s length equals the maximum length across all children.

Args: uid: Unique ID for the parent timeline. Auto-generated if None. store_filters: Per-data filter kwargs to apply before timeline creation. Example: {“notes”: {“event_type”: “Note”}} excludes rests from the notes data. include_stores: Only include these data (default: all non-empty). exclude_stores: Exclude these data from the timeline. flatten: If True, merge all events into a single parent timeline without children. If False (default), each data becomes a child timeline at offset 0.

Returns: A Timeline with the requested structure.

Raises: ValueError: If no data remain after filtering, or all data are empty.

Examples: >>> # Default: each data as a child >>> timeline = store.create_timeline(uid=“my_score”) >>> notes = timeline.get_child(“notes”)

>>> # Filtered: only Note events, exclude annotations
>>> timeline = store.create_timeline(
...     store_filters={"notes": {"event_type": "Note"}},
...     exclude_stores=["annotations"],
... )

get_cmaps

EventStore.get_cmaps()

Get ConversionMaps derivable from store metadata.

Returns a dictionary mapping target unit names to ConversionMaps that can convert from this bundle’s native unit. Subclasses should override to provide maps based on available metadata (PPQ, tempo events, sample rate, etc.).

Returns: Dict mapping target unit name (e.g., “quarters”, “seconds”) to ConversionMap instances. Empty dict if no C-Maps can be derived.

Examples: >>> bundle = midi_loader.load(“performance.mid”) >>> cmaps = bundle.get_cmaps() >>> if “quarters” in cmaps: … quarters = cmaps“quarters” # Convert 960 ticks

items

EventStore.items()

Iterate over (name, data) pairs in canonical order.

Yields: Tuples of (data_name, EventData).

keys

EventStore.keys()

Return data names in canonical order.

Returns: Tuple of data names.

summary

EventStore.summary()

Get a summary of the store contents.

Returns a dictionary mapping table/data names to summary information: - unit: The time unit of the data - range: Tuple of (min_coord, max_coord) for events - count: Number of events in the table

Subclasses may override to provide additional domain-specific information (e.g., event type breakdown, has_rests for ScoreStore).

Returns: Dict mapping table names to summary dicts.

Examples: >>> store = SomeStore(…) >>> store.summary() {“notes”: {“unit”: “quarters”, “range”: (0.0, 120.5), “count”: 498}}

values

EventStore.values()

Iterate over data.

Yields: EventData in canonical order.