time

attribute__all__

= ['TICK_RESOLUTION', 'Division', 'DivisionLike', 'Position', 'PositionLike', 'TickResolver', 'TimeCalculator', 'tick_to_pos', 'pos_to_tick', 'push_beat_events', 'pop_beat_events', 'resolve_tick', 'push_tick_resolver', 'pop_tick_resolver', 'div_to_tick', 'tick_to_div', 'resolve_division']

Position

Division

_TimeSignature

TimeCalculator

func_require_int(name, value) -> int

paramnamestr

paramvalueobject

Returns

int

func_assert_unique_beat_bars(events) -> None

parameventslist[BeatEvent]

Returns

None

func_build_time_signatures(beat_events) -> list[_TimeSignature]

parambeat_eventsIterable[BeatEvent]

Returns

list[margrete_rpc.chart.time._TimeSignature]

func_measure_length(ts) -> int

paramts_TimeSignature

Returns

int

funcpush_beat_events(beat_events) -> contextvars.Token[Iterable[BeatEvent] | None]

Install beat_events as the active beat events for position resolution.

While active, :func:tick_to_pos and :func:pos_to_tick use these events when none are passed explicitly. :class:EditTransaction does this automatically for the duration of an edit.

parambeat_eventsIterable[BeatEvent]

The time-signature events to make active.

Returns

contextvars.Token

A token to pass to :func:pop_beat_events to restore the previous events.

funcpop_beat_events(token) -> None

Restore the beat events active before the matching :func:push_beat_events.

paramtokencontextvars.Token[Iterable[BeatEvent] | None]

Returns

None

func_resolve_beat_events(beat_events) -> Iterable[BeatEvent]

parambeat_eventsIterable[BeatEvent] | None

Returns

collections.abc.Iterable[margrete_rpc.chart.events.BeatEvent]

functick_to_pos(tick, *, beat_events=None) -> Position

Convert an absolute tick to a (bar, beat, offset) position.

paramtickint

Non-negative absolute tick from the chart start.

parambeat_eventsIterable[BeatEvent] | None

= None

Time-signature events to resolve against; falls back to the active events (see :func:push_beat_events), then to a default 4/4 signature.

Returns

margrete_rpc.chart.time.Position

The (bar, beat, offset) position of tick.

funcpos_to_tick(bar, beat=0, offset=0, *, beat_events=None) -> int

Convert a (bar, beat, offset) position to an absolute tick.

parambarint

Zero-based bar index.

parambeatint

= 0

Zero-based beat within the bar.

paramoffsetint

= 0

Tick offset within the beat.

parambeat_eventsIterable[BeatEvent] | None

= None

Time-signature events to resolve against; falls back to the active events (see :func:push_beat_events), then to a default 4/4 signature.

Returns

int

The absolute tick from the chart start.

funcpush_tick_resolver(resolver) -> contextvars.Token[TickResolver | None]

Install resolver as the active position->tick resolver.

While active, :func:resolve_tick uses it to turn :data:Position tuples into ticks. :class:EditTransaction installs a resolver bound to the chart's beat events.

paramresolverTickResolver

The position-to-tick function to make active.

Returns

contextvars.Token

A token to pass to :func:pop_tick_resolver to restore the previous resolver.

funcpop_tick_resolver(token) -> None

Restore the resolver active before the matching :func:push_tick_resolver.

paramtokencontextvars.Token[TickResolver | None]

Returns

None

funcresolve_tick(value) -> int

Coerce a tick-or-position argument to an absolute tick.

paramvalueint | PositionLike

An int tick (returned unchanged) or a :data:PositionLike tuple, resolved via the active tick resolver (see :func:push_tick_resolver) or, if none is set, a default 4/4 signature.

Returns

int

The absolute tick.

funcdiv_to_tick(numerator, denominator) -> int

Convert a numerator/denominator beat fraction to a tick count.

For example div_to_tick(1, 4) is the ticks in a quarter note and div_to_tick(1, 1) equals TICK_RESOLUTION.

paramnumeratorint

Fraction numerator (number of divisions).

paramdenominatorint

Fraction denominator (1..TICK_RESOLUTION).

Returns

int

The duration in ticks.

functick_to_div(ticks) -> Division

Convert a tick count to the reduced (numerator, denominator) beat fraction.

The inverse of :func:div_to_tick; e.g. one beat's worth of ticks yields (1, 1).

paramticksint

Non-negative duration in ticks.

Returns

margrete_rpc.chart.time.Division

The reduced (numerator, denominator) beat fraction.

funcresolve_division(value) -> int

Coerce a tick-count-or-fraction argument to an int tick count.

paramvalueint | DivisionLike

An int tick count (returned unchanged) or a :data:DivisionLike (numerator, denominator) beat fraction, converted via :func:div_to_tick.

Returns

int

The duration in ticks.