clockblocks.tempo_envelope.TempoHistory

class clockblocks.tempo_envelope.TempoHistory(levels: Sequence = (60,), durations: Sequence[float] = (), curve_shapes: Optional[Sequence[Union[float, str]]] = None, units: str = 'tempo', duration_units: str = 'beats', beat: float = 0.0)[source]

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:

Methods

adjust_beat_at_time(time_to_adjust, desired_beat)

Adjusts the curvature of segments from now until the specified time so that we reach it at desired_beat, if possible.

adjust_metric_phase_at_beat(beat, ...)

Sets the goal (time) metric phase at the given beat.

adjust_metric_phase_at_time(target_time, ...)

Sets the goal (beat) metric phase at the given time.

adjust_time_at_beat(beat_to_adjust, desired_time)

Adjusts the curvature of segments from now until beat so that we reach it at desired_time, if possible.

advance(beats)

Advance the current beat/time in the envelope by the given number of beats.

advance_time(seconds)

Advance the current beat/time in the envelope by the given number of seconds.

as_tempo_envelope()

Converts this TempoHistory to a simpler TempoEnvelope (removing reference to current beat and time)

beat()

The current beat.

get_beat_wait_from_time_wait(seconds)

Get the amount of beats we would have to wait in order to wait for the given number of seconds, starting at the current point in the TempoHistory.

get_wait_time(beats)

Get the amount of time it would take to wait the specified number of beats starting at the current point in the TempoEnvelope.

go_to_beat(b)

Jump straight to the given beat in this TempoEnvelope

set_beat_length_target(beat_length_target, ...)

Set a target beat length for this TempoEnvelope 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 beat rate for this TempoEnvelope 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 TempoEnvelope 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.

show_plot([title, resolution, ...])

Shows a plot of this TempoEnvelope using matplotlib.

time()

The current time.

truncate()

Removes all segments after the current beat.

Inherited Methods

adsr(attack_length, attack_level, ...[, ...])

Construct a standard attack/decay/sustain/release envelope

append_envelope(envelope_to_append)

Extends this envelope by another one (shifted to start at the end of this one).

append_segment(level, duration[, ...])

Append a segment to the end of the curve ending at level and lasting for duration.

ar(attack_length, release_length[, ...])

Construct an attack/release envelope

asr(attack_length, sustain_level, ...[, ...])

Construct an attack/sustain/release envelope

average_level([t_range])

Returns the average value that the Envelope takes over the given range.

beat_at_time(t)

beat_length_at(beat[, from_left])

Get the beat length at the given beat.

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.

convert_units(values, input_units, output_units)

Utility method to convert values between unites of tempo, rate and beat length.

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(beat)

Extends the end of this TempoEnvelope to the given beat (if needed) by adding a constant segment at the end.

from_function(function[, domain_start, ...])

Constructs a TempoEnvelope that approximates an arbitrary function.

from_levels(levels[, length, units, ...])

Constructs a TempoEnvelope from the given levels and total length, using the specified units.

from_levels_and_durations([levels, ...])

Constructs a TempoEnvelope from the given levels, durations and curve shapes, using the specified units.

from_list(constructor_list[, units, ...])

Construct a TempoEnvelope from a list that can take a number of formats

from_points(*points[, units, duration_units])

Construct an envelope from a list of (beat/time, tempo/rate/beat length) pairs.

from_segments(segments)

Create a new envelope from a list of EnvelopeSegments.

get_upper_integration_bound(t1, desired_area)

Given a lower integration bound, find the upper bound that will result in the desired integral

insert(t, level[, curve_shape_in, ...])

Insert a curve point at time t, and set the shape of the curve into and out of it.

insert_interpolated(t[, min_difference])

Insert another curve point at the given time, without changing the shape of the curve.

integrate_interval(t1, t2)

Get the definite integral under this Envelope from t1 to t2

is_shifted_version_of(other[, tolerance])

Determines if this segment is simply a shifted version of another segment

json_dumps()

Dump this object as a JSON string.

json_loads(s)

Load this object from a JSON string.

length()

The length of the domain on which this Envelope is defined (end time minus start time).

load_from_json(file_path)

Load this object from a JSON file with the given path.

local_extrema([include_saddle_points])

Returns a list of the times where the curve changes direction.

max_absolute_slope()

Returns the maximum absolute value of the slope over the entire Envelope.

max_level([t_range])

Returns the highest value that the Envelope takes over the given range.

min_level([t_range])

Returns the lowest value that the Envelope takes over the given range.

normalize_to_duration(desired_duration[, ...])

Stretch or squeeze the segments of this Envelope so that it has the desired total duration.

pop_segment()

Remove and return the last segment of this Envelope.

pop_segment_from_start()

Remove and return the first segment of this Envelope.

prepend_envelope(envelope_to_prepend)

