clockblocks.tempo_envelope.TempoEnvelope¶
-
class
clockblocks.tempo_envelope.
TempoEnvelope
(levels: Sequence = 60, durations: Sequence[float] = (), curve_shapes: Sequence[Union[float, str]] = None, units: str = 'tempo', duration_units: str = 'beats')[source]¶ Bases:
expenvelope.envelope.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. A TempoEnvelopes also has a notion of the current beat and time and has methods for advancing time.- 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
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.
beat
()The current beat.
beat_length_at
(beat[, from_left])Get the beat length at the given beat.
Warps this tempo_curve so that all of 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.
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.
get_beat_wait_from_time_wait
(seconds)Get the amount of beats we would have to wait to wait for the given number of seconds, starting at the current point in the TempoEnvelope.
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
rate_at
(beat[, from_left])Get the beat rate (in beats/second) at the given beat.
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.
tempo_at
(beat[, from_left])Get the tempo (in beats/minute) at the given beat.
time
()The current time.
truncate
([beat])Removes all segments after beat (which defaults to the current beat) and adds a constant segment if necessary to being us up to that 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.
Returns a copy of this object by serializing to and from JSON.
Ending value of the Envelope
end_time
()End of the domain on which this Envelope is defined.
from_segments
(segments)Create a new envelope from a list of
EnvelopeSegment
s.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
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.
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.
normalize_to_duration
(desired_duration[, …])Stretch or squeeze the segments of this Envelope so that it has the desired total duration.
Remove and return the last segment of this Envelope.
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.
release
(duration[, start_level, curve_shape])Construct an simple decaying envelope
Removes all segments after the given time (including a partial segment if t lands in the middle of a segment).
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])Splits the Envelope at one or several points and returns a tuple of the pieces
Beginning value of the Envelope
Beginning of the domain on which this Envelope is defined.
value_at
(t[, from_left])Get the value of this Envelope at the given time.
Attributes
The current beat length.
Tuple of all the segment curve shapes.
Tuple of all the segment lengths.
Tuple of levels at all segment boundary points.
Alias for
Envelope.start_time()
.The current rate in beats/second
The current tempo in beats/minute
Tuple of all the segment start times.
-
classmethod
from_levels_and_durations
(levels: Sequence = 0, 0, durations: Sequence[float] = 0, curve_shapes: Sequence[Union[float, str]] = None, units: str = 'tempo', duration_units: str = 'beats') → clockblocks.tempo_envelope.TempoEnvelope[source]¶ 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') → clockblocks.tempo_envelope.TempoEnvelope[source]¶ 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') → clockblocks.tempo_envelope.TempoEnvelope[source]¶ 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') → clockblocks.tempo_envelope.TempoEnvelope[source]¶ 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, resolution_multiple=2, key_point_precision=100, key_point_iterations=5, units: str = 'tempo', duration_units: str = 'beats') → clockblocks.tempo_envelope.TempoEnvelope[source]¶ 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()
resolution_multiple – see
from_function()
key_point_precision – see
from_function()
key_point_iterations – 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
- Returns
a TempoEnvelope, constructed accordingly
-
time
()[source]¶ The current time. Time is found by integrating under the beatlength curve: seconds/beat * beats = seconds.
-
property
beat_length
¶ The current beat length.
-
truncate
(beat: float = None) → clockblocks.tempo_envelope.TempoEnvelope[source]¶ Removes all segments after beat (which defaults to the current beat) and adds a constant segment if necessary to being us up to that beat.
- Parameters
beat – the beat that we are truncating the tempo envelope after
- Returns
self, for chaining purposes
-
beat_length_at
(beat: float, from_left: bool = False) → float[source]¶ 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
-
property
rate
¶ The current rate in beats/second
-
rate_at
(beat: float, from_left: bool = False) → float[source]¶ 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
-
property
tempo
¶ The current tempo in beats/minute
-
tempo_at
(beat: float, from_left: bool = False) → float[source]¶ 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
-
set_beat_length_target
(beat_length_target: float, duration: float, curve_shape: float = 0, metric_phase_target: 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: Sequence[float] = None, metric_phase_targets: Sequence[Union[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: 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: Sequence[float] = None, metric_phase_targets: Sequence[Union[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: 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: Sequence[float] = None, metric_phase_targets: Sequence[Union[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: Union[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 calledadjust_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: Union[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 calledadjust_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 to wait for the given number of seconds, starting at the current point in the TempoEnvelope.
- 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) → clockblocks.tempo_envelope.TempoEnvelope[source]¶ Jump straight to the given beat in this TempoEnvelope
- Parameters
b – the beat to jump to
- Returns
self, for chaining purposes
-
static
convert_units
(values: Union[float, Sequence[float]], input_units: str, output_units: str) → Union[float, Sequence[float]][source]¶ Utility method to convert values between unites of tempo, rate and beat length.
- Parameters
values – a 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
()[source]¶ Warps this tempo_curve so that all of 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)[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 or not 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
-
classmethod
adsr
(attack_length: float, attack_level, decay_length: float, sustain_level, sustain_length: float, release_length: float, attack_shape: Union[float, str] = None, decay_shape: Union[float, str] = None, release_shape: 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) → expenvelope.envelope.Envelope¶ 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: Union[float, str] = None, release_shape: 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: Union[float, str] = None, release_shape: 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: 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
¶ Tuple of all the segment curve shapes.
-
duplicate
() → T¶ Returns a copy of this object by serializing to and from JSON.
-
property
durations
¶ 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[expenvelope.envelope_segment.EnvelopeSegment]) → T¶ Create a new envelope from a list of
EnvelopeSegment
s.- Parameters
segments – list of segments
-
get_upper_integration_bound
(t1: float, desired_area: float, max_error: float = 0.001) → 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
¶ 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: 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.
-
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
¶ Alias for
Envelope.start_time()
.
-
pop_segment
() → Optional[expenvelope.envelope_segment.EnvelopeSegment]¶ 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
() → Optional[expenvelope.envelope_segment.EnvelopeSegment]¶ 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: 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) → 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
- 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
¶ 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.