======================================================================
=== FILE: expenvelope/expenvelope.envelope.Envelope.txt
======================================================================

expenvelope.envelope.Envelope
*****************************

class expenvelope.envelope.Envelope(levels: Sequence = (0,), durations: Sequence[float] = (), curve_shapes: Sequence[float | str] = None, offset: float = 0)

   Bases: "SavesToJSON"

   Class representing a piece-wise exponential function. This class
   was designed with musical applications in mind, with the intention
   being to represent a continuously changing musical parameter over
   time. For instance, an Envelope might be used to represent the
   pitch curve of a glissando, or the volume curve of a forte-piano.

   Parameters:
      * **levels** -- the levels of the curve. These can be anything
        that acts like a number. For instance, one could even use
        numpy arrays as levels.

      * **durations** -- the durations of the curve segments. (Should
        have length one less than levels.)

      * **curve_shapes** -- the curve shape values (optional, should
        have length one less than levels). Generally these will be
        floats, with the default of 0 representing linear change, > 0
        representing late change, and < 0 representing early change.
        It is also possible to use the string "exp" to produce
        constant proportional change per unit time, so long as the
        segment does not touch zero. Finally, strings containing
        "exp", such as "exp ** 2 / 5" will be evaluated with the curve
        shape required for exponential change being plugged in for the
        variable "exp".

      * **offset** -- starts curve from somewhere other than zero

   Variables:
      **segments** -- list of "EnvelopeSegment"s representing the
      pieces of this envelope.

   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "adsr"(att | Construct a standard attack/decay/sustain/release envelope                                 |
   | ack_length |                                                                                            |
   | , attack_l |                                                                                            |
   | evel,      |                                                                                            |
   | ...[,      |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "append_en | Extends this envelope by another one (shifted to start at the end of this one).            |
   | velope"(en |                                                                                            |
   | velope_to_ |                                                                                            |
   | append)    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "append_se | Append a segment to the end of the curve ending at level and lasting for duration.         |
   | gment"(lev |                                                                                            |
   | el,        |                                                                                            |
   | duration[, |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "ar"(attac | Construct an attack/release envelope                                                       |
   | k_length,  |                                                                                            |
   | release_le |                                                                                            |
   | ngth[,     |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "asr"(atta | Construct an attack/sustain/release envelope                                               |
   | ck_length, |                                                                                            |
   | sustain_le |                                                                                            |
   | vel, ...[, |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "average_l | Returns the average value that the Envelope takes over the given range.                    |
   | evel"([t_r |                                                                                            |
   | ange])     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "end_level | Ending value of the Envelope                                                               |
   | "()        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "end_time" | End of the domain on which this Envelope is defined.                                       |
   | ()         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "from_func | Constructs an Envelope that approximates an arbitrary function.                            |
   | tion"(func |                                                                                            |
   | tion[, dom |                                                                                            |
   | ain_start, |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "from_leve | Construct an envelope from levels alone, normalized to the given length.                   |
   | ls"(levels |                                                                                            |
   | [, length, |                                                                                            |
   | offset])   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "from_leve | Construct an Envelope from levels, durations, and optionally curve shapes.                 |
   | ls_and_dur |                                                                                            |
   | ations"(le |                                                                                            |
   | vels,      |                                                                                            |
   | durations) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "from_list | Construct an envelope from a list that can take a number of formats                        |
   | "(construc |                                                                                            |
   | tor_list)  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "from_poin | Construct an envelope from points                                                          |
   | ts"(*point |                                                                                            |
   | s)         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "from_segm | Create a new envelope from a list of "EnvelopeSegment"s.                                   |
   | ents"(segm |                                                                                            |
   | ents)      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "get_durat | Tuple of all the segment lengths.                                                          |
   | ions"([rou |                                                                                            |
   | nded])     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "get_upper | Given a lower integration bound, find the upper bound that will result in the desired      |
   | _integrati | integral.                                                                                  |
   | on_bound"( |                                                                                            |
   | t1, desire |                                                                                            |
   | d_area)    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "insert"(t | Insert a curve point at time t, and set the shape of the curve into and out of it.         |
   | , level[,  |                                                                                            |
   | curve_shap |                                                                                            |
   | e_in,      |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "insert_in | Insert another curve point at the given time, without changing the shape of the curve.     |
   | terpolated |                                                                                            |
   | "(t[, rela |                                                                                            |
   | tive_toler |                                                                                            |
   | ance])     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "integrate | Get the definite integral under this Envelope from t1 to t2                                |
   | _interval" |                                                                                            |
   | (t1, t2)   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "is_shifte | Determines if this segment is simply a shifted version of another segment                  |
   | d_version_ |                                                                                            |
   | of"(other[ |                                                                                            |
   | , toleranc |                                                                                            |
   | e])        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "length"() | The length of the domain on which this Envelope is defined (end time minus start time).    |
   +------------+--------------------------------------------------------------------------------------------+
   | "local_ext | Returns a list of the times where the curve changes direction.                             |
   | rema"([inc |                                                                                            |
   | lude_saddl |                                                                                            |
   | e_points]) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "max_absol | Returns the maximum absolute value of the slope over the entire Envelope.                  |
   | ute_slope" |                                                                                            |
   | ()         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "max_level | Returns the highest value that the Envelope takes over the given range.                    |
   | "([t_range |                                                                                            |
   | ])         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "min_level | Returns the lowest value that the Envelope takes over the given range.                     |
   | "([t_range |                                                                                            |
   | ])         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "normalize | Stretch or squeeze the segments of this Envelope so that it has the desired total          |
   | _to_durati | duration.                                                                                  |
   | on"(desire |                                                                                            |
   | d_duration |                                                                                            |
   | [, ...])   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "pop_segme | Remove and return the last segment of this Envelope.                                       |
   | nt"()      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "pop_segme | Remove and return the first segment of this Envelope.                                      |
   | nt_from_st |                                                                                            |
   | art"()     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "prepend_e | Extends this envelope backwards by another one (shifted to end at the start of this one).  |
   | nvelope"(e |                                                                                            |
   | nvelope_to |                                                                                            |
   | _prepend)  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "prepend_s | Prepend a segment to the beginning of the curve, starting at level and lasting for         |
   | egment"(le | duration.                                                                                  |
   | vel,       |                                                                                            |
   | duration[, |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "release"( | Construct an simple decaying envelope                                                      |
   | duration[, |                                                                                            |
   | start_leve |                                                                                            |
   | l, curve_s |                                                                                            |
   | hape])     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "remove_se | Removes all segments after the given time (including a partial segment if t lands in the   |
   | gments_aft | middle of a segment).                                                                      |
   | er"(t)     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "remove_se | Removes all segments before the given time (including a partial segment if t lands in the  |
   | gments_bef | middle of a segment).                                                                      |
   | ore"(t)    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "scale_hor | Scales the domain of this Envelope by the specified amount.                                |
   | izontal"(a |                                                                                            |
   | mount)     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "scale_ver | Scales the levels of this segment by the specified amount.                                 |
   | tical"(amo |                                                                                            |
   | unt)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "shift_hor | Shifts the domain of this Envelope by the specified amount.                                |
   | izontal"(a |                                                                                            |
   | mount)     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "shift_ver | Shifts the levels of this Envelope the specified amount.                                   |
   | tical"(amo |                                                                                            |
   | unt)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "show_plot | Shows a plot of this Envelope using matplotlib.                                            |
   | "([title,  |                                                                                            |
   | resolution |                                                                                            |
   | , ...])    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "simplifie | Simplifies the envelope to only extrema and inflection points.                             |
   | d"([use_cu |                                                                                            |
   | rvature,   |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "split_at" | Splits the Envelope at one or several points and returns a tuple of the pieces             |
   | (t[, chang |                                                                                            |
   | e_original |                                                                                            |
   | , zero_out |                                                                                            |
   | _offsets]) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "start_lev | Beginning value of the Envelope                                                            |
   | el"()      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "start_tim | Beginning of the domain on which this Envelope is defined.                                 |
   | e"()       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "value_at" | Get the value of this Envelope at the given time.                                          |
   | (t[, from_ |                                                                                            |
   | left])     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   -[ Inherited Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "duplicate | Returns a copy of this object by serializing to and from JSON.                             |
   | "()        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "json_dump | Dump this object as a JSON string.                                                         |
   | s"()       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "json_load | Load this object from a JSON string.                                                       |
   | s"(s)      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "load_from | Load this object from a JSON file with the given path.                                     |
   | _json"(fil |                                                                                            |
   | e_path)    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "save_to_j | Save this object to a JSON file using the given path.                                      |
   | son"(file_ |                                                                                            |
   | path)      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   -[ Attributes ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "curve_sha | Tuple of all the segment curve shapes.                                                     |
   | pes"       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "durations | Tuple of all the segment lengths.                                                          |
   | "          |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "levels"   | Tuple of levels at all segment boundary points.                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "offset"   | Alias for "Envelope.start_time()".                                                         |
   +------------+--------------------------------------------------------------------------------------------+
   | "times"    | Tuple of all the segment start times.                                                      |
   +------------+--------------------------------------------------------------------------------------------+

   classmethod from_segments(segments: Sequence[EnvelopeSegment]) -> T

      Create a new envelope from a list of "EnvelopeSegment"s.

      Parameters:
         **segments** -- list of segments

   classmethod from_levels_and_durations(levels: Sequence, durations: Sequence[float], curve_shapes: Sequence[float | str] = None, offset: float = 0) -> T

      Construct an Envelope from levels, durations, and optionally
      curve shapes.

      Parameters:
         * **levels** -- the levels of the curve. These can be
           anything that acts like a number. For instance, one could
           even use numpy arrays as levels.

         * **durations** -- the durations of the curve segments.
           (Should have length one less than levels.)

         * **curve_shapes** -- the curve shape values (optional,
           should have length one less than levels). Generally these
           will be floats, with the default of 0 representing linear
           change, > 0 representing late change, and < 0 representing
           early change. It is also possible to use the string "exp"
           to produce constant proportional change per unit time, so
           long as the segment does not touch zero. Finally, strings
           containing "exp", such as "exp ** 2 / 5" will be evaluated
           with the curve shape required for exponential change being
           plugged in for the variable "exp".

         * **offset** -- starts curve from somewhere other than zero

      Returns:
         an Envelope constructed accordingly

   classmethod from_levels(levels: Sequence, length: float = 1.0, offset: float = 0) -> T

      Construct an envelope from levels alone, normalized to the given
      length.

      Parameters:
         * **levels** -- the levels of the curve. These can be
           anything that acts like a number. For instance, one could
           even use numpy arrays as levels.

         * **length** -- the total length of the curve, divided evenly
           amongst the levels

         * **offset** -- starts curve from somewhere other than zero

      Returns:
         an Envelope constructed accordingly

   classmethod from_list(constructor_list: Sequence) -> T

      Construct an envelope from a list that can take a number of
      formats

      Parameters:
         **constructor_list** -- Either a flat list that just contains
         levels, or a list of lists either of the form [levels_list,
         total_duration], [levels_list, durations_list] or
         [levels_list, durations_list, curve_shape_list] for example:
         - an input of [1, 0.5, 0.3] is interpreted as evenly spaced
         levels with a total duration of 1 - an input of [[1, 0.5,
         0.3], 3.0] is interpreted as levels and durations with a
         total duration of e.g. 3.0 - an input of [[1, 0.5, 0.3],
         [0.2, 0.8]] is interpreted as levels and durations - an input
         of [[1, 0.5, 0.3], [0.2, 0.8], [2, 0.5]] is interpreted as
         levels, durations, and curvatures

      Returns:
         an Envelope constructed accordingly

   classmethod from_points(*points: Sequence) -> T

      Construct an envelope from points

      Parameters:
         **points** -- list of points, each of which is of the form
         (time, value) or (time, value, curve_shape)

      Returns:
         an Envelope constructed accordingly

   classmethod release(duration: float, start_level=1, curve_shape: 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

   classmethod ar(attack_length: float, release_length: float, peak_level=1, attack_shape: float | str = None, release_shape: 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: float | str = None, release_shape: 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

   classmethod adsr(attack_length: float, attack_level, decay_length: float, sustain_level, sustain_length: float, release_length: float, attack_shape: float | str = None, decay_shape: float | str = None, release_shape: 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

   classmethod from_function(function: Callable[[float], float], domain_start: float = 0, domain_end: float = 1, scanning_step_size: float = 0.05, key_point_resolution_multiple: int = 2, iterations: int = 6, min_key_point_distance: float = 1e-07, start_from_zero=True) -> T

      Constructs an Envelope that approximates an arbitrary function.
      By default, the function is split at local extrema and
      inflection points found through a pretty unsophisticated
      numerical process.

      Parameters:
         * **function** -- a function from time to level (often a
           lambda function)

         * **domain_start** -- the beginning of the function domain
           range to capture

         * **domain_end** -- the end of the function domain range to
           capture

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

         * **start_from_zero** -- if true, the envelope is shifted so
           that it starts at time zero. Otherwise, it will have an
           offset equal to *domain_start*

      Returns:
         an Envelope constructed accordingly

   length() -> float

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

   start_time() -> float

      Beginning of the domain on which this Envelope is defined.

   end_time() -> float

      End of the domain on which this Envelope is defined.

   start_level()

      Beginning value of the Envelope

   end_level()

      Ending value of the 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.

   min_level(t_range: 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.

   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.

   max_absolute_slope()

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

   property levels: Sequence

      Tuple of levels at all segment boundary points.

   property durations: Sequence[float]

      Tuple of all the segment lengths.

   get_durations(rounded: bool = False) -> Sequence[float]

      Tuple of all the segment lengths.

      Segment lengths are derived as "end_time - start_time", so an
      envelope built up on a regular grid (e.g. repeated 0.1-long
      segments) accumulates floating-point dust in these differences
      even though each segment was appended with a clean duration.
      Pass "rounded=True" to snap each length to a nearby nice decimal
      — used for serialization / repr so the intended durations show,
      without disturbing the exact segment boundary times that the
      curve math relies on.

      Parameters:
         **rounded** -- if True, snap each duration to a nearby nice
         decimal (see "snap_float_to_nice_decimal()")

   property times: Sequence[float]

      Tuple of all the segment start times.

   property curve_shapes: Sequence[float | str]

      Tuple of all the segment curve shapes.

   property offset: float

      Alias for "Envelope.start_time()".

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

      Insert another curve point at the given time, without changing
      the shape of the curve. Returns the t value of the new (or
      already existing) interpolated point.

      To avoid manufacturing degenerate, near-zero-width segments due
      to floating point imprecision, a point is only added if it is at
      least "relative_tolerance * segment_width" away from the
      endpoints of the segment it falls in. If "t" lands *within* that
      tolerance of an existing control point, this function call is
      assumed to be an idempotent re-insertion of an existing curve
      point after floating point error has muddied the waters. In this
      case no point is added, and the existing control point's time is
      returned instead.

      Parameters:
         * **t** -- the point at which to insert the point

         * **relative_tolerance** -- how close "t" may come to an
           existing control point before it is treated as coincident
           with it, expressed as a fraction of the width of the
           segment containing "t".

      Returns:
         the t value at which we interpolated. If we snapped to an
         existing control point, its t is returned; otherwise the
         passed value of "t" is returned.

   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.

   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.

   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.

   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.

   append_envelope(envelope_to_append: T) -> T

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

   prepend_envelope(envelope_to_prepend: T) -> T

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

   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.

   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

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

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

      Walks the envelope segment by segment, subtracting each
      segment's closed-form area until the remaining area falls within
      a single segment, then inverts that segment using
      "EnvelopeSegment.get_t_at_integral()" — exactly for
      constant/linear segments, and to within "max_error" for
      exponential ones.

      Assumes a non-negative integrand, so that the integral increases
      monotonically (true for tempo and dynamics curves, the primary
      use). Regions before the first segment and after the last are
      treated as flat (at the start/end level), matching
      "integrate_interval()".

      Parameters:
         * **t1** -- lower bound of integration

         * **desired_area** -- desired value of the integral.

         * **max_error** -- convergence tolerance forwarded to the
           per-segment inverse for the exponential case; ignored by
           the (exact) constant and linear cases.

   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

   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 or stops plateauing

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

   simplified(use_curvature=True, include_saddle_points=True) -> T

      Simplifies the envelope to only extrema and inflection points.

      Parameters:
         * **use_curvature** -- if True, adjusts the curvature of the
           segments to match the half-way point between key points. If
           False, linearly interpolate between key points.

         * **include_saddle_points** -- if True, include saddle points
           as well as extrema

   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

   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

   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

   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

   show_plot(title: str = None, resolution: int = 25, show_segment_divisions: bool = True, x_range: tuple[float, float] = None, y_range: tuple[float, float] = None) -> None

      Shows a plot of this Envelope 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

         * **x_range** -- min and max value shown on the x-axis

         * **y_range** -- min and max value shown on the y-axis

   duplicate() -> T

      Returns a copy of this object by serializing to and from JSON.

   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

   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

   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


======================================================================
=== FILE: expenvelope/expenvelope.envelope.txt
======================================================================

expenvelope.envelope
********************

Module containing the central "Envelope" class, which represents a
piece-wise exponential function. "Envelope"s support arithmetic
operations like addition, subtraction, multiplication, and division.
They also support horizontal scaling and shifting.

Note also that this is defining a function whose domain is a portion
of the real number line, but whose range can actually be nearly
anything, including, e.g., numpy arrays. All of the functionality,
even integration, works for mappings onto other kinds of ranges.

-[ Classes ]-

+------------+--------------------------------------------------------------------------------------------+
| "Envelope" | Class representing a piece-wise exponential function.                                      |
| ([levels,  |                                                                                            |
| durations, |                                                                                            |
| curve_shap |                                                                                            |
| es, ...])  |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* expenvelope.envelope.Envelope

  * "Envelope"

    * "Envelope.from_segments()"

    * "Envelope.from_levels_and_durations()"

    * "Envelope.from_levels()"

    * "Envelope.from_list()"

    * "Envelope.from_points()"

    * "Envelope.release()"

    * "Envelope.ar()"

    * "Envelope.asr()"

    * "Envelope.adsr()"

    * "Envelope.from_function()"

    * "Envelope.length()"

    * "Envelope.start_time()"

    * "Envelope.end_time()"

    * "Envelope.start_level()"

    * "Envelope.end_level()"

    * "Envelope.max_level()"

    * "Envelope.min_level()"

    * "Envelope.average_level()"

    * "Envelope.max_absolute_slope()"

    * "Envelope.levels"

    * "Envelope.durations"

    * "Envelope.get_durations()"

    * "Envelope.times"

    * "Envelope.curve_shapes"

    * "Envelope.offset"

    * "Envelope.insert()"

    * "Envelope.insert_interpolated()"

    * "Envelope.append_segment()"

    * "Envelope.prepend_segment()"

    * "Envelope.pop_segment()"

    * "Envelope.pop_segment_from_start()"

    * "Envelope.remove_segments_after()"

    * "Envelope.remove_segments_before()"

    * "Envelope.append_envelope()"

    * "Envelope.prepend_envelope()"

    * "Envelope.value_at()"

    * "Envelope.integrate_interval()"

    * "Envelope.get_upper_integration_bound()"

    * "Envelope.normalize_to_duration()"

    * "Envelope.local_extrema()"

    * "Envelope.split_at()"

    * "Envelope.simplified()"

    * "Envelope.is_shifted_version_of()"

    * "Envelope.shift_vertical()"

    * "Envelope.scale_vertical()"

    * "Envelope.shift_horizontal()"

    * "Envelope.scale_horizontal()"

    * "Envelope.show_plot()"

    * "Envelope.duplicate()"

    * "Envelope.json_dumps()"

    * "Envelope.json_loads()"

    * "Envelope.load_from_json()"

    * "Envelope.save_to_json()"


======================================================================
=== FILE: expenvelope/expenvelope.envelope_segment.EnvelopeSegment.txt
======================================================================

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_l | Get the average level achieved in this segment                                             |
   | evel"()    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "clone"()  | Make a duplicate of this segment.                                                          |
   +------------+--------------------------------------------------------------------------------------------+
   | "end_slope | Get the ending slope of the EnvelopeSegment                                                |
   | "()        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "from_endp | Construct an EnvelopeSegment with the given start/end times/levels, specifying curve shape |
   | oints_and_ | indirectly through the desired halfway level.                                              |
   | halfway_le |                                                                                            |
   | vel"(start |                                                                                            |
   | _time,     |                                                                                            |
   | ...)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "get_integ | Returns the range of possible values for the integral of this segment available by         |
   | ral_range" | tweaking curvature                                                                         |
   | ()         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "get_t_at_ | Inverse of "integrate_segment()" within this single segment: given a lower bound "t1"      |
   | integral"( | inside the segment, find the upper bound "t2" (also inside the segment) such that          |
   | t1, desire | "integrate_segment(t1, t2) == desired_area".                                               |
   | d_area[, m |                                                                                            |
   | ax_error]) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "integrate | Integrate part of this segment.                                                            |
   | _segment"( |                                                                                            |
   | t1, t2)    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "is_shifte | Determines if this segment is simply a shifted version of another segment                  |
   | d_version_ |                                                                                            |
   | of"(other[ |                                                                                            |
   | , toleranc |                                                                                            |
   | e])        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "max_absol | Get the max absolute value of the slope of this segment over the interval.                 |
   | ute_slope" |                                                                                            |
   | ()         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "max_level | Get the maximum level achieved in this segment                                             |
   | "()        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "min_level | Get the minimum level achieved in this segment                                             |
   | "()        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "scale_hor | Scales the domain of this segment by the specified amount.                                 |
   | izontal"(a |                                                                                            |
   | mount)     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "scale_ver | Scales the output of this segment by the specified amount.                                 |
   | tical"(amo |                                                                                            |
   | unt)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "set_curva | Changes the curvature of this segment so as to hit a desired target for the integral of    |
   | ture_to_de | the segment                                                                                |
   | sired_inte |                                                                                            |
   | gral"(...) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "shift_hor | Shifts the domain of this segment by the specified amount.                                 |
   | izontal"(a |                                                                                            |
   | mount)     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "shift_ver | Shifts the output of this segment by the specified amount.                                 |
   | tical"(amo |                                                                                            |
   | unt)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "show_plot | Uses matplotlib to display a graph of this EnvelopeSegment.                                |
   | "([title,  |                                                                                            |
   | resolution |                                                                                            |
   | ])         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "split_at" | Split this segment into two EnvelopeSegment's without altering the curve shape and return  |
   | (t)        | them.                                                                                      |
   +------------+--------------------------------------------------------------------------------------------+
   | "start_slo | Get the starting slope of the EnvelopeSegment                                              |
   | pe"()      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "value_at" | Get interpolated value of the curve at time t.                                             |
   | (t[, clip_ |                                                                                            |
   | at_boundar |                                                                                            |
   | y])        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   -[ Attributes ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "curve_sha | The curve shape of this segment.                                                           |
   | pe"        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "duration" | Duration of this segment.                                                                  |
   +------------+--------------------------------------------------------------------------------------------+
   | "end_level | The end level of this segment.                                                             |
   | "          |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "start_lev | The start level of this segment.                                                           |
   | el"        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   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_t_at_integral(t1: float, desired_area: float, max_error: float = 1e-14) -> float

      Inverse of "integrate_segment()" within this single segment:
      given a lower bound "t1" inside the segment, find the upper
      bound "t2" (also inside the segment) such that
      "integrate_segment(t1, t2) == desired_area".

      Assumes "self.start_time <= t1 <= self.end_time", "desired_area
      >= 0", that the level is non-negative across "[t1, end_time]"
      (so the integral increases monotonically with the upper bound),
      and that "desired_area" does not exceed the area remaining to
      "end_time". The constant and linear cases are solved
      analytically (exactly); the exponential case is solved with a
      bracketed Newton iteration converging to "max_error".

      Parameters:
         * **t1** -- lower bound of integration, within this segment

         * **desired_area** -- the integral we want to achieve,
           measured forward from "t1"

         * **max_error** -- convergence tolerance for the exponential
           (bracketed Newton) case; unused in the linear case

   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: 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


======================================================================
=== FILE: expenvelope/expenvelope.envelope_segment.txt
======================================================================

expenvelope.envelope_segment
****************************

Module containing the "EnvelopeSegment" class. Every
"envelope.Envelope" object, under the hood, is made up of a list of
"EnvelopeSegment"s. "EnvelopeSegment"s support arithmetic operations
like addition, subtraction, multiplication, and division. They also
support horizontal scaling and shifting.

Note also that this is defining a function whose domain is a portion
of the real number line, but whose range can actually be nearly
anything, including, e.g., numpy arrays. All of the functionality,
even integration, works for mappings onto other kinds of ranges.

-[ Classes ]-

+------------+--------------------------------------------------------------------------------------------+
| "EnvelopeS | A segment of an envelope, with the ability to perform interpolation and integration.       |
| egment"(st |                                                                                            |
| art_time,  |                                                                                            |
| end_time,  |                                                                                            |
| ...)       |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* expenvelope.envelope_segment.EnvelopeSegment

  * "EnvelopeSegment"

    * "EnvelopeSegment.from_endpoints_and_halfway_level()"

    * "EnvelopeSegment.start_level"

    * "EnvelopeSegment.end_level"

    * "EnvelopeSegment.curve_shape"

    * "EnvelopeSegment.duration"

    * "EnvelopeSegment.max_level()"

    * "EnvelopeSegment.min_level()"

    * "EnvelopeSegment.average_level()"

    * "EnvelopeSegment.max_absolute_slope()"

    * "EnvelopeSegment.start_slope()"

    * "EnvelopeSegment.end_slope()"

    * "EnvelopeSegment.value_at()"

    * "EnvelopeSegment.integrate_segment()"

    * "EnvelopeSegment.get_t_at_integral()"

    * "EnvelopeSegment.get_integral_range()"

    * "EnvelopeSegment.set_curvature_to_desired_integral()"

    * "EnvelopeSegment.split_at()"

    * "EnvelopeSegment.clone()"

    * "EnvelopeSegment.shift_vertical()"

    * "EnvelopeSegment.scale_vertical()"

    * "EnvelopeSegment.shift_horizontal()"

    * "EnvelopeSegment.scale_horizontal()"

    * "EnvelopeSegment.is_shifted_version_of()"

    * "EnvelopeSegment.show_plot()"


