clockblocks.clock.Clock
- class clockblocks.clock.Clock(name: Optional[str] = None, parent: Optional[Clock] = None, initial_rate: Optional[float] = None, initial_tempo: Optional[float] = None, initial_beat_length: Optional[float] = None, timing_policy: str | float = 0.98, synchronization_policy: Optional[str] = None, pool_size: int = 200)[source]
Bases:
objectRecursively nestable clock class. Clocks can fork child-clocks, which can in turn fork their own child-clock. Only the master clock calls sleep; child-clocks instead register _WakeUpCalls with their parents, who register wake-up calls with their parents all the way up to the master clock.
- 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)
timing_policy – either “relative”, “absolute”, or a float between 0 and 1 representing a balance between the two. “relative” attempts to keeps each wait call as faithful as possible to what it should be. This can result in the clock getting behind real time, since if heavy processing causes us to get behind on one note we never catch up. “absolute” tries instead to stay faithful to the time since the clock began. If one wait is too long due to heavy processing, later delays will be shorter to try to catch up. This can result in inaccuracies in relative timing. Setting the timing policy to a float between 0 and 1 implements a hybrid approach in which, when the clock gets behind, it is allowed to catch up somewhat, but only to a certain extent. (0 is equivalent to absolute timing, 1 is equivalent to relative timing.)
synchronization_policy – either None or one of “all relatives”, “all descendants”, “no synchronization”, or “inherit”. Since a clock is woken up by its parent clock, it will always remain synchronized with all parents / grandparents / etc; however, if you ask one of its children what time / beat it is on, it may have old information, since it has been asleep. If the synchronization_policy is set to “no synchronization”, then we live with this, but if it is set to “all descendants” then we take the time (and CPU cycles) to catch up all its descendants so that they read the correct time. Nevertheless, cousin clocks (other descendants of this clock’s parent) may still not be caught up, so the “all relatives” policy makes sure that all descendants of the master clock - no matter how they are related to this clock - will have up-to-date information about what time / beat they are on whenever this clock wakes up. This is the default setting, since it avoids inaccurate information, but if there are a lot of clocks it may be valuable to turn off relative synchronization if it’s slowing things down. The value “inherit” means that this clock inherits its synchronization policy from its master. If no value is specified, then it defaults to “all relatives” for the master clock and “inherit” for all descendants, which in practice means that all clocks will synchronize with all relatives upon waking.
pool_size – the size of the process pool for unsynchronized forks, which are used for playing notes. Only has an effect if this is the master clock.
- 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
The beat length of this clock in (true) seconds, accounting for the rates of all parent clocks.
The rate of this clock in beats / (true) second, accounting for the rates of all parent clocks.
The tempo of this clock in beats / (true) minute, accounting for the rates of all parent clocks.
apply_beat_length_function(function[, ...])Applies a function to be used to set the beat_length (and therefore rate and tempo) of this clock.
apply_rate_function(function[, ...])Applies a function to be used to set the rate (and therefore beat_length and tempo) of this clock.
apply_tempo_function(function[, ...])Applies a function to be used to set the tempo (and therefore beat_length and rate) of this clock.
beat()How many beats have passed since this clock was created.
children()Get all direct child clocks forked by this clock.
Get all children, grandchildren, etc.
Extracts this clock's absolute TempoHistory (as opposed to the TempoHistory relative to parent clock).
fast_forward([on_or_off])Set fast-forwarding of the clock; when fast-forwarding, all waiting is instantaneous.
Fast-forward clock, skipping ahead instantaneously by b beats.
Fast-forward clock, skipping ahead instantaneously by t seconds.
Fast-forward clock, skipping instantaneously to beat b.
Fast-forward clock, skipping instantaneously to the time of t seconds.
fork(process_function[, args, kwargs, name, ...])Spawns a parallel process running on a child clock.
fork_unsynchronized(process_function[, ...])Spawns a parallel process, but as an asynchronous thread, not on a child clock.
inheritance([include_self])Get all parent, grandparent, etc.
Determine if the clock is fast-forwarding.
Check if this is the master clock
iterate_all_relatives([include_self])Iterate through all related clocks to this clock.
iterate_descendants([include_self])Iterate through all children, grandchildren, etc.
iterate_inheritance([include_self])Iterate through parent, grandparent, etc.
kill()Ends the process forked on this clock and all child processes.
Enables logging statements about calculation time between wait calls.
Print a hierarchical representation of this clock's family tree.
release_from_suspension([releasing_clock])Called after "rouse_and_hold" to release the roused clock.
rouse_and_hold([holding_clock])Rouse this clock if it is dormant, but keep it suspended until release_from_suspension is called.
Runs this clock on a parallel thread so that it can act as a server.
set_beat_length_target(beat_length_target, ...)Set a target beat length for this clock to reach in duration beats/seconds (with the unit defined by duration_units).
set_beat_length_targets(beat_length_targets, ...)Same as set_beat_length_target, except that you can set multiple targets at once by providing lists to each of the arguments.
set_rate_target(rate_target, duration[, ...])Set a target rate for this clock to reach in duration beats/seconds (with the unit defined by duration_units)
set_rate_targets(rate_targets, durations[, ...])Same as set_rate_target, except that you can set multiple targets at once by providing lists to each of the arguments.
set_tempo_target(tempo_target, duration[, ...])Set a target tempo for this clock to reach in duration beats/seconds (with the unit defined by duration_units)
set_tempo_targets(tempo_targets, durations)Same as set_tempo_target, except that you can set multiple targets at once by providing lists to each of the arguments.
Disables logging statements about calculation time between wait calls.
If we set up a looping list of tempo targets, this stops that looping process.
time()How much time has passed since this clock was created.
How much time (in seconds) has passed since the master clock was created.
This timing policy only cares about keeping the time since the clock start accurate to what it should be.
use_mixed_timing_policy(absolute_relative_mix)Balance considerations of relative timing and absolute timing accuracy according to the given coefficient
This timing policy only cares about making each individual wait call as accurate as possible.
wait(dt[, units, sub_call])Causes the current thread to block for dt beats (or seconds if units="time") in this clock.
Causes this thread to block until all forked child processes have finished.
Causes this thread to block forever.
Attributes
Whether or not this clock is still running
The length of a beat in this clock in seconds.
The master clock under which this clock operates (possibly itself)
The rate of this clock in beats / second.
Determines whether or not this clock actively updates the beat and time of related clocks when it wakes up.
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.
Determines how this clock should respond to getting behind.
- is_master() bool[source]
Check if this is the master clock
- Returns:
True if this is the master clock, False otherwise
- children() Sequence[Clock][source]
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][source]
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][source]
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][source]
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][source]
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][source]
Get all children, grandchildren, etc. of this clock
- Returns:
tuple of all descendants
- property synchronization_policy: str
Determines whether or not this clock actively updates the beat and time of related clocks when it wakes up. Allowable values are “all relatives”, “all descendants”, “no synchronization”, and “inherit”. If “inherit” then it will adopt the setting of its parent clock. The default is to keep all clocks up-to-date. Turning off synchronization can save calculation time, but it can lead to clocks giving old information about what beat or time it is when asked from a different clock’s process.
- property timing_policy: str | float
Determines how this clock should respond to getting behind. Allowable values are “absolute”, “relative” or a float between 0 and 1 representing a balance between absolute and relative.
- use_absolute_timing_policy() None[source]
This timing policy only cares about keeping the time since the clock start accurate to what it should be. The downside is that relative timings get distorted when it falls behind.
- use_relative_timing_policy() None[source]
This timing policy only cares about making each individual wait call as accurate as possible. The downside is that long periods of calculation cause the clock to drift and get behind.
- use_mixed_timing_policy(absolute_relative_mix: float) None[source]
Balance considerations of relative timing and absolute timing accuracy according to the given coefficient
- Parameters:
absolute_relative_mix – a float representing the minimum proportion of the ideal wait time we are willing to wait in order to catch up to the correct absolute time since the clock started.
- time() float[source]
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.
- time_in_master() float[source]
How much time (in seconds) has passed since the master clock was created.
- 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.
- absolute_rate() float[source]
The rate of this clock in beats / (true) second, accounting for the rates of all parent clocks. (As opposed to rate, which just gives the rate relative to the parent clock.)
- absolute_tempo() float[source]
The tempo of this clock in beats / (true) minute, accounting for the rates of all parent clocks. (As opposed to tempo, which just gives the tempo relative to the parent clock.)
- absolute_beat_length() float[source]
The beat length of this clock in (true) seconds, accounting for the rates of all parent clocks. (As opposed to beat_length, which just gives the length in parent beats.)
- set_beat_length_target(beat_length_target: float, duration: float, curve_shape: float = 0, metric_phase_target: float | MetricPhaseTarget | tuple = None, duration_units: str = 'beats', truncate: bool = True) None[source]
Set a target beat length for this clock 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
metric_phase_target – This argument lets us align the arrival at the given beat length with a particular part of the parent beat (time), or, if we specified “time” as our duration units, it allows us to align the arrival at that specified time with a particular part of this clock’s beat. This argument takes either a float in [0, 1), a MetricPhaseTarget object, or a tuple of arguments to the MetricPhaseTarget constructor
duration_units – one of (“beats”, “time”); defines whether the duration is in beats or in seconds/parent beats.
truncate – Whether or not to delete all future tempo plans before setting this goal.
- set_rate_target(rate_target: float, duration: float, curve_shape: float = 0, metric_phase_target: float | MetricPhaseTarget | tuple = None, duration_units: str = 'beats', truncate: bool = True) None[source]
Set a target rate for this clock to reach in duration beats/seconds (with the unit defined by duration_units)
- Parameters:
rate_target – The rate we want to reach
duration – How long until we reach that tempo
curve_shape – > 0 makes change happen later, < 0 makes change happen sooner
metric_phase_target – This argument allows us to align the arrival at the given rate with a particular part of the parent beat (time), or, if we specified “time” as our duration units, it allows us to align the arrival at that specified time with a particular part of this clock’s beat. This argument takes either a float in [0, 1), a MetricPhaseTarget object, or a tuple of arguments to the MetricPhaseTarget constructor
duration_units – one of (“beats”, “time”); defines whether the duration is in beats or in seconds/parent beats.
truncate – Whether or not to delete all future tempo plans before setting this goal.
- set_tempo_target(tempo_target: float, duration: float, curve_shape: float = 0, metric_phase_target: float | MetricPhaseTarget | tuple = None, duration_units: str = 'beats', truncate: bool = True) None[source]
Set a target tempo for this clock to reach in duration beats/seconds (with the unit defined by duration_units)
- Parameters:
tempo_target – The tempo we want to reach
duration – How long until we reach that tempo
curve_shape – > 0 makes change happen later, < 0 makes change happen sooner
metric_phase_target – This argument allows us to align the arrival at the given tempo with a particular part of the parent beat (time), or, if we specified “time” as our duration units, it allows us to align the arrival at that specified time with a particular part of this clock’s beat. This argument takes either a float in [0, 1), a MetricPhaseTarget object, or a tuple of arguments to the MetricPhaseTarget constructor
duration_units – one of (“beats”, “time”); defines whether the duration is in beats or in seconds/parent beats.
truncate – Whether or not to delete all future tempo plans before setting this goal.
- set_beat_length_targets(beat_length_targets: Sequence[float], durations: Sequence[float], curve_shapes: Sequence[float] = None, metric_phase_targets: Sequence[float | MetricPhaseTarget | tuple] = None, duration_units: str = 'beats', truncate: bool = True, loop: bool = False) None[source]
Same as set_beat_length_target, except that you can set multiple targets at once by providing lists to each of the arguments.
- Parameters:
beat_length_targets – list of the target beat_lengths
durations – list of segment durations (in beats or seconds, as defined by duration_units)
curve_shapes – list of segment curve_shapes (or none to not set curve shape)
metric_phase_targets – list of metric phase targets for each segment (or None to ignore metric phase)
duration_units – one of (“beats”, “time”); defines whether the duration is in beats or in seconds/parent beats.
truncate – Whether or not to delete all future tempo plans before setting these targets.
loop – If true, loops the added sequence of targets indefinitely, or until stop_tempo_loop_or_function is called.
- set_rate_targets(rate_targets: Sequence[float], durations: Sequence[float], curve_shapes: Sequence[float] = None, metric_phase_targets: Sequence[float | MetricPhaseTarget | tuple] = None, duration_units: str = 'beats', truncate: bool = True, loop: bool = False) None[source]
Same as set_rate_target, except that you can set multiple targets at once by providing lists to each of the arguments.
- Parameters:
rate_targets – list of the target rates
durations – list of segment durations (in beats or seconds, as defined by duration_units)
curve_shapes – list of segment curve_shapes (or none to not set curve shape)
metric_phase_targets – list of metric phase targets for each segment (or None to ignore metric phase)
duration_units – one of (“beats”, “time”); defines whether the duration is in beats or in seconds/parent beats.
truncate – Whether or not to delete all future tempo plans before setting these targets.
loop – If true, loops the added sequence of targets indefinitely, or until stop_tempo_loop_or_function is called.
- set_tempo_targets(tempo_targets: Sequence[float], durations: Sequence[float], curve_shapes: Sequence[float] = None, metric_phase_targets: Sequence[float | MetricPhaseTarget | tuple] = None, duration_units: str = 'beats', truncate: bool = True, loop: bool = False) None[source]
Same as set_tempo_target, except that you can set multiple targets at once by providing lists to each of the arguments.
- Parameters:
tempo_targets – list of the target tempos
durations – list of segment durations (in beats or seconds, as defined by duration_units)
curve_shapes – list of segment curve_shapes (or none to not set curve shape)
metric_phase_targets – list of metric phase targets for each segment (or None to ignore metric phase)
duration_units – one of (“beats”, “time”); defines whether the duration is in beats or in seconds/parent beats.
truncate – Whether or not to delete all future tempo plans before setting these targets.
loop – If true, loops the added sequence of targets indefinitely, or until stop_tempo_loop_or_function is called.
- stop_tempo_loop_or_function() None[source]
If we set up a looping list of tempo targets, this stops that looping process. It also stops extending any tempo function that we set up to go indefinitely.
- 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, scanning_step_size: float = 0.05, key_point_resolution_multiple: int = 2, iterations: int = 6, min_key_point_distance: float = 1e-07) None[source]
Applies a function to be used to set the beat_length (and therefore rate and tempo) of this clock.
- Parameters:
function – a function (usually a lambda function) taking a single argument representing the beat or the time (depending on the ‘duration_units’ argument) and outputting the beat_length. Note that the beat or time argument is measured in relation to the moment that apply_beat_length_function was called, not from the start of the clock.
domain_start – along with domain_end, allows us to specify a specific portion of the function to be used
domain_end – along with domain_start, allows us to specify a specific portion of the function to be used. If None, the tempo continues to be defined according to the function formula.
duration_units – either “beats” or “time”, depending on what the function argument refers to
truncate – whether or not to remove all future plans before applying this function
loop – If a finite portion of the function’s domain is being used, this argument will loop that portion of the domain when we come to the end of it.
extension_increment – if domain_end is None, then this defines how far in advance we extend the function at any given time.
scanning_step_size – see
Envelope.from_function()key_point_resolution_multiple – see
Envelope.from_function()iterations – see
Envelope.from_function()min_key_point_distance – see
Envelope.from_function()
- 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, scanning_step_size: float = 0.05, key_point_resolution_multiple: int = 2, iterations: int = 6, min_key_point_distance: float = 1e-07) None[source]
Applies a function to be used to set the rate (and therefore beat_length and tempo) of this clock.
- Parameters:
function – a function (usually a lambda function) taking a single argument representing the beat or the time (depending on the ‘duration_units’ argument) and outputting the rate. Note that the beat or time argument is measured in relation to the moment that apply_beat_length_function was called, not from the start of the clock.
domain_start – along with domain_end, allows us to specify a specific portion of the function to be used
domain_end – along with domain_start, allows us to specify a specific portion of the function to be used. If None, the tempo continues to be defined according to the function formula.
duration_units – either “beats” or “time”, depending on what the function argument refers to
truncate – whether or not to remove all future plans before applying this function
loop – If a finite portion of the function’s domain is being used, this argument will loop that portion of the domain when we come to the end of it.
extension_increment – if domain_end is None, then this defines how far in advance we extend the function at any given time.
scanning_step_size – see
Envelope.from_function()key_point_resolution_multiple – see
Envelope.from_function()iterations – see
Envelope.from_function()min_key_point_distance – see
Envelope.from_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, scanning_step_size: float = 0.05, key_point_resolution_multiple: int = 2, iterations: int = 6, min_key_point_distance: float = 1e-07) None[source]
Applies a function to be used to set the tempo (and therefore beat_length and rate) of this clock.
- Parameters:
function – a function (usually a lambda function) taking a single argument representing the beat or the time (depending on the ‘duration_units’ argument) and outputting the tempo in BPM. Note that the beat or time argument is measured in relation to the moment that apply_beat_length_function was called, not from the start of the clock.
domain_start – along with domain_end, allows us to specify a specific portion of the function to be used
domain_end – along with domain_start, allows us to specify a specific portion of the function to be used. If None, the tempo continues to be defined according to the function formula.
duration_units – either “beats” or “time”, depending on what the function argument refers to
truncate – whether or not to remove all future plans before applying this function
loop – If a finite portion of the function’s domain is being used, this argument will loop that portion of the domain when we come to the end of it.
extension_increment – if domain_end is None, then this defines how far in advance we extend the function at any given time.
scanning_step_size – see
Envelope.from_function()key_point_resolution_multiple – see
Envelope.from_function()iterations – see
Envelope.from_function()min_key_point_distance – see
Envelope.from_function()
- fork(process_function: Callable, args: Sequence = (), kwargs: Optional[dict] = None, name: Optional[str] = None, initial_rate: Optional[float] = None, initial_tempo: Optional[float] = None, initial_beat_length: Optional[float] = None, schedule_at: Optional[Union[float, MetricPhaseTarget]] = None, done_callback: Optional[Callable] = None) Clock[source]
Spawns a parallel process running on a child clock.
- Parameters:
process_function – function defining the process to be spawned
args – arguments to be passed to the process function. One subtlety to note here: if the number of arguments passed is one fewer than the number taken by the function, the clock on which the process is forked will be passed as the first argument, followed by the arguments given. For instance, if we define “forked_function(clock, a, b)”, and then call “parent.fork(forked_function, (13, 6))”, 13 will be passed to “a” and 6 to “b”, while the clock on which forked_function is running will be passed to “clock”. On the other hand, if the signature of the function were “forked_function(a, b)”, 13 would be simply be passed to “a” and 6 to “b”.
kwargs – keyword arguments to be passed to the process function
name – name to be given to the clock of the spawned child process
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)
schedule_at – either a beat or a
MetricPhaseTargetspecifying when we want this forked process to begin. The default value of None indicates that it is to begin immediately. A float indicates the beat in this clock at which the process is to start (should be in the future). Alternatively, a MetricPhaseTarget can be used to specify where in a regular cycle the process should begin. For instance, if we want to sync every fork to 3/4 time, MetricPhaseTarget(0, 3) would start a process on the downbeat, MetricPhaseTarget(1, 3) would start it on beat 2, and MetricPhaseTarget(2.5, 3) would start it halfway through beat 3.done_callback – a callback function to be invoked when the clock has terminated
- Returns:
the clock of the spawned child process
- kill() None[source]
Ends the process forked on this clock and all child processes. If this is the master clock, since it wasn’t forked, this simply kills all child processes.
- property alive: bool
Whether or not this clock is still running
- Returns:
True if running, False if it was killed or its process ended.
- fork_unsynchronized(process_function: Callable, args: Sequence = (), kwargs: Optional[dict] = None) None[source]
Spawns a parallel process, but as an asynchronous thread, not on a child clock. (Still makes use of this clock’s ThreadPool, so it’s quicker to spawn than creating a new Thread)
- Parameters:
process_function – the process to be spawned
args – arguments for that function
kwargs – keyword arguments for that function
- run_as_server() T[source]
Runs this clock on a parallel thread so that it can act as a server. This is the approach that should be taken if running clockblocks from an interactive terminal session. Simply type
c = Clock().run_as_server()- Returns:
self
- wait(dt: float, units: str = 'beats', sub_call: bool = False) float[source]
Causes the current thread to block for dt beats (or seconds if units=”time”) in this clock.
- Parameters:
dt – the number of beats in this clock
units – either “beats” or “time”. If time, then it ignores the rate of this clock, and waits in seconds (or in parent clock beats, if this is a sub-clock)
sub_call – flag that wouldn’t matter to the user, but indicates whether this wait call was called from within another wait call.
- Returns:
0 if this wait call is uninterrupted, otherwise the amount of beats that remained when interrupted
- wait_for_children_to_finish() None[source]
Causes this thread to block until all forked child processes have finished.
- wait_forever() None[source]
Causes this thread to block forever. Generally called from a parent clock when actions are being carried out on child clocks, or as a result of callback functions.
- rouse_and_hold(holding_clock: Optional[Clock] = None) None[source]
Rouse this clock if it is dormant, but keep it suspended until release_from_suspension is called. Generally this would not be called by the user, but it is useful for callback functions operating outside of the clock system, since they can wake up the clock of interest, carry out what they need to carry out and then release the clock from suspension.
- Parameters:
holding_clock – when rouse_and_hold is called on a child clock, all parents/grandparents/etc. must also be roused and held. However, we need to keep track of the child clock that started the whole process. That’s what this argument is for. (It’s an implementation detail).
- release_from_suspension(releasing_clock: Optional[Clock] = None) None[source]
Called after “rouse_and_hold” to release the roused clock.
- Parameters:
releasing_clock – the clock providing the initial impetus to release from suspension. Just like rouse_and_hold, a release propagates up the family tree, but we need to keep track of the initial clock from which it propagates. (Again, this is an implementation detail.
- fast_forward(on_or_off=True) None[source]
Set fast-forwarding of the clock; when fast-forwarding, all waiting is instantaneous. (Only available on the master clock.)
- Parameters:
on_or_off – if True, start fast-forwarding; if False, stop fast-forwarding.
- fast_forward_to_time(t: float) None[source]
Fast-forward clock, skipping instantaneously to the time of t seconds. (Only available on the master clock.)
- Parameters:
t – time to fast forward to
- fast_forward_in_time(t: float) None[source]
Fast-forward clock, skipping ahead instantaneously by t seconds. (Only available on the master clock.)
- Parameters:
t – number of seconds to fast forward by
- fast_forward_to_beat(b: float) None[source]
Fast-forward clock, skipping instantaneously to beat b. (Only available on the master clock.)
- Parameters:
b – beat to fast forward to
- fast_forward_in_beats(b: float) None[source]
Fast-forward clock, skipping ahead instantaneously by b beats. (Only available on the master clock.)
- Parameters:
b – number of beats to fast forward by
- is_fast_forwarding() bool[source]
Determine if the clock is fast-forwarding.
- Returns:
boolean representing whether the clock is fast-forwarding
- log_processing_time() None[source]
Enables logging statements about calculation time between wait calls.
- stop_logging_processing_time() None[source]
Disables logging statements about calculation time between wait calls.
- extract_absolute_tempo_envelope(start_beat: float = 0, step_size: float = 0.1, tolerance: float = 0.005) TempoEnvelope[source]
Extracts this clock’s absolute TempoHistory (as opposed to the TempoHistory relative to parent clock). Used when creating a score from this clock’s point of view.
- Parameters:
start_beat – where on the TempoHistory to start
step_size – granularity
tolerance – error tolerance with which we allow a step to simply extend the previous segment rather than create a new one.
- Returns:
A TempoHistory representing the true variation of tempo on this clock, as filtered through the changing rates of its parents.