======================================================================
=== FILE: clockblocks/clockblocks.clock.Clock.txt
======================================================================
clockblocks.clock.Clock
***********************
class clockblocks.clock.Clock(name: str | None = None, parent: Clock | None = None, initial_rate: float | None = None, initial_tempo: float | None = None, initial_beat_length: float | None = None, clock_family_options: ClockFamilyOptions | None = None)
Bases: "object"
Recursively nestable clock. Clocks can fork child-clocks, which can
in turn fork their own child-clocks. A clock with no parent is the
*master*, and the whole family stays coordinated under it.
A master created on the main thread needs no cleanup. If you create
one on another thread, call "master.kill()" when you're done with
it so its background timing thread doesn't linger (or use
"run_as_server()", which manages that thread for you).
Parameters:
* **name** -- (optional) can be useful for keeping track in
confusing multi-threaded situations
* **parent** -- the parent clock for this clock; a value of None
indicates the master clock
* **initial_rate** -- starting rate of this clock (if set, don't
set initial tempo or beat length)
* **initial_tempo** -- starting tempo of this clock (if set,
don't set initial rate or beat length)
* **initial_beat_length** -- starting beat length of this clock
(if set, don't set initial tempo or rate)
* **clock_family_options** -- (master-only) a
"ClockFamilyOptions" bundling the family-level
timing/threading knobs ("timing_policy", "precise_timing",
"spin_guard_duration", "pool_size", "prewarm_pool"). The live
knobs are also adjustable afterwards via "timing_policy",
"precise_timing", and "spin_guard_duration". Passing it to a
forked child raises an error, since a child shares its
master's scheduler and pool.
Variables:
* **name** -- the name of this clock (string)
* **parent** -- the parent Clock to which this clock belongs
(Clock, or None if master clock)
* **tempo_history** -- TempoHistory describing how this clock
has changed or will change tempo
-[ Methods ]-
+------------+--------------------------------------------------------------------------------------------+
| "apply_bea | Drive this clock's beat_length from a function. |
| t_length_f | |
| unction"(f | |
| unction[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "apply_rat | Drive this clock's rate from a function. |
| e_function | |
| "(function | |
| [, ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "apply_tem | Append the given "TempoEnvelope" onto this clock's internal tempo envelope, starting from |
| po_envelop | the current beat. |
| e"(envelop | |
| e[, | |
| truncate, | |
| loop]) | |
+------------+--------------------------------------------------------------------------------------------+
| "apply_tem | Drive this clock's tempo (BPM) from a function. |
| po_functio | |
| n"(functio | |
| n[, ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "bring_up_ | Advance this clock's tempo_history to match where it currently is in scheduler time. |
| to_date"() | |
+------------+--------------------------------------------------------------------------------------------+
| "children" | Get all direct child clocks forked by this clock. |
| () | |
+------------+--------------------------------------------------------------------------------------------+
| "clock_to_ | Gets the time in the scheduler for a given beat or time in this clock, working recursively |
| scheduler_ | up the chain of clocks. |
| time"(beat | |
| _or_time[, | |
| units]) | |
+------------+--------------------------------------------------------------------------------------------+
| "descendan | Get all children, grandchildren, etc. |
| ts"() | |
+------------+--------------------------------------------------------------------------------------------+
| "extract_a | Extract this clock's absolute tempo curve — its tempo as observed in master (scheduler) |
| bsolute_te | time, with parent rate-changes folded in. |
| mpo_envelo | |
| pe"([...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "fast_forw | Turn indefinite fast-forwarding on or off. |
| ard"([on_o | |
| r_off]) | |
+------------+--------------------------------------------------------------------------------------------+
| "fast_forw | Fast-forward, skipping ahead instantaneously by *b* beats. |
| ard_in_bea | |
| ts"(b) | |
+------------+--------------------------------------------------------------------------------------------+
| "fast_forw | Fast-forward, skipping ahead instantaneously by *t* seconds. |
| ard_in_tim | |
| e"(t) | |
+------------+--------------------------------------------------------------------------------------------+
| "fast_forw | Fast-forward, skipping instantaneously up to beat *b* on this clock. |
| ard_to_bea | |
| t"(b) | |
+------------+--------------------------------------------------------------------------------------------+
| "fast_forw | Fast-forward, skipping instantaneously up to time *t* (in seconds) on this clock, then |
| ard_to_tim | resume real-time playback. |
| e"(t) | |
+------------+--------------------------------------------------------------------------------------------+
| "fork"(for | Spawns a child clock running *forked_function* as a coordinated parallel timeline. |
| ked_functi | |
| on[, args, | |
| kwargs, | |
| name, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "hold_sche | Context manager that: 1) ensures that the scheduler is not executing scheduled actions — |
| duler"() | waiting if one is in flight, then preventing others from starting; 2) rouses the scheduler |
| | and updates its committed time to the current projected time. |
+------------+--------------------------------------------------------------------------------------------+
| "inheritan | Get all parent, grandparent, etc. |
| ce"([inclu | |
| de_self]) | |
+------------+--------------------------------------------------------------------------------------------+
| "is_fast_f | Whether the clock is currently fast-forwarding. |
| orwarding" | |
| () | |
+------------+--------------------------------------------------------------------------------------------+
| "is_master | Check if this is the master clock |
| "() | |
+------------+--------------------------------------------------------------------------------------------+
| "iterate_a | Iterate through all related clocks to this clock. |
| ll_relativ | |
| es"([inclu | |
| de_self]) | |
+------------+--------------------------------------------------------------------------------------------+
| "iterate_d | Iterate through all children, grandchildren, etc. |
| escendants | |
| "([include | |
| _self]) | |
+------------+--------------------------------------------------------------------------------------------+
| "iterate_i | Iterate through parent, grandparent, etc. |
| nheritance | |
| "([include | |
| _self]) | |
+------------+--------------------------------------------------------------------------------------------+
| "kill"() | End this clock (and the corresponding forked function if not master) and cascade to all |
| | descendant clocks. |
+------------+--------------------------------------------------------------------------------------------+
| "print_fam | Print a hierarchical representation of this clock's family tree. |
| ily_tree"( | |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "print_sta | Print this clock's "status()" snapshot. |
| tus"([verb | |
| ose]) | |
+------------+--------------------------------------------------------------------------------------------+
| "projected | A wall-clock-interpolated estimate of "beat". |
| _beat"() | |
+------------+--------------------------------------------------------------------------------------------+
| "projected | A wall-clock-interpolated estimate of "time", advancing smoothly between events rather |
| _time"() | than holding still between them. |
+------------+--------------------------------------------------------------------------------------------+
| "run_as_se | Run this (master) clock on a background daemon thread so the calling thread stays free — |
| rver"() | the approach for driving clockblocks from an interactive REPL: "c = |
| | Clock().run_as_server()". |
+------------+--------------------------------------------------------------------------------------------+
| "schedule_ | The lightweight alternative to fork() for immediately returning functions. |
| action"(ac | |
| tion, | |
| when[, | |
| args, | |
| kwargs]) | |
+------------+--------------------------------------------------------------------------------------------+
| "scheduler | Gets beats or time in this clock for a given time in the scheduler. |
| _to_clock_ | |
| time"(sche | |
| duler_time | |
| [, ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_beat_ | Smoothly change this clock's beat length (seconds per beat) to "beat_length_target", |
| length_tar | arriving at the moment given by "when". |
| get"(beat_ | |
| length_tar | |
| get, when) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_beat_ | Smoothly change this clock's beat length (seconds per beat) through a series of targets, |
| length_tar | building a multi-segment tempo curve in one call — the multi-segment form of |
| gets"(beat | "set_beat_length_target()". |
| _length_ta | |
| rgets, | |
| ...) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_rate_ | Smoothly change this clock's rate (beats per second) to "rate_target", arriving at "when". |
| target"(ra | |
| te_target, | |
| when[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_rate_ | Smoothly change this clock's rate (beats per second; the reciprocal of beat length, so a |
| targets"(r | higher rate is a faster tempo) through a series of targets — the multi-segment form of |
| ate_target | "set_rate_target()". |
| s, whens[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_tempo | Smoothly change this clock's tempo to "tempo_target", arriving at "when". |
| _target"(t | |
| empo_targe | |
| t, when[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_tempo | Smoothly change this clock's tempo (beats per minute) through a series of targets — the |
| _targets"( | multi-segment form of "set_tempo_target()", and usually the most natural of the three |
| tempo_targ | equivalent plural setters. |
| ets, | |
| whens[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "status"([ | A snapshot of this clock's name and position, alongside the scheduler's elapsed wall time |
| verbose]) | and how far behind schedule it is currently running. |
+------------+--------------------------------------------------------------------------------------------+
| "stop_temp | Stop following any function or looping envelope previously applied to this clock's tempo. |
| o_loop_or_ | |
| function"( | |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "terminate | Kill this clock's children and their descendants in turn, returning once they have |
| _forked_ch | finished unwinding. |
| ildren"() | |
+------------+--------------------------------------------------------------------------------------------+
| "use_absol | Shorthand for "timing_policy = 0.0" (always catch up to absolute schedule). |
| ute_timing | |
| _policy"() | |
+------------+--------------------------------------------------------------------------------------------+
| "use_mixed | Shorthand for "timing_policy = absolute_relative_mix" (a blend between 0=absolute and |
| _timing_po | 1=relative). |
| licy"(abso | |
| lute_relat | |
| ive_mix) | |
+------------+--------------------------------------------------------------------------------------------+
| "use_relat | Shorthand for "timing_policy = 1.0" (always wait the full requested delay). |
| ive_timing | |
| _policy"() | |
+------------+--------------------------------------------------------------------------------------------+
| "wait"(dur | Block this clock for *duration* beats (or seconds, if units="time") from now, yielding to |
| ation[, | the scheduler. |
| units]) | |
+------------+--------------------------------------------------------------------------------------------+
| "wait_for_ | Block this clock's own thread until all of its child clocks have finished, yielding to the |
| children_t | scheduler so they can run, then return as soon as the last child ends. |
| o_finish"( | |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "wait_for_ | Block this clock's own thread until *clock* has finished, yielding to the scheduler so it |
| clock_to_f | (and everything else) keeps running. |
| inish"(clo | |
| ck) | |
+------------+--------------------------------------------------------------------------------------------+
| "wait_fore | Block this clock's own thread indefinitely, yielding to the scheduler so child clocks keep |
| ver"() | running. |
+------------+--------------------------------------------------------------------------------------------+
| "wait_unti | Block this clock until the beat (or time, if units="time") indicated by *when* — a |
| l"(when[, | convenience for absolute targets given as a bare number (equivalent to |
| units]) | wait(Moment.at_beat(when)), or Moment.at_time for units="time"). |
+------------+--------------------------------------------------------------------------------------------+
-[ Attributes ]-
+------------+--------------------------------------------------------------------------------------------+
| "absolute_ | Beat length in true seconds, with all parent rates folded in. |
| beat_lengt | |
| h" | |
+------------+--------------------------------------------------------------------------------------------+
| "absolute_ | Rate of this clock in beats / (true) second, with all parent rates folded in. |
| rate" | |
+------------+--------------------------------------------------------------------------------------------+
| "absolute_ | Tempo (BPM) in true minutes, with all parent rates folded in. |
| tempo" | |
+------------+--------------------------------------------------------------------------------------------+
| "alive" | True if this clock is currently running (PENDING and DEAD both return False). |
+------------+--------------------------------------------------------------------------------------------+
| "beat" | How many beats have passed since this clock was created. |
+------------+--------------------------------------------------------------------------------------------+
| "beat_leng | The length of a beat in this clock in seconds. |
| th" | |
+------------+--------------------------------------------------------------------------------------------+
| "master" | The master clock under which this clock operates (possibly itself) |
+------------+--------------------------------------------------------------------------------------------+
| "precise_t | Whether to use a busy wait in the final moments leading up to a scheduled event. |
| iming" | |
+------------+--------------------------------------------------------------------------------------------+
| "rate" | The rate of this clock in beats / second. |
+------------+--------------------------------------------------------------------------------------------+
| "spin_guar | Width (seconds) of the busy-wait guard band used when "precise_timing" is on. |
| d_duration | |
| " | |
+------------+--------------------------------------------------------------------------------------------+
| "tempo" | The rate of this clock in beats / minute Note that beat_length, tempo and rate are |
| | interconnected properties, and that by setting one of them the other two are automatically |
| | set in response according to the relationship: beat_length = 1/rate = 60/tempo. |
+------------+--------------------------------------------------------------------------------------------+
| "time" | How much time has passed since this clock was created. |
+------------+--------------------------------------------------------------------------------------------+
| "timing_po | How the family trades off relative vs. absolute timing, as a float from 0 to 1. |
| licy" | |
+------------+--------------------------------------------------------------------------------------------+
property master: Clock
The master clock under which this clock operates (possibly
itself)
is_master() -> bool
Check if this is the master clock
Returns:
True if this is the master clock, False otherwise
hold_scheduler()
Context manager that: 1) ensures that the scheduler is not
executing scheduled actions — waiting if one is in flight, then
preventing others from starting; 2) rouses the scheduler and
updates its committed time to the current projected time. Code
under this context manager therefore acts like an immediately
scheduled action, holding exclusive access to an up-to-date
scheduler.
Note that, when used from within the clock system, this context
manager is a no-op, since the current thread already holds
exclusive access to an up-to-date scheduler. In fact, invoking
*clock.scheduler.held()* in that context would cause deadlock,
which is why this method exists as the main entry point.
children() -> Sequence[Clock]
Get all direct child clocks forked by this clock.
Returns:
tuple of all child clocks of this clock
iterate_inheritance(include_self: bool = True) -> Iterator[Clock]
Iterate through parent, grandparent, etc. of this clock up until
the master clock
Parameters:
**include_self** -- whether or not to include this clock in
the iterator or start with the parent
Returns:
iterator going up the clock family tree up to the master
clock
inheritance(include_self: bool = True) -> Sequence[Clock]
Get all parent, grandparent, etc. of this clock up until the
master clock
Parameters:
**include_self** -- whether or not to include this clock in
the iterator or start with the parent
Returns:
tuple containing the clock's inheritance
iterate_all_relatives(include_self: bool = False) -> Iterator[Clock]
Iterate through all related clocks to this clock.
Parameters:
**include_self** -- whether or not to include this clock in
the iterator
Returns:
iterator going through all clocks in the family tree,
starting with the master
iterate_descendants(include_self: bool = False) -> Iterator[Clock]
Iterate through all children, grandchildren, etc. of this clock
Parameters:
**include_self** -- whether or not to include this clock in
the iterator
Returns:
iterator going through all descendants
descendants() -> Sequence[Clock]
Get all children, grandchildren, etc. of this clock
Returns:
tuple of all descendants
print_family_tree() -> None
Print a hierarchical representation of this clock's family tree.
property time: float
How much time has passed since this clock was created. Either in
seconds, if this is the master clock, or in beats in the parent
clock, if this clock was the result of a call to fork. Note that
this is quantized to the scheduler's event stream; for a live
estimate when outside the clock system use "projected_time()".
(Read-only property. Before clockblocks 1.1 this was a method;
the "clock.time()" spelling still works, with a
DeprecationWarning.)
property beat: float
How many beats have passed since this clock was created. Note
that this is quantized to the scheduler's event stream; for a
live estimate when outside the clock system use
"projected_time()".
(Read-only property. Before clockblocks 1.1 this was a method;
the "clock.beat()" spelling still works, with a
DeprecationWarning.)
projected_time() -> float
A wall-clock-interpolated estimate of "time", advancing smoothly
between events rather than holding still between them. For
readers outside the clock system; see the section comment above.
(A method rather than a property, because it is a live sample:
every call returns a different value.)
This is an estimate, and it can step backward — see
"projected_time()".
Returns:
the estimated elapsed time, in the same units as "time".
projected_beat() -> float
A wall-clock-interpolated estimate of "beat". See
"projected_time()".
Returns:
the estimated elapsed beats.
status(verbose: bool = False) -> str
A snapshot of this clock's name and position, alongside the
scheduler's elapsed wall time and how far behind schedule it is
currently running.
print_status(verbose: bool = False) -> None
Print this clock's "status()" snapshot.
property beat_length: float
The length of a beat in this clock in seconds. Note that
beat_length, tempo and rate are interconnected properties, and
that by setting one of them the other two are automatically set
in response according to the relationship: beat_length = 1/rate
= 60/tempo. Also, note that "seconds" refers to actual seconds
only in the master clock; otherwise it refers to beats in the
parent clock.
property rate: float
The rate of this clock in beats / second. Note that beat_length,
tempo and rate are interconnected properties, and that by
setting one of them the other two are automatically set in
response according to the relationship: beat_length = 1/rate =
60/tempo. Also, note that "seconds" refers to actual seconds
only in the master clock; otherwise it refers to beats in the
parent clock.
property tempo: float
The rate of this clock in beats / minute Note that beat_length,
tempo and rate are interconnected properties, and that by
setting one of them the other two are automatically set in
response according to the relationship: beat_length = 1/rate =
60/tempo. Also, note that "seconds" refers to actual seconds
only in the master clock; otherwise it refers to beats in the
parent clock.
property absolute_rate: float
Rate of this clock in beats / (true) second, with all parent
rates folded in.
(Read-only property. Before clockblocks 1.1 this was a method;
the "clock.absolute_rate()" spelling still works, with a
DeprecationWarning.)
property absolute_tempo: float
Tempo (BPM) in true minutes, with all parent rates folded in.
(Read-only property; the pre-1.1 "clock.absolute_tempo()"
spelling still works, with a DeprecationWarning.)
property absolute_beat_length: float
Beat length in true seconds, with all parent rates folded in.
(Read-only property; the pre-1.1 "clock.absolute_beat_length()"
spelling still works, with a DeprecationWarning.)
set_beat_length_target(beat_length_target: float, when: ResolvableMoment, curve_shape: float = None, truncate: bool = True, align_to: ResolvableMoment = None) -> None
Smoothly change this clock's beat length (seconds per beat) to
"beat_length_target", arriving at the moment given by "when".
This is the underlying representation behind
"set_tempo_target()" and "set_rate_target()"; a longer beat
length means a slower tempo.
Parameters:
* **beat_length_target** -- the beat length to arrive at, in
seconds per beat.
* **when** -- when the target should be reached, as a
"Moment" (e.g. "Moment.after_beats(4)",
"Moment.at_time(10)") or a "MetricPhaseTarget" (the next
point matching a particular phase within the beat cycle).
"after_*" moments count from the clock's *current*
position. A plain number is rejected; wrap it in a Moment
to clarify beat/time and relative/absolute.
* **curve_shape** -- the bend of the transition. "0" (the
default) is a straight line; "> 0" keeps the old tempo
longer and changes late; "< 0" changes early then eases in.
When "align_to" solves for the curvature (see below) this
acts only as a starting hint, and with a fixed "align_to",
it is ignored entirely (and a warning is issued if set).
* **truncate** -- if "True" (the default), any tempo curve
already scheduled past the current beat is discarded first,
so the change starts from where the clock is right now. If
"False", this target is appended after whatever is already
scheduled.
* **align_to** -- optional. If *when* is an arrival beat,
this specifies the desired arrival time. If *when* is an
arrival time, this specifies the desired arrival beat. A
MetricPhaseTarget can be given instead of a singular
time/beat, to express when we should arrive within a
time/beat cycle. Note that the coordination of beat and
time is done via mutating the curve shape, so an explicit
curve shape is only a hint (ignored completely if align_to
is a fixed point rather than a metric phase target).
Raises:
**ValueError** -- if "when"/"align_to" share an axis, or if
no curvature can reach the requested "align_to" (in which
case the tempo curve is left unchanged).
set_rate_target(rate_target: float, when: ResolvableMoment, curve_shape: float = None, truncate: bool = True, align_to: ResolvableMoment = None) -> None
Smoothly change this clock's rate (beats per second) to
"rate_target", arriving at "when". Rate is the reciprocal of
beat length: a higher rate is a faster tempo.
Parameters:
* **rate_target** -- the rate to arrive at, in beats per
second.
* **when** -- when the target is reached. See
"set_beat_length_target()".
* **curve_shape** -- the bend of the transition. See
"set_beat_length_target()".
* **truncate** -- whether to discard already-scheduled tempo
changes first. See "set_beat_length_target()".
* **align_to** -- optional; solve the curvature to land the
free axis on a phase or coordinate. See
"set_beat_length_target()".
Raises:
**ValueError** -- see "set_beat_length_target()".
set_tempo_target(tempo_target: float, when: ResolvableMoment, curve_shape: float = None, truncate: bool = True, align_to: ResolvableMoment = None) -> None
Smoothly change this clock's tempo to "tempo_target", arriving
at "when". Tempo is measured in beats per minute; this is
usually the most natural of the three equivalent ways to set a
target (see also "set_rate_target()" and
"set_beat_length_target()").
Parameters:
* **tempo_target** -- the tempo to arrive at, in beats per
minute (quarter-notes per minute by convention).
* **when** -- when the target is reached. See
"set_beat_length_target()".
* **curve_shape** -- the bend of the transition. See
"set_beat_length_target()".
* **truncate** -- whether to discard already-scheduled tempo
changes first. See "set_beat_length_target()".
* **align_to** -- optional; solve the curvature to land the
free axis on a phase or coordinate. See
"set_beat_length_target()".
Raises:
**ValueError** -- see "set_beat_length_target()".
set_beat_length_targets(beat_length_targets: Sequence[float], whens: Sequence[ResolvableMoment], curve_shapes: Sequence[float] = None, truncate: bool = True, align_to: ResolvableMoment | Sequence[ResolvableMoment | None] = None) -> None
Smoothly change this clock's beat length (seconds per beat)
through a series of targets, building a multi-segment tempo
curve in one call — the multi-segment form of
"set_beat_length_target()". This is non-looping; to apply a
looping tempo shape, build a "TempoEnvelope" and use
"apply_tempo_envelope()".
Parameters:
* **beat_length_targets** -- the beat lengths (seconds per
beat) to arrive at, one per segment.
* **whens** -- when each target is reached (same length as
"beat_length_targets"), each a "Moment" or
"MetricPhaseTarget". Note that every *when* is resolved
against the clock's *current* position, so an "after_*"
moment counts from now, not from the previous segment's.
Beats- and time-axis moments may be freely mixed across the
list, so long as the whens come out in strictly increasing
clock-time.
* **curve_shapes** -- optional per-segment bends (same length
as "beat_length_targets"), each as in
"set_beat_length_target()". "None" for the whole argument
(the default), or a per-element "None", means linear ("0")
for that segment.
* **truncate** -- if "True" (the default), any tempo curve
already scheduled past the current beat is discarded first,
so the run starts from where the clock is now; if "False"
the run is appended after whatever is already scheduled.
* **align_to** --
optional curvature-solved alignment, extending
"set_beat_length_target()"'s "align_to" to runs of
segments. Either:
* a single "Moment"/"MetricPhaseTarget" — align the *whole*
call as one run, landing its end on the target; or
* a per-segment list/tuple (same length as
"beat_length_targets") of "None"/targets — each
non-"None" entry closes a *run* (all segments since the
previous alignment, or the start) and bends them
collectively so the run lands on that target.
A group-aligned run of more than one segment must have its
"whens" on a single axis (all beats or all time), with the
alignment target on the opposite (free) axis.
Raises:
**ValueError** -- if "whens"/"curve_shapes"/"align_to"
lengths are inconsistent with "beat_length_targets"; if the
"whens" do not come out strictly increasing in clock-time
(the error names the offending index); if a multi-segment
aligned run mixes beat- and time-axis "whens"; or if an
alignment target is unreachable by curvature adjustment. On
any failure the tempo curve is left unchanged.
set_rate_targets(rate_targets: Sequence[float], whens: Sequence[ResolvableMoment], curve_shapes: Sequence[float] = None, truncate: bool = True, align_to: ResolvableMoment | Sequence[ResolvableMoment | None] = None) -> None
Smoothly change this clock's rate (beats per second; the
reciprocal of beat length, so a higher rate is a faster tempo)
through a series of targets — the multi-segment form of
"set_rate_target()".
Parameters:
* **rate_targets** -- the rates (beats per second) to arrive
at, one per segment.
* **whens** -- when each target is reached. See
"set_beat_length_targets()".
* **curve_shapes** -- optional per-segment bends. See
"set_beat_length_targets()".
* **truncate** -- whether to discard already-scheduled tempo
changes first. See "set_beat_length_targets()".
* **align_to** -- optional curvature-solved alignment of
segment runs. See "set_beat_length_targets()".
Raises:
**ValueError** -- see "set_beat_length_targets()".
set_tempo_targets(tempo_targets: Sequence[float], whens: Sequence[ResolvableMoment], curve_shapes: Sequence[float] = None, truncate: bool = True, align_to: ResolvableMoment | Sequence[ResolvableMoment | None] = None) -> None
Smoothly change this clock's tempo (beats per minute) through a
series of targets — the multi-segment form of
"set_tempo_target()", and usually the most natural of the three
equivalent plural setters.
Parameters:
* **tempo_targets** -- the tempos (beats per minute) to
arrive at, one per segment.
* **whens** -- when each target is reached. See
"set_beat_length_targets()".
* **curve_shapes** -- optional per-segment bends. See
"set_beat_length_targets()".
* **truncate** -- whether to discard already-scheduled tempo
changes first. See "set_beat_length_targets()".
* **align_to** -- optional curvature-solved alignment of
segment runs. See "set_beat_length_targets()".
Raises:
**ValueError** -- see "set_beat_length_targets()".
apply_beat_length_function(function: Callable, domain_start: float = 0, domain_end: float = None, duration_units: str = 'beats', truncate: bool = True, loop: bool = False, extension_increment: float = 2.0, **kwargs) -> None
Drive this clock's beat_length from a function. See
"apply_function()" for the full parameter list (passed via
"**kwargs").
apply_rate_function(function: Callable, domain_start: float = 0, domain_end: float = None, duration_units: str = 'beats', truncate: bool = True, loop: bool = False, extension_increment: float = 2.0, **kwargs) -> None
Drive this clock's rate from a function.
apply_tempo_function(function: Callable, domain_start: float = 0, domain_end: float = None, duration_units: str = 'beats', truncate: bool = True, loop: bool = False, extension_increment: float = 2.0, **kwargs) -> None
Drive this clock's tempo (BPM) from a function.
apply_tempo_envelope(envelope: TempoEnvelope, truncate: bool = True, loop: bool = False) -> None
Append the given "TempoEnvelope" onto this clock's internal
tempo envelope, starting from the current beat. With *loop=True*
the envelope repeats indefinitely until
"stop_tempo_loop_or_function()". *truncate* first discards any
tempo curve already projected past the current beat so the
envelope begins cleanly from now.
stop_tempo_loop_or_function() -> None
Stop following any function or looping envelope previously
applied to this clock's tempo.
clock_to_scheduler_time(beat_or_time, units='beats')
Gets the time in the scheduler for a given beat or time in this
clock, working recursively up the chain of clocks.
Parameters:
* **beat_or_time** -- the beat or time of interest in this
clock
* **units** -- one of ("beats", "time"), determining the
units for the first argument
Returns:
how much time should pass in the scheduler
scheduler_to_clock_time(scheduler_time, desired_units='beats')
Gets beats or time in this clock for a given time in the
scheduler.
Parameters:
* **scheduler_time** -- the time of interest in the scheduler
* **desired_units** -- one of ("beats", "time"), whether
we're looking for beats or time in this clock
Returns:
how much time should pass in the scheduler
bring_up_to_date()
Advance this clock's tempo_history to match where it currently
is in scheduler time.
Called before mutating tempo from a foreign thread: if we don't,
the tempo setter's *truncate()* cuts at the last *committed*
beat (whatever the clock last woke at), causing the new tempo to
retroactively reshape the segment the clock is currently napping
through. From the owning thread this is a no-op since committed
== current.
extract_absolute_tempo_envelope(start_beat: float = 0, end_beat: float | None = None, step_size: float = 0.1, tolerance: float = 0.005) -> TempoEnvelope
Extract this clock's absolute tempo curve — its tempo as
observed in master (scheduler) time, with parent rate-changes
folded in. Used when building a Score from this clock's
perspective.
Extracts over "[start_beat, end_beat]", where *end_beat*
defaults to this clock's current beat. When all ancestors are
pure, flat tempos, they simply scale this clock's tempo curve
directly. When the ancestors are changing, there is no exact
solution, so we sample every *step_size* beats. Sampling is
aligned to the tempo break points of every clock in the chain,
so an instantaneous tempo change stays sharp rather than
smearing into a short accelerando or ritardando.
wait(duration: float | ResolvableMoment, units: str = 'beats') -> None
Block this clock for *duration* beats (or seconds, if
units="time") from now, yielding to the scheduler. *duration*
may also be any ResolvableMoment (a Moment or
MetricPhaseTarget), in which case it is resolved directly and
*units* is ignored — e.g. wait(Moment.at_beat(8)) or
wait(MetricPhaseTarget(0, 4)). wait_until() is just a
convenience for absolute targets given as a bare number; passing
an absolute Moment to wait() does the same thing.
wait_until(when: float | ResolvableMoment, units: str = 'beats') -> None
Block this clock until the beat (or time, if units="time")
indicated by *when* — a convenience for absolute targets given
as a bare number (equivalent to wait(Moment.at_beat(when)), or
Moment.at_time for units="time"). *when* may also be any
ResolvableMoment, in which case the units are ignored and
behavior is identical to wait(). If *when* is in the past,
returns essentially immediately.
fork(forked_function: Callable, args: Sequence = (), kwargs: dict = None, name: str = None, initial_rate: float = None, initial_tempo: float = None, initial_beat_length: float = None, when: ResolvableMoment | None = None, done_callback: Callable[[], None] = None)
Spawns a child clock running *forked_function* as a coordinated
parallel timeline.
The child runs on its own thread but stays synchronized under
this clock's master scheduler — "parallel" here means parallel
musical time (like a separate voice or layer), not simultaneous
CPU execution; the scheduler runs one clock's code at a time.
Parameters:
* **forked_function** -- the function to be run on the new
child clock
* **args** -- positional arguments to be passed to the forked
function. (Unlike legacy clockblocks, clockblocks does
*not* inject the child clock as an extra first argument
when the signature is one short — call "current_clock()"
from inside the forked function if you need a reference to
it.)
* **kwargs** -- keyword arguments to be passed to the forked
function
* **name** -- name to be given to the spawned child clock
* **initial_rate** -- starting rate of this clock (if set,
don't set initial tempo or beat length)
* **initial_tempo** -- starting tempo of this clock (if set,
don't set initial rate or beat length)
* **initial_beat_length** -- starting beat length of this
clock (if set, don't set initial tempo or rate)
* **when** -- when the forked function should begin, as a
"ResolvableMoment". None (default) starts it immediately.
Otherwise pass an explicit Moment — "at_beat()" (or
"at_time()") for an absolute point, or "after_beats()" (or
"after_time()") for an offset from now. Unlike wait and
wait_until, a bare number is rejected here, since it's not
clear whether it would be relative or absolute. Also
possible is a "MetricPhaseTarget" which starts it at the
next matching point in a cycle.
* **done_callback** -- a callback function to be invoked when
the clock has terminated
Returns:
the spawned child clock
schedule_action(action: Callable, when: ResolvableMoment, args: Sequence = (), kwargs: dict = None) -> None
The lightweight alternative to fork() for immediately returning
functions. Schedules *action* to run once at *when*, as a leaf
event on the scheduler thread — without spawning a child clock.
For functions that don't wait, this is much more performant:
there is no thread creation, no scheduler/clock handoff; just a
callable fired at the right musical time.
For work that needs to wait, fork() a child clock instead. The
function scheduled here will not have an active clock to wait
on, and will hold up the entire scheduler if it sleeps.
Parameters:
* **action** -- the callable to run (exceptions are caught
and logged by the scheduler)
* **when** -- when to run it, as a "ResolvableMoment" — same
convention as fork(): an explicit Moment
(Moment.at_beat/at_time for an absolute point,
Moment.after_beats/ after_time for an offset from now) or a
MetricPhaseTarget. Unlike wait and wait_until, a bare
number is rejected here, since it's not clear whether it
would be relative or absolute.
* **args** -- positional arguments to pass to action
* **kwargs** -- keyword arguments to pass to action
wait_forever() -> None
Block this clock's own thread indefinitely, yielding to the
scheduler so child clocks keep running. Typically called once a
clock has forked its work and has nothing left to do itself
(e.g. the master clock keeping the main thread alive).
This only ever unblocks via "kill()", at which point it raises
"ClockKilledError". For a forked clock, this is caught by the
fork wrapper and it cleanly unwinds. For a master clock it would
need to be caught. A built-in way to do this is by using the
clock as a context manager, which does exception handling and
teardown for you. ("run_as_server()" also absorbs the exception
automatically within the spawned thread).
That said, typically this is used at end of script and killed
via ctrl-c/process exit, so no explicit catching of this
exception is necessary.
wait_for_children_to_finish() -> None
Block this clock's own thread until all of its child clocks have
finished, yielding to the scheduler so they can run, then return
as soon as the last child ends.
If this clock is itself killed while waiting, raises
"ClockKilledError" rather than returning — so a normal return
always means the children genuinely finished.
wait_for_clock_to_finish(clock: Clock) -> None
Block this clock's own thread until *clock* has finished,
yielding to the scheduler so it (and everything else) keeps
running. The counterpart to "wait_for_children_to_finish()" for
a specific clock rather than one's own children — *clock* may be
any other clock in the same family (a sibling, a descendant, an
unrelated fork), so long as it shares this clock's scheduler.
Returns as soon as *clock* finishes, whether it ended on its own
or was killed. If *clock* has already finished, returns
immediately. If this clock is itself killed while waiting,
raises "ClockKilledError" rather than returning.
Parameters:
**clock** -- the clock to wait on. Must belong to the same
family (raises ValueError otherwise), and must not be this
clock itself (which would wait forever).
terminate_forked_children() -> None
Kill this clock's children and their descendants in turn,
returning once they have finished unwinding. At the natural end
of a forked clock that has (or might have) still-active
children, either this or "wait_for_children_to_finish()" should
be called, making explicit what to do with those forked
children. (The default is termination with a warning, in case
it's not what the user wants.)
run_as_server() -> Clock
Run this (master) clock on a background daemon thread so the
calling thread stays free — the approach for driving clockblocks
from an interactive REPL: "c = Clock().run_as_server()". The
background thread becomes the clock's owning thread and waits
forever; the calling thread relinquishes ownership (its
*current_clock()* becomes None), so further work must be forked
on the returned clock object directly ("c.fork(...)"), not via
the context-inferring helpers such as "fork()" and "wait()".
Returns self. Only valid on the master clock — raises
NotMasterClockError on a child.
property alive: bool
True if this clock is currently running (PENDING and DEAD both
return False).
fast_forward(on_or_off: bool = True) -> None
Turn indefinite fast-forwarding on or off. While on, all waiting
is instantaneous. (Only valid on the master clock.)
Parameters:
**on_or_off** -- True to start fast-forwarding, False to
stop.
fast_forward_to_time(t: float) -> None
Fast-forward, skipping instantaneously up to time *t* (in
seconds) on this clock, then resume real-time playback. (Only
valid on the master clock.)
Parameters:
**t** -- time to fast-forward to
fast_forward_in_time(t: float) -> None
Fast-forward, skipping ahead instantaneously by *t* seconds.
(Only valid on the master clock.)
Parameters:
**t** -- number of seconds to fast-forward by
fast_forward_to_beat(b: float) -> None
Fast-forward, skipping instantaneously up to beat *b* on this
clock. (Only valid on the master clock.)
Parameters:
**b** -- beat to fast-forward to
fast_forward_in_beats(b: float) -> None
Fast-forward, skipping ahead instantaneously by *b* beats. (Only
valid on the master clock.)
Parameters:
**b** -- number of beats to fast-forward by
is_fast_forwarding() -> bool
Whether the clock is currently fast-forwarding. Since fast-
forwarding is a scheduler-wide state, this is true for every
clock in the family whenever it's true for any of them.
property timing_policy: float
How the family trades off relative vs. absolute timing, as a
float from 0 to 1.
At 1.0 (relative) each wait is kept as faithful as possible to
its requested duration, timed from when the previous event fired
(callback runtime does not count against the wait). This can
still let the clock fall behind real time: if a wait overruns
(e.g. through a callback that runs longer than its own wait or
the OS waking late) that lateness is never made up. At 0.0
(absolute) the clock instead stays faithful to the time elapsed
since it began — a wait that ran long is followed by shorter
waits to catch up, at the cost of some relative-timing accuracy.
A value in between clamps the catch-up: the clock attempts to
stay on the absolute schedule but can only compress a wait to
*wait_dur * timing_policy* (or stretch it to *wait_dur /
timing_policy* if trying to compensate for being ahead).
(Forwards to the scheduler, settable only on the master clock)
use_absolute_timing_policy() -> None
Shorthand for "timing_policy = 0.0" (always catch up to absolute
schedule).
use_relative_timing_policy() -> None
Shorthand for "timing_policy = 1.0" (always wait the full
requested delay).
use_mixed_timing_policy(absolute_relative_mix: float) -> None
Shorthand for "timing_policy = absolute_relative_mix" (a blend
between 0=absolute and 1=relative).
property precise_timing: bool
Whether to use a busy wait in the final moments leading up to a
scheduled event. The busy wait fully occupies a CPU core and
lasts at most "spin_guard_duration" seconds per event. (Forwards
to the scheduler, settable only on the master clock)
property spin_guard_duration: float
Width (seconds) of the busy-wait guard band used when
"precise_timing" is on. (Forwards to the scheduler, settable
only on the master clock)
kill() -> None
End this clock (and the corresponding forked function if not
master) and cascade to all descendant clocks.
Pending scheduled work for this clock and its descendants is
canceled and the clocks are marked dead. A clock currently
blocked in "wait()" raises "ClockKilledError"; any later
"wait()" or "fork()" made through a reference to a dead clock
raises "DeadClockError".
Killing the master also tears down the family's scheduler, and
releases its owning thread: that thread's "current_clock()"
becomes "None", so the module-level helpers ("wait()", "fork()",
"get_beat()", ...) raise "NoActiveClockError" there rather than
reporting a dead clock.
Returns once the killed clocks have finished unwinding to ensure
synchronicity. Emits a warning if this takes more than a few
seconds.
Safe to call from any thread, and killing an already-dead clock
is a no-op.
(See the "Clock termination / lifecycle paths" note near the top
of this module for how the five termination paths work
internally.)
======================================================================
=== FILE: clockblocks/clockblocks.clock.ClockFamilyOptions.txt
======================================================================
clockblocks.clock.ClockFamilyOptions
************************************
class clockblocks.clock.ClockFamilyOptions(timing_policy: float = 0.98, precise_timing: bool = False, spin_guard_duration: float = 0.0005, pool_size: int = 200, prewarm_pool: int = 10, time_backend: TimingBackend | None = None)
Bases: "object"
Fine-tuning options for a clock family, passed to a master "Clock"
on construction. A master and all its descendants share one
scheduler and one thread pool; these knobs configure both.
The live knobs ("timing_policy", "precise_timing",
"spin_guard_duration") can be changed after construction via the
matching "Clock" properties; the thread pool knobs are
construction-only because the thread pool is built once.
Parameters:
* **timing_policy** -- 0.0 = absolute timing (measure from clock
start and catch up as much as possible), 1.0 = relative timing
(wait the full delay each time, even when behind), floats in
between clamp how far a wait may be compressed/stretched from
its nominal length to stay on the absolute schedule. Default
value is 0.98 (near-relative: a wait may shave up to 2% of its
length per event to catch up).
* **precise_timing** -- When true, use a busy-wait in the
immediate run-up to a scheduled action to arrive as precisely
as possible. (OS wait is by nature jittery.) Costs one core
for at most "spin_guard_duration" seconds per event. Helps
under any "timing_policy" by tightening whatever that policy
optimizes.
* **spin_guard_duration** -- Width (seconds) of the busy-spin
guard band used when "precise_timing" is on. Default 500µs.
* **pool_size** -- Max worker threads in the family's shared
ThreadPoolExecutor, used for every call to "fork". Workers are
created lazily up to this cap; past it, a forked clock falls
back to a plain thread and warns that the pool has run out of
threads.
* **prewarm_pool** -- How many pool workers to spin up eagerly
at construction, front-loading the (sub-millisecond) thread-
creation cost of the first that-many forks. Clamped to
"pool_size"; 0 disables, leaving an idle clock with no threads
at all.
-[ Attributes ]-
+------------+--------------------------------------------------------------------------------------------+
| "pool_size | |
| " | |
+------------+--------------------------------------------------------------------------------------------+
| "precise_t | |
| iming" | |
+------------+--------------------------------------------------------------------------------------------+
| "prewarm_p | |
| ool" | |
+------------+--------------------------------------------------------------------------------------------+
| "spin_guar | |
| d_duration | |
| " | |
+------------+--------------------------------------------------------------------------------------------+
| "time_back | |
| end" | |
+------------+--------------------------------------------------------------------------------------------+
| "timing_po | |
| licy" | |
+------------+--------------------------------------------------------------------------------------------+
timing_policy: float = 0.98
precise_timing: bool = False
spin_guard_duration: float = 0.0005
pool_size: int = 200
prewarm_pool: int = 10
time_backend: TimingBackend | None = None
======================================================================
=== FILE: clockblocks/clockblocks.clock.ClockState.txt
======================================================================
clockblocks.clock.ClockState
****************************
class clockblocks.clock.ClockState(*values)
Bases: "Enum"
Where a clock sits in its lifecycle. A forked clock starts out
PENDING, becomes ALIVE once its function begins running, and ends
up DEAD once that function returns or the clock is killed.
-[ Attributes ]-
+------------+--------------------------------------------------------------------------------------------+
| "PENDING" | |
+------------+--------------------------------------------------------------------------------------------+
| "ALIVE" | |
+------------+--------------------------------------------------------------------------------------------+
| "DEAD" | |
+------------+--------------------------------------------------------------------------------------------+
PENDING = 'pending'
ALIVE = 'alive'
DEAD = 'dead'
======================================================================
=== FILE: clockblocks/clockblocks.clock.txt
======================================================================
clockblocks.clock
*****************
Module defining the central "Clock" class — recursively nestable
clocks that coordinate musical time under a master clock and its
background "Scheduler".
-[ Classes ]-
+------------+--------------------------------------------------------------------------------------------+
| "Clock"([n | Recursively nestable clock. |
| ame, | |
| parent, in | |
| itial_rate | |
| , ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "ClockFami | Fine-tuning options for a clock family, passed to a master "Clock" on construction. |
| lyOptions" | |
| ([timing_p | |
| olicy, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "ClockStat | Where a clock sits in its lifecycle. |
| e"(*values | |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
* clockblocks.clock.Clock
* "Clock"
* "Clock.master"
* "Clock.is_master()"
* "Clock.hold_scheduler()"
* "Clock.children()"
* "Clock.iterate_inheritance()"
* "Clock.inheritance()"
* "Clock.iterate_all_relatives()"
* "Clock.iterate_descendants()"
* "Clock.descendants()"
* "Clock.print_family_tree()"
* "Clock.time"
* "Clock.beat"
* "Clock.projected_time()"
* "Clock.projected_beat()"
* "Clock.status()"
* "Clock.print_status()"
* "Clock.beat_length"
* "Clock.rate"
* "Clock.tempo"
* "Clock.absolute_rate"
* "Clock.absolute_tempo"
* "Clock.absolute_beat_length"
* "Clock.set_beat_length_target()"
* "Clock.set_rate_target()"
* "Clock.set_tempo_target()"
* "Clock.set_beat_length_targets()"
* "Clock.set_rate_targets()"
* "Clock.set_tempo_targets()"
* "Clock.apply_beat_length_function()"
* "Clock.apply_rate_function()"
* "Clock.apply_tempo_function()"
* "Clock.apply_tempo_envelope()"
* "Clock.stop_tempo_loop_or_function()"
* "Clock.clock_to_scheduler_time()"
* "Clock.scheduler_to_clock_time()"
* "Clock.bring_up_to_date()"
* "Clock.extract_absolute_tempo_envelope()"
* "Clock.wait()"
* "Clock.wait_until()"
* "Clock.fork()"
* "Clock.schedule_action()"
* "Clock.wait_forever()"
* "Clock.wait_for_children_to_finish()"
* "Clock.wait_for_clock_to_finish()"
* "Clock.terminate_forked_children()"
* "Clock.run_as_server()"
* "Clock.alive"
* "Clock.fast_forward()"
* "Clock.fast_forward_to_time()"
* "Clock.fast_forward_in_time()"
* "Clock.fast_forward_to_beat()"
* "Clock.fast_forward_in_beats()"
* "Clock.is_fast_forwarding()"
* "Clock.timing_policy"
* "Clock.use_absolute_timing_policy()"
* "Clock.use_relative_timing_policy()"
* "Clock.use_mixed_timing_policy()"
* "Clock.precise_timing"
* "Clock.spin_guard_duration"
* "Clock.kill()"
* clockblocks.clock.ClockFamilyOptions
* "ClockFamilyOptions"
* "ClockFamilyOptions.timing_policy"
* "ClockFamilyOptions.precise_timing"
* "ClockFamilyOptions.spin_guard_duration"
* "ClockFamilyOptions.pool_size"
* "ClockFamilyOptions.prewarm_pool"
* "ClockFamilyOptions.time_backend"
* clockblocks.clock.ClockState
* "ClockState"
* "ClockState.PENDING"
* "ClockState.ALIVE"
* "ClockState.DEAD"
======================================================================
=== FILE: clockblocks/clockblocks.enums.DurationUnits.txt
======================================================================
clockblocks.enums.DurationUnits
*******************************
class clockblocks.enums.DurationUnits(*values)
Bases: "StrEnum"
Units with which we measure duration or Moment positioning. Either
musical BEATS, or the integrated TIME taken by those beats at the
clock's tempo.
Note that time is only true seconds on the master clock. Within a
clock tree, a child's TIME is the same as its parent's BEATS, and
is affected by the rates of all clocks above it in the tree. Use
"clock.master.time" for true seconds.
A "StrEnum", so the bare strings "beats" / "time" are accepted
interchangeably.
-[ Inherited Methods ]-
+------------+--------------------------------------------------------------------------------------------+
| "encode"([ | Encode the string using the codec registered for encoding. |
| encoding, | |
| errors]) | |
+------------+--------------------------------------------------------------------------------------------+
| "replace"( | Return a copy with all occurrences of substring old replaced by new. |
| old, new[, | |
| count]) | |
+------------+--------------------------------------------------------------------------------------------+
| "split"([s | Return a list of the substrings in the string, using sep as the separator string. |
| ep, | |
| maxsplit]) | |
+------------+--------------------------------------------------------------------------------------------+
| "rsplit"([ | Return a list of the substrings in the string, using sep as the separator string. |
| sep, | |
| maxsplit]) | |
+------------+--------------------------------------------------------------------------------------------+
| "join"(ite | Concatenate any number of strings. |
| rable, /) | |
+------------+--------------------------------------------------------------------------------------------+
| "capitaliz | Return a capitalized version of the string. |
| e"() | |
+------------+--------------------------------------------------------------------------------------------+
| "casefold" | Return a version of the string suitable for caseless comparisons. |
| () | |
+------------+--------------------------------------------------------------------------------------------+
| "title"() | Return a version of the string where each word is titlecased. |
+------------+--------------------------------------------------------------------------------------------+
| "center"(w | Return a centered string of length width. |
| idth[, | |
| fillchar]) | |
+------------+--------------------------------------------------------------------------------------------+
| "count"(su | Return the number of non-overlapping occurrences of substring sub in string S[start:end]. |
| b[, | |
| start[, | |
| end]]) | |
+------------+--------------------------------------------------------------------------------------------+
| "expandtab | Return a copy where all tab characters are expanded using spaces. |
| s"([tabsiz | |
| e]) | |
+------------+--------------------------------------------------------------------------------------------+
| "find"(sub | Return the lowest index in S where substring sub is found, such that sub is contained |
| [, start[, | within S[start:end]. |
| end]]) | |
+------------+--------------------------------------------------------------------------------------------+
| "partition | Partition the string into three parts using the given separator. |
| "(sep, /) | |
+------------+--------------------------------------------------------------------------------------------+
| "index"(su | Return the lowest index in S where substring sub is found, such that sub is contained |
| b[, | within S[start:end]. |
| start[, | |
| end]]) | |
+------------+--------------------------------------------------------------------------------------------+
| "ljust"(wi | Return a left-justified string of length width. |
| dth[, | |
| fillchar]) | |
+------------+--------------------------------------------------------------------------------------------+
| "lower"() | Return a copy of the string converted to lowercase. |
+------------+--------------------------------------------------------------------------------------------+
| "lstrip"([ | Return a copy of the string with leading whitespace removed. |
| chars]) | |
+------------+--------------------------------------------------------------------------------------------+
| "rfind"(su | Return the highest index in S where substring sub is found, such that sub is contained |
| b[, | within S[start:end]. |
| start[, | |
| end]]) | |
+------------+--------------------------------------------------------------------------------------------+
| "rindex"(s | Return the highest index in S where substring sub is found, such that sub is contained |
| ub[, | within S[start:end]. |
| start[, | |
| end]]) | |
+------------+--------------------------------------------------------------------------------------------+
| "rjust"(wi | Return a right-justified string of length width. |
| dth[, | |
| fillchar]) | |
+------------+--------------------------------------------------------------------------------------------+
| "rstrip"([ | Return a copy of the string with trailing whitespace removed. |
| chars]) | |
+------------+--------------------------------------------------------------------------------------------+
| "rpartitio | Partition the string into three parts using the given separator. |
| n"(sep, /) | |
+------------+--------------------------------------------------------------------------------------------+
| "splitline | Return a list of the lines in the string, breaking at line boundaries. |
| s"([keepen | |
| ds]) | |
+------------+--------------------------------------------------------------------------------------------+
| "strip"([c | Return a copy of the string with leading and trailing whitespace removed. |
| hars]) | |
+------------+--------------------------------------------------------------------------------------------+
| "swapcase" | Convert uppercase characters to lowercase and lowercase characters to uppercase. |
| () | |
+------------+--------------------------------------------------------------------------------------------+
| "translate | Replace each character in the string using the given translation table. |
| "(table, | |
| /) | |
+------------+--------------------------------------------------------------------------------------------+
| "upper"() | Return a copy of the string converted to uppercase. |
+------------+--------------------------------------------------------------------------------------------+
| "startswit | Return True if S starts with the specified prefix, False otherwise. |
| h"(prefix[ | |
| , start[, | |
| end]]) | |
+------------+--------------------------------------------------------------------------------------------+
| "endswith" | Return True if S ends with the specified suffix, False otherwise. |
| (suffix[, | |
| start[, | |
| end]]) | |
+------------+--------------------------------------------------------------------------------------------+
| "removepre | Return a str with the given prefix string removed if present. |
| fix"(prefi | |
| x, /) | |
+------------+--------------------------------------------------------------------------------------------+
| "removesuf | Return a str with the given suffix string removed if present. |
| fix"(suffi | |
| x, /) | |
+------------+--------------------------------------------------------------------------------------------+
| "isascii"( | Return True if all characters in the string are ASCII, False otherwise. |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "islower"( | Return True if the string is a lowercase string, False otherwise. |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "isupper"( | Return True if the string is an uppercase string, False otherwise. |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "istitle"( | Return True if the string is a title-cased string, False otherwise. |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "isspace"( | Return True if the string is a whitespace string, False otherwise. |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "isdecimal | Return True if the string is a decimal string, False otherwise. |
| "() | |
+------------+--------------------------------------------------------------------------------------------+
| "isdigit"( | Return True if the string is a digit string, False otherwise. |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "isnumeric | Return True if the string is a numeric string, False otherwise. |
| "() | |
+------------+--------------------------------------------------------------------------------------------+
| "isalpha"( | Return True if the string is an alphabetic string, False otherwise. |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "isalnum"( | Return True if the string is an alpha-numeric string, False otherwise. |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "isidentif | Return True if the string is a valid Python identifier, False otherwise. |
| ier"() | |
+------------+--------------------------------------------------------------------------------------------+
| "isprintab | Return True if the string is printable, False otherwise. |
| le"() | |
+------------+--------------------------------------------------------------------------------------------+
| "zfill"(wi | Pad a numeric string with zeros on the left, to fill a field of the given width. |
| dth, /) | |
+------------+--------------------------------------------------------------------------------------------+
| "format"(* | Return a formatted version of S, using substitutions from args and kwargs. |
| args, | |
| **kwargs) | |
+------------+--------------------------------------------------------------------------------------------+
| "format_ma | Return a formatted version of S, using substitutions from mapping. |
| p"(mapping | |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "maketrans | Return a translation table usable for str.translate(). |
| " | |
+------------+--------------------------------------------------------------------------------------------+
-[ Attributes ]-
+------------+--------------------------------------------------------------------------------------------+
| "opposite" | The other axis: "BEATS.opposite" is "TIME" and vice versa. |
+------------+--------------------------------------------------------------------------------------------+
| "BEATS" | |
+------------+--------------------------------------------------------------------------------------------+
| "TIME" | |
+------------+--------------------------------------------------------------------------------------------+
BEATS = 'beats'
TIME = 'time'
property opposite: DurationUnits
The other axis: "BEATS.opposite" is "TIME" and vice versa. Used
to get the *free* axis (the one a *when* did not pin) when
solving alignment.
encode(encoding='utf-8', errors='strict')
Encode the string using the codec registered for encoding.
encoding
The encoding in which to encode the string.
errors
The error handling scheme to use for encoding errors. The
default is 'strict' meaning that encoding errors raise a
UnicodeEncodeError. Other possible values are 'ignore',
'replace' and 'xmlcharrefreplace' as well as any other name
registered with codecs.register_error that can handle
UnicodeEncodeErrors.
replace(old, new, count=-1, /)
Return a copy with all occurrences of substring old replaced by
new.
count
Maximum number of occurrences to replace. -1 (the default
value) means replace all occurrences.
If the optional argument count is given, only the first count
occurrences are replaced.
split(sep=None, maxsplit=-1)
Return a list of the substrings in the string, using sep as the
separator string.
sep
The separator used to split the string.
When set to None (the default value), will split on any
whitespace character (including n r t f and spaces) and
will discard empty strings from the result.
maxsplit
Maximum number of splits. -1 (the default value) means no
limit.
Splitting starts at the front of the string and works to the
end.
Note, str.split() is mainly useful for data that has been
intentionally delimited. With natural text that includes
punctuation, consider using the regular expression module.
rsplit(sep=None, maxsplit=-1)
Return a list of the substrings in the string, using sep as the
separator string.
sep
The separator used to split the string.
When set to None (the default value), will split on any
whitespace character (including n r t f and spaces) and
will discard empty strings from the result.
maxsplit
Maximum number of splits. -1 (the default value) means no
limit.
Splitting starts at the end of the string and works to the
front.
join(iterable, /)
Concatenate any number of strings.
The string whose method is called is inserted in between each
given string. The result is returned as a new string.
Example: '.'.join(['ab', 'pq', 'rs']) -> 'ab.pq.rs'
capitalize()
Return a capitalized version of the string.
More specifically, make the first character have upper case and
the rest lower case.
casefold()
Return a version of the string suitable for caseless
comparisons.
title()
Return a version of the string where each word is titlecased.
More specifically, words start with uppercased characters and
all remaining cased characters have lower case.
center(width, fillchar=' ', /)
Return a centered string of length width.
Padding is done using the specified fill character (default is a
space).
count(sub[, start[, end]]) -> int
Return the number of non-overlapping occurrences of substring
sub in string S[start:end]. Optional arguments start and end
are interpreted as in slice notation.
expandtabs(tabsize=8)
Return a copy where all tab characters are expanded using
spaces.
If tabsize is not given, a tab size of 8 characters is assumed.
find(sub[, start[, end]]) -> int
Return the lowest index in S where substring sub is found, such
that sub is contained within S[start:end]. Optional arguments
start and end are interpreted as in slice notation.
Return -1 on failure.
partition(sep, /)
Partition the string into three parts using the given separator.
This will search for the separator in the string. If the
separator is found, returns a 3-tuple containing the part before
the separator, the separator itself, and the part after it.
If the separator is not found, returns a 3-tuple containing the
original string and two empty strings.
index(sub[, start[, end]]) -> int
Return the lowest index in S where substring sub is found, such
that sub is contained within S[start:end]. Optional arguments
start and end are interpreted as in slice notation.
Raises ValueError when the substring is not found.
ljust(width, fillchar=' ', /)
Return a left-justified string of length width.
Padding is done using the specified fill character (default is a
space).
lower()
Return a copy of the string converted to lowercase.
lstrip(chars=None, /)
Return a copy of the string with leading whitespace removed.
If chars is given and not None, remove characters in chars
instead.
rfind(sub[, start[, end]]) -> int
Return the highest index in S where substring sub is found, such
that sub is contained within S[start:end]. Optional arguments
start and end are interpreted as in slice notation.
Return -1 on failure.
rindex(sub[, start[, end]]) -> int
Return the highest index in S where substring sub is found, such
that sub is contained within S[start:end]. Optional arguments
start and end are interpreted as in slice notation.
Raises ValueError when the substring is not found.
rjust(width, fillchar=' ', /)
Return a right-justified string of length width.
Padding is done using the specified fill character (default is a
space).
rstrip(chars=None, /)
Return a copy of the string with trailing whitespace removed.
If chars is given and not None, remove characters in chars
instead.
rpartition(sep, /)
Partition the string into three parts using the given separator.
This will search for the separator in the string, starting at
the end. If the separator is found, returns a 3-tuple containing
the part before the separator, the separator itself, and the
part after it.
If the separator is not found, returns a 3-tuple containing two
empty strings and the original string.
splitlines(keepends=False)
Return a list of the lines in the string, breaking at line
boundaries.
Line breaks are not included in the resulting list unless
keepends is given and true.
strip(chars=None, /)
Return a copy of the string with leading and trailing whitespace
removed.
If chars is given and not None, remove characters in chars
instead.
swapcase()
Convert uppercase characters to lowercase and lowercase
characters to uppercase.
translate(table, /)
Replace each character in the string using the given translation
table.
table
Translation table, which must be a mapping of Unicode
ordinals to Unicode ordinals, strings, or None.
The table must implement lookup/indexing via __getitem__, for
instance a dictionary or list. If this operation raises
LookupError, the character is left untouched. Characters mapped
to None are deleted.
upper()
Return a copy of the string converted to uppercase.
startswith(prefix[, start[, end]]) -> bool
Return True if S starts with the specified prefix, False
otherwise. With optional start, test S beginning at that
position. With optional end, stop comparing S at that position.
prefix can also be a tuple of strings to try.
endswith(suffix[, start[, end]]) -> bool
Return True if S ends with the specified suffix, False
otherwise. With optional start, test S beginning at that
position. With optional end, stop comparing S at that position.
suffix can also be a tuple of strings to try.
removeprefix(prefix, /)
Return a str with the given prefix string removed if present.
If the string starts with the prefix string, return
string[len(prefix):]. Otherwise, return a copy of the original
string.
removesuffix(suffix, /)
Return a str with the given suffix string removed if present.
If the string ends with the suffix string and that suffix is not
empty, return string[:-len(suffix)]. Otherwise, return a copy of
the original string.
isascii()
Return True if all characters in the string are ASCII, False
otherwise.
ASCII characters have code points in the range U+0000-U+007F.
Empty string is ASCII too.
islower()
Return True if the string is a lowercase string, False
otherwise.
A string is lowercase if all cased characters in the string are
lowercase and there is at least one cased character in the
string.
isupper()
Return True if the string is an uppercase string, False
otherwise.
A string is uppercase if all cased characters in the string are
uppercase and there is at least one cased character in the
string.
istitle()
Return True if the string is a title-cased string, False
otherwise.
In a title-cased string, upper- and title-case characters may
only follow uncased characters and lowercase characters only
cased ones.
isspace()
Return True if the string is a whitespace string, False
otherwise.
A string is whitespace if all characters in the string are
whitespace and there is at least one character in the string.
isdecimal()
Return True if the string is a decimal string, False otherwise.
A string is a decimal string if all characters in the string are
decimal and there is at least one character in the string.
isdigit()
Return True if the string is a digit string, False otherwise.
A string is a digit string if all characters in the string are
digits and there is at least one character in the string.
isnumeric()
Return True if the string is a numeric string, False otherwise.
A string is numeric if all characters in the string are numeric
and there is at least one character in the string.
isalpha()
Return True if the string is an alphabetic string, False
otherwise.
A string is alphabetic if all characters in the string are
alphabetic and there is at least one character in the string.
isalnum()
Return True if the string is an alpha-numeric string, False
otherwise.
A string is alpha-numeric if all characters in the string are
alpha-numeric and there is at least one character in the string.
isidentifier()
Return True if the string is a valid Python identifier, False
otherwise.
Call keyword.iskeyword(s) to test whether string s is a reserved
identifier, such as "def" or "class".
isprintable()
Return True if the string is printable, False otherwise.
A string is printable if all of its characters are considered
printable in repr() or if it is empty.
zfill(width, /)
Pad a numeric string with zeros on the left, to fill a field of
the given width.
The string is never truncated.
format(*args, **kwargs) -> str
Return a formatted version of S, using substitutions from args
and kwargs. The substitutions are identified by braces ('{' and
'}').
format_map(mapping) -> str
Return a formatted version of S, using substitutions from
mapping. The substitutions are identified by braces ('{' and
'}').
static maketrans()
Return a translation table usable for str.translate().
If there is only one argument, it must be a dictionary mapping
Unicode ordinals (integers) or characters to Unicode ordinals,
strings or None. Character keys will be then converted to
ordinals. If there are two arguments, they must be strings of
equal length, and in the resulting dictionary, each character in
x will be mapped to the character at the same position in y. If
there is a third argument, it must be a string, whose characters
will be mapped to None in the result.
======================================================================
=== FILE: clockblocks/clockblocks.enums.TempoUnits.txt
======================================================================
clockblocks.enums.TempoUnits
****************************
class clockblocks.enums.TempoUnits(*values)
Bases: "StrEnum"
The three different, and mutually determined, ways of expressing
tempo.
* TEMPO is the standard BPM understood by musicians
* RATE is in beats per second, and useful for reasoning about tempo
relationships in a clock tree
* BEATLENGTH is the duration of one beat; mostly useful internally
as the unit we're integrating over
A "StrEnum", so the bare strings are accepted.
-[ Inherited Methods ]-
+------------+--------------------------------------------------------------------------------------------+
| "encode"([ | Encode the string using the codec registered for encoding. |
| encoding, | |
| errors]) | |
+------------+--------------------------------------------------------------------------------------------+
| "replace"( | Return a copy with all occurrences of substring old replaced by new. |
| old, new[, | |
| count]) | |
+------------+--------------------------------------------------------------------------------------------+
| "split"([s | Return a list of the substrings in the string, using sep as the separator string. |
| ep, | |
| maxsplit]) | |
+------------+--------------------------------------------------------------------------------------------+
| "rsplit"([ | Return a list of the substrings in the string, using sep as the separator string. |
| sep, | |
| maxsplit]) | |
+------------+--------------------------------------------------------------------------------------------+
| "join"(ite | Concatenate any number of strings. |
| rable, /) | |
+------------+--------------------------------------------------------------------------------------------+
| "capitaliz | Return a capitalized version of the string. |
| e"() | |
+------------+--------------------------------------------------------------------------------------------+
| "casefold" | Return a version of the string suitable for caseless comparisons. |
| () | |
+------------+--------------------------------------------------------------------------------------------+
| "title"() | Return a version of the string where each word is titlecased. |
+------------+--------------------------------------------------------------------------------------------+
| "center"(w | Return a centered string of length width. |
| idth[, | |
| fillchar]) | |
+------------+--------------------------------------------------------------------------------------------+
| "count"(su | Return the number of non-overlapping occurrences of substring sub in string S[start:end]. |
| b[, | |
| start[, | |
| end]]) | |
+------------+--------------------------------------------------------------------------------------------+
| "expandtab | Return a copy where all tab characters are expanded using spaces. |
| s"([tabsiz | |
| e]) | |
+------------+--------------------------------------------------------------------------------------------+
| "find"(sub | Return the lowest index in S where substring sub is found, such that sub is contained |
| [, start[, | within S[start:end]. |
| end]]) | |
+------------+--------------------------------------------------------------------------------------------+
| "partition | Partition the string into three parts using the given separator. |
| "(sep, /) | |
+------------+--------------------------------------------------------------------------------------------+
| "index"(su | Return the lowest index in S where substring sub is found, such that sub is contained |
| b[, | within S[start:end]. |
| start[, | |
| end]]) | |
+------------+--------------------------------------------------------------------------------------------+
| "ljust"(wi | Return a left-justified string of length width. |
| dth[, | |
| fillchar]) | |
+------------+--------------------------------------------------------------------------------------------+
| "lower"() | Return a copy of the string converted to lowercase. |
+------------+--------------------------------------------------------------------------------------------+
| "lstrip"([ | Return a copy of the string with leading whitespace removed. |
| chars]) | |
+------------+--------------------------------------------------------------------------------------------+
| "rfind"(su | Return the highest index in S where substring sub is found, such that sub is contained |
| b[, | within S[start:end]. |
| start[, | |
| end]]) | |
+------------+--------------------------------------------------------------------------------------------+
| "rindex"(s | Return the highest index in S where substring sub is found, such that sub is contained |
| ub[, | within S[start:end]. |
| start[, | |
| end]]) | |
+------------+--------------------------------------------------------------------------------------------+
| "rjust"(wi | Return a right-justified string of length width. |
| dth[, | |
| fillchar]) | |
+------------+--------------------------------------------------------------------------------------------+
| "rstrip"([ | Return a copy of the string with trailing whitespace removed. |
| chars]) | |
+------------+--------------------------------------------------------------------------------------------+
| "rpartitio | Partition the string into three parts using the given separator. |
| n"(sep, /) | |
+------------+--------------------------------------------------------------------------------------------+
| "splitline | Return a list of the lines in the string, breaking at line boundaries. |
| s"([keepen | |
| ds]) | |
+------------+--------------------------------------------------------------------------------------------+
| "strip"([c | Return a copy of the string with leading and trailing whitespace removed. |
| hars]) | |
+------------+--------------------------------------------------------------------------------------------+
| "swapcase" | Convert uppercase characters to lowercase and lowercase characters to uppercase. |
| () | |
+------------+--------------------------------------------------------------------------------------------+
| "translate | Replace each character in the string using the given translation table. |
| "(table, | |
| /) | |
+------------+--------------------------------------------------------------------------------------------+
| "upper"() | Return a copy of the string converted to uppercase. |
+------------+--------------------------------------------------------------------------------------------+
| "startswit | Return True if S starts with the specified prefix, False otherwise. |
| h"(prefix[ | |
| , start[, | |
| end]]) | |
+------------+--------------------------------------------------------------------------------------------+
| "endswith" | Return True if S ends with the specified suffix, False otherwise. |
| (suffix[, | |
| start[, | |
| end]]) | |
+------------+--------------------------------------------------------------------------------------------+
| "removepre | Return a str with the given prefix string removed if present. |
| fix"(prefi | |
| x, /) | |
+------------+--------------------------------------------------------------------------------------------+
| "removesuf | Return a str with the given suffix string removed if present. |
| fix"(suffi | |
| x, /) | |
+------------+--------------------------------------------------------------------------------------------+
| "isascii"( | Return True if all characters in the string are ASCII, False otherwise. |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "islower"( | Return True if the string is a lowercase string, False otherwise. |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "isupper"( | Return True if the string is an uppercase string, False otherwise. |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "istitle"( | Return True if the string is a title-cased string, False otherwise. |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "isspace"( | Return True if the string is a whitespace string, False otherwise. |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "isdecimal | Return True if the string is a decimal string, False otherwise. |
| "() | |
+------------+--------------------------------------------------------------------------------------------+
| "isdigit"( | Return True if the string is a digit string, False otherwise. |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "isnumeric | Return True if the string is a numeric string, False otherwise. |
| "() | |
+------------+--------------------------------------------------------------------------------------------+
| "isalpha"( | Return True if the string is an alphabetic string, False otherwise. |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "isalnum"( | Return True if the string is an alpha-numeric string, False otherwise. |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "isidentif | Return True if the string is a valid Python identifier, False otherwise. |
| ier"() | |
+------------+--------------------------------------------------------------------------------------------+
| "isprintab | Return True if the string is printable, False otherwise. |
| le"() | |
+------------+--------------------------------------------------------------------------------------------+
| "zfill"(wi | Pad a numeric string with zeros on the left, to fill a field of the given width. |
| dth, /) | |
+------------+--------------------------------------------------------------------------------------------+
| "format"(* | Return a formatted version of S, using substitutions from args and kwargs. |
| args, | |
| **kwargs) | |
+------------+--------------------------------------------------------------------------------------------+
| "format_ma | Return a formatted version of S, using substitutions from mapping. |
| p"(mapping | |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "maketrans | Return a translation table usable for str.translate(). |
| " | |
+------------+--------------------------------------------------------------------------------------------+
-[ Attributes ]-
+------------+--------------------------------------------------------------------------------------------+
| "TEMPO" | |
+------------+--------------------------------------------------------------------------------------------+
| "RATE" | |
+------------+--------------------------------------------------------------------------------------------+
| "BEATLENGT | |
| H" | |
+------------+--------------------------------------------------------------------------------------------+
TEMPO = 'tempo'
RATE = 'rate'
BEATLENGTH = 'beatlength'
encode(encoding='utf-8', errors='strict')
Encode the string using the codec registered for encoding.
encoding
The encoding in which to encode the string.
errors
The error handling scheme to use for encoding errors. The
default is 'strict' meaning that encoding errors raise a
UnicodeEncodeError. Other possible values are 'ignore',
'replace' and 'xmlcharrefreplace' as well as any other name
registered with codecs.register_error that can handle
UnicodeEncodeErrors.
replace(old, new, count=-1, /)
Return a copy with all occurrences of substring old replaced by
new.
count
Maximum number of occurrences to replace. -1 (the default
value) means replace all occurrences.
If the optional argument count is given, only the first count
occurrences are replaced.
split(sep=None, maxsplit=-1)
Return a list of the substrings in the string, using sep as the
separator string.
sep
The separator used to split the string.
When set to None (the default value), will split on any
whitespace character (including n r t f and spaces) and
will discard empty strings from the result.
maxsplit
Maximum number of splits. -1 (the default value) means no
limit.
Splitting starts at the front of the string and works to the
end.
Note, str.split() is mainly useful for data that has been
intentionally delimited. With natural text that includes
punctuation, consider using the regular expression module.
rsplit(sep=None, maxsplit=-1)
Return a list of the substrings in the string, using sep as the
separator string.
sep
The separator used to split the string.
When set to None (the default value), will split on any
whitespace character (including n r t f and spaces) and
will discard empty strings from the result.
maxsplit
Maximum number of splits. -1 (the default value) means no
limit.
Splitting starts at the end of the string and works to the
front.
join(iterable, /)
Concatenate any number of strings.
The string whose method is called is inserted in between each
given string. The result is returned as a new string.
Example: '.'.join(['ab', 'pq', 'rs']) -> 'ab.pq.rs'
capitalize()
Return a capitalized version of the string.
More specifically, make the first character have upper case and
the rest lower case.
casefold()
Return a version of the string suitable for caseless
comparisons.
title()
Return a version of the string where each word is titlecased.
More specifically, words start with uppercased characters and
all remaining cased characters have lower case.
center(width, fillchar=' ', /)
Return a centered string of length width.
Padding is done using the specified fill character (default is a
space).
count(sub[, start[, end]]) -> int
Return the number of non-overlapping occurrences of substring
sub in string S[start:end]. Optional arguments start and end
are interpreted as in slice notation.
expandtabs(tabsize=8)
Return a copy where all tab characters are expanded using
spaces.
If tabsize is not given, a tab size of 8 characters is assumed.
find(sub[, start[, end]]) -> int
Return the lowest index in S where substring sub is found, such
that sub is contained within S[start:end]. Optional arguments
start and end are interpreted as in slice notation.
Return -1 on failure.
partition(sep, /)
Partition the string into three parts using the given separator.
This will search for the separator in the string. If the
separator is found, returns a 3-tuple containing the part before
the separator, the separator itself, and the part after it.
If the separator is not found, returns a 3-tuple containing the
original string and two empty strings.
index(sub[, start[, end]]) -> int
Return the lowest index in S where substring sub is found, such
that sub is contained within S[start:end]. Optional arguments
start and end are interpreted as in slice notation.
Raises ValueError when the substring is not found.
ljust(width, fillchar=' ', /)
Return a left-justified string of length width.
Padding is done using the specified fill character (default is a
space).
lower()
Return a copy of the string converted to lowercase.
lstrip(chars=None, /)
Return a copy of the string with leading whitespace removed.
If chars is given and not None, remove characters in chars
instead.
rfind(sub[, start[, end]]) -> int
Return the highest index in S where substring sub is found, such
that sub is contained within S[start:end]. Optional arguments
start and end are interpreted as in slice notation.
Return -1 on failure.
rindex(sub[, start[, end]]) -> int
Return the highest index in S where substring sub is found, such
that sub is contained within S[start:end]. Optional arguments
start and end are interpreted as in slice notation.
Raises ValueError when the substring is not found.
rjust(width, fillchar=' ', /)
Return a right-justified string of length width.
Padding is done using the specified fill character (default is a
space).
rstrip(chars=None, /)
Return a copy of the string with trailing whitespace removed.
If chars is given and not None, remove characters in chars
instead.
rpartition(sep, /)
Partition the string into three parts using the given separator.
This will search for the separator in the string, starting at
the end. If the separator is found, returns a 3-tuple containing
the part before the separator, the separator itself, and the
part after it.
If the separator is not found, returns a 3-tuple containing two
empty strings and the original string.
splitlines(keepends=False)
Return a list of the lines in the string, breaking at line
boundaries.
Line breaks are not included in the resulting list unless
keepends is given and true.
strip(chars=None, /)
Return a copy of the string with leading and trailing whitespace
removed.
If chars is given and not None, remove characters in chars
instead.
swapcase()
Convert uppercase characters to lowercase and lowercase
characters to uppercase.
translate(table, /)
Replace each character in the string using the given translation
table.
table
Translation table, which must be a mapping of Unicode
ordinals to Unicode ordinals, strings, or None.
The table must implement lookup/indexing via __getitem__, for
instance a dictionary or list. If this operation raises
LookupError, the character is left untouched. Characters mapped
to None are deleted.
upper()
Return a copy of the string converted to uppercase.
startswith(prefix[, start[, end]]) -> bool
Return True if S starts with the specified prefix, False
otherwise. With optional start, test S beginning at that
position. With optional end, stop comparing S at that position.
prefix can also be a tuple of strings to try.
endswith(suffix[, start[, end]]) -> bool
Return True if S ends with the specified suffix, False
otherwise. With optional start, test S beginning at that
position. With optional end, stop comparing S at that position.
suffix can also be a tuple of strings to try.
removeprefix(prefix, /)
Return a str with the given prefix string removed if present.
If the string starts with the prefix string, return
string[len(prefix):]. Otherwise, return a copy of the original
string.
removesuffix(suffix, /)
Return a str with the given suffix string removed if present.
If the string ends with the suffix string and that suffix is not
empty, return string[:-len(suffix)]. Otherwise, return a copy of
the original string.
isascii()
Return True if all characters in the string are ASCII, False
otherwise.
ASCII characters have code points in the range U+0000-U+007F.
Empty string is ASCII too.
islower()
Return True if the string is a lowercase string, False
otherwise.
A string is lowercase if all cased characters in the string are
lowercase and there is at least one cased character in the
string.
isupper()
Return True if the string is an uppercase string, False
otherwise.
A string is uppercase if all cased characters in the string are
uppercase and there is at least one cased character in the
string.
istitle()
Return True if the string is a title-cased string, False
otherwise.
In a title-cased string, upper- and title-case characters may
only follow uncased characters and lowercase characters only
cased ones.
isspace()
Return True if the string is a whitespace string, False
otherwise.
A string is whitespace if all characters in the string are
whitespace and there is at least one character in the string.
isdecimal()
Return True if the string is a decimal string, False otherwise.
A string is a decimal string if all characters in the string are
decimal and there is at least one character in the string.
isdigit()
Return True if the string is a digit string, False otherwise.
A string is a digit string if all characters in the string are
digits and there is at least one character in the string.
isnumeric()
Return True if the string is a numeric string, False otherwise.
A string is numeric if all characters in the string are numeric
and there is at least one character in the string.
isalpha()
Return True if the string is an alphabetic string, False
otherwise.
A string is alphabetic if all characters in the string are
alphabetic and there is at least one character in the string.
isalnum()
Return True if the string is an alpha-numeric string, False
otherwise.
A string is alpha-numeric if all characters in the string are
alpha-numeric and there is at least one character in the string.
isidentifier()
Return True if the string is a valid Python identifier, False
otherwise.
Call keyword.iskeyword(s) to test whether string s is a reserved
identifier, such as "def" or "class".
isprintable()
Return True if the string is printable, False otherwise.
A string is printable if all of its characters are considered
printable in repr() or if it is empty.
zfill(width, /)
Pad a numeric string with zeros on the left, to fill a field of
the given width.
The string is never truncated.
format(*args, **kwargs) -> str
Return a formatted version of S, using substitutions from args
and kwargs. The substitutions are identified by braces ('{' and
'}').
format_map(mapping) -> str
Return a formatted version of S, using substitutions from
mapping. The substitutions are identified by braces ('{' and
'}').
static maketrans()
Return a translation table usable for str.translate().
If there is only one argument, it must be a dictionary mapping
Unicode ordinals (integers) or characters to Unicode ordinals,
strings or None. Character keys will be then converted to
ordinals. If there are two arguments, they must be strings of
equal length, and in the resulting dictionary, each character in
x will be mapped to the character at the same position in y. If
there is a third argument, it must be a string, whose characters
will be mapped to None in the result.
======================================================================
=== FILE: clockblocks/clockblocks.enums.txt
======================================================================
clockblocks.enums
*****************
Module containing the enums used to express units of duration and
rate: "DurationUnits", for saying whether a quantity is measured in
beats or in time, and "TempoUnits", for saying whether a rate of
musical time is expressed as a tempo, a rate, or a beat length.
-[ Classes ]-
+------------+--------------------------------------------------------------------------------------------+
| "DurationU | Units with which we measure duration or Moment positioning. |
| nits"(*val | |
| ues) | |
+------------+--------------------------------------------------------------------------------------------+
| "TempoUnit | The three different, and mutually determined, ways of expressing tempo. |
| s"(*values | |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
* clockblocks.enums.DurationUnits
* "DurationUnits"
* "DurationUnits.BEATS"
* "DurationUnits.TIME"
* "DurationUnits.opposite"
* "DurationUnits.encode()"
* "DurationUnits.replace()"
* "DurationUnits.split()"
* "DurationUnits.rsplit()"
* "DurationUnits.join()"
* "DurationUnits.capitalize()"
* "DurationUnits.casefold()"
* "DurationUnits.title()"
* "DurationUnits.center()"
* "DurationUnits.count()"
* "DurationUnits.expandtabs()"
* "DurationUnits.find()"
* "DurationUnits.partition()"
* "DurationUnits.index()"
* "DurationUnits.ljust()"
* "DurationUnits.lower()"
* "DurationUnits.lstrip()"
* "DurationUnits.rfind()"
* "DurationUnits.rindex()"
* "DurationUnits.rjust()"
* "DurationUnits.rstrip()"
* "DurationUnits.rpartition()"
* "DurationUnits.splitlines()"
* "DurationUnits.strip()"
* "DurationUnits.swapcase()"
* "DurationUnits.translate()"
* "DurationUnits.upper()"
* "DurationUnits.startswith()"
* "DurationUnits.endswith()"
* "DurationUnits.removeprefix()"
* "DurationUnits.removesuffix()"
* "DurationUnits.isascii()"
* "DurationUnits.islower()"
* "DurationUnits.isupper()"
* "DurationUnits.istitle()"
* "DurationUnits.isspace()"
* "DurationUnits.isdecimal()"
* "DurationUnits.isdigit()"
* "DurationUnits.isnumeric()"
* "DurationUnits.isalpha()"
* "DurationUnits.isalnum()"
* "DurationUnits.isidentifier()"
* "DurationUnits.isprintable()"
* "DurationUnits.zfill()"
* "DurationUnits.format()"
* "DurationUnits.format_map()"
* "DurationUnits.maketrans()"
* clockblocks.enums.TempoUnits
* "TempoUnits"
* "TempoUnits.TEMPO"
* "TempoUnits.RATE"
* "TempoUnits.BEATLENGTH"
* "TempoUnits.encode()"
* "TempoUnits.replace()"
* "TempoUnits.split()"
* "TempoUnits.rsplit()"
* "TempoUnits.join()"
* "TempoUnits.capitalize()"
* "TempoUnits.casefold()"
* "TempoUnits.title()"
* "TempoUnits.center()"
* "TempoUnits.count()"
* "TempoUnits.expandtabs()"
* "TempoUnits.find()"
* "TempoUnits.partition()"
* "TempoUnits.index()"
* "TempoUnits.ljust()"
* "TempoUnits.lower()"
* "TempoUnits.lstrip()"
* "TempoUnits.rfind()"
* "TempoUnits.rindex()"
* "TempoUnits.rjust()"
* "TempoUnits.rstrip()"
* "TempoUnits.rpartition()"
* "TempoUnits.splitlines()"
* "TempoUnits.strip()"
* "TempoUnits.swapcase()"
* "TempoUnits.translate()"
* "TempoUnits.upper()"
* "TempoUnits.startswith()"
* "TempoUnits.endswith()"
* "TempoUnits.removeprefix()"
* "TempoUnits.removesuffix()"
* "TempoUnits.isascii()"
* "TempoUnits.islower()"
* "TempoUnits.isupper()"
* "TempoUnits.istitle()"
* "TempoUnits.isspace()"
* "TempoUnits.isdecimal()"
* "TempoUnits.isdigit()"
* "TempoUnits.isnumeric()"
* "TempoUnits.isalpha()"
* "TempoUnits.isalnum()"
* "TempoUnits.isidentifier()"
* "TempoUnits.isprintable()"
* "TempoUnits.zfill()"
* "TempoUnits.format()"
* "TempoUnits.format_map()"
* "TempoUnits.maketrans()"
======================================================================
=== FILE: clockblocks/clockblocks.exceptions.txt
======================================================================
clockblocks.exceptions
**********************
Exception hierarchy for clockblocks. Kept in a dependency-free module
of its own so that any module ("clock", "utilities", "scheduler", …)
can import these at the top level without risking an import cycle —
several of them reference each other's errors but none of them should
have to defer the import to function-call time.
-[ Exceptions ]-
+------------+--------------------------------------------------------------------------------------------+
| "ClockKill | Raised inside a forked clock's own thread when its wait is woken by kill(), so the fork |
| edError" | wrapper can unwind the user function cleanly. |
+------------+--------------------------------------------------------------------------------------------+
| "Clockbloc | Base class for clockblocks errors. |
| ksError" | |
+------------+--------------------------------------------------------------------------------------------+
| "DeadClock | Raised when something tries to wait or fork on a clock that's no longer ALIVE (either |
| Error" | killed already, or — for fork — still PENDING in its start_delay). |
+------------+--------------------------------------------------------------------------------------------+
| "NoActiveC | Raised when a context-inferring clock operation (the module-level wait/fork/etc.) is |
| lockError" | attempted from a thread that has no clock active on it. |
+------------+--------------------------------------------------------------------------------------------+
| "NotMaster | Raised by operations that are only valid on the master (top-level) clock — e.g. |
| ClockError | run_as_server() — when called on a child clock. |
| " | |
+------------+--------------------------------------------------------------------------------------------+
| "Scheduler | Raised when wait() is called from a thread that is holding the scheduler via |
| HeldError" | hold_scheduler() — most commonly inside a MIDI / OSC / HID callback, which runs under such |
| | a hold. |
+------------+--------------------------------------------------------------------------------------------+
| "WrongThre | Raised when wait() is called from a thread that doesn't own the clock. |
| adError" | |
+------------+--------------------------------------------------------------------------------------------+
======================================================================
=== FILE: clockblocks/clockblocks.metric_phase.MetricPhaseTarget.txt
======================================================================
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)
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_neare | Get the nearest beats below and above the given beat with the correct metric phase |
| st_matchin | |
| g_beats"(b | |
| eat) | |
+------------+--------------------------------------------------------------------------------------------+
| "get_neare | Get the nearest times below and above the given time with the correct metric phase |
| st_matchin | |
| g_times"(t | |
| ime) | |
+------------+--------------------------------------------------------------------------------------------+
| "resolve"( | Resolve this phase target to an absolute Moment on *clock*: the nearest *future* moment in |
| clock) | the clock (either a beat or time, depending on self.units) whose metric phase matches. |
+------------+--------------------------------------------------------------------------------------------+
get_nearest_matching_beats(beat: float) -> Tuple[float, float]
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]
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
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.
======================================================================
=== FILE: clockblocks/clockblocks.metric_phase.txt
======================================================================
clockblocks.metric_phase
************************
Module containing the "MetricPhaseTarget" class, which names a point
within a repeating beat or measure cycle — "the next downbeat", say,
or "halfway through the bar" — without having to work out how far away
that point actually is. Pass one wherever a moment in time is called
for: to "wait()" to wait until the next such point, to "fork()" to
start a child clock there, or as the *when* or *align_to* of a tempo
target, to land an accelerando exactly on a downbeat.
-[ Classes ]-
+------------+--------------------------------------------------------------------------------------------+
| "MetricPha | Class representing a particular point in a (beat or measure) cycle. |
| seTarget"( | |
| phase_or_p | |
| hases[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
* clockblocks.metric_phase.MetricPhaseTarget
* "MetricPhaseTarget"
* "MetricPhaseTarget.get_nearest_matching_beats()"
* "MetricPhaseTarget.get_nearest_matching_times()"
* "MetricPhaseTarget.resolve()"
======================================================================
=== FILE: clockblocks/clockblocks.moment.Moment.txt
======================================================================
clockblocks.moment.Moment
*************************
class clockblocks.moment.Moment(value: float, units: str | DurationUnits = 'beats', relative: bool = False)
Bases: "object"
Represents a point on a clock's timeline. Can be either in beats or
in time (as defined by *units*), and can be either relative
(measured from a clock's current beat/time) or absolute (measured
from the clock's start).
User code should generally construct via one of the classmethods:
Moment.at_beat(8) # absolute: beat 8 of the clock
Moment.at_time(8) # absolute: 8 seconds (in the clock's
time) since it started Moment.after_beats(2) # relative: 2
beats from now Moment.after_time(0.5) # relative: 0.5 seconds
from now
resolve(clock) returns an *absolute* Moment on that clock (a no-op
if already absolute). The final scheduling process works only with
absolute Moments, which are either pinned to a specific beat or a
specific time in the clock's timeline. Relative moments or
MetricPhaseTargets are resolved at scheduling time into absolute
moments.
Parameters:
* **value** -- how far along the timeline this moment sits, in
the given units
* **units** -- whether *value* counts beats or time
("beats"/"time", or a "DurationUnits")
* **relative** -- if True, *value* is an offset from the clock's
current position rather than a point measured from the clock's
start
-[ Methods ]-
+------------+--------------------------------------------------------------------------------------------+
| "after_bea | A relative moment, the given number of beats from a clock's current beat. |
| ts"(beats) | |
+------------+--------------------------------------------------------------------------------------------+
| "after_tim | A relative moment, the given amount of time from a clock's current time. |
| e"(time) | |
+------------+--------------------------------------------------------------------------------------------+
| "at_beat"( | An absolute moment at the given beat of a clock. |
| beat) | |
+------------+--------------------------------------------------------------------------------------------+
| "at_time"( | An absolute moment at the given time on a clock. |
| time) | |
+------------+--------------------------------------------------------------------------------------------+
| "beat_on"( | This (absolute) moment expressed as a beat of *clock*. |
| clock) | |
+------------+--------------------------------------------------------------------------------------------+
| "resolve"( | Pin this moment to an absolute one on the given clock. |
| clock) | |
+------------+--------------------------------------------------------------------------------------------+
| "scheduler | The scheduler-time at which this (absolute) moment occurs on *clock*. |
| _time"(clo | |
| ck) | |
+------------+--------------------------------------------------------------------------------------------+
classmethod at_beat(beat: float) -> Moment
An absolute moment at the given beat of a clock.
Parameters:
**beat** -- beat, counted from the clock's start
classmethod at_time(time: float) -> Moment
An absolute moment at the given time on a clock.
Parameters:
**time** -- time in seconds, counted from the clock's start
classmethod after_beats(beats: float) -> Moment
A relative moment, the given number of beats from a clock's
current beat.
Parameters:
**beats** -- how many beats from now
classmethod after_time(time: float) -> Moment
A relative moment, the given amount of time from a clock's
current time.
Parameters:
**time** -- how many seconds from now
resolve(clock: Clock) -> Moment
Pin this moment to an absolute one on the given clock. A no-op
if it is already absolute; a relative moment is measured out
from the clock's current beat or time.
Parameters:
**clock** -- the clock whose timeline the result is measured
against
Returns:
an absolute Moment on that clock
beat_on(clock: Clock) -> float
This (absolute) moment expressed as a beat of *clock*.
scheduler_time(clock: Clock) -> float
The scheduler-time at which this (absolute) moment occurs on
*clock*.
======================================================================
=== FILE: clockblocks/clockblocks.moment.ResolvableMoment.txt
======================================================================
clockblocks.moment.ResolvableMoment
***********************************
class clockblocks.moment.ResolvableMoment(*args, **kwargs)
Bases: "Protocol"
Anything that can name a point on a clock's timeline. The
scheduling layer (wait / wait_until / fork / schedule_action)
accepts any ResolvableMoment and calls resolve(clock) to pin it to
an absolute Moment on that clock. Moment and MetricPhaseTarget both
implement this.
-[ Methods ]-
+------------+--------------------------------------------------------------------------------------------+
| "resolve"( | Pin this to an absolute "Moment" on the given clock. |
| clock) | |
+------------+--------------------------------------------------------------------------------------------+
resolve(clock: Clock) -> Moment
Pin this to an absolute "Moment" on the given clock.
Parameters:
**clock** -- the clock whose timeline the result is measured
against
Returns:
an absolute Moment on that clock
======================================================================
=== FILE: clockblocks/clockblocks.moment.to_absolute_moment.txt
======================================================================
clockblocks.moment.to_absolute_moment
*************************************
clockblocks.moment.to_absolute_moment(when: float | ResolvableMoment | None, clock: Clock, *, units_if_number: str | DurationUnits = DurationUnits.BEATS, relative_if_number: bool = True, allow_number: bool = True) -> Moment
Coerce a *when* argument into an absolute Moment on *clock*. None
is treated as "now" (relative 0); anything that isn't None or a
number is assumed to be a ResolvableMoment and resolved.
A bare number is handled per *allow_number*: when True
(wait()/wait_until(), whose names fix the meaning) it is wrapped
using the caller's convention (*units_if_number* /
*relative_if_number*); when False (fork()/schedule_action(), where
"when" alone wouldn't say whether a number is relative or absolute)
a number raises TypeError, steering the caller to an explicit
Moment.
======================================================================
=== FILE: clockblocks/clockblocks.moment.txt
======================================================================
clockblocks.moment
******************
Module containing "Moment", which names a point on a clock's timeline,
and the "ResolvableMoment" protocol implemented by anything that can
be pinned to such a point.
-[ Classes ]-
+------------+--------------------------------------------------------------------------------------------+
| "Moment"(v | Represents a point on a clock's timeline. |
| alue[, | |
| units, | |
| relative]) | |
+------------+--------------------------------------------------------------------------------------------+
| "Resolvabl | Anything that can name a point on a clock's timeline. |
| eMoment"(* | |
| args, | |
| **kwargs) | |
+------------+--------------------------------------------------------------------------------------------+
* clockblocks.moment.Moment
* "Moment"
* "Moment.at_beat()"
* "Moment.at_time()"
* "Moment.after_beats()"
* "Moment.after_time()"
* "Moment.resolve()"
* "Moment.beat_on()"
* "Moment.scheduler_time()"
* clockblocks.moment.ResolvableMoment
* "ResolvableMoment"
* "ResolvableMoment.resolve()"
-[ Functions ]-
+------------+--------------------------------------------------------------------------------------------+
| "to_absolu | Coerce a *when* argument into an absolute Moment on *clock*. |
| te_moment" | |
| (when, | |
| clock, *[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
* clockblocks.moment.to_absolute_moment
* "to_absolute_moment()"
======================================================================
=== FILE: clockblocks/clockblocks.scheduler.CompressedTime.txt
======================================================================
clockblocks.scheduler.CompressedTime
************************************
class clockblocks.scheduler.CompressedTime(factor: float = 10.0)
Bases: "TimingBackend"
A "TimingBackend" that runs scaled real time: "now()" advances
"factor" times faster and the sleep condition's "wait()" divides
its timeout by "factor". A clock family on this backend runs
deterministically fast while cross-thread handshakes still happen
as usual.
Caveat: handshake / context-switch overhead is *not* compressed, so
a T-second wait costs roughly "T / factor + handshake_overhead".
Very large factors hit that floor and loosen achievable timing
tolerances (see "tests/README.md"). 10x is a good default.
-[ Methods ]-
+------------+--------------------------------------------------------------------------------------------+
| "get_sleep | A condition whose "wait()" shortens any timeout by "factor", so that sleeps in compressed |
| _condition | time take correspondingly less real time. |
| "() | |
+------------+--------------------------------------------------------------------------------------------+
| "now"() | Real time since this backend was created, scaled up by "factor". |
+------------+--------------------------------------------------------------------------------------------+
now() -> float
Real time since this backend was created, scaled up by "factor".
get_sleep_condition() -> Condition
A condition whose "wait()" shortens any timeout by "factor", so
that sleeps in compressed time take correspondingly less real
time.
======================================================================
=== FILE: clockblocks/clockblocks.scheduler.QueueEvent.txt
======================================================================
clockblocks.scheduler.QueueEvent
********************************
class clockblocks.scheduler.QueueEvent(t: float, priority: Tuple[int, ...], action: Callable[[], NoneType], metadata: Any = None)
Bases: "object"
-[ Attributes ]-
+------------+--------------------------------------------------------------------------------------------+
| "metadata" | |
+------------+--------------------------------------------------------------------------------------------+
| "t" | |
+------------+--------------------------------------------------------------------------------------------+
| "priority" | |
+------------+--------------------------------------------------------------------------------------------+
| "action" | |
+------------+--------------------------------------------------------------------------------------------+
t: float
priority: Tuple[int, ...]
action: Callable[[], None]
metadata: Any = None
======================================================================
=== FILE: clockblocks/clockblocks.scheduler.Scheduler.txt
======================================================================
clockblocks.scheduler.Scheduler
*******************************
class clockblocks.scheduler.Scheduler(timing_policy: float = 0.98, precise_timing: bool = False, spin_guard_duration: float = 0.0005, daemon: bool = True, time_backend: TimingBackend | None = None)
Bases: "Thread"
The background timing thread for one clock family. Internal: user
code need never touch it directly. Each master clock mints and owns
its own Scheduler, children share their master's, and the public
timing knobs are surfaced on "Clock" (e.g. "timing_policy", fast-
forward).
Runs a single loop over a time-ordered heap of events, sleeping
until the next is due and then firing it. Utilizes two locks for
concurrency safety: "_queue_change_condition", for anything that
touches the event Queue, and "_execution_lock" which is held
throughout an event's action. See inline commentary in "run()".
In the clock system each event wakes a clock and parks until the
user code runs up to its next "wait()". Tempo changes reschedule
pending events using "reschedule()", and killing a clock removes
them via "remove_events()".
Parameters:
* **timing_policy** -- Bounds how far each wait may deviate from
its nominal length in order to track the absolute schedule. 0
-> Absolute timing (cut/extend the wait as needed to match
ideal time since start). 1 -> Relative timing (wait exactly
the nominal delay, drift never corrected). 0.98 (default) -> a
wait may be compressed to 98% (or stretched to 102%) of its
nominal length to correct any accumulated drift.
* **precise_timing** -- When True, close the final approach to
each event with a busy-spin instead of resting on the
(jittery) OS wait timeout, hitting the event time to within
microseconds. Costs one core for at most "spin_guard_duration"
seconds per event — see "run()" STEP 1c.
* **spin_guard_duration** -- Width (seconds) of the busy-spin
guard band used when "precise_timing" is on. The coarse OS
wait stops this far short of the deadline and the remainder is
spun out. Default 500µs.
* **daemon** -- run as a daemon thread (the default) so it can't
keep the process alive on its own.
* **time_backend** -- The "TimingBackend" supplying "now" and
the sleep condition. Defaults to real "perf_counter" time;
tests pass "CompressedTime" to run faster.
-[ Methods ]-
+------------+--------------------------------------------------------------------------------------------+
| "held"() | Context manager that: 1) ensures that the scheduler is not executing scheduled actions — |
| | waiting if one is in flight, then preventing others from starting; 2) rouses the scheduler |
| | and updates its committed time to the current projected time. |
+------------+--------------------------------------------------------------------------------------------+
| "is_fast_f | Whether a fast-forward goal is currently set. |
| orwarding" | |
| () | |
+------------+--------------------------------------------------------------------------------------------+
| "kill"() | Stop the scheduler. |
+------------+--------------------------------------------------------------------------------------------+
| "lag"() | How far behind the absolute schedule the scheduler is currently running, in seconds: the |
| | real time that has elapsed minus the ideal time that should have elapsed. |
+------------+--------------------------------------------------------------------------------------------+
| "projected | A wall-clock-interpolated estimate of where the scheduler is *right now*, as opposed to |
| _time"() | "time", which returns the time of the last executed event. |
+------------+--------------------------------------------------------------------------------------------+
| "remove_ev | Remove all queued events that satisfy *matches(event)*. |
| ents"(matc | |
| hes) | |
+------------+--------------------------------------------------------------------------------------------+
| "reschedul | Walk the heap and recompute *t* for any event that satisfies *matches(event)*. |
| e"(matches | |
| , | |
| recompute) | |
+------------+--------------------------------------------------------------------------------------------+
| "run"() | Main scheduler loop: wait until the next queued action is due, then execute it, forever. |
+------------+--------------------------------------------------------------------------------------------+
| "schedule_ | Schedule the given action to be executed at time 't' (in seconds since scheduler start). |
| action"(t, | |
| action[, | |
| priority, | |
| metadata]) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_fast_ | Set the fast-forward goal (a scheduler-time, float('inf') for indefinite, or None to stop) |
| forward_go | and wake the run loop so it acts on the change immediately rather than after its current |
| al"(goal) | timed wait. |
+------------+--------------------------------------------------------------------------------------------+
| "wall_time | Return the actual time elapsed on the schedule. |
| "() | |
+------------+--------------------------------------------------------------------------------------------+
-[ Inherited Methods ]-
+------------+--------------------------------------------------------------------------------------------+
| "getName"( | Return a string used for identification purposes only. |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "isDaemon" | Return whether this thread is a daemon. |
| () | |
+------------+--------------------------------------------------------------------------------------------+
| "is_alive" | Return whether the thread is alive. |
| () | |
+------------+--------------------------------------------------------------------------------------------+
| "join"([ti | Wait until the thread terminates. |
| meout]) | |
+------------+--------------------------------------------------------------------------------------------+
| "setDaemon | Set whether this thread is a daemon. |
| "(daemonic | |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "setName"( | Set the name string for this thread. |
| name) | |
+------------+--------------------------------------------------------------------------------------------+
| "start"() | Start the thread's activity. |
+------------+--------------------------------------------------------------------------------------------+
-[ Attributes ]-
+------------+--------------------------------------------------------------------------------------------+
| "daemon" | A boolean value indicating whether this thread is a daemon thread. |
+------------+--------------------------------------------------------------------------------------------+
| "ident" | Thread identifier of this thread or None if it has not been started. |
+------------+--------------------------------------------------------------------------------------------+
| "name" | A string used for identification purposes only. |
+------------+--------------------------------------------------------------------------------------------+
| "native_id | Native integral thread ID of this thread, or None if it has not been started. |
| " | |
+------------+--------------------------------------------------------------------------------------------+
| "time" | The scheduler's ideal time (the time that should have passed by schedule). |
+------------+--------------------------------------------------------------------------------------------+
property time: float
The scheduler's ideal time (the time that should have passed by
schedule).
This is *event-quantized*, not wall-clock-interpolated: it is
bumped to each event's scheduled time as that event executes
(see "_execute_event()"), so between events it holds the most
recently executed event's time. See "time" for what that means
for reads taken between events / from other threads.
Deterministic, hence a read-only property; for a smoothly-
advancing wall-clock *sample* of the position between events,
see "projected_time()".
projected_time() -> float
A wall-clock-interpolated estimate of where the scheduler is
*right now*, as opposed to "time", which returns the time of the
last executed event.
Between events, "time" stays put while real time passes; this
fills the gap by interpolating from the last event toward the
next, so continuous readers (e.g. parameter automation) see
smooth motion. The estimate depends on "timing_policy", which
decides when the next event is planned to arrive.
This is an estimate, and not monotonic. It resets on deliberate
schedule changes (a fast-forward, a live *timing_policy*
retune), and booking an event below the current projection pulls
it back to that event. (This kind of makes sense, since the
free-climb overshot a point where something needed to happen.)
In both cases the cause of the backward step is that we are
collapsing the gap between a stale committed time and an overly
optimistic projected time.
To avoid this issue entirely, use the "held()" context manager,
which first rouses the scheduler to the projected position.
Refer to "diagrams/projectedTimeExplanation" for how this
resolves under the various scenarios (ahead of schedule, behind,
empty queue, etc.).
wall_time() -> float
Return the actual time elapsed on the schedule. Returns 0 until
timing is anchored by the first event that requires a real wait
(see "run()"), then advances in real time. Also resets to ideal
time after fast-forwarding, erasing any prior lag.
Measured through the "TimingBackend", which defaults to
"time.perf_counter". *perf_counter* is monotonic and high-
resolution, so this is true elapsed real time, never affected by
NTP corrections (slews or steps) to CLOCK_REALTIME. Under a
compressed backend it is scaled in step with everything else.
lag() -> float
How far behind the absolute schedule the scheduler is currently
running, in seconds: the real time that has elapsed minus the
ideal time that should have elapsed.
Positive means events are firing late. It grows when an event's
action takes longer than the gap to the next event, and (under a
relative timing policy) is allowed to persist rather than being
chased down. Fast-forwarding resets it to zero, since
"_reanchor_timing()" re-anchors "_start_time" to put us exactly
on the absolute schedule.
set_fast_forward_goal(goal: float | None) -> None
Set the fast-forward goal (a scheduler-time, float('inf') for
indefinite, or None to stop) and wake the run loop so it acts on
the change immediately rather than after its current timed wait.
is_fast_forwarding() -> bool
Whether a fast-forward goal is currently set.
kill() -> None
Stop the scheduler.
held()
Context manager that: 1) ensures that the scheduler is not
executing scheduled actions — waiting if one is in flight, then
preventing others from starting; 2) rouses the scheduler and
updates its committed time to the current projected time. Code
under this context manager therefore acts like an immediately
scheduled action, holding exclusive access to an up-to-date
scheduler.
Implemented by taking *_execution_lock*, which the run loop
holds for the full duration of each action. So don't call this
from within a scheduled action: you'd block waiting for that
action to finish, but it can't finish while it's stuck waiting
here.
In the context of the clock system, this context manager should
be used any time you want to take clock-related actions from a
non-clock thread. However, since it's implemented by taking the
same *_execution_lock* held during scheduled actions, it should
never be used *within* a scheduled action: the action would
block waiting for itself to finish. For this reason we have
"hold_scheduler()", which safely wraps this method by detecting
whether we are running from a clock and no-op'ing in that case.
remove_events(matches: Callable[[QueueEvent], bool]) -> int
Remove all queued events that satisfy *matches(event)*. Returns
the number removed. Used when a clock is killed and its pending
wakeups (and pending forks) need to be cancelled.
reschedule(matches: Callable[[QueueEvent], bool], recompute: Callable[[QueueEvent], float]) -> None
Walk the heap and recompute *t* for any event that satisfies
*matches(event)*. Used when a tempo change makes previously-
scheduled wakeups stale.
schedule_action(t: float, action: Callable, priority: Tuple[int, ...] = (0,), metadata: Any = None) -> None
Schedule the given action to be executed at time 't' (in seconds
since scheduler start).
run() -> None
Main scheduler loop: wait until the next queued action is due,
then execute it, forever.
The two subtle parts — how the wait is structured around
*_queue_change_condition* so a queue change can't be lost, and
why execution is wrapped in *_execution_lock* — are explained
inline at STEP 1 and STEP 2 below.
Note that the clock starts in an unanchored state (*_start_time
= _last_event_time = None*) This is intentional: we don't want
the code that runs before the first future action is scheduled
(which can be lengthy initial setup) to cause us to start off
way behind schedule. The timing is anchored (via
*_reanchor_timing*) when the first future event is pulled from
the queue.
property daemon
A boolean value indicating whether this thread is a daemon
thread.
This must be set before start() is called, otherwise
RuntimeError is raised. Its initial value is inherited from the
creating thread; the main thread is not a daemon thread and
therefore all threads created in the main thread default to
daemon = False.
The entire Python program exits when only daemon threads are
left.
getName()
Return a string used for identification purposes only.
This method is deprecated, use the name attribute instead.
property ident
Thread identifier of this thread or None if it has not been
started.
This is a nonzero integer. See the get_ident() function. Thread
identifiers may be recycled when a thread exits and another
thread is created. The identifier is available even after the
thread has exited.
isDaemon()
Return whether this thread is a daemon.
This method is deprecated, use the daemon attribute instead.
is_alive()
Return whether the thread is alive.
This method returns True just before the run() method starts
until just after the run() method terminates. See also the
module function enumerate().
join(timeout=None)
Wait until the thread terminates.
This blocks the calling thread until the thread whose join()
method is called terminates -- either normally or through an
unhandled exception or until the optional timeout occurs.
When the timeout argument is present and not None, it should be
a floating point number specifying a timeout for the operation
in seconds (or fractions thereof). As join() always returns
None, you must call is_alive() after join() to decide whether a
timeout happened -- if the thread is still alive, the join()
call timed out.
When the timeout argument is not present or None, the operation
will block until the thread terminates.
A thread can be join()ed many times.
join() raises a RuntimeError if an attempt is made to join the
current thread as that would cause a deadlock. It is also an
error to join() a thread before it has been started and attempts
to do so raises the same exception.
property name
A string used for identification purposes only.
It has no semantics. Multiple threads may be given the same
name. The initial name is set by the constructor.
property native_id
Native integral thread ID of this thread, or None if it has not
been started.
This is a non-negative integer. See the get_native_id()
function. This represents the Thread ID as reported by the
kernel.
setDaemon(daemonic)
Set whether this thread is a daemon.
This method is deprecated, use the .daemon property instead.
setName(name)
Set the name string for this thread.
This method is deprecated, use the name attribute instead.
start()
Start the thread's activity.
It must be called at most once per thread object. It arranges
for the object's run() method to be invoked in a separate thread
of control.
This method will raise a RuntimeError if called more than once
on the same thread object.
======================================================================
=== FILE: clockblocks/clockblocks.scheduler.TimingBackend.txt
======================================================================
clockblocks.scheduler.TimingBackend
***********************************
class clockblocks.scheduler.TimingBackend
Bases: "object"
The scheduler's pluggable source of "now" and of the condition it
uses for waiting.
The scheduler (and therefore an entire clock family) has exactly
one timed sleep — the run loop's wait on "_queue_change_condition"
(see "Scheduler.run()" STEP 1c). That condition is sourced from the
TimingBackend passed in the constructor, and defaults to a regular
condition on a plain lock. Similarly, all timing reads within the
scheduler run through timing_backend.now(). The backend therefore
defines both how time is perceived and how the scheduler waits.
See "CompressedTime" for a backend used to run fast deterministic
tests.
-[ Methods ]-
+------------+--------------------------------------------------------------------------------------------+
| "get_sleep | A fresh condition variable for the scheduler's run loop to wait on. |
| _condition | |
| "() | |
+------------+--------------------------------------------------------------------------------------------+
| "now"() | The backend's current time, in seconds. |
+------------+--------------------------------------------------------------------------------------------+
now() -> float
The backend's current time, in seconds. Only differences between
readings are meaningful; the origin is arbitrary.
get_sleep_condition() -> Condition
A fresh condition variable for the scheduler's run loop to wait
on. Timeouts passed to its "wait()" are interpreted in the same
units "now()" returns.
======================================================================
=== FILE: clockblocks/clockblocks.scheduler.txt
======================================================================
clockblocks.scheduler
*********************
Module containing the "Scheduler", the single background thread that
drives an entire clock family: it holds a queue of upcoming events,
sleeps until the next one is due, and wakes the clocks waiting on
them. Also contains the "TimingBackend" that supplies the scheduler's
notion of "now" and how it sleeps, along with "CompressedTime", a
backend that makes a clock family run in scaled-down real time.
(Currently used for testing purposes.)
-[ Classes ]-
+------------+--------------------------------------------------------------------------------------------+
| "Compresse | A "TimingBackend" that runs scaled real time: "now()" advances "factor" times faster and |
| dTime"([fa | the sleep condition's "wait()" divides its timeout by "factor". |
| ctor]) | |
+------------+--------------------------------------------------------------------------------------------+
| "QueueEven | |
| t"(t, | |
| priority, | |
| action[, | |
| metadata]) | |
+------------+--------------------------------------------------------------------------------------------+
| "Scheduler | The background timing thread for one clock family. |
| "([timing_ | |
| policy, pr | |
| ecise_timi | |
| ng, ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "TimingBac | The scheduler's pluggable source of "now" and of the condition it uses for waiting. |
| kend"() | |
+------------+--------------------------------------------------------------------------------------------+
* clockblocks.scheduler.CompressedTime
* "CompressedTime"
* "CompressedTime.now()"
* "CompressedTime.get_sleep_condition()"
* clockblocks.scheduler.QueueEvent
* "QueueEvent"
* "QueueEvent.t"
* "QueueEvent.priority"
* "QueueEvent.action"
* "QueueEvent.metadata"
* clockblocks.scheduler.Scheduler
* "Scheduler"
* "Scheduler.time"
* "Scheduler.projected_time()"
* "Scheduler.wall_time()"
* "Scheduler.lag()"
* "Scheduler.set_fast_forward_goal()"
* "Scheduler.is_fast_forwarding()"
* "Scheduler.kill()"
* "Scheduler.held()"
* "Scheduler.remove_events()"
* "Scheduler.reschedule()"
* "Scheduler.schedule_action()"
* "Scheduler.run()"
* "Scheduler.daemon"
* "Scheduler.getName()"
* "Scheduler.ident"
* "Scheduler.isDaemon()"
* "Scheduler.is_alive()"
* "Scheduler.join()"
* "Scheduler.name"
* "Scheduler.native_id"
* "Scheduler.setDaemon()"
* "Scheduler.setName()"
* "Scheduler.start()"
* clockblocks.scheduler.TimingBackend
* "TimingBackend"
* "TimingBackend.now()"
* "TimingBackend.get_sleep_condition()"
======================================================================
=== FILE: clockblocks/clockblocks.tempo_envelope.EnvelopeLoopInfo.txt
======================================================================
clockblocks.tempo_envelope.EnvelopeLoopInfo
*******************************************
class clockblocks.tempo_envelope.EnvelopeLoopInfo(env: TempoEnvelope, length_in_beats: float, length_in_time: float, current_end_beat: float, current_end_time: float)
Bases: "object"
Internal bookkeeping for a tempo envelope set to loop: the envelope
being repeated plus the running beat/time extents needed to keep
appending copies as the clock advances.
-[ Attributes ]-
+------------+--------------------------------------------------------------------------------------------+
| "env" | |
+------------+--------------------------------------------------------------------------------------------+
| "length_in | |
| _beats" | |
+------------+--------------------------------------------------------------------------------------------+
| "length_in | |
| _time" | |
+------------+--------------------------------------------------------------------------------------------+
| "current_e | |
| nd_beat" | |
+------------+--------------------------------------------------------------------------------------------+
| "current_e | |
| nd_time" | |
+------------+--------------------------------------------------------------------------------------------+
env: TempoEnvelope
length_in_beats: float
length_in_time: float
current_end_beat: float
current_end_time: float
======================================================================
=== FILE: clockblocks/clockblocks.tempo_envelope.FunctionFollowInfo.txt
======================================================================
clockblocks.tempo_envelope.FunctionFollowInfo
*********************************************
class clockblocks.tempo_envelope.FunctionFollowInfo(func: Callable[[float], float], next_domain_start: float, extension_increment: float, units: TempoUnits, duration_units: DurationUnits, scanning_step_size: float, min_key_point_distance: float, iterations: int, key_point_resolution_multiple: int, current_end_beat: float, current_end_time: float)
Bases: "object"
Internal bookkeeping for a tempo curve that follows a user
function: the function itself plus the state needed to keep
extending the envelope to approximate it as the clock advances.
-[ Attributes ]-
+------------+--------------------------------------------------------------------------------------------+
| "func" | |
+------------+--------------------------------------------------------------------------------------------+
| "next_doma | |
| in_start" | |
+------------+--------------------------------------------------------------------------------------------+
| "extension | |
| _increment | |
| " | |
+------------+--------------------------------------------------------------------------------------------+
| "units" | |
+------------+--------------------------------------------------------------------------------------------+
| "duration_ | |
| units" | |
+------------+--------------------------------------------------------------------------------------------+
| "scanning_ | |
| step_size" | |
+------------+--------------------------------------------------------------------------------------------+
| "min_key_p | |
| oint_dista | |
| nce" | |
+------------+--------------------------------------------------------------------------------------------+
| "iteration | |
| s" | |
+------------+--------------------------------------------------------------------------------------------+
| "key_point | |
| _resolutio | |
| n_multiple | |
| " | |
+------------+--------------------------------------------------------------------------------------------+
| "current_e | |
| nd_beat" | |
+------------+--------------------------------------------------------------------------------------------+
| "current_e | |
| nd_time" | |
+------------+--------------------------------------------------------------------------------------------+
func: Callable[[float], float]
next_domain_start: float
extension_increment: float
units: TempoUnits
duration_units: DurationUnits
scanning_step_size: float
min_key_point_distance: float
iterations: int
key_point_resolution_multiple: int
current_end_beat: float
current_end_time: float
======================================================================
=== FILE: clockblocks/clockblocks.tempo_envelope.TempoEnvelope.txt
======================================================================
clockblocks.tempo_envelope.TempoEnvelope
****************************************
class clockblocks.tempo_envelope.TempoEnvelope(levels: float | Sequence[float] = (60,), durations: Sequence[float] = (), curve_shapes: Sequence[float | str] = None, units: str = 'tempo', duration_units: str = 'beats')
Bases: "Envelope"
A subclass of "Envelope" that is specifically designed for
representing changing tempo curves. The underlying envelope
represents beat length as a function of the current beat, which
means that the area under the curve represents how much time should
pass from one beat to the next (beats * sec/beat = sec). Although
the methods take a "units" argument, which can be "beatlength",
"tempo", or "rate", these are always converted to beat length in
the underlying representation
Parameters:
* **levels** -- levels of the curve segments (i.e. tempo values)
in the units specified by the *units* argument
* **durations** -- durations of the curve segments in the units
specified by the *duration_units* argument
* **curve_shapes** -- see "from_levels_and_durations()"
* **units** -- one of "tempo", "rate" or "beat length",
determining how we interpret the levels given
* **duration_units** -- either "beats" or "time", determining
how we interpret the durations given
-[ Methods ]-
+------------+--------------------------------------------------------------------------------------------+
| "beat_at_t | Determine the beat at the given time, measured from time 0. |
| ime"(t) | |
+------------+--------------------------------------------------------------------------------------------+
| "beat_leng | Get the beat length at the given beat. |
| th_at"(bea | |
| t[, from_l | |
| eft]) | |
+------------+--------------------------------------------------------------------------------------------+
| "convert_d | Warps this tempo_curve so that all the locations of key points get re-interpreted as times |
| urations_t | instead of beat locations. |
| o_times"() | |
+------------+--------------------------------------------------------------------------------------------+
| "convert_u | Utility method to convert values between unites of tempo, rate and beat length. |
| nits"(valu | |
| es, input_ | |
| units, out | |
| put_units) | |
+------------+--------------------------------------------------------------------------------------------+
| "extend_to | Extends the end of this TempoEnvelope to the given beat (if needed) by adding a constant |
| "(beat) | segment at the end. |
+------------+--------------------------------------------------------------------------------------------+
| "from_func | Constructs a TempoEnvelope that approximates an arbitrary function. |
| tion"(func | |
| tion[, dom | |
| ain_start, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "from_leve | Constructs a TempoEnvelope from the given levels and total length, using the specified |
| ls"(levels | units. |
| [, length, | |
| units, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "from_leve | Constructs a TempoEnvelope from the given levels, durations and curve shapes, using the |
| ls_and_dur | specified units. |
| ations"([l | |
| evels, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "from_list | Construct a TempoEnvelope from a list that can take a number of formats |
| "(construc | |
| tor_list[, | |
| units, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "from_poin | Construct an envelope from a list of (beat/time, tempo/rate/beat length) pairs. |
| ts"(*point | |
| s[, units, | |
| duration_u | |
| nits]) | |
+------------+--------------------------------------------------------------------------------------------+
| "is_defaul | True if this is the trivial default tempo — a constant 60 bpm (rate 1.0) with no duration, |
| t"() | i.e. structurally identical to a freshly- constructed "TempoEnvelope()". |
+------------+--------------------------------------------------------------------------------------------+
| "rate_at"( | Get the beat rate (in beats/second) at the given beat. |
| beat[, fro | |
| m_left]) | |
+------------+--------------------------------------------------------------------------------------------+
| "show_plot | Shows a plot of this TempoEnvelope using matplotlib. |
| "([title, | |
| resolution | |
| , ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "tempo_at" | Get the tempo (in beats/minute) at the given beat. |
| (beat[, fr | |
| om_left]) | |
+------------+--------------------------------------------------------------------------------------------+
| "time_at_b | Determine the time at the given beat by integrating the beat-length curve from beat 0 |
| eat"(beat) | (seconds/beat * beats = seconds). |
+------------+--------------------------------------------------------------------------------------------+
| "truncate_ | Removes all segments after the given beat and adds a constant segment if necessary to |
| at"(beat) | bring us up to that beat. |
+------------+--------------------------------------------------------------------------------------------+
-[ Inherited Methods ]-
+------------+--------------------------------------------------------------------------------------------+
| "adsr"(att | Construct a standard attack/decay/sustain/release envelope |
| ack_length | |
| , attack_l | |
| evel, | |
| ...[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "append_en | Extends this envelope by another one (shifted to start at the end of this one). |
| velope"(en | |
| velope_to_ | |
| append) | |
+------------+--------------------------------------------------------------------------------------------+
| "append_se | Append a segment to the end of the curve ending at level and lasting for duration. |
| gment"(lev | |
| el, | |
| duration[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "ar"(attac | Construct an attack/release envelope |
| k_length, | |
| release_le | |
| ngth[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "asr"(atta | Construct an attack/sustain/release envelope |
| ck_length, | |
| sustain_le | |
| vel, ...[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "average_l | Returns the average value that the Envelope takes over the given range. |
| evel"([t_r | |
| ange]) | |
+------------+--------------------------------------------------------------------------------------------+
| "duplicate | Returns a copy of this object by serializing to and from JSON. |
| "() | |
+------------+--------------------------------------------------------------------------------------------+
| "end_level | Ending value of the Envelope |
| "() | |
+------------+--------------------------------------------------------------------------------------------+
| "end_time" | End of the domain on which this Envelope is defined. |
| () | |
+------------+--------------------------------------------------------------------------------------------+
| "from_segm | Create a new envelope from a list of "EnvelopeSegment"s. |
| ents"(segm | |
| ents) | |
+------------+--------------------------------------------------------------------------------------------+
| "get_durat | Tuple of all the segment lengths. |
| ions"([rou | |
| nded]) | |
+------------+--------------------------------------------------------------------------------------------+
| "get_upper | Given a lower integration bound, find the upper bound that will result in the desired |
| _integrati | integral. |
| on_bound"( | |
| t1, desire | |
| d_area) | |
+------------+--------------------------------------------------------------------------------------------+
| "insert"(t | Insert a curve point at time t, and set the shape of the curve into and out of it. |
| , level[, | |
| curve_shap | |
| e_in, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "insert_in | Insert another curve point at the given time, without changing the shape of the curve. |
| terpolated | |
| "(t[, rela | |
| tive_toler | |
| ance]) | |
+------------+--------------------------------------------------------------------------------------------+
| "integrate | Get the definite integral under this Envelope from t1 to t2 |
| _interval" | |
| (t1, t2) | |
+------------+--------------------------------------------------------------------------------------------+
| "is_shifte | Determines if this segment is simply a shifted version of another segment |
| d_version_ | |
| of"(other[ | |
| , toleranc | |
| e]) | |
+------------+--------------------------------------------------------------------------------------------+
| "json_dump | Dump this object as a JSON string. |
| s"() | |
+------------+--------------------------------------------------------------------------------------------+
| "json_load | Load this object from a JSON string. |
| s"(s) | |
+------------+--------------------------------------------------------------------------------------------+
| "length"() | The length of the domain on which this Envelope is defined (end time minus start time). |
+------------+--------------------------------------------------------------------------------------------+
| "load_from | Load this object from a JSON file with the given path. |
| _json"(fil | |
| e_path) | |
+------------+--------------------------------------------------------------------------------------------+
| "local_ext | Returns a list of the times where the curve changes direction. |
| rema"([inc | |
| lude_saddl | |
| e_points]) | |
+------------+--------------------------------------------------------------------------------------------+
| "max_absol | Returns the maximum absolute value of the slope over the entire Envelope. |
| ute_slope" | |
| () | |
+------------+--------------------------------------------------------------------------------------------+
| "max_level | Returns the highest value that the Envelope takes over the given range. |
| "([t_range | |
| ]) | |
+------------+--------------------------------------------------------------------------------------------+
| "min_level | Returns the lowest value that the Envelope takes over the given range. |
| "([t_range | |
| ]) | |
+------------+--------------------------------------------------------------------------------------------+
| "normalize | Stretch or squeeze the segments of this Envelope so that it has the desired total |
| _to_durati | duration. |
| on"(desire | |
| d_duration | |
| [, ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "pop_segme | Remove and return the last segment of this Envelope. |
| nt"() | |
+------------+--------------------------------------------------------------------------------------------+
| "pop_segme | Remove and return the first segment of this Envelope. |
| nt_from_st | |
| art"() | |
+------------+--------------------------------------------------------------------------------------------+
| "prepend_e | Extends this envelope backwards by another one (shifted to end at the start of this one). |
| nvelope"(e | |
| nvelope_to | |
| _prepend) | |
+------------+--------------------------------------------------------------------------------------------+
| "prepend_s | Prepend a segment to the beginning of the curve, starting at level and lasting for |
| egment"(le | duration. |
| vel, | |
| duration[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "release"( | Construct an simple decaying envelope |
| duration[, | |
| start_leve | |
| l, curve_s | |
| hape]) | |
+------------+--------------------------------------------------------------------------------------------+
| "remove_se | Removes all segments after the given time (including a partial segment if t lands in the |
| gments_aft | middle of a segment). |
| er"(t) | |
+------------+--------------------------------------------------------------------------------------------+
| "remove_se | Removes all segments before the given time (including a partial segment if t lands in the |
| gments_bef | middle of a segment). |
| ore"(t) | |
+------------+--------------------------------------------------------------------------------------------+
| "save_to_j | Save this object to a JSON file using the given path. |
| son"(file_ | |
| path) | |
+------------+--------------------------------------------------------------------------------------------+
| "scale_hor | Scales the domain of this Envelope by the specified amount. |
| izontal"(a | |
| mount) | |
+------------+--------------------------------------------------------------------------------------------+
| "scale_ver | Scales the levels of this segment by the specified amount. |
| tical"(amo | |
| unt) | |
+------------+--------------------------------------------------------------------------------------------+
| "shift_hor | Shifts the domain of this Envelope by the specified amount. |
| izontal"(a | |
| mount) | |
+------------+--------------------------------------------------------------------------------------------+
| "shift_ver | Shifts the levels of this Envelope the specified amount. |
| tical"(amo | |
| unt) | |
+------------+--------------------------------------------------------------------------------------------+
| "simplifie | Simplifies the envelope to only extrema and inflection points. |
| d"([use_cu | |
| rvature, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "split_at" | Splits the Envelope at one or several points and returns a tuple of the pieces |
| (t[, chang | |
| e_original | |
| , zero_out | |
| _offsets]) | |
+------------+--------------------------------------------------------------------------------------------+
| "start_lev | Beginning value of the Envelope |
| el"() | |
+------------+--------------------------------------------------------------------------------------------+
| "start_tim | Beginning of the domain on which this Envelope is defined. |
| e"() | |
+------------+--------------------------------------------------------------------------------------------+
| "value_at" | Get the value of this Envelope at the given time. |
| (t[, from_ | |
| left]) | |
+------------+--------------------------------------------------------------------------------------------+
-[ Attributes ]-
+------------+--------------------------------------------------------------------------------------------+
| "curve_sha | Tuple of all the segment curve shapes. |
| pes" | |
+------------+--------------------------------------------------------------------------------------------+
| "durations | Tuple of all the segment lengths. |
| " | |
+------------+--------------------------------------------------------------------------------------------+
| "levels" | Tuple of levels at all segment boundary points. |
+------------+--------------------------------------------------------------------------------------------+
| "offset" | Alias for "Envelope.start_time()". |
+------------+--------------------------------------------------------------------------------------------+
| "times" | Tuple of all the segment start times. |
+------------+--------------------------------------------------------------------------------------------+
classmethod from_levels_and_durations(levels: Sequence = (0, 0), durations: Sequence[float] = (0,), curve_shapes: Sequence[float | str] = None, units: str = 'tempo', duration_units: str = 'beats') -> TempoEnvelope
Constructs a TempoEnvelope from the given levels, durations and
curve shapes, using the specified units.
Parameters:
* **levels** -- levels of the curve segments (i.e. tempo
values) in the units specified by the *units* argument
* **durations** -- durations of the curve segments in the
units specified by the *duration_units* argument
* **curve_shapes** -- see "from_levels_and_durations()"
* **units** -- one of "tempo", "rate" or "beat length",
determining how we interpret the levels given
* **duration_units** -- either "beats" or "time", determining
how we interpret the durations given
Returns:
a TempoEnvelope, constructed accordingly
classmethod from_levels(levels: Sequence[float], length: float = 1.0, units: str = 'tempo', duration_units: str = 'beats') -> TempoEnvelope
Constructs a TempoEnvelope from the given levels and total
length, using the specified units.
Parameters:
* **levels** -- levels of the curve segments (i.e. tempo
values) in the units specified by the *units* argument
* **length** -- total length of the tempo curve, in the units
specified by the *duration_units* argument
* **units** -- one of "tempo", "rate" or "beat length",
determining how we interpret the levels given
* **duration_units** -- either "beats" or "time", determining
how we interpret the durations given
Returns:
a TempoEnvelope, constructed accordingly
classmethod from_list(constructor_list: Sequence, units: str = 'tempo', duration_units: str = 'beats') -> TempoEnvelope
Construct a TempoEnvelope from a list that can take a number of
formats
Parameters:
* **constructor_list** -- see "from_list()"
* **units** -- one of "tempo", "rate" or "beat length",
determining how we interpret the levels given
* **duration_units** -- either "beats" or "time", determining
how we interpret the durations given
Returns:
a TempoEnvelope, constructed accordingly
classmethod from_points(*points, units: str = 'tempo', duration_units: str = 'beats') -> TempoEnvelope
Construct an envelope from a list of (beat/time, tempo/rate/beat
length) pairs. Units are defined by the *units* and
*duration_units* parameters.
Parameters:
* **points** -- list of points, each of which is of the form
(time, value) or (time, value, curve_shape)
* **units** -- one of "tempo", "rate" or "beat length",
determining how we interpret the tempo values
* **duration_units** -- either "beats" or "time", determining
how we interpret the time values
Returns:
a TempoEnvelope, constructed accordingly
classmethod from_function(function, domain_start=0, domain_end=1, units: str = 'tempo', duration_units: str = 'beats', scanning_step_size: float = 0.05, key_point_resolution_multiple: int = 2, iterations: int = 6, min_key_point_distance: float = 1e-07) -> TempoEnvelope
Constructs a TempoEnvelope that approximates an arbitrary
function. The domain of the function is in units defined by the
*duration_units* parameter, and the range is in units defined by
the *units* parameter.
Parameters:
* **function** -- A function from beat/time to
tempo/rate/beat length, as defined by the *duration_units*
and *units* parameters.
* **domain_start** -- see "from_function()"
* **domain_end** -- see "from_function()"
* **units** -- one of "tempo", "rate" or "beat length",
determining how we interpret the function output
* **duration_units** -- either "beats" or "time", determining
how we interpret the function input
* **scanning_step_size** -- when analyzing the function for
discontinuities, maxima and minima, inflection points,
etc., use this step size for the initial pass.
* **key_point_resolution_multiple** -- factor by which we add
extra key points between the extrema and inflection points
to improve the curve fit.
* **iterations** -- when a potential key point is found, we
zoom in and scan again in the viscinity of the point. This
determines how many iterations of zooming we do.
* **min_key_point_distance** -- after scanning for key
points, any that are closer than this distance are merged.
Returns:
a TempoEnvelope, constructed accordingly
beat_length_at(beat: float, from_left: bool = False) -> float
Get the beat length at the given beat. If the beat length jumps
at the given beat, the default is to return the beat length
after the jump, though this can be overridden with the
*from_left* argument.
Parameters:
* **beat** -- the beat at which to get the beat length
* **from_left** -- whether to evaluate from the right or
left-hand side of the beat in question
rate_at(beat: float, from_left: bool = False) -> float
Get the beat rate (in beats/second) at the given beat. If the
rate jumps at the given beat, the default is to return the rate
after the jump, though this can be overridden with the
*from_left* argument.
Parameters:
* **beat** -- the beat at which to get the rate
* **from_left** -- whether to evaluate from the right or
left-hand side of the beat in question
tempo_at(beat: float, from_left: bool = False) -> float
Get the tempo (in beats/minute) at the given beat. If the tempo
jumps at the given beat, the default is to return the tempo
after the jump, though this can be overridden with the
*from_left* argument.
Parameters:
* **beat** -- the beat at which to get the tempo
* **from_left** -- whether to evaluate from the right or
left-hand side of the beat in question
extend_to(beat: float) -> TempoEnvelope
Extends the end of this TempoEnvelope to the given beat (if
needed) by adding a constant segment at the end.
truncate_at(beat: float) -> TempoEnvelope
Removes all segments after the given beat and adds a constant
segment if necessary to bring us up to that beat.
Parameters:
**beat** -- the beat that we are truncating the tempo
envelope after
Returns:
self, for chaining purposes
static convert_units(values: float | Sequence[float], input_units: str, output_units: str) -> float | Sequence[float]
Utility method to convert values between unites of tempo, rate
and beat length.
Parameters:
* **values** -- value or list of values in terms of the
input_units
* **input_units** -- current units of the given values
(either "tempo", "rate", or "beat length")
* **output_units** -- desired units to convert to (either
"tempo", "rate", or "beat length")
Returns:
the list of values, converted to output units
convert_durations_to_times()
Warps this tempo_curve so that all the locations of key points
get re-interpreted as times instead of beat locations. For
instance, a tempo curve where the rate hovers around 2 will see
a segment of length 3 get stretched into a segment of length 6,
since if it's supposed to take 3 seconds, it would take 6 beats.
Pretty confusing, but when we want to construct a tempo curve
specifying the *times* that changes occur rather than the beats,
we can first construct it as though the durations were in beats,
then call this function to warp it so that the durations are in
time.
Returns:
self, altered accordingly
show_plot(title=None, resolution=25, show_segment_divisions=True, units='tempo', x_range=None, y_range=None)
Shows a plot of this TempoEnvelope using matplotlib.
Parameters:
* **title** -- A title to give the plot.
* **resolution** -- number of points to use per envelope
segment
* **show_segment_divisions** -- Whether to place dots at the
division points between envelope segments
* **units** -- one of "tempo", "rate" or "beat length",
determining the units of the y-axis
* **x_range** -- min and max value shown on the x-axis
* **y_range** -- min and max value shown on the y-axis
is_default() -> bool
True if this is the trivial default tempo — a constant 60 bpm
(rate 1.0) with no duration, i.e. structurally identical to a
freshly-constructed "TempoEnvelope()". (Note this is stricter
than "functionally constant at 60": a flat-60 envelope that
carries a real duration or extra segments is *not* default (and
worth surfacing for debugging)
time_at_beat(beat: float) -> float
Determine the time at the given beat by integrating the beat-
length curve from beat 0 (seconds/beat * beats = seconds).
Parameters:
**beat** -- the beat at which to calculate the time
beat_at_time(t: float) -> float
Determine the beat at the given time, measured from time 0. This
is the inverse of "time_at_beat()".
Parameters:
**t** -- the time at which to calculate the beat
classmethod adsr(attack_length: float, attack_level, decay_length: float, sustain_level, sustain_length: float, release_length: float, attack_shape: float | str = None, decay_shape: float | str = None, release_shape: float | str = None) -> T
Construct a standard attack/decay/sustain/release envelope
Parameters:
* **attack_length** -- rise time
* **attack_level** -- level reached after attack before decay
* **decay_length** -- length of decay portion of the curve
* **sustain_level** -- sustain level reached after decay and
before release
* **sustain_length** -- length of sustain portion of curve
* **release_length** -- release time
* **attack_shape** -- sets curve shape for attack portion of
the curve (see documentation for
"Envelope.from_levels_and_durations()")
* **decay_shape** -- sets curve shape for decay portion of
the curve (see documentation for
"Envelope.from_levels_and_durations()")
* **release_shape** -- sets curve shape for release portion
of the curve (see documentation for
"Envelope.from_levels_and_durations()")
Returns:
an Envelope constructed accordingly
append_envelope(envelope_to_append: T) -> T
Extends this envelope by another one (shifted to start at the
end of this one).
append_segment(level, duration: float, curve_shape: float = None, tolerance: float = 0, halfway_level=None) -> None
Append a segment to the end of the curve ending at level and
lasting for duration. If we're adding a linear segment to a
linear segment, then we extend the last linear segment instead
of adding a new one if the level is within tolerance of where
the last one was headed
Parameters:
* **level** -- the level we're going to
* **duration** -- the duration of the new segment
* **curve_shape** -- defaults to 0 (linear)
* **tolerance** -- tolerance for extending a linear segment
rather than adding a new one
* **halfway_level** -- alternate way of defining the curve
shape. If this is set and the curve shape is not then we
use this to determine the curve shape.
classmethod ar(attack_length: float, release_length: float, peak_level=1, attack_shape: float | str = None, release_shape: float | str = None) -> T
Construct an attack/release envelope
Parameters:
* **attack_length** -- rise time
* **release_length** -- release time
* **peak_level** -- level reached after attack and before
release (see documentation for
"Envelope.from_levels_and_durations()")
* **attack_shape** -- sets curve shape for attack portion of
the curve (see documentation for
"Envelope.from_levels_and_durations()")
* **release_shape** -- sets curve shape for release portion
of the curve (see documentation for
"Envelope.from_levels_and_durations()")
Returns:
an Envelope constructed accordingly
classmethod asr(attack_length: float, sustain_level, sustain_length: float, release_length: float, attack_shape: float | str = None, release_shape: float | str = None) -> T
Construct an attack/sustain/release envelope
Parameters:
* **attack_length** -- rise time
* **sustain_level** -- sustain level reached after attack and
before release
* **sustain_length** -- length of sustain portion of curve
* **release_length** -- release time
* **attack_shape** -- sets curve shape for attack portion of
the curve (see documentation for
"Envelope.from_levels_and_durations()")
* **release_shape** -- sets curve shape for release portion
of the curve (see documentation for
"Envelope.from_levels_and_durations()")
Returns:
an Envelope constructed accordingly
average_level(t_range: tuple[float, float] = None)
Returns the average value that the Envelope takes over the given
range.
Parameters:
**t_range** -- tuple defining the start and end time of the
interval to check. If None, return the average level reached
over the entire Envelope.
property curve_shapes: Sequence[float | str]
Tuple of all the segment curve shapes.
duplicate() -> T
Returns a copy of this object by serializing to and from JSON.
property durations: Sequence[float]
Tuple of all the segment lengths.
end_level()
Ending value of the Envelope
end_time() -> float
End of the domain on which this Envelope is defined.
classmethod from_segments(segments: Sequence[EnvelopeSegment]) -> T
Create a new envelope from a list of "EnvelopeSegment"s.
Parameters:
**segments** -- list of segments
get_durations(rounded: bool = False) -> Sequence[float]
Tuple of all the segment lengths.
Segment lengths are derived as "end_time - start_time", so an
envelope built up on a regular grid (e.g. repeated 0.1-long
segments) accumulates floating-point dust in these differences
even though each segment was appended with a clean duration.
Pass "rounded=True" to snap each length to a nearby nice decimal
— used for serialization / repr so the intended durations show,
without disturbing the exact segment boundary times that the
curve math relies on.
Parameters:
**rounded** -- if True, snap each duration to a nearby nice
decimal (see "snap_float_to_nice_decimal()")
get_upper_integration_bound(t1: float, desired_area: float, max_error: float = 1e-14) -> float
Given a lower integration bound, find the upper bound that will
result in the desired integral.
Walks the envelope segment by segment, subtracting each
segment's closed-form area until the remaining area falls within
a single segment, then inverts that segment using
"EnvelopeSegment.get_t_at_integral()" — exactly for
constant/linear segments, and to within "max_error" for
exponential ones.
Assumes a non-negative integrand, so that the integral increases
monotonically (true for tempo and dynamics curves, the primary
use). Regions before the first segment and after the last are
treated as flat (at the start/end level), matching
"integrate_interval()".
Parameters:
* **t1** -- lower bound of integration
* **desired_area** -- desired value of the integral.
* **max_error** -- convergence tolerance forwarded to the
per-segment inverse for the exponential case; ignored by
the (exact) constant and linear cases.
insert(t, level, curve_shape_in=0, curve_shape_out=0) -> None
Insert a curve point at time t, and set the shape of the curve
into and out of it. This essentially divides the segment at that
point in two.
Parameters:
* **t** -- The time at which to add a point
* **level** -- The level of the new point we are adding
* **curve_shape_in** -- the curve shape of the new segment
going into the point we are adding
* **curve_shape_out** -- the curve shape of the new segment
going out of the point we are adding
insert_interpolated(t: float, relative_tolerance: float = 1e-07) -> float
Insert another curve point at the given time, without changing
the shape of the curve. Returns the t value of the new (or
already existing) interpolated point.
To avoid manufacturing degenerate, near-zero-width segments due
to floating point imprecision, a point is only added if it is at
least "relative_tolerance * segment_width" away from the
endpoints of the segment it falls in. If "t" lands *within* that
tolerance of an existing control point, this function call is
assumed to be an idempotent re-insertion of an existing curve
point after floating point error has muddied the waters. In this
case no point is added, and the existing control point's time is
returned instead.
Parameters:
* **t** -- the point at which to insert the point
* **relative_tolerance** -- how close "t" may come to an
existing control point before it is treated as coincident
with it, expressed as a fraction of the width of the
segment containing "t".
Returns:
the t value at which we interpolated. If we snapped to an
existing control point, its t is returned; otherwise the
passed value of "t" is returned.
integrate_interval(t1: float, t2: float)
Get the definite integral under this Envelope from t1 to t2
Parameters:
* **t1** -- lower bound of integration
* **t2** -- upper bound of integration
is_shifted_version_of(other: T, tolerance: float = 1e-10) -> bool
Determines if this segment is simply a shifted version of
another segment
Parameters:
* **other** -- another EnvelopeSegment
* **tolerance** -- how close it needs to be to count as the
same
json_dumps() -> str
Dump this object as a JSON string. This uses a custom encoder
that recognizes and appropriately converts any attributes that
are object inheriting from SavesToJSON.
classmethod json_loads(s: str) -> T
Load this object from a JSON string. This uses a custom decoder
that looks for a "_type" key in any object/dictionary being
parsed and converts it to the class specified (assuming it a
subclass of SavesToJSON).
Parameters:
**s** -- a string representing this object in JSON format
length() -> float
The length of the domain on which this Envelope is defined (end
time minus start time).
property levels: Sequence
Tuple of levels at all segment boundary points.
classmethod load_from_json(file_path: str) -> T
Load this object from a JSON file with the given path. This uses
a custom decoder that looks for a "_type" key in any
object/dictionary being parsed and converts it to the class
specified (assuming it a subclass of SavesToJSON).
Parameters:
**file_path** -- path for loading the file
local_extrema(include_saddle_points: bool = False) -> Sequence[float]
Returns a list of the times where the curve changes direction.
Parameters:
**include_saddle_points** -- if True, also include points
where the curve starts or stops plateauing
max_absolute_slope()
Returns the maximum absolute value of the slope over the entire
Envelope.
max_level(t_range: tuple[float, float] = None)
Returns the highest value that the Envelope takes over the given
range.
Parameters:
**t_range** -- tuple defining the start and end time of the
interval to check. If None, return the max level reached over
the entire Envelope.
min_level(t_range: tuple[float, float] = None)
Returns the lowest value that the Envelope takes over the given
range.
Parameters:
**t_range** -- tuple defining the start and end time of the
interval to check. If None, return the max level reached over
the entire Envelope.
normalize_to_duration(desired_duration: float, in_place: bool = True) -> T
Stretch or squeeze the segments of this Envelope so that it has
the desired total duration.
Parameters:
* **desired_duration** -- the desired new duration of the
Envelope
* **in_place** -- if True, modifies this Envelope in place;
if False, makes a copy first
property offset: float
Alias for "Envelope.start_time()".
pop_segment() -> EnvelopeSegment | None
Remove and return the last segment of this Envelope. If there is
only one segment, reduce it to length zero and return None.
pop_segment_from_start() -> EnvelopeSegment | None
Remove and return the first segment of this Envelope. If there
is only one segment, reduce it to length zero and return None.
prepend_envelope(envelope_to_prepend: T) -> T
Extends this envelope backwards by another one (shifted to end
at the start of this one).
prepend_segment(level, duration: float, curve_shape: float = None, tolerance: float = 0, halfway_level=None) -> None
Prepend a segment to the beginning of the curve, starting at
level and lasting for duration. If we're adding a linear segment
to a linear segment, then we extend the last linear segment
instead of adding a new one if the level is within tolerance of
where the last one was headed
Parameters:
* **level** -- the level that the prepended segment starts at
* **duration** -- the duration of the new segment
* **curve_shape** -- defaults to 0 (linear)
* **tolerance** -- tolerance for extending a linear segment
rather than adding a new one
* **halfway_level** -- alternate way of defining the curve
shape. If this is set and the curve shape is not then we
use this to determine the curve shape.
classmethod release(duration: float, start_level=1, curve_shape: float | str = None) -> T
Construct an simple decaying envelope
Parameters:
* **duration** -- total decay length
* **start_level** -- level decayed from
* **curve_shape** -- shape of the curve (see documentation
for "Envelope.from_levels_and_durations()")
Returns:
an Envelope constructed accordingly
remove_segments_after(t: float) -> None
Removes all segments after the given time (including a partial
segment if t lands in the middle of a segment).
Parameters:
**t** -- the point at which this Envelope is to be truncated.
remove_segments_before(t: float) -> None
Removes all segments before the given time (including a partial
segment if t lands in the middle of a segment).
Parameters:
**t** -- the point at which this Envelope is to be truncated.
save_to_json(file_path: str) -> None
Save this object to a JSON file using the given path. This uses
a custom encoder that recognizes and appropriately converts any
attributes that are object inheriting from SavesToJSON.
Parameters:
**file_path** -- path for saving the file
scale_horizontal(amount: float) -> T
Scales the domain of this Envelope by the specified amount.
Parameters:
**amount** -- amount to scale domain by
Returns:
self, for chaining purposes
scale_vertical(amount) -> T
Scales the levels of this segment by the specified amount.
Parameters:
**amount** -- amount to scale output by
Returns:
self, for chaining purposes
shift_horizontal(amount: float) -> T
Shifts the domain of this Envelope by the specified amount.
Parameters:
**amount** -- the amount to shift the domain by
Returns:
self, for chaining purposes
shift_vertical(amount) -> T
Shifts the levels of this Envelope the specified amount.
Parameters:
**amount** -- the amount to shift up and down by
Returns:
self, for chaining purposes
simplified(use_curvature=True, include_saddle_points=True) -> T
Simplifies the envelope to only extrema and inflection points.
Parameters:
* **use_curvature** -- if True, adjusts the curvature of the
segments to match the half-way point between key points. If
False, linearly interpolate between key points.
* **include_saddle_points** -- if True, include saddle points
as well as extrema
split_at(t: float | Sequence[float], change_original: bool = False, zero_out_offsets: bool = True) -> Sequence[T]
Splits the Envelope at one or several points and returns a tuple
of the pieces
Parameters:
* **t** -- either the time t or a tuple/list of times t at
which to split the curve
* **change_original** -- if true, the original Envelope gets
turned into the first of the returned tuple
* **zero_out_offsets** -- if true, each new piece is shifted
to start at zero
Returns:
tuple of Envelopes representing the pieces this has been
split into
start_level()
Beginning value of the Envelope
start_time() -> float
Beginning of the domain on which this Envelope is defined.
property times: Sequence[float]
Tuple of all the segment start times.
value_at(t: float, from_left: bool = False)
Get the value of this Envelope at the given time.
Parameters:
* **t** -- the time
* **from_left** -- if true, get the limit as we approach t
from the left. In the case of a zero-length segment, which
suddenly changes the value, this tells us what the value
was right before the jump instead of right after the jump.
======================================================================
=== FILE: clockblocks/clockblocks.tempo_envelope.TempoHistory.txt
======================================================================
clockblocks.tempo_envelope.TempoHistory
***************************************
class clockblocks.tempo_envelope.TempoHistory(levels: float | Sequence[float] = (60,), durations: Sequence[float] = (), curve_shapes: Sequence[float | str] = None, units: str = 'tempo', duration_units: str = 'beats', beat: float = 0.0)
Bases: "TempoEnvelope"
Subclass of TempoEnvelope that keeps track of a current beat and
time, and provides functionality for moving forward a certain
number of beats or seconds, and/or setting tempo target(s) to reach
in the future.
Parameters:
* **levels** -- see "TempoEnvelope"
* **durations** -- see "TempoEnvelope"
* **curve_shapes** -- see "TempoEnvelope"
* **units** -- see "TempoEnvelope"
* **duration_units** -- see "TempoEnvelope"
* **beat** -- Where to set the current beat
-[ Methods ]-
+------------+--------------------------------------------------------------------------------------------+
| "advance"( | Advance the current beat/time in the envelope by the given number of beats. |
| duration[, | |
| duration_u | |
| nits]) | |
+------------+--------------------------------------------------------------------------------------------+
| "append_en | Append another tempo envelope onto the end of this one, starting from the current beat. |
| velope"(en | |
| velope_to_ | |
| append[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "apply_fun | Apply a function for this TempoEnvelope to follow. |
| ction"(fun | |
| c[, domain | |
| _start, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "as_tempo_ | Converts this TempoHistory to a simpler TempoEnvelope (removing reference to current beat |
| envelope"( | and time) |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "beat_at_t | Determine the beat at the given time. |
| ime"(t) | |
+------------+--------------------------------------------------------------------------------------------+
| "from_temp | Constructs a TempoHistory from a TempoEnvelope. |
| o_envelope | |
| "(tempo_en | |
| velope[, | |
| beat]) | |
+------------+--------------------------------------------------------------------------------------------+
| "go_to_bea | Jump straight to the given beat in this TempoHistory |
| t"(b) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_beat_ | Set a target beat length for this TempoEnvelope to reach in duration beats/seconds (with |
| length_tar | the unit defined by duration_units). |
| get"(beat_ | |
| length_tar | |
| get, ...) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_rate_ | Set a target beat rate for this TempoEnvelope to reach in duration beats/seconds (with the |
| target"(ra | unit defined by duration_units). |
| te_target, | |
| duration[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_tempo | Set a target tempo for this TempoEnvelope to reach in duration beats/seconds (with the |
| _target"(t | unit defined by duration_units). |
| empo_targe | |
| t, | |
| duration[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "show_plot | Shows a plot of this TempoHistory using matplotlib. |
| "([title, | |
| resolution | |
| , ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "stop_foll | If we've applied a function or a looping envelope, this causes us to stop doing so |
| ow_functio | |
| n_or_envel | |
| ope_loop"( | |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "time_at_b | Determine the time at the given beat. |
| eat"(beat) | |
+------------+--------------------------------------------------------------------------------------------+
| "truncate" | Removes all segments after the current beat. |
| () | |
+------------+--------------------------------------------------------------------------------------------+
| "truncate_ | Removes all segments after the given beat and adds a constant segment if necessary to |
| at"(beat) | bring us up to that beat. |
+------------+--------------------------------------------------------------------------------------------+
-[ Inherited Methods ]-
+------------+--------------------------------------------------------------------------------------------+
| "adsr"(att | Construct a standard attack/decay/sustain/release envelope |
| ack_length | |
| , attack_l | |
| evel, | |
| ...[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "append_se | Append a segment to the end of the curve ending at level and lasting for duration. |
| gment"(lev | |
| el, | |
| duration[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "ar"(attac | Construct an attack/release envelope |
| k_length, | |
| release_le | |
| ngth[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "asr"(atta | Construct an attack/sustain/release envelope |
| ck_length, | |
| sustain_le | |
| vel, ...[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "average_l | Returns the average value that the Envelope takes over the given range. |
| evel"([t_r | |
| ange]) | |
+------------+--------------------------------------------------------------------------------------------+
| "beat_leng | Get the beat length at the given beat. |
| th_at"(bea | |
| t[, from_l | |
| eft]) | |
+------------+--------------------------------------------------------------------------------------------+
| "convert_d | Warps this tempo_curve so that all the locations of key points get re-interpreted as times |
| urations_t | instead of beat locations. |
| o_times"() | |
+------------+--------------------------------------------------------------------------------------------+
| "convert_u | Utility method to convert values between unites of tempo, rate and beat length. |
| nits"(valu | |
| es, input_ | |
| units, out | |
| put_units) | |
+------------+--------------------------------------------------------------------------------------------+
| "duplicate | Returns a copy of this object by serializing to and from JSON. |
| "() | |
+------------+--------------------------------------------------------------------------------------------+
| "end_level | Ending value of the Envelope |
| "() | |
+------------+--------------------------------------------------------------------------------------------+
| "end_time" | End of the domain on which this Envelope is defined. |
| () | |
+------------+--------------------------------------------------------------------------------------------+
| "extend_to | Extends the end of this TempoEnvelope to the given beat (if needed) by adding a constant |
| "(beat) | segment at the end. |
+------------+--------------------------------------------------------------------------------------------+
| "from_func | Constructs a TempoEnvelope that approximates an arbitrary function. |
| tion"(func | |
| tion[, dom | |
| ain_start, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "from_leve | Constructs a TempoEnvelope from the given levels and total length, using the specified |
| ls"(levels | units. |
| [, length, | |
| units, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "from_leve | Constructs a TempoEnvelope from the given levels, durations and curve shapes, using the |
| ls_and_dur | specified units. |
| ations"([l | |
| evels, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "from_list | Construct a TempoEnvelope from a list that can take a number of formats |
| "(construc | |
| tor_list[, | |
| units, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "from_poin | Construct an envelope from a list of (beat/time, tempo/rate/beat length) pairs. |
| ts"(*point | |
| s[, units, | |
| duration_u | |
| nits]) | |
+------------+--------------------------------------------------------------------------------------------+
| "from_segm | Create a new envelope from a list of "EnvelopeSegment"s. |
| ents"(segm | |
| ents) | |
+------------+--------------------------------------------------------------------------------------------+
| "get_durat | Tuple of all the segment lengths. |
| ions"([rou | |
| nded]) | |
+------------+--------------------------------------------------------------------------------------------+
| "get_upper | Given a lower integration bound, find the upper bound that will result in the desired |
| _integrati | integral. |
| on_bound"( | |
| t1, desire | |
| d_area) | |
+------------+--------------------------------------------------------------------------------------------+
| "insert"(t | Insert a curve point at time t, and set the shape of the curve into and out of it. |
| , level[, | |
| curve_shap | |
| e_in, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "insert_in | Insert another curve point at the given time, without changing the shape of the curve. |
| terpolated | |
| "(t[, rela | |
| tive_toler | |
| ance]) | |
+------------+--------------------------------------------------------------------------------------------+
| "integrate | Get the definite integral under this Envelope from t1 to t2 |
| _interval" | |
| (t1, t2) | |
+------------+--------------------------------------------------------------------------------------------+
| "is_defaul | True if this is the trivial default tempo — a constant 60 bpm (rate 1.0) with no duration, |
| t"() | i.e. structurally identical to a freshly- constructed "TempoEnvelope()". |
+------------+--------------------------------------------------------------------------------------------+
| "is_shifte | Determines if this segment is simply a shifted version of another segment |
| d_version_ | |
| of"(other[ | |
| , toleranc | |
| e]) | |
+------------+--------------------------------------------------------------------------------------------+
| "json_dump | Dump this object as a JSON string. |
| s"() | |
+------------+--------------------------------------------------------------------------------------------+
| "json_load | Load this object from a JSON string. |
| s"(s) | |
+------------+--------------------------------------------------------------------------------------------+
| "length"() | The length of the domain on which this Envelope is defined (end time minus start time). |
+------------+--------------------------------------------------------------------------------------------+
| "load_from | Load this object from a JSON file with the given path. |
| _json"(fil | |
| e_path) | |
+------------+--------------------------------------------------------------------------------------------+
| "local_ext | Returns a list of the times where the curve changes direction. |
| rema"([inc | |
| lude_saddl | |
| e_points]) | |
+------------+--------------------------------------------------------------------------------------------+
| "max_absol | Returns the maximum absolute value of the slope over the entire Envelope. |
| ute_slope" | |
| () | |
+------------+--------------------------------------------------------------------------------------------+
| "max_level | Returns the highest value that the Envelope takes over the given range. |
| "([t_range | |
| ]) | |
+------------+--------------------------------------------------------------------------------------------+
| "min_level | Returns the lowest value that the Envelope takes over the given range. |
| "([t_range | |
| ]) | |
+------------+--------------------------------------------------------------------------------------------+
| "normalize | Stretch or squeeze the segments of this Envelope so that it has the desired total |
| _to_durati | duration. |
| on"(desire | |
| d_duration | |
| [, ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "pop_segme | Remove and return the last segment of this Envelope. |
| nt"() | |
+------------+--------------------------------------------------------------------------------------------+
| "pop_segme | Remove and return the first segment of this Envelope. |
| nt_from_st | |
| art"() | |
+------------+--------------------------------------------------------------------------------------------+
| "prepend_e | Extends this envelope backwards by another one (shifted to end at the start of this one). |
| nvelope"(e | |
| nvelope_to | |
| _prepend) | |
+------------+--------------------------------------------------------------------------------------------+
| "prepend_s | Prepend a segment to the beginning of the curve, starting at level and lasting for |
| egment"(le | duration. |
| vel, | |
| duration[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "rate_at"( | Get the beat rate (in beats/second) at the given beat. |
| beat[, fro | |
| m_left]) | |
+------------+--------------------------------------------------------------------------------------------+
| "release"( | Construct an simple decaying envelope |
| duration[, | |
| start_leve | |
| l, curve_s | |
| hape]) | |
+------------+--------------------------------------------------------------------------------------------+
| "remove_se | Removes all segments after the given time (including a partial segment if t lands in the |
| gments_aft | middle of a segment). |
| er"(t) | |
+------------+--------------------------------------------------------------------------------------------+
| "remove_se | Removes all segments before the given time (including a partial segment if t lands in the |
| gments_bef | middle of a segment). |
| ore"(t) | |
+------------+--------------------------------------------------------------------------------------------+
| "save_to_j | Save this object to a JSON file using the given path. |
| son"(file_ | |
| path) | |
+------------+--------------------------------------------------------------------------------------------+
| "scale_hor | Scales the domain of this Envelope by the specified amount. |
| izontal"(a | |
| mount) | |
+------------+--------------------------------------------------------------------------------------------+
| "scale_ver | Scales the levels of this segment by the specified amount. |
| tical"(amo | |
| unt) | |
+------------+--------------------------------------------------------------------------------------------+
| "shift_hor | Shifts the domain of this Envelope by the specified amount. |
| izontal"(a | |
| mount) | |
+------------+--------------------------------------------------------------------------------------------+
| "shift_ver | Shifts the levels of this Envelope the specified amount. |
| tical"(amo | |
| unt) | |
+------------+--------------------------------------------------------------------------------------------+
| "simplifie | Simplifies the envelope to only extrema and inflection points. |
| d"([use_cu | |
| rvature, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "split_at" | Splits the Envelope at one or several points and returns a tuple of the pieces |
| (t[, chang | |
| e_original | |
| , zero_out | |
| _offsets]) | |
+------------+--------------------------------------------------------------------------------------------+
| "start_lev | Beginning value of the Envelope |
| el"() | |
+------------+--------------------------------------------------------------------------------------------+
| "start_tim | Beginning of the domain on which this Envelope is defined. |
| e"() | |
+------------+--------------------------------------------------------------------------------------------+
| "tempo_at" | Get the tempo (in beats/minute) at the given beat. |
| (beat[, fr | |
| om_left]) | |
+------------+--------------------------------------------------------------------------------------------+
| "value_at" | Get the value of this Envelope at the given time. |
| (t[, from_ | |
| left]) | |
+------------+--------------------------------------------------------------------------------------------+
-[ Attributes ]-
+------------+--------------------------------------------------------------------------------------------+
| "beat" | The current beat. |
+------------+--------------------------------------------------------------------------------------------+
| "beat_leng | The current beat length. |
| th" | |
+------------+--------------------------------------------------------------------------------------------+
| "curve_sha | Tuple of all the segment curve shapes. |
| pes" | |
+------------+--------------------------------------------------------------------------------------------+
| "durations | Tuple of all the segment lengths. |
| " | |
+------------+--------------------------------------------------------------------------------------------+
| "levels" | Tuple of levels at all segment boundary points. |
+------------+--------------------------------------------------------------------------------------------+
| "offset" | Alias for "Envelope.start_time()". |
+------------+--------------------------------------------------------------------------------------------+
| "rate" | The current rate in beats/second |
+------------+--------------------------------------------------------------------------------------------+
| "tempo" | The current tempo in beats/minute |
+------------+--------------------------------------------------------------------------------------------+
| "time" | The current time. |
+------------+--------------------------------------------------------------------------------------------+
| "times" | Tuple of all the segment start times. |
+------------+--------------------------------------------------------------------------------------------+
follow_func_or_envelope_loop: FunctionFollowInfo | EnvelopeLoopInfo
classmethod from_tempo_envelope(tempo_envelope: TempoEnvelope, beat: float = 0.0)
Constructs a TempoHistory from a TempoEnvelope.
Parameters:
* **tempo_envelope** -- the TempoEnvelope to copy
* **beat** -- the beat to start this TempoHistory on
property time
The current time. Time is found by integrating under the beat
length curve: seconds/beat * beats = seconds.
property beat
The current beat.
property beat_length
The current beat length.
property rate
The current rate in beats/second
property tempo
The current tempo in beats/minute
time_at_beat(beat)
Determine the time at the given beat.
For beats at or ahead of the committed pointer (the common case,
used e.g. by wait()), we integrate forward from the pointer
(cheap). For beats behind the pointer (e.g. when resolving
TimeStamps) we integrate from the origin instead to avoid a
negative integral.
Parameters:
**beat** -- The beat at which to calculate the time.
beat_at_time(t)
Determine the beat at the given time. See "time_at_beat()" for
why we branch on whether the target is ahead of or behind the
committed pointer.
Parameters:
**t** -- The time at which to calculate the beat
append_envelope(envelope_to_append: TempoEnvelope, truncate: bool = False, loop: bool = False) -> TempoEnvelope
Append another tempo envelope onto the end of this one, starting
from the current beat.
Parameters:
* **envelope_to_append** -- the TempoEnvelope to add on
* **truncate** -- if True, first discard any existing
segments that extend past the current beat, so the appended
envelope begins cleanly from now
* **loop** -- if True, keep repeating *envelope_to_append*
indefinitely from this point on
Returns:
self, for chaining purposes
set_beat_length_target(beat_length_target: float, duration: float, curve_shape: float = 0, alignment_target: float | MetricPhaseTarget | None = None, duration_units: str = 'beats', truncate: bool = True) -> None
Set a target beat length for this TempoEnvelope to reach in
duration beats/seconds (with the unit defined by
duration_units).
Parameters:
* **beat_length_target** -- The beat length we want to reach
* **duration** -- How long until we reach that beat length
* **curve_shape** -- > 0 makes change happen later, < 0 makes
change happen sooner. When *alignment_target* is given,
this acts only as a *seed* for solving the curvature, a
suggestion rather than a guaranteed value. (And even then
it only makes sense if alignment target is a
MetricPhaseTarget; if it's a fixed time/beat, there's only
one curvature solution, if it exists.)
* **alignment_target** -- optional constraint on the
endpoint's *free* axis (the one *duration* does not pin:
time when duration_units is beats, beats when it is time).
Either a number (land the free axis exactly on that
coordinate, which fully determines the curvature) or a
"MetricPhaseTarget" (snap to the nearest matching phase on
the free axis). See "_add_segment()". Raises ValueError if
unreachable due to the limited flexibility of curvature
adjustment.
* **duration_units** -- one of ("beats", "time"); defines
whether the duration is in beats or in seconds.
* **truncate** -- Whether or not to truncate this
TempoEnvelope to the current beat before setting this
target.
set_rate_target(rate_target: float, duration: float, curve_shape: float = 0, alignment_target: float | MetricPhaseTarget | None = None, duration_units: str = 'beats', truncate: bool = True) -> None
Set a target beat rate for this TempoEnvelope to reach in
duration beats/seconds (with the unit defined by
duration_units). See "set_beat_length_target()".
set_tempo_target(tempo_target: float, duration: float, curve_shape: float = 0, alignment_target: float | MetricPhaseTarget | None = None, duration_units: str = 'beats', truncate: bool = True) -> None
Set a target tempo for this TempoEnvelope to reach in duration
beats/seconds (with the unit defined by duration_units). See
"set_beat_length_target()".
apply_function(func: Callable[[float], float], domain_start: float = 0, domain_end: float = None, units: str = 'tempo', duration_units: str = 'beats', truncate: bool = False, loop: bool = False, extension_increment: float = 2.0, scanning_step_size: float = 0.05, key_point_resolution_multiple: int = 2, iterations: int = 6, min_key_point_distance: float = 1e-07) -> None
Apply a function for this TempoEnvelope to follow. If domain_end
is None, this causes us to follow this function indefinitely; if
a value is given for domain_end, then this appends an envelope
that matches the contour of the prescribed function over a
finite domain.
Parameters:
* **func** -- a function (likely a lambda function) that maps
a given beat/time to the desired tempo/rate/beatlength at
that moment. See the *units* and *duration_units*
arguments, which allow you to specify the units of the
input and output of the function.
* **domain_start** -- what part of the function's domain to
start at (defaults to 0)
* **domain_end** -- what part of the function's domain to end
at (defaults to None, which causes the TempoHistory to
follow the function indefinitely, or until
"stop_follow_function_or_envelope_loop()" is called.)
* **units** -- either "beats" or "time". If beats, then the
*func* param specifies a mapping from beats to
tempo/rate/beatlength; if time, then it specifies a mapping
from sections to tempo/rate/beatlength.
* **duration_units** -- one of ("tempo", "rate",
"beatlength"). This determines the units of the output of
the *func* parameter.
* **truncate** -- if True, truncate any current projection of
the TempoHistory into the future, and begin following this
function from the current moment. If False, start following
the function from the end of the current projection of the
TempoHistory.
* **loop** -- Only relevant if domain_end is set. If so, this
determines whether or not we loop the segment of function.
* **extension_increment** -- Only relevant if domain_end is
None. When following the tempo/rate/beatlength function
indefinitely, we project the function this far into the
future, and only extend further as we reach the end of what
we have projected.
* **scanning_step_size** -- see
"expenvelope.Envelope.from_function()"
* **key_point_resolution_multiple** -- see
"expenvelope.Envelope.from_function()"
* **iterations** -- see
"expenvelope.Envelope.from_function()"
* **min_key_point_distance** -- see
"expenvelope.Envelope.from_function()"
stop_follow_function_or_envelope_loop()
If we've applied a function or a looping envelope, this causes
us to stop doing so
advance(duration: float, duration_units: DurationUnits = 'beats') -> tuple[float, float]
Advance the current beat/time in the envelope by the given
number of beats.
Parameters:
* **duration** -- how many beats or seconds to advance by
* **duration_units** -- one of ("beats", "time")
Returns:
tuple of delta beats, delta time
go_to_beat(b: float) -> TempoEnvelope
Jump straight to the given beat in this TempoHistory
Parameters:
**b** -- the beat to jump to
Returns:
self, for chaining purposes
truncate_at(beat: float) -> TempoEnvelope
Removes all segments after the given beat and adds a constant
segment if necessary to bring us up to that beat.
Parameters:
**beat** -- the beat that we are truncating the tempo
envelope after
Returns:
self, for chaining purposes
truncate() -> TempoEnvelope
Removes all segments after the current beat.
Returns:
self, for chaining purposes
classmethod adsr(attack_length: float, attack_level, decay_length: float, sustain_level, sustain_length: float, release_length: float, attack_shape: float | str = None, decay_shape: float | str = None, release_shape: float | str = None) -> T
Construct a standard attack/decay/sustain/release envelope
Parameters:
* **attack_length** -- rise time
* **attack_level** -- level reached after attack before decay
* **decay_length** -- length of decay portion of the curve
* **sustain_level** -- sustain level reached after decay and
before release
* **sustain_length** -- length of sustain portion of curve
* **release_length** -- release time
* **attack_shape** -- sets curve shape for attack portion of
the curve (see documentation for
"Envelope.from_levels_and_durations()")
* **decay_shape** -- sets curve shape for decay portion of
the curve (see documentation for
"Envelope.from_levels_and_durations()")
* **release_shape** -- sets curve shape for release portion
of the curve (see documentation for
"Envelope.from_levels_and_durations()")
Returns:
an Envelope constructed accordingly
append_segment(level, duration: float, curve_shape: float = None, tolerance: float = 0, halfway_level=None) -> None
Append a segment to the end of the curve ending at level and
lasting for duration. If we're adding a linear segment to a
linear segment, then we extend the last linear segment instead
of adding a new one if the level is within tolerance of where
the last one was headed
Parameters:
* **level** -- the level we're going to
* **duration** -- the duration of the new segment
* **curve_shape** -- defaults to 0 (linear)
* **tolerance** -- tolerance for extending a linear segment
rather than adding a new one
* **halfway_level** -- alternate way of defining the curve
shape. If this is set and the curve shape is not then we
use this to determine the curve shape.
classmethod ar(attack_length: float, release_length: float, peak_level=1, attack_shape: float | str = None, release_shape: float | str = None) -> T
Construct an attack/release envelope
Parameters:
* **attack_length** -- rise time
* **release_length** -- release time
* **peak_level** -- level reached after attack and before
release (see documentation for
"Envelope.from_levels_and_durations()")
* **attack_shape** -- sets curve shape for attack portion of
the curve (see documentation for
"Envelope.from_levels_and_durations()")
* **release_shape** -- sets curve shape for release portion
of the curve (see documentation for
"Envelope.from_levels_and_durations()")
Returns:
an Envelope constructed accordingly
classmethod asr(attack_length: float, sustain_level, sustain_length: float, release_length: float, attack_shape: float | str = None, release_shape: float | str = None) -> T
Construct an attack/sustain/release envelope
Parameters:
* **attack_length** -- rise time
* **sustain_level** -- sustain level reached after attack and
before release
* **sustain_length** -- length of sustain portion of curve
* **release_length** -- release time
* **attack_shape** -- sets curve shape for attack portion of
the curve (see documentation for
"Envelope.from_levels_and_durations()")
* **release_shape** -- sets curve shape for release portion
of the curve (see documentation for
"Envelope.from_levels_and_durations()")
Returns:
an Envelope constructed accordingly
average_level(t_range: tuple[float, float] = None)
Returns the average value that the Envelope takes over the given
range.
Parameters:
**t_range** -- tuple defining the start and end time of the
interval to check. If None, return the average level reached
over the entire Envelope.
beat_length_at(beat: float, from_left: bool = False) -> float
Get the beat length at the given beat. If the beat length jumps
at the given beat, the default is to return the beat length
after the jump, though this can be overridden with the
*from_left* argument.
Parameters:
* **beat** -- the beat at which to get the beat length
* **from_left** -- whether to evaluate from the right or
left-hand side of the beat in question
convert_durations_to_times()
Warps this tempo_curve so that all the locations of key points
get re-interpreted as times instead of beat locations. For
instance, a tempo curve where the rate hovers around 2 will see
a segment of length 3 get stretched into a segment of length 6,
since if it's supposed to take 3 seconds, it would take 6 beats.
Pretty confusing, but when we want to construct a tempo curve
specifying the *times* that changes occur rather than the beats,
we can first construct it as though the durations were in beats,
then call this function to warp it so that the durations are in
time.
Returns:
self, altered accordingly
static convert_units(values: float | Sequence[float], input_units: str, output_units: str) -> float | Sequence[float]
Utility method to convert values between unites of tempo, rate
and beat length.
Parameters:
* **values** -- value or list of values in terms of the
input_units
* **input_units** -- current units of the given values
(either "tempo", "rate", or "beat length")
* **output_units** -- desired units to convert to (either
"tempo", "rate", or "beat length")
Returns:
the list of values, converted to output units
property curve_shapes: Sequence[float | str]
Tuple of all the segment curve shapes.
duplicate() -> T
Returns a copy of this object by serializing to and from JSON.
property durations: Sequence[float]
Tuple of all the segment lengths.
end_level()
Ending value of the Envelope
end_time() -> float
End of the domain on which this Envelope is defined.
extend_to(beat: float) -> TempoEnvelope
Extends the end of this TempoEnvelope to the given beat (if
needed) by adding a constant segment at the end.
classmethod from_function(function, domain_start=0, domain_end=1, units: str = 'tempo', duration_units: str = 'beats', scanning_step_size: float = 0.05, key_point_resolution_multiple: int = 2, iterations: int = 6, min_key_point_distance: float = 1e-07) -> TempoEnvelope
Constructs a TempoEnvelope that approximates an arbitrary
function. The domain of the function is in units defined by the
*duration_units* parameter, and the range is in units defined by
the *units* parameter.
Parameters:
* **function** -- A function from beat/time to
tempo/rate/beat length, as defined by the *duration_units*
and *units* parameters.
* **domain_start** -- see "from_function()"
* **domain_end** -- see "from_function()"
* **units** -- one of "tempo", "rate" or "beat length",
determining how we interpret the function output
* **duration_units** -- either "beats" or "time", determining
how we interpret the function input
* **scanning_step_size** -- when analyzing the function for
discontinuities, maxima and minima, inflection points,
etc., use this step size for the initial pass.
* **key_point_resolution_multiple** -- factor by which we add
extra key points between the extrema and inflection points
to improve the curve fit.
* **iterations** -- when a potential key point is found, we
zoom in and scan again in the viscinity of the point. This
determines how many iterations of zooming we do.
* **min_key_point_distance** -- after scanning for key
points, any that are closer than this distance are merged.
Returns:
a TempoEnvelope, constructed accordingly
classmethod from_levels(levels: Sequence[float], length: float = 1.0, units: str = 'tempo', duration_units: str = 'beats') -> TempoEnvelope
Constructs a TempoEnvelope from the given levels and total
length, using the specified units.
Parameters:
* **levels** -- levels of the curve segments (i.e. tempo
values) in the units specified by the *units* argument
* **length** -- total length of the tempo curve, in the units
specified by the *duration_units* argument
* **units** -- one of "tempo", "rate" or "beat length",
determining how we interpret the levels given
* **duration_units** -- either "beats" or "time", determining
how we interpret the durations given
Returns:
a TempoEnvelope, constructed accordingly
classmethod from_levels_and_durations(levels: Sequence = (0, 0), durations: Sequence[float] = (0,), curve_shapes: Sequence[float | str] = None, units: str = 'tempo', duration_units: str = 'beats') -> TempoEnvelope
Constructs a TempoEnvelope from the given levels, durations and
curve shapes, using the specified units.
Parameters:
* **levels** -- levels of the curve segments (i.e. tempo
values) in the units specified by the *units* argument
* **durations** -- durations of the curve segments in the
units specified by the *duration_units* argument
* **curve_shapes** -- see "from_levels_and_durations()"
* **units** -- one of "tempo", "rate" or "beat length",
determining how we interpret the levels given
* **duration_units** -- either "beats" or "time", determining
how we interpret the durations given
Returns:
a TempoEnvelope, constructed accordingly
classmethod from_list(constructor_list: Sequence, units: str = 'tempo', duration_units: str = 'beats') -> TempoEnvelope
Construct a TempoEnvelope from a list that can take a number of
formats
Parameters:
* **constructor_list** -- see "from_list()"
* **units** -- one of "tempo", "rate" or "beat length",
determining how we interpret the levels given
* **duration_units** -- either "beats" or "time", determining
how we interpret the durations given
Returns:
a TempoEnvelope, constructed accordingly
classmethod from_points(*points, units: str = 'tempo', duration_units: str = 'beats') -> TempoEnvelope
Construct an envelope from a list of (beat/time, tempo/rate/beat
length) pairs. Units are defined by the *units* and
*duration_units* parameters.
Parameters:
* **points** -- list of points, each of which is of the form
(time, value) or (time, value, curve_shape)
* **units** -- one of "tempo", "rate" or "beat length",
determining how we interpret the tempo values
* **duration_units** -- either "beats" or "time", determining
how we interpret the time values
Returns:
a TempoEnvelope, constructed accordingly
classmethod from_segments(segments: Sequence[EnvelopeSegment]) -> T
Create a new envelope from a list of "EnvelopeSegment"s.
Parameters:
**segments** -- list of segments
get_durations(rounded: bool = False) -> Sequence[float]
Tuple of all the segment lengths.
Segment lengths are derived as "end_time - start_time", so an
envelope built up on a regular grid (e.g. repeated 0.1-long
segments) accumulates floating-point dust in these differences
even though each segment was appended with a clean duration.
Pass "rounded=True" to snap each length to a nearby nice decimal
— used for serialization / repr so the intended durations show,
without disturbing the exact segment boundary times that the
curve math relies on.
Parameters:
**rounded** -- if True, snap each duration to a nearby nice
decimal (see "snap_float_to_nice_decimal()")
get_upper_integration_bound(t1: float, desired_area: float, max_error: float = 1e-14) -> float
Given a lower integration bound, find the upper bound that will
result in the desired integral.
Walks the envelope segment by segment, subtracting each
segment's closed-form area until the remaining area falls within
a single segment, then inverts that segment using
"EnvelopeSegment.get_t_at_integral()" — exactly for
constant/linear segments, and to within "max_error" for
exponential ones.
Assumes a non-negative integrand, so that the integral increases
monotonically (true for tempo and dynamics curves, the primary
use). Regions before the first segment and after the last are
treated as flat (at the start/end level), matching
"integrate_interval()".
Parameters:
* **t1** -- lower bound of integration
* **desired_area** -- desired value of the integral.
* **max_error** -- convergence tolerance forwarded to the
per-segment inverse for the exponential case; ignored by
the (exact) constant and linear cases.
insert(t, level, curve_shape_in=0, curve_shape_out=0) -> None
Insert a curve point at time t, and set the shape of the curve
into and out of it. This essentially divides the segment at that
point in two.
Parameters:
* **t** -- The time at which to add a point
* **level** -- The level of the new point we are adding
* **curve_shape_in** -- the curve shape of the new segment
going into the point we are adding
* **curve_shape_out** -- the curve shape of the new segment
going out of the point we are adding
insert_interpolated(t: float, relative_tolerance: float = 1e-07) -> float
Insert another curve point at the given time, without changing
the shape of the curve. Returns the t value of the new (or
already existing) interpolated point.
To avoid manufacturing degenerate, near-zero-width segments due
to floating point imprecision, a point is only added if it is at
least "relative_tolerance * segment_width" away from the
endpoints of the segment it falls in. If "t" lands *within* that
tolerance of an existing control point, this function call is
assumed to be an idempotent re-insertion of an existing curve
point after floating point error has muddied the waters. In this
case no point is added, and the existing control point's time is
returned instead.
Parameters:
* **t** -- the point at which to insert the point
* **relative_tolerance** -- how close "t" may come to an
existing control point before it is treated as coincident
with it, expressed as a fraction of the width of the
segment containing "t".
Returns:
the t value at which we interpolated. If we snapped to an
existing control point, its t is returned; otherwise the
passed value of "t" is returned.
integrate_interval(t1: float, t2: float)
Get the definite integral under this Envelope from t1 to t2
Parameters:
* **t1** -- lower bound of integration
* **t2** -- upper bound of integration
is_default() -> bool
True if this is the trivial default tempo — a constant 60 bpm
(rate 1.0) with no duration, i.e. structurally identical to a
freshly-constructed "TempoEnvelope()". (Note this is stricter
than "functionally constant at 60": a flat-60 envelope that
carries a real duration or extra segments is *not* default (and
worth surfacing for debugging)
is_shifted_version_of(other: T, tolerance: float = 1e-10) -> bool
Determines if this segment is simply a shifted version of
another segment
Parameters:
* **other** -- another EnvelopeSegment
* **tolerance** -- how close it needs to be to count as the
same
json_dumps() -> str
Dump this object as a JSON string. This uses a custom encoder
that recognizes and appropriately converts any attributes that
are object inheriting from SavesToJSON.
classmethod json_loads(s: str) -> T
Load this object from a JSON string. This uses a custom decoder
that looks for a "_type" key in any object/dictionary being
parsed and converts it to the class specified (assuming it a
subclass of SavesToJSON).
Parameters:
**s** -- a string representing this object in JSON format
length() -> float
The length of the domain on which this Envelope is defined (end
time minus start time).
property levels: Sequence
Tuple of levels at all segment boundary points.
classmethod load_from_json(file_path: str) -> T
Load this object from a JSON file with the given path. This uses
a custom decoder that looks for a "_type" key in any
object/dictionary being parsed and converts it to the class
specified (assuming it a subclass of SavesToJSON).
Parameters:
**file_path** -- path for loading the file
local_extrema(include_saddle_points: bool = False) -> Sequence[float]
Returns a list of the times where the curve changes direction.
Parameters:
**include_saddle_points** -- if True, also include points
where the curve starts or stops plateauing
max_absolute_slope()
Returns the maximum absolute value of the slope over the entire
Envelope.
max_level(t_range: tuple[float, float] = None)
Returns the highest value that the Envelope takes over the given
range.
Parameters:
**t_range** -- tuple defining the start and end time of the
interval to check. If None, return the max level reached over
the entire Envelope.
min_level(t_range: tuple[float, float] = None)
Returns the lowest value that the Envelope takes over the given
range.
Parameters:
**t_range** -- tuple defining the start and end time of the
interval to check. If None, return the max level reached over
the entire Envelope.
normalize_to_duration(desired_duration: float, in_place: bool = True) -> T
Stretch or squeeze the segments of this Envelope so that it has
the desired total duration.
Parameters:
* **desired_duration** -- the desired new duration of the
Envelope
* **in_place** -- if True, modifies this Envelope in place;
if False, makes a copy first
property offset: float
Alias for "Envelope.start_time()".
pop_segment() -> EnvelopeSegment | None
Remove and return the last segment of this Envelope. If there is
only one segment, reduce it to length zero and return None.
pop_segment_from_start() -> EnvelopeSegment | None
Remove and return the first segment of this Envelope. If there
is only one segment, reduce it to length zero and return None.
prepend_envelope(envelope_to_prepend: T) -> T
Extends this envelope backwards by another one (shifted to end
at the start of this one).
prepend_segment(level, duration: float, curve_shape: float = None, tolerance: float = 0, halfway_level=None) -> None
Prepend a segment to the beginning of the curve, starting at
level and lasting for duration. If we're adding a linear segment
to a linear segment, then we extend the last linear segment
instead of adding a new one if the level is within tolerance of
where the last one was headed
Parameters:
* **level** -- the level that the prepended segment starts at
* **duration** -- the duration of the new segment
* **curve_shape** -- defaults to 0 (linear)
* **tolerance** -- tolerance for extending a linear segment
rather than adding a new one
* **halfway_level** -- alternate way of defining the curve
shape. If this is set and the curve shape is not then we
use this to determine the curve shape.
rate_at(beat: float, from_left: bool = False) -> float
Get the beat rate (in beats/second) at the given beat. If the
rate jumps at the given beat, the default is to return the rate
after the jump, though this can be overridden with the
*from_left* argument.
Parameters:
* **beat** -- the beat at which to get the rate
* **from_left** -- whether to evaluate from the right or
left-hand side of the beat in question
classmethod release(duration: float, start_level=1, curve_shape: float | str = None) -> T
Construct an simple decaying envelope
Parameters:
* **duration** -- total decay length
* **start_level** -- level decayed from
* **curve_shape** -- shape of the curve (see documentation
for "Envelope.from_levels_and_durations()")
Returns:
an Envelope constructed accordingly
remove_segments_after(t: float) -> None
Removes all segments after the given time (including a partial
segment if t lands in the middle of a segment).
Parameters:
**t** -- the point at which this Envelope is to be truncated.
remove_segments_before(t: float) -> None
Removes all segments before the given time (including a partial
segment if t lands in the middle of a segment).
Parameters:
**t** -- the point at which this Envelope is to be truncated.
save_to_json(file_path: str) -> None
Save this object to a JSON file using the given path. This uses
a custom encoder that recognizes and appropriately converts any
attributes that are object inheriting from SavesToJSON.
Parameters:
**file_path** -- path for saving the file
scale_horizontal(amount: float) -> T
Scales the domain of this Envelope by the specified amount.
Parameters:
**amount** -- amount to scale domain by
Returns:
self, for chaining purposes
scale_vertical(amount) -> T
Scales the levels of this segment by the specified amount.
Parameters:
**amount** -- amount to scale output by
Returns:
self, for chaining purposes
shift_horizontal(amount: float) -> T
Shifts the domain of this Envelope by the specified amount.
Parameters:
**amount** -- the amount to shift the domain by
Returns:
self, for chaining purposes
shift_vertical(amount) -> T
Shifts the levels of this Envelope the specified amount.
Parameters:
**amount** -- the amount to shift up and down by
Returns:
self, for chaining purposes
show_plot(title=None, resolution=25, show_segment_divisions=True, units='tempo', x_range=None, y_range=None, show_current_beat=True)
Shows a plot of this TempoHistory using matplotlib.
Parameters:
* **title** -- see "TempoEnvelope.show_plot()"
* **resolution** -- see "TempoEnvelope.show_plot()"
* **show_segment_divisions** -- see
"TempoEnvelope.show_plot()"
* **units** -- see "TempoEnvelope.show_plot()"
* **x_range** -- see "TempoEnvelope.show_plot()"
* **y_range** -- see "TempoEnvelope.show_plot()"
* **show_current_beat** -- whether or not to show the current
beat as a dashed line
simplified(use_curvature=True, include_saddle_points=True) -> T
Simplifies the envelope to only extrema and inflection points.
Parameters:
* **use_curvature** -- if True, adjusts the curvature of the
segments to match the half-way point between key points. If
False, linearly interpolate between key points.
* **include_saddle_points** -- if True, include saddle points
as well as extrema
split_at(t: float | Sequence[float], change_original: bool = False, zero_out_offsets: bool = True) -> Sequence[T]
Splits the Envelope at one or several points and returns a tuple
of the pieces
Parameters:
* **t** -- either the time t or a tuple/list of times t at
which to split the curve
* **change_original** -- if true, the original Envelope gets
turned into the first of the returned tuple
* **zero_out_offsets** -- if true, each new piece is shifted
to start at zero
Returns:
tuple of Envelopes representing the pieces this has been
split into
start_level()
Beginning value of the Envelope
start_time() -> float
Beginning of the domain on which this Envelope is defined.
tempo_at(beat: float, from_left: bool = False) -> float
Get the tempo (in beats/minute) at the given beat. If the tempo
jumps at the given beat, the default is to return the tempo
after the jump, though this can be overridden with the
*from_left* argument.
Parameters:
* **beat** -- the beat at which to get the tempo
* **from_left** -- whether to evaluate from the right or
left-hand side of the beat in question
property times: Sequence[float]
Tuple of all the segment start times.
value_at(t: float, from_left: bool = False)
Get the value of this Envelope at the given time.
Parameters:
* **t** -- the time
* **from_left** -- if true, get the limit as we approach t
from the left. In the case of a zero-length segment, which
suddenly changes the value, this tells us what the value
was right before the jump instead of right after the jump.
as_tempo_envelope() -> TempoEnvelope
Converts this TempoHistory to a simpler TempoEnvelope (removing
reference to current beat and time)
======================================================================
=== FILE: clockblocks/clockblocks.tempo_envelope.tempo_modification.txt
======================================================================
clockblocks.tempo_envelope.tempo_modification
*********************************************
clockblocks.tempo_envelope.tempo_modification(fn)
Decorator applied to methods of TempoEnvelope that change the curve
and therefore could mess up any cached beat/time relationships.
======================================================================
=== FILE: clockblocks/clockblocks.tempo_envelope.txt
======================================================================
clockblocks.tempo_envelope
**************************
Module defining the "TempoEnvelope" class for describing a time-
varying tempo, the "TempoHistory" class, which adds to that a tracking
of the current beat and time, and the "MetricPhaseTarget" class, which
specifies a goal arrival point within the beat (or meter) cycle.
-[ Classes ]-
+------------+--------------------------------------------------------------------------------------------+
| "EnvelopeL | Internal bookkeeping for a tempo envelope set to loop: the envelope being repeated plus |
| oopInfo"(e | the running beat/time extents needed to keep appending copies as the clock advances. |
| nv, length | |
| _in_beats, | |
| ...) | |
+------------+--------------------------------------------------------------------------------------------+
| "FunctionF | Internal bookkeeping for a tempo curve that follows a user function: the function itself |
| ollowInfo" | plus the state needed to keep extending the envelope to approximate it as the clock |
| (func, nex | advances. |
| t_domain_s | |
| tart, ...) | |
+------------+--------------------------------------------------------------------------------------------+
| "TempoEnve | A subclass of "Envelope" that is specifically designed for representing changing tempo |
| lope"([lev | curves. |
| els, | |
| durations, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "TempoHist | Subclass of TempoEnvelope that keeps track of a current beat and time, and provides |
| ory"([leve | functionality for moving forward a certain number of beats or seconds, and/or setting |
| ls, | tempo target(s) to reach in the future. |
| durations, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
* clockblocks.tempo_envelope.EnvelopeLoopInfo
* "EnvelopeLoopInfo"
* "EnvelopeLoopInfo.env"
* "EnvelopeLoopInfo.length_in_beats"
* "EnvelopeLoopInfo.length_in_time"
* "EnvelopeLoopInfo.current_end_beat"
* "EnvelopeLoopInfo.current_end_time"
* clockblocks.tempo_envelope.FunctionFollowInfo
* "FunctionFollowInfo"
* "FunctionFollowInfo.func"
* "FunctionFollowInfo.next_domain_start"
* "FunctionFollowInfo.extension_increment"
* "FunctionFollowInfo.units"
* "FunctionFollowInfo.duration_units"
* "FunctionFollowInfo.scanning_step_size"
* "FunctionFollowInfo.min_key_point_distance"
* "FunctionFollowInfo.iterations"
* "FunctionFollowInfo.key_point_resolution_multiple"
* "FunctionFollowInfo.current_end_beat"
* "FunctionFollowInfo.current_end_time"
* clockblocks.tempo_envelope.TempoEnvelope
* "TempoEnvelope"
* "TempoEnvelope.from_levels_and_durations()"
* "TempoEnvelope.from_levels()"
* "TempoEnvelope.from_list()"
* "TempoEnvelope.from_points()"
* "TempoEnvelope.from_function()"
* "TempoEnvelope.beat_length_at()"
* "TempoEnvelope.rate_at()"
* "TempoEnvelope.tempo_at()"
* "TempoEnvelope.extend_to()"
* "TempoEnvelope.truncate_at()"
* "TempoEnvelope.convert_units()"
* "TempoEnvelope.convert_durations_to_times()"
* "TempoEnvelope.show_plot()"
* "TempoEnvelope.is_default()"
* "TempoEnvelope.time_at_beat()"
* "TempoEnvelope.beat_at_time()"
* "TempoEnvelope.adsr()"
* "TempoEnvelope.append_envelope()"
* "TempoEnvelope.append_segment()"
* "TempoEnvelope.ar()"
* "TempoEnvelope.asr()"
* "TempoEnvelope.average_level()"
* "TempoEnvelope.curve_shapes"
* "TempoEnvelope.duplicate()"
* "TempoEnvelope.durations"
* "TempoEnvelope.end_level()"
* "TempoEnvelope.end_time()"
* "TempoEnvelope.from_segments()"
* "TempoEnvelope.get_durations()"
* "TempoEnvelope.get_upper_integration_bound()"
* "TempoEnvelope.insert()"
* "TempoEnvelope.insert_interpolated()"
* "TempoEnvelope.integrate_interval()"
* "TempoEnvelope.is_shifted_version_of()"
* "TempoEnvelope.json_dumps()"
* "TempoEnvelope.json_loads()"
* "TempoEnvelope.length()"
* "TempoEnvelope.levels"
* "TempoEnvelope.load_from_json()"
* "TempoEnvelope.local_extrema()"
* "TempoEnvelope.max_absolute_slope()"
* "TempoEnvelope.max_level()"
* "TempoEnvelope.min_level()"
* "TempoEnvelope.normalize_to_duration()"
* "TempoEnvelope.offset"
* "TempoEnvelope.pop_segment()"
* "TempoEnvelope.pop_segment_from_start()"
* "TempoEnvelope.prepend_envelope()"
* "TempoEnvelope.prepend_segment()"
* "TempoEnvelope.release()"
* "TempoEnvelope.remove_segments_after()"
* "TempoEnvelope.remove_segments_before()"
* "TempoEnvelope.save_to_json()"
* "TempoEnvelope.scale_horizontal()"
* "TempoEnvelope.scale_vertical()"
* "TempoEnvelope.shift_horizontal()"
* "TempoEnvelope.shift_vertical()"
* "TempoEnvelope.simplified()"
* "TempoEnvelope.split_at()"
* "TempoEnvelope.start_level()"
* "TempoEnvelope.start_time()"
* "TempoEnvelope.times"
* "TempoEnvelope.value_at()"
* clockblocks.tempo_envelope.TempoHistory
* "TempoHistory"
* "TempoHistory.follow_func_or_envelope_loop"
* "TempoHistory.from_tempo_envelope()"
* "TempoHistory.time"
* "TempoHistory.beat"
* "TempoHistory.beat_length"
* "TempoHistory.rate"
* "TempoHistory.tempo"
* "TempoHistory.time_at_beat()"
* "TempoHistory.beat_at_time()"
* "TempoHistory.append_envelope()"
* "TempoHistory.set_beat_length_target()"
* "TempoHistory.set_rate_target()"
* "TempoHistory.set_tempo_target()"
* "TempoHistory.apply_function()"
* "TempoHistory.stop_follow_function_or_envelope_loop()"
* "TempoHistory.advance()"
* "TempoHistory.go_to_beat()"
* "TempoHistory.truncate_at()"
* "TempoHistory.truncate()"
* "TempoHistory.adsr()"
* "TempoHistory.append_segment()"
* "TempoHistory.ar()"
* "TempoHistory.asr()"
* "TempoHistory.average_level()"
* "TempoHistory.beat_length_at()"
* "TempoHistory.convert_durations_to_times()"
* "TempoHistory.convert_units()"
* "TempoHistory.curve_shapes"
* "TempoHistory.duplicate()"
* "TempoHistory.durations"
* "TempoHistory.end_level()"
* "TempoHistory.end_time()"
* "TempoHistory.extend_to()"
* "TempoHistory.from_function()"
* "TempoHistory.from_levels()"
* "TempoHistory.from_levels_and_durations()"
* "TempoHistory.from_list()"
* "TempoHistory.from_points()"
* "TempoHistory.from_segments()"
* "TempoHistory.get_durations()"
* "TempoHistory.get_upper_integration_bound()"
* "TempoHistory.insert()"
* "TempoHistory.insert_interpolated()"
* "TempoHistory.integrate_interval()"
* "TempoHistory.is_default()"
* "TempoHistory.is_shifted_version_of()"
* "TempoHistory.json_dumps()"
* "TempoHistory.json_loads()"
* "TempoHistory.length()"
* "TempoHistory.levels"
* "TempoHistory.load_from_json()"
* "TempoHistory.local_extrema()"
* "TempoHistory.max_absolute_slope()"
* "TempoHistory.max_level()"
* "TempoHistory.min_level()"
* "TempoHistory.normalize_to_duration()"
* "TempoHistory.offset"
* "TempoHistory.pop_segment()"
* "TempoHistory.pop_segment_from_start()"
* "TempoHistory.prepend_envelope()"
* "TempoHistory.prepend_segment()"
* "TempoHistory.rate_at()"
* "TempoHistory.release()"
* "TempoHistory.remove_segments_after()"
* "TempoHistory.remove_segments_before()"
* "TempoHistory.save_to_json()"
* "TempoHistory.scale_horizontal()"
* "TempoHistory.scale_vertical()"
* "TempoHistory.shift_horizontal()"
* "TempoHistory.shift_vertical()"
* "TempoHistory.show_plot()"
* "TempoHistory.simplified()"
* "TempoHistory.split_at()"
* "TempoHistory.start_level()"
* "TempoHistory.start_time()"
* "TempoHistory.tempo_at()"
* "TempoHistory.times"
* "TempoHistory.value_at()"
* "TempoHistory.as_tempo_envelope()"
-[ Functions ]-
+------------+--------------------------------------------------------------------------------------------+
| "tempo_mod | Decorator applied to methods of TempoEnvelope that change the curve and therefore could |
| ification" | mess up any cached beat/time relationships. |
| (fn) | |
+------------+--------------------------------------------------------------------------------------------+
* clockblocks.tempo_envelope.tempo_modification
* "tempo_modification()"
======================================================================
=== FILE: clockblocks/clockblocks.time_stamp.TimeStamp.txt
======================================================================
clockblocks.time_stamp.TimeStamp
********************************
class clockblocks.time_stamp.TimeStamp(scheduler_time: float, master_clock: Clock)
Bases: "object"
A clock-agnostic point on the scheduler's timeline, projectable
into any clock's beat or time axis on demand. Usually captured for
the current moment with "now()" (e.g. at note-on); later queries
answer "what beat / time was this in clock X?" for any clock in the
same family.
Parameters:
* **scheduler_time** -- the scheduler-time (canonical, not
relative to any clock) this TimeStamp is pinned to. Per-clock
beats and times are later derived from it.
* **master_clock** -- the master clock of the clock family this
TimeStamp belongs to.
Variables:
**scheduler_time** -- the scheduler-time this TimeStamp
represents.
-[ Methods ]-
+------------+--------------------------------------------------------------------------------------------+
| "beat_in_c | Get the beat in "clock" at the moment this TimeStamp represents. |
| lock"(cloc | |
| k) | |
+------------+--------------------------------------------------------------------------------------------+
| "now"([mas | Capture a TimeStamp for the current moment. |
| ter_clock] | |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "time_in_c | Get the time in "clock" at the moment this TimeStamp represents. |
| lock"(cloc | |
| k) | |
+------------+--------------------------------------------------------------------------------------------+
-[ Attributes ]-
+------------+--------------------------------------------------------------------------------------------+
| "time_in_m | The time (in the master clock's own time frame) at which this TimeStamp was created. |
| aster" | |
+------------+--------------------------------------------------------------------------------------------+
classmethod now(master_clock: Clock = None) -> TimeStamp
Capture a TimeStamp for the current moment. Any clock in the
family may be given (its master is used); if omitted, the clock
is taken from the current thread.
property time_in_master: float
The time (in the master clock's own time frame) at which this
TimeStamp was created.
beat_in_clock(clock: Clock) -> float
Get the beat in "clock" at the moment this TimeStamp represents.
time_in_clock(clock: Clock) -> float
Get the time in "clock" at the moment this TimeStamp represents.
======================================================================
=== FILE: clockblocks/clockblocks.time_stamp.TimeStampInterval.txt
======================================================================
clockblocks.time_stamp.TimeStampInterval
****************************************
class clockblocks.time_stamp.TimeStampInterval(start_scheduler_time: float, end_scheduler_time: float, master_clock: Clock)
Bases: "object"
The oriented span between two moments on the scheduler's timeline,
produced by subtracting two TimeStamps ("end_stamp - start_stamp").
Like "TimeStamp" it stores only scheduler times (and the associated
master clock) and resolves on demand.
Note that this interval is an anchored interval, not a free-
floating duration. Its start and end points are particular moments
on the scheduler, and the beat duration of that span in a given
clock depends on that clock's absolute tempo curve between those
end points.
Note that, due to floating point arithmetic, two time stamps that
were created with a clean time delta may yield a slightly noisy
delta when the difference is taken ("(start + 0.1) - start" is not
exactly "0.1" in IEEE-754). For this reason, the duration methods
here snap their results to a nice decimal if one is nearby,
restoring any intended round durations.
Variables:
* **start_scheduler_time** -- scheduler-time of the earlier
endpoint.
* **end_scheduler_time** -- scheduler-time of the later
endpoint.
-[ Methods ]-
+------------+--------------------------------------------------------------------------------------------+
| "beats_dur | How many beats elapsed in "clock" across this interval. |
| ation_in_c | |
| lock"(cloc | |
| k) | |
+------------+--------------------------------------------------------------------------------------------+
| "time_dura | How much time elapsed across this interval, in "clock"'s own time frame. |
| tion_in_cl | |
| ock"(clock | |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
-[ Attributes ]-
+------------+--------------------------------------------------------------------------------------------+
| "time_dura | How much time elapsed across this interval, in the master clock's own time frame. |
| tion_in_ma | |
| ster" | |
+------------+--------------------------------------------------------------------------------------------+
property time_duration_in_master: float
How much time elapsed across this interval, in the master
clock's own time frame.
beats_duration_in_clock(clock: Clock) -> float
How many beats elapsed in "clock" across this interval.
time_duration_in_clock(clock: Clock) -> float
How much time elapsed across this interval, in "clock"'s own
time frame.
======================================================================
=== FILE: clockblocks/clockblocks.time_stamp.txt
======================================================================
clockblocks.time_stamp
**********************
Module containing the "TimeStamp" class, which captures a moment on
the scheduler's timeline in a clock-agnostic way, so that it can later
be projected into the beat or time axis of any clock in the family.
Also contains "TimeStampInterval", representing the span between two
such time stamps.
-[ Classes ]-
+------------+--------------------------------------------------------------------------------------------+
| "TimeStamp | A clock-agnostic point on the scheduler's timeline, projectable into any clock's beat or |
| "(schedule | time axis on demand. |
| r_time, ma | |
| ster_clock | |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "TimeStamp | The oriented span between two moments on the scheduler's timeline, produced by subtracting |
| Interval"( | two TimeStamps ("end_stamp - start_stamp"). |
| start_sche | |
| duler_time | |
| , ...) | |
+------------+--------------------------------------------------------------------------------------------+
* clockblocks.time_stamp.TimeStamp
* "TimeStamp"
* "TimeStamp.now()"
* "TimeStamp.time_in_master"
* "TimeStamp.beat_in_clock()"
* "TimeStamp.time_in_clock()"
* clockblocks.time_stamp.TimeStampInterval
* "TimeStampInterval"
* "TimeStampInterval.time_duration_in_master"
* "TimeStampInterval.beats_duration_in_clock()"
* "TimeStampInterval.time_duration_in_clock()"
======================================================================
=== FILE: clockblocks/clockblocks.utilities.apply_beat_length_function.txt
======================================================================
clockblocks.utilities.apply_beat_length_function
************************************************
clockblocks.utilities.apply_beat_length_function(function: Callable, domain_start: float = 0, domain_end: float = None, duration_units: str = 'beats', truncate: bool = True, loop: bool = False, extension_increment: float = 2.0, **kwargs) -> None
Drive the current clock's beat length (in seconds per beat) by
following a function of beats/time. Forwards to
"apply_beat_length_function()"; acts on the currently active clock.
Raises NoActiveClockError if there is no active clock. See
"apply_tempo_function()" for the meaning of every argument (the
only difference is that "function" returns a beat length in seconds
per beat).
======================================================================
=== FILE: clockblocks/clockblocks.utilities.apply_rate_function.txt
======================================================================
clockblocks.utilities.apply_rate_function
*****************************************
clockblocks.utilities.apply_rate_function(function: Callable, domain_start: float = 0, domain_end: float = None, duration_units: str = 'beats', truncate: bool = True, loop: bool = False, extension_increment: float = 2.0, **kwargs) -> None
Drive the current clock's rate (in beats per second) by following a
function of beats/time. Forwards to "apply_rate_function()"; acts
on the currently active clock. Raises NoActiveClockError if there
is no active clock. See "apply_tempo_function()" for the meaning of
every argument (the only difference is that "function" returns a
rate in beats per second).
======================================================================
=== FILE: clockblocks/clockblocks.utilities.apply_tempo_envelope.txt
======================================================================
clockblocks.utilities.apply_tempo_envelope
******************************************
clockblocks.utilities.apply_tempo_envelope(envelope: TempoEnvelope, truncate: bool = True, loop: bool = False) -> None
Append a ready-made "TempoEnvelope" onto the current clock's tempo
curve. This is the way to *loop* a tempo shape (a "TempoEnvelope"
is defined over beats, so it loops unambiguously). Forwards to
"apply_tempo_envelope()"; acts on the currently active clock.
Raises NoActiveClockError if there is no active clock.
Parameters:
* **envelope** -- the tempo envelope to apply (under the hood a
beat-length-over-beats curve).
* **truncate** -- if "True", discard any tempo curve already
scheduled past the current beat first.
* **loop** -- if "True", repeat the envelope indefinitely until
stopped with "stop_tempo_loop_or_function()".
======================================================================
=== FILE: clockblocks/clockblocks.utilities.apply_tempo_function.txt
======================================================================
clockblocks.utilities.apply_tempo_function
******************************************
clockblocks.utilities.apply_tempo_function(function: Callable, domain_start: float = 0, domain_end: float = None, duration_units: str = 'beats', truncate: bool = True, loop: bool = False, extension_increment: float = 2.0, **kwargs) -> None
Drive the current clock's tempo (in beats per minute) by following
a function of beats/time. Forwards to "apply_tempo_function()";
acts on the currently active clock. Raises NoActiveClockError if
there is no active clock.
Parameters:
* **function** -- a callable mapping a position (in the units
given by "duration_units") to a tempo.
* **domain_start** -- the input value at which to start reading
"function".
* **domain_end** -- the input value at which to stop, or "None"
to follow the function open-endedly.
* **duration_units** -- ""beats"" or ""time"" — whether the
function's input is measured in beats or in seconds.
* **truncate** -- if "True", discard any tempo curve already
scheduled past the current beat first.
* **loop** -- only relevant when "domain_end" is set: if "True",
repeat that finite domain indefinitely (until
"stop_tempo_loop_or_function()").
* **extension_increment** -- only relevant when "domain_end" is
"None": how far ahead (in the function's domain) to project at
a time, extending again as the clock reaches the projected
end.
* **kwargs** -- forwarded to the underlying envelope-from-
function sampling ("scanning_step_size", "iterations", etc. —
see "apply_function()").
======================================================================
=== FILE: clockblocks/clockblocks.utilities.current_clock.txt
======================================================================
clockblocks.utilities.current_clock
***********************************
clockblocks.utilities.current_clock() -> Clock | None
Get the "Clock" active on the current thread, or None if none is
active.
======================================================================
=== FILE: clockblocks/clockblocks.utilities.fork.txt
======================================================================
clockblocks.utilities.fork
**************************
clockblocks.utilities.fork(forked_function: Callable, args: Sequence = (), kwargs: dict = None, name: str = None, initial_rate: float = None, initial_tempo: float = None, initial_beat_length: float = None, when: float | 'moment.ResolvableMoment' = None, done_callback: Callable = None) -> Clock
Run "forked_function" on a new child clock of the currently active
clock, so it proceeds in parallel while staying coordinated under
the same musical time. See "fork()"; raises NoActiveClockError if
there is no active clock.
Parameters:
* **forked_function** -- the function to run on the child clock.
Note that, unlike the original clockblocks, the child clock is
*not* injected as an argument — call "current_clock()" from
inside the function if you need a reference to it.
* **args** -- positional arguments passed to "forked_function".
* **kwargs** -- keyword arguments passed to "forked_function".
* **name** -- optional name for the child clock, useful for
debugging.
* **initial_rate** -- the child's starting rate in beats per
second. Give at most one of
"initial_rate"/"initial_tempo"/"initial_beat_length"; if none
is given the child starts at rate 1.
* **initial_tempo** -- the child's starting tempo in beats per
minute.
* **initial_beat_length** -- the child's starting beat length in
seconds per beat.
* **when** -- when to start the fork. "None" (the default)
starts it immediately; otherwise pass a "Moment" (e.g.
"Moment.after_beats(4)" or "Moment.at_time(10)") or a
"MetricPhaseTarget". Unlike "wait()", a bare number is
rejected here, since we don't know from context whether it's
beats/time, relative/absolute.
* **done_callback** -- an optional function called when the
forked function finishes.
Returns:
the newly created child "Clock".
======================================================================
=== FILE: clockblocks/clockblocks.utilities.get_beat.txt
======================================================================
clockblocks.utilities.get_beat
******************************
clockblocks.utilities.get_beat() -> float
Return how many beats have passed on the currently active clock
(see "beat").
As with the tempo helpers, this reads *this* clock and not the
master; use "current_clock().master.beat" for that. Raises
NoActiveClockError if there is no active clock.
Returns:
the current beat of the active clock.
======================================================================
=== FILE: clockblocks/clockblocks.utilities.get_beat_length.txt
======================================================================
clockblocks.utilities.get_beat_length
*************************************
clockblocks.utilities.get_beat_length() -> float
Return the current beat length (in seconds per beat) of the
currently active clock (see "beat_length"). Raises
NoActiveClockError if there is no active clock.
Returns:
the current beat length, in seconds per beat.
======================================================================
=== FILE: clockblocks/clockblocks.utilities.get_rate.txt
======================================================================
clockblocks.utilities.get_rate
******************************
clockblocks.utilities.get_rate() -> float
Return the current rate (in beats per second) of the currently
active clock (see "rate"). Raises NoActiveClockError if there is no
active clock.
Returns:
the current rate, in beats per second.
======================================================================
=== FILE: clockblocks/clockblocks.utilities.get_tempo.txt
======================================================================
clockblocks.utilities.get_tempo
*******************************
clockblocks.utilities.get_tempo() -> float
Return the current tempo (in beats per minute) of the currently
active clock (see "tempo"). Raises NoActiveClockError if there is
no active clock.
Returns:
the current tempo, in beats per minute.
======================================================================
=== FILE: clockblocks/clockblocks.utilities.get_time.txt
======================================================================
clockblocks.utilities.get_time
******************************
clockblocks.utilities.get_time() -> float
Return how much time has passed on the currently active clock (see
"time") — in seconds if it is the master clock, or parent clock
beats if it is a forked child clock.
As with the tempo helpers, this reads *this* clock and not the
master; use "current_clock().master.time" for that. Raises
NoActiveClockError if there is no active clock.
Returns:
the current time of the active clock.
======================================================================
=== FILE: clockblocks/clockblocks.utilities.meaningfully_greater_than.txt
======================================================================
clockblocks.utilities.meaningfully_greater_than
***********************************************
clockblocks.utilities.meaningfully_greater_than(a: float, b: float, *, rel_tol: float = 1e-09, abs_tol: float = 1e-12) -> bool
True if "a" is meaningfully greater than "b" (mirror of
"meaningfully_less_than()").
======================================================================
=== FILE: clockblocks/clockblocks.utilities.meaningfully_less_than.txt
======================================================================
clockblocks.utilities.meaningfully_less_than
********************************************
clockblocks.utilities.meaningfully_less_than(a: float, b: float, *, rel_tol: float = 1e-09, abs_tol: float = 1e-12) -> bool
True if "a" is meaningfully less than "b" — i.e. "a < b" and not
merely by rounding noise (see "near_equal()"). Use in place of a
bare "<" when "a" and "b" are beats/times reconstructed from
scheduler time.
======================================================================
=== FILE: clockblocks/clockblocks.utilities.near_equal.txt
======================================================================
clockblocks.utilities.near_equal
********************************
clockblocks.utilities.near_equal(a: float, b: float, *, rel_tol: float = 1e-09, abs_tol: float = 1e-12) -> bool
True if "a" and "b" are equal to within floating-point
reconstruction noise.
Thin wrapper over "math.isclose()" with project-wide default
tolerances plus a small absolute floor: "math.isclose" defaults
"abs_tol=0.0", which is too strict near zero, and several callers
compare quantities that can be ~0 (e.g. envelope-segment
durations).
======================================================================
=== FILE: clockblocks/clockblocks.utilities.set_beat_length.txt
======================================================================
clockblocks.utilities.set_beat_length
*************************************
clockblocks.utilities.set_beat_length(beat_length: float) -> None
Immediately set the beat length of the current clock (see
"beat_length"). Raises NoActiveClockError if there is no active
clock.
Parameters:
**beat_length** -- the new beat length, in seconds per beat.
======================================================================
=== FILE: clockblocks/clockblocks.utilities.set_beat_length_target.txt
======================================================================
clockblocks.utilities.set_beat_length_target
********************************************
clockblocks.utilities.set_beat_length_target(beat_length_target: float, when: ResolvableMoment, curve_shape: float = None, truncate: bool = True, align_to: ResolvableMoment = None) -> None
Smoothly change the current clock's beat length to
"beat_length_target" (in seconds per beat), arriving at "when".
Forwards to "set_beat_length_target()" on the currently active
clock. Raises NoActiveClockError if there is no active clock.
Parameters:
* **beat_length_target** -- the beat length to arrive at, in
seconds per beat.
* **when** -- when the target is reached, as a "Moment" or
"MetricPhaseTarget".
* **curve_shape** -- the bend of the transition: "0" is linear,
"> 0" changes late, "< 0" early.
* **truncate** -- if "True", discard any tempo curve already
scheduled past the current beat first.
* **align_to** -- optional; solve the curvature to land the free
axis on a phase or coordinate. See "set_beat_length_target()".
======================================================================
=== FILE: clockblocks/clockblocks.utilities.set_beat_length_targets.txt
======================================================================
clockblocks.utilities.set_beat_length_targets
*********************************************
clockblocks.utilities.set_beat_length_targets(beat_length_targets: Sequence[float], whens: Sequence[ResolvableMoment], curve_shapes: Sequence[float] = None, truncate: bool = True, align_to: ResolvableMoment | Sequence[ResolvableMoment | None] = None) -> None
Set several beat-length targets at once, building a multi-segment
tempo curve on the current clock. Forwards to
"set_beat_length_targets()"; acts on the currently active clock.
Raises NoActiveClockError if there is no active clock.
Parameters:
* **beat_length_targets** -- the beat length to arrive at for
each segment, in seconds per beat.
* **whens** -- the arrival moment for each target (same length
as "beat_length_targets").
* **curve_shapes** -- optional per-segment curve shapes (same
length), or "None" for all-linear.
* **truncate** -- if "True", discard any tempo curve already
scheduled past the current beat first.
* **align_to** -- optional; align whole runs of segments to a
phase/coordinate. See "set_beat_length_targets()".
======================================================================
=== FILE: clockblocks/clockblocks.utilities.set_rate.txt
======================================================================
clockblocks.utilities.set_rate
******************************
clockblocks.utilities.set_rate(rate: float) -> None
Immediately set the rate of the current clock (see "rate"). Raises
NoActiveClockError if there is no active clock.
Parameters:
**rate** -- the new rate, in beats per second.
======================================================================
=== FILE: clockblocks/clockblocks.utilities.set_rate_target.txt
======================================================================
clockblocks.utilities.set_rate_target
*************************************
clockblocks.utilities.set_rate_target(rate_target: float, when: ResolvableMoment, curve_shape: float = None, truncate: bool = True, align_to: ResolvableMoment = None) -> None
Smoothly change the current clock's rate to "rate_target" (in beats
per second), arriving at "when". Forwards to "set_rate_target()" on
the currently active clock. Raises NoActiveClockError if there is
no active clock.
Parameters:
* **rate_target** -- the rate to arrive at, in beats per second.
* **when** -- when the target is reached, as a "Moment" or
"MetricPhaseTarget".
* **curve_shape** -- the bend of the transition: "0" is linear,
"> 0" changes late, "< 0" early.
* **truncate** -- if "True", discard any tempo curve already
scheduled past the current beat first.
* **align_to** -- optional; solve the curvature to land the free
axis on a phase or coordinate. See "set_rate_target()".
======================================================================
=== FILE: clockblocks/clockblocks.utilities.set_rate_targets.txt
======================================================================
clockblocks.utilities.set_rate_targets
**************************************
clockblocks.utilities.set_rate_targets(rate_targets: Sequence[float], whens: Sequence[ResolvableMoment], curve_shapes: Sequence[float] = None, truncate: bool = True, align_to: ResolvableMoment | Sequence[ResolvableMoment | None] = None) -> None
Set several rate targets at once, building a multi-segment tempo
curve on the current clock. Forwards to "set_rate_targets()"; acts
on the currently active clock. Raises NoActiveClockError if there
is no active clock.
Parameters:
* **rate_targets** -- the rate to arrive at for each segment, in
beats per second.
* **whens** -- the arrival moment for each target (same length
as "rate_targets").
* **curve_shapes** -- optional per-segment curve shapes (same
length), or "None" for all-linear.
* **truncate** -- if "True", discard any tempo curve already
scheduled past the current beat first.
* **align_to** -- optional; align whole runs of segments to a
phase/coordinate. See "set_beat_length_targets()".
======================================================================
=== FILE: clockblocks/clockblocks.utilities.set_tempo.txt
======================================================================
clockblocks.utilities.set_tempo
*******************************
clockblocks.utilities.set_tempo(tempo: float) -> None
Immediately set the tempo of the current clock (see "tempo").
Raises NoActiveClockError if there is no active clock.
Parameters:
**tempo** -- the new tempo, in beats per minute.
======================================================================
=== FILE: clockblocks/clockblocks.utilities.set_tempo_target.txt
======================================================================
clockblocks.utilities.set_tempo_target
**************************************
clockblocks.utilities.set_tempo_target(tempo_target: float, when: ResolvableMoment, curve_shape: float = None, truncate: bool = True, align_to: ResolvableMoment = None) -> None
Smoothly change the current clock's tempo to "tempo_target" (in
beats per minute), arriving at "when". Forwards to
"set_tempo_target()" on the currently active clock. Raises
NoActiveClockError if there is no active clock.
Parameters:
* **tempo_target** -- the tempo to arrive at, in beats per
minute.
* **when** -- when the target is reached, as a "Moment" (e.g.
"Moment.after_beats(4)", "Moment.at_time(10)") or a
"MetricPhaseTarget".
* **curve_shape** -- the bend of the transition: "0" is linear,
"> 0" changes late, "< 0" early.
* **truncate** -- if "True", discard any tempo curve already
scheduled past the current beat first.
* **align_to** -- optional; solve the curvature to land the free
axis (the one "when" did not pin) on a phase or coordinate —
e.g. accelerate over a fixed time, landing on a downbeat. See
"set_tempo_target()".
======================================================================
=== FILE: clockblocks/clockblocks.utilities.set_tempo_targets.txt
======================================================================
clockblocks.utilities.set_tempo_targets
***************************************
clockblocks.utilities.set_tempo_targets(tempo_targets: Sequence[float], whens: Sequence[ResolvableMoment], curve_shapes: Sequence[float] = None, truncate: bool = True, align_to: ResolvableMoment | Sequence[ResolvableMoment | None] = None) -> None
Set several tempo targets at once, building a multi-segment tempo
curve on the current clock. Forwards to "set_tempo_targets()"; acts
on the currently active clock. Raises NoActiveClockError if there
is no active clock.
Parameters:
* **tempo_targets** -- the tempo to arrive at for each segment,
in beats per minute.
* **whens** -- the arrival moment for each target (same length
as "tempo_targets"). Each is resolved against the clock's
*current* position (so an "after_*" moment counts from now,
not from the previous segment's end), beats and time may be
mixed, and the moments must come out strictly increasing in
clock-time.
* **curve_shapes** -- optional per-segment curve shapes (same
length), or "None" for all-linear.
* **truncate** -- if "True", discard any tempo curve already
scheduled past the current beat first.
* **align_to** -- optional; bend whole runs of segments to land
collectively on a phase/coordinate. Pass a single
"Moment"/"MetricPhaseTarget" to align the whole call at its
end, or a per-segment list of "None"/targets where each
non-"None" entry closes and aligns the run since the previous
alignment. See "set_beat_length_targets()".
This is one-shot. To loop a tempo shape, build a "TempoEnvelope"
and pass it to "apply_tempo_envelope()" with "loop=True".
======================================================================
=== FILE: clockblocks/clockblocks.utilities.stop_tempo_loop_or_function.txt
======================================================================
clockblocks.utilities.stop_tempo_loop_or_function
*************************************************
clockblocks.utilities.stop_tempo_loop_or_function() -> None
Stop following any function or looping envelope previously started
on the current clock's tempo (via "apply_tempo_function()"/"apply_r
ate_function()"/"apply_beat_length_function()" or a looping
"apply_tempo_envelope()"). The tempo holds at its current value.
Forwards to "stop_tempo_loop_or_function()"; acts on the currently
active clock. Raises NoActiveClockError if there is no active
clock.
======================================================================
=== FILE: clockblocks/clockblocks.utilities.terminate_forked_children.txt
======================================================================
clockblocks.utilities.terminate_forked_children
***********************************************
clockblocks.utilities.terminate_forked_children() -> None
Kill the child clocks of the currently active clock, returning once
they have finished unwinding (see "terminate_forked_children()").
The deliberate counterpart to "wait_for_children_to_finish()". On a
thread with no active clock, raises NoActiveClockError.
======================================================================
=== FILE: clockblocks/clockblocks.utilities.txt
======================================================================
clockblocks.utilities
*********************
Module containing the free functions that make up clockblocks' most
convenient interface. Rather than calling methods on a particular
clock, these operate on whichever clock is running the current thread:
most importantly "wait()" and "fork()", along with getters and setters
for that clock's tempo ("set_tempo()", "set_tempo_target()",
"apply_tempo_envelope()", and their rate/beat-length counterparts).
-[ Functions ]-
+------------+--------------------------------------------------------------------------------------------+
| "apply_bea | Drive the current clock's beat length (in seconds per beat) by following a function of |
| t_length_f | beats/time. |
| unction"(f | |
| unction[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "apply_rat | Drive the current clock's rate (in beats per second) by following a function of |
| e_function | beats/time. |
| "(function | |
| [, ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "apply_tem | Append a ready-made "TempoEnvelope" onto the current clock's tempo curve. |
| po_envelop | |
| e"(envelop | |
| e[, | |
| truncate, | |
| loop]) | |
+------------+--------------------------------------------------------------------------------------------+
| "apply_tem | Drive the current clock's tempo (in beats per minute) by following a function of |
| po_functio | beats/time. |
| n"(functio | |
| n[, ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "current_c | Get the "Clock" active on the current thread, or None if none is active. |
| lock"() | |
+------------+--------------------------------------------------------------------------------------------+
| "fork"(for | Run "forked_function" on a new child clock of the currently active clock, so it proceeds |
| ked_functi | in parallel while staying coordinated under the same musical time. |
| on[, args, | |
| kwargs, | |
| name, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "get_beat" | Return how many beats have passed on the currently active clock (see "beat"). |
| () | |
+------------+--------------------------------------------------------------------------------------------+
| "get_beat_ | Return the current beat length (in seconds per beat) of the currently active clock (see |
| length"() | "beat_length"). |
+------------+--------------------------------------------------------------------------------------------+
| "get_rate" | Return the current rate (in beats per second) of the currently active clock (see "rate"). |
| () | |
+------------+--------------------------------------------------------------------------------------------+
| "get_tempo | Return the current tempo (in beats per minute) of the currently active clock (see |
| "() | "tempo"). |
+------------+--------------------------------------------------------------------------------------------+
| "get_time" | Return how much time has passed on the currently active clock (see "time") — in seconds if |
| () | it is the master clock, or parent clock beats if it is a forked child clock. |
+------------+--------------------------------------------------------------------------------------------+
| "meaningfu | True if "a" is meaningfully greater than "b" (mirror of "meaningfully_less_than()"). |
| lly_greate | |
| r_than"(a, | |
| b, *[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "meaningfu | True if "a" is meaningfully less than "b" — i.e. "a < b" and not merely by rounding noise |
| lly_less_t | (see "near_equal()"). |
| han"(a, b, | |
| *[, | |
| rel_tol, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "near_equa | True if "a" and "b" are equal to within floating-point reconstruction noise. |
| l"(a, b, | |
| *[, | |
| rel_tol, | |
| abs_tol]) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_beat_ | Immediately set the beat length of the current clock (see "beat_length"). |
| length"(be | |
| at_length) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_beat_ | Smoothly change the current clock's beat length to "beat_length_target" (in seconds per |
| length_tar | beat), arriving at "when". |
| get"(beat_ | |
| length_tar | |
| get, when) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_beat_ | Set several beat-length targets at once, building a multi-segment tempo curve on the |
| length_tar | current clock. |
| gets"(beat | |
| _length_ta | |
| rgets, | |
| ...) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_rate" | Immediately set the rate of the current clock (see "rate"). |
| (rate) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_rate_ | Smoothly change the current clock's rate to "rate_target" (in beats per second), arriving |
| target"(ra | at "when". |
| te_target, | |
| when[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_rate_ | Set several rate targets at once, building a multi-segment tempo curve on the current |
| targets"(r | clock. |
| ate_target | |
| s, whens[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_tempo | Immediately set the tempo of the current clock (see "tempo"). |
| "(tempo) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_tempo | Smoothly change the current clock's tempo to "tempo_target" (in beats per minute), |
| _target"(t | arriving at "when". |
| empo_targe | |
| t, when[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_tempo | Set several tempo targets at once, building a multi-segment tempo curve on the current |
| _targets"( | clock. |
| tempo_targ | |
| ets, | |
| whens[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "stop_temp | Stop following any function or looping envelope previously started on the current clock's |
| o_loop_or_ | tempo (via "apply_tempo_function()"/"apply_rate_fu |
| function"( | nction()"/"apply_beat_length_function()" or a looping "apply_tempo_envelope()"). |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "terminate | Kill the child clocks of the currently active clock, returning once they have finished |
| _forked_ch | unwinding (see "terminate_forked_children()"). |
| ildren"() | |
+------------+--------------------------------------------------------------------------------------------+
| "wait"(dt[ | Block the clock currently active on this thread for "dt" beats (or seconds, if |
| , units]) | "units="time""), yielding to the scheduler. |
+------------+--------------------------------------------------------------------------------------------+
| "wait_for_ | Block on the currently active clock until its child clocks have finished (see |
| children_t | "wait_for_children_to_finish()"). |
| o_finish"( | |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "wait_for_ | Block on the currently active clock until *clock* has finished (see |
| clock_to_f | "wait_for_clock_to_finish()"). |
| inish"(clo | |
| ck) | |
+------------+--------------------------------------------------------------------------------------------+
| "wait_fore | Block forever on the currently active clock (see "wait_forever()") — usually to keep the |
| ver"() | main script alive while child clocks do the work. |
+------------+--------------------------------------------------------------------------------------------+
| "wait_unti | Block the clock currently active on this thread until the *absolute* beat (or time, if |
| l"(when[, | "units="time"") given by "when". |
| units]) | |
+------------+--------------------------------------------------------------------------------------------+
* clockblocks.utilities.apply_beat_length_function
* "apply_beat_length_function()"
* clockblocks.utilities.apply_rate_function
* "apply_rate_function()"
* clockblocks.utilities.apply_tempo_envelope
* "apply_tempo_envelope()"
* clockblocks.utilities.apply_tempo_function
* "apply_tempo_function()"
* clockblocks.utilities.current_clock
* "current_clock()"
* clockblocks.utilities.fork
* "fork()"
* clockblocks.utilities.get_beat
* "get_beat()"
* clockblocks.utilities.get_beat_length
* "get_beat_length()"
* clockblocks.utilities.get_rate
* "get_rate()"
* clockblocks.utilities.get_tempo
* "get_tempo()"
* clockblocks.utilities.get_time
* "get_time()"
* clockblocks.utilities.meaningfully_greater_than
* "meaningfully_greater_than()"
* clockblocks.utilities.meaningfully_less_than
* "meaningfully_less_than()"
* clockblocks.utilities.near_equal
* "near_equal()"
* clockblocks.utilities.set_beat_length
* "set_beat_length()"
* clockblocks.utilities.set_beat_length_target
* "set_beat_length_target()"
* clockblocks.utilities.set_beat_length_targets
* "set_beat_length_targets()"
* clockblocks.utilities.set_rate
* "set_rate()"
* clockblocks.utilities.set_rate_target
* "set_rate_target()"
* clockblocks.utilities.set_rate_targets
* "set_rate_targets()"
* clockblocks.utilities.set_tempo
* "set_tempo()"
* clockblocks.utilities.set_tempo_target
* "set_tempo_target()"
* clockblocks.utilities.set_tempo_targets
* "set_tempo_targets()"
* clockblocks.utilities.stop_tempo_loop_or_function
* "stop_tempo_loop_or_function()"
* clockblocks.utilities.terminate_forked_children
* "terminate_forked_children()"
* clockblocks.utilities.wait
* "wait()"
* clockblocks.utilities.wait_for_children_to_finish
* "wait_for_children_to_finish()"
* clockblocks.utilities.wait_for_clock_to_finish
* "wait_for_clock_to_finish()"
* clockblocks.utilities.wait_forever
* "wait_forever()"
* clockblocks.utilities.wait_until
* "wait_until()"
======================================================================
=== FILE: clockblocks/clockblocks.utilities.wait.txt
======================================================================
clockblocks.utilities.wait
**************************
clockblocks.utilities.wait(dt: float | ResolvableMoment, units='beats') -> None
Block the clock currently active on this thread for "dt" beats (or
seconds, if "units="time""), yielding to the scheduler. Forwards to
"wait()".
"dt" may also be a "Moment" or "MetricPhaseTarget", in which case
it is resolved directly and "units" is ignored — e.g.
"wait(Moment.at_beat(8))".
On a thread with no active clock, raises NoActiveClockError.
Parameters:
* **dt** -- how long to wait — a number (in beats, or seconds if
"units="time""), or a Moment / MetricPhaseTarget to wait
until.
* **units** -- either ""beats"" or ""time"" (ignored when "dt"
is a Moment).
======================================================================
=== FILE: clockblocks/clockblocks.utilities.wait_for_children_to_finish.txt
======================================================================
clockblocks.utilities.wait_for_children_to_finish
*************************************************
clockblocks.utilities.wait_for_children_to_finish() -> None
Block on the currently active clock until its child clocks have
finished (see "wait_for_children_to_finish()"). On a thread with no
active clock, raises NoActiveClockError.
======================================================================
=== FILE: clockblocks/clockblocks.utilities.wait_for_clock_to_finish.txt
======================================================================
clockblocks.utilities.wait_for_clock_to_finish
**********************************************
clockblocks.utilities.wait_for_clock_to_finish(clock: Clock) -> None
Block on the currently active clock until *clock* has finished (see
"wait_for_clock_to_finish()"). On a thread with no active clock,
raises NoActiveClockError.
======================================================================
=== FILE: clockblocks/clockblocks.utilities.wait_forever.txt
======================================================================
clockblocks.utilities.wait_forever
**********************************
clockblocks.utilities.wait_forever() -> None
Block forever on the currently active clock (see "wait_forever()")
— usually to keep the main script alive while child clocks do the
work. Unblocks only if the clock is killed, raising
"ClockKilledError". On a thread with no active clock, raises
NoActiveClockError.
======================================================================
=== FILE: clockblocks/clockblocks.utilities.wait_until.txt
======================================================================
clockblocks.utilities.wait_until
********************************
clockblocks.utilities.wait_until(when: float | ResolvableMoment, units='beats') -> None
Block the clock currently active on this thread until the
*absolute* beat (or time, if "units="time"") given by "when".
Forwards to "wait_until()".
"when" may also be a "Moment" or "MetricPhaseTarget", in which case
the units are ignored and behavior is identical to wait(). If
"when" is already in the past, this returns essentially
immediately.
On a thread with no active clock, raises NoActiveClockError.
Parameters:
* **when** -- the absolute beat (or time, if "units="time"") to
wait until, or a Moment / MetricPhaseTarget to resolve.
* **units** -- either ""beats"" or ""time"" (ignored when "when"
is a Moment).
======================================================================
=== FILE: clockblocks.txt
======================================================================
clockblocks package
*******************
Clockblocks is a library for controlling the flow of musical time,
part of SCAMP (Suite for Computer-Assisted Music in Python).
Each "Clock" runs on its own thread, and clocks form families under a
single master clock, whose "Scheduler" wakes each thread back up when
its call to "wait()" is due. The scheduler keeps the whole clock
family coordinated under a shared, ideal timeline, which is not
polluted by the small delays that user code inevitably incurs. How
aggressively a clock catches up when it does fall behind is set by its
timing policy, which ranges from waiting out each delay in full to
staying pinned to the absolute schedule.
The rate at which beats pass within a clock is given by its tempo,
which may vary over time, as described by a "TempoEnvelope". Clocks
are also nestable: "fork()" spawns a child clock running a function in
a parallel, subordinate timeline. A child clock's tempo is felt
relative to that of its parent, so the true rate at which time passes
in a clock is the product of the clock's own rate and that of each of
its ancestors.
Taken together, these features allow a composer to create multiple,
polyphonic (and perhaps poly-tempo) layers of music, each with its own
tempo curve, all coordinated under a master clock.
-[ Modules: ]-
+------------+--------------------------------------------------------------------------------------------+
| "clock" | Module defining the central "Clock" class — recursively nestable clocks that coordinate |
| | musical time under a master clock and its background "Scheduler". |
+------------+--------------------------------------------------------------------------------------------+
| "enums" | Module containing the enums used to express units of duration and rate: "DurationUnits", |
| | for saying whether a quantity is measured in beats or in time, and "TempoUnits", for |
| | saying whether a rate of musical time is expressed as a tempo, a rate, or a beat length. |
+------------+--------------------------------------------------------------------------------------------+
| "exception | Exception hierarchy for clockblocks. |
| s" | |
+------------+--------------------------------------------------------------------------------------------+
| "metric_ph | Module containing the "MetricPhaseTarget" class, which names a point within a repeating |
| ase" | beat or measure cycle — "the next downbeat", say, or "halfway through the bar" — without |
| | having to work out how far away that point actually is. |
+------------+--------------------------------------------------------------------------------------------+
| "moment" | Module containing "Moment", which names a point on a clock's timeline, and the |
| | "ResolvableMoment" protocol implemented by anything that can be pinned to such a point. |
+------------+--------------------------------------------------------------------------------------------+
| "scheduler | Module containing the "Scheduler", the single background thread that drives an entire |
| " | clock family: it holds a queue of upcoming events, sleeps until the next one is due, and |
| | wakes the clocks waiting on them. |
+------------+--------------------------------------------------------------------------------------------+
| "tempo_env | Module defining the "TempoEnvelope" class for describing a time- varying tempo, the |
| elope" | "TempoHistory" class, which adds to that a tracking of the current beat and time, and the |
| | "MetricPhaseTarget" class, which specifies a goal arrival point within the beat (or meter) |
| | cycle. |
+------------+--------------------------------------------------------------------------------------------+
| "time_stam | Module containing the "TimeStamp" class, which captures a moment on the scheduler's |
| p" | timeline in a clock-agnostic way, so that it can later be projected into the beat or time |
| | axis of any clock in the family. |
+------------+--------------------------------------------------------------------------------------------+
| "utilities | Module containing the free functions that make up clockblocks' most convenient interface. |
| " | |
+------------+--------------------------------------------------------------------------------------------+
* clockblocks.clock
* clockblocks.clock.Clock
* "Clock"
* "Clock.master"
* "Clock.is_master()"
* "Clock.hold_scheduler()"
* "Clock.children()"
* "Clock.iterate_inheritance()"
* "Clock.inheritance()"
* "Clock.iterate_all_relatives()"
* "Clock.iterate_descendants()"
* "Clock.descendants()"
* "Clock.print_family_tree()"
* "Clock.time"
* "Clock.beat"
* "Clock.projected_time()"
* "Clock.projected_beat()"
* "Clock.status()"
* "Clock.print_status()"
* "Clock.beat_length"
* "Clock.rate"
* "Clock.tempo"
* "Clock.absolute_rate"
* "Clock.absolute_tempo"
* "Clock.absolute_beat_length"
* "Clock.set_beat_length_target()"
* "Clock.set_rate_target()"
* "Clock.set_tempo_target()"
* "Clock.set_beat_length_targets()"
* "Clock.set_rate_targets()"
* "Clock.set_tempo_targets()"
* "Clock.apply_beat_length_function()"
* "Clock.apply_rate_function()"
* "Clock.apply_tempo_function()"
* "Clock.apply_tempo_envelope()"
* "Clock.stop_tempo_loop_or_function()"
* "Clock.clock_to_scheduler_time()"
* "Clock.scheduler_to_clock_time()"
* "Clock.bring_up_to_date()"
* "Clock.extract_absolute_tempo_envelope()"
* "Clock.wait()"
* "Clock.wait_until()"
* "Clock.fork()"
* "Clock.schedule_action()"
* "Clock.wait_forever()"
* "Clock.wait_for_children_to_finish()"
* "Clock.wait_for_clock_to_finish()"
* "Clock.terminate_forked_children()"
* "Clock.run_as_server()"
* "Clock.alive"
* "Clock.fast_forward()"
* "Clock.fast_forward_to_time()"
* "Clock.fast_forward_in_time()"
* "Clock.fast_forward_to_beat()"
* "Clock.fast_forward_in_beats()"
* "Clock.is_fast_forwarding()"
* "Clock.timing_policy"
* "Clock.use_absolute_timing_policy()"
* "Clock.use_relative_timing_policy()"
* "Clock.use_mixed_timing_policy()"
* "Clock.precise_timing"
* "Clock.spin_guard_duration"
* "Clock.kill()"
* clockblocks.clock.ClockFamilyOptions
* "ClockFamilyOptions"
* "ClockFamilyOptions.timing_policy"
* "ClockFamilyOptions.precise_timing"
* "ClockFamilyOptions.spin_guard_duration"
* "ClockFamilyOptions.pool_size"
* "ClockFamilyOptions.prewarm_pool"
* "ClockFamilyOptions.time_backend"
* clockblocks.clock.ClockState
* "ClockState"
* "ClockState.PENDING"
* "ClockState.ALIVE"
* "ClockState.DEAD"
* clockblocks.enums
* clockblocks.enums.DurationUnits
* "DurationUnits"
* "DurationUnits.BEATS"
* "DurationUnits.TIME"
* "DurationUnits.opposite"
* "DurationUnits.encode()"
* "DurationUnits.replace()"
* "DurationUnits.split()"
* "DurationUnits.rsplit()"
* "DurationUnits.join()"
* "DurationUnits.capitalize()"
* "DurationUnits.casefold()"
* "DurationUnits.title()"
* "DurationUnits.center()"
* "DurationUnits.count()"
* "DurationUnits.expandtabs()"
* "DurationUnits.find()"
* "DurationUnits.partition()"
* "DurationUnits.index()"
* "DurationUnits.ljust()"
* "DurationUnits.lower()"
* "DurationUnits.lstrip()"
* "DurationUnits.rfind()"
* "DurationUnits.rindex()"
* "DurationUnits.rjust()"
* "DurationUnits.rstrip()"
* "DurationUnits.rpartition()"
* "DurationUnits.splitlines()"
* "DurationUnits.strip()"
* "DurationUnits.swapcase()"
* "DurationUnits.translate()"
* "DurationUnits.upper()"
* "DurationUnits.startswith()"
* "DurationUnits.endswith()"
* "DurationUnits.removeprefix()"
* "DurationUnits.removesuffix()"
* "DurationUnits.isascii()"
* "DurationUnits.islower()"
* "DurationUnits.isupper()"
* "DurationUnits.istitle()"
* "DurationUnits.isspace()"
* "DurationUnits.isdecimal()"
* "DurationUnits.isdigit()"
* "DurationUnits.isnumeric()"
* "DurationUnits.isalpha()"
* "DurationUnits.isalnum()"
* "DurationUnits.isidentifier()"
* "DurationUnits.isprintable()"
* "DurationUnits.zfill()"
* "DurationUnits.format()"
* "DurationUnits.format_map()"
* "DurationUnits.maketrans()"
* clockblocks.enums.TempoUnits
* "TempoUnits"
* "TempoUnits.TEMPO"
* "TempoUnits.RATE"
* "TempoUnits.BEATLENGTH"
* "TempoUnits.encode()"
* "TempoUnits.replace()"
* "TempoUnits.split()"
* "TempoUnits.rsplit()"
* "TempoUnits.join()"
* "TempoUnits.capitalize()"
* "TempoUnits.casefold()"
* "TempoUnits.title()"
* "TempoUnits.center()"
* "TempoUnits.count()"
* "TempoUnits.expandtabs()"
* "TempoUnits.find()"
* "TempoUnits.partition()"
* "TempoUnits.index()"
* "TempoUnits.ljust()"
* "TempoUnits.lower()"
* "TempoUnits.lstrip()"
* "TempoUnits.rfind()"
* "TempoUnits.rindex()"
* "TempoUnits.rjust()"
* "TempoUnits.rstrip()"
* "TempoUnits.rpartition()"
* "TempoUnits.splitlines()"
* "TempoUnits.strip()"
* "TempoUnits.swapcase()"
* "TempoUnits.translate()"
* "TempoUnits.upper()"
* "TempoUnits.startswith()"
* "TempoUnits.endswith()"
* "TempoUnits.removeprefix()"
* "TempoUnits.removesuffix()"
* "TempoUnits.isascii()"
* "TempoUnits.islower()"
* "TempoUnits.isupper()"
* "TempoUnits.istitle()"
* "TempoUnits.isspace()"
* "TempoUnits.isdecimal()"
* "TempoUnits.isdigit()"
* "TempoUnits.isnumeric()"
* "TempoUnits.isalpha()"
* "TempoUnits.isalnum()"
* "TempoUnits.isidentifier()"
* "TempoUnits.isprintable()"
* "TempoUnits.zfill()"
* "TempoUnits.format()"
* "TempoUnits.format_map()"
* "TempoUnits.maketrans()"
* clockblocks.exceptions
* clockblocks.metric_phase
* clockblocks.metric_phase.MetricPhaseTarget
* "MetricPhaseTarget"
* "MetricPhaseTarget.get_nearest_matching_beats()"
* "MetricPhaseTarget.get_nearest_matching_times()"
* "MetricPhaseTarget.resolve()"
* clockblocks.moment
* clockblocks.moment.Moment
* "Moment"
* "Moment.at_beat()"
* "Moment.at_time()"
* "Moment.after_beats()"
* "Moment.after_time()"
* "Moment.resolve()"
* "Moment.beat_on()"
* "Moment.scheduler_time()"
* clockblocks.moment.ResolvableMoment
* "ResolvableMoment"
* "ResolvableMoment.resolve()"
* clockblocks.moment.to_absolute_moment
* "to_absolute_moment()"
* clockblocks.scheduler
* clockblocks.scheduler.CompressedTime
* "CompressedTime"
* "CompressedTime.now()"
* "CompressedTime.get_sleep_condition()"
* clockblocks.scheduler.QueueEvent
* "QueueEvent"
* "QueueEvent.t"
* "QueueEvent.priority"
* "QueueEvent.action"
* "QueueEvent.metadata"
* clockblocks.scheduler.Scheduler
* "Scheduler"
* "Scheduler.time"
* "Scheduler.projected_time()"
* "Scheduler.wall_time()"
* "Scheduler.lag()"
* "Scheduler.set_fast_forward_goal()"
* "Scheduler.is_fast_forwarding()"
* "Scheduler.kill()"
* "Scheduler.held()"
* "Scheduler.remove_events()"
* "Scheduler.reschedule()"
* "Scheduler.schedule_action()"
* "Scheduler.run()"
* "Scheduler.daemon"
* "Scheduler.getName()"
* "Scheduler.ident"
* "Scheduler.isDaemon()"
* "Scheduler.is_alive()"
* "Scheduler.join()"
* "Scheduler.name"
* "Scheduler.native_id"
* "Scheduler.setDaemon()"
* "Scheduler.setName()"
* "Scheduler.start()"
* clockblocks.scheduler.TimingBackend
* "TimingBackend"
* "TimingBackend.now()"
* "TimingBackend.get_sleep_condition()"
* clockblocks.tempo_envelope
* clockblocks.tempo_envelope.EnvelopeLoopInfo
* "EnvelopeLoopInfo"
* "EnvelopeLoopInfo.env"
* "EnvelopeLoopInfo.length_in_beats"
* "EnvelopeLoopInfo.length_in_time"
* "EnvelopeLoopInfo.current_end_beat"
* "EnvelopeLoopInfo.current_end_time"
* clockblocks.tempo_envelope.FunctionFollowInfo
* "FunctionFollowInfo"
* "FunctionFollowInfo.func"
* "FunctionFollowInfo.next_domain_start"
* "FunctionFollowInfo.extension_increment"
* "FunctionFollowInfo.units"
* "FunctionFollowInfo.duration_units"
* "FunctionFollowInfo.scanning_step_size"
* "FunctionFollowInfo.min_key_point_distance"
* "FunctionFollowInfo.iterations"
* "FunctionFollowInfo.key_point_resolution_multiple"
* "FunctionFollowInfo.current_end_beat"
* "FunctionFollowInfo.current_end_time"
* clockblocks.tempo_envelope.TempoEnvelope
* "TempoEnvelope"
* "TempoEnvelope.from_levels_and_durations()"
* "TempoEnvelope.from_levels()"
* "TempoEnvelope.from_list()"
* "TempoEnvelope.from_points()"
* "TempoEnvelope.from_function()"
* "TempoEnvelope.beat_length_at()"
* "TempoEnvelope.rate_at()"
* "TempoEnvelope.tempo_at()"
* "TempoEnvelope.extend_to()"
* "TempoEnvelope.truncate_at()"
* "TempoEnvelope.convert_units()"
* "TempoEnvelope.convert_durations_to_times()"
* "TempoEnvelope.show_plot()"
* "TempoEnvelope.is_default()"
* "TempoEnvelope.time_at_beat()"
* "TempoEnvelope.beat_at_time()"
* "TempoEnvelope.adsr()"
* "TempoEnvelope.append_envelope()"
* "TempoEnvelope.append_segment()"
* "TempoEnvelope.ar()"
* "TempoEnvelope.asr()"
* "TempoEnvelope.average_level()"
* "TempoEnvelope.curve_shapes"
* "TempoEnvelope.duplicate()"
* "TempoEnvelope.durations"
* "TempoEnvelope.end_level()"
* "TempoEnvelope.end_time()"
* "TempoEnvelope.from_segments()"
* "TempoEnvelope.get_durations()"
* "TempoEnvelope.get_upper_integration_bound()"
* "TempoEnvelope.insert()"
* "TempoEnvelope.insert_interpolated()"
* "TempoEnvelope.integrate_interval()"
* "TempoEnvelope.is_shifted_version_of()"
* "TempoEnvelope.json_dumps()"
* "TempoEnvelope.json_loads()"
* "TempoEnvelope.length()"
* "TempoEnvelope.levels"
* "TempoEnvelope.load_from_json()"
* "TempoEnvelope.local_extrema()"
* "TempoEnvelope.max_absolute_slope()"
* "TempoEnvelope.max_level()"
* "TempoEnvelope.min_level()"
* "TempoEnvelope.normalize_to_duration()"
* "TempoEnvelope.offset"
* "TempoEnvelope.pop_segment()"
* "TempoEnvelope.pop_segment_from_start()"
* "TempoEnvelope.prepend_envelope()"
* "TempoEnvelope.prepend_segment()"
* "TempoEnvelope.release()"
* "TempoEnvelope.remove_segments_after()"
* "TempoEnvelope.remove_segments_before()"
* "TempoEnvelope.save_to_json()"
* "TempoEnvelope.scale_horizontal()"
* "TempoEnvelope.scale_vertical()"
* "TempoEnvelope.shift_horizontal()"
* "TempoEnvelope.shift_vertical()"
* "TempoEnvelope.simplified()"
* "TempoEnvelope.split_at()"
* "TempoEnvelope.start_level()"
* "TempoEnvelope.start_time()"
* "TempoEnvelope.times"
* "TempoEnvelope.value_at()"
* clockblocks.tempo_envelope.TempoHistory
* "TempoHistory"
* "TempoHistory.follow_func_or_envelope_loop"
* "TempoHistory.from_tempo_envelope()"
* "TempoHistory.time"
* "TempoHistory.beat"
* "TempoHistory.beat_length"
* "TempoHistory.rate"
* "TempoHistory.tempo"
* "TempoHistory.time_at_beat()"
* "TempoHistory.beat_at_time()"
* "TempoHistory.append_envelope()"
* "TempoHistory.set_beat_length_target()"
* "TempoHistory.set_rate_target()"
* "TempoHistory.set_tempo_target()"
* "TempoHistory.apply_function()"
* "TempoHistory.stop_follow_function_or_envelope_loop()"
* "TempoHistory.advance()"
* "TempoHistory.go_to_beat()"
* "TempoHistory.truncate_at()"
* "TempoHistory.truncate()"
* "TempoHistory.adsr()"
* "TempoHistory.append_segment()"
* "TempoHistory.ar()"
* "TempoHistory.asr()"
* "TempoHistory.average_level()"
* "TempoHistory.beat_length_at()"
* "TempoHistory.convert_durations_to_times()"
* "TempoHistory.convert_units()"
* "TempoHistory.curve_shapes"
* "TempoHistory.duplicate()"
* "TempoHistory.durations"
* "TempoHistory.end_level()"
* "TempoHistory.end_time()"
* "TempoHistory.extend_to()"
* "TempoHistory.from_function()"
* "TempoHistory.from_levels()"
* "TempoHistory.from_levels_and_durations()"
* "TempoHistory.from_list()"
* "TempoHistory.from_points()"
* "TempoHistory.from_segments()"
* "TempoHistory.get_durations()"
* "TempoHistory.get_upper_integration_bound()"
* "TempoHistory.insert()"
* "TempoHistory.insert_interpolated()"
* "TempoHistory.integrate_interval()"
* "TempoHistory.is_default()"
* "TempoHistory.is_shifted_version_of()"
* "TempoHistory.json_dumps()"
* "TempoHistory.json_loads()"
* "TempoHistory.length()"
* "TempoHistory.levels"
* "TempoHistory.load_from_json()"
* "TempoHistory.local_extrema()"
* "TempoHistory.max_absolute_slope()"
* "TempoHistory.max_level()"
* "TempoHistory.min_level()"
* "TempoHistory.normalize_to_duration()"
* "TempoHistory.offset"
* "TempoHistory.pop_segment()"
* "TempoHistory.pop_segment_from_start()"
* "TempoHistory.prepend_envelope()"
* "TempoHistory.prepend_segment()"
* "TempoHistory.rate_at()"
* "TempoHistory.release()"
* "TempoHistory.remove_segments_after()"
* "TempoHistory.remove_segments_before()"
* "TempoHistory.save_to_json()"
* "TempoHistory.scale_horizontal()"
* "TempoHistory.scale_vertical()"
* "TempoHistory.shift_horizontal()"
* "TempoHistory.shift_vertical()"
* "TempoHistory.show_plot()"
* "TempoHistory.simplified()"
* "TempoHistory.split_at()"
* "TempoHistory.start_level()"
* "TempoHistory.start_time()"
* "TempoHistory.tempo_at()"
* "TempoHistory.times"
* "TempoHistory.value_at()"
* "TempoHistory.as_tempo_envelope()"
* clockblocks.tempo_envelope.tempo_modification
* "tempo_modification()"
* clockblocks.time_stamp
* clockblocks.time_stamp.TimeStamp
* "TimeStamp"
* "TimeStamp.now()"
* "TimeStamp.time_in_master"
* "TimeStamp.beat_in_clock()"
* "TimeStamp.time_in_clock()"
* clockblocks.time_stamp.TimeStampInterval
* "TimeStampInterval"
* "TimeStampInterval.time_duration_in_master"
* "TimeStampInterval.beats_duration_in_clock()"
* "TimeStampInterval.time_duration_in_clock()"
* clockblocks.utilities
* clockblocks.utilities.apply_beat_length_function
* "apply_beat_length_function()"
* clockblocks.utilities.apply_rate_function
* "apply_rate_function()"
* clockblocks.utilities.apply_tempo_envelope
* "apply_tempo_envelope()"
* clockblocks.utilities.apply_tempo_function
* "apply_tempo_function()"
* clockblocks.utilities.current_clock
* "current_clock()"
* clockblocks.utilities.fork
* "fork()"
* clockblocks.utilities.get_beat
* "get_beat()"
* clockblocks.utilities.get_beat_length
* "get_beat_length()"
* clockblocks.utilities.get_rate
* "get_rate()"
* clockblocks.utilities.get_tempo
* "get_tempo()"
* clockblocks.utilities.get_time
* "get_time()"
* clockblocks.utilities.meaningfully_greater_than
* "meaningfully_greater_than()"
* clockblocks.utilities.meaningfully_less_than
* "meaningfully_less_than()"
* clockblocks.utilities.near_equal
* "near_equal()"
* clockblocks.utilities.set_beat_length
* "set_beat_length()"
* clockblocks.utilities.set_beat_length_target
* "set_beat_length_target()"
* clockblocks.utilities.set_beat_length_targets
* "set_beat_length_targets()"
* clockblocks.utilities.set_rate
* "set_rate()"
* clockblocks.utilities.set_rate_target
* "set_rate_target()"
* clockblocks.utilities.set_rate_targets
* "set_rate_targets()"
* clockblocks.utilities.set_tempo
* "set_tempo()"
* clockblocks.utilities.set_tempo_target
* "set_tempo_target()"
* clockblocks.utilities.set_tempo_targets
* "set_tempo_targets()"
* clockblocks.utilities.stop_tempo_loop_or_function
* "stop_tempo_loop_or_function()"
* clockblocks.utilities.terminate_forked_children
* "terminate_forked_children()"
* clockblocks.utilities.wait
* "wait()"
* clockblocks.utilities.wait_for_children_to_finish
* "wait_for_children_to_finish()"
* clockblocks.utilities.wait_for_clock_to_finish
* "wait_for_clock_to_finish()"
* clockblocks.utilities.wait_forever
* "wait_forever()"
* clockblocks.utilities.wait_until
* "wait_until()"
-[ Public-Facing API (result of *import **): ]-
+------------+--------------------------------------------------------------------------------------------+
| "Clock"([n | Recursively nestable clock. |
| ame, | |
| parent, in | |
| itial_rate | |
| , ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "ClockFami | Fine-tuning options for a clock family, passed to a master "Clock" on construction. |
| lyOptions" | |
| ([timing_p | |
| olicy, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "ClockStat | Where a clock sits in its lifecycle. |
| e"(*values | |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "DurationU | Units with which we measure duration or Moment positioning. |
| nits"(*val | |
| ues) | |
+------------+--------------------------------------------------------------------------------------------+
| "TempoUnit | The three different, and mutually determined, ways of expressing tempo. |
| s"(*values | |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "ClockKill | Raised inside a forked clock's own thread when its wait is woken by kill(), so the fork |
| edError" | wrapper can unwind the user function cleanly. |
+------------+--------------------------------------------------------------------------------------------+
| "Clockbloc | Base class for clockblocks errors. |
| ksError" | |
+------------+--------------------------------------------------------------------------------------------+
| "DeadClock | Raised when something tries to wait or fork on a clock that's no longer ALIVE (either |
| Error" | killed already, or — for fork — still PENDING in its start_delay). |
+------------+--------------------------------------------------------------------------------------------+
| "NoActiveC | Raised when a context-inferring clock operation (the module-level wait/fork/etc.) is |
| lockError" | attempted from a thread that has no clock active on it. |
+------------+--------------------------------------------------------------------------------------------+
| "NotMaster | Raised by operations that are only valid on the master (top-level) clock — e.g. |
| ClockError | run_as_server() — when called on a child clock. |
| " | |
+------------+--------------------------------------------------------------------------------------------+
| "Scheduler | Raised when wait() is called from a thread that is holding the scheduler via |
| HeldError" | hold_scheduler() — most commonly inside a MIDI / OSC / HID callback, which runs under such |
| | a hold. |
+------------+--------------------------------------------------------------------------------------------+
| "WrongThre | Raised when wait() is called from a thread that doesn't own the clock. |
| adError" | |
+------------+--------------------------------------------------------------------------------------------+
| "PackageNo | The package was not found. |
| tFoundErro | |
| r" | |
+------------+--------------------------------------------------------------------------------------------+
| "version"( | Get the version string for the named package. |
| distributi | |
| on_name) | |
+------------+--------------------------------------------------------------------------------------------+
| "MetricPha | Class representing a particular point in a (beat or measure) cycle. |
| seTarget"( | |
| phase_or_p | |
| hases[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "Moment"(v | Represents a point on a clock's timeline. |
| alue[, | |
| units, | |
| relative]) | |
+------------+--------------------------------------------------------------------------------------------+
| "Resolvabl | Anything that can name a point on a clock's timeline. |
| eMoment"(* | |
| args, | |
| **kwargs) | |
+------------+--------------------------------------------------------------------------------------------+
| "Compresse | A "TimingBackend" that runs scaled real time: "now()" advances "factor" times faster and |
| dTime"([fa | the sleep condition's "wait()" divides its timeout by "factor". |
| ctor]) | |
+------------+--------------------------------------------------------------------------------------------+
| "TimingBac | The scheduler's pluggable source of "now" and of the condition it uses for waiting. |
| kend"() | |
+------------+--------------------------------------------------------------------------------------------+
| "TempoEnve | A subclass of "Envelope" that is specifically designed for representing changing tempo |
| lope"([lev | curves. |
| els, | |
| durations, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "TempoHist | Subclass of TempoEnvelope that keeps track of a current beat and time, and provides |
| ory"([leve | functionality for moving forward a certain number of beats or seconds, and/or setting |
| ls, | tempo target(s) to reach in the future. |
| durations, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "TimeStamp | A clock-agnostic point on the scheduler's timeline, projectable into any clock's beat or |
| "(schedule | time axis on demand. |
| r_time, ma | |
| ster_clock | |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "TimeStamp | The oriented span between two moments on the scheduler's timeline, produced by subtracting |
| Interval"( | two TimeStamps ("end_stamp - start_stamp"). |
| start_sche | |
| duler_time | |
| , ...) | |
+------------+--------------------------------------------------------------------------------------------+
| "apply_bea | Drive the current clock's beat length (in seconds per beat) by following a function of |
| t_length_f | beats/time. |
| unction"(f | |
| unction[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "apply_rat | Drive the current clock's rate (in beats per second) by following a function of |
| e_function | beats/time. |
| "(function | |
| [, ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "apply_tem | Append a ready-made "TempoEnvelope" onto the current clock's tempo curve. |
| po_envelop | |
| e"(envelop | |
| e[, | |
| truncate, | |
| loop]) | |
+------------+--------------------------------------------------------------------------------------------+
| "apply_tem | Drive the current clock's tempo (in beats per minute) by following a function of |
| po_functio | beats/time. |
| n"(functio | |
| n[, ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "current_c | Get the "Clock" active on the current thread, or None if none is active. |
| lock"() | |
+------------+--------------------------------------------------------------------------------------------+
| "fork"(for | Run "forked_function" on a new child clock of the currently active clock, so it proceeds |
| ked_functi | in parallel while staying coordinated under the same musical time. |
| on[, args, | |
| kwargs, | |
| name, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "get_beat" | Return how many beats have passed on the currently active clock (see "beat"). |
| () | |
+------------+--------------------------------------------------------------------------------------------+
| "get_beat_ | Return the current beat length (in seconds per beat) of the currently active clock (see |
| length"() | "beat_length"). |
+------------+--------------------------------------------------------------------------------------------+
| "get_rate" | Return the current rate (in beats per second) of the currently active clock (see "rate"). |
| () | |
+------------+--------------------------------------------------------------------------------------------+
| "get_tempo | Return the current tempo (in beats per minute) of the currently active clock (see |
| "() | "tempo"). |
+------------+--------------------------------------------------------------------------------------------+
| "get_time" | Return how much time has passed on the currently active clock (see "time") — in seconds if |
| () | it is the master clock, or parent clock beats if it is a forked child clock. |
+------------+--------------------------------------------------------------------------------------------+
| "set_beat_ | Immediately set the beat length of the current clock (see "beat_length"). |
| length"(be | |
| at_length) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_beat_ | Smoothly change the current clock's beat length to "beat_length_target" (in seconds per |
| length_tar | beat), arriving at "when". |
| get"(beat_ | |
| length_tar | |
| get, when) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_beat_ | Set several beat-length targets at once, building a multi-segment tempo curve on the |
| length_tar | current clock. |
| gets"(beat | |
| _length_ta | |
| rgets, | |
| ...) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_rate" | Immediately set the rate of the current clock (see "rate"). |
| (rate) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_rate_ | Smoothly change the current clock's rate to "rate_target" (in beats per second), arriving |
| target"(ra | at "when". |
| te_target, | |
| when[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_rate_ | Set several rate targets at once, building a multi-segment tempo curve on the current |
| targets"(r | clock. |
| ate_target | |
| s, whens[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_tempo | Immediately set the tempo of the current clock (see "tempo"). |
| "(tempo) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_tempo | Smoothly change the current clock's tempo to "tempo_target" (in beats per minute), |
| _target"(t | arriving at "when". |
| empo_targe | |
| t, when[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "set_tempo | Set several tempo targets at once, building a multi-segment tempo curve on the current |
| _targets"( | clock. |
| tempo_targ | |
| ets, | |
| whens[, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+
| "stop_temp | Stop following any function or looping envelope previously started on the current clock's |
| o_loop_or_ | tempo (via "apply_tempo_function()"/"apply_rate_fu |
| function"( | nction()"/"apply_beat_length_function()" or a looping "apply_tempo_envelope()"). |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "terminate | Kill the child clocks of the currently active clock, returning once they have finished |
| _forked_ch | unwinding (see "terminate_forked_children()"). |
| ildren"() | |
+------------+--------------------------------------------------------------------------------------------+
| "wait"(dt[ | Block the clock currently active on this thread for "dt" beats (or seconds, if |
| , units]) | "units="time""), yielding to the scheduler. |
+------------+--------------------------------------------------------------------------------------------+
| "wait_for_ | Block on the currently active clock until its child clocks have finished (see |
| children_t | "wait_for_children_to_finish()"). |
| o_finish"( | |
| ) | |
+------------+--------------------------------------------------------------------------------------------+
| "wait_for_ | Block on the currently active clock until *clock* has finished (see |
| clock_to_f | "wait_for_clock_to_finish()"). |
| inish"(clo | |
| ck) | |
+------------+--------------------------------------------------------------------------------------------+
| "wait_fore | Block forever on the currently active clock (see "wait_forever()") — usually to keep the |
| ver"() | main script alive while child clocks do the work. |
+------------+--------------------------------------------------------------------------------------------+
| "wait_unti | Block the clock currently active on this thread until the *absolute* beat (or time, if |
| l"(when[, | "units="time"") given by "when". |
| units]) | |
+------------+--------------------------------------------------------------------------------------------+