======================================================================
=== FILE: expenvelope/expenvelope.json_serializer.SavesToJSON.txt
======================================================================

expenvelope.json_serializer.SavesToJSON
***************************************

class expenvelope.json_serializer.SavesToJSON

   Bases: "object"

   Abstract class that, when implemented, gives the ability to save to
   and from JSON objects. Children must implement the "_to_dict" and
   "_from_dict" functions which convert back and forth between an
   instance and a dictionary representing that instance's data. The
   data in such a dictionary may contain only standard json-
   serializable types (lists, dicts, ints, floats, strings, etc.) and
   other objects that implement the SavesToJSON interface,

   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "duplicate | Returns a copy of this object by serializing to and from JSON.                             |
   | "()        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "json_dump | Dump this object as a JSON string.                                                         |
   | s"()       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "json_load | Load this object from a JSON string.                                                       |
   | s"(s)      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "load_from | Load this object from a JSON file with the given path.                                     |
   | _json"(fil |                                                                                            |
   | e_path)    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "save_to_j | Save this object to a JSON file using the given path.                                      |
   | son"(file_ |                                                                                            |
   | path)      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   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.

   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

   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

   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

   duplicate() -> T

      Returns a copy of this object by serializing to and from JSON.


======================================================================
=== FILE: expenvelope/expenvelope.json_serializer.SavesToJSONMeta.txt
======================================================================

