clockblocks.metric_phase.MetricPhaseTarget

class clockblocks.metric_phase.MetricPhaseTarget(phase_or_phases: float | Sequence[float], divisor: float = 1, relative: bool = False, units: str | DurationUnits | None = None, min_duration: float = 0)[source]

Bases: object

Class representing a particular point in a (beat or measure) cycle. Implements the ResolvableMoment protocol, so a MetricPhaseTarget can be passed anywhere a Moment can: wait / wait_until / fork / schedule_action.

Parameters:

  • phase_or_phases – Where we are in the cycle.

  • divisor – Length of the cycle (defaults to one beat, meaning that this specifies where we are in the beat)

  • relative – Whether or not the start of the cycle is measured relative to the current beat/time or to the start of the clock.

  • units – “beats”, “time”, or None — whether the phase and divisor are measured in the clock’s beats or in its time. Defaults to None, meaning “infer the axis from context”: when passed to a when argument, beats will be inferred as the natural musical default. When passed as an align_to argument the axis is inferred to be the one not specified by when. Pass an explicit “beats”/”time” only to force the axis. (If when and align_to share the same axis, this will raise an error.)

  • min_duration – minimum distance into the future (measured in units) before a match counts. resolve() returns the nearest matching beat/time that is at least this far ahead of now. Defaults to 0, meaning the very next match (which may be essentially now if you are already on the phase). Expresses musical concepts like “the next downbeat, but at least 4 beats from now.”

Methods

get_nearest_matching_beats(beat)

Get the nearest beats below and above the given beat with the correct metric phase

get_nearest_matching_times(time)

Get the nearest times below and above the given time with the correct metric phase

resolve(clock)

Resolve this phase target to an absolute Moment on clock: the nearest future moment in the clock (either a beat or time, depending on self.units) whose metric phase matches.
get_nearest_matching_beats(beat: float) → Tuple[float, float][source]

Get the nearest beats below and above the given beat with the correct metric phase

Parameters:

beat – the beat to search around

Returns:

tuple of nearest beat below, nearest beat above

get_nearest_matching_times(time: float) → Tuple[float, float][source]

Get the nearest times below and above the given time with the correct metric phase

Parameters:

time – the time to search around

Returns:

tuple of nearest time below, nearest time above

resolve(clock: Clock) → Moment[source]

Resolve this phase target to an absolute Moment on clock: the nearest future moment in the clock (either a beat or time, depending on self.units) whose metric phase matches. Satisfies the ResolvableMoment protocol. self.units of None resolves to BEATS in this context.