======================================================================
=== 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])    |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+