Extends this envelope backwards by another one (shifted to end at the start of this one).

prepend_segment(level, duration[, ...])

Prepend a segment to the beginning of the curve, starting at level and lasting for duration.

rate_at(beat[, from_left])

Get the beat rate (in beats/second) at the given beat.

release(duration[, start_level, curve_shape])

Construct an simple decaying envelope

remove_segments_after(t)

Removes all segments after the given time (including a partial segment if t lands in the middle of a segment).

remove_segments_before(t)

Removes all segments before the given time (including a partial segment if t lands in the middle of a segment).

save_to_json(file_path)

Save this object to a JSON file using the given path.

scale_horizontal(amount)

Scales the domain of this Envelope by the specified amount.

scale_vertical(amount)

Scales the levels of this segment by the specified amount.

shift_horizontal(amount)

Shifts the domain of this Envelope by the specified amount.

shift_vertical(amount)

Shifts the levels of this Envelope the specified amount.

split_at(t[, change_original, zero_out_offsets])

Splits the Envelope at one or several points and returns a tuple of the pieces

start_level()

Beginning value of the Envelope

start_time()

Beginning of the domain on which this Envelope is defined.

tempo_at(beat[, from_left])

Get the tempo (in beats/minute) at the given beat.

time_at_beat(b)

truncate_at(beat)

Removes all segments after the given beat and adds a constant segment if necessary to bring us up to that beat.

value_at(t[, from_left])

Get the value of this Envelope at the given time.

Attributes

beat_length

The current beat length.

curve_shapes

Tuple of all the segment curve shapes.

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

times

Tuple of all the segment start times.

time()[source]

The current time. Time is found by integrating under the beat length curve: seconds/beat * beats = seconds.

beat()[source]

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

set_beat_length_target(beat_length_target: float, duration: float, curve_shape: float = 0, metric_phase_target: Optional[Union[float, MetricPhaseTarget, tuple]] = None, duration_units: str = 'beats', truncate: bool = True) None[source]

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

  • 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.

  • truncate – Whether or not to truncate this TempoEnvelope to the current beat before setting this target.

set_beat_length_targets(beat_length_targets: Sequence[float], durations: Sequence[float], curve_shapes: Optional[Sequence[float]] = None, metric_phase_targets: Optional[Sequence[float | MetricPhaseTarget | tuple]] = None, duration_units: str = 'beats', truncate: bool = True) 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 truncate this TempoEnvelope to the current beat before setting these targets.

set_rate_target(rate_target: float, duration: float, curve_shape: float = 0, metric_phase_target: Optional[Union[float, MetricPhaseTarget, tuple]] = None, duration_units: str = 'beats', truncate: bool = True) None[source]

Set a target beat rate for this TempoEnvelope to reach in duration beats/seconds (with the unit defined by duration_units).

Parameters:
  • rate_target – The beat rate we want to reach

  • duration – How long until we reach that beat rate

  • 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.

  • truncate – Whether or not to truncate this TempoEnvelope to the current beat before setting this target.

set_rate_targets(rate_targets: Sequence[float], durations: Sequence[float], curve_shapes: Optional[Sequence[float]] = None, metric_phase_targets: Optional[Sequence[float | MetricPhaseTarget | tuple]] = None, duration_units: str = 'beats', truncate: bool = True) 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 beat 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 truncate this TempoEnvelope to the current beat before setting these targets.

set_tempo_target(tempo_target: float, duration: float, curve_shape: float = 0, metric_phase_target: Optional[Union[float, MetricPhaseTarget, tuple]] = None, duration_units: str = 'beats', truncate: bool = True) None[source]

Set a target tempo for this TempoEnvelope 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 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.

  • truncate – Whether or not to truncate this TempoEnvelope to the current beat before setting this target.

set_tempo_targets(tempo_targets: Sequence[float], durations: Sequence[float], curve_shapes: Optional[Sequence[float]] = None, metric_phase_targets: Optional[Sequence[float | MetricPhaseTarget | tuple]] = None, duration_units: str = 'beats', truncate: bool = True) 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 truncate this TempoEnvelope to the current beat before setting these targets.

adjust_metric_phase_at_beat(beat: float, metric_phase_target: float | MetricPhaseTarget | tuple) bool[source]

Sets the goal (time) metric phase at the given beat. So, for instance, if we called adjust_metric_phase_at_beat(5, 0.5), this would mean that we want to be at time 1.5, 2.5, 3.5 etc. at beat 5. If we called adjust_metric_phase_at_beat(7, 1.25, 3), this would mean that at beat 7, we would want to be at time 1.25, 4.25, 7.25, etc.

Parameters:
  • beat – The beat at which to have the given phase in time

  • metric_phase_target – either a MetricPhaseTarget, or the argument to construct one