expenvelope.json_serializer.SavesToJSONMeta
*******************************************

class expenvelope.json_serializer.SavesToJSONMeta(clsname, bases, attrs)

   Bases: "ABCMeta"

   Used to keep track of all known subclasses of SavesToJSON, so that
   objects can be reconstructed.

   -[ Inherited Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "mro"()    | Return a type's method resolution order.                                                   |
   +------------+--------------------------------------------------------------------------------------------+
   | "register" | Register a virtual subclass of an ABC.                                                     |
   | (subclass) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   -[ Attributes ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "names_to_ |                                                                                            |
   | types"     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "types_to_ |                                                                                            |
   | names"     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   names_to_types = {'ChangePedal': <class 'scamp.spanners.ChangePedal'>, 'EngravingSettings': <class 'scamp.settings.EngravingSettings'>, 'Ensemble': <class 'scamp.instruments.Ensemble'>, 'Envelope': <class 'expenvelope.envelope.Envelope'>, 'GlissandiSettings': <class 'scamp.settings.GlissandiSettings'>, 'MIDIStreamPlaybackImplementation': <class 'scamp.playback_implementations.MIDIStreamPlaybackImplementation'>, 'NotePlaybackAdjustment': <class 'scamp.playback_adjustments.NotePlaybackAdjustment'>, 'NoteProperties': <class 'scamp.note_properties.NoteProperties'>, 'OSCPlaybackImplementation': <class 'scamp.playback_implementations.OSCPlaybackImplementation'>, 'ParamPlaybackAdjustment': <class 'scamp.playback_adjustments.ParamPlaybackAdjustment'>, 'Performance': <class 'scamp.performance.Performance'>, 'PerformanceNote': <class 'scamp.performance.PerformanceNote'>, 'PerformancePart': <class 'scamp.performance.PerformancePart'>, 'PitchInterval': <class 'scamp_extensions.pitch.scale.PitchInterval'>, 'PlaybackImplementation': <class 'scamp.playback_implementations.PlaybackImplementation'>, 'PlaybackSettings': <class 'scamp.settings.PlaybackSettings'>, 'QuantizationRecord': <class 'scamp.quantization.QuantizationRecord'>, 'QuantizationSettings': <class 'scamp.settings.QuantizationSettings'>, 'SavesToJSON': <class 'expenvelope.json_serializer.SavesToJSON'>, 'Scale': <class 'scamp_extensions.pitch.scale.Scale'>, 'ScaleType': <class 'scamp_extensions.pitch.scale.ScaleType'>, 'ScampInstrument': <class 'scamp.instruments.ScampInstrument'>, 'Session': <class 'scamp.session.Session'>, 'SoundfontHost': <class 'scamp._soundfont_host.SoundfontHost'>, 'SoundfontPlaybackImplementation': <class 'scamp.playback_implementations.SoundfontPlaybackImplementation'>, 'Spanner': <class 'scamp.spanners.Spanner'>, 'SpellingPolicy': <class 'scamp.spelling.SpellingPolicy'>, 'StaffText': <class 'scamp.text.StaffText'>, 'StartBracket': <class 'scamp.spanners.StartBracket'>, 'StartDashes': <class 'scamp.spanners.StartDashes'>, 'StartHairpin': <class 'scamp.spanners.StartHairpin'>, 'StartPedal': <class 'scamp.spanners.StartPedal'>, 'StartPhrasingSlur': <class 'scamp.spanners.StartPhrasingSlur'>, 'StartSlur': <class 'scamp.spanners.StartSlur'>, 'StartTrill': <class 'scamp.spanners.StartTrill'>, 'StopBracket': <class 'scamp.spanners.StopBracket'>, 'StopDashes': <class 'scamp.spanners.StopDashes'>, 'StopHairpin': <class 'scamp.spanners.StopHairpin'>, 'StopPedal': <class 'scamp.spanners.StopPedal'>, 'StopPhrasingSlur': <class 'scamp.spanners.StopPhrasingSlur'>, 'StopSlur': <class 'scamp.spanners.StopSlur'>, 'StopTrill': <class 'scamp.spanners.StopTrill'>, 'TempoEnvelope': <class 'clockblocks.tempo_envelope.TempoEnvelope'>, 'TempoHistory': <class 'clockblocks.tempo_envelope.TempoHistory'>, 'TempoSettings': <class 'scamp.settings.TempoSettings'>, 'TimeSignature': <class 'scamp.quantization.TimeSignature'>, 'TimeVaryingParameter': <class 'scamp_extensions.utilities.time_varying_parameter.TimeVaryingParameter'>, '_MIDIPlaybackImplementation': <class 'scamp.playback_implementations._MIDIPlaybackImplementation'>, '_ScampSettings': <class 'scamp.settings._ScampSettings'>, '_StartOctaveLine': <class 'scamp.spanners._StartOctaveLine'>, '_StopOctaveLine': <class 'scamp.spanners._StopOctaveLine'>}

   types_to_names = {<class 'clockblocks.tempo_envelope.TempoEnvelope'>: 'TempoEnvelope', <class 'clockblocks.tempo_envelope.TempoHistory'>: 'TempoHistory', <class 'expenvelope.envelope.Envelope'>: 'Envelope', <class 'expenvelope.json_serializer.SavesToJSON'>: 'SavesToJSON', <class 'scamp._soundfont_host.SoundfontHost'>: 'SoundfontHost', <class 'scamp.instruments.Ensemble'>: 'Ensemble', <class 'scamp.instruments.ScampInstrument'>: 'ScampInstrument', <class 'scamp.note_properties.NoteProperties'>: 'NoteProperties', <class 'scamp.performance.Performance'>: 'Performance', <class 'scamp.performance.PerformanceNote'>: 'PerformanceNote', <class 'scamp.performance.PerformancePart'>: 'PerformancePart', <class 'scamp.playback_adjustments.NotePlaybackAdjustment'>: 'NotePlaybackAdjustment', <class 'scamp.playback_adjustments.ParamPlaybackAdjustment'>: 'ParamPlaybackAdjustment', <class 'scamp.playback_implementations.MIDIStreamPlaybackImplementation'>: 'MIDIStreamPlaybackImplementation', <class 'scamp.playback_implementations.OSCPlaybackImplementation'>: 'OSCPlaybackImplementation', <class 'scamp.playback_implementations.PlaybackImplementation'>: 'PlaybackImplementation', <class 'scamp.playback_implementations.SoundfontPlaybackImplementation'>: 'SoundfontPlaybackImplementation', <class 'scamp.playback_implementations._MIDIPlaybackImplementation'>: '_MIDIPlaybackImplementation', <class 'scamp.quantization.QuantizationRecord'>: 'QuantizationRecord', <class 'scamp.quantization.TimeSignature'>: 'TimeSignature', <class 'scamp.session.Session'>: 'Session', <class 'scamp.settings.EngravingSettings'>: 'EngravingSettings', <class 'scamp.settings.GlissandiSettings'>: 'GlissandiSettings', <class 'scamp.settings.PlaybackSettings'>: 'PlaybackSettings', <class 'scamp.settings.QuantizationSettings'>: 'QuantizationSettings', <class 'scamp.settings.TempoSettings'>: 'TempoSettings', <class 'scamp.settings._ScampSettings'>: '_ScampSettings', <class 'scamp.spanners.ChangePedal'>: 'ChangePedal', <class 'scamp.spanners.Spanner'>: 'Spanner', <class 'scamp.spanners.StartBracket'>: 'StartBracket', <class 'scamp.spanners.StartDashes'>: 'StartDashes', <class 'scamp.spanners.StartHairpin'>: 'StartHairpin', <class 'scamp.spanners.StartPedal'>: 'StartPedal', <class 'scamp.spanners.StartPhrasingSlur'>: 'StartPhrasingSlur', <class 'scamp.spanners.StartSlur'>: 'StartSlur', <class 'scamp.spanners.StartTrill'>: 'StartTrill', <class 'scamp.spanners.StopBracket'>: 'StopBracket', <class 'scamp.spanners.StopDashes'>: 'StopDashes', <class 'scamp.spanners.StopHairpin'>: 'StopHairpin', <class 'scamp.spanners.StopPedal'>: 'StopPedal', <class 'scamp.spanners.StopPhrasingSlur'>: 'StopPhrasingSlur', <class 'scamp.spanners.StopSlur'>: 'StopSlur', <class 'scamp.spanners.StopTrill'>: 'StopTrill', <class 'scamp.spanners._StartOctaveLine'>: '_StartOctaveLine', <class 'scamp.spanners._StopOctaveLine'>: '_StopOctaveLine', <class 'scamp.spelling.SpellingPolicy'>: 'SpellingPolicy', <class 'scamp.text.StaffText'>: 'StaffText', <class 'scamp_extensions.pitch.scale.PitchInterval'>: 'PitchInterval', <class 'scamp_extensions.pitch.scale.Scale'>: 'Scale', <class 'scamp_extensions.pitch.scale.ScaleType'>: 'ScaleType', <class 'scamp_extensions.utilities.time_varying_parameter.TimeVaryingParameter'>: 'TimeVaryingParameter'}

   mro()

      Return a type's method resolution order.

   register(subclass)

      Register a virtual subclass of an ABC.

      Returns the subclass, to allow usage as a class decorator.


======================================================================
=== FILE: expenvelope/expenvelope.json_serializer.txt
======================================================================

expenvelope.json_serializer
***************************

Module containing the "SavesToJSON" abstract class for serializing
complex objects back and forth to JSON files.

-[ Classes ]-

+------------+--------------------------------------------------------------------------------------------+
| "SavesToJS | Abstract class that, when implemented, gives the ability to save to and from JSON objects. |
| ON"()      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "SavesToJS | Used to keep track of all known subclasses of SavesToJSON, so that objects can be          |
| ONMeta"(cl | reconstructed.                                                                             |
| sname,     |                                                                                            |
| bases,     |                                                                                            |
| attrs)     |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* expenvelope.json_serializer.SavesToJSON

  * "SavesToJSON"

    * "SavesToJSON.json_dumps()"

    * "SavesToJSON.save_to_json()"

    * "SavesToJSON.json_loads()"

    * "SavesToJSON.load_from_json()"

    * "SavesToJSON.duplicate()"

* expenvelope.json_serializer.SavesToJSONMeta

  * "SavesToJSONMeta"

    * "SavesToJSONMeta.names_to_types"

    * "SavesToJSONMeta.types_to_names"

    * "SavesToJSONMeta.mro()"

    * "SavesToJSONMeta.register()"


======================================================================
=== FILE: expenvelope.txt
======================================================================

expenvelope package
*******************

Expenvelope is a library for expressing piecewise exponential curves,
with musical applications in mind. (This is modeled in some ways on
the *Env* class in SuperCollider.) Contents of this package include
the *envelope* module, which defines the central "Envelope" class, and
the *envelope_segment* module, which defines the "EnvelopeSegment"
class, out of which an "Envelope" is built.

-[ Modules: ]-

+------------+--------------------------------------------------------------------------------------------+
| "envelope" | Module containing the central "Envelope" class, which represents a piece-wise exponential  |
|            | function.                                                                                  |
+------------+--------------------------------------------------------------------------------------------+
| "envelope_ | Module containing the "EnvelopeSegment" class.                                             |
| segment"   |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "json_seri | Module containing the "SavesToJSON" abstract class for serializing complex objects back    |
| alizer"    | and forth to JSON files.                                                                   |
+------------+--------------------------------------------------------------------------------------------+

* expenvelope.envelope

  * expenvelope.envelope.Envelope

    * "Envelope"

      * "Envelope.from_segments()"

      * "Envelope.from_levels_and_durations()"

      * "Envelope.from_levels()"

      * "Envelope.from_list()"

      * "Envelope.from_points()"

      * "Envelope.release()"

      * "Envelope.ar()"

      * "Envelope.asr()"

      * "Envelope.adsr()"

      * "Envelope.from_function()"

      * "Envelope.length()"

      * "Envelope.start_time()"

      * "Envelope.end_time()"

      * "Envelope.start_level()"

      * "Envelope.end_level()"

      * "Envelope.max_level()"

      * "Envelope.min_level()"

      * "Envelope.average_level()"

      * "Envelope.max_absolute_slope()"

      * "Envelope.levels"

      * "Envelope.durations"

      * "Envelope.get_durations()"

      * "Envelope.times"

      * "Envelope.curve_shapes"

      * "Envelope.offset"

      * "Envelope.insert()"

      * "Envelope.insert_interpolated()"

      * "Envelope.append_segment()"

      * "Envelope.prepend_segment()"

      * "Envelope.pop_segment()"

      * "Envelope.pop_segment_from_start()"

      * "Envelope.remove_segments_after()"

      * "Envelope.remove_segments_before()"

      * "Envelope.append_envelope()"

      * "Envelope.prepend_envelope()"

      * "Envelope.value_at()"

      * "Envelope.integrate_interval()"

      * "Envelope.get_upper_integration_bound()"

      * "Envelope.normalize_to_duration()"

      * "Envelope.local_extrema()"

      * "Envelope.split_at()"

      * "Envelope.simplified()"

      * "Envelope.is_shifted_version_of()"

      * "Envelope.shift_vertical()"

      * "Envelope.scale_vertical()"

      * "Envelope.shift_horizontal()"

      * "Envelope.scale_horizontal()"

      * "Envelope.show_plot()"

      * "Envelope.duplicate()"

      * "Envelope.json_dumps()"

      * "Envelope.json_loads()"

      * "Envelope.load_from_json()"

      * "Envelope.save_to_json()"

* expenvelope.envelope_segment

  * expenvelope.envelope_segment.EnvelopeSegment

    * "EnvelopeSegment"

      * "EnvelopeSegment.from_endpoints_and_halfway_level()"

      * "EnvelopeSegment.start_level"

      * "EnvelopeSegment.end_level"

      * "EnvelopeSegment.curve_shape"

      * "EnvelopeSegment.duration"

      * "EnvelopeSegment.max_level()"

      * "EnvelopeSegment.min_level()"

      * "EnvelopeSegment.average_level()"

      * "EnvelopeSegment.max_absolute_slope()"

      * "EnvelopeSegment.start_slope()"

      * "EnvelopeSegment.end_slope()"

      * "EnvelopeSegment.value_at()"

      * "EnvelopeSegment.integrate_segment()"

      * "EnvelopeSegment.get_t_at_integral()"

      * "EnvelopeSegment.get_integral_range()"

      * "EnvelopeSegment.set_curvature_to_desired_integral()"

      * "EnvelopeSegment.split_at()"

      * "EnvelopeSegment.clone()"

      * "EnvelopeSegment.shift_vertical()"

      * "EnvelopeSegment.scale_vertical()"

      * "EnvelopeSegment.shift_horizontal()"

      * "EnvelopeSegment.scale_horizontal()"

      * "EnvelopeSegment.is_shifted_version_of()"

      * "EnvelopeSegment.show_plot()"

* expenvelope.json_serializer

  * expenvelope.json_serializer.SavesToJSON

    * "SavesToJSON"

      * "SavesToJSON.json_dumps()"

      * "SavesToJSON.save_to_json()"

      * "SavesToJSON.json_loads()"

      * "SavesToJSON.load_from_json()"

      * "SavesToJSON.duplicate()"

  * expenvelope.json_serializer.SavesToJSONMeta

    * "SavesToJSONMeta"

      * "SavesToJSONMeta.names_to_types"

      * "SavesToJSONMeta.types_to_names"

      * "SavesToJSONMeta.mro()"

      * "SavesToJSONMeta.register()"

-[ Public-Facing API (result of *import **): ]-

+------------+--------------------------------------------------------------------------------------------+
| "snap_floa | If x is near to a nice decimal, this rounds it.                                            |
| t_to_nice_ |                                                                                            |
| decimal"(x |                                                                                            |
| [, ...])   |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "Envelope" | Class representing a piece-wise exponential function.                                      |
| ([levels,  |                                                                                            |
| durations, |                                                                                            |
| curve_shap |                                                                                            |
| es, ...])  |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "EnvelopeS | A segment of an envelope, with the ability to perform interpolation and integration.       |
| egment"(st |                                                                                            |
| art_time,  |                                                                                            |
| end_time,  |                                                                                            |
| ...)       |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+