clockblocks package

Clockblocks is a Python library for controlling the flow of musical time, designed with musical applications in mind. Contents of this package include the clock module, which defines the central Clock class; the tempo_envelope module, which defines the TempoEnvelope class for mapping out how a clock’s tempo changes with time, as well as the MetricPhaseTarget class for specifying desired metric phases; the debug module, which provides utilities for logging in a way that clarifies which clock logging messages are occurring under; and the utilities module, which contains a few utility functions.

Modules:

clockblocks.clock

Module defining the central Clock class, as well as the TimeStamp class, which records the current beat in every clock at a given moment.

clockblocks.debug

Utilities for logging and debugging processes operating on multiple clocks.

clockblocks.settings

Global preferences and settings for clockblocks.

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.

clockblocks.utilities

Utility functions, including versions of wait() and fork() that implicitly make use of the active clock on the current thread.

Public-Facing API (result of import *):

Clock([name, parent, initial_rate, ...])

Recursively nestable clock class.

ClockKilledError

Exception raised when a clock is killed, allowing us to exit the process forked on it.

DeadClockError

Exception raised when a clock is asked to do something after it was killed.

TimeStamp([clock])

A TimeStamp stores the beat of every Clock within a family of clocks, at a specific moment.

MetricPhaseTarget(phase_or_phases[, ...])

Class representing a particular point in a (beat or measure) cycle.

TempoEnvelope([levels, durations, ...])

A subclass of Envelope that is specifically designed for representing changing tempo curves.

TempoHistory([levels, durations, ...])

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.

current_clock()

Get the Clock active on the current thread (or None if none is active)

fork(process_function[, args, kwargs, name, ...])

Spawns a parallel process running on a child clock of the currently active clock.

fork_unsynchronized(process_function[, ...])

Spawns a parallel process, but as an asynchronous thread, not on a child clock.

sleep_precisely(secs[, interruption_event])

High-precision sleep for the given number of seconds.

sleep_precisely_until(stop_time[, ...])

High-precision sleep until stop_time.

wait(dt[, units])

Calls wait() on the clock that is currently active on the thread.

wait_for_children_to_finish()

Calls wait_for_children_to_finish() on the clock that is currently active on the thread; generally, this is called when there are child clocks running and we want to keep the main script alive while the action takes place on the child clocks.

wait_forever()

Calls wait_forever() on the clock that is currently active on the thread; generally, this is called when there are child clocks running and we want to keep the main script alive while the action takes place on the child clocks.