Returns:

True, if the adjustment is possible, False if not

adjust_time_at_beat(beat_to_adjust: float, desired_time: float) bool[source]

Adjusts the curvature of segments from now until beat so that we reach it at desired_time, if possible. If not possible, leaves the TempoCurve unchanged and returns False

Parameters:
  • beat_to_adjust – the beat at which we want to be at a particular time

  • desired_time – the time we want to be at

Returns:

True if the adjustment worked, False if it’s impossible

adjust_metric_phase_at_time(target_time: float, metric_phase_target: float | MetricPhaseTarget | tuple) bool[source]

Sets the goal (beat) metric phase at the given time. So, for instance, if we called adjust_metric_phase_at_time(5, 0.5), this would mean that at time 5 we want to be at beat 1.5, 2.5, 3.5 etc. If we called adjust_metric_phase_at_time(7, 1.25, 3), this would mean that at time 7, we would want to be at beat 1.25, 4.25, 7.25, etc.

Parameters:
  • target_time – The time at which to have the given phase in beat

  • metric_phase_target – either a MetricPhaseTarget, or the argument to construct one

Returns:

True, if the adjustment is possible, False if not

adjust_beat_at_time(time_to_adjust: float, desired_beat: float) bool[source]

Adjusts the curvature of segments from now until the specified time so that we reach it at desired_beat, if possible. If not possible, leaves the TempoCurve unchanged and returns False.

Parameters:
  • time_to_adjust – the time at which we want to be at a particular beat

  • desired_beat – the beat we want to be at

Returns:

True if the adjustment worked, False if it’s impossible

get_wait_time(beats: float) float[source]

Get the amount of time it would take to wait the specified number of beats starting at the current point in the TempoEnvelope.

Parameters:

beats – how many beats to wait

Returns:

how much time that will take

advance(beats: float) tuple[float, float][source]

Advance the current beat/time in the envelope by the given number of beats.

Parameters:

beats – how many beats to advance by

Returns:

tuple of delta beats, delta time

get_beat_wait_from_time_wait(seconds: float) float[source]

Get the amount of beats we would have to wait in order to wait for the given number of seconds, starting at the current point in the TempoHistory.

Parameters:

seconds – how many seconds to wait

Returns:

how many beats that would correspond to

advance_time(seconds: float)[source]

Advance the current beat/time in the envelope by the given number of seconds.

Parameters:

seconds – how many seconds to advance by

Returns:

tuple of delta beats, delta time

go_to_beat(b: float) TempoEnvelope[source]

Jump straight to the given beat in this TempoEnvelope

Parameters:

b – the beat to jump to

Returns:

self, for chaining purposes

truncate() TempoEnvelope[source]

Removes all segments after the current beat.

Returns:

self, for chaining purposes

show_plot(title=None, resolution=25, show_segment_divisions=True, units='tempo', x_range=None, y_range=None)[source]

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

as_tempo_envelope() TempoEnvelope[source]

Converts this TempoHistory to a simpler TempoEnvelope (removing reference to current beat and time)

classmethod adsr(attack_length: float, attack_level, decay_length: float, sustain_level, sustain_length: float, release_length: float, attack_shape: Optional[Union[float, str]] = None, decay_shape: Optional[Union[float, str]] = None, release_shape: Optional[Union[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: Optional[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: Optional[Union[float, str]] = None, release_shape: Optional[Union[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: Optional[Union[float, str]] = None, release_shape: Optional[Union[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: Optional[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_at_time(t)
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: Union[float, Sequence[float]], input_units: str, output_units: str) Union[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[Union[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: Optional[Sequence[Union[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 EnvelopeSegments.

Parameters:

segments – list of segments

get_upper_integration_bound(t1: float, desired_area: float, max_error: float = 1e-10) float

Given a lower integration bound, find the upper bound that will result in the desired integral

Parameters:
  • t1 – lower bound of integration

  • desired_area – desired value of the integral.

  • max_error – the upper bound is found through a process of successive approximation; once we get within this error, the approximation is considered good enough.

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, min_difference: float = 1e-07) float

Insert another curve point at the given time, without changing the shape of the curve. A point only gets added if it’s at least min_difference from all existing control points.

Parameters:
  • t – the point at which to insert the point

  • min_difference – the minimum difference that this point has to be from an existing point on the curve in order for a new point to be added.

Returns:

the t value at which we interpolated. If we try to insert within min_difference of an existing control point, then no new point is added, and we return the t of the nearest control point.

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 to plateau

max_absolute_slope()

Returns the maximum absolute value of the slope over the entire Envelope.

max_level(t_range: Optional[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: Optional[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: Optional[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: Optional[Union[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

split_at(t: Union[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

time_at_beat(b)
property times: Sequence[float]

Tuple of all the segment start times.

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

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.