expenvelope.envelope_segment.EnvelopeSegment

class expenvelope.envelope_segment.EnvelopeSegment(start_time: float, end_time: float, start_level, end_level, curve_shape: float | str)

Bases: object

A segment of an envelope, with the ability to perform interpolation and integration.

Parameters:

• start_time – the start time of the segment (where it is in the parent Envelope)

• end_time – the end time of the segment

• start_level – the level of the envelope segment at the beginning. Note that a type has not been specified; the only requirements are that the type should be consistent and respond to addition and multiplication. This means, for instance, that numpy arrays could be used.

• end_level – the level of the envelope segment at the end.

• curve_shape – 0 is linear, > 0 changes late, < 0 changes early. Also, string expressions involving “exp” can be given, where “exp” stands for the shape that will produce constant proportional change per unit time.

Variables:

• start_time – the start time of the segment

• end_time – the end time of the segment

Methods

average_level()	Get the average level achieved in this segment
clone()	Make a duplicate of this segment.
end_slope()	Get the ending slope of the EnvelopeSegment
from_endpoints_and_halfway_level(start_time, ...)	Construct an EnvelopeSegment with the given start/end times/levels, specifying curve shape indirectly through the desired halfway level.
get_integral_range()	Returns the range of possible values for the integral of this segment available by tweaking curvature
integrate_segment(t1, t2)	Integrate part of this segment.
is_shifted_version_of(other[, tolerance])	Determines if this segment is simply a shifted version of another segment
max_absolute_slope()	Get the max absolute value of the slope of this segment over the interval.
max_level()	Get the maximum level achieved in this segment
min_level()	Get the minimum level achieved in this segment
scale_horizontal(amount)	Scales the domain of this segment by the specified amount.
scale_vertical(amount)	Scales the output of this segment by the specified amount.
set_curvature_to_desired_integral(...)	Changes the curvature of this segment so as to hit a desired target for the integral of the segment
shift_horizontal(amount)	Shifts the domain of this segment by the specified amount.
shift_vertical(amount)	Shifts the output of this segment by the specified amount.
show_plot([title, resolution])	Uses matplotlib to display a graph of this EnvelopeSegment.
split_at(t)	Split this segment into two EnvelopeSegment's without altering the curve shape and return them.
start_slope()	Get the starting slope of the EnvelopeSegment
value_at(t[, clip_at_boundary])	Get interpolated value of the curve at time t.

Attributes

curve_shape	The curve shape of this segment.
duration	Duration of this segment.
end_level	The end level of this segment.
start_level	The start level of this segment.

classmethod from_endpoints_and_halfway_level(start_time: float, end_time: float, start_level, end_level, halfway_level) → T

Construct an EnvelopeSegment with the given start/end times/levels, specifying curve shape indirectly through the desired halfway level.

Parameters:

• start_time – the start time of the segment (where it is in the parent Envelope)

• end_time – the end time of the segment

• start_level – the level of the envelope segment at the beginning. (See documentation for EnvelopeSegment)

• end_level – the level of the envelope segment at the end.

• halfway_level – The level we want to reach halfway through the segment.

property start_level

The start level of this segment. (Can take a wide variety of types; see documentation for EnvelopeSegment)

property end_level

The end level of this segment. (Can take a wide variety of types; see documentation for EnvelopeSegment)

property curve_shape: float

The curve shape of this segment. (See documentation for EnvelopeSegment)

property duration: float

Duration of this segment.

max_level()

Get the maximum level achieved in this segment

min_level()

Get the minimum level achieved in this segment

average_level()

Get the average level achieved in this segment

max_absolute_slope()

Get the max absolute value of the slope of this segment over the interval. (Since the slope of e^x is e^x, the max slope of e^x in the interval of [0, S] is e^S. If S is negative, the curve has exactly the same slopes, but in reverse (still need to think about why), so that’s why the max slope term ends up being e^abs(S). We then have to scale that by the average slope over our interval divided by the average slope of e^x over [0, S] to get the true, scaled average slope. Hence the other scaling terms.)

start_slope()

Get the starting slope of the EnvelopeSegment

end_slope()

Get the ending slope of the EnvelopeSegment

value_at(t: float, clip_at_boundary: bool = True)

Get interpolated value of the curve at time t. The equation here is y(t) = y1 + (y2 - y1) / (e^S - 1) * (e^(S*t) - 1) (y1=starting rate, y2=final rate, t=progress along the curve 0 to 1, S=curve_shape) Essentially it’s an appropriately scaled and stretched segment of e^x with x in the range [0, S] as S approaches zero, we get a linear segment, and S of ln(y2/y1) represents normal exponential interpolation large values of S correspond to last-minute change, and negative values of S represent early change.

Parameters:

• t – time at which to evaluate the level (relative to the time zero, not to the start time of this segment)

• clip_at_boundary – if True, any t outside the boundary gets evaluated based on the start or end level (whichever is applicable.

integrate_segment(t1, t2)

Integrate part of this segment.

Parameters:

• t1 – start time (relative to the time zero, not to the start time of this segment)

• t2 – end time (ditto)

get_integral_range()

Returns the range of possible values for the integral of this segment available by tweaking curvature

:return a tuple of (low, high)

set_curvature_to_desired_integral(desired_integral) → None

Changes the curvature of this segment so as to hit a desired target for the integral of the segment

Parameters:

desired_integral – target value of the segment integral

split_at(t: float) → tuple[T, T]

Split this segment into two EnvelopeSegment’s without altering the curve shape and return them. This segment is altered in the process.

Parameters:

t – where to split it (t is absolute time)

Returns:

a tuple of this segment modified to be only the first part, and a new segment for the second part

clone() → T

Make a duplicate of this segment.

shift_vertical(amount) → T

Shifts the output of this segment by the specified amount.

Parameters:

amount – the amount to shift up and down by

Returns:

self, for chaining purposes

scale_vertical(amount) → T

Scales the output 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 segment by the specified amount.

Parameters:

amount – the amount to shift the domain by

Returns:

self, for chaining purposes

scale_horizontal(amount: float) → T

Scales the domain of this segment by the specified amount.

Parameters:

amount – amount to scale domain by

Returns:

self, for chaining purposes

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

show_plot(title: Optional[str] = None, resolution: int = 25) → None

Uses matplotlib to display a graph of this EnvelopeSegment.

Parameters:

• title – (optional) the title to give the graph

• resolution – how many points to use in creating